Module store_peer
Expand description
A SyncPeer whose far side is a store the caller holds.
§What it is for
StoreSyncPeer is the far side of a network peer with the network taken
out: a pull reads the store, a push ingests into it. A server mounts it
behind serve_sync — the Durable Object over its
SQLite, a Postgres-backed service over its pool — and a client reaches it
through RemoteSyncPeer. In-process, it is also a
peer in its own right: two stores in one program replicate through it with
no transport at all.
§The token is the far store’s own position
StoreResume carries the first
SequencePosition of the last group a
pull forwarded, and the next pull reads the groups above it. A position is
meaningful only inside the
store that assigned it, which is exactly where it goes: a token is handed
back only to the peer that minted it (SY-15), and that peer reads the store
that numbered it. Nothing here can tell a token minted by a different
store peer from one minted by this one — both are numbers — so a caller that
swaps the far side under a saved token resumes at the wrong place. That is
the caller’s to prevent, the same way it is for any opaque token.
§Groups: one write is one group
A pull reads the far store through
read_groups and hands back one
EventGroup per write group the store wrote: an append, or an ingested
group with the compensation written beside it (SY-2). Each arrives whole,
and an ingested group carries the guard it was pushed
with, so a relay forwards the origin’s evidence (SY-6, SY-30). A page never
splits a group and never merges two: a group that would take the page past
its budget waits, whole, for the next pull. Rows the store wrote before it
recorded groups come back one group each, without a guard.
§Waiting
A pull reads one event past what its budget can carry, so it knows in the
same call whether it reached the end of the far log. It says
Waiting::Nothing only when the read ended with every group sent, and
Waiting::Unknown otherwise. It never counts: an exact count is a scan of
the rest of the log on every pull.
§The responder
Every Pulled and every Ack names the store that answered
(ADR-0104): the ingest half’s store_id, read
after the page or after the watermark. A runner that sees it change between
two answers knows the far store was restored or re-minted (VT-6).
Read after, not before: a re-mint that lands between the page and the read labels an old incarnation’s page with the new identity. That errs toward stopping the edge, which is the safe direction for SY-34; read first, the same race would label the new incarnation’s page with the old identity, and the edge would carry on.
It is read on every call, and never cached. A cached identity is the one a re-mint does not reach, which is the change the field exists to report. The cost is one more read of the store per pull and per push. On a store that keeps its identity in memory that is a field load; on a SQL store it is one indexed read of a one-row table; on Neon, whose store reads its meta row on every call (ADR-0086), it is one more read-only HTTP round trip to the database. It adds none on the sync wire: a remote pull or push is still one exchange, and the identity travels in its reply.
Structs§
- Foreign
Token - A
ResumeTokenthat noStoreSyncPeerminted. - Store
Resume - Where a
StoreSyncPeerpull left off: thefirstfar-store position of the last group it forwarded, or the start. - Store
Sync Peer - A peer over a store the caller holds:
eventsto read,ingestto write.
Enums§
- Store
Peer Error - How a
StoreSyncPeerfails: its store’s group-read errorR, its ingest errorW, its merge rule’s errorA, or a push over the limits it declared.