Skip to main content

Module projection

Module projection 

Source
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§

ProjectionId
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.
CommitError
Why a commit failed.
InvalidProjectionId
A ProjectionId failed validation (VT-35).
ResetError
Why a reset failed.

Constants§

MAX_PROJECTION_ID_LEN
Longest permitted projection identifier, in bytes.

Traits§

ProjectionProbeconformance
The write seam the projection conformance suite runs through.
ProjectionStore
A store that holds read models and their replay checkpoints.
SendProjectionStore
A store that holds read models and their replay checkpoints.