Devices

How an app keeps a copy of someone's data on a phone or a Mac, works without a connection, and sends its changes when it can.

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 is a device, and so is the CLI's marfa device. A device syncs only with the instance, the source of truth, never with another device.

The working copy

A device chooses the slice it keeps: the types, tier and edge types it holds. * alone holds every type except system.*. It can also pin an item to keep it whatever the slice says.

The copy is one file, the store, on a file system that locks files: one on a network share or WebDAV is refused invalid. Reached through a symbolic link, its lock and files sit beside the file the link leads to.

The device fills its copy once, by a hydration that reads every item in the slice, then keeps it current from the event stream:

Terminal
marfa device --db reading.db hydrate --type core.bookmark --tier library
marfa device --db reading.db catch-up
hydrated 1 item(s) and 0 edge(s) of core.bookmark at library in 1 page(s); cursor 32
applied 0 event(s), skipped 0; cursor 32

A sign-in that expires during a long read is renewed, and the read goes on from its last event. Only a key or an ended sign-in ends it credential_ended.

Reads need no connection, saved views included. While the copy fills, it answers from what has arrived, marking a list or a search partial. An edge read or write, and a read or write of an item that hasn't arrived, are refused hydration_incomplete.

Other processes can read the copy while one writes: see the writer and readers.

Tables and files

A device holds a table only when an app asks, so a phone can hold a step counter without ten years of its readings. A table too large to hold is read from the server, by the table rules.

A device keeps fetched files within a file budget, dropping the least recently read: see Keep files on a device.

When the copy falls behind

A copy sometimes needs filling again, and its queued writes wait.

  • After a device was away longer than the instance keeps events, its copy is stale: it answers reads marked stale, and refuses edge reads, until a hydration refills it in place.
  • When another instance answers at the address, or the credential's reach changed, the copy has expired. The device confirms its instance before each call that sends what the copy holds. The copy refuses reads and writes until a hydration, which empties it first.
  • When the server was put back to an earlier point, as from a disk snapshot, it expires too. The next hydration queues what the server lost, blocked server_restored, as Restore a copy of the data directory shows.

Fix a working copy that can't catch up says what to run for each message.

A write made offline

A write made offline shows in the copy at once, and waits in the queue with the version it was based on. A queued write survives the app being killed. On Linux it also survives a power cut; on a Mac, iPhone or iPad, a power cut can lose the last writes, but the store stays whole. Sending the queue is a drain. A drain sends them in order, or leaves them queued while it can't reach the server, and the instance recognizes a retry, so none applies twice. Each answered write gets a verdict, and the copy takes what the instance now holds.

A device sends every update with conflict=auto, so the instance settles most collisions, as Versions explains.

Verdicts

Each settled write gets one of six verdicts:

VerdictWhat happened
acceptedThe instance applied the write.
mergedThe write collided with a change to the same field, and the type's merge rule settled it.
conflictedThe write collided, and the type's merge rule put its value in a conflicted copy.
refusedThe instance refused the write, whose content is kept to offer back.
blockedSomething must change before the write can go.
deadThe write failed five times, not counting network or server trouble.

Only the last three need an app's attention: blocked writes lists how each reason a write is blocked clears.

A release resends the write under its idempotency key, so the instance answers an attempt that may have applied from its record. Only a write blocked key_spent, conflict_unresolved or ancestor_unavailable gets a fresh key, because the old one applied none of it. A withdrawal removes it and resets the copy to what the instance holds.

A working copy can also be a folder of files: see Sync a folder.

The rules behind this page are in the device, queue and verdicts and folder sync chapters of the contract.

On this page