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 exact core output)

The client core exposes no callbacks. Each observer transaction instead commits an exact revisioned change batch, and commands which create network work emit an explicit sync intent. After every command — and after draining inbound realtime traffic — the FFI forwards those outputs verbatim as change and sync-intent events. poll_event drains them. Native hosts do not infer changes by diffing counters or method names.

Modules

transport

Compatibility export for the shared Rust native transport.

Structs

Handle

The opaque handle behind the void*. One SyncClient instance, its owned transport, and the exact core-output queue, guarded for cross-thread polling.

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.