Expand description
§syncular-client — Syncular v2 Rust client core (POC stage 2)
A clean-room client implementation of the SPEC.md client-behavior
contract on rusqlite local storage, consuming the committed ssp2
codec as its wire layer. Built without reading the v1 Rust tree or the
v2 TypeScript client — the conformance catalog (packages/conformance)
is the proof that both cores implement one written protocol.
Blocking hosts drive sync() / sync_until_idle(). Mailbox hosts prepare
a round on the owner, run PreparedSyncRound::exchange on an I/O executor,
and apply the result on the owner. An upload continuation repeats that
exchange/apply cycle before the captured metadata request. The owner can
serve local commands throughout; it queues inbound realtime traffic until
the round completes. Scheduling is host policy (§8.4).
Re-exports§
pub use api::creation_time_bucket;pub use api::last;pub use api::AuthorityReadDeclaration;pub use api::ClientChangeBatch;pub use api::ClientDiagnosticsHost;pub use api::ClientDiagnosticsLease;pub use api::ClientDiagnosticsReplica;pub use api::ClientDiagnosticsRequest;pub use api::ClientDiagnosticsSchema;pub use api::ClientDiagnosticsSnapshot;pub use api::ClientDiagnosticsStorage;pub use api::ClientLimits;pub use api::CommandEffects;pub use api::CommitOperation;pub use api::CommitOperationOutcome;pub use api::CommitOutcome;pub use api::CommitOutcomeQuery;pub use api::CommitOutcomeResolution;pub use api::CommitOutcomeStatus;pub use api::ConflictRecord;pub use api::CoverageSnapshot;pub use api::DiagnosticLastChange;pub use api::DiagnosticLastRound;pub use api::DiagnosticQueryFailure;pub use api::DiagnosticRoundCounters;pub use api::DiagnosticSubscription;pub use api::ExpectedDiagnosticSubscription;pub use api::FetchedBlob;pub use api::LocalDataPurgeInput;pub use api::LocalDataPurgeResult;pub use api::LocalDataPurgeTarget;pub use api::LocalDataRebootstrapInput;pub use api::LocalDataRebootstrapResult;pub use api::Mutation;pub use api::PresencePeer;pub use api::QueryOwner;pub use api::QueryReadFailure;pub use api::QueryRow;pub use api::QuerySnapshot;pub use api::QueryValue;pub use api::RealtimePolicy;pub use api::RealtimeState;pub use api::RejectionRecord;pub use api::ResolveCommitOutcomeInput;pub use api::RetainedCommitRow;pub use api::RetainedUniqueConflict;pub use api::RowState;pub use api::SchemaFloor;pub use api::SubscriptionStateView;pub use api::SyncIntent;pub use api::SyncOutcome;pub use api::SyncReport;pub use api::SyncStatusSnapshot;pub use api::TableChange;pub use api::TimeBucketUnit;pub use api::WindowBase;pub use api::WindowChange;pub use api::WindowCoverage;pub use api::WindowState;pub use api::WindowUnitRef;pub use api::CLIENT_DIAGNOSTICS_VERSION;pub use api::MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS;pub use api::MAX_DIAGNOSTIC_QUERY_FAILURES;pub use api::REALTIME_LOST_CODE;pub use api::REALTIME_UNAVAILABLE_CODE;pub use client::FileQuerySnapshotReader;pub use client::SyncClient;pub use client::SECURITY_PREFLIGHT_REQUIRED_CODE;pub use schema::compile_schema;pub use schema::parse_schema_json;pub use schema::ClientSchema;pub use transport::BlobDownload;pub use transport::BlobUploadGrant;pub use transport::SegmentRequest;pub use transport::Transport;pub use transport::TransportError;pub use realtime_round::RealtimeRound;pub use realtime_round::RoundInbound;pub use realtime_round::REALTIME_TAG_DELTA;pub use realtime_round::REALTIME_TAG_ROUND;pub use remote::PreparedRemoteCommit;pub use remote::RemoteBytes;pub use remote::RemoteClientError;pub use remote::RemoteCommandResult;pub use remote::RemoteCommitInput;pub use remote::RemoteCommitResult;pub use remote::RemoteQueryResult;pub use remote::SyncRemoteClient;
Modules§
- api
- Driver-facing API shapes (JSON-able), mirroring the conformance
ClientInstancecontract: sync reports, conflicts, rejections, row states, subscription states. Serialized as camelCase to cross the shim boundary unchanged. - client
- The Syncular v2 Rust client core (SPEC.md client-behavior contract): rusqlite local storage, §3.2/§3.3 effective-scope persistence + purge, §4 pull/cursor/bootstrap (§4.7 resume, §5.6 segment application), §6 push with outbox order, §7 optimistic apply / rollback / replay-on-top, §2.3 clientCommitId idempotency, §8 realtime client rules, §10 errors.
- native_
transport - Shared blocking HTTP/WebSocket host transport for Rust-backed bindings. The network stack is feature-gated; its no-network shape remains available in dependency-lean builds so host code needs only one transport type. Shared native host transport for every Rust-backed Syncular binding.
- previous_
version - RFC 0005 previous-version context: the persisted schema descriptor, the bounded capture, and the sibling container FILE beside the replica. RFC 0005 previous-version context — phase 1 (the storage half).
- query_
guard - The raw-query guard, mirrored from the TS core’s
query-guard.ts— the two cores enforce the same rule soquerybehaves identically through every binding: - realtime_
round - Transport-agnostic §8.7 sync-round-over-socket framing.
- remote
- Database-less SSP2 producer (
SPEC.md§6.10). - schema
- Client schema IR (SPEC.md §2.4) — the same JSON shape the conformance
fixture uses (
DriverSchema): tables with typed columns, a primary key, and §3.1 scope patterns ('prefix:{variable}', column defaults to the variable name). - transport
- The transport seam handed TO the client by its host (the conformance
harness, an app shell, …). Bytes and strings only — mirroring the
ClientEndpointsinversion of the conformance driver contract. The client is synchronous: the driver protocol is request/response. - values
- Value conversions at the client’s edges: driver JSON (
{"$bytes": hex}convention) ↔ the §2.4 row-codec values ↔ SQLite storage, plus the §11.2 canonical scope JSON (contractual across implementations).
Structs§
- Completed
Sync Round - Network results returned to the same mutable owner that prepared the round.
- Message
Stream Scanner - Feed bytes, learn exactly where one complete SSP2 envelope ends.
- Prepared
Sync Round - Immutable request and blob bodies captured by the mutable client owner. Send this value to an I/O executor; it contains no SQLite connection.
- Progress
Observer - Progress
Subscription - Keep this guard alive to receive updates; dropping it unsubscribes.
- Scanned
Message - A completed scan: the exact envelope bytes plus any surplus buffered
past the
ENDframe. - Sync
Progress
Enums§
- Applied
Sync Round - A completed upload returns to the owner to persist its pin removal before any metadata push. A completed response returns its durable apply outcome.
- Progress
Phase - Progress
State