Crate syncular 

syncular-ffi — the Syncular v2 Rust client core as a C-ABI native library

The POC client crate, packaged for shipping. Five C functions expose the whole client over a JSON command surface — the v1-proven bindings shape, and the SAME syncular-command router the conformance shim locks:

void*  syncular_client_new(const char* config_json);
char*  syncular_client_command(void* handle, const char* command_json);
char*  syncular_client_poll_event(void* handle, int64_t timeout_ms);
void   syncular_client_close(void* handle);
void   syncular_free_string(char* ptr);

command_json is {"method": "...", "params": {...}} — every method the shim speaks (create/subscribe/mutate/sync/syncUntilIdle/readRows/…). The reply is {"result": ...} or {"error": {"code", "message"}}. Bytes ride as {"$bytes": "<hex>"}, unchanged from the driver protocol, so a JSI/TurboModule bridge marshals plain JSON.

Transport ownership (native vs. inverted)

The conformance shim inverts transport to the harness (the host holds the sync/segment/realtime endpoints). A native app cannot do that — there is no host loop to call back into. So under the native-transport feature this crate OWNS a real HTTP + WS transport (see transport); the config carries a baseUrl and the core drives the network itself. Without the feature (the dependency-lean default), network commands fail loudly with transport.unavailable and only client-local commands run — which is all the C smoke test and pure-logic tests need.

Events (lean queue over a callback-free core)

The client core exposes no callbacks; it surfaces observable state (sync_needed, presence peers, conflicts, schema floor, lease errors). After each command — and after draining inbound realtime traffic — the FFI diffs that state and enqueues client-observable events (sync-needed / conflict / presence / schema-floor, the invalidation-equivalent set). poll_event drains them. This keeps the core callback-free (portable, testable) while giving native hosts a push-shaped signal.

Modules

transport

The transport the FFI core OWNS.

Structs

Handle

The opaque handle behind the void*. One SyncClient instance, its owned transport, and the derived event queue, guarded for cross-thread use (the native WS reader thread pushes into queue).

Functions

syncular_client_close

Close a client core, releasing its database, transport, and socket thread. The handle is invalid after this call.

syncular_client_command

Run one JSON command ({"method","params"}) against the client. Returns a freshly-allocated {"result"|"error"} JSON string the caller frees with syncular_free_string. Returns null only on a null handle.

syncular_client_new

Create a client core. config_json is a JSON object: {} for the dependency-lean default (client-local commands only); with the native-transport feature it carries {"baseUrl": "...", ...} for the owned HTTP+WS transport. Returns an opaque handle, or null on a malformed config.

syncular_client_poll_event

Poll the next client-observable event, waiting up to timeout_ms (negative = block until one arrives, 0 = non-blocking). Returns a freshly-allocated event JSON string, or null if none arrived in time.

syncular_free_string

Free a string returned by syncular_client_command / syncular_client_poll_event.