fix(RDKEMW-16441): gateway connect fails on numeric loopback IP when no external network

.bdignore

@@ -0,0 +1,3 @@
+# BlackDuck scan exclusions
+# Vendored third-party source — attributed in NOTICE and LICENSE files
+src/vendor/

.github/workflows/ci.yml

@@ -199,3 +199,39 @@ jobs:
 
       - name: Add coverage summary to job summary
         run: cat code-coverage-results.md >> $GITHUB_STEP_SUMMARY
+
+  network_isolation_tests:
+    permissions:
+      contents: read
+      packages: read
+    needs: [build_docker, build_project]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Log in to the Container registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Download build directory
+        uses: actions/download-artifact@v4
+        with:
+          name: build-dir
+          path: ${{ github.workspace }}/build
+
+      - name: Run network-isolation tests (--network none)
+        run: |
+          chmod +x ${{ github.workspace }}/build/test/utApp
+          docker run --rm --network none \
+            --user "$(id -u):$(id -g)" \
+            -v ${{ github.workspace }}:/workspace \
+            -w /workspace \
+            ${{ needs.build_docker.outputs.image_tag }} \
+            bash -c " \
+              build/test/utApp \
+                --gtest_filter='TransportNumericIPUTest.*:TransportIPv6UTest.ConnectViaIPv6LoopbackIP:TransportNumericIPResolverTest.ConnectFailureViaNumericIP' \
+            "

.version

@@ -0,0 +1 @@
+1.1.8

LICENSE

@@ -200,3 +200,31 @@
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
+
+===========================================================================
+
+BSD-3 License
+
+Copyright <YEAR> <COPYRIGHT HOLDER>
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in
+      the documentation and/or other materials provided with the distribution.
+    * Neither the name of the copyright holder nor the names of its
+      contributors may be used to endorse or promote products derived from
+      this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

build.sh

@@ -18,6 +18,39 @@
 
 set -e
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+IMAGE="firebolt-cpp-transport-ci:local"
+
+# Pre-scan for --docker before arg parsing so forwarded args are preserved
+use_docker=false
+_forward_args=()
+for _arg in "$@"; do
+  [[ "$_arg" == "--docker" ]] && { use_docker=true; continue; }
+  _forward_args+=("$_arg")
+done
+
+if $use_docker; then
+  for _bdir in build build-dev; do
+    _cache="$SCRIPT_DIR/$_bdir/CMakeCache.txt"
+    if [[ -f "$_cache" ]]; then
+      _cached=$(grep '^CMAKE_HOME_DIRECTORY' "$_cache" 2>/dev/null | cut -d= -f2 || true)
+      # In Docker, the workspace is mounted at /workspace.  Only wipe if the
+      # cache was configured for a different environment (e.g. a native host build).
+      if [[ -n "$_cached" && "$_cached" != "/workspace" ]]; then
+        echo "Wiping stale $_bdir (configured at $_cached, expected /workspace)..."
+        rm -rf "$SCRIPT_DIR/$_bdir"
+      fi
+    fi
+  done
+  if ! docker image inspect "$IMAGE" &>/dev/null; then
+    echo "Building CI Docker image (one-time)..."
+    docker build -t "$IMAGE" -f "$SCRIPT_DIR/.github/Dockerfile" "$SCRIPT_DIR"
+  fi
+  exec docker run --rm --user "$(id -u):$(id -g)" \
+    -v "$SCRIPT_DIR:/workspace" -w /workspace \
+    "$IMAGE" ./build.sh "${_forward_args[@]}"
+fi
+
 bdir="build"
 do_install=false
 params=
@@ -50,12 +83,21 @@ while [[ ! -z $1 ]]; do
   esac; shift
 done
 
-[[ ! -z $SYSROOT_PATH ]] || { echo "SYSROOT_PATH not set" >/dev/stderr; exit 1; }
-[[ -e $SYSROOT_PATH ]] || { echo "SYSROOT_PATH not exist ($SYSROOT_PATH)" >/dev/stderr; exit 1; }
+SYSROOT_PATH="${SYSROOT_PATH:-/}"
+[[ -e $SYSROOT_PATH ]] || { echo "SYSROOT_PATH does not exist ($SYSROOT_PATH)" >/dev/stderr; exit 1; }
 
 $cleanFirst && rm -rf $bdir
 
