pub trait ProjectionProbe: ProjectionStore {
const READS_THROUGH_BATCH: bool;
// Required methods
fn probe_write(
&self,
batch: &mut Self::Batch,
key: &str,
value: u64,
) -> impl Future<Output = Result<(), Self::Error>>;
fn probe_delete_all(
&self,
batch: &mut Self::Batch,
) -> impl Future<Output = Result<(), Self::Error>>;
fn probe_read(
&self,
key: &str,
) -> impl Future<Output = Result<Option<u64>, Self::Error>>;
fn probe_read_through(
&self,
batch: &mut Self::Batch,
key: &str,
) -> impl Future<Output = Result<Option<u64>, Self::Error>>;
}conformance only.Expand description
The write seam the projection conformance suite runs through.
Without it, generic code holding an adapter’s batch can do exactly two things
with it — commit it or roll it back. There is no way to put a row into the
batch and no way to look at the read model afterwards, so the rule carrying
this port’s entire reason for existing — the read-model write and the
checkpoint write become durable together or not at all — cannot be written,
and a suite built on ProjectionStore alone degenerates into a checkpoint
test that a store writing only checkpoints passes.
An adapter that wants to be certified implements this beside its
ProjectionStore impl. It is not part of the runtime surface: it exists so
a suite that has never heard of the adapter can drive its read model.
§Why this lives in the contract crate rather than the testkit
It looks like a testing utility and belongs beside the port anyway, and the
reason is coherence rather than taste. An adapter crate implementing a
testkit trait for its own type is legal — the type is local, so the orphan
rule is satisfied. But the natural place to write such an impl is the
adapter’s own tests/ directory, and that is a different crate. There,
neither the trait nor the type is local, impl ProjectionProbe for MyStore
is rejected by the orphan rule, and the only way out is a non-dev
dependency on the testkit, feature-gated. Putting the trait here keeps the
impl in the adapter’s own src/, beside the store and behind the adapter’s
own feature, and costs one flag on a dependency it already has rather than a
new edge in its graph:
[dependencies]
# No feature: the port and every item the `impl ProjectionStore` below
# names are unconditional since ADR-0063. (From `0.2.0` until then this
# line had to carry `unstable-projection`, because the port impl in an
# adapter's `src/` cannot be made optional and the port was gated.)
happenstance-core = "…"
[features]
# Forwards to the contract crate. The `impl ProjectionProbe` lives in `src/`
# under `#[cfg(feature = "conformance")]`, because a crate cannot `cfg` on a
# dependency's feature — which is also why a `[dev-dependencies]` entry
# would not work: it does not exist for the lib build the impl compiles in.
conformance = ["happenstance-core/conformance"]
[dev-dependencies]
happenstance-testkit = "…"Nothing inside this workspace can fail the wrong version of that
decision. Every fixture here already lives in a crate that depends on the
testkit, so the trait would be local, the impls local, the orphan rule
silent, and the whole gate green. The falsifier is
documented-extension-surface (HS-S0015), which builds an outside author’s
fixture from this documentation alone — named here so the placement is not
“simplified” into the testkit on grounds of diff size before it runs.
§Both flavours, one trait
The bound is bare ProjectionStore, and there is deliberately no
SendProjectionProbe. trait_variant emits a blanket impl, so
SendProjectionStore implies ProjectionStore and a Send adapter
already satisfies this supertrait bound. A second trait would collide with
that blanket impl — error[E0275] — which is the shape ADR-0008 records.
Required Associated Constants§
Sourceconst READS_THROUGH_BATCH: bool
const READS_THROUGH_BATCH: bool
Whether this adapter offers any read path on an open batch.
Declaring false is a conformant answer, not a failure: many adapters
buffer their writes and cannot read them back before commit. A store
declaring false still has the read-through rule emitted as a
reported skip carrying its reason — never omitted — because a rule
absent from the binary is indistinguishable in CI output from a rule
that passed.
Required Methods§
Sourcefn probe_write(
&self,
batch: &mut Self::Batch,
key: &str,
value: u64,
) -> impl Future<Output = Result<(), Self::Error>>
fn probe_write( &self, batch: &mut Self::Batch, key: &str, value: u64, ) -> impl Future<Output = Result<(), Self::Error>>
Writes one probe row into an open batch.
A future of a Result, because the batch may be a live transaction and
then this is a statement: I/O that yields and can fail. A buffering
adapter pushes onto a vector, never awaits and never fails, and its
body reads async move { batch.push(…); Ok(()) }. Nothing becomes
durable until the batch reaches commit
either way.
Spelled -> impl Future<…> with no + Send, for the reason
probe_read gives.
§Errors
Returns the adapter’s error if the statement was refused. A refused statement on a live transaction may poison it; the suite treats any error here as the batch being unusable and does not commit it.
Sourcefn probe_delete_all(
&self,
batch: &mut Self::Batch,
) -> impl Future<Output = Result<(), Self::Error>>
fn probe_delete_all( &self, batch: &mut Self::Batch, ) -> impl Future<Output = Result<(), Self::Error>>
Queues deletion of every probe row into an open batch.
Exists so reset is checkable without the
suite knowing what a read model is. reset takes the caller’s own
deletes, so a suite with no way to express “delete everything” cannot
exercise it at all. Shaped like probe_write for
the same reason.
§Errors
Returns the adapter’s error if the statement was refused.
Sourcefn probe_read(
&self,
key: &str,
) -> impl Future<Output = Result<Option<u64>, Self::Error>>
fn probe_read( &self, key: &str, ) -> impl Future<Output = Result<Option<u64>, Self::Error>>
Reads one probe row from the committed read model.
The one asynchronous member, and not arbitrarily so: the other three mutate a batch the caller already holds, while this is real I/O against the store.
Spelled -> impl Future<…> rather than async fn, and with no
+ Send. This trait is not under #[trait_variant::make], so async fn here would fire async_fn_in_trait under the gate’s -D warnings;
writing the desugaring by hand also puts the absence of the Send
bound at the declaration, where a reader can see it. A Send bound
would break wasm32 and could not be relaxed later without a breaking
change — and it is not needed, because suite code binds the weaker
flavour and takes its per-test wrapper as a parameter.
§Errors
Returns the adapter’s error if the read model cannot be read.
Sourcefn probe_read_through(
&self,
batch: &mut Self::Batch,
key: &str,
) -> impl Future<Output = Result<Option<u64>, Self::Error>>
fn probe_read_through( &self, batch: &mut Self::Batch, key: &str, ) -> impl Future<Output = Result<Option<u64>, Self::Error>>
Reads one probe row through an open batch, committed state included.
Only called when READS_THROUGH_BATCH is
true; may be unimplemented!() otherwise.
§This signature is the one a live transaction can meet
&mut Self::Batch because a driver borrows its connection mutably to
issue a statement — sqlx’s Executor for &mut Transaction,
rusqlite’s &mut Transaction; a future because the statement is I/O
and yields; a Result because a statement on a live transaction can
fail. Until ADR-0062 it was fn(&self, &Self::Batch, &str) -> Option<u64>,
and tests/probe_live_transaction_shape.rs recorded what that cost: a
store whose batch is a transaction could satisfy it only by declaring
READS_THROUGH_BATCH = false, a false statement about itself, so the
suite could not tell a live-transaction adapter from a buffering one.
That file now runs the honest body instead.
A buffering adapter that can read its own pending set — a map layered
over committed state — answers from the map without awaiting. One that
cannot declares false and leaves this unimplemented!(), which is a
conformant answer and the reported-skip path.
§Errors
Returns the adapter’s error if the read could not be issued.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".
Implementors§
Source§impl ProjectionProbe for MemoryProjectionStore
Available on crate feature memory only.
impl ProjectionProbe for MemoryProjectionStore
memory only.