Storage¶
approvo ships no database adapters. It defines three async protocols
in approvo.stores.base and a conformance suite in approvo.testing. You
implement the protocols over the database you already run, run the suite,
and inject the result. ADR-0004 explains
the reasoning; the short version is that a bundled adapter would fight
your migration tool, your pool, and your transaction boundaries, and would
rot.
The three stores¶
| Store | Trust level | Lose it and… |
|---|---|---|
EventStore |
source of truth | you have lost the approvals |
ProjectionStore |
rebuildable cache | run rebuild_projections() |
IdempotencyStore |
short-lived coordination | in-flight retries may double-append |
All three are scoped to a log_id. One log is one hash chain, hence one
write-serialization point — partition by
tenant, team, or environment.
Why three protocols, not one? Each has a different failure mode, and collapsing them would hide that. Lose the
EventStoreand you have lost the approvals — it's the source of truth. Lose theProjectionStoreand you callrebuild_projections()— it's a disposable cache; skip it entirely withNullProjectionStoreif you don't need list screens. Lose theIdempotencyStoreand in-flight retries might double-append — it's short-lived coordination, not data. One interface would either force every implementer to build idempotency/projection machinery they don't need, or blur which failures actually matter. See ADR-0004 for the full design rationale and the conformance suite to validate your implementation.
EventStore¶
class EventStore(Protocol):
log_id: str
async def head(self) -> LedgerEntry | None: ...
async def append(self, entry: LedgerEntry) -> None: ...
async def get_by_seq(self, seq: int) -> LedgerEntry | None: ...
async def events_for_request(self, request_id: str) -> list[LedgerEntry]: ...
def scan(self, start: int = 0, limit: int | None = None) -> AsyncIterator[LedgerEntry]: ...
async def leaf_hashes(self, up_to: int | None = None) -> list[str]: ...
async def latest_checkpoint(self) -> Checkpoint | None: ...
Requirements (each has a conformance test):
appendMUST be atomic on(log_id, seq). Use a native unique constraint / unique index / conditional write. Do not read-then- write — it races and the race silently forks the chain. On a taken sequence number, raiseapprovo.errors.LedgerConflict; the service catches it and retries against the new head (full-jitter backoff, thenConcurrencyExhausted).- Entries MUST NOT be mutable. Deny
UPDATE/DELETEto the app credential. approvo detects tampering regardless, but prevention beats detection. events_for_requestMUST be indexed on(log_id, request_id, seq). It is on the hot path of every status read.- Reads MUST return
seqorder;scanMUST stream (server-side cursor), becauseverify()walks the whole log. - Writes SHOULD be durable before returning. A rolled-back append
leaves a gap that
verify()correctly reports as tampering.
LedgerEntry serializes with .to_dict() / .from_dict() to plain
JSON-compatible types. Store entry.to_dict() as a JSON/JSONB column or
document; keep seq, request_id, event_type, and entry_hash as
separate indexed columns for query performance.
ProjectionStore¶
class ProjectionStore(Protocol):
async def upsert(self, view: RequestView) -> None: ...
async def get(self, request_id: str) -> RequestView | None: ...
async def query(self, query: RequestQuery) -> Page[RequestView]: ...
async def clear(self) -> None: ...
Requirements:
upsertMUST NOT move a view backwards — apply only when the incominglast_seq≥ the stored one. A conditional update does it.querySHOULD use keyset pagination, encoding its cursor in the opaquenext_cursorstring.RequestQueryfilters combine with AND; an unsupported filter SHOULD raise, not be silently ignored (returning unfiltered rows to an approvals screen is a security problem).
Don't need list screens? Use NullProjectionStore and skip the table
entirely. (ADR-0009)
IdempotencyStore¶
class IdempotencyStore(Protocol):
async def reserve(self, key: str, fingerprint: str) -> Reservation: ...
async def complete(self, key: str, response: dict) -> None: ...
async def release(self, key: str) -> None: ...
Requirements:
reserveMUST be atomic — returnwon=Trueto exactly one concurrent caller (insert-if-absent / conditional put). Others getwon=Falseplus the stored fingerprint and, once the winner callscomplete, the response.- A key reused with a different fingerprint MUST raise
IdempotencyConflict. - Rows MAY be TTL-expired. Pick a window well beyond your clients' retry budget — expiring early turns a replay into a real second append.
The conformance suite¶
# tests/test_my_stores.py
import pytest
from approvo.testing import (
EventStoreConformance, ProjectionStoreConformance, IdempotencyStoreConformance,
)
from myapp.approvo_stores import (
PgEventStore, PgProjectionStore, PgIdempotencyStore,
)
class TestPgEventStore(EventStoreConformance):
@pytest.fixture
async def event_store(self, pg_pool):
await pg_pool.execute("TRUNCATE approvo_ledger")
yield PgEventStore(pg_pool, log_id="test")
class TestPgProjectionStore(ProjectionStoreConformance):
@pytest.fixture
async def projection_store(self, pg_pool):
await pg_pool.execute("TRUNCATE approvo_request_view")
yield PgProjectionStore(pg_pool, log_id="test")
class TestPgIdempotencyStore(IdempotencyStoreConformance):
@pytest.fixture
async def idempotency_store(self, pg_pool):
await pg_pool.execute("TRUNCATE approvo_idempotency")
yield PgIdempotencyStore(pg_pool, log_id="test")
The suite includes concurrency tests (asyncio.gather of eight competing
appends / reserves expecting exactly one winner). Those exercise real
parallelism only against a real datastore over a pool — they pass
trivially against a single-connection store, which is why you run this
against the thing you actually deploy.
Requires pytest + pytest-asyncio (pip install approvo[dev]). Tests
are marked @pytest.mark.asyncio, so they work with or without
asyncio_mode = "auto".
Reference schema sketches¶
Not shipped as code — adapt to your migration tool.
PostgreSQL¶
CREATE TABLE approvo_ledger (
log_id text NOT NULL,
seq bigint NOT NULL,
entry_hash text NOT NULL,
prev_hash text NOT NULL,
event_type text NOT NULL,
request_id text,
recorded_at timestamptz NOT NULL,
entry jsonb NOT NULL,
PRIMARY KEY (log_id, seq) -- the concurrency control
);
CREATE INDEX ON approvo_ledger (log_id, request_id, seq)
WHERE request_id IS NOT NULL; -- the hot-path index
CREATE INDEX ON approvo_ledger (log_id, seq DESC)
WHERE event_type = 'checkpoint.published';
-- then: REVOKE UPDATE, DELETE ON approvo_ledger FROM <app_role>;
MongoDB¶
db.approvo_ledger.createIndex({ log_id: 1, seq: 1 }, { unique: true }) // concurrency control
db.approvo_ledger.createIndex(
{ log_id: 1, request_id: 1, seq: 1 },
{ partialFilterExpression: { request_id: { $type: "string" } } }) // hot-path index
db.approvo_ledger.createIndex({ log_id: 1, event_type: 1, seq: -1 })
// grant the app role insert + find only; use majority write concern
Map DuplicateKeyError / UniqueViolationError → LedgerConflict in
your append.
Runnable example¶
A complete MongoDB implementation of all three stores — plus a FastAPI
service and a scripted end-to-end walkthrough — lives in
examples/vehicle-release-approvals/
in the repository. It passes the conformance suite above against a real
mongod and is a good starting point for adapting to your own datastore.