-if [[ ! -e "$bdir" || -n "$@" ]]; then
+_cache="$SCRIPT_DIR/$bdir/CMakeCache.txt"
+if [[ -f "$_cache" ]]; then
+  _cached=$(grep '^CMAKE_HOME_DIRECTORY' "$_cache" 2>/dev/null | cut -d= -f2 || true)
+  if [[ -n "$_cached" && "$_cached" != "$SCRIPT_DIR" ]]; then
+    echo "Wiping stale $bdir (configured at $_cached, now at $SCRIPT_DIR)..."
+    rm -rf "$SCRIPT_DIR/$bdir"
+  fi
+fi
+
+if [[ ! -f "$bdir/CMakeCache.txt" || $# -gt 0 ]]; then
   params+=" -DCMAKE_EXPORT_COMPILE_COMMANDS=ON"
   command -v ccache >/dev/null 2>&1 && params+=" -DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache"
   cmake -B $bdir \

cmake/version.cmake

@@ -21,26 +21,26 @@ endif ()
 if (NOT PROJECT_VERSION)
     set(VERSION_STRING "0.1.0-unknown")
 
-    find_package(Git QUIET)
-
-    if (GIT_FOUND)
-        execute_process(
-            COMMAND ${GIT_EXECUTABLE} describe --tags --abbrev=0 --match "v[0-9]*.[0-9]*.[0-9]*"
-            WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
-            OUTPUT_VARIABLE GIT_VERSION
-            OUTPUT_STRIP_TRAILING_WHITESPACE
-            ERROR_QUIET
-        )
-    endif ()
-
-    if (GIT_VERSION)
-        string(REGEX REPLACE "^v" "" VERSION_STRING "${GIT_VERSION}")
-    endif ()
-
-    if(VERSION_STRING STREQUAL "0.1.0-unknown" AND EXISTS "${CMAKE_SOURCE_DIR}/.version")
+    if (EXISTS "${CMAKE_SOURCE_DIR}/.version")
         file(READ "${CMAKE_SOURCE_DIR}/.version" VERSION_STRING)
         string(STRIP "${VERSION_STRING}" VERSION_STRING)
-    endif()
+    else ()
+        find_package(Git QUIET)
+
+        if (GIT_FOUND)
+            execute_process(
+                COMMAND ${GIT_EXECUTABLE} describe --tags --abbrev=0 --match "v[0-9]*.[0-9]*.[0-9]*"
+                WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
+                OUTPUT_VARIABLE GIT_VERSION
+                OUTPUT_STRIP_TRAILING_WHITESPACE
+                ERROR_QUIET
+            )
+        endif ()
+
+        if (GIT_VERSION)
+            string(REGEX REPLACE "^v" "" VERSION_STRING "${GIT_VERSION}")
+        endif ()
+    endif ()
 
     set(PROJECT_VERSION "${VERSION_STRING}" CACHE STRING "Project version string")
     set(PROJECT_VERSION "${VERSION_STRING}")

include/firebolt/config.h.in

@@ -73,6 +73,45 @@ struct Config
 
     /** Watchdog polling cycle in milliseconds. Default: 500. */
     unsigned watchdogCycle_ms = 500;
+
+    /**
+     * @brief Retry policy for the initial gateway connection.
+     *
+     * On embedded devices the Firebolt client may start before the gateway
+     * daemon is ready (poor systemd ordering) or before the loopback interface
+     * has an IPv4 address assigned.  Setting reconnect_max_attempts > 0 causes
+     * connect() to retry up to that many times, waiting reconnect_delay_ms
+     * between each attempt, before returning an error to the caller.
+     *
+     * Each attempt is bounded by connect_attempt_timeout_ms: if the underlying
+     * transport (DNS + TCP + WebSocket handshake) does not complete within that
+     * window, the attempt is aborted and counted as a failure.  connect()
+     * therefore blocks for at most:
+     *   (reconnect_max_attempts + 1) * connect_attempt_timeout_ms
+     *   + reconnect_max_attempts * reconnect_delay_ms
+     *
+     * Capped internally at 100 retries regardless of this value.
+     *
+     * Default: 0 (single attempt, no retry; connect() returns the last
+     * transport error, e.g. Error::NotConnected, Error::Timedout, or
+     * Error::General, or Error::NotConnected on per-attempt timeout).
+     */
+    unsigned reconnect_max_attempts = 0;
+
+    /** Milliseconds to wait between reconnect attempts. Default: 1000. */
+    unsigned reconnect_delay_ms = 1000;
+
+    /**
+     * @brief Per-attempt timeout for the initial connection handshake (ms).
+     *
+     * If DNS resolution + TCP connect + WebSocket handshake do not complete
+     * within this window, the in-flight attempt is aborted and connect()
+     * either retries (if reconnect_max_attempts > 0) or returns
+     * Error::NotConnected to the caller.
+     *
+     * Default: 10000 (10 seconds).
+     */
+    unsigned connect_attempt_timeout_ms = 10000;
 };
 
 } // namespace Firebolt

include/firebolt/gateway.h

@@ -36,6 +36,9 @@ class IGateway
 public:
     virtual ~IGateway();
 
+    // NOTE: onConnectionChange is invoked once with the final result on the
+    // connect() calling thread.  All subsequent callbacks (disconnect, watchdog
+    // reconnect) fire on the websocketpp IO thread.  Callers must be thread-safe.
     virtual Firebolt::Error connect(const Firebolt::Config& config, ConnectionChangeCallback onConnectionChange) = 0;
     virtual Firebolt::Error disconnect() = 0;
 

src/CMakeLists.txt

@@ -82,6 +82,9 @@ target_link_libraries(${TARGET}
 
 target_include_directories(${TARGET}
     PRIVATE
+        # vendor/ must come before the system websocketpp headers so that
+        # our patched endpoint.hpp (numeric-IP resolver fix) takes priority.
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/vendor>
         $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>
         $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}>
     PUBLIC