bookclerk_library::test_support

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

A library store that behaves like one opened on an external database plugin, for tests.

Production hosts reach every database through an adapter guest that refuses interactive transactions and enforces the limits it advertised. A plain engine connection does neither, so a test that passes on one can still fail on the hosted demo. ProfileStore wraps an engine proxy in a BeginGate and routes every host batch through a ProfileExec that applies a Profile's capability advertisement. Named atomic operations (job claims, outbox writes, user security changes) go the way the plugin host sends them to an adapter: compiled to one typed batch, validated against the profile and run through the same executor (ProfileAtomic).

This module is the engine-neutral core; the bookclerk-db-testkit crate opens it on in-memory SQLite and adds fixtures.

Item Kind Summary
ProfileExec struct Stands in for a database adapter's executeAtomic.
ProfileAtomic struct Runs named atomic operations the way the plugin host sends them to a database adapter, through a ProfileExec.
ProfileStore struct A library store opened on an engine proxy that behaves like an external database plugin under one Profile.
Profile enum A capability advertisement a database plugin may present to the host.
engine_error function Maps an engine error onto the error the guest would answer with: a typed limit_exceeded when the message carries one, deadline_exceeded when the batch's deadline elapsed, otherwise the adapter's classification of the failure.

Re-exports

Modules

  • paging: Checks that a paged listing returns what the full listing returns.

Structs

ProfileExec

pub struct ProfileExec {
    /* private fields */
}

Stands in for a database adapter's executeAtomic.

Each batch is admitted against the profile's capabilities the way the adapter SDK admits it, run as one engine transaction under the profile's result caps, and its reply checked the way the host checks a guest reply. Injected faults are consumed one batch at a time.

ProfileExec::new

pub fn new(db: DatabaseConnection, caps: DbCapabilities) -> Self

Wraps db with caps.

ProfileExec::batch_sizes

pub fn batch_sizes(&self) -> Vec<usize>

Statement counts of every batch so far, including batches a fault turned away.

ProfileExec::lose_next_replies

pub fn lose_next_replies(&self, n: u32)

Arms n lost replies: the batch is applied, the caller sees unavailable.

ProfileExec::lock_next_requests

pub fn lock_next_requests(&self, n: u32)

Arms n lock-contention refusals: nothing is applied, the caller sees unavailable naming SQLITE_BUSY.

Implements: Debug, TypedAtomicExec

ProfileAtomic

pub struct ProfileAtomic {
    /* private fields */
}

Runs named atomic operations the way the plugin host sends them to a database adapter, through a ProfileExec.

Each compiled plan is validated against the profile's advertisement, authorized and stamped as the host does for a guest batch, run through the profile executor and interpreted from the typed reply. Nothing here reaches the engine another way, so a named operation that would exceed the profile fails closed in the test as it would on the hosted adapter.

ProfileAtomic::new

pub fn new(exec: Arc<ProfileExec>, caps: DbCapabilities) -> Self

Wraps exec with caps.

Implements: Debug, NamedAtomicRunner

ProfileStore

pub struct ProfileStore {
    /* private fields */
}

A library store opened on an engine proxy that behaves like an external database plugin under one Profile.

ProfileStore::open

pub async fn open(
    engine: impl ProxyDatabaseTrait + 'static,
    backend: DbBackend,
    profile: Profile,
) -> Result<Self>

Opens engine behind a begin gate, applies the host schema and wires a store that enforces profile on every host batch and every named atomic operation.

backend is the SQL dialect the engine proxy speaks, which SeaORM needs to render statements; the kit opens sqlite-shaped engines.

Errors

Returns the engine or schema error when the database cannot be opened.

ProfileStore::profile

pub fn profile(&self) -> Profile

The enforced profile.

ProfileStore::into_store

pub fn into_store(self) -> LibraryStore

The store alone, for fixtures that only need a store that behaves like one on an external plugin. The gate keeps refusing begin().

ProfileStore::capabilities

pub fn capabilities(&self) -> &DbCapabilities

The enforced capability advertisement.

ProfileStore::store

pub fn store(&self) -> &LibraryStore

The library store under test.

ProfileStore::connection

pub fn connection(&self) -> &DatabaseConnection

The begin-refusing connection, for reads a test makes directly.

ProfileStore::refused_begins

pub fn refused_begins(&self) -> u32

How many interactive transactions the code under test tried to open.

A host write that works on an external adapter leaves this at zero.

ProfileStore::batch_sizes

pub fn batch_sizes(&self) -> Vec<usize>

Statement counts of every batch sent so far, in arrival order, including batches a fault turned away.

ProfileStore::lose_next_replies

pub fn lose_next_replies(&self, n: u32)

The next n batches are applied but their replies are lost: the caller sees unavailable, the way a dropped RPC reply looks, and a retry with the same operation id must not repeat the write.

ProfileStore::lock_next_requests

pub fn lock_next_requests(&self, n: u32)

The next n batches are refused with SQLite lock contention before anything is applied, the way a busy file lock answers.

ProfileStore::execute_batch

pub async fn execute_batch(
    &self,
    request: ExecuteRequest,
) -> Result<ExecuteReply, PluginError>

Runs one host-authored batch through the profile the way a store write does: stamped against the host schema, admitted against the advertisement, run as one transaction, its reply checked.

Errors

Returns the typed limit_exceeded error when the request or the reply exceeds a cap, invalid_params when the batch does not typecheck against the host schema, and unavailable for an injected fault or an engine failure.

Implements: Debug

Enums

Profile

pub enum Profile {
    FirstParty,
    D1,
    Minimum,
}

A capability advertisement a database plugin may present to the host.

Host and plugin database code is expected to pass under every profile: what works on the shipped adapters must also work when a plugin advertises only the host minimums.

Variants

  • FirstParty: The shipped sqlite and Postgres adapters: 256 KiB inline results, streamed reads, the first-party statement and bind caps.
  • D1: The Cloudflare D1 adapter: D1's bind, payload and lowered-SQL caps, no consistent backup read, 8 MiB streamed results.
  • Minimum: The smallest advertisement the host connects to (DbCapabilities::host_minimum): 4,096-byte results, 1,024-byte cells, one row per statement, no streamed reads.

Profile::ALL

pub const ALL: [Profile; 3] = _

Every profile, in the order conformance runs report them.

Profile::name

pub fn name(self) -> &'static str

Stable name used in test output and the plugin tooling (first-party, d1, minimum).

Profile::parse

pub fn parse(name: &str) -> Option<Self>

Parses Self::name.

Profile::capabilities

pub fn capabilities(self) -> DbCapabilities

The capability advertisement this profile enforces.

Implements: Clone, Copy, Debug, Eq, Hash, PartialEq

Functions

engine_error

pub fn engine_error(err: DbErr) -> PluginError

Maps an engine error onto the error the guest would answer with: a typed limit_exceeded when the message carries one, deadline_exceeded when the batch's deadline elapsed, otherwise the adapter's classification of the failure.

bookclerk-db-testkit maps the engine errors of a plugin-owned binding database the same way.

Generated from crates/bookclerk-library at main · View as Markdown