Struct SyncClient 

pub struct SyncClient { /* private fields */ }

Implementations

impl SyncClient

pub fn new( client_id: String, schema_json: &Value, limits: ClientLimits, ) -> Result<Self, String>

pub fn open_path( client_id: String, schema_json: &Value, limits: ClientLimits, path: &str, ) -> Result<Self, String>

Build a client backed by an on-disk SQLite database at path — the seam a native host (Tauri plugin, FFI file-DB variant) uses to persist across process restarts. create_tables runs IF NOT EXISTS, so re-opening the same file reuses the persisted rows. Keeps rusqlite out of the command router’s dependency set (the router only holds a path).

pub fn with_connection( client_id: String, schema_json: &Value, limits: ClientLimits, conn: Connection, ) -> Result<Self, String>

Build a client over a caller-supplied rusqlite connection — the seam a native host (Tauri plugin, FFI file-DB variant) uses to back the core with an on-disk database (Connection::open(path)) rather than the default :memory:. The connection MUST be fresh (no pre-existing syncular tables); create_tables runs IF NOT EXISTS, so re-opening the same file across process restarts reuses the persisted rows.

pub fn set_now_ms(&mut self, now_ms: i64)

Pin the client clock (epoch ms) — the §5.4 expiry check runs against this instead of system time (conformance virtual clock).

pub fn set_encryption(&mut self, encryption: EncryptionConfig)

§5.11: install the client-side encryption keys (keyId → key bytes). The command router parses these from the create command’s encryption config (keys as {$bytes: hex}).

pub fn upgrading(&self) -> bool

§7.4.5: true while a schema-bump reset + first re-bootstrap runs.

pub fn recreate_with_schema( &mut self, schema_json: &Value, ) -> Result<(), String>

§7.4.2 “app ships new code”: swap to a NEW generated schema while keeping this client’s local database (identity, outbox, tables). The §7.4.1 marker check then fires the wipe/re-bootstrap flow when the version changed. Mirrors the TS client’s boot-time detection — the Rust core has no persistent restart, so recreation IS the boot.

pub fn subscribe( &mut self, id: String, table: String, scopes: Vec<(String, Vec<String>)>, params: Option<String>, ) -> Result<(), String>

pub fn unsubscribe(&mut self, id: &str)

pub fn set_window( &mut self, base: &WindowBase, units: &[String], ) -> Result<(), String>

§4.8: set the live window units for a base — a value-sharded family of subscriptions, one per unit. Added units get fresh subscriptions (image-lane bootstrap on the next sync); removed units are unsubscribed and evicted, fused in one local transaction (E1–E4). Idempotent; re-entry cancels any deferred eviction.

pub fn window_state(&self, base: &WindowBase) -> Vec<String>

§4.8 completeness oracle (I3): the windowed-in units for a base.

pub fn mutate(&mut self, mutations: Vec<Mutation>) -> Result<String, String>

Record one atomic local commit (§7.1) and apply it optimistically.

pub fn pending_commit_ids(&self) -> Vec<String>

pub fn conflicts(&self) -> &[ConflictRecord]

pub fn rejections(&self) -> &[RejectionRecord]

pub fn schema_floor(&self) -> Option<&SchemaFloor>

pub fn lease_state(&self) -> Option<&LeaseState>

§7.3.5: the client’s opaque auth-lease state, if any.

pub fn sync_needed(&self) -> bool

pub fn subscription_state(&self, id: &str) -> Option<SubscriptionStateView>

pub fn read_rows(&self, table: &str) -> Result<Vec<RowState>, String>

pub fn query( &self, sql: &str, params: &[Value], ) -> Result<Vec<Map<String, Value>>, String>

Run an arbitrary read-only SQL query against the local database and return each row as a column-name → JSON value map. This is the seam the React useSyncQuery live-query API needs (it takes app-authored SQL over the visible tables/views, not a fixed table read like [read_rows]).

Bound params are the driver value forms: JSON strings/numbers/bools/ null bind directly; a {"$bytes": hex} object binds as a BLOB — the same envelope the command surface uses everywhere else. Output BLOB columns come back as {"$bytes": hex} to round-trip cleanly.

The result column typing is dynamic (SQLite’s stored affinity), because arbitrary SQL can alias, join, and compute — there is no schema column to consult per output cell, unlike [read_rows].

pub fn sync(&mut self, transport: &mut dyn Transport) -> SyncOutcome

pub fn sync_until_idle( &mut self, transport: &mut dyn Transport, max_rounds: Option<u32>, ) -> SyncOutcome

pub fn upload_blob( &mut self, bytes: &[u8], media_type: Option<String>, name: Option<String>, ) -> Result<Value, String>

§5.9.7: hash bytes into the content address, cache them, queue the upload (flushed before the next push, B4). Returns the canonical BlobRef JSON {blobId, byteLength, mediaType?} for a blob_ref column value.

pub fn fetch_blob( &mut self, transport: &mut dyn Transport, blob_id_or_ref: &str, ) -> Result<Value, (String, String)>

§5.9.7: resolve blob bytes — a content-addressed cache hit serves with no fetch (B1); a miss downloads (§5.9.5), verifies the address, caches, and returns {blobId, byteLength, bytes:{$bytes:hex}}.

pub fn connect_realtime( &mut self, transport: &mut dyn Transport, ) -> Result<(), String>

pub fn disconnect_realtime(&mut self, transport: &mut dyn Transport)

pub fn set_presence( &mut self, transport: &mut dyn Transport, scope_key: &str, doc: Option<&Value>, ) -> Result<(), String>

§8.6.2: publish (or clear, doc: None) this client’s presence document for scope_key. Requires a live socket; the document is ephemeral (lost on disconnect). Authorization is the connection’s registration (§8.6.3) — an unheld key is rejected loudly by the server with presence.forbidden.

pub fn presence(&self, scope_key: &str) -> Vec<PresencePeer>

§8.6: the peers currently present on a scope key (ephemeral).

pub fn on_realtime_text(&mut self, text: &str)

Inbound JSON control message (§8.1). Unknown events are tolerated.

pub fn on_realtime_binary( &mut self, transport: &mut dyn Transport, bytes: &[u8], )

Inbound binary delta: a complete SSP2 response (§8.2), applied like a pull response per section; an unapplied delta is a wake-up.