Merge branch 'master' into fix/bucket-refresh-wrong-index

Author: gmelodie

.github/copilot-instructions.md

@@ -41,7 +41,7 @@ nim-libp2p/
 │   ├── integration/            # Integration tests (WebSocket, AutoTLS, peer ID auth)
 │   └── interop/                # Cross-implementation interoperability tests
 ├── examples/                   # Tutorial and example applications
-├── cbind/                      # C/FFI bindings layer
+├── cbind/                      # C/CDDL FFI bindings (generated via nim-ffi)
 ├── docs/                       # Documentation
 │   ├── README.md               # Documentation index
 │   ├── development.md          # Setup and testing guide
@@ -206,7 +206,8 @@ These flags are used in CI and tests:
 
 ### Memory Management
 - Memory model: `--mm:refc` (reference counting)
-- For C bindings (`cbind/`): use `createShared`/`freeShared` for cross-thread objects
+- For C bindings (`cbind/`): the FFI runtime (threads, request channel, shared
+  memory, CBOR codec) is provided by `nim-ffi`; annotate procs/types instead
 
 ### Style
 
@@ -454,28 +455,38 @@ These flags are used in CI and tests:
 
 ---
 
-## C Bindings (`cbind/`)
+## C/CDDL Bindings (`cbind/`)
 
-The `cbind/` directory contains the C/FFI layer for using nim-libp2p from C/C++:
+The `cbind/` directory exposes nim-libp2p to C via the [`nim-ffi`](https://github.com/logos-messaging/nim-ffi)
+framework. nim-ffi provides the worker thread, request channel, shared memory,
+CBOR codec and event queue, and *generates* the C/CDDL bindings from the
+annotations in `libp2p.nim`:
 
-- `libp2p.nim` — FFI function implementations (exported with `{.exportc.}`)
-- `libp2p.h` — Generated C header
-- `ffi_types.nim` — C-compatible type definitions
-- `types.nim` — Additional C-compatible type implementations
-- `alloc.nim` — Cross-thread memory allocation helpers
-- `libp2p_thread/` — Thread management for async operations from C
-- `examples/cbindings.c`, `examples/echo.c` — C usage examples
+- `libp2p.nim` — the top-level FFI module: `declareLibrary` + `{.ffi.}` /
+  `{.ffiCtor.}` / `{.ffiDtor.}` / `{.ffiEvent.}` annotations and the ported
+  libp2p logic; `genBindings()` emits the bindings.
+- `libp2p/config.nim` — config types and parsing, `include`d into `libp2p.nim`.
+- `c_bindings/` — generated C header (`libp2p.h`), consumed by
+  `logos-co/logos-libp2p-module`.
+- `cddl_bindings/` — generated CDDL schema for the CBOR wire format.
 
 ```sh
 cd cbind
-nimble libDynamic    # Build .so/.dylib/.dll
-nimble libStatic     # Build .a
-nimble examples      # Build and run C examples
+nimble setup
+nimble buildffi         # Build ../build/liblibp2p.{so,dylib,dll}
+nimble genbindings_c    # Generate c_bindings/libp2p.h
+nimble genbindings_cddl # Generate the CDDL schema
 ```
 
 **cbind conventions**:
-- Validate all `cstring` pointer parameters for `nil` before use; call the callback with `RET_ERR` if nil
-- Use `valueOr` (not `tryGet()`) when converting cstring multiaddresses to `MultiAddress` objects
+- Requests/responses are CBOR; declare `{.ffi.}` object types for them — never
+  raw `ptr`/`pointer` across the boundary.
+- Stream handles are plain `uint64` ids tracked in `LibP2P` state (nim-ffi has
+  no handle type for incoming streams).
+- Convert config-parsing failures to `return err(...)`; never `raiseAssert` on
+  host-supplied input (the constructor returns a `Result`).
+- Protocol/pubsub handlers are `{.ffiEvent.}` — host code subscribes via the
+  generated `libp2p_add_event_listener`.
 
 ---
 
@@ -489,9 +500,9 @@ nimble examples      # Build and run C examples
 | `daily_ci_report.yml` | Daily CI failure reporting: opens/updates GitHub issues for failed daily CI runs |
 | `daily_nimbus.yml` | Nimbus-specific test matrix |
 | `daily_runnable_examples.yml` | Daily runnable examples checks |
-| `cbindings.yml` | C bindings compilation and tests |
+| `cbindings.yml` | FFI library build + C/CDDL binding generation |
 | `coverage.yml` | Code coverage (uploads to codecov) |
-| `linters.yml` | nph formatting checks |
+| `linters.yml` | nph (Nim) + clang-format (cbind C/H) formatting checks |
 | `pr_lint.yml` | PR title/description linting |
 | `auto_assign_pr.yml` | Automatically assigns reviewers to PRs |
 | `update_copilot_instructions.yml` | Weekly automated update of copilot-instructions.md |

.github/workflows/cbindings.yml

@@ -1,4 +1,4 @@
-name: C bindings examples
+name: C bindings
 
 on:
   push:
@@ -54,7 +54,7 @@ jobs:
         run: |
           nimble install_pinned
 
-      - name: Build and run c bindings examples
+      - name: Build FFI library and generate C/CDDL bindings
         run: |
           nim --version
           nimble --version
@@ -64,18 +64,18 @@ jobs:
           cd cbind
           nimble install_pinned
           nimble setup
+          nimble buildffi
+          nimble genbindings_c
+          nimble genbindings_cddl
+
+      - name: Build and run C bindings examples
+        run: |
+          cd cbind
           nimble examples
 
-  # Temporary parallel job: builds the new nim-ffi library (cbind/libp2p_ffi.nim)
-  # and generates its C/CDDL bindings. Folded into the main flow at the flip PR,
-  # when libp2p_ffi.nim replaces the legacy libp2p.nim.
-  #
-  # Disabled until the final PR of the nim-ffi migration series: libp2p_ffi.nim is
-  # built up incrementally across PRs 2..9 and only compiles end-to-end at the
-  # flip. Re-enable (drop `if: false`) once the library is complete and expected
-  # to pass.
+  # macOS coverage for the FFI library build + C/CDDL binding generation; the
+  # main c-bindings job above covers linux.
   c-bindings-ffi:
-    if: false
     timeout-minutes: 30
     strategy:
       fail-fast: false

.github/workflows/daily_ci_report.yml

@@ -42,6 +42,7 @@ jobs:
               ("Daily test all (latests dependnecies)", "daily_test_all_latest_deps.yml"),
               ("Daily test all (without feature flags)", "daily_test_all_no_flags.yml"),
               ("Daily runnable examples", "daily_runnable_examples.yml"),
+              ("Daily interop", "daily_interop.yml"),
           ]
 
           LABEL_NAME = "daily-ci-failure"

