Skip to main content

Crate happenstance_neon

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:

connectionnone — every request is authenticated and routed on its own
transaction handlenone — no BEGIN that a later request can join
cursornone — a result set is one buffered JSON document
round tripsexactly one per operation
response cap64 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_id

Then 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-store
pub use event_store::NeonReadStream;event-store
pub use projection_store::NeonProjectionStore;projection-store
pub use projection_store::NeonWriteBatch;projection-store
pub use event_store::NeonPeerError;sync
pub use event_store::NeonSyncPeer;sync
pub 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_storeevent-store
The Neon-backed EventStore, and the buffered thing it calls a stream.
migration
The schema, rendered for one NeonConfig and split into statements.
projection_storeprojection-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 /sql endpoint answers with.