chore(cbind): swap cbind for ffi (nim-ffi part 9)

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/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,4 +84,4 @@ 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"

cbind/alloc.nim

@@ -3,7 +3,7 @@ mode = ScriptMode.Verbose
 packageName = "cbind"
 version = "0.1.0"
 author = "Status Research & Development GmbH"
-description = "C bindings for LibP2P implementation"
+description = "C bindings for nim-libp2p, generated via nim-ffi"
 license = "MIT"
 
 import os, strutils, sequtils
@@ -21,43 +21,6 @@ task install_pinned,
   let deps = readFile(".pinned").splitWhitespace().mapIt(it.split(";", 1)[1])
   exec "nimble install -y " & deps.join(" ")
 
-proc getLibExt(libType: string): string =
-  if libType == "static":
-    "a"
-  else:
-    when defined(windows):
-      "dll"
-    elif defined(macosx):
-      "dylib"
-    else:
-      "so"
-
-proc buildCBindings(libType: string, params = "") =
-  let buildDir = "../build"
-
-  if not dirExists buildDir:
-    mkDir buildDir
-
-  var extra_params = params
-  for i in 2 ..< paramCount():
-    extra_params &= " " & paramStr(i)
-
-  let ext = getLibExt(libType)
-  let app = if libType == "static": "staticlib" else: "lib"
-
-  exec "nim c --out:" & buildDir & "/libp2p." & ext & " --threads:on --app:" & app &
-    " --opt:size --noMain --mm:refc --header -d:metrics" &
-    " --nimMainPrefix:libp2p --nimcache:nimcache libp2p.nim"
-
-task libDynamic, "Generate dynamic bindings":
-  buildCBindings "dynamic", ""
-
-task libStatic, "Generate static bindings":
-  buildCBindings "static", ""
-
-# nim-ffi library, built in parallel to the legacy cbind above (see libp2p_ffi.nim).
-# Renamed over libp2p.nim at the flip PR, which drops everything above this line.
-
 proc findInstalledPkgDir(prefix: string): string =
   ## Path of an installed dep dir matching `prefix` (e.g. "ffi-"). install_pinned
   ## drops cbind's pinned deps under the project-local `nimbledeps/pkgs2`; a plain
@@ -108,16 +71,16 @@ proc buildFfiLib() =
   exec "nim c --out:" & buildDir & "/liblibp2p." & ffiLibExt() &
     " --threads:on --app:lib --opt:size --noMain --mm:refc -d:metrics" &
     " -d:ffiThreadExitTimeoutMs=5000" & ffiDepPaths() &
-    " --nimMainPrefix:liblibp2p --nimcache:nimcache libp2p_ffi.nim"
+    " --nimMainPrefix:liblibp2p --nimcache:nimcache libp2p.nim"
 
 task buildffi, "Build the FFI shared library":
   buildFfiLib()
 
 proc genBindingsFor(lang, outDir: string) =
   exec "nim c --threads:on --app:lib --noMain --mm:refc -d:metrics" &
     " --nimMainPrefix:liblibp2p -d:ffiGenBindings -d:targetLang=" & lang &
-    " -d:ffiOutputDir=" & outDir & " -d:ffiSrcPath=libp2p_ffi.nim" & ffiDepPaths() &
-    " --nimcache:nimcache_" & lang & " -o:/dev/null libp2p_ffi.nim"
+    " -d:ffiOutputDir=" & outDir & " -d:ffiSrcPath=libp2p.nim" & ffiDepPaths() &
+    " --nimcache:nimcache_" & lang & " -o:/dev/null libp2p.nim"
 
 task genbindings_c, "Generate C bindings (cbind/c_bindings)":
   genBindingsFor("c", "c_bindings")