bookclerk_library::test_support
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. |
paging: Checks that a paged listing returns what the full listing returns.
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.
pub fn new(db: DatabaseConnection, caps: DbCapabilities) -> Self
Wraps db with caps.
pub fn batch_sizes(&self) -> Vec<usize>
Statement counts of every batch so far, including batches a fault turned away.
pub fn lose_next_replies(&self, n: u32)
Arms n lost replies: the batch is applied, the caller sees
unavailable.
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
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.
pub fn new(exec: Arc<ProfileExec>, caps: DbCapabilities) -> Self
Wraps exec with caps.
Implements: Debug, NamedAtomicRunner
pub struct ProfileStore {
/* private fields */
}
A library store opened on an engine proxy that behaves like an external
database plugin under one Profile.
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.
Returns the engine or schema error when the database cannot be opened.
pub fn profile(&self) -> Profile
The enforced profile.
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().
pub fn capabilities(&self) -> &DbCapabilities
The enforced capability advertisement.
pub fn store(&self) -> &LibraryStore
The library store under test.
pub fn connection(&self) -> &DatabaseConnection
The begin-refusing connection, for reads a test makes directly.
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.
pub fn batch_sizes(&self) -> Vec<usize>
Statement counts of every batch sent so far, in arrival order, including batches a fault turned away.
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.
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.
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.
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
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.
pub const ALL: [Profile; 3] = _
Every profile, in the order conformance runs report them.
pub fn name(self) -> &'static str
Stable name used in test output and the plugin tooling
(first-party, d1, minimum).
pub fn parse(name: &str) -> Option<Self>
Parses Self::name.
pub fn capabilities(self) -> DbCapabilities
The capability advertisement this profile enforces.
Implements: Clone, Copy, Debug, Eq, Hash, PartialEq
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