feat: adopt nim-ffi v0.1.5 (macro-based snake_case FFI) (#81)

Author: Ivansete-status

CLAUDE.md

@@ -95,21 +95,23 @@ flake.nix / Makefile        # Reproducible cross-platform build system
 
 ## FFI API (`library/libsds.nim`)
 
-The C API wraps `ReliabilityManager` behind an opaque `SdsContext` handle:
+The C API (snake_case, generated by the nim-ffi `{.ffiCtor.}`/`{.ffi.}`/`{.ffiDtor.}`
+macros) wraps `ReliabilityManager` behind an opaque context handle. Requests and
+responses are marshalled as JSON; see `library/libsds.h`.
 
 | Export | Maps to |
 |---|---|
-| `SdsNewReliabilityManager` | Create context |
-| `SdsWrapOutgoingMessage` | `wrapOutgoingMessage` |
-| `SdsUnwrapReceivedMessage` | `unwrapReceivedMessage` |
-| `SdsMarkDependenciesMet` | Notify buffered-message dependencies satisfied |
-| `SdsSetEventCallback` | Register event handler (JSON payloads) |
-| `SdsSetRetrievalHintProvider` | Register hint-provider callback |
-| `SdsStartPeriodicTasks` | Start periodic sync loop |
-| `SdsCleanupReliabilityManager` | Free context |
-| `SdsResetReliabilityManager` | Reset state without freeing |
-
-Each `SdsContext` runs a dedicated Chronos async loop on a worker thread; application threads communicate with it via SPSC channels.
+| `sds_create` | Create context (`{.ffiCtor.}`; `configJson` carries `participantId`) |
+| `sds_set_event_callback` | Register event handler (JSON payloads) |
+| `sds_set_retrieval_hint_provider` | Register hint-provider callback (hand-written) |
+| `sds_wrap_outgoing_message` | `wrapOutgoingMessage` |
+| `sds_unwrap_received_message` | `unwrapReceivedMessage` |
+| `sds_mark_dependencies_met` | Notify buffered-message dependencies satisfied |
+| `sds_start_periodic_tasks` | Start periodic sync loop |
+| `sds_reset` | Reset state without freeing |
+| `sds_destroy` | Recycle/free context (`{.ffiDtor.}`) |
+
+Each context runs a dedicated Chronos async loop on a worker thread; application threads communicate with it via SPSC channels.
 
 ---
 

library/libsds.h

@@ -1,8 +1,10 @@
 
-// Generated manually and inspired by the one generated by the Nim Compiler.
-// In order to see the header file generated by Nim just run `make libsds`
-// from the root repo folder and the header should be created in
-// nimcache/release/libsds/libsds.h
+// C API for libsds, built on the nim-ffi framework.
+//
+// Parameters and results are marshalled as JSON: each request/response struct
+// in library/libsds.nim is a JSON object, passed in via the `*Json` cstring
+// argument and returned to the callback as a JSON string. Binary fields
+// (message bytes) are JSON arrays of byte values.
 #ifndef __libsds__
 #define __libsds__
 
@@ -18,51 +20,52 @@
 extern "C" {
 #endif
 
+// Result/event callback. `msg` is the (JSON) payload of length `len`.
+// callerRet is one of the RET_* codes above.
 typedef void (*SdsCallBack) (int callerRet, const char* msg, size_t len, void* userData);
 
+// Synchronous provider invoked by SDS-R to fetch a retrieval hint for a
+// message id. The implementation allocates `*hint` (and sets `*hintLen`); the
+// library takes ownership and frees it with deallocShared.
 typedef void (*SdsRetrievalHintProvider) (const char* messageId, char** hint, size_t* hintLen, void* userData);
 
 
 // --- Core API Functions ---
 
 
-void* SdsNewReliabilityManager(SdsCallBack callback, void* userData);
+// Create a context + ReliabilityManager. configJson: {"participantId":"..."}
+// (empty participantId disables SDS-R). Returns the context handle, or NULL on
+// failure. The callback also fires on async completion.
+void* sds_create(const char* configJson, SdsCallBack callback, void* userData);
 
-void SdsSetEventCallback(void* ctx, SdsCallBack callback, void* userData);
+// Register the event callback (message_ready, message_sent,
+// missing_dependencies, periodic_sync, repair_ready). Payloads are JSON.
+void sds_set_event_callback(void* ctx, SdsCallBack callback, void* userData);
 
-void SdsSetRetrievalHintProvider(void* ctx, SdsRetrievalHintProvider callback, void* userData);
+// Register the retrieval-hint provider used by SDS-R.
+int sds_set_retrieval_hint_provider(void* ctx, SdsRetrievalHintProvider callback, void* userData);
 
-int SdsCleanupReliabilityManager(void* ctx, SdsCallBack callback, void* userData);
+// reqJson: {"message":[..bytes..],"messageId":"..","channelId":".."}
+// Result JSON: {"message":[..bytes..]}
+int sds_wrap_outgoing_message(void* ctx, SdsCallBack callback, void* userData, const char* reqJson);
 
-int SdsResetReliabilityManager(void* ctx, SdsCallBack callback, void* userData);
+// reqJson: {"message":[..bytes..]}
+// Result JSON: {"message":[..],"channelId":"..","missingDeps":[{"messageId":"..","retrievalHint":"<base64>"}]}
+int sds_unwrap_received_message(void* ctx, SdsCallBack callback, void* userData, const char* reqJson);
 
-int SdsWrapOutgoingMessage(void* ctx,
-                    void* message,
-                    size_t messageLen,
-                    const char* messageId,
-                    const char* channelId,
-                    SdsCallBack callback,
-                    void* userData);
+// reqJson: {"messageIds":["..",".."],"channelId":".."}
+int sds_mark_dependencies_met(void* ctx, SdsCallBack callback, void* userData, const char* reqJson);
 
-int SdsUnwrapReceivedMessage(void* ctx, 
-                    void* message, 
-                    size_t messageLen, 
-                    SdsCallBack callback, 
-                    void* userData);
+int sds_reset(void* ctx, SdsCallBack callback, void* userData);
 
-int SdsMarkDependenciesMet(void* ctx, 
-                    char** messageIDs, 
-                    size_t count, 
-                    const char* channelId,
-                    SdsCallBack callback,
-                    void* userData);
-
-int SdsStartPeriodicTasks(void* ctx, SdsCallBack callback, void* userData);
+int sds_start_periodic_tasks(void* ctx, SdsCallBack callback, void* userData);
 
+// Tear down the context created by sds_create.
+int sds_destroy(void* ctx, SdsCallBack callback, void* userData);
 
 
 #ifdef __cplusplus
 }
 #endif
 
-#endif /* __libsds__ */
+#endif /* __libsds__ */