Expand description
Brand-neutral cloud sync engine. See API.md for the adapter traits and
the record/conflict contract shared with the iOS CloudKit implementation.
Modules§
- field
- helper
- Backend for a helper process speaking the
rightkit-sync-helper/1line-JSON protocol. The macOS CloudKit helper (rightkit-cloudkit-helper, Swift) is the production implementation;rightkit-sync-fake-helperis the protocol fake used by the end-to-end tests. SeeAPI.mdsection 4. - wire
- Line-JSON wire format of the
rightkit-sync-helper/1protocol. One JSON object per line, UTF-8, no other framing. SeeAPI.mdsection 4.
Structs§
- Always
Available - Backoff
Policy - Deterministic exponential backoff merged with server hints.
- Change
Page - Consent
Request - A change of the signed-in account or sync scope that the app has not yet consented to.
fromis the scope the local store last synced with;tois the scope now signed in. - File
Storage - Atomic, durable, owner-only write (temp file, fsync, rename, fsync directory) to one file,
through
rightkit_fs::atomic_write_private. - Item
Header - Immutable identity + version of one syncable item.
- Last
Writer Wins - Ledger
- Ledger
Store - Memory
Backend - Memory
Storage - Clonable in-memory storage; clones share bytes (simulates an app restart).
- NoHooks
- Null
Observer - Pass
Report - RawRecord
- Record
Outcome - Remote
Version - Schedule
Policy - Delays the scheduler suggests.
backoffshould match the engine’sSyncConfig::backoff. - Sync
Budget - What one
sync_oncecall may spend. - Sync
Config - Sync
Engine - Sync
Engine Builder - Sync
Metrics - Cumulative engine counters and current ledger queue sizes, from
SyncEngine::metrics. Queue sizes are the figures that grow resident memory: the ledger keeps one remote version per record and is serialized in full on every durable write. - Sync
Report - What
sync_oncedid, in plain data a host can pass across an FFI boundary. - Sync
Status - Runtime figures of the engine, computed on call by
SyncEngine::status. - System
Clock
Enums§
- Apply
Outcome - Result of landing one downloaded item locally.
- Consent
Choice - The app’s answer to a
PassOutcome::ConsentRequiredpause. - Field
Value - Pass
Outcome - Save
Policy - Sync
Error - Work
Outcome - How the host should report the run to its scheduler.
Traits§
- Auth
Provider - Account state and session credentials.
generationchanges on account switch; an in-flight pass observing a different generation cancels itself. - Backend
- The cloud zone. Method set mirrors the iOS
CloudSyncService. - Clock
- Conflict
Policy - Last-writer-wins by default. Tombstones and duplicate-alias reduction are fixed by the shared contract and not pluggable here.
- Ledger
Storage - Local
Store - The app’s local data. All calls are synchronous.
- Pass
Hooks - Optional domain extension for record types the engine does not own (device announcements, request queues, …).
- Record
Mapper - Domain <-> wire mapping for the one syncable item type.
- Sync
Observer - Free-form diagnostics hook (no logging dependency baked in).
Functions§
- next_
delay - Seconds until the next run, never below
policy.min_secs;Nonewhen nothing should be scheduled (disabled, or waiting for the app’s consent answer). - read_
tombstone (id, deletedAt)when the record is a tombstone. The id falls back to the record name for legacy tombstones that lost theiridfield.- should_
continue - Whether another pass should run inside the same call.
- sync_
once - Runs the engine for one bounded unit of work. Never sleeps; see the module docs.
- work_
outcome - How the host reports
outcometo its scheduler. - write_
tombstone - Tombstone convention shared with HeardRight iOS: keep
id,updatedAt(= deletion time) anddeletedAt; clear every other field exceptkeep. Decoders must not require any other field on a tombstone.
Type Aliases§
- Extras
- Durable app-owned scratch the engine persists inside its ledger.
- Sync
Result