Trait Fixture
pub trait Fixture {
type Store: EventStore;
Show 12 associated constants and 7 methods
const SECOND_HANDLE: Capability;
const REOPEN: Capability;
const READ_YOUR_OWN_WRITES: Capability = Capability::SUPPORTED;
const MID_BATCH_FAULT: Capability = _;
const READ_FAULT: Capability = _;
const MAX_EVENT_DATA_LEN: Option<usize> = None;
const MAX_TAGS_PER_EVENT: Option<usize> = None;
const MAX_EVENTS_PER_BATCH: Option<usize> = None;
const MAX_METADATA_LEN: Option<usize> = None;
const MAX_TAGS_PER_BATCH: Option<usize> = None;
const HELD_ABOVE_FRONTIER: Capability = _;
const REMOVAL: Capability = _;
// Required method
fn connect(&self) -> impl Future<Output = Self::Store>;
// Provided methods
fn arm_mid_batch_fault(&self, after: usize) -> impl Future<Output = ()> { ... }
fn arm_read_fault(&self) -> impl Future<Output = ()> { ... }
fn reopen(&self) -> impl Future<Output = ()> { ... }
fn arm_held_above_frontier(&self) -> impl Future<Output = Armed> { ... }
fn settle_frontier(&self) -> impl Future<Output = Settled> { ... }
fn remove_outside_port(
&self,
positions: &[SequencePosition],
) -> impl Future<Output = Removed> { ... }
}Expand description
One isolated backing store, plus the ways a rule is allowed to reach it.
Implement this 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 MemoryEventStore behind an Arc. Each instance is one
store. Each connect is one handle onto it.
§No Send bound, and no trait_variant
EventStore needs two flavours because a caller may want to
tokio::spawn a store’s future, and a Send bound that helps there is
unsatisfiable on wasm32 (ADR-0001). None of that applies here: nothing
ever spawns a fixture. The harness owns the executor, and a fixture is only
ever driven by the rule holding it. A second flavour would double the surface
to buy a property no caller wants — and would exclude precisely the adapters
ADR-0001 exists for.
§Why the methods are spelled -> impl Future rather than async fn
The same reason happenstance-neon’s transport records: async fn in a
public trait fires rustc’s async_fn_in_trait lint, and the gate runs
-D warnings. The desugared form is also strictly better documentation
here, because it makes the absence of + Send visible at the
declaration, which is the whole ADR-0001 point.
An implementation may still use 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
A borrowing type Store<'a> where Self: 'a is the obvious shape for “a
handle onto this fixture”, and it is the shape to keep away from. where Self: 'a on a GAT implemented for a foreign trait is one of the five independently
necessary ingredients of the rustc ICE this repository already minimised
(rust-lang/rust#158983; experiments/rustc-ice-gat-foreign-trait/),
which still reproduces on 1.97.1.
Nothing is lost. A pool-backed fixture holds its pool in an Arc and returns
an owned handle that keeps the pool alive; that is exactly what
MemoryFixture does with an Arc clone,
and what a !Send fixture would do with an Rc. The handle owning a
refcount instead of borrowing a lifetime is the difference between a
compiling contract and an ICE.
§Capability constants are checked at codegen, not at cargo check
An empty reason string cannot be written — Capability::declined rejects
it — but for an associated const the rejection arrives later than one would
like. Capability::declined’s own documentation states exactly when, and
what each of check, clippy and build reports; it is written there rather
than here so that a reader looking at the constructor finds it.
Required Associated Constants§
const SECOND_HANDLE: Capability
const SECOND_HANDLE: Capability
Whether this fixture can hand out a second, independent handle onto the one backing store.
A fixture that can is what lets a rule catch the adapter whose
correctness is per-session: a cached max(position) fast path, a
per-connection repeatable-read snapshot, an advisory lock scoped to one
pool member.
This one is a MUST, and it is the only capability here that is.
SPECIFICATION.md CF-16 requires every fixture to be able to open a second
handle; REOPEN is a SHOULD, because a volatile store
declining it is an honest answer. Declining this is not a trade, it is a
fixture that does not meet the contract, and the shape cannot tell the two
apart: the type says Capability in both places.
§What enforces it
two_handles_observe_each_others_appends
panics on a declined SECOND_HANDLE rather than reporting a skip,
quoting the reason the fixture gave. That is deliberately in the rule
rather than in the testkit’s own meta-tests, because the meta-tests never
run in an adapter’s CI and the fixture declining a MUST is there. An
adapter author who meets a red rule, declines the capability and re-runs
gets a red rule again, with an explanation.
It stays spelled as a Capability so that the rules which merely
strengthen themselves where a second handle exists have somewhere to
ask, and so that the failure names the fixture’s own words.
The second line is
mutation_coverage::capability_skips_are_reported
(crates/happenstance-testkit/tests/mutation_coverage.rs), which drives
a fixture declining everything and asserts the rule rejects it, and
separately holds the testkit’s own registered instruments to the MUST.
const REOPEN: Capability
const REOPEN: Capability
Whether this fixture can be reopened: every outstanding handle’s
process-level state discarded, such that a subsequent
connect observes only what was durably committed.
This is deliberately the weaker of the two operations one might mean by “restart”. A Durable Object’s storage outlives its isolate, so it can discard handle state and read the store again; its isolate cannot be restarted from inside a test at all. Naming the stronger operation would have bought a capability every fixture in the workspace declines, which is a skip reported on every run and evidence of nothing.
§What declaring it commits the fixture to
CF-17, and it is MID_BATCH_FAULT’s CF-39 one
capability over. A fixture declaring this supported MUST make
reopen discard process-level state over a medium that
outlives it, so that the subsequent connect reads
what was durably committed rather than what a live object still happens
to be holding. The fixture MUST state the mechanism — which file is
closed, which connection pool is drained, which isolate’s storage is read
again. A fixture over a store with no medium outside the process MUST
decline this capability with that as its stated reason, rather than
declare it and let three rules certify a Vec.
§And what this obligation is not, stated rather than discovered later
It is a MUST no rule can enforce, and pretending otherwise would be
worse than saying so. CF-39 works because arming a mid-batch fault has a
port-observable consequence: the append has to answer Err, and
arming_a_mid_batch_fault_makes_the_append_fail is written on exactly
that. Reopening has none. A correct reopen over a durable medium and an
empty one over a Vec produce byte-identical observations through
EventStore, so any rule that rejected the second would reject the
first with it — which is why there is no such rule and why one must not
be written.
The sentence above is stronger than “no rule happens to catch it”, and
the evidence is in the tree rather than in the argument.
LiveHandleReopenFixture in tests/mutation_coverage/mutants.rs is
happenstance-sqlite’s fixture in miniature — an honest reopen that
closes the connections the fixture holds and leaves the medium alone,
because reopening a file does not replace the file. It is indistinguishable
from an empty reopen on every observation anyone has proposed, including
the sharpest one: what a handle taken before the call can still do
afterwards. So a rule built on any of them rejects the workspace’s only
durable adapter.
What exists instead is the named wrong implementation, driven:
NoopReopenFixture in tests/mutation_coverage/mutants.rs declares this
capability supported and overrides reopen with an empty body over a
completely correct but entirely volatile store.
reopen_over_claiming_is_undetectable_and_this_is_the_record drives it
through every rule and pins the two things that are measurable: it
fails none of them, and it converts
acknowledged_writes_survive_a_reopen,
reopened_store_does_not_reissue_an_event_id and
recorded_time_survives_a_reopen — this suite’s whole durability
certification — from reported skips into passes, while its honest twin,
the same store one line apart, reports them as skips. The incentive runs
backwards: the fixture that over-claims scores better.
It is deliberately not in that binary’s REGISTRY. A registry row
would have to claim something is checked, and nothing is; the record is a
test that says so in its own name.
The one mistake that is caught is the other one:
reopen’s provided body panics, so a fixture that
declares the capability and forgets the override aborts loudly. What
nothing catches is an override that is present, honest-looking and empty.
Provided Associated Constants§
const READ_YOUR_OWN_WRITES: Capability = Capability::SUPPORTED
const READ_YOUR_OWN_WRITES: Capability = Capability::SUPPORTED
Whether a read through this store shows an append the same caller has just been told succeeded.
Defaulted to SUPPORTED, which is the opposite
polarity to every other capability on this trait, and deliberately so.
Read-your-own-writes is what almost every store offers for free — it
falls out of assigning positions under a lock held until commit — so a
fixture that says nothing must keep being held to it. Defaulting this
one to a declension would silently stop checking the property on every
adapter that never heard of the constant, which is the failure mode
ADR-0042’s default-to-declined shape exists to prevent everywhere else.
The rule is that a capability lands defaulted, not that it lands
defaulted off.
§What declining it means, and what it does not
Declining says: append returning Ok(P) does not promise that a read
or head issued immediately afterwards through this same handle contains
the event at P. It does not say the append is in doubt, and it does
not excuse an adapter from ES-10 — position order still has to be
visibility order. It says only that visibility is a predicate rather
than an identity, so the frontier trails the highest assigned position.
happenstance-postgres is the built case and the reason this constant
exists. It buys ES-10 with xid8 + pg_snapshot_xmin: a row is visible
once its writing transaction’s id is below the frontier beneath which
nothing can still be in flight. That frontier is a property of the
server, not of this store — an unrelated open transaction in an
unrelated database holds it back, measured by that crate at 0.688 ms
unloaded and 4010.719 ms behind a five-second write elsewhere.
§Why this is a capability and not a bound the rules could weaken
Two exits were considered and both are closed.
A rule waiting for the frontier is forbidden. [FROZEN] CF-33 bans
a conformance rule from reading a clock, sleeping, or asserting on an
operation count, and its Rejects: names this exact pathology: a rule
that “passes on the author’s machine, fails on a loaded CI runner”.
That is not a rule this suite is allowed to write, and the reason given
there is the right one — a flaky suite teaches adapter authors to re-run
until green, and that habit is what lets a real failure through.
The fixture may wait, and that is where the waiting went (CF-42). A
named rule that reads back its own append calls
settle_frontier first, and a declining
fixture that can bring its frontier past every acknowledged row
overrides it to do so. One that cannot keeps the provided body, and
those rules then report a skip under this capability, with the reason
given here.
A prefix-only weakening does not reach far enough; a larger one does.
The model family (model, unlinked: it needs proptest) predicts whether the store will
reject a conditional append. ES-25 evaluates a condition over what the
store holds, ES-10 and ES-11 govern what a read shows, and a
frontier store keeps the two apart, so a prediction made from a read
has no oracle. Against a declining fixture the family therefore runs
a trailing model instead of its exact one. It predicts over what
is held, bounds a position it has not been shown, and defers a verdict
it cannot decide yet. It never waits, so it gives some things up,
which ops_agree_with_the_model’s documentation lists. It also
assumes, with no clause to cite, that visibility never moves
backward.
const MID_BATCH_FAULT: Capability = _
const MID_BATCH_FAULT: Capability = _
Whether this fixture can make its store fail part way through writing one batch.
ES-18 says either every event of a batch lands or none does, and the two rules that check it today both reach the store through the condition path — where a conformant store decides before it writes anything, so a partial write was never on the table. The case that is left is a fault between two rows, and reaching it needs the store’s co-operation.
§Why this is a fixture capability and not a decorator
SPECIFICATION.md ES-18 asks for “a fault-injecting decorator over any
EventStore”, and that shape does not exist. A decorator sits above
append, which is the unit the port makes atomic: the only fault it can
inject is one that happens before the call or after it, and a decorator
that appended events[..k] and then returned Err would be asserting
that the store must undo a partial batch the decorator wrote. Nothing
in the port lets an outside caller reach between two rows of one
transaction, which is precisely why the atomicity being tested is worth
having.
So the injection is the adapter’s: a trigger that raises on the third
insert, a CHECK constraint armed for one write, a connection killed
mid-statement. Every store that can do it does it differently, which is
what makes it a capability rather than testkit machinery.
A store with no way to fail one row of a batch declines, and the default
below is that answer. It is defaulted rather than required — unlike
SECOND_HANDLE and REOPEN,
which every fixture must answer deliberately — because an in-memory store
has no fault to inject and demanding an answer would buy one more line of
boilerplate per fixture and no information.
const READ_FAULT: Capability = _
const READ_FAULT: Capability = _
Whether this fixture can make its store fail part way through a
read.
MID_BATCH_FAULT’s sibling on the other path.
EventStore::read yields
Result<SequencedEvent, Self::Error> per item, so the port has an
error arm on the read side and, until this constant, nothing in the suite
ever reached it: no rule induced a read fault, no mutant modelled one, and
Fixture had a write-path seam and no read-path analogue.
§Why this is a fixture capability and not a decorator
FaultyStore is the decorator, and it is the
reason this capability is worth having rather than a reason it is not:
a wrapper can fail a stream it produced, which is why
tests/faulty_store_conformance.rs can declare this capability, and it
cannot fail an adapter’s own fetch. The defect this exists to catch
lives inside a poll_next an outside caller never sees —
let Ok(page) = fetch().await else { return Poll::Ready(None) }; — and
reaching it needs the store’s co-operation, exactly as reaching between
two rows of an append does.
So the injection is the adapter’s: a connection dropped between two pages, an HTTP round trip that 503s, a cursor invalidated by the server. A store with no way to fail a read declines, and the default below is that answer.
§What declaring it commits the fixture to
arming_a_read_fault_makes_the_stream_yield_an_error
arms the fault and requires the next read’s stream to yield an Err
item rather than to end. Where inside the read it fires is the
adapter’s business — first poll, page boundary, mid-page — for
arm_commit_fault’s reason: a
read is one call whose granularity is the adapter’s, and naming an index
would be the testkit asserting a paging model the port does not have.
CF-39’s shape, one path over: a fixture whose
arm_read_fault does nothing would otherwise
contribute a green result about a store nothing ever faulted. A store
that can absorb every read fault its fixture is able to arm MUST decline
this capability with that as its stated reason, rather than declare it
and contribute a full, successful read.
const MAX_EVENT_DATA_LEN: Option<usize> = None
const MAX_EVENT_DATA_LEN: Option<usize> = None
The largest data payload this fixture’s store accepts, in bytes, or
None if it has no ceiling.
§Why this is an Option<usize> and not a Capability
The five constants here look like capabilities and are deliberately not
spelled as ones. A declined Capability is a trade: the fixture
could have co-operated and chose not to, and the reason string is the
record of that choice, printed on every run so a reviewer and a user of
the adapter can both read what was given up. None here is not a trade.
It is a store reporting a fact about itself — that it has no ceiling
on this value — and there is nothing it could have done differently and
no reason it owes anybody. Asking it to write one would put a fiction in
the CI log.
What None shares with a declined capability is the reporting
obligation, and only that: the rule cannot run, so it must say so. It
therefore returns RuleOutcome::Skipped through the same path, carrying
NO_STORE_LIMITS as the capability name and NO_CEILING_REASON as
the reason. A rule silently omitted is indistinguishable in CI output from
a rule that passed, which is CF-18’s whole argument and does not stop
being true because the thing being reported is a fact rather than a
decision.
§What stating a number commits the store to
append_reports_exceeded_store_limits
appends a payload of exactly this many bytes and requires it to be
accepted, then a payload one byte larger and requires it to be refused
as AppendError::ExceedsStoreLimit { limit: StoreLimit::EventDataLen, .. }
— never as AppendError::Store, and never by truncating. A number that is
not where the store’s real ceiling is fails that rule in one direction or
the other, which is the point: this constant is the store’s documented
limit (VT-21 requires one), and the suite is what holds the documentation
to the code.
A store MAY state a ceiling below MIN_SUPPORTED_EVENT_DATA_LEN, and it
will then fail store_accepts_the_guaranteed_minimum_payload —
correctly, because VT-21 makes 65,536 bytes a floor every store must
clear. The two rules are independent and both are owed an answer.
const MAX_TAGS_PER_EVENT: Option<usize> = None
const MAX_TAGS_PER_EVENT: Option<usize> = None
The largest number of tags on one event this fixture’s store accepts, or
None if it has no ceiling.
See MAX_EVENT_DATA_LEN for why these five
are Option<usize> rather than Capability, and for what stating a
number commits the store to. The floor is MIN_SUPPORTED_TAGS_PER_EVENT
(VT-22).
const MAX_EVENTS_PER_BATCH: Option<usize> = None
const MAX_EVENTS_PER_BATCH: Option<usize> = None
The largest number of events this fixture’s store accepts in one append,
or None if it has no ceiling.
See MAX_EVENT_DATA_LEN. The floor is
MIN_SUPPORTED_EVENTS_PER_BATCH (VT-24).
Note what this is not: VT-24 forbids a MAX_EVENTS_PER_BATCH constant
in happenstance-core and forbids an EventBatch newtype to carry one,
because the bound is adapter-specific. That prohibition is about the
contract. Naming the number here is the opposite move — one store saying
what one store does, in the one place a conformance rule can read it.
There is deliberately no MAX_QUERY_ITEMS beside these three. A
query-item refusal is not an append outcome, so it has no StoreLimit
variant to be reported through and no rule to gate.
const MAX_METADATA_LEN: Option<usize> = None
const MAX_METADATA_LEN: Option<usize> = None
The largest metadata on one event this fixture’s store accepts, in
bytes, or None if it has no ceiling.
See MAX_EVENT_DATA_LEN. Stating a number
commits the store to accepting metadata of exactly that many bytes and
refusing one more as ExceedsStoreLimit { limit: StoreLimit::MetadataLen, .. }, never as EventDataLen, which names data.
Unlike the other four there is no floor (ADR-0043):
StoreLimit::MetadataLen.guaranteed_minimum() is 0, so any number
here is a legal declaration, and no rule fails a store for stating a
small one.
const MAX_TAGS_PER_BATCH: Option<usize> = None
const MAX_TAGS_PER_BATCH: Option<usize> = None
The most tags, summed over every event of one append, this fixture’s
store accepts, or None if it has no ceiling beyond the one
MAX_EVENTS_PER_BATCH ×
MAX_TAGS_PER_EVENT already implies.
See MAX_EVENT_DATA_LEN. Stating a number
commits the store to accepting an append whose events carry exactly that
many tags between them, spread so that no event is over its own
ceiling, and refusing one more as ExceedsStoreLimit { limit: StoreLimit::TagsPerBatch, .. }. The floor is
MIN_SUPPORTED_TAGS_PER_BATCH (VT-36), which VT-22 and VT-24 already
imply. Unlike the other ceilings, a number here below the floor fails
store_accepts_the_guaranteed_minimum_tags_per_batch
on the declaration itself, before anything is written: declaring less
is not the fix for a store that cannot clear the floor.
A stated number must also be coherent with the other two (VT-36):
at least MAX_TAGS_PER_EVENT, so that a lone event within its own
ceiling never trips this one and halving a refused batch terminates;
and reachable, so that one tag more than it fits in
MAX_EVENTS_PER_BATCH events of at most MAX_TAGS_PER_EVENT tags. A
ceiling that cannot be crossed without first crossing another is not a
ceiling, and None is the honest declaration for it.
Defaulted, like its siblings, so that adding it broke no fixture.
const HELD_ABOVE_FRONTIER: Capability = _
const HELD_ABOVE_FRONTIER: Capability = _
Whether this fixture can hold a committed row above ES-10’s visibility
frontier: a row the store has committed and read does not yet show.
Only a store whose visibility is a predicate rather than an identity has
such a row at all. happenstance-postgres and happenstance-neon are
the built cases: a row is visible once its writer’s xact_id falls below
pg_snapshot_xmin(pg_current_snapshot()), so between commit and that
moment it is committed and invisible. A store that publishes a row at
commit has no such row, and the default below is that answer.
§What the capability is for
ES-41 reads contains_event_id as held, not visible (ADR-0095).
contains_event_id_reports_a_held_row_above_the_frontier
arms this, appends, checks that read does not show the row, and
requires the probe to answer true for it. The wrong implementation
is the probe that carries the read path’s frontier predicate. Every
other rule passes it, because no other rule stages a row the predicate
could hide.
§Why this is a capability and not a rule every store runs
The row cannot be staged through the port. Every store publishes what it
commits sooner or later, and [FROZEN] CF-33 forbids a rule that waits
or races for the gap between the two. So the staging is the adapter’s,
just like a mid-batch fault.
§How a fixture that does not answer is checked
The default is declined, in this crate’s words. For a store with no
frontier those words are a fact, and its fixture may leave them. For a
store whose fixture declines
READ_YOUR_OWN_WRITES, they are false,
because declining that constant says reads trail commits.
[assert_declensions_are_stated] therefore rejects such a fixture
unless it states this constant itself.
const REMOVAL: Capability = _
const REMOVAL: Capability = _
Whether this fixture can remove events from its store outside the
port: delete them from the adapter’s own storage, by a mechanism
EventStore does not have.
ES-38 (a removed position is never handed out again) and ES-40 (a condition over removed history does not reject) are about a store that has lost events, and neither can be checked against a store nothing can remove from. ADR-0028 names this capability for its sub-question 3, so that both rules can run against the real adapters as well as against CF-27’s completeness instrument.
§Why this is a fixture capability and not a port method
ADR-0028’s first decision keeps deletion outside the port through 1.x.
A retention job’s raw DELETE, a TRUNCATE and a Durable Object’s
delete_all() all happen where no adapter can see them, so the removal
a rule needs has to come from the same place: the fixture’s side of the
storage, which the fixture can reach and the port cannot.
§Why it is not the decorator
CF-27’s instrument, the WithholdingStore decorator, hides events
from a store that still holds them, so only a deletion from an adapter’s
own storage can show its allocator surviving one (the INTEGER PRIMARY KEY without AUTOINCREMENT shape ADR-0028 names). CF-27’s own
instrument, and only it, grants this by forwarding to withhold; its
ES-38 pass is by delegation and certifies nothing about an allocator.
§What declaring it commits the fixture to
removal_outside_the_port_removes_exactly_the_named_events
appends four events, removes the second and the fourth through
remove_outside_port, and requires a handle
it already held to read back exactly the other two, unchanged, and the
membership probe to answer false for the removed identities.
CF-39’s shape, one capability over: an adapter fixture whose removal does not delete from the adapter’s own storage MUST decline this capability, rather than declare it and contribute a green result about a store nothing was removed from.
§Same store, not a new one
A removal leaves the store’s identity and its position allocator where
they were. A wipe that re-mints the StoreId or rewinds the allocator —
a Durable Object’s delete_all(), DROP SCHEMA followed by a fresh
migration, TRUNCATE … RESTART IDENTITY on Postgres — makes a
different store, which is VT-6’s business and not removal.
§Defaulted, and not checked by CF-18’s emitted check
The default is declined, in UNSTATED_REMOVAL’s words, which say
that the fixture has not said and that the answer is given by default.
Those words are true of every fixture that says nothing, so
[assert_declensions_are_stated] accepts the silence, as it does
HELD_ABOVE_FRONTIER’s for a store with
no frontier. A fixture that declares the capability and forgets the
override is caught by the rule instead, on every run, because the
provided body answers Removed::Nothing.
Required Associated Types§
type Store: EventStore
type Store: EventStore
A handle onto this fixture’s backing store.
Bound on EventStore, the flavour with no Send requirement, because
it is the weaker one and accepts both kinds of adapter.
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.
§Panics
Implementations panic rather than returning Result. A fixture that
cannot connect is a broken test environment, not a non-conformant
adapter, and a Result here would put “the database is down” into the
same channel as “the adapter is wrong” — where the suite’s own error
messages would then have to guess which it was reading.
Provided Methods§
fn arm_mid_batch_fault(&self, after: usize) -> impl Future<Output = ()>
fn arm_mid_batch_fault(&self, after: usize) -> impl Future<Output = ()>
Arms the store so that the next append of more than after events
fails while writing event after + 1.
The fault fires once. Whether the store answers Err or swallows it is
the adapter’s business; what ES-18 requires is that the two answers stay
consistent with what is in the log afterwards, which is what
append_is_atomic_under_a_mid_batch_fault
checks.
§Panics
The provided body panics, for
reopen’s reason and with the same two ways of reaching
it: a fixture that declares MID_BATCH_FAULT
supported and forgets the override, or a rule that reached here without a
require! gate.
fn arm_read_fault(&self) -> impl Future<Output = ()>
fn arm_read_fault(&self) -> impl Future<Output = ()>
Arms the store so that the next read fails part way through.
The fault fires once. Where inside the read it fires is the adapter’s
business — first poll, page boundary, mid-page — and it takes no index
for READ_FAULT’s stated reason: a read is one call
whose granularity belongs to the adapter, so naming a position would be
the testkit asserting a paging model the port does not have. What
arming_a_read_fault_makes_the_stream_yield_an_error
requires is only that the stream yields an Err item rather than
ending, which is the one thing the port makes observable.
Arming MUST reach a handle the caller already holds. A rule connects
before it arms, exactly as the mid-batch rules do, so a fixture whose
arming is applied at connect and nowhere else arms nothing the rule can
see.
§Panics
The provided body panics, for reopen’s reason and with
the same two ways of reaching it: a fixture that declares
READ_FAULT supported and forgets the override, or a
rule that reached here without a require! gate.
fn reopen(&self) -> impl Future<Output = ()>
fn reopen(&self) -> impl Future<Output = ()>
Closes and reopens the underlying storage, discarding every outstanding handle’s process-level state.
After this returns, 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.
§Panics
The provided body panics, and it names both ways of reaching it because
only one of them is the suite’s fault. Nothing in the trait ties
REOPEN: Capability::SUPPORTED to overriding this method, so the
reachable path an adapter author actually hits is: declare it supported,
forget the override, run the suite. Blaming a missing require! gate
there would send them reading the testkit for a bug that is in their
fixture.
fn arm_held_above_frontier(&self) -> impl Future<Output = Armed>
fn arm_held_above_frontier(&self) -> impl Future<Output = Armed>
Arms the store so that every append committed after this returns,
through any handle, is held above the visibility frontier for the rest
of this fixture’s life. It is committed, read and head do not show
it, and the store still holds it.
Arming MUST reach a handle the caller already holds, as
arm_read_fault’s does. The rule connects
before it arms.
“For the rest of this fixture’s life” rather than “until released” is deliberate. A rule gets a fresh fixture, so the two are the same run. A release would be a second method whose only caller is the rule’s last line.
An override returns Armed::Staged once it has armed the store.
§The provided body says it armed nothing
It returns Armed::Nothing, and the rule asserts on that answer
before it appends. A fixture that declares
HELD_ABOVE_FRONTIER supported and
forgets this override therefore fails on every run, with a message
naming this method. The answer is needed because the rule’s staging
check cannot catch the forgotten override reliably. On a frontier
store, an unrelated transaction can hold the frontier back, so an
unarmed append sometimes sits above it anyway, and the staging check
passes on that run. Detection that fires only on some runs is the
flake CF-33 exists to forbid.
The staging check stays, for the other wrong implementation: an
override that answers Armed::Staged and arms nothing.
fn settle_frontier(&self) -> impl Future<Output = Settled>
fn settle_frontier(&self) -> impl Future<Output = Settled>
Brings this store’s visibility frontier up to everything it holds, and says whether it did.
An override that returns Settled::Visible promises this: every row
the store held when the call was made is visible to every read and
head issued after the call returns, through any handle. That relies on
the frontier never moving backward afterwards, which this method’s
override promises for its own store. No clause holds a store to it.
§Who calls it, and when
Only a fixture that declines
READ_YOUR_OWN_WRITES is ever asked. For
a fixture that supports it the rules make no call at all: the branch is
on that constant, so the store sees exactly the calls it saw before this
method existed.
A rule that reads back an append of its own calls this first (CF-42).
It calls it only where no append future of its own is still pending,
because on a store like happenstance-postgres the settle waits for
every open writer older than a row it holds, and the rule’s own
unfinished append would then never finish. It never calls it after
arm_held_above_frontier, whose rows
are held above the frontier for the rest of the fixture’s life, so a
settle there could never return.
§Why the fixture settles and not the rule
[FROZEN] CF-33 forbids a rule to wait, and a rule that re-read until
its append appeared would be waiting through the store’s own read path:
a store that lost the row would hang the suite rather than fail a named
rule. The fixture can ask the storage directly. The Postgres fixture
polls its own table until no committed row sits at or above
pg_snapshot_xmin. A store whose read path then hides a row still fails
the rule’s assertion, by name.
§The provided body settles nothing
It returns Settled::Nothing, and every rule that reads back its own
append then reports RuleOutcome::Skipped under
READ_YOUR_OWN_WRITES, carrying this fixture’s own stated reason. That
is an honest skip: the rule did not run. It is never a pass that holds
only because the server happened to be quiet, and never a failure the
adapter did not earn.
§Panics
An override panics when it cannot settle within its own bound, for
connect’s reason: a frontier still held back long
after every writer has finished is a broken test environment, not a
non-conformant adapter. Answering Settled::Nothing instead would
report a stuck server as a skip.
fn remove_outside_port(
&self,
positions: &[SequencePosition],
) -> impl Future<Output = Removed>
fn remove_outside_port( &self, positions: &[SequencePosition], ) -> impl Future<Output = Removed>
Removes the events this store holds at positions outside EventStore
(a raw DELETE on the adapter’s own storage), and says whether it did.
An override returns Removed::Deleted once every named event is gone
from the store’s own storage, and nothing else is (CF-27’s instrument,
named under REMOVAL, once each is withheld instead).
§The contract on the argument
- Every named position is one this store holds. A rule names only
positions an
appendreturned and that nothing has removed since. - A position named twice is removed once.
- An empty slice removes nothing, and an override answers
Removed::Deleted. - An override may treat a position it does not hold as a broken test
environment and panic, for
connect’s reason. - Removing part of a write group (SY-39) is outside what ES-38 describes. A rule that removes from a grouped log names whole groups.
§What the removal must reach, and what it must leave
It MUST reach a handle the caller already holds, as
arm_read_fault’s arming must. The rule
connects before it removes.
It MUST NOT mint a new incarnation or rewind the position allocator.
See REMOVAL’s “Same store, not a new one”.
§The provided body says it removed nothing
It returns Removed::Nothing and touches nothing. The rule asserts on
that answer before it reads anything back, so a fixture that declares
REMOVAL supported and forgets this override fails on
every run, with a message naming this method.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".