rightkit-sync 0.1.1

Brand-neutral desktop/mobile cloud sync engine: change tokens, tombstones, last-writer-wins conflicts, resumable batches, offline queue, retry/backoff.
Documentation

rightkit-sync

Generic cloud sync engine for Right Suite apps. It owns change cursors, tombstones, last-writer-wins conflict resolution, resumable batches, an offline queue, retry and backoff, and an account-scoped ledger. It is aligned with the HeardRight iOS CloudKit record and conflict model.

Use it when an app must sync records through a cloud store and needs the same tombstone, conflict, and retry rules as the other Right Suite apps.

Do not use it as a transport on its own. The engine takes adapter traits; the CloudKit backend is the macOS helper described below.

Public surface

  • API.md (in this crate): adapter traits, the shared wire contract, the helper protocol, and per-app migration. Read it before changing record or conflict behavior.
  • helper::{CloudKitHelper, HelperBackend, HelperAuth}: the macOS CloudKit backend, over the Swift rightkit-cloudkit-helper (swift/RightKitCloudKitHelper at the RightKit root). HelperAuth is defined in src/helper/mod.rs.
  • MemoryBackend (src/memory.rs) and the rightkit-sync-fake-helper binary (src/bin/rightkit-sync-fake-helper.rs): a reference zone and protocol fake for tests. The fake-helper binary and its end-to-end test live in the repository only; the published package ships MemoryBackend but not the binary.

Features

None. The crate has no Cargo features. Dependencies: serde, serde_json, rightkit-child-process (process usage in SyncEngine::status(), src/engine.rs), and rightkit-fs (fs feature, for the durable ledger write, src/storage.rs).

Platform support

  • macOS: the CloudKit helper backend. The helper is a separate Swift binary.
  • Windows: cfg(windows) process handling in src/helper/process.rs.
  • The engine, MemoryBackend, and the fake helper (repository only) are portable Rust.

Published version: see INDEX.md at the repository root. Changes are recorded in CHANGELOG.md.

Example

Illustrative; not compiled as a doctest. For compiled usage, see tests/convergence.rs (engine behavior) and, in the repository only, tests/helper_e2e.rs (helper protocol through the fake helper).

// Build a sync engine over MemoryBackend in tests, or over CloudKitHelper
// in the app's macOS host, and drive it with the app's record mapper.

Runtime budget

Generated from runtime-budget.json; edit that file, then run node packages/release/runtime-budgets.mjs sync <crate-dir>.

  • Resident memory ceiling: undeclared.
  • CPU ceiling (idle, steady state): 1%.
  • Wake-ups ceiling: 1 per second.
  • Disk operations ceiling: 1 operations per second.
  • Required scale: 100,000 records or more.
  • Required hosts: macOS and Windows.
  • Status exposure: SyncEngine::status() in src/engine.rs; exposes resident memory, idle CPU, wake-ups, disk operations.
  • Measured: not yet measured.