Skip to main content

Module store_peer

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§

ForeignToken
A ResumeToken that no StoreSyncPeer minted.
StoreResume
Where a StoreSyncPeer pull left off: the first far-store position of the last group it forwarded, or the start.
StoreSyncPeer
A peer over a store the caller holds: events to read, ingest to write.

Enums§

StorePeerError
How a StoreSyncPeer fails: its store’s group-read error R, its ingest error W, its merge rule’s error A, or a push over the limits it declared.