.github/workflows/daily_interop.yml

@@ -0,0 +1,38 @@
+name: Daily interop
+
+on:
+  schedule:
+    - cron: "30 7 * * *"
+  workflow_dispatch:
+  pull_request:
+    types: [labeled, synchronize]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  build-unified-testing-interop-images:
+    name: Build unified-testing interop image (${{ matrix.name }})
+    if: github.event_name != 'pull_request' || contains(github.event.pull_request.labels.*.name, 'run-daily-ci')
+    runs-on: ubuntu-22.04
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: hole-punching-v2
+            dockerfile: interop/hole-punching-v2/Dockerfile
+          - name: kad-dht-v2
+            dockerfile: interop/kad-dht-v2/Dockerfile
+          - name: transport-v2
+            dockerfile: interop/transport-v2/Dockerfile
+          - name: perf
+            dockerfile: interop/perf/Dockerfile
+    steps:
+      - uses: actions/checkout@v6
+      - uses: docker/setup-buildx-action@v4
+      - name: Build image
+        run: docker build -f ${{ matrix.dockerfile }} .

.github/workflows/mobile_android.yml

@@ -59,16 +59,16 @@ jobs:
           test -f "$out/include/nim_ffi_prelude.h"
           test -f "$out/include/tinycbor/cbor.h"
           test -f "$out/include/cddl_bindings/libp2p.cddl"
-          test -x "$out/bin/libp2p_ffi_android_check"
+          test -x "$out/bin/libp2p_android_check"
 
           readelf -h "$out/lib/liblibp2p.so" | tee liblibp2p.readelf
-          readelf -h "$out/bin/libp2p_ffi_android_check" | tee check.readelf
+          readelf -h "$out/bin/libp2p_android_check" | tee check.readelf
 
           grep -q "Machine:[[:space:]]*${{ matrix.machine }}" liblibp2p.readelf
           grep -q "Machine:[[:space:]]*${{ matrix.machine }}" check.readelf
 
           file "$out/lib/liblibp2p.so"
-          file "$out/bin/libp2p_ffi_android_check"
+          file "$out/bin/libp2p_android_check"
 
       - name: Enable KVM for Android emulator
         if: matrix.abi == 'x86_64'
@@ -93,7 +93,7 @@ jobs:
             adb shell "mkdir -p /data/local/tmp/nim-libp2p"
             adb push "result-x86_64/lib/liblibp2p.so" "/data/local/tmp/nim-libp2p/"
             adb push "result-x86_64/lib/libc++_shared.so" "/data/local/tmp/nim-libp2p/"
-            adb push "result-x86_64/bin/libp2p_ffi_android_check" "/data/local/tmp/nim-libp2p/"
-            adb shell "chmod 755 /data/local/tmp/nim-libp2p/libp2p_ffi_android_check"
-            adb shell "cd /data/local/tmp/nim-libp2p && LD_LIBRARY_PATH=/data/local/tmp/nim-libp2p ./libp2p_ffi_android_check; echo RC=\$?" | tee run.log
+            adb push "result-x86_64/bin/libp2p_android_check" "/data/local/tmp/nim-libp2p/"
+            adb shell "chmod 755 /data/local/tmp/nim-libp2p/libp2p_android_check"
+            adb shell "cd /data/local/tmp/nim-libp2p && LD_LIBRARY_PATH=/data/local/tmp/nim-libp2p ./libp2p_android_check; echo RC=\$?" | tee run.log
             grep -q '^RC=0' run.log

.github/workflows/mobile_ios.yml

@@ -71,10 +71,10 @@ jobs:
           test -f "$out/include/nim_ffi_prelude.h"
           test -f "$out/include/tinycbor/cbor.h"
           test -f "$out/include/cddl_bindings/libp2p.cddl"
-          test -x "$out/bin/libp2p_ffi_ios_check"
+          test -x "$out/bin/libp2p_ios_check"
 
           otool -l "$out/lib/liblibp2p.dylib" | tee liblibp2p.otool
-          otool -l "$out/bin/libp2p_ffi_ios_check" | tee check.otool
+          otool -l "$out/bin/libp2p_ios_check" | tee check.otool
           lipo -info "$out/lib/liblibp2p.dylib" | tee liblibp2p.lipo
           lipo -info "$out/lib/liblibp2p.a" | tee liblibp2p_static.lipo
 
@@ -84,7 +84,7 @@ jobs:
           grep -q "arm64" liblibp2p_static.lipo
 
           file "$out/lib/liblibp2p.dylib"
-          file "$out/bin/libp2p_ffi_ios_check"
+          file "$out/bin/libp2p_ios_check"
 
       - name: Run FFI check on iOS simulator
         if: matrix.target == 'simulator-arm64'
@@ -93,15 +93,15 @@ jobs:
           run_dir="$RUNNER_TEMP/nim-libp2p-ios-sim"
           rm -rf "$run_dir"
           mkdir -p "$run_dir/bin" "$run_dir/lib"
-          cp "$out/bin/libp2p_ffi_ios_check" "$run_dir/bin/"
+          cp "$out/bin/libp2p_ios_check" "$run_dir/bin/"
           cp "$out/lib/liblibp2p.dylib" "$run_dir/lib/"
           chmod -R u+w "$run_dir"
 
-          install_name="$(otool -L "$run_dir/bin/libp2p_ffi_ios_check" | awk '/liblibp2p\.dylib/{print $1; exit}')"
+          install_name="$(otool -L "$run_dir/bin/libp2p_ios_check" | awk '/liblibp2p\.dylib/{print $1; exit}')"
           test -n "$install_name"
-          install_name_tool -change "$install_name" "@executable_path/../lib/liblibp2p.dylib" "$run_dir/bin/libp2p_ffi_ios_check"
+          install_name_tool -change "$install_name" "@executable_path/../lib/liblibp2p.dylib" "$run_dir/bin/libp2p_ios_check"
           install_name_tool -id "@rpath/liblibp2p.dylib" "$run_dir/lib/liblibp2p.dylib"
-          codesign --force --sign - "$run_dir/lib/liblibp2p.dylib" "$run_dir/bin/libp2p_ffi_ios_check"
+          codesign --force --sign - "$run_dir/lib/liblibp2p.dylib" "$run_dir/bin/libp2p_ios_check"
 
           device_udid="$(
             xcrun simctl list devices --json | /usr/bin/python3 -c '
@@ -143,4 +143,4 @@ jobs:
 
           xcrun simctl boot "$device_udid" || true
           xcrun simctl bootstatus "$device_udid" -b
-          xcrun simctl spawn "$device_udid" "$run_dir/bin/libp2p_ffi_ios_check"
+          xcrun simctl spawn "$device_udid" "$run_dir/bin/libp2p_ios_check"