Skip to main content

Crate happenstance_core

Crate happenstance_core 

Source
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

ConcernType
What happenedEvent, EventType, Tag, Tags
Where it sits in the logSequencePosition, SequencedEvent
What to readQuery, QueryItem, ReadOptions
What must not have changedAppendCondition
Storage seamsEventStore, 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) — the MemoryEventStore and MemoryProjectionStore reference implementations. Implies std.

  • serde — Serialize/Deserialize for the wire types. Off by default so the contract crate carries no serialisation opinion; enabled by replication adapters that need one.

  • unstable-projection — removed in 0.4.0. From 0.2.0 to ADR-0063 it held the ProjectionStore port out of the semver promise, for the reason the projection module header records; from ADR-0063 to 0.4.0 it was declared empty, so a 0.2.0 manifest kept resolving. The port is unconditional and frozen, and a manifest that still names the feature fails to resolve — the break 0.4.0 was 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 — not std and not memory. It implied unstable-projection until 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, and cargo doc --no-default-features is 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;conformance
pub use bytes;
pub use futures_core;

Modules§

projection
The projection store port.
store
The event store port, in two flavours.

Structs§

AppendCondition
The consistency boundary an append is checked against.
ConditionViolated
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.
EventParts
The owned pieces of an Event, from Event::into_parts.
EventType
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.
MemoryEventStorememory
The reference implementation of EventStore.
MemoryProjectionBatchmemory
An in-flight write against a MemoryProjectionStore.
MemoryProjectionStorememory
The reference implementation of ProjectionStore.
QueryItem
One clause of a Query.
ReadOptions
How to traverse the matched events.
RecordedAt
When the store accepted an event: milliseconds since the Unix epoch, UTC.
SequencePosition
An event’s place in the store’s total order.
SequencedEvent
An Event together 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§

AppendError
Why an append failed.
InvalidEventType
An EventType failed validation.
InvalidQuery
A Query or QueryItem failed validation.
InvalidTag
A Tag failed validation.
MemoryProjectionStoreErrormemory
MemoryProjectionStore’s error type, which is uninhabited.
MemoryStoreErrormemory
MemoryEventStore’s error type, which is uninhabited.
Query
A filter over the log.
StoreLimit
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 data payload 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.