Module write_group
Expand description
The write-group port: a store’s log read back in the writes that made it.
§Why a store has to say this
EventStore::read yields one event
at a time, and nothing on a
SequencedEvent says which append,
or which ingested group, wrote it. A runner pushing the local log, or a
StoreSyncPeer answering a pull, therefore could
not keep a multi-event write whole: it cut one at a page boundary, or merged
independent writes into one atomic unit, and a relayed foreign group lost
the guard it arrived with (SY-30, #420).
WriteGroupStore is the store saying it. Every row belongs to exactly one
write group: one append call is one group, and one
IngestGroup that lands at least one foreign event is
one group, its compensation included (SY-2). A group is named by its
first position, the lowest local position among the
rows it wrote, and reads back with the guard it was ingested under.
§Why this trait lives here and not on EventStore
The argument ingest makes for IngestStore:
coherence lets each adapter implement a trait this crate defines, so
happenstance-core never hears about write groups and no published read
type changes. A group id is store-local and never travels; the wire shape
stays EventGroup.
§Why first is the cursor
A store that serialises its writers (SQLite, the Durable Object, the
in-memory stores) writes a group’s rows contiguously, and either end of the
group would do. Postgres and Neon do not serialise: two concurrent appends
can interleave their positions, G = {5, 7} and H = {6, 8}. Resuming above
the last position pushed after G would skip H’s row 6; resuming above G’s
first position does not. Every row at a position at or below a group’s
first belongs to a group whose own first is no higher, so it was read
already, and a group commits in one transaction, so no group with first
at or below an observed position can appear later (ES-10).
§Rows written before a store recorded groups
Read as one group each, named by their own position, with no guard. Which rows one earlier call wrote is not recorded anywhere, so it cannot be recovered; a pre-upgrade multi-event append still travels split, exactly as it did before.
Structs§
- Group
Order Error - A
GroupPageBuilderwas offered a row out of group order: one naming the groupfirst, after the groupafterhad been offered and left, wherefirstis not aboveafter. - Group
Page - What one
read_groupsreturned. - Group
Page Builder - Folds rows, offered in group order, into a page of whole groups.
- Write
Group - One write as the store recorded it: the events one
append, or one ingested group with its compensation, wrote together, and the origin’s guard.
Enums§
- Guard
Codec Error - Why a guard could not be stored or read back.
Constants§
- STORED_
GUARD_ FORMAT - The first byte of every stored guard.
Traits§
- Send
Write Group Store - A store that can read its log back in the write groups it wrote.
- Write
Group Store - A store that can read its log back in the write groups it wrote.
Functions§
- decode_
guard - The guard
storedholds, asencode_guardwrote it. - encode_
guard - The bytes a store keeps for
guard.