Expand description
The happenstance contract: DCB-compliant event sourcing types and storage ports.
This crate defines what an event store is and nothing about how one is built. It holds no I/O, opens no connections, and takes no opinion on serialisation. Everything else in the happenstance ecosystem — SQLite, Postgres, replication — depends on it, so it is deliberately the smallest and most stable crate in the workspace.
It implements the Dynamic Consistency Boundary specification.
§DCB in a paragraph
Classical event sourcing draws consistency boundaries ahead of time, as aggregates, and every decision must fit inside one. DCB draws them per decision instead. A command handler reads whatever events it needs — across any number of entities — and then appends conditioned on nothing matching that same query having appeared since. The boundary is whatever the handler actually looked at, so invariants that span entities stop requiring either an oversized aggregate or a saga.
§The shape of the API
| Concern | Type |
|---|---|
| What happened | Event, EventType, Tag, Tags |
| Where it sits in the log | SequencePosition, SequencedEvent |
| What to read | Query, QueryItem, ReadOptions |
| What must not have changed | AppendCondition |
| Storage seams | EventStore, ProjectionStore |
§Design notes
Illegal states are unrepresentable. Query is an enum rather than a
vector because the specification permits “at least one item” or “match
everything” and nothing else. SequencePosition wraps a NonZeroU64,
so position zero cannot exist and Option<SequencePosition> costs no extra
space. Tags is canonically sorted at construction, so it can never be
observed out of order.
Payloads are opaque. Event::data is Bytes with no
serde bound in sight. Adapters stay free of domain knowledge, and
replication can forward an event byte-for-byte without deserialising it.
Encoding is a job for the layer above.
The concurrency signal is in the type system. An append returns
AppendError, which separates ConditionViolated — routine under
contention, and a cue to retry — from adapter-specific failures. No caller
has to match on a string to tell them apart.
There are two flavours of each port. EventStore carries no Send
bound so it can be implemented on wasm32; SendEventStore is derived
from it for native use. Implementing the latter gives you the former. See
the store module documentation for the full rationale.
§Getting started
Enable the memory feature (on by default) and use MemoryEventStore — see
its documentation for a runnable walkthrough of the read-decide-append loop.
MemoryProjectionStore is its projection-side twin, and its page carries a
runnable begin → write → commit → read-back walkthrough of its own.
Neither name is a link here. It would be a broken one whenever memory is
off, and cargo doc --no-default-features treats a broken intra-doc link as a
hard error rather than a warning (D13).
§Feature flags
-
std(default) — standard library support. -
memory(default) — theMemoryEventStoreandMemoryProjectionStorereference implementations. Impliesstd. -
serde—Serialize/Deserializefor the wire types. Off by default so the contract crate carries no serialisation opinion; enabled by replication adapters that need one. -
unstable-projection— removed in0.4.0. From0.2.0to ADR-0063 it held theProjectionStoreport out of the semver promise, for the reason theprojectionmodule header records; from ADR-0063 to0.4.0it was declared empty, so a0.2.0manifest kept resolving. The port is unconditional and frozen, and a manifest that still names the feature fails to resolve — the break0.4.0was the release to make. -
conformance—ProjectionProbe, the write seam the projection conformance suite drives an adapter’s read model through. For adapter authors running that suite against their own store; nothing in the runtime path needs it. Off by default, pulls in no dependency, and implies no other feature — notstdand notmemory. It impliedunstable-projectionuntil ADR-0063, because the module it lives in was gated then; it is not gated now, and that feature is gone.The name is deliberately not a link here: a link into a
cfg-gated item is a hard error when the feature is off, andcargo doc --no-default-featuresis a gate step.
Re-exports§
pub use store::EventStore;pub use store::SendEventStore;pub use store::collect;pub use store::read_decision_model;pub use projection::Authority;pub use projection::Checkpoint;pub use projection::CommitError;pub use projection::InvalidProjectionId;pub use projection::MAX_PROJECTION_ID_LEN;pub use projection::ProjectionId;pub use projection::ProjectionStore;pub use projection::ResetError;pub use projection::SendProjectionStore;pub use projection::ProjectionProbe;conformancepub use bytes;pub use futures_core;
Modules§
- projection
- The projection store port.
- store
- The event store port, in two flavours.
Structs§
- Append
Condition - The consistency boundary an append is checked against.
- Condition
Violated - The specification-defined outcome of an append that was rejected because the
store already held an event matching the
AppendCondition. - Event
- An event on its way into the store.
- EventId
- A store-assigned event identity: which store first accepted the event, and at what position it did so.
- Event
Parts - The owned pieces of an
Event, fromEvent::into_parts. - Event
Type - The identifier a store filters on:
CourseDefined,StudentSubscribed, and so on. - Guard
- One clause of an
AppendCondition: a query and the boundary it is checked from. - Memory
Event Store memory - The reference implementation of
EventStore. - Memory
Projection Batch memory - An in-flight write against a
MemoryProjectionStore. - Memory
Projection Store memory - The reference implementation of
ProjectionStore. - Query
Item - One clause of a
Query. - Read
Options - How to traverse the matched events.
- Recorded
At - When the store accepted an event: milliseconds since the Unix epoch, UTC.
- Sequence
Position - An event’s place in the store’s total order.
- Sequenced
Event - An
Eventtogether with the three facts its store assigned it. - StoreId
- Identifies one incarnation of a store’s persistent state.
- Tag
- A single domain-specific label attached to an
Event. - Tags
- A canonical set of
Tags: always sorted, always deduplicated.
Enums§
- Append
Error - Why an append failed.
- Invalid
Event Type - An
EventTypefailed validation. - Invalid
Query - A
QueryorQueryItemfailed validation. - Invalid
Tag - A
Tagfailed validation. - Memory
Projection Store Error memory MemoryProjectionStore’s error type, which is uninhabited.- Memory
Store Error memory MemoryEventStore’s error type, which is uninhabited.- Query
- A filter over the log.
- Store
Limit - Which capacity limit an append exceeded.
Constants§
- MAX_
EVENT_ TYPE_ LEN - Longest permitted event type, in bytes.
- MAX_
TAG_ LEN - Longest permitted tag, in bytes.
- MIN_
SUPPORTED_ EVENTS_ PER_ BATCH - Smallest number of events in one append every store must accept.
- MIN_
SUPPORTED_ EVENT_ DATA_ LEN - Smallest
datapayload every store must accept, in bytes. - MIN_
SUPPORTED_ QUERY_ ITEMS - Smallest number of query items every store must be able to evaluate.
- MIN_
SUPPORTED_ TAGS_ PER_ BATCH - Smallest total number of tags, summed over every event of one append, every store must accept (VT-36).
- MIN_
SUPPORTED_ TAGS_ PER_ EVENT - Smallest number of tags on one event every store must accept.