Expand description
The projection store port.
§Status: frozen, and how that was earned
Like EventStore, this port is frozen and inside
the crate’s semver promise, since ADR-0063. It was not, from 0.2.0 until
that decision: it shipped behind an off-by-default unstable-projection
feature with a written exemption, and the reason it did is worth keeping
here because it is the reason the freeze means something now.
The bar the specification set (PS-2) was not a count of adapters but a
spread: the suite green against two adapters at opposite ends of the
batch-shape axis — one whose batch is an owned write set replayed at commit,
and one whose batch is a live transaction. Every implementation there had
ever been sat at the first end, and ADR-0060 found the second was not merely
unbuilt but unreachable through this port’s own signatures: begin was
total, synchronous and infallible while every route to a real driver’s
transaction is async and fallible; and the probe seam the suite drives a
read model through was synchronous, infallible and took &Self::Batch,
while a driver borrows its connection mutably to issue a statement. A
live-transaction store could implement the port only by declaring
READS_THROUGH_BATCH = false — a false statement about itself — so the
suite could not tell the two ends apart. A skeleton did not report any of
this because todo!() has type ! and coerces to anything.
ADR-0062 moved those signatures: begin is async and fallible, and the
three batch-touching probe members take &mut Self::Batch and return a
future of a Result. happenstance-postgres then built the far end — a
store whose batch is a sqlx::Transaction, declaring READS_THROUGH_BATCH = true truthfully — and it passed all seventeen rules against a live server,
with PS-12’s read-through rule reported as a run rather than a skip for the
first time on any adapter over a real database. The two ends disagreed about
nothing the port had to move for. That is the measurement PS-2 asked for,
and ADR-0063 is the freeze taken on it.
What is frozen is this port. The runner over it has its own axis: the
typed layer’s Projection::apply is async since ADR-0074 was built, so it
can issue a statement into a live batch, and the runner sat behind
happenstance’s own unstable-projection until 0.5.0 removed it. Neither
fact moved this port.
Changing a signature here is now a breaking change with a decision record behind it, which is what frozen means in this workspace.
§The invariant that drives the design
A read model and its checkpoint must move together. If the read-model write commits and the checkpoint write does not, a restart replays events that were already applied; if the checkpoint commits first, a crash silently skips events. Neither is acceptable, and no amount of ordering or retrying fixes it — the two writes must be one transaction.
So the port cannot offer apply() and set_checkpoint() as independent
calls. It hands out an adapter-owned batch and takes it back at commit time
together with the position.
§What is out of scope at 0.1: a projection that writes back into the log
A projection that emits events into the event store as a side effect of
applying one is out of scope for this port at 0.1, and this paragraph is
the port saying so rather than leaving it to be discovered
(spec/SPECIFICATION.md §4’s PS-31).
It is a consequence of a decision already taken, not a question still open.
An EventId is a store-assigned (StoreId, SequencePosition) pair minted at
append (VT-5), and EventStore::append refuses a
caller-supplied one (VT-10). An outward-writing projection needs exactly what
VT-10 refuses: a write whose identity the caller chooses, so that a rebuild
re-emitting the same event is a no-op rather than a second fact. Without that,
every rebuild duplicates every emitted event, which is the wrong
implementation silence here produces. Revisiting it means a deliberate
idempotent-emission seam, and VT-5 is what would make one expressible.
§The batch is owned, and is not required to be a live transaction
ProjectionStore::Batch is a plain associated type with no lifetime
parameter. It used to be a generic associated type borrowing from the
store, on the reasoning that a transaction cannot outlive its connection.
Two compiled results retired that shape and neither is about Send: the
error[E0195] every impl hit, written out once beside the doctest that
disposes of it in # Implementing it,
and a store carrying a lifetime of its own, which made rustc 1.97.1 ICE
while reporting the region error the GAT’s where Self: 'a produced. A
batch may still be a live transaction — the port stops requiring one,
which is what lets an adapter with no connection at all implement it.
§The Send flavour’s extra requirement is documented, not declared
SendProjectionStore transitively requires Batch: Send, because the
batch crosses an await between begin and
commit. That bound cannot be written on the
associated type: trait_variant copies associated-type bounds verbatim
into the bare flavour, so type Batch: Send; would impose Send on the
flavour that exists precisely for wasm32, where nothing is. A caller who
needs a spawnable runner writes S::Batch: Send in their own where
clause.
Projections that cannot be made transactional with their checkpoint must instead be made idempotent, so that replaying an event is harmless. That is a property of the projection, not of this port.
§Naming what the port hands back
use happenstance_core::{
Authority, Checkpoint, CommitError, ProjectionId, ResetError, SequencePosition,
};
// Every state the port can report is one a caller can name.
let checkpoint = Checkpoint::Live {
through: SequencePosition::FIRST,
};
assert!(matches!(checkpoint, Checkpoint::Live { .. }));
// `commit` and `reset` fail differently, so a caller matching one is never
// offered the other's arms.
let refused: ResetError<core::convert::Infallible> = ResetError::Refused;
let foreign: CommitError<core::convert::Infallible> = CommitError::ForeignBatch;
assert!(matches!(refused, ResetError::Refused));
assert!(matches!(foreign, CommitError::ForeignBatch));
let _rebuild = (ProjectionId::from_static("van_stock"), Authority::Rebuilding);Structs§
- Projection
Id - Names a read model within a projection store.
Enums§
- Authority
- What a commit claims about the rows it leaves behind.
- Checkpoint
- Where a projection has been brought to, and whether its rows can be trusted.
- Commit
Error - Why a
commitfailed. - Invalid
Projection Id - A
ProjectionIdfailed validation (VT-35). - Reset
Error - Why a
resetfailed.
Constants§
- MAX_
PROJECTION_ ID_ LEN - Longest permitted projection identifier, in bytes.
Traits§
- Projection
Probe conformance - The write seam the projection conformance suite runs through.
- Projection
Store - A store that holds read models and their replay checkpoints.
- Send
Projection Store - A store that holds read models and their replay checkpoints.