Crate happenstance_neon
Expand description
Neon serverless Postgres adapters for happenstance, over the one-shot /sql
HTTP endpoint.
§Status
Implemented, and run rather than asserted: the conformance suite passes
against a live Neon endpoint (PostgreSQL 18.6 behind the pooler), event
store and projection store both, including the concurrency family at
CONTENDERS = 64.
This crate shipped in 0.2.0. The release set was five, decided, and the
owner re-opened it on the evidence at e597c34; the manifest carries no
publish key. This paragraph asserted the opposite until the release pass,
which would have told a docs.rs reader that the crate they were reading was
unpublished.
From 0.4.0 it meets ES-11 and ES-12, which it failed intermittently
before: a read and an append are two independent HTTP requests, and nothing
the store honours ordered them. SqlTransport::reads_settled is now a
required method, and append waits on it until every read the same
transport sent earlier has been answered — an answer follows execution,
so the read’s snapshot precedes the write (ADR-0087). The ordering domain is
one transport value: two transports are not ordered against each other, and
that is the claim’s stated limit. The README carries the account.
It also declines READ_YOUR_OWN_WRITES in its conformance fixture, which
is a different limitation with a different cause: the endpoint is PostgreSQL,
so a read carries the same xact_id < pg_snapshot_xmin(…) visibility frontier
happenstance-postgres documents, and that would hold over a direct
connection too. ES-11 is about the transport; this is about the server.
What a dropped append future does here is answered in
event_store’s # Cancellation section (unlinked: it needs event-store), which ES-23 obliges this
adapter to carry. The short version: it MAY already have committed, and this
crate owns no client that could tell you.
§It owns no HTTP client, and that is still true
SqlTransport is a two-method trait and NullTransport is the only
implementation in src/. See the transport module for why: a real client
needs a TLS stack on the host and wasm-bindgen’s fetch on wasm32, they
are two different clients, and neither is what this crate is here to prove.
The conformance suite reaches the live endpoint through a hyper + rustls
transport that lives in tests/, as a [dev-dependencies] and never as a
feature. That distinction is load-bearing rather than tidy: cargo xtask ci
runs cargo hack check -p happenstance-neon --target wasm32-unknown-unknown --feature-powerset --no-dev-deps, a feature is not target-scoped, and a
live-transport feature would therefore be switched on for wasm32 and fail
to build. Dev-dependencies are invisible to that powerset and to the MSRV
job’s --no-dev-deps check, so the client reaches no consumer’s graph, no
feature combination and no licence surface.
What that still costs is recorded honestly: the crate demonstrates a
licence-clean client for the host, and not for wasm32. The shape above
it does not need to know which one it has.
§What this adapter is an instrument for
It is deliberately the least capable store in the workspace, and it is in
the tree to sit at the far end of the transport axis from MemoryEventStore,
a RefCell store, rusqlite and a Durable Object — all of which serialise
their writers behind a lock and can hold a transaction open across a decision.
Neon’s /sql endpoint can do none of that:
| connection | none — every request is authenticated and routed on its own |
| transaction handle | none — no BEGIN that a later request can join |
| cursor | none — a result set is one buffered JSON document |
| round trips | exactly one per operation |
| response cap | 64 MiB, hard (MAX_RESPONSE_BYTES) |
The one thing it does offer is a non-interactive transaction: an array
of statements executed server-side inside one BEGIN/COMMIT, at a chosen
isolation level, in a single round trip. Atomic, and unable to branch. Every
capability limit below follows from that distinction.
§The trap this crate exists to spring
An append that probes for a condition violation and then writes, in two
round trips, type-checks against
EventStore perfectly.
ProbeThenWriteStore is that implementation, written out in full and compiled
only for this crate’s tests, so the compiling call site can be pointed at. It is
also silently wrong here: two round trips are two implicit transactions, with a
network-latency-wide window between them and no snapshot spanning it. A conflicting
append committed inside that window is invisible to the probe and unopposed by the insert.
A shape table that recorded only error[E….] would therefore rank this crate
the most compatible adapter in the workspace. It is the least. The limits that
matter here are not type errors.
§Can the condition and the write collapse into one statement?
Yes, and it must not. This is the one place where the crate’s own recorded answer was overturned by a measurement rather than by an argument, so the old answer is stated before the new one.
It used to say: a single CTE computes the probe and the insert on one snapshot
and projects both, so ConditionViolated::conflicting_position survives the
collapse — one statement, one round trip, one snapshot. Every word of that is
true of SQL. It is false of this endpoint, because
Neon-Batch-Isolation-Level is honoured only on a request carrying two or
more statements. Both halves are measured against the live endpoint:
current_setting('transaction_isolation') answers serializable inside a
two-statement batch carrying the header, and read committed inside a
one-statement request carrying the same header.
So the single CTE runs at READ COMMITTED, where two racers both find no
conflict and both insert — the lost update ProbeThenWriteStore exists to
name, arriving through the door left open while the other one was being
closed. The append is therefore a two-statement batch: a probe that
reports the conflicting position, and a guarded INSERT … WHERE NOT EXISTS,
on one SERIALIZABLE snapshot in one round trip.
Two statements in one request is safe; two round trips is not. That sentence
is the whole of this adapter’s append design, and the event_store module
carries the measurement behind it.
§After a branch or a restore, re-mint before the first append
This store’s identity, the StoreId half of every EventId it mints, is
one row that migration 1 writes once. A Neon branch that is created, reset
or restored, like a pg_restore or a point-in-time recovery, carries its
parent’s identity together with an older position sequence, and would then
re-issue EventIds the parent has already issued, which replication drops
silently (VT-6). Stop every writer to the copy, then re-mint it with
NeonEventStore::remint_identity, or run
migration::remint_statement’s text against it from the tooling that
makes the branch. For the default NeonConfig that text is:
UPDATE "public"."store_meta" SET v = uuid_send(gen_random_uuid()) WHERE k = 'store_id' RETURNING encode(v, 'base64') AS store_idThen resume appends. No restart is needed: every append reads the row inside
its own statement, and inserts nothing, refusing with
NeonError::MissingIdentity, when the row is absent. An ingest refuses the
same way and writes neither the foreign events nor their compensation.
ADR-0086 §7.2 proposed a join against the meta row inside the shared stamp,
so that an absent row yields zero rows. That stamp also writes an ingest’s
compensation, where a join would drop the compensation silently and leave
the foreign event it answers committed alone. So the stamp stays a scalar
subquery, and each writer that uses it is guarded by an EXISTS on the same
row in the same statement instead: an append inserts nothing without it, and
an ingest gates its compensation on it and is refused whole by its second
statement. A branch is made by
the platform’s control plane rather than by this crate, so put the statement
in whatever tooling makes branches. Minting afresh on every open was
considered and declined (ADR-0086): a Workers deployment builds a store per
request, and would mint an identity per request.
§Which flavour, and which claim
NeonEventStore implements the bare
EventStore, and NeonProjectionStore the
bare ProjectionStore. The crate compiles for the host target and for
wasm32-unknown-unknown, implementing
the bare flavour on each. That is not the same claim as satisfying both
flavours: the contract crate’s implication table runs one way only, so nothing
here satisfies SendEventStore, on either target, even where the transport
happens to be Send.
Re-exports§
pub use config::NeonConfig;pub use error::NeonError;pub use error::NeonSqlError;pub use transport::HttpResponse;pub use transport::IsolationLevel;pub use transport::MAX_RESPONSE_BYTES;pub use transport::NullTransport;pub use transport::NullTransportError;pub use transport::ReadLedger;pub use transport::ReadTicket;pub use transport::ReadsSettled;pub use transport::SqlRequest;pub use transport::SqlStatement;pub use transport::SqlTransport;pub use event_store::NeonEventStore;event-storepub use event_store::NeonReadStream;event-storepub use projection_store::NeonProjectionStore;projection-storepub use projection_store::NeonWriteBatch;projection-storepub use event_store::NeonPeerError;syncpub use event_store::NeonSyncPeer;syncpub use happenstance_core;pub use serde_json;pub use happenstance_sync;sync
Modules§
- config
- Where the tables live, and how much of a response the adapter will accept.
- error
- How a Neon-backed store fails.
- event_
store event-store - The Neon-backed
EventStore, and the buffered thing it calls a stream. - migration
- The schema, rendered for one
NeonConfigand split into statements. - projection_
store projection-store - The Neon-backed
ProjectionStore, and the batch that is not a transaction. - transport
- The one-shot SQL-over-HTTP transport seam.
- wire
- The JSON the
/sqlendpoint answers with.