Skip to content

0009. Platform-neutral ports with contract tests on every target

  • Status: Accepted
  • Date: 2026-11-08

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.

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/contracts holds one suite per port (for example describeProjectExecutor(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, and adapters/node-sqlite in Node. Concurrency contracts for adapters/postgres run 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.
  • 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-dependencies skill).
  • adapters/postgres joins the matrix before the open-source release; the contract API is fixed now so adding it needs no redesign.
  • Open: whether setAlarm called 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.