0009. Platform-neutral ports with contract tests on every target
- Status: Accepted
- Date: 2026-11-08
Context
Section titled “Context”Core must run unchanged on Cloudflare (Durable Objects, Queues, D1, R2) and in containers (Postgres, a jobs table or SQS, S3). Portability claims that are not tested drift. Local experiments (2026-11-07) showed that the Durable Object test helper runInDurableObject interleaves concurrent calls in a way a deployed DO does not, so tests must call DOs as production does.
Decision
Section titled “Decision”Core defines these ports. Core has no cloudflare:*, node:*, or platform globals.
| Port | Contract | Cloudflare | Container |
|---|---|---|---|
ProjectExecutor.execute(scope, command, input) |
Runs a named core command atomically. Commands for one project are serialized; different projects run in parallel. A command awaits only ProjectTx methods, never external I/O. A throw rolls back everything, including outbox and wake writes. |
RPC to the project’s DO, run inside ctx.storage.transaction(async …) |
BEGIN; SELECT pg_advisory_xact_lock(hash(project)), row-level security with SET LOCAL app.project_id |
ProjectTx |
Project-scoped repositories; methods take no project ID | DO SQLite | Postgres rows carrying project_id |
ProjectTx.wakeAt(t) |
Registered atomically with state. Fires no earlier than t, at least once, coalesced to the earliest time; firing runs the tick command |
wake_at rows plus the DO alarm (ADR 0011) |
project_wakeups row polled with FOR UPDATE SKIP LOCKED |
ProjectTx.outbox(job) + DeliveryQueue |
Outbox rows commit with state; delivery is at least once; consumers are idempotent | outbox drained to Queues | jobs table with SKIP LOCKED (default) or SQS |
DeliveryRateLimiter.acquire(bucket, n) |
Token bucket; never exceeds the configured rate; a denial returns retry-after | token-bucket DO | Postgres row with FOR UPDATE |
ControlStore |
Fixed cross-project lookups (key hash, source ID, tracking host → project), workspaces, users, roll-ups | D1 | Postgres control schema |
BlobStore |
put, get, list | R2 | S3 or filesystem |
SecretProvider |
getKey(kid) |
Workers secrets | Secrets Manager or environment variables |
OutboundHttp |
The SSRF rules in docs/architecture.md | fetch (Workers egress) |
undici with a resolver-pinned address check |
EmailProvider |
send, verifyWebhook, normalizeEvents, capabilities (ADR 0024) |
SES | SES |
SystemMailer |
Sends operator system mail (sign-in codes, notifications), separate from workspace sends (ADR 0029) | Cloudflare Email Service | SMTP or SES configured by the self-hoster |
Clock, IdGenerator, Signer, SecretCipher |
Injectable time and IDs; HMAC signing; AEAD encryption | WebCrypto | WebCrypto |
Contract tests:
testing/contractsholds one suite per port (for exampledescribeProjectExecutor(factory)). Every adapter of a port runs the same suite.- Cases include: commands on one project never interleave and two projects run in parallel; rollback covers outbox and wake writes; a wake never fires early, fires at least once, and coalesces; outbox delivery is at least once and a duplicate job is a no-op; a project transaction cannot read another project’s rows; the clock is injectable; the rate limiter never exceeds its rate; timezone golden files match (ADR 0016); the email adapter handles “accepted, then connection reset” as
unknown. - Durable Objects are called through their stubs, never through
runInDurableObject. - On every pull request: Cloudflare adapters in Miniflare through
@cloudflare/vitest-plugin, andadapters/node-sqlitein Node. Concurrency contracts foradapters/postgresrun on a real Postgres; PGlite is used only for repository tests. - Nightly: the contract suite against a deployed Cloudflare environment, including DO eviction and crash cases.
Consequences
Section titled “Consequences”- A new platform feature starts as a port with a contract test, then is implemented in every adapter.
- A port change updates every adapter in the matrix in the same pull request (see the
check-dependenciesskill). adapters/postgresjoins the matrix before the open-source release; the contract API is fixed now so adding it needs no redesign.- Open: whether
setAlarmcalled inside the transaction callback commits atomically with the transaction on a deployed DO, and whether deployed DO serialization matches the Miniflare results. The nightly deployed suite verifies both; ADR 0011 has a backstop that does not depend on the answer.