Working copies
How a device keeps a copy of part of an instance, reads it without a connection, and has the writes it queued judged by the instance when it reconnects.
A device is a program that keeps a working copy of part of an instance on the machine it runs on. It reads from that copy, and sends its writes from a queue when it can reach the server. An app built on the Swift SDK, the CLI's marfa device and a synced folder are devices. A device syncs only with the instance, the source of truth.
The working copy
A device chooses the slice it keeps: the types, tier and edge types it holds, and can pin an item to keep it regardless. The copy is one file, the store. A file system that can't lock files is refused invalid.
A hydration fills the copy with the slice, and the event stream then keeps it current:
marfa device --db reading.db hydrate --type app.example.expense --tier library
marfa device --db reading.db catch-uphydrated 2 item(s) and 0 edge(s) of app.example.expense at library in 1 page(s); cursor 7
applied 0 event(s), skipped 0; cursor 7Reads need no connection. While the copy fills, it marks a list or search partial, and refuses an edge read or a read of an item that hasn't arrived, hydration_incomplete. A device holds a table only when an app asks, and keeps fetched files within a file budget (Keep files on a device).
When the copy falls behind
- A copy away longer than the instance keeps events is
stale: its reads say so until a hydration refills it. - A copy that finds another instance at the address, or a changed credential reach, has expired. It refuses reads and writes until a hydration, which empties the copy and keeps the queue and pins. After another instance, each waiting write is held
blocked: instance_changeduntil an app releases or withdraws it. - A server put back to an earlier point expires the copy too. The next hydration queues, blocked
server_restored, the work the copy held that the server lost (Restore a copy of the data directory). - A store made by a build of the core with another schema won't open. The refusal names the release that last saved it, the only build that can send the writes it holds.
Fix a working copy that can't catch up says what to run for each message.
A write made offline
A write shows in the copy at once and waits in the queue with the version it was based on, and survives the app being killed. A drain sends the queue in order, and the instance recognizes a retry, so none applies twice. A device sends every item update with conflict=auto, so the instance settles most collisions (Versions). Each answered write gets a verdict.
Verdicts
| Verdict | What happened |
|---|---|
accepted | The instance applied the write. |
merged | It collided, and the merge rule settled it. |
conflicted | It collided. For an item, its value went into a conflicted copy. |
refused | The instance refused it. The content is kept to offer back. |
blocked | Something must change before it can go. |
dead | It failed five times, not counting network or server trouble. |
The other four need an app's attention: the queue's verdicts say what to do.
The rules are in the contract's device, queue and verdicts and folder sync chapters.