Module event_store
event-store only.Expand description
The Neon-backed EventStore, and the buffered thing it calls a stream.
§Cancellation
A dropped append future MAY already have committed, and this adapter
cannot tell you which. ES-23 is [FROZEN] and obliges every adapter to
state which of its two outcomes it has; this is ours.
append awaits one SqlTransport::round_trip per attempt. This crate owns
no HTTP client — crate::NullTransport is the only one in src/ —
so what dropping the future does to a request already in flight is a
property of whatever transport a caller supplied, and not something this
adapter can promise anything about. The endpoint may well execute the batch
and discard the response nobody is waiting for.
The retry loop widens the window rather than narrowing it: a drop can land between attempts, after an earlier attempt has already reached the endpoint.
A caller MUST NOT read a dropped future as evidence either way. ES-24 is the resolution: reissue the identical batch, and let event identity make the reissue idempotent.
§Why the bare flavour
SendEventStore would require every
future this crate produces to be Send, and the wasm32 transport’s future
is a wasm_bindgen_futures::JsFuture wrapping a Promise, which is not.
Implementing the bare EventStore once is what lets the same source
compile for the host and for wasm32-unknown-unknown.
Note precisely what that claims. store.rs:17-18 states the implication in
one direction only:
impl SendEventStore ==> EventStore comes free
impl EventStore =/=> SendEventStore (cannot conjure Send)So this crate compiles for both targets implementing the bare flavour on
each. It does not satisfy SendEventStore on either target, including
the host, even when the transport happens to be Send — the impl is written
once, on the weaker trait, and there is no way back up.
Both halves of that were compiled rather than reasoned about. Asserting
NeonEventStore<NullTransport>: SendEventStore gives
error[E0277]: the trait bound … is not satisfied. Trying to fix that by
adding a second impl — impl<T: SqlTransport + Send + Sync> SendEventStore for NeonEventStore<T> alongside the bare one — gives
error[E0119]: conflicting implementations of trait EventStore, naming
trait_variant’s blanket impl<T: SendEventStore> EventStore for T. The two
flavours are therefore mutually exclusive per type, not a lattice an
adapter can sit at two points of.
§The schema
Authoritative in migrations/0001_neon_log.sql, rendered by
crate::migration. It is not restated here: a prose copy of a schema is a
copy that drifts, and this module used to carry one that had drifted into
saying bigserial with no origin columns, no recorded_at and no xact_id.
What is worth reading before the file: position carries no column
default and is not bigserial; the sequence is read explicitly at the one
INSERT that allocates; and each row stamps pg_current_xact_id() into an
xid8 column, which is the mechanism every read and head filter on.
§ES-10, and what this adapter pays for it
ES-10 says position order is visibility order: once a reader has seen position
P, nothing at or below P may appear later. nextval() allocates outside
the transaction, so a naive store breaks it — a writer takes 99, a writer that
started later takes 100 and commits first, and a reader who conditioned on
after: Some(100) never sees the 99 that would have violated its boundary.
This adapter buys the invariant the same way happenstance-postgres does, on
ADR-0024’s prior authority, and re-measured against this endpoint rather
than inherited from it — because that ADR’s staleness numbers were taken
against a dedicated container and this is a shared Neon branch carrying a
pooler and Neon’s own compute processes, either of which could hold
pg_snapshot_xmin back. Ten append-then-read cycles against the live
endpoint: the frontier had already passed the appended position on the first
read, ten of ten. The round trip is 80-100 ms and the frontier’s own lag is
sub-millisecond, so the margin is three orders of magnitude, which is a
different situation from the Postgres adapter’s and is worth saying rather
than assuming.
What follows for a caller, unsoftened: head reports a
frontier rather than the highest position assigned, and
read-your-own-writes is not promised. Both are capability limits rather
than defects.
§The append is two statements, and that is not a regression
This module used to document a single WITH probe AS (…) , ins AS (…) CTE,
on the argument that one statement is one snapshot. The argument was right
and the conclusion was wrong, because of a fact about the endpoint rather
than about SQL: Neon-Batch-Isolation-Level is honoured on a request carrying
two or more statements and ignored on the single-statement form. Both
halves are measured — current_setting('transaction_isolation') answers
serializable in a two-statement batch carrying the header and
read committed in a one-statement request carrying the same header.
A single CTE therefore runs at READ COMMITTED, where two racers both find
no conflict and both insert. That is the lost update this crate’s
ProbeThenWriteStore exists to name, arriving through the door left open
while the other one was being closed. So the conditional append is a
two-statement non-interactive batch: a probe that reports the conflicting
position, and a guarded INSERT … WHERE NOT EXISTS, both on one
SERIALIZABLE snapshot in one round trip. conflicting_position survives,
which is what the CTE was for.
ProbeThenWriteStore is a deliberately lost-update store, so it is compiled
for this crate’s unit tests and nowhere else (wi-17ec03). Neither path to
it resolves from outside:
use happenstance_neon::ProbeThenWriteStore;use happenstance_neon::event_store::ProbeThenWriteStore;Stable rustdoc does not check a compile_fail error code, so either block
above would pass on any error. The same two paths to the real store
compile, so the missing name is what fails above:
use happenstance_neon::NeonEventStore;
use happenstance_neon::event_store::NeonReadStream;Measured at 64 simultaneous contenders on one boundary against the live
endpoint, six runs: exactly one commit and sixty-three
ConditionViolated every time, and no contender needing more than one retry.
That measurement is real and it is not what sets the retry count, which is
worth saying because taking it at face value is how this adapter shipped a
number that failed half its runs. Contenders on disjoint boundaries do not
drain the way contenders on one boundary do: the SSI predicate lock is
relation-wide on a small table, so a retry that finds no conflict on its own
boundary goes straight back into the same fight.
NeonEventStore::SERIALISATION_ATTEMPTS carries both numbers and the table
that decides between them.
Structs§
- Neon
Event Store - An event store over Neon’s serverless
/sqlHTTP endpoint. - Neon
Read Stream - The read “stream”: one round trip, then a buffer being drained.
- Neon
Sync Peer sync - A
SyncPeerover aNeonEventStore: one SQL request per pull and one per push.
Enums§
- Neon
Peer Error sync - How a
NeonSyncPeerfails: the store’s error, the ingest’s refusal, or a push over the limits it declared.