Struct SyncClient 

pub struct SyncClient { /* private fields */ }

Implementations

impl SyncClient

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

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 open_path_with_identity( client_id: Option<String>, schema_json: &Value, limits: ClientLimits, path: &str, ) -> Result<Self, String>

pub fn client_id(&self) -> &str

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 security_lifecycle(&self) -> &'static str

pub fn security_preflight(&self) -> bool

pub fn begin_security_preflight(&mut self)

Enter the fail-closed gate and release all core-owned key material.

pub fn activate_security( &mut self, encryption: EncryptionConfig, ) -> Result<(), String>

Install the post-authentication keyring and release the host loop.

pub fn local_revision(&self) -> u64

pub fn status_snapshot(&self) -> SyncStatusSnapshot

pub fn diagnostics_snapshot( &self, request: &ClientDiagnosticsRequest, ) -> Result<ClientDiagnosticsSnapshot, String>

pub fn drain_change_batches(&mut self) -> Vec<ClientChangeBatch>

pub fn drain_sync_intents(&mut self) -> Vec<SyncIntent>

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 commit_outcome( &self, client_commit_id: &str, ) -> Result<Option<CommitOutcome>, String>

pub fn commit_outcomes( &self, query: CommitOutcomeQuery, ) -> Result<Vec<CommitOutcome>, String>

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<CommandEffects, 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) -> WindowState

§4.8 completeness oracle (I3): the windowed-in units for a base plus the subset still bootstrap-pending. Registration alone is not completeness — a unit is pending until its subscription completes a bootstrap round (cursor advances past -1 with no resume token held).

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

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

pub fn patch( &mut self, table: &str, row_id: &str, partial: Map<String, Value>, base_version: Option<i64>, ) -> Result<String, String>

Merge a partial update over the current visible local row, then record the ordinary full-row upsert. This keeps patch semantics identical across the TypeScript and native cores without weakening the wire’s full-row invariant.

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

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

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

pub fn resolve_commit_outcome( &mut self, input: ResolveCommitOutcomeInput, ) -> Result<CommitOutcome, String>

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: &[QueryValue], ) -> Result<Vec<QueryRow>, 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 query_snapshot( &mut self, sql: &str, params: &[QueryValue], coverage: &[WindowCoverage], ) -> Result<QuerySnapshot, String>

Rows, coverage, and local revision from one SQLite read snapshot.

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 purge_local_data( &mut self, input: &LocalDataPurgeInput, ) -> Result<LocalDataPurgeResult, String>

Apply one host-authorized local security purge. The host MUST gate the corresponding subscriptions first; this primitive owns local SQLite cleanup and never grants/revokes server authority by itself.

pub fn rebootstrap_local_data( &mut self, input: &LocalDataRebootstrapInput, ) -> Result<LocalDataRebootstrapResult, String>

Application-authorized recovery of the replicated projection. Unlike a local security purge, this retains the entire outbox, device identity, lease, outcomes, subscription registrations, and protected bookkeeping. The projection reset, subscription rewind, optimistic replay, and idempotency marker share one savepoint for interruption safety.

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.