Skip to main content

ProjectionProbe

Trait ProjectionProbe 

Source
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>>;
}
Available on crate feature 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§

Source

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§

Source

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.

Source

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.

Source

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.

Source

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.