Skip to main content

Module event_store

Module event_store 

Available on crate feature 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§

NeonEventStore
An event store over Neon’s serverless /sql HTTP endpoint.
NeonReadStream
The read “stream”: one round trip, then a buffer being drained.
NeonSyncPeersync
A SyncPeer over a NeonEventStore: one SQL request per pull and one per push.

Enums§

NeonPeerErrorsync
How a NeonSyncPeer fails: the store’s error, the ingest’s refusal, or a push over the limits it declared.