Trait ProjectionFixture
pub trait ProjectionFixture {
type Store: ProjectionProbe;
const SECOND_HANDLE: Capability = _;
const RESET_REFUSAL: Capability = _;
const COMMIT_FAULT: Capability = _;
const REOPEN: Capability = _;
// Required method
fn connect(&self) -> impl Future<Output = Self::Store>;
// Provided methods
fn reopen(&self) -> impl Future<Output = Reopened> { ... }
fn arm_commit_fault(&self) -> impl Future<Output = ()> { ... }
fn protect_from_reset(&self, id: &ProjectionId) -> impl Future<Output = ()> { ... }
}Expand description
One isolated projection store, plus the ways a projection rule is allowed to reach it.
Fixture’s sibling, and a second trait rather than a second associated
type on the first, because Fixture::Store binds EventStore — the
wrong port. An adapter may implement one of the two ports and not the other,
and a single trait would oblige a projection-only adapter to invent an event
store to satisfy a bound no projection rule reads.
Implement it for whatever a rule should be given a fresh instance of: a
temporary directory holding a SQLite file, a connection pool aimed at a
throwaway schema, a MemoryProjectionStore behind an Arc. Each instance is
one store. Each connect is one handle onto it.
§Why Store is bound on the probe rather than on the port
ProjectionProbe is the write seam the suite drives an adapter’s read
model through, and it is a supertrait of ProjectionStore — so one bound
buys both. Binding the port instead would compile and would quietly buy a
suite that cannot see a read model at all: with ProjectionStore alone, the
only things generic code can do with a batch are commit it and roll it back,
and the rule carrying this port’s entire reason for existing degenerates into
a checkpoint test that a store writing only checkpoints passes.
Binding the probe here is what turns “your store must be observable” from a
convention into a compile error: an adapter that has not implemented
ProjectionProbe cannot name a type that satisfies this trait, so it
cannot invoke the suite, and by CLAUDE.md’s rule it does not exist.
§No Send bound, and no trait_variant
The bare flavour, never SendProjectionStore: it is the weaker requirement
and accepts both kinds of adapter, and only one of the two names may be in
scope per module. Nothing ever spawns a fixture — the harness owns the
executor — so the argument that gives the port two flavours (ADR-0001) does
not reach here, and a second flavour would double the surface to buy a
property no caller wants.
§Why the methods are spelled -> impl Future rather than async fn
Fixture’s reason, unchanged: async fn in a public trait fires rustc’s
async_fn_in_trait lint and the gate runs -D warnings. The desugared form
also puts the absence of + Send at the declaration, where a reader can
see it. An implementation may still write async fn — the two are the same
signature after desugaring, and the lint fires only on the declaration.
§Why Store is an owned associated type and not a GAT
The same rustc ICE Fixture records, for the same five ingredients, still
reproducing on 1.97.1 (experiments/rustc-ice-gat-foreign-trait/). Hand back
an owned handle holding a refcount;
MemoryProjectionFixture is the
worked example.
§Capability constants, and where an empty reason fires
Four constants, all answered deliberately:
SECOND_HANDLE is a MUST, and
RESET_REFUSAL,
COMMIT_FAULT and REOPEN are the
port’s genuinely declinable capabilities. A declined one must name a reason —
Capability::declined rejects the empty string in a const fn assert!
— but on an associated const that rejection arrives later than one would
like. An associated const is evaluated lazily, only when monomorphised code
reads it, which is after cargo check and cargo clippy have both
stopped. It fails at codegen, so cargo build and cargo test catch it
and cargo check and cargo clippy do not — a green check is not
evidence here.
This is that failure, and reading the constant is the load-bearing line: a fixture nobody ever looks at compiles perfectly well.
use happenstance_core::MemoryProjectionStore;
use happenstance_testkit::fixtures::MemoryProjectionHandle;
use happenstance_testkit::{Capability, ProjectionFixture};
struct Reasonless(std::sync::Arc<MemoryProjectionStore>);
impl ProjectionFixture for Reasonless {
type Store = MemoryProjectionHandle;
const SECOND_HANDLE: Capability = Capability::SUPPORTED;
// The whole difference from the block below.
const RESET_REFUSAL: Capability = Capability::declined("");
const COMMIT_FAULT: Capability = Capability::declined(
"this store cannot make a commit fail once it has been accepted",
);
const REOPEN: Capability = Capability::declined(
"this store keeps everything in process memory, so a reopen has \
no medium to read back from",
);
fn connect(&self) -> impl core::future::Future<Output = Self::Store> {
core::future::ready(MemoryProjectionHandle::new(std::sync::Arc::clone(&self.0)))
}
}
fn main() {
let _ = <Reasonless as ProjectionFixture>::RESET_REFUSAL;
}The doctest above is spelled bare compile_fail, never
compile_fail,E0080: rustdoc on 1.97.1 silently ignores an error-code
annotation it cannot match, so the stricter-looking spelling is the weaker
check (Capability::declined records the measurement).
Bare compile_fail passes when the snippet fails to compile for any
reason, so the twin below is what makes the pair sound. It is the same
snippet with one expression changed — the empty string becomes a sentence —
and it must compile. A typo, a renamed item or a wrong path breaks the twin,
and a broken twin is a hard test failure, so the only thing the pair can be
reporting is the one expression that differs between them.
use happenstance_core::MemoryProjectionStore;
use happenstance_testkit::fixtures::MemoryProjectionHandle;
use happenstance_testkit::{Capability, ProjectionFixture};
struct Reasoned(std::sync::Arc<MemoryProjectionStore>);
impl ProjectionFixture for Reasoned {
type Store = MemoryProjectionHandle;
const SECOND_HANDLE: Capability = Capability::SUPPORTED;
const RESET_REFUSAL: Capability = Capability::declined(
"this store holds no protection policy, so there is no projection it \
could decline to reset",
);
const COMMIT_FAULT: Capability = Capability::declined(
"this store cannot make a commit fail once it has been accepted",
);
const REOPEN: Capability = Capability::declined(
"this store keeps everything in process memory, so a reopen has \
no medium to read back from",
);
fn connect(&self) -> impl core::future::Future<Output = Self::Store> {
core::future::ready(MemoryProjectionHandle::new(std::sync::Arc::clone(&self.0)))
}
}
let _ = <Reasoned as ProjectionFixture>::RESET_REFUSAL;§Examples
The whole trait, over the reference store — this is what
projection_store_conformance! is
handed:
use std::sync::Arc;
use happenstance_core::MemoryProjectionStore;
use happenstance_testkit::fixtures::MemoryProjectionHandle;
use happenstance_testkit::{Capability, ProjectionFixture};
struct MyFixture(Arc<MemoryProjectionStore>);
impl ProjectionFixture for MyFixture {
type Store = MemoryProjectionHandle;
const SECOND_HANDLE: Capability = Capability::SUPPORTED;
const RESET_REFUSAL: Capability = Capability::declined(
"this store protects nothing, so it has no reset to refuse",
);
const COMMIT_FAULT: Capability = Capability::declined(
"this store applies both halves of a commit under one lock and has \
no write it can be made to fail between them",
);
const REOPEN: Capability = Capability::declined(
"this store keeps its read model and checkpoints in process memory \
only, so there is no medium a reopen could read them back from",
);
fn connect(&self) -> impl core::future::Future<Output = Self::Store> {
core::future::ready(MemoryProjectionHandle::new(Arc::clone(&self.0)))
}
}Provided Associated Constants§
const SECOND_HANDLE: Capability = _
const SECOND_HANDLE: Capability = _
Whether this fixture can hand out a second, independent handle onto the one backing projection store.
This one is a MUST, as it is on Fixture, and for a sharper
reason. PS-1 — the read-model write and the checkpoint write become
durable together or not at all — is only observable from outside the
connection that made the commit: a store whose commit is visible only to
its own session satisfies every single-handle assertion and loses the
row, or the checkpoint, or both, the moment anything else looks. So
every rule in this family reads back through a fresh
connect, and a fixture that cannot open one cannot
observe the invariant this port exists for at all.
Declining it is therefore not a trade the suite may record as a skip
— it is a fixture that does not meet the contract — and the type cannot
tell the two apart, because both spell Capability.
§What enforces it
The rules themselves, through must! rather than require!, so the
enforcement is on the path an adapter’s own CI executes. An adapter
author who meets a red rule, writes
const SECOND_HANDLE: Capability = Capability::declined("…") and re-runs
gets a red rule again, quoting their own stated reason back at them — not
a green suite and one SKIP line. The second line is
mutation_coverage::projection_capability_skips_are_reported, which
drives the whole enumeration against a fixture declining everything and
asserts each of those rules rejects it.
It stays spelled as a Capability rather than as a bool so the
failure carries the fixture’s own words.
§Why a MUST is nevertheless defaulted
Every capability on this trait is defaulted, this one included, and the default is a declension: a fixture that says nothing is read as having answered “no”, never as having answered “yes”. A default may decline on an author’s behalf; it may never declare on their behalf, because a declaration is a promise about a store only that store’s author is in a position to make.
Nothing about the MUST is weakened by that, because the compiler was
never what enforced it. Requiredness bought an error[E0046] once, on
the day an author wrote their impl; must! inside every rule of this
family buys a red suite on every run, quoting the reason back, on
the path an adapter’s own CI executes. The second is the stronger of the
two and it is the one that was already there.
Silent in tests/projection_fixture_declension.rs holds both halves
of that paragraph honest: it writes not one capability constant, so it
stops compiling if any of the three goes back to being required, and it
is rejected by
commit_advances_the_checkpoint
rather than skipped by it.
const RESET_REFUSAL: Capability = _
const RESET_REFUSAL: Capability = _
Whether this fixture’s store can be made to refuse a reset for a projection it protects.
The projection port’s one genuinely declinable capability, and a real
trade rather than a fact: PS-18 makes refusal a mechanism the port
supplies and leaves what to protect to the domain, so a store with no
protection policy has nothing to refuse and declining is the honest
answer. MemoryProjectionStore is exactly that store, and
MemoryProjectionFixture
declines with the real reason.
§The policy that used to be stated here, and why it was retracted
This constant was required rather than defaulted, unlike
Fixture::MID_BATCH_FAULT, under a stated trait-level rule: a default
would have to carry a testkit-written reason, and the projection
family’s declension policy is that the fixture writes the reason — a
store’s account of a trade only it can describe. The rule is retracted.
Its argument is preserved above rather than deleted, because it is still
the reason an adapter author should override this constant, and it is
the cost the retraction accepts.
What it was measured against was the wrong precedent. The comparison it
drew was to NO_CEILING_REASON, and CF-40 governs a fact — an
Option<usize> ceiling, which that clause says MUST NOT be spelled as a
Capability because None there is not a trade. The on-point precedent
is CF-39, which governs MID_BATCH_FAULT: a genuine trade, of very
nearly this shape, defaulted on its trait, whose default reason is
written in the fixture’s own voice — and which recovers the honesty a
default gives up as a clause-level MUST rather than as requiredness.
A rule stated in one doc paragraph and contradicted by the specification’s
treatment of its nearest neighbour is the thing that owed an argument.
The direct measurement of what requiredness buys runs the other way too.
Fixture::REOPEN is required; NoopReopenFixture in
experiments/suite-against-wrong-adapters/tests/support/wrong_fixtures.rs
answers it, falsely, and scores better than an honest fixture that
declines — 86 passed and 3 skipped against 83 passed and 6 skipped.
Requiredness compels a sentence; it does not compel a true one.
So the default below is the testkit’s, and it says only what the testkit
is in a position to know — that the fixture did not answer. An adapter
author who leaves it standing has a SKIP line in their CI log written
by somebody else, which is the whole of what this trade costs and is
worth overriding to avoid.
It is read by exactly one rule,
refused_reset_changes_nothing,
which is PS-18’s; a fixture that declines it gets that rule as a reported
skip carrying its stated reason, and a fixture that declares it must
also override protect_from_reset, which is
the mechanism this constant gates.
§What declaring it commits a fixture to
CF-43, CF-39’s shape for this capability: once
protect_from_reset has returned, every later
reset of that id through any handle answers ResetError::Refused, by a
mechanism inside the store’s own reset that the fixture states; a store
that refuses no reset declines. A forgotten override reaches the panic
below. An override that does nothing is the quieter mistake, and
refused_reset_changes_nothing rejects it at its first assertion, since
a store nobody protected answers Ok: NoopProtectFixture, in this
crate’s tests/projection_mutation_coverage/mutants.rs, is registered as
failing it. happenstance-sqlite is the first adapter to declare the
capability.
const COMMIT_FAULT: Capability = _
const COMMIT_FAULT: Capability = _
Whether this fixture can make a commit report failure.
PS-1’s second conjunct is a claim about a commit that failed: the read
model and the checkpoint must be exactly as they were. Nothing a caller
holds can make a conformant commit fail — that is the property under
test — so, exactly as with Fixture::MID_BATCH_FAULT, the injection
belongs to the adapter: a trigger that raises on the third row, a CHECK
armed for one write, a connection killed between the read-model write and
the checkpoint write. Every store that can do it does it differently,
which is what makes it a capability rather than testkit machinery.
§Why it was required, and why it is now defaulted
Fixture::MID_BATCH_FAULT carries a default declension and this one
deliberately did not, for RESET_REFUSAL’s
retracted reason: a default has to carry a testkit-written reason, and
this family’s declension policy was that the fixture writes it. “This
store has no ceiling” is the same sentence for every store that says it,
which is why NO_CEILING_REASON exists; why a particular store cannot
make a commit fail is not — an in-memory map applies both halves under
one lock, a one-shot HTTP backend has no interactive transaction to
abort, and a pooled adapter usually can. The cost was one line per
fixture and the return was that no fixture author was left un-asked.
That is still true, and it is still the reason to override this
constant. What it is not is a reason to make it required, and this
capability is the one where the difference is sharpest, because its
nearest relative — MID_BATCH_FAULT, a trade of the same shape, over
the same kind of adapter-supplied injection — was decided the other way
in the specification, defaulted, with CF-39 carrying the honesty as
a clause-level MUST. The section below is this port’s copy of that MUST,
and it was already here before the default was: requiredness was never
the thing holding this line.
§What declaring it commits the fixture to
failed_commit_leaves_both_unchanged
arms the fault and requires the next commit to answer Err. A fixture
whose arm_commit_fault does nothing would
otherwise turn that rule into a green result about a store nothing ever
faulted, which is CF-39’s argument one port over. So a store that can
absorb every fault its fixture is able to arm MUST decline this
capability with that as its stated reason, rather than declare it and
contribute an Ok.
const REOPEN: Capability = _
const REOPEN: Capability = _
Whether this fixture can be reopened: every outstanding handle’s
process-level state discarded, so that a later
connect observes only what was durably committed.
Fixture::REOPEN for the projection port, and CF-17 governs it in the
same words: a fixture declaring it supported MUST make
reopen discard that state over a medium that outlives
the process’s hold on it, and MUST state the mechanism — which file is
closed, which pool is drained. A fixture over a store with no medium
outside the process MUST decline it, with that as its stated reason.
It is read by exactly one rule,
committed_rows_and_checkpoint_survive_a_reopen,
which reads PS-1’s durable across a reopen: until it existed, no
projection rule showed that a committed read model and its checkpoint
outlive every handle that wrote them. A store that keeps either half in
process memory passes every other rule in the family, because every
other rule reads back through a handle onto the same live process.
§Why it is defaulted, unlike Fixture::REOPEN
Every capability on this trait is defaulted to a declension, for the
reason SECOND_HANDLE gives: a default may decline
on an author’s behalf, never declare. A fixture that inherits this
default is still told so, in its own CI, by
[assert_projection_declensions_are_stated].
§What declaring it does not prove
What Fixture::REOPEN does not: an override that answers
Reopened::Discarded over a volatile store and discards nothing is
indistinguishable, through the port, from an honest reopen over a file.
So the rule rejects a store that loses a commit across a reopen and
cannot reject a fixture that only claims to reopen. The declaration
MUST above is what carries that hazard, exactly as it does on the
event-store side.
Required Associated Types§
type Store: ProjectionProbe
type Store: ProjectionProbe
A handle onto this fixture’s backing projection store.
Bound on ProjectionProbe, which implies ProjectionStore — see the
trait documentation for why the probe is the bound that earns its keep
and the port is the one that does not.
Required Methods§
fn connect(&self) -> impl Future<Output = Self::Store>
fn connect(&self) -> impl Future<Output = Self::Store>
Opens a handle onto this fixture’s backing store.
Async because a real fixture acquires its handle over I/O — a pool
checkout, a connection, an HTTP client’s first request. A fixture whose
connect is a refcount bump should return core::future::ready
rather than an async move block, so it does not pretend to do I/O it
does not do.
§Panics
Implementations panic rather than returning Result, for
Fixture::connect’s reason and it is worth restating here rather than
linking: a fixture that cannot connect is a broken test environment,
not a non-conformant adapter, and a Result would put “the database is
down” into the same channel as “the adapter is wrong” — where the suite’s
own messages would then have to guess which one they were reading.
Provided Methods§
fn reopen(&self) -> impl Future<Output = Reopened>
fn reopen(&self) -> impl Future<Output = Reopened>
Closes and reopens the underlying storage, discarding every outstanding handle’s process-level state, and says whether it did.
After an override returns Reopened::Discarded, a fresh
connect must observe exactly what was durably
committed and nothing else. Handles obtained before the call may stop
working; a rule must not use one afterwards.
§The provided body says it reopened nothing
It returns Reopened::Nothing, and the rule asserts on that answer
before it reads anything back. A fixture that declares
REOPEN supported and forgets this override therefore
fails on every run, with a message naming this method.
This is Fixture::arm_held_above_frontier’s shape rather than
Fixture::reopen’s panicking provided body, and the difference is
deliberate: an answer the rule asserts on puts the failure in the rule,
where an adapter author’s CI reports it as that rule failing, and keeps
a panic out of this crate’s library code.
fn arm_commit_fault(&self) -> impl Future<Output = ()>
fn arm_commit_fault(&self) -> impl Future<Output = ()>
Arms the store so that the next commit fails.
The fault fires once, and where inside the commit it fires is the adapter’s business: what PS-1’s second conjunct requires is that a commit which reported failure left the read model and the checkpoint exactly as they were, whichever half the store had got to.
§Panics
The provided body panics, for
Fixture::arm_mid_batch_fault’s reason and with the same two ways of
reaching it: a fixture that declares COMMIT_FAULT
supported and forgets the override, or a rule that reached here without a
gate. That is what stops “declared and never implemented” from passing
vacuously — it aborts loudly instead.
fn protect_from_reset(&self, id: &ProjectionId) -> impl Future<Output = ()>
fn protect_from_reset(&self, id: &ProjectionId) -> impl Future<Output = ()>
Puts id under this store’s protection, so the next
reset of it is refused.
arm_commit_fault’s sibling, and it exists for
the same reason: the capability above is a claim, and a rule cannot
exercise the claim without telling the store which projection to
protect. Nothing a caller holds can make a conformant reset answer
ResetError::Refused —
PS-18’s own words are that the port supplies the mechanism and the domain
decides what to protect, so the domain is where the choice lives and a
fixture is how a suite reaches it.
It takes the ProjectionId rather than declaring a protected one,
which is the difference between a rule that can name its own subject and
a rule that has to share one id with every other rule in the family. An
adapter implements it however its policy is spelled: a row in a
protected-projections table, a CHECK, a beforeDelete trigger, a
hard-coded list.
This is not a fourth capability, and deliberately so. The projection
family’s declension set is the three constants above; this is the
mechanism the second of them gates, exactly as arm_commit_fault is
the mechanism the third gates. A fixture that declines
RESET_REFUSAL never has it called.
§Panics
The provided body panics, for
arm_commit_fault’s reason and with the same
two ways of reaching it: a fixture that declares RESET_REFUSAL
supported and forgets the override, or a rule that reached here without a
require!(F: RESET_REFUSAL) gate. “Declared and never implemented” then
aborts loudly rather than passing vacuously — a fixture whose body did
nothing would leave
refused_reset_changes_nothing
asserting about a store nothing had ever asked to protect anything.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".