Working copy
Open, fill, pin, catch up and close a working copy, give it a new key, and recover a store it refuses.
WorkingCopy is the copy an app keeps on the device. It lives in one SQLite store, holds a slice of the instance and queues every write. Devices explains the slice, hydration and the queue; this page lists the calls.
Open a copy
import Marfa
let store = URL.applicationSupportDirectory.appending(path: "marfa.sqlite")
let server = try Server(url: URL(string: "https://marfa.example.com")!, key: key)
let copy = try await WorkingCopy.open(store: store, server: server)WorkingCopy.open(store:server:fileBudget:ifRefused:) opens the store at store, and makes it when absent. It makes no request. Through a symbolic link, its lock and files sit beside the target. A new copy reads and queues writes before its first hydration.
| Parameter | Default | What it does |
|---|---|---|
store | The store's file URL. | |
server | nil | The server to hydrate from, catch up from and drain to. Without one the copy is local only. |
fileBudget | nil | The budget of the file cache, set before the call returns. nil keeps what the store holds. |
ifRefused | .keep | What to do with a store another build of the core made. .replace replaces it with an empty store only when it holds no unsent write. |
A replaced store keeps its downloaded files and file budget. It loses its pins, its position in the server's events and its declared types, so hydrate it as a new copy.
open throws | When |
|---|---|
MarfaError.wrongSchema | Another build of the core made the store. unsent counts the writes the server hasn't taken. See A store the copy refuses. |
MarfaError.storeDamaged | SQLite can't read the store. |
MarfaError.store | The lock file can't be opened for writing, or the store can't use write-ahead mode. |
MarfaError.invalid | The store's file system doesn't lock files, as on a network share or WebDAV. |
MarfaError.readingHandle | A second opener passed a fileBudget, or .replace found another process writing the store. |
SignInError.notSignedIn | server was made from a credential the keychain no longer holds. |
A store made against another address opens and keeps its writes. The first call that reaches the server asks which instance answers. If it is the instance the store was made against, the store follows it to the new address. Otherwise the call throws wrongServer and sends nothing.
The writer and readers
copy.handle is .writer or .reader. The first process to open a store is its writer; a second opener of the same store gets a reader.
- A reader writes nothing. It opens the store read-only, records no renewed credential and no new address, and its
changes()stream hears each of the writer's saves. A new stream on a reader first hears one.saved, so it misses no save made as it started. - A reader can still send requests from a moved address of the same instance, and leaves recording the address to the writer.
WorkingCopy.openReader(store:)opens a reader that never takes the writer role, so a helper process started first can't lock the app out. It throwsinvalidwhen no store exists at the path yet.
The copy's parts
| Property | Type | Page |
|---|---|---|
items | Items | Items, edges and tables, and saved views on Views and folders |
edges | Edges | Items, edges and tables |
tags, metadata, extensions | Tags, Metadata, Extensions | Items, edges and tables |
tables | Tables | Items, edges and tables |
blobs | Blobs | Files |
queue | Queue | Queue and verdicts |
catalog | Catalog | Sign-in and server calls |
Fill the copy
let report = try await copy.hydrate(types: ["*"], tier: .all, edgeTypes: ["in-collection"])hydrate(types:tier:edgeTypes:inPlaceOnly:) replaces the copy with every item of types at tier, with their tags and the edges going out from them. Each edge type in edgeTypes is held whole.
typesnames types or patterns.["*"]alone is every type exceptsystem.*. Besidesystem.*types it adds them; beside any other type it throwsinvalid.tieris.library,.feedor.all.- An interrupted hydration resumes from the page it reached when its slice is unchanged. The report says
resumed, or why itrestarted. - Reads during a fill answer what has arrived, marked
.partial. A read of a view throwshydrationIncomplete.status()shows progress initemsListedagainstitemsExpected. - The copy runs one hydration at a time. A second call waits, and returns the first one's report when it filled the same slice under the same key.
- The call tells every
changes()stream.refreshed(.hydrated)when it completes, and.refreshed(.unfinished)when it fails or is canceled.
A copy whose cursor the server's event log let go has status().hydration of .stale. Hydrating a stale copy refills it in place: reads answer the rows it holds, marked .stale, and the report says inPlace. Until the refill completes, item writes are queued and edge writes throw hydrationIncomplete.
inPlaceOnly: true refills or does nothing. It never removes a row, an edge or a file, and throws before it changes anything when the hydration would clear the copy:
| Error | Reason | Why |
|---|---|---|
instanceChanged | The copy was built from another instance. | |
copyExpired | not_stale | The copy isn't stale. |
copyExpired | reach_changed | The key or sign-in reaches other items. |
copyExpired | slice_changed | The types, tier or edge types differ. |
copyExpired | head_past_log | The server was restored behind the copy. |
Use it to ask whether to hydrate afresh or keep the copy stale. A server that refuses the credential or the reach of a stale copy ends it all the same: .stale is a copy kept, .expired a copy ended.
The hydration report
| Field | Holds |
|---|---|
types, tier, edgeTypes | The slice filled. |
items, edges | What the copy holds now. |
pages, pagesTotal | Pages read. |
resumed, restarted | Whether it carried on, or why it started again. |
inPlace | Whether it refilled a stale copy. |
cursor | The position in the server's events it reached. |
registeredTypes, replacedTypes | Declared types the instance lacked and now holds, or held at an older version. |
unregisteredTypes, unreplacedTypes | Declared types the instance refused, each with id, code and message. |
Declare types
declareTypes(_:) replaces the app's declared types, each a type definition as a JSONObject. Offline creates are checked against them before the first hydration, and a hydration registers any the instance lacks. declaredTypes() reads them back with the empty fields and the version a registration needs. Define a type shows a definition.
Pin an item
pin(_:) reads and holds one item whatever the slice says, and returns a PinReport with pinned and wasPinned. An item in the bin throws notFound with the code trashed; one the server doesn't hold throws notFound with not_found. unpin(_:) lets the item go unless queued writes still need it.
Catch up
catchUp() reads the type catalog again, then applies every event since the last hydration or catch-up. A held changes() stream does this by itself. It waits for a hydration that is running.
CatchUpReport field | Holds |
|---|---|
applied | Events applied. |
skipped | Events the copy had no use for. |
cursor | The position it reached. |
catalogChanged | Whether the type catalog changed. |
readOnlyHeld | Rows whose readOnly changed. No event brings these, and applied doesn't count them. |
changedTables | Each held table it filled or changed, as itemId and table. |
Every item carries readOnly: whether a person's connector holds it read only, as the server last answered. It is advice for showing an item as not editable. Neither the copy nor the server refuses a write for it. The copy asks again at most every 15 minutes, and a change to the connector sends no event, so the value can be older. An item the server hasn't answered yet holds false.
Status
status() returns a Status:
| Field | Holds |
|---|---|
serverOrigin, instanceId | The server and instance the copy follows. |
sliceTypes, sliceTier, sliceEdgeTypes | The slice. |
pinned | Pinned item IDs. |
hydration | .never, .inProgress, .complete, .stale or .expired. |
items, edges | Rows held. |
itemsListed, itemsExpected | A running hydration's progress; itemsExpected is nil where the server didn't count. |
eventCursor, catalogVersion | Where the copy is in the server's events and its catalog. |
fileCache | The file cache. |
lastSynced | When the copy last finished a pull without error, by the device's clock. |
Search
search(_:filters:limit:) searches indexed fields and tags, best match first, and returns Rows<SearchHit>, each hit with item, score and snippet. limit defaults to 20. SearchFilters takes types, states, allStates, tier, tags, occurredAfter, occurredBefore, filter and beneath.
Give the copy a new key
use(_:) gives an open copy a new sign-in or key for the same server. The store reopens with the new token, and queued writes remain.
- Call it after
signedOutor.keyRefused, even with the same credential. - During the change, every call throws
keyChanging: ask again. It waits for the slowest running call first. - A new reach shows as
.needsHydrationonupdates(). Hydrate again. - Held
changes()streams keep going, and a follow the old key stopped starts again.
It throws noServer for a copy opened without a server, wrongServer for a server at another address, SignInError.notSignedIn for a credential the keychain no longer holds, and closed. In each, nothing changes.
Close
close() releases the store once running calls finish. A call made after it begins throws closed at once, on the copy or its parts, and the last update on updates() is .closed. Closing twice does nothing.
A store the copy refuses
These static calls work on a store that is closed in this process. Each throws readingHandle while another process writes the store.
| Call | What it does |
|---|---|
WorkingCopy.check(store:) | Reads every page and checks each index, changing nothing. Throws storeDamaged or wrongSchema. |
WorkingCopy.unsentWrites(in:) | Lists the writes the server hasn't taken, from a damaged, refused or whole store, as UnsentWrites. |
WorkingCopy.remove(store:confirming:) | Removes the store, its log, its fetched files and its lock, losing exactly the writes it was shown. |
WorkingCopy.setAsideDamaged(store:) | Moves a damaged store to <store>.damaged-<n> and makes a new one carrying every write it could read. |
WorkingCopy.removeLosingAll(store:) | Removes a damaged store, losing every unsent write, read or not. |
A removal names what it loses. Show the person unsentWrites(in:), each UnsentWrite with id, kind, itemId, body and verdict, then pass the answer to remove(store:confirming:). If its writes changed since, it throws unsentDiffers and removes nothing: read and ask again. It throws invalid for a folder's store. A reader doesn't stop a removal and shows the old copy until it reopens.
let unsent = try await WorkingCopy.unsentWrites(in: store)
// Show unsent.writes and ask the person.
try await WorkingCopy.remove(store: store, confirming: unsent)setAsideDamaged(store:) deletes nothing. The new store holds no rows, so hydrate it, then drain to send what it carries. It throws invalid for a store that opens as it is or a folder's store, and a set-aside that stopped part way finishes when called again. Its SetAside answer:
| Field | Holds |
|---|---|
setAside | Where the damaged store now is. |
carried | Writes the new store carries. |
unread, unreadIds | Writes that couldn't be read, and the IDs that could. |
whole | Whether the old queue was read whole. Where not, the cache keeps every file until the old store is removed. |
held | Carried writes blocked instanceChanged, because the old store didn't say its instance. |
recordUnread | Carried writes blocked recordUnread, because a record that decides how each is sent couldn't be read. |
Release a held write to send it. The rules are in the contract's stores chapter, and A working copy that can't catch up covers what a person sees.