Queue and verdicts

Send a working copy's queued writes, read the instance's answer to each, and clear a write that stopped.

Every write a working copy makes waits in its queue, kept across launches, until a drain sends it. The server's answer to each write is its verdict. copy.queue reads and clears the queue. Write in a working copy explains when to drain and what to show.

Drain

queue.drain() sends what the queue holds once, in order, and records each verdict. It returns a DrainReport.

Nothing drains on its own unless the app holds a stream:

  • A held changes() stream drains once when the server is back, and again after a drain left a write undelivered.
  • A held updates() sequence drains again while the copy follows, after a drain left a write undelivered.
DrainReport fieldHolds
answeredWrites the server answered, whatever the answer.
heldWrites the pass held back.
undeliveredWrites that couldn't reach the server. They wait for the next drain.
unsentWrites settled without a request.
unmadeRequests that couldn't be made, counted against their write.
unavailableWhy the drain ended before the queue was through.
stoppedThe credential refusal that parked the queue.
retryAfterSecondsThe longest wait a rate limit asked for in the pass.
verdictsA DrainVerdict for each write attempted or settled.
unclaimedSourcesSources the writes named that the key hasn't claimed, so a credentialRefused isn't read as a key that stopped working.

A DrainVerdict has id, kind, itemId (an edge write's from end), edgeId, verdict, refusals, and replayed, which says the server answered from its record of the idempotency key rather than writing again.

Read the queue

queue.all() lists every queued write as a QueuedWrite:

FieldHolds
id, kindThe write and its WriteKind, such as createItem, replaceTags, uploadBlob or writeRows.
itemId, toId, edgeIdThe row written. For an edge write, itemId is the from end and toId the to end.
namespace, tag, blobAn extension's namespace, a tag, or an upload's hash.
baseVersion, idempotencyKeyThe version written over, and the key minted when it was queued.
dependsOnThe writes this one can't go without, and is refused with.
followsThe write ahead of it to the same row, which it goes after.
verdictnil until the server answers.
waitingHeld behind a write named in dependsOn or follows that has no answer. It goes once that one is answered.
body, answerWhat the write sends, and the server's whole answer.
refusals, environmentalStreak, lastFailureRefusals counted, drains in a row that met a failure that was no answer, and the last such failure's status and text.
queuedAt, answeredAtWhen it was queued and answered.

Verdicts

VerdictMeans
.acceptedWritten as sent.
.merged(fields:)Applied over changes made since, field by field.
.conflicted(siblingId:fields:conflicts:)The server kept its own value. An item's losing value went to the sibling siblingId. A table write names the cells it replaced in conflicts, each a RowConflict with row and column.
.refused(Refusal)The server refused it. It is never sent again.
.blocked(reason:refusal:)Stopped until something outside the queue changes.
.deadRefused five times. Never sent again unless released.

An accepted, merged or conflicted write is never sent again. Conflicts explains what a person sees.

Refusals

Refusal fieldHolds
reasonThe server's code, or a sentence naming the refused write this one waited on.
code, messageThe server's code and message.
fieldsEach property refused, as field and message.
trashedThe row is in the bin and can be restored.
grantThe permission the key lacks: kind (.type, .edgeType or .extension), name and level (.read or .write).
requestLimitThe write's size and the server's limit in bytes.

A write larger than the server's request limit is never sent. The copy refuses it unsent with the code over_request_limit and both numbers in requestLimit, so the app can say how much to remove. The limit is the instance's max_request_bytes.

For example, a write to an item another device moved to the bin is refused with reason and code item_not_found and trashed set.

Blocked writes

BlockedReasonMeansClears
.credentialRefusedThe server refused the key.By itself: the next drain sends it again.
.keySpentThe server answered 422 idempotency_contract_changed: the key went with another request.Release, which sends it under a fresh key.
.ancestorUnavailableThe server answered 409 ancestor_unavailable.Release or withdraw.
.conflictUnresolvedThe server answered 409 version_conflict. A tag replace gets it when another writer changed the tags since the copy read them, and the copy keeps the person's tags.Release, which sends a tag replace with no read_tags, so the tags become the copy's, or withdraw.
.failingAloneSet aside: it keeps meeting a failure that is no answer while other writes go. lastFailure says what.Release or withdraw.
.instanceChangedQueued against an instance other than the one the copy is built from now.Release, which sends it to the instance there, or withdraw.
.recordUnreadCarried from a store set aside where the record deciding how it is sent couldn't be read.Release or withdraw.
.serverRestoredQueued to put back what the server lost when it was restored to an earlier point, and never sent.Release, which keeps its key, or withdraw.

A write held behind another isn't blocked: it has no verdict, and waiting is set.

Clear a stopped write

CallDoes
queue.release(_ id)Queues a blocked or dead write for the next drain, under its idempotency key unless it was blocked keySpent, conflictUnresolved or ancestorUnavailable, which get a fresh one. A row write goes with its whole batch. Returns whether it released one.
queue.release(reason:)Releases every write blocked for one reason, and returns how many.
queue.withdraw(_ id)Takes a write that can never be sent out of the queue and puts its row back as the server holds it.
queue.discard(_ id)Takes a refused write, and the content it carried, out of the queue.
queue.forgetAnswered()Clears answered writes, and returns how many.
queue.forgetAnswered(ids:)Clears only the named answered writes.
queue.takeAnswered()Clears what forgetAnswered() clears and returns each write, in one step.

withdraw takes only a dead write or one blocked ancestorUnavailable, conflictUnresolved, failingAlone, instanceChanged, recordUnread or serverRestored. It returns the ID of every write it took, more than one where the write belonged to a batch, and an empty list for any other write. It reads the row from the server first, so it needs the server, and answers an empty list when the copy moved during the read: ask again. Writes waiting on it are refused unsent.

discard returns false for a write that isn't refused or that a waiting write depends on, and throws notFound for an ID the queue doesn't hold.

The clearing calls keep what a person made:

  • A refused write that carried content stays, with its body readable, until discard.
  • Blocked and dead writes stay until released or withdrawn.
  • An answered write that a waiting write depends on stays.

Use takeAnswered() to act on answers: two callers never both get one answer, and none is cleared unread. Each clearing call tells held streams .refreshed(.forgotten) when it cleared something.

The rules are in the contract's queue and verdicts chapter.

On this page