Cache, counter & storage

Three small key-addressed contracts. The cache is read-through key/value with TTLs (Caching); the counter is an atomic monotonic sequence; object storage holds blobs by key. The ports-and-adapters model behind them is in Contracts.

Cache¶

ctx.cache(spec) returns a combined read/write CachePort. Keys are strings within the spec's namespace. Values must be JSON-serializable, or pre-encoded bytes (stored verbatim, returned for the caller to decode) — don't rely on key ordering or non-JSON types surviving a round trip.

CacheSpec — most fields tune document read-through; the deep behavior is in Caching:

TTLs default from the CacheSpec; the per-entry ttl= overrides that entry's lifetime alone (the seam the adaptive lifetimes write through). See Cache reads with Redis.

Counter¶

ctx.counter(spec) returns a CounterPort — an atomic sequence within the spec's namespace (CounterSpec carries only a name). suffix partitions counters under one spec.

There is no read verb, deliberately: a counter's value is only meaningful at the instant it is allocated, so a handler that read one would be holding a number another allocation has already moved past. Allocate and use the value you were given.

What every backend guarantees¶

These hold identically on Postgres, MongoDB, Redis, Firestore and the in-memory mock, because one shared conformance battery asserts them against each:

• an untouched counter reads as 0, so the first incr() returns 1;
• values are signed 64-bit. An allocation or reset that would leave that range is refused and the stored value is unchanged — never wrapped, never clamped. A reset is checked before it is stored, so it cannot succeed and break the next allocation;
• counters are not required to be non-negative: decr below zero is legal, and a negative by is an ordinary decrease;
• incr(by=0) returns the current value without moving it — the one read the port offers. It still creates the counter at 0 if it did not exist.

The value domain is the reason the mock enforces a bound it could easily exceed: a mock that accepts allocations no real store can hold certifies bugs instead of catching them. One residue is deliberate and worth knowing — when an allocation (not a reset) crosses the boundary, the refusal comes from the store itself, so its error kind is the backend's own. What is uniform is that it refuses and changes nothing.

Allocations also never join the caller's transaction — on every backend (Redis, Postgres, Mongo, Firestore) the statement runs on its own connection, so a rolled-back transaction does not hand the number back. A sequence that could roll back would reissue a number already given out; gaps are the correct trade. Implementers of the Postgres, Mongo and Firestore client ports must preserve this.

Backends: Redis, Postgres, Mongo, Firestore, mock. Postgres needs an app-migrated counter table.

Enumerating counters (admin)¶

ctx.counter.admin(spec) returns a CounterAdminPort. It exists because the missing read verb, correct as it is for handlers, left counters as the one plane that is durable state nothing can read — so a migration that faithfully rebuilt every other plane would restart the counters at zero and reissue invoice numbers already in customers' hands, with no error anywhere to say so.

Both properties hold at once: handlers still cannot read a counter (the admin port is a separate acquisition, and it cannot allocate), while operators and a portable export can. suffix=None is a real partition — the unsuffixed counter — not an absent one.

Carrying counters to another deployment needs no new write verb; reset is already it:

for entry in await source.counter.admin(INVOICES).list_counters():
    await target.counter(INVOICES).reset(entry.value, suffix=entry.suffix)

The value is the last number handed out, so the target's next incr continues the sequence rather than repeating its final number. Enumerate a counter you intend to carry only when nothing is allocating from it (a stopped fleet) — a value read while the source is live is stale the moment it is read. The whole set is returned at once, so a spec partitioned into millions of suffixes is not yet in scope.

Storage¶

Object storage splits into query and command ports — ctx.storage.query(spec) / ctx.storage.command(spec) (StorageSpec carries only a name). Objects are addressed by string key.

A third port, StorageUploadSessionPort, drives resumable multipart uploads (begin / presign part / list parts / complete / abort) — its HTTP projection is on the FastAPI route generators page. Ranged reads work over chunked-AEAD encrypted objects (only the covering chunks are fetched and decrypted); a legacy whole-payload envelope cannot be sliced and refuses with core.storage.range_whole_payload_unsupported.

Implemented by¶

The in-memory mock implements all three for tests.