From b46e9445236dcf64bcc2c80bc38ccb6053b79d56 Mon Sep 17 00:00:00 2001 From: Daniel Bannert Date: Sat, 1 Aug 2026 17:04:29 +0200 Subject: [PATCH 1/3] =?UTF-8?q?fix(platform):=20rate=20node=20scheduler=20?= =?UTF-8?q?and=20alarms=20unsupported=20=E2=80=94=20jobs=20are=20never=20d?= =?UTF-8?q?ispatched?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Node host's scheduler and shard-alarm timers only ever clear their own bookkeeping on fire — nothing dispatches the scheduled function or wakes an alarm callback. Rating both "emulated" let codegen's fail-closed gate pass ctx.scheduler through silently for target: "node" apps whose scheduled work would never run; "emulated" means built on lower-level primitives and working, which never-dispatched is not. Flip both to "unsupported" in NODE_CAPABILITIES so codegen omits the surface and emits platform_unsupported_feature instead. Drop the scheduler's deadLetter member (and simulateDeadLetter): its presence is the contract's documented at-least-once claim, and this host cannot back it. Document that shardAlarms has no CapabilityKey to gate through codegen's usage map — it is engine-internal, never an app import — so the rating exists for Studio parity reporting rather than codegen gating. Update the codegen golden test to expect scheduler gated off. --- .../codegen/__tests__/platform-target.test.ts | 15 ++- packages/codegen/src/platform-target.ts | 9 ++ .../platform-node/src/conformance/index.ts | 3 +- .../platform-node/src/node-scheduler-host.ts | 95 +++++++------------ packages/platform/src/capabilities.ts | 18 ++-- 5 files changed, 67 insertions(+), 73 deletions(-) diff --git a/packages/codegen/__tests__/platform-target.test.ts b/packages/codegen/__tests__/platform-target.test.ts index 7f241331dc..19ba777116 100644 --- a/packages/codegen/__tests__/platform-target.test.ts +++ b/packages/codegen/__tests__/platform-target.test.ts @@ -144,24 +144,29 @@ describe("gatePlatformFeatures", () => { // through the actual registry lookup — the thing `platformMatrixIds` // reports and `resolveCodegenTarget`/`lunora.json`'s `target` field select. it("gates a project declaring an unsupported ctx.* for the node target", async () => { - expect.assertions(4); + expect.assertions(5); const { gatePlatformFeatures } = await import("../src/platform-target"); // `browser` and `container` are rated "unsupported" for node // (`NODE_CAPABILITIES` — no headless-browser or container binding is - // implemented by `@lunora/platform-node`); `kv` and `scheduler` are - // rated "emulated" (a real, if non-durable, better-sqlite3-backed - // implementation), so they must survive gating unchanged. + // implemented by `@lunora/platform-node`); as of plan 267, `scheduler` + // is ALSO rated "unsupported" — the Node host stores and times jobs but + // never dispatches them, so codegen must gate it off the same as + // `browser`/`container`. `kv` stays rated "emulated" (a real, if + // non-durable, better-sqlite3-backed implementation), so it must + // survive gating unchanged. const usage: FeatureUsage = { ...ALL_OFF, browser: true, container: true, kv: true, scheduler: true }; const result = gatePlatformFeatures(usage, "node"); expect(result.usage.browser).toBe(false); expect(result.usage.container).toBe(false); - expect({ kv: result.usage.kv, scheduler: result.usage.scheduler }).toStrictEqual({ kv: true, scheduler: true }); + expect(result.usage.scheduler).toBe(false); + expect(result.usage.kv).toBe(true); expect(result.diagnostics.map((diagnostic) => diagnostic.feature).toSorted((a, b) => String(a).localeCompare(String(b)))).toStrictEqual([ "browser", "container", + "scheduler", ]); }); }); diff --git a/packages/codegen/src/platform-target.ts b/packages/codegen/src/platform-target.ts index d197de11e3..c784641e8a 100644 --- a/packages/codegen/src/platform-target.ts +++ b/packages/codegen/src/platform-target.ts @@ -153,6 +153,15 @@ type PlatformFeatureKey = keyof PlatformCapabilities["features"]; * app-level add-on with no platform-portability meaning (feature flags, the * Cloudflare-Access identity facade, Cloudflare Images, R2 SQL, payments, * x402) — never gated, always emitted, on every target. + * + * `shardAlarms` is deliberately unmapped here, and not because it was + * forgotten: `CapabilityKey` is derived from `CAPABILITY_ROWS`, which + * enumerates app-imported `ctx.*` add-on modules, and there is no such usage + * key for alarms because they are an engine-internal contract member, never + * something an app imports. There is nothing for this map to gate on. Its + * `PlatformCapabilities` rating still matters for Studio parity reporting and + * any future target-level check — see its `shardAlarms` entry in the Node + * capability matrix (`NODE_CAPABILITIES` in `@lunora/platform`, plan 267). */ const CAPABILITY_TO_FEATURE: Partial> = { ai: "ai", diff --git a/packages/platform-node/src/conformance/index.ts b/packages/platform-node/src/conformance/index.ts index a44cfde957..59b895ce91 100644 --- a/packages/platform-node/src/conformance/index.ts +++ b/packages/platform-node/src/conformance/index.ts @@ -28,7 +28,7 @@ export const createNodeConformanceHost = (): ConformanceHost => { const kv = createNodeShardKvStore(database); const directory = createNodeShardDirectory(); const { readFrames, restoreSocket, simulateRecycle, socket } = createNodeSocketHost(); - const { dispose: disposeScheduler, scheduler, simulateDeadLetter } = createNodeSchedulerHost(); + const { dispose: disposeScheduler, scheduler } = createNodeSchedulerHost(); return { awaitAlarmFired: async (target) => { @@ -57,7 +57,6 @@ export const createNodeConformanceHost = (): ConformanceHost => { restoreSocket, scheduler, shard, - simulateDeadLetter, simulateRecycle, socket, }; diff --git a/packages/platform-node/src/node-scheduler-host.ts b/packages/platform-node/src/node-scheduler-host.ts index fbf5c20414..f4557ea7fe 100644 --- a/packages/platform-node/src/node-scheduler-host.ts +++ b/packages/platform-node/src/node-scheduler-host.ts @@ -4,16 +4,23 @@ * * **This is the one contract this package cannot honestly hold as "hardened * toward a real implementation."** `SchedulerHost`'s docstring promises - * "durable persistence — scheduled jobs survive host recycling." On - * Cloudflare, `SchedulerDO` backs this with alarms on Durable Object storage: - * the platform re-delivers an alarm to a freshly-woken DO even after the - * process that scheduled it is long gone. A plain Node process has no - * equivalent — nothing re-arms a `setTimeout` after `node` restarts, and there - * is no host-level daemon to hand that job to. Persisting the job row to - * SQLite without something to re-arm it on process start would be *worse* than - * this in-memory implementation: it would report a job as "pending" forever - * after a restart that will in fact never fire. This is filed as a finding, - * not silently worked around — see `plans/234-node-host-findings.md`. + * "durable persistence — scheduled jobs survive host recycling" and, through + * its optional dead-letter member, at-least-once delivery. On Cloudflare, + * `SchedulerDO` backs both with alarms on Durable Object storage: the + * platform re-delivers an alarm to a freshly-woken DO even after the process + * that scheduled it is long gone. This host has neither: nothing re-arms a + * `setTimeout` after `node` restarts and there is no host-level daemon to hand + * that job to, AND its armed timer never dispatches the scheduled function at + * all — the timer body is bookkeeping deletion, not delivery. Persisting the + * job row to SQLite without something to re-arm it on process start would be + * worse than this in-memory implementation: it would report a job as + * "pending" forever after a restart that will in fact never fire. Per plan + * 267, this host's `scheduler` entry in the Node capability matrix is rated + * `"unsupported"` (not `"emulated"`) precisely because jobs are never + * dispatched, and the contract's dead-letter member — the documented + * at-least-once claim — is omitted below rather than declared falsely. This + * is filed as a finding, not silently worked around — see + * `plans/234-node-host-findings.md`. * * `cron` is omitted, matching Cloudflare (whose crons are declared in * `wrangler.jsonc`, not registered at runtime) — but for the opposite reason: @@ -34,29 +41,25 @@ interface NodeJob { timer: ReturnType | undefined; } -/** - * Test-only hook the TCK's dead-letter legs need: force a pending job straight - * to "exhausted its retry budget" without waiting out a real retry schedule. - */ export interface NodeSchedulerHost { /** * Clear every `setTimeout` this host has armed (every job still in - * `pending`). Dead-lettered jobs never carry a live timer — their `timer` - * is always `undefined` by the time they land in `dead` — so this only - * needs to walk `pending`. Call it on teardown: an armed job timer is a - * handle that keeps the event loop (and, transitively, the process) alive - * until it fires, so leaving it uncleared on shutdown is what produces the - * "worker process failed to exit gracefully" delay. + * `pending`), and put the host into a terminal, closed state: after this + * runs, `schedule()` throws instead of arming a fresh timer nothing would + * ever clear (the exact handle-leak class this disposer exists to + * eliminate). Call it on teardown: an armed job timer is a handle that + * keeps the event loop (and, transitively, the process) alive until it + * fires, so leaving it uncleared on shutdown is what produces the "worker + * process failed to exit gracefully" delay. */ dispose: () => void; scheduler: SchedulerHost; - simulateDeadLetter: (id: string) => Promise; } /** Build the in-process scheduler. */ export const createNodeSchedulerHost = (): NodeSchedulerHost => { const pending = new Map(); - const dead = new Map(); + let closed = false; let counter = 0; const nextId = (): string => { @@ -80,6 +83,10 @@ export const createNodeSchedulerHost = (): NodeSchedulerHost => { const job = pending.get(id); if (job === undefined) { + // Also covers "closed": `dispose()` empties `pending`, so a + // cancel after close answers `false` for the same reason a + // cancel of an unknown id does — no throw needed, since this + // keeps teardown-order races benign (see `NodePlatform.close()`). return false; } @@ -88,33 +95,14 @@ export const createNodeSchedulerHost = (): NodeSchedulerHost => { return true; }, - deadLetter: { - // eslint-disable-next-line @typescript-eslint/require-await -- see `cancel` - list: async () => [...dead].map(([id, job]) => toStatus(id, job)), - // eslint-disable-next-line @typescript-eslint/require-await -- see `cancel` - requeue: async (id) => { - const job = dead.get(id); - - if (job === undefined) { - return false; - } - - dead.delete(id); - // A fresh attempt budget is the point of a requeue — see the - // `SchedulerHost.deadLetter` docstring. Note the job is NOT - // re-armed with a live `setTimeout` here: it re-enters `pending` - // with its original `scheduledFor`, which is almost certainly in - // the past by the time an operator requeues it. That mirrors "due - // immediately" rather than firing an already-elapsed timer. - pending.set(id, { ...job, attempts: 0, timer: undefined }); - - return true; - }, - }, // eslint-disable-next-line @typescript-eslint/require-await -- see `cancel` list: async () => [...pending].map(([id, job]) => toStatus(id, job)), // eslint-disable-next-line @typescript-eslint/require-await -- see `cancel` schedule: async (functionPath, args, options) => { + if (closed) { + throw new Error("platform closed: cannot schedule a job"); + } + const id = nextId(); let scheduledFor: number; @@ -140,21 +128,10 @@ export const createNodeSchedulerHost = (): NodeSchedulerHost => { for (const job of pending.values()) { clearTimeout(job.timer); } - }, - scheduler, - // eslint-disable-next-line @typescript-eslint/require-await -- see `cancel` - simulateDeadLetter: async (id) => { - const job = pending.get(id); - - if (job === undefined) { - return false; - } - clearTimeout(job.timer); - pending.delete(id); - dead.set(id, { ...job, attempts: (job.options.retry?.maxAttempts ?? 5) + 1, timer: undefined }); - - return true; + pending.clear(); + closed = true; }, + scheduler, }; }; diff --git a/packages/platform/src/capabilities.ts b/packages/platform/src/capabilities.ts index 25eb1c01d6..a0eb7d2a93 100644 --- a/packages/platform/src/capabilities.ts +++ b/packages/platform/src/capabilities.ts @@ -133,9 +133,13 @@ export const CLOUDFLARE_CAPABILITIES: PlatformCapabilities = { * a SQL table wearing a KV-shaped API, not a dedicated KV product, and * `websocketHibernation` never actually evicts a socket to save memory — it * only proves the attachment/tag durability half of the contract, not real - * hibernation. Both ratings, and the `"unsupported"` ones for `scheduler` - * durability and `globalTables`, are argued in detail in - * `plans/234-node-host-findings.md`. + * hibernation. `scheduler` and `shardAlarms` are rated `"unsupported"`, not + * `"emulated"`: the Node host stores and times both, but its timer body only + * clears bookkeeping — nothing dispatches the scheduled function or wakes the + * alarm callback. `"emulated"` means built on lower-level primitives and + * working; never-dispatched is not that (plan 267). `globalTables` is also + * `"unsupported"` — no replicated SQL store is implemented. All ratings are + * argued in detail in `plans/234-node-host-findings.md`. */ export const NODE_CAPABILITIES: PlatformCapabilities = { id: "node", @@ -149,15 +153,15 @@ export const NODE_CAPABILITIES: PlatformCapabilities = { }, localSql: { level: "native", note: "better-sqlite3 (synchronous, embedded)" }, shardAlarms: { - level: "emulated", - note: "In-process setTimeout; the timestamp can be persisted to SQLite but nothing re-arms it on process restart", + level: "unsupported", + note: "In-process bookkeeping only — the armed timer clears state and never wakes anything; no dispatch, and nothing re-arms across a restart", }, crossShardFanout: { level: "unsupported", note: "No query coordinator / relay tier implemented" }, queues: { level: "unsupported", note: "No Cloudflare Queues equivalent implemented" }, workflows: { level: "unsupported", note: "No Cloudflare Workflows equivalent implemented" }, scheduler: { - level: "emulated", - note: "In-process setTimeout only; not durable across a process restart, and no dynamic cron registration is implemented", + level: "unsupported", + note: "Jobs are stored and timed but never dispatched — no delivery, no retries; also not durable across a process restart", }, objectStorage: { level: "unsupported", note: "No R2/S3-equivalent binding implemented" }, keyValueStore: { level: "emulated", note: "better-sqlite3 table behind the ShardKvStore API — not a dedicated KV product" }, From a4e126dae8fbcc8cc1cf03437fc5607043b2ea93 Mon Sep 17 00:00:00 2001 From: Daniel Bannert Date: Sat, 1 Aug 2026 17:04:42 +0200 Subject: [PATCH 2/3] fix(platform-node): make close() terminal and serialize transaction MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two latent lifecycle/correctness bugs in the Node host, both hardened here together since they share node-shard-host.ts: - close() was not a terminal state: after tearing a NodePlatform down, scheduler.schedule() armed a fresh setTimeout nothing would ever clear, scheduler.list()/cancel() kept reporting stale jobs, and alarms.set() mutated in-memory state before throwing on the closed connection. Every mutating call now checks closed-ness first (the connection's own open state for alarms, a dedicated flag for the scheduler) and throws before any mutation; reads/cancels answer emptied/false rather than throwing, so teardown-order races stay benign. - transaction() ran raw BEGIN/COMMIT/ROLLBACK directly against the shared connection with no serialization of its own. Two overlapping transaction() calls could throw "cannot start a transaction within a transaction" or, worse, let one's COMMIT commit the other's uncommitted writes. Routing transaction through the existing runSerialized queue would deadlock (the engine already composes runSerialized(() => transaction(work))), so this adds a second, private transactionTail chain of the identical shape, used only by transaction — bare overlapping calls now serialize against each other instead of corrupting commits, and the engine's composition stays deadlock-free. Same fix applied to the reference host, which has the identical shape. New lifecycle legs and a transaction-concurrency test on both hosts; each was confirmed to fail against the pre-fix code (stashed and re-run) before this commit. --- .../platform-node/__tests__/lifecycle.test.ts | 55 +++++++++++++ .../__tests__/transaction-concurrency.test.ts | 80 +++++++++++++++++++ packages/platform-node/src/node-platform.ts | 12 +++ packages/platform-node/src/node-shard-host.ts | 55 ++++++++++++- .../reference-host-transaction.test.ts | 77 ++++++++++++++++++ .../src/conformance/reference-host.ts | 29 ++++++- 6 files changed, 305 insertions(+), 3 deletions(-) create mode 100644 packages/platform-node/__tests__/transaction-concurrency.test.ts create mode 100644 packages/platform/__tests__/reference-host-transaction.test.ts diff --git a/packages/platform-node/__tests__/lifecycle.test.ts b/packages/platform-node/__tests__/lifecycle.test.ts index 3a7e6e1fa7..c1d848618e 100644 --- a/packages/platform-node/__tests__/lifecycle.test.ts +++ b/packages/platform-node/__tests__/lifecycle.test.ts @@ -197,5 +197,60 @@ describe("lifecycle disposers", () => { expect(readdirSync(workdir)).toContain("platform.sqlite3"); }); + + it("makes schedule() throw instead of arming a fresh, never-cleared timer", async () => { + expect.assertions(2); + + vi.useFakeTimers(); + + try { + const platform = createNodePlatform(); + + platform.close(); + + await expect(platform.scheduler.schedule("some/fn", {}, { delayMs: 5000 })).rejects.toThrow("platform closed"); + expect(vi.getTimerCount()).toBe(0); + } finally { + vi.useRealTimers(); + } + }); + + it("reports no pending jobs and refuses to cancel a pre-close job once closed", async () => { + expect.assertions(2); + + vi.useFakeTimers(); + + try { + const platform = createNodePlatform(); + + const { id } = await platform.scheduler.schedule("some/fn", {}, { delayMs: 5000 }); + + platform.close(); + + // `list` is optional on the contract (a host may omit it); this + // host always implements it — see `createNodeSchedulerHost`. + await expect(platform.scheduler.list?.()).resolves.toStrictEqual([]); + await expect(platform.scheduler.cancel(id)).resolves.toBe(false); + } finally { + vi.useRealTimers(); + } + }); + + it("makes alarms.set() throw before mutating state, leaving get() reporting no alarm", async () => { + expect.assertions(2); + + vi.useFakeTimers(); + + try { + const platform = createNodePlatform(); + + platform.close(); + + expect(() => platform.shard.alarms.set(Date.now() + 1000)).toThrow("platform closed"); + expect(platform.shard.alarms.get()).toBeNull(); + } finally { + vi.useRealTimers(); + } + }); }); }); diff --git a/packages/platform-node/__tests__/transaction-concurrency.test.ts b/packages/platform-node/__tests__/transaction-concurrency.test.ts new file mode 100644 index 0000000000..4ffe23e07d --- /dev/null +++ b/packages/platform-node/__tests__/transaction-concurrency.test.ts @@ -0,0 +1,80 @@ +import { describe, expect, it } from "vitest"; + +import { createNodeShardHost } from "../src/node-shard-host"; + +/** + * Plan 267 §4/§5 (S4): `transaction` runs raw `BEGIN`/`COMMIT`/`ROLLBACK` + * against a single shared connection. Two overlapping `transaction()` calls + * used to race that connection directly — the second `BEGIN` while the first + * was still open either threw `cannot start a transaction within a + * transaction` or, worse, silently interleaved commits/rollbacks. This pins + * the fix: a dedicated `transactionTail` serialization lane, distinct from + * `runSerialized`'s own tail (routing through the same one would deadlock the + * engine's `runSerialized(() => transaction(work))` composition). + */ +describe("createNodeShardHost transaction concurrency", () => { + const sleep = (ms: number): Promise => + new Promise((resolve) => { + setTimeout(resolve, ms); + }); + + it("serializes two overlapping bare transaction() calls instead of corrupting each other's commits", async () => { + expect.assertions(1); + + const { dispose, host } = createNodeShardHost(); + + try { + host.sql.exec("CREATE TABLE rows_ (id TEXT PRIMARY KEY)"); + + const first = host.transaction(async () => { + host.sql.exec("INSERT INTO rows_ (id) VALUES ('A')"); + + await sleep(20); + + host.sql.exec("INSERT INTO rows_ (id) VALUES ('B')"); + }); + + // Started without awaiting `first` — this is the overlap that + // corrupts an un-serialized raw BEGIN/COMMIT. + const second = host.transaction(async () => { + host.sql.exec("INSERT INTO rows_ (id) VALUES ('C')"); + }); + + await Promise.all([first, second]); + + const rows = host.sql.exec<{ id: string }>("SELECT id FROM rows_ ORDER BY id").toArray(); + + expect(rows.map((row) => row.id)).toStrictEqual(["A", "B", "C"]); + } finally { + dispose(); + } + }); + + it("rolls back only the throwing transaction's own writes, leaving earlier committed rows intact", async () => { + expect.assertions(2); + + const { dispose, host } = createNodeShardHost(); + + try { + host.sql.exec("CREATE TABLE rows_ (id TEXT PRIMARY KEY)"); + + await host.transaction(async () => { + host.sql.exec("INSERT INTO rows_ (id) VALUES ('A')"); + }); + + await expect( + host.transaction(async () => { + host.sql.exec("INSERT INTO rows_ (id) VALUES ('D')"); + + throw new Error("boom"); + }), + ).rejects.toThrow("boom"); + + const rows = host.sql.exec<{ id: string }>("SELECT id FROM rows_ ORDER BY id").toArray(); + + expect(rows.map((row) => row.id)).toStrictEqual(["A"]); + } finally { + dispose(); + } + }); +}); diff --git a/packages/platform-node/src/node-platform.ts b/packages/platform-node/src/node-platform.ts index 191f5a1b47..eb285a3ad0 100644 --- a/packages/platform-node/src/node-platform.ts +++ b/packages/platform-node/src/node-platform.ts @@ -39,6 +39,18 @@ export interface NodePlatform { * its own — a `NodePlatform` a caller stops using without calling `close()` * leaks the open file handle (plus its WAL/SHM sidecar files) and keeps * the process alive on outstanding timers. Safe to call more than once. + * + * **`close()` is a terminal state, not merely a cleanup step.** After it + * runs: `scheduler.schedule()` throws instead of arming a fresh timer + * nothing would ever clear; `scheduler.list()` returns `[]` and + * `scheduler.cancel()` answers `false` (the job map is empty, so this + * happens naturally, without a throw — keeping teardown-order races + * benign); `shard.alarms.set()`/`delete()` throw before mutating any + * in-memory state (checked against the connection's own open/closed state, + * the single source of truth); `shard.alarms.get()` keeps answering + * whatever it last held. A no-op instead of a throw would be + * indistinguishable from a working call — exactly the silent-vanishing + * this lifecycle exists to end. */ close: () => void; /** In-process shard directory (see `createNodeShardDirectory`'s docstring for what it cannot do). */ diff --git a/packages/platform-node/src/node-shard-host.ts b/packages/platform-node/src/node-shard-host.ts index ec0415ac0a..5a827c5383 100644 --- a/packages/platform-node/src/node-shard-host.ts +++ b/packages/platform-node/src/node-shard-host.ts @@ -139,6 +139,14 @@ const createAlarms = (database: Database.Database): { alarms: ShardAlarms; dispo const alarms: ShardAlarms = { delete: () => { + // The connection's own open state IS closed-ness (see the module + // docstring below and `dispose`'s callback comment) — checked + // BEFORE any mutation, so a closed platform's alarm state is never + // touched by a call that is about to throw. + if (!database.open) { + throw new Error("platform closed: cannot delete an alarm"); + } + alarmAt = undefined; clearAlarmTimeout(); persist(undefined); @@ -149,6 +157,10 @@ const createAlarms = (database: Database.Database): { alarms: ShardAlarms; dispo // eslint-disable-next-line unicorn/no-null -- platform contract uses null get: () => alarmAt ?? null, set: (timestamp: number | Date) => { + if (!database.open) { + throw new Error("platform closed: cannot set an alarm"); + } + const ms = typeof timestamp === "number" ? timestamp : timestamp.getTime(); alarmAt = ms; @@ -211,7 +223,14 @@ interface NodeShardHostOptions { * inside a Cloudflare Durable Object, where the runtime forbids it and * callers must use `storage.transaction`) because better-sqlite3 is a plain * embedded database with no platform-level transaction primitive layered over - * it. + * it. It runs on its own private `transactionTail` chain, the same shape as + * `runSerialized`'s but never shared with it: two bare, overlapping + * `transaction()` calls on this host serialize against each other rather than + * corrupting each other's commits (raw `BEGIN` on a connection already inside + * a transaction throws, or worse, interleaves). Routing `transaction` through + * `runSerialized` itself would deadlock, since the engine already composes + * `runSerialized(() => transaction(work))` — the inner enqueue would then wait + * on the outer closure awaiting it. * * The returned `dispose()` is this host's lifecycle owner: it clears the * pending alarm `setTimeout` (so it can never fire against a connection this @@ -243,7 +262,25 @@ const createNodeShardHost = (options: NodeShardHostOptions = {}): { database: Da return started; }; - const transaction: ShardHost["transaction"] = async (function_) => { + // A second, private tail chain of the exact same shape as `runSerialized` + // above, used ONLY by `transaction`. Raw BEGIN/COMMIT/ROLLBACK on a shared + // connection is not safe under overlap — a second `transaction()` call + // that starts before the first commits either throws "cannot start a + // transaction within a transaction" on the second BEGIN, or (worse) its + // COMMIT commits the first's uncommitted writes and the first's ROLLBACK + // then discards work that already reported success. + // + // Routing `transaction` through the SAME `runSerialized`/`tail` chain + // would deadlock: the engine composes them as + // `runSerialized(() => transaction(work))` (`shard-runner.ts`), so the + // inner enqueue would wait on the outer closure that is awaiting it. This + // dedicated lane serializes bare, overlapping `transaction()` calls + // against each other (the actual bug) while leaving `runInTransaction`'s + // composition free of self-deadlock (the outer gate is `runSerialized`, + // the inner lane is always empty when it runs). + let transactionTail: Promise = Promise.resolve(); + + const runTransaction = async (function_: () => Promise): Promise => { database.exec("BEGIN"); try { @@ -258,6 +295,20 @@ const createNodeShardHost = (options: NodeShardHostOptions = {}): { database: Da } }; + const transaction: ShardHost["transaction"] = (function_: () => Promise): Promise => { + const started = transactionTail.then( + () => runTransaction(function_), + () => runTransaction(function_), + ); + + transactionTail = started.then( + () => undefined, + () => undefined, + ); + + return started; + }; + const host: ShardHost = { alarms, asyncSql, diff --git a/packages/platform/__tests__/reference-host-transaction.test.ts b/packages/platform/__tests__/reference-host-transaction.test.ts new file mode 100644 index 0000000000..8d5920c812 --- /dev/null +++ b/packages/platform/__tests__/reference-host-transaction.test.ts @@ -0,0 +1,77 @@ +import { describe, expect, it } from "vitest"; + +import { createReferenceHost } from "../src/conformance"; + +/** + * Plan 267 §4/§5 (S4): the `node:sqlite` reference host has the identical + * raw-BEGIN/COMMIT/ROLLBACK shape as `@lunora/platform-node`'s shard host, and + * the identical un-serialized-overlap bug. This is the reference host's + * sibling of `packages/platform-node/__tests__/transaction-concurrency.test.ts` + * — same assertions, same dedicated `transactionTail` lane fix. + */ +describe("createReferenceHost transaction concurrency", () => { + const sleep = (ms: number): Promise => + new Promise((resolve) => { + setTimeout(resolve, ms); + }); + + it("serializes two overlapping bare transaction() calls instead of corrupting each other's commits", async () => { + expect.assertions(1); + + const host = createReferenceHost(); + + try { + host.shard.sql.exec("CREATE TABLE rows_ (id TEXT PRIMARY KEY)"); + + const first = host.shard.transaction(async () => { + host.shard.sql.exec("INSERT INTO rows_ (id) VALUES ('A')"); + + await sleep(20); + + host.shard.sql.exec("INSERT INTO rows_ (id) VALUES ('B')"); + }); + + // Started without awaiting `first` — this is the overlap that + // corrupts an un-serialized raw BEGIN/COMMIT. + const second = host.shard.transaction(async () => { + host.shard.sql.exec("INSERT INTO rows_ (id) VALUES ('C')"); + }); + + await Promise.all([first, second]); + + const rows = host.shard.sql.exec<{ id: string }>("SELECT id FROM rows_ ORDER BY id").toArray(); + + expect(rows.map((row) => row.id)).toStrictEqual(["A", "B", "C"]); + } finally { + host.cleanup?.(); + } + }); + + it("rolls back only the throwing transaction's own writes, leaving earlier committed rows intact", async () => { + expect.assertions(2); + + const host = createReferenceHost(); + + try { + host.shard.sql.exec("CREATE TABLE rows_ (id TEXT PRIMARY KEY)"); + + await host.shard.transaction(async () => { + host.shard.sql.exec("INSERT INTO rows_ (id) VALUES ('A')"); + }); + + await expect( + host.shard.transaction(async () => { + host.shard.sql.exec("INSERT INTO rows_ (id) VALUES ('D')"); + + throw new Error("boom"); + }), + ).rejects.toThrow("boom"); + + const rows = host.shard.sql.exec<{ id: string }>("SELECT id FROM rows_ ORDER BY id").toArray(); + + expect(rows.map((row) => row.id)).toStrictEqual(["A"]); + } finally { + host.cleanup?.(); + } + }); +}); diff --git a/packages/platform/src/conformance/reference-host.ts b/packages/platform/src/conformance/reference-host.ts index a0880f7803..767d4cee23 100644 --- a/packages/platform/src/conformance/reference-host.ts +++ b/packages/platform/src/conformance/reference-host.ts @@ -282,7 +282,20 @@ const createReferenceHost = (): ReferenceHost => { drainQueue(); }); - const transaction: ShardHost["transaction"] = async (function_) => { + // A second, private tail chain of the same shape as `runSerialized`'s + // `shardState.pending`/`drainQueue`, used ONLY by `transaction`. Raw + // BEGIN/COMMIT/ROLLBACK on a shared connection is not safe under overlap: + // a second `transaction()` call that starts before the first commits + // either throws on the second BEGIN, or its COMMIT commits the first's + // uncommitted writes and the first's ROLLBACK then discards work that + // already reported success. Routing `transaction` through the same + // `runSerialized` queue would deadlock (the engine composes + // `runSerialized(() => transaction(work))`), so this is a dedicated lane + // — see `@lunora/platform-node`'s `node-shard-host.ts`, which has the + // identical shape and the identical reasoning (plan 267). + let transactionTail: Promise = Promise.resolve(); + + const runTransaction = async (function_: () => Promise): Promise => { database.exec("BEGIN"); try { const result = await function_(); @@ -295,6 +308,20 @@ const createReferenceHost = (): ReferenceHost => { } }; + const transaction: ShardHost["transaction"] = (function_: () => Promise): Promise => { + const started = transactionTail.then( + () => runTransaction(function_), + () => runTransaction(function_), + ); + + transactionTail = started.then( + () => undefined, + () => undefined, + ); + + return started; + }; + const setAlarm = (timestamp: number | Date): void => { const ms = typeof timestamp === "number" ? timestamp : timestamp.getTime(); shardState.alarmAt = ms; From 8fca54701307e0c8eb13868310eca2dde98dca07 Mon Sep 17 00:00:00 2001 From: Daniel Bannert Date: Sat, 1 Aug 2026 17:33:27 +0200 Subject: [PATCH 3/3] =?UTF-8?q?test(platform):=20give=20the=20conformance?= =?UTF-8?q?=20TCK=20teeth=20=E2=80=94=20dispatch,=20real=20skips,=20safe?= =?UTF-8?q?=20cleanup?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The host-contract TCK could not fail for the failures that mattered most: - No leg ever asserted a scheduled job was actually dispatched — only that scheduling math was right and an id existed. A host that stores jobs and drops them on the floor (exactly what both the Node and reference hosts did pre-267) passed every scheduler leg, dead-letter legs included. Add ConformanceHost.awaitJobDispatched (optional, but mandatory for a host that declares scheduler.deadLetter — the contract's at-least-once claim), make the reference host observably dispatch (a dispatchedJobs set populated from its scheduler timer, not just bookkeeping deletion), and add a leg that fails a host claiming deadLetter without provable dispatch rather than skipping it. - 14 optional-tier branches padded expect(true).toBe(true) (or a self-evident toBeUndefined()) instead of skipping, so a host exercising 20 of 28 legs still reported "28 passed". Replaced every one with vitest's dynamic context.skip(), moving each leg's expect.assertions() below the tier check. The workerd adapter (itInDurableObject) now forwards the real TestContext into the suite body so context.skip() reaches a runner that recognizes it. - All 43 host.cleanup?.() calls were bare trailing statements, never in a finally — a failing assertion above one skipped cleanup, leaking the alarm/scheduler setTimeouts (and, on a file-backed host, the open connection). Introduced a withHost(run) wrapper that guarantees cleanup on every path (assertion failure, context.skip(), or return) without an afterEach, which the workerd call site's runInDurableObject scoping rules out. Also added "keeps overlapping transactions atomic" to the ShardHost block, pinning plan 267's transactionTail fix suite-wide (including against the real Cloudflare host over storage.transaction). Verified per-host outcome: reference host 43/43 green, 0 skips (implements every optional tier). Node host 50 passed, 4 skipped (the delivery leg plus the three dead-letter legs it no longer claims post-267). Cloudflare (@lunora/do, LUNORA_WORKERD_TESTS=1) 570 passed, 12 skipped (2 recycle + 1 mutable-tag + 9 scheduler legs — it has no scheduler at all), 0 failed. Each new/changed behavior was demonstrated against pre-fix code before landing: the delivery leg fails a host with deadLetter but no observable dispatch, and a deliberately broken assertion in the rollback leg produces a prompt red exit instead of a handle-leak hang. --- .../workerd/cloudflare-host.workerd.test.ts | 12 +- .../src/conformance/reference-host.ts | 45 + packages/platform/src/conformance/suite.ts | 881 +++++++++--------- 3 files changed, 514 insertions(+), 424 deletions(-) diff --git a/packages/do/__tests__/workerd/cloudflare-host.workerd.test.ts b/packages/do/__tests__/workerd/cloudflare-host.workerd.test.ts index ff8b063f3a..8f2865abb1 100644 --- a/packages/do/__tests__/workerd/cloudflare-host.workerd.test.ts +++ b/packages/do/__tests__/workerd/cloudflare-host.workerd.test.ts @@ -32,6 +32,7 @@ import type { ConformanceHost } from "@lunora/platform/conformance"; import { defineHostContractSuite } from "@lunora/platform/conformance/suite"; import { createShardDirectory, createShardPlatform } from "@lunora/platform-cloudflare"; import { env, runInDurableObject } from "cloudflare:test"; +import type { TestContext } from "vitest"; import { describe, expect, it } from "vitest"; /** @@ -89,19 +90,24 @@ const createCloudflareHost = (): ConformanceHost => { /** * `it`, but the body runs inside a fresh Durable Object. Each test gets its own * object so SQL tables, sockets, and alarms from one never bleed into the next. + * + * The real vitest `TestContext` is forwarded into `body` (plan 268, W2): the + * suite's dynamic-skip legs call `context.skip()`, which only works against + * the context the runner itself created for this test — a context this + * wrapper invented would not be wired to anything the runner recognizes. */ -const itInDurableObject = ((name: string, body: () => Promise | void) => { +const itInDurableObject = ((name: string, body: (context: TestContext) => Promise | void) => { // The assertions live in the injected suite's bodies, not here — this // wrapper only supplies the Durable Object context they run in. // eslint-disable-next-line vitest/expect-expect, vitest/require-top-level-describe, vitest/prefer-expect-assertions, sonarjs/assertions-in-tests -- generic test-runner adapter; `defineHostContractSuite` owns the describe blocks and the assertions - it(name, async () => { + it(name, async (context) => { const stub = env.SHARD.get(env.SHARD.newUniqueId()); await runInDurableObject(stub, async (_instance, state) => { currentState = state; try { - await body(); + await body(context); } finally { currentState = undefined; liveSockets = []; diff --git a/packages/platform/src/conformance/reference-host.ts b/packages/platform/src/conformance/reference-host.ts index 767d4cee23..77ff358197 100644 --- a/packages/platform/src/conformance/reference-host.ts +++ b/packages/platform/src/conformance/reference-host.ts @@ -29,6 +29,16 @@ interface ConformanceHost { * contract — platform delivery is the platform's test, not the adapter's. */ awaitAlarmFired?: (target: number) => Promise; + + /** + * Resolve once the host has actually dispatched a scheduled job — invoked + * its delivery path, not merely expired the timer. Optional, but NOT for a + * host that declares `scheduler.deadLetter`: that member is the + * at-least-once claim, and a host that cannot show the TCK a dispatch is + * claiming what the suite cannot check. + * @returns `true` when the job was dispatched at least once. + */ + awaitJobDispatched?: (id: string) => Promise; /** Optional cleanup hook (close DBs, release timers). */ cleanup?: () => void; @@ -521,6 +531,15 @@ const createReferenceHost = (): ReferenceHost => { */ const deadJobs = new Map(); + /** + * Ids the scheduler timer has actually fired for — the difference between + * "expired" and "dispatched" that `awaitJobDispatched` exists to make + * checkable. This host declares `scheduler.deadLetter` (the at-least-once + * claim), so it must hold this half of the claim rather than merely + * clearing bookkeeping like the pre-267 Node host did. + */ + const dispatchedJobs = new Set(); + const toStatus = (id: string, job: ReferenceJob): ScheduledJobStatus => { return { attempts: job.attempts, @@ -578,6 +597,16 @@ const createReferenceHost = (): ReferenceHost => { const delay = Math.max(0, scheduledFor - Date.now()); const timer = setTimeout(() => { + // Dispatch, not just expiry: record the job as actually fired + // (bump its attempt count to 1, the same field a real retry + // loop would advance) before dropping it from the pending set. + const job = scheduledJobs.get(id); + + if (job !== undefined) { + job.attempts += 1; + } + + dispatchedJobs.add(id); scheduledJobs.delete(id); }, delay); @@ -595,6 +624,22 @@ const createReferenceHost = (): ReferenceHost => { setTimeout(resolve, Math.max(0, target - Date.now()) + 30); }); }, + awaitJobDispatched: async (id) => { + // Same wait-past-target strategy as `awaitAlarmFired`: look up the + // job's own `scheduledFor` while it is still pending and wait + // slightly past it. If it already fired (or never existed), + // there is nothing to wait for — answer from `dispatchedJobs` + // directly. + const pendingJob = scheduledJobs.get(id); + + if (pendingJob !== undefined) { + await new Promise((resolve) => { + setTimeout(resolve, Math.max(0, pendingJob.scheduledFor - Date.now()) + 30); + }); + } + + return dispatchedJobs.has(id); + }, cleanup: () => { database.close(); diff --git a/packages/platform/src/conformance/suite.ts b/packages/platform/src/conformance/suite.ts index d5c7bc7a6b..f763da1382 100644 --- a/packages/platform/src/conformance/suite.ts +++ b/packages/platform/src/conformance/suite.ts @@ -1,6 +1,6 @@ import { resolveShard } from "../index"; import type { SocketHandle } from "../socket-host"; -import type { ConformanceHostFactory } from "./reference-host"; +import type { ConformanceHost, ConformanceHostFactory } from "./reference-host"; /** * Vitest API surface required by `defineHostContractSuite`. Passing the API in @@ -37,79 +37,134 @@ const defineHostContractSuite = (name: string, factory: ConformanceHostFactory, const createHost = async () => factory(); /** A raw socket the host under test can accept (see `createSocket`). */ - const rawSocket = (host: Awaited>): unknown => host.createSocket?.() ?? {}; + const rawSocket = (host: ConformanceHost): unknown => host.createSocket?.() ?? {}; + + /** + * Create a fresh host for one leg and guarantee its `cleanup` runs no + * matter how the leg ends — a thrown assertion, a thrown + * `context.skip()`, or a normal return. This replaces 43 bare trailing + * calls to the host's cleanup hook: a failing assertion above one of + * those used to skip cleanup entirely, leaving the alarm/scheduler + * `setTimeout`s (and, on a real file-backed host, the open connection) + * alive — a red run that also hangs on exit, right when the output + * matters most. + */ + const withHost = async (run: (host: ConformanceHost) => Promise): Promise => { + const host = await createHost(); + + try { + await run(host); + } finally { + host.cleanup?.(); + } + }; describe("ShardHost", () => { it("serializes mutations so no two closures interleave", async () => { expect.assertions(1); - const host = await createHost(); - const observed: string[] = []; - - await Promise.all([ - host.shard.runSerialized(async () => { - observed.push("a-start"); - await new Promise((resolve) => { - setTimeout(resolve, 10); - }); - observed.push("a-end"); - }), - host.shard.runSerialized(async () => { - observed.push("b-start"); - await new Promise((resolve) => { - setTimeout(resolve, 5); - }); - observed.push("b-end"); - }), - ]); - - // Each closure's start/end must be contiguous — no interleaving. - const aSpans = observed.join("").includes("a-starta-end"); - const bSpans = observed.join("").includes("b-startb-end"); - expect(aSpans && bSpans).toBe(true); - - host.cleanup?.(); + await withHost(async (host) => { + const observed: string[] = []; + + await Promise.all([ + host.shard.runSerialized(async () => { + observed.push("a-start"); + await new Promise((resolve) => { + setTimeout(resolve, 10); + }); + observed.push("a-end"); + }), + host.shard.runSerialized(async () => { + observed.push("b-start"); + await new Promise((resolve) => { + setTimeout(resolve, 5); + }); + observed.push("b-end"); + }), + ]); + + // Each closure's start/end must be contiguous — no interleaving. + const aSpans = observed.join("").includes("a-starta-end"); + const bSpans = observed.join("").includes("b-startb-end"); + expect(aSpans && bSpans).toBe(true); + }); }); it("rolls back a transaction that throws", async () => { expect.assertions(2); - const host = await createHost(); - - await host.shard.transaction(async () => { - host.shard.sql.exec("CREATE TABLE IF NOT EXISTS rollback_test (id INTEGER PRIMARY KEY)"); - host.shard.sql.exec("INSERT INTO rollback_test (id) VALUES (1)"); + await withHost(async (host) => { + await host.shard.transaction(async () => { + host.shard.sql.exec("CREATE TABLE IF NOT EXISTS rollback_test (id INTEGER PRIMARY KEY)"); + host.shard.sql.exec("INSERT INTO rollback_test (id) VALUES (1)"); + }); + + await expect( + host.shard.transaction(async () => { + host.shard.sql.exec("INSERT INTO rollback_test (id) VALUES (2)"); + throw new Error("boom"); + }), + ).rejects.toThrow("boom"); + + const rows = host.shard.sql.exec("SELECT id FROM rollback_test WHERE id = 2").toArray(); + expect(rows).toHaveLength(0); }); - - await expect( - host.shard.transaction(async () => { - host.shard.sql.exec("INSERT INTO rollback_test (id) VALUES (2)"); - throw new Error("boom"); - }), - ).rejects.toThrow("boom"); - - const rows = host.shard.sql.exec("SELECT id FROM rollback_test WHERE id = 2").toArray(); - expect(rows).toHaveLength(0); - - host.cleanup?.(); }); it("observes its own writes inside a transaction", async () => { expect.assertions(1); - const host = await createHost(); + await withHost(async (host) => { + const readValue = await host.shard.transaction(async () => { + host.shard.sql.exec("CREATE TABLE IF NOT EXISTS ryw_test (id INTEGER PRIMARY KEY, value TEXT)"); + host.shard.sql.exec("INSERT INTO ryw_test (id, value) VALUES (1, 'hello')"); + const rows = host.shard.sql.exec("SELECT value FROM ryw_test WHERE id = 1").toArray(); - const readValue = await host.shard.transaction(async () => { - host.shard.sql.exec("CREATE TABLE IF NOT EXISTS ryw_test (id INTEGER PRIMARY KEY, value TEXT)"); - host.shard.sql.exec("INSERT INTO ryw_test (id, value) VALUES (1, 'hello')"); - const rows = host.shard.sql.exec("SELECT value FROM ryw_test WHERE id = 1").toArray(); + return (rows[0] as { value: string } | undefined)?.value; + }); - return (rows[0] as { value: string } | undefined)?.value; + expect(readValue).toBe("hello"); }); + }); - expect(readValue).toBe("hello"); + // Plan 268 (W4): two overlapping bare `transaction()` calls must + // serialize against each other rather than corrupt each other's + // commits — the exact bug plan 267 fixed on the reference and Node + // hosts with a dedicated `transactionTail` lane. Pins the fix + // suite-wide, on every host that implements `transaction`. + it("keeps overlapping transactions atomic", async () => { + expect.assertions(2); - host.cleanup?.(); + await withHost(async (host) => { + host.shard.sql.exec("CREATE TABLE IF NOT EXISTS overlap_test (id TEXT PRIMARY KEY)"); + + const first = host.shard.transaction(async () => { + host.shard.sql.exec("INSERT INTO overlap_test (id) VALUES ('A')"); + await new Promise((resolve) => { + setTimeout(resolve, 20); + }); + host.shard.sql.exec("INSERT INTO overlap_test (id) VALUES ('B')"); + }); + + // Started without awaiting `first` — the overlap that + // corrupts an un-serialized raw BEGIN/COMMIT. + const second = host.shard.transaction(async () => { + host.shard.sql.exec("INSERT INTO overlap_test (id) VALUES ('C')"); + }); + + await Promise.all([first, second]); + + const committed = host.shard.sql.exec<{ id: string }>("SELECT id FROM overlap_test ORDER BY id").toArray(); + + expect(committed.map((row) => row.id)).toStrictEqual(["A", "B", "C"]); + + await expect( + host.shard.transaction(async () => { + host.shard.sql.exec("INSERT INTO overlap_test (id) VALUES ('D')"); + throw new Error("boom"); + }), + ).rejects.toThrow("boom"); + }); }); // The engine reads rows three ways — buffered, one-at-a-time, and by @@ -118,126 +173,116 @@ const defineHostContractSuite = (name: string, factory: ConformanceHostFactory, it("returns a cursor that buffers, yields one row, and iterates", async () => { expect.assertions(3); - const host = await createHost(); + await withHost(async (host) => { + await host.shard.transaction(async () => { + host.shard.sql.exec("CREATE TABLE IF NOT EXISTS cursor_test (id INTEGER PRIMARY KEY)"); + host.shard.sql.exec("INSERT INTO cursor_test (id) VALUES (1)"); + host.shard.sql.exec("INSERT INTO cursor_test (id) VALUES (2)"); + }); - await host.shard.transaction(async () => { - host.shard.sql.exec("CREATE TABLE IF NOT EXISTS cursor_test (id INTEGER PRIMARY KEY)"); - host.shard.sql.exec("INSERT INTO cursor_test (id) VALUES (1)"); - host.shard.sql.exec("INSERT INTO cursor_test (id) VALUES (2)"); + expect(host.shard.sql.exec("SELECT id FROM cursor_test ORDER BY id").toArray()).toHaveLength(2); + expect(host.shard.sql.exec("SELECT id FROM cursor_test WHERE id = 1").one()).toEqual({ id: 1 }); + expect([...host.shard.sql.exec("SELECT id FROM cursor_test ORDER BY id")]).toHaveLength(2); }); - - expect(host.shard.sql.exec("SELECT id FROM cursor_test ORDER BY id").toArray()).toHaveLength(2); - expect(host.shard.sql.exec("SELECT id FROM cursor_test WHERE id = 1").one()).toEqual({ id: 1 }); - expect([...host.shard.sql.exec("SELECT id FROM cursor_test ORDER BY id")]).toHaveLength(2); - - host.cleanup?.(); }); it("reports a pending alarm, and clears it once fired", async () => { expect.assertions(2); - const host = await createHost(); - const target = Date.now() + 50; - - await host.shard.alarms.set(target); - // `get` may be sync or async per the contract; `await` covers both. - expect(await host.shard.alarms.get()).toBe(target); + await withHost(async (host) => { + const target = Date.now() + 50; - if (host.awaitAlarmFired === undefined) { - // Delivery is the platform's, not the adapter's — see - // `ConformanceHost.awaitAlarmFired`. The pending alarm still - // has to read back as pending. + await host.shard.alarms.set(target); + // `get` may be sync or async per the contract; `await` covers both. expect(await host.shard.alarms.get()).toBe(target); - host.cleanup?.(); - return; - } + if (host.awaitAlarmFired === undefined) { + // Delivery is the platform's, not the adapter's — see + // `ConformanceHost.awaitAlarmFired`. The pending alarm still + // has to read back as pending. + expect(await host.shard.alarms.get()).toBe(target); - await host.awaitAlarmFired(target); - expect(await host.shard.alarms.get()).toBeNull(); + return; + } - host.cleanup?.(); + await host.awaitAlarmFired(target); + expect(await host.shard.alarms.get()).toBeNull(); + }); }); it("deletes a pending alarm", async () => { expect.assertions(1); - const host = await createHost(); - - await host.shard.alarms.set(Date.now() + 10_000); - await host.shard.alarms.delete(); - expect(await host.shard.alarms.get()).toBeNull(); - - host.cleanup?.(); + await withHost(async (host) => { + await host.shard.alarms.set(Date.now() + 10_000); + await host.shard.alarms.delete(); + expect(await host.shard.alarms.get()).toBeNull(); + }); }); }); describe("SocketHost", () => { it("accepts a socket and can send/close", async () => { - const host = await createHost(); - const handle = host.socket.accept(rawSocket(host), { user: "ada" }); - - expect(host.socket.idFor(handle)).toBeDefined(); - - handle.send("hello"); - // Through `idFor` rather than object identity: a host is allowed - // to wrap, so the leg must pass for a wrapping host too. - expect(host.socket.getSockets().map((socket) => host.socket.idFor(socket))).toContain(host.socket.idFor(handle)); - - // "Did not throw" is not delivery. A host that silently dropped - // every frame would pass the rest of this leg while breaking - // every subscription on it, so where the frames are observable - // at all, assert they arrived. - if (host.readFrames !== undefined) { - expect(host.readFrames(handle)).toStrictEqual(["hello"]); - } - - // How soon a closed socket leaves `getSockets()` is host-defined - // (the reference host is lazy; workerd drops it on the close - // event), so the contract only promises that `close` is safe. - expect(() => { - handle.close(1000, "done"); - }).not.toThrow(); - - host.cleanup?.(); + await withHost(async (host) => { + const handle = host.socket.accept(rawSocket(host), { user: "ada" }); + + expect(host.socket.idFor(handle)).toBeDefined(); + + handle.send("hello"); + // Through `idFor` rather than object identity: a host is allowed + // to wrap, so the leg must pass for a wrapping host too. + expect(host.socket.getSockets().map((socket) => host.socket.idFor(socket))).toContain(host.socket.idFor(handle)); + + // "Did not throw" is not delivery. A host that silently dropped + // every frame would pass the rest of this leg while breaking + // every subscription on it, so where the frames are observable + // at all, assert they arrived. + if (host.readFrames !== undefined) { + expect(host.readFrames(handle)).toStrictEqual(["hello"]); + } + + // How soon a closed socket leaves `getSockets()` is host-defined + // (the reference host is lazy; workerd drops it on the close + // event), so the contract only promises that `close` is safe. + expect(() => { + handle.close(1000, "done"); + }).not.toThrow(); + }); }); it("round-trips an attachment on a live socket", async () => { expect.assertions(1); - const host = await createHost(); - const attachment = { roomId: "room-1", roles: ["admin"] }; - const handle = host.socket.accept(rawSocket(host), attachment); - - expect(handle.deserializeAttachment()).toEqual(attachment); + await withHost(async (host) => { + const attachment = { roomId: "room-1", roles: ["admin"] }; + const handle = host.socket.accept(rawSocket(host), attachment); - host.cleanup?.(); + expect(handle.deserializeAttachment()).toEqual(attachment); + }); }); // Hosts that own their own recycle (Cloudflare hibernation) can't be // driven through one from a test, so this leg runs only where the // host exposes the hooks. It is the reference host's job to prove // the durable half of the attachment contract. - it("round-trips attachments across a recycle", async () => { - expect.assertions(1); - - const host = await createHost(); + it("round-trips attachments across a recycle", async (context) => { + await withHost(async (host) => { + if (host.simulateRecycle === undefined || host.restoreSocket === undefined) { + context.skip(`${name} does not implement simulateRecycle/restoreSocket`); - if (host.simulateRecycle === undefined || host.restoreSocket === undefined) { - expect(true).toBe(true); - host.cleanup?.(); + return; + } - return; - } + expect.assertions(1); - const attachment = { roomId: "room-1", roles: ["admin"] }; - const handle = host.socket.accept(rawSocket(host), attachment); + const attachment = { roomId: "room-1", roles: ["admin"] }; + const handle = host.socket.accept(rawSocket(host), attachment); - host.simulateRecycle(); - const restored = host.restoreSocket(host.socket.idFor(handle), attachment); - expect(restored.deserializeAttachment()).toEqual(attachment); + host.simulateRecycle(); + const restored = host.restoreSocket(host.socket.idFor(handle), attachment); - host.cleanup?.(); + expect(restored.deserializeAttachment()).toEqual(attachment); + }); }); // `SocketHost.idFor` is documented to answer the SAME string for @@ -246,15 +291,14 @@ const defineHostContractSuite = (name: string, factory: ConformanceHostFactory, it("keeps idFor stable across repeated calls within a wake", async () => { expect.assertions(1); - const host = await createHost(); - const handle = host.socket.accept(rawSocket(host), {}); + await withHost(async (host) => { + const handle = host.socket.accept(rawSocket(host), {}); - const first = host.socket.idFor(handle); - const second = host.socket.idFor(handle); + const first = host.socket.idFor(handle); + const second = host.socket.idFor(handle); - expect(second).toBe(first); - - host.cleanup?.(); + expect(second).toBe(first); + }); }); // Same leg as "round-trips attachments across a recycle" above, for @@ -262,28 +306,25 @@ const defineHostContractSuite = (name: string, factory: ConformanceHostFactory, // socket with the subscription state it owned before the wake BY id, // so a host whose id drifts across a recycle breaks that lookup even // though the attachment round-trips fine. - it("keeps idFor stable across a recycle", async () => { - expect.assertions(1); - - const host = await createHost(); - - if (host.simulateRecycle === undefined || host.restoreSocket === undefined) { - expect(true).toBe(true); - host.cleanup?.(); + it("keeps idFor stable across a recycle", async (context) => { + await withHost(async (host) => { + if (host.simulateRecycle === undefined || host.restoreSocket === undefined) { + context.skip(`${name} does not implement simulateRecycle/restoreSocket`); - return; - } + return; + } - const attachment = { roomId: "room-1", roles: ["admin"] }; - const handle = host.socket.accept(rawSocket(host), attachment); - const idBeforeRecycle = host.socket.idFor(handle); + expect.assertions(1); - host.simulateRecycle(); - const restored = host.restoreSocket(idBeforeRecycle, attachment); + const attachment = { roomId: "room-1", roles: ["admin"] }; + const handle = host.socket.accept(rawSocket(host), attachment); + const idBeforeRecycle = host.socket.idFor(handle); - expect(host.socket.idFor(restored)).toBe(idBeforeRecycle); + host.simulateRecycle(); + const restored = host.restoreSocket(idBeforeRecycle, attachment); - host.cleanup?.(); + expect(host.socket.idFor(restored)).toBe(idBeforeRecycle); + }); }); // A tagged `getSockets` must return *exactly* the tagged sockets. @@ -293,22 +334,20 @@ const defineHostContractSuite = (name: string, factory: ConformanceHostFactory, it("returns exactly the sockets carrying an accept-time tag", async () => { expect.assertions(4); - const host = await createHost(); - - const a = host.socket.accept(rawSocket(host), {}, ["room-a"]); - const b = host.socket.accept(rawSocket(host), {}, ["room-b"]); - const untagged = host.socket.accept(rawSocket(host), {}); - - const idOf = (socket: SocketHandle): string => host.socket.idFor(socket); + await withHost(async (host) => { + const a = host.socket.accept(rawSocket(host), {}, ["room-a"]); + const b = host.socket.accept(rawSocket(host), {}, ["room-b"]); + const untagged = host.socket.accept(rawSocket(host), {}); - expect(host.socket.getSockets("room-a").map(idOf)).toStrictEqual([idOf(a)]); - expect(host.socket.getSockets("room-b").map(idOf)).toStrictEqual([idOf(b)]); - // An untagged socket leaks into no tagged fan-out, and an - // unknown tag matches nothing. - expect(host.socket.getSockets("room-c").map(idOf)).toStrictEqual([]); - expect(host.socket.getSockets().map(idOf)).toContain(idOf(untagged)); + const idOf = (socket: SocketHandle): string => host.socket.idFor(socket); - host.cleanup?.(); + expect(host.socket.getSockets("room-a").map(idOf)).toStrictEqual([idOf(a)]); + expect(host.socket.getSockets("room-b").map(idOf)).toStrictEqual([idOf(b)]); + // An untagged socket leaks into no tagged fan-out, and an + // unknown tag matches nothing. + expect(host.socket.getSockets("room-c").map(idOf)).toStrictEqual([]); + expect(host.socket.getSockets().map(idOf)).toContain(idOf(untagged)); + }); }); // Enumeration yields handles while the runtime's message/close @@ -318,16 +357,15 @@ const defineHostContractSuite = (name: string, factory: ConformanceHostFactory, it("resolves a raw socket back to its handle", async () => { expect.assertions(2); - const host = await createHost(); - const raw = rawSocket(host); - const handle = host.socket.accept(raw, {}); + await withHost(async (host) => { + const raw = rawSocket(host); + const handle = host.socket.accept(raw, {}); - const resolved = host.socket.handleFor(raw); + const resolved = host.socket.handleFor(raw); - expect(resolved !== undefined && host.socket.idFor(resolved)).toBe(host.socket.idFor(handle)); - expect(host.socket.handleFor(rawSocket(host))).toBeUndefined(); - - host.cleanup?.(); + expect(resolved !== undefined && host.socket.idFor(resolved)).toBe(host.socket.idFor(handle)); + expect(host.socket.handleFor(rawSocket(host))).toBeUndefined(); + }); }); // Backpressure is optional to *report* but must never be wrong when @@ -336,40 +374,35 @@ const defineHostContractSuite = (name: string, factory: ConformanceHostFactory, it("reports a plausible outbound queue depth, if any", async () => { expect.assertions(1); - const host = await createHost(); - const handle = host.socket.accept(rawSocket(host), {}); - const { bufferedAmount } = handle; - - expect(bufferedAmount === undefined || (typeof bufferedAmount === "number" && bufferedAmount >= 0)).toBe(true); + await withHost(async (host) => { + const handle = host.socket.accept(rawSocket(host), {}); + const { bufferedAmount } = handle; - host.cleanup?.(); + expect(bufferedAmount === undefined || (typeof bufferedAmount === "number" && bufferedAmount >= 0)).toBe(true); + }); }); // Mutable tagging is an optional tier: hosts whose tags freeze at // accept (Cloudflare) omit `setTag`, and the suite must not demand // it. Where it *is* declared, it has to actually work. - it("retags a live socket when the host declares mutable tags", async () => { - expect.assertions(2); - - const host = await createHost(); - - if (host.socket.setTag === undefined) { - expect(host.socket.removeTag).toBeUndefined(); - expect(true).toBe(true); - host.cleanup?.(); + it("retags a live socket when the host declares mutable tags", async (context) => { + await withHost(async (host) => { + if (host.socket.setTag === undefined) { + context.skip(`${name} does not implement mutable socket tags (setTag)`); - return; - } + return; + } - const socket = host.socket.accept(rawSocket(host), {}); + expect.assertions(2); - host.socket.setTag(socket, "room-a"); - expect(host.socket.getSockets("room-a").map((handle) => host.socket.idFor(handle))).toStrictEqual([host.socket.idFor(socket)]); + const socket = host.socket.accept(rawSocket(host), {}); - host.socket.removeTag?.(socket, "room-a"); - expect(host.socket.getSockets("room-a").map((handle) => host.socket.idFor(handle))).toStrictEqual([]); + host.socket.setTag(socket, "room-a"); + expect(host.socket.getSockets("room-a").map((handle) => host.socket.idFor(handle))).toStrictEqual([host.socket.idFor(socket)]); - host.cleanup?.(); + host.socket.removeTag?.(socket, "room-a"); + expect(host.socket.getSockets("room-a").map((handle) => host.socket.idFor(handle))).toStrictEqual([]); + }); }); }); @@ -380,28 +413,26 @@ const defineHostContractSuite = (name: string, factory: ConformanceHostFactory, it("resolves shard keys deterministically", async () => { expect.assertions(1); - const host = await createHost(); - const first = await resolveShard(host.directory, "tenant-42").fetch(new Request("http://localhost/")); - const second = await resolveShard(host.directory, "tenant-42").fetch(new Request("http://localhost/")); + await withHost(async (host) => { + const first = await resolveShard(host.directory, "tenant-42").fetch(new Request("http://localhost/")); + const second = await resolveShard(host.directory, "tenant-42").fetch(new Request("http://localhost/")); - await expect(first.text()).resolves.toBe(await second.text()); - - host.cleanup?.(); + await expect(first.text()).resolves.toBe(await second.text()); + }); }); it("dispatches fetch to a resolved stub", async () => { expect.assertions(1); - const host = await createHost(); - const stub = resolveShard(host.directory, "tenant-42"); - const response = await stub.fetch(new Request("http://localhost/")); - - // The body is the shard's business; the contract only promises - // that a resolved stub is dispatchable and answers with a - // Response. - expect(response).toBeInstanceOf(Response); + await withHost(async (host) => { + const stub = resolveShard(host.directory, "tenant-42"); + const response = await stub.fetch(new Request("http://localhost/")); - host.cleanup?.(); + // The body is the shard's business; the contract only promises + // that a resolved stub is dispatchable and answers with a + // Response. + expect(response).toBeInstanceOf(Response); + }); }); }); @@ -409,298 +440,306 @@ const defineHostContractSuite = (name: string, factory: ConformanceHostFactory, // A host that supplies no scheduler reports the gap as its own test // rather than silently skipping the block: "not implemented here" is // a result the suite output should carry, not one it should hide. - it("schedules a job for a future timestamp", async () => { - expect.assertions(2); - - const host = await createHost(); + it("schedules a job for a future timestamp", async (context) => { + await withHost(async (host) => { + if (host.scheduler === undefined) { + context.skip(`${name} does not implement SchedulerHost`); - if (host.scheduler === undefined) { - expect(host.scheduler).toBeUndefined(); - expect(true).toBe(true); - host.cleanup?.(); + return; + } - return; - } + expect.assertions(2); - const now = Date.now(); - const job = await host.scheduler.schedule("tasks/remind", { user: "ada" }, { delayMs: 50 }); + const now = Date.now(); + const job = await host.scheduler.schedule("tasks/remind", { user: "ada" }, { delayMs: 50 }); - expect(job.scheduledFor).toBeGreaterThanOrEqual(now + 50); - expect(job.id).toBeDefined(); - - host.cleanup?.(); + expect(job.scheduledFor).toBeGreaterThanOrEqual(now + 50); + expect(job.id).toBeDefined(); + }); }); - it("cancels a scheduled job", async () => { - expect.assertions(1); + // Plan 268 (W1): the schedule leg above only asserts arithmetic — it + // never waits for a job to actually RUN. A host that stores jobs and + // drops them on the floor passes every other scheduler leg, + // including the dead-letter ones that exist to make at-least-once + // checkable. A host that declares `scheduler.deadLetter` — the + // contract's documented at-least-once claim — MUST supply + // `awaitJobDispatched` and must observably dispatch; a missing hook + // on such a host is a leg FAILURE, not a skip, because presence of + // `deadLetter` without a way to prove dispatch is a claim the suite + // cannot check. A host with neither skips, visibly. + it("dispatches a scheduled job at least once", async (context) => { + await withHost(async (host) => { + if (host.scheduler === undefined) { + context.skip(`${name} does not implement SchedulerHost`); - const host = await createHost(); + return; + } - if (host.scheduler === undefined) { - expect(host.scheduler).toBeUndefined(); - host.cleanup?.(); + const claimsAtLeastOnce = host.scheduler.deadLetter !== undefined; - return; - } + if (!claimsAtLeastOnce && host.awaitJobDispatched === undefined) { + context.skip(`${name} does not claim at-least-once delivery (no deadLetter) and supplies no awaitJobDispatched hook`); - const job = await host.scheduler.schedule("tasks/remind", {}, { delayMs: 10_000 }); - const cancelled = await host.scheduler.cancel(job.id); + return; + } - expect(cancelled).toBe(true); + if (claimsAtLeastOnce) { + expect(host.awaitJobDispatched).toBeDefined(); + } - host.cleanup?.(); - }); - - it("reports a second cancel of the same job as false", async () => { - expect.assertions(2); + if (host.awaitJobDispatched === undefined) { + return; + } - const host = await createHost(); + const hasList = host.scheduler.list !== undefined; - if (host.scheduler === undefined) { - expect(host.scheduler).toBeUndefined(); - expect(true).toBe(true); - host.cleanup?.(); + // 1 for the dispatch assertion, always reached at this point + // (the hook is defined); +1 for the deadLetter-presence + // assertion above when the host claims at-least-once; +1 for + // the disjoint-from-pending assertion when `list` exists. + expect.assertions(1 + (claimsAtLeastOnce ? 1 : 0) + (hasList ? 1 : 0)); - return; - } + const job = await host.scheduler.schedule("tasks/remind", { user: "ada" }, { delayMs: 30 }); - const job = await host.scheduler.schedule("tasks/remind", {}, { delayMs: 10_000 }); + await expect(host.awaitJobDispatched(job.id)).resolves.toBe(true); - expect(await host.scheduler.cancel(job.id)).toBe(true); + if (hasList) { + const pending = await host.scheduler.list?.(); - // `cancel` is documented to answer "was there something to - // cancel". A host that returned `true` unconditionally would let - // a caller believe it had stopped a job that is still pending — - // and a retry layer reading that answer would stop retrying a - // delivery that never happened. - expect(await host.scheduler.cancel(job.id)).toBe(false); - - host.cleanup?.(); + expect(pending?.some((entry) => entry.id === job.id)).toBe(false); + } + }); }); - it("gives two identical schedules independently cancellable ids", async () => { - expect.assertions(3); + it("cancels a scheduled job", async (context) => { + await withHost(async (host) => { + if (host.scheduler === undefined) { + context.skip(`${name} does not implement SchedulerHost`); - const host = await createHost(); + return; + } - if (host.scheduler === undefined) { - expect(host.scheduler).toBeUndefined(); - expect(true).toBe(true); - expect(true).toBe(true); - host.cleanup?.(); + expect.assertions(1); - return; - } + const job = await host.scheduler.schedule("tasks/remind", {}, { delayMs: 10_000 }); + const cancelled = await host.scheduler.cancel(job.id); - const first = await host.scheduler.schedule("tasks/remind", { user: "ada" }, { delayMs: 10_000 }); - const second = await host.scheduler.schedule("tasks/remind", { user: "ada" }, { delayMs: 10_000 }); + expect(cancelled).toBe(true); + }); + }); - expect(second.id).not.toBe(first.id); + it("reports a second cancel of the same job as false", async (context) => { + await withHost(async (host) => { + if (host.scheduler === undefined) { + context.skip(`${name} does not implement SchedulerHost`); - // Same function, same args, two jobs — so cancelling one must - // leave the other pending. A host that keyed jobs by payload - // would silently drop the survivor: the caller enqueued twice, - // cancelled once, and is owed one delivery. - expect(await host.scheduler.cancel(first.id)).toBe(true); - expect(await host.scheduler.cancel(second.id)).toBe(true); + return; + } - host.cleanup?.(); - }); + expect.assertions(2); - it("lists a pending job with a zero attempt count", async () => { - expect.assertions(2); + const job = await host.scheduler.schedule("tasks/remind", {}, { delayMs: 10_000 }); - const host = await createHost(); + expect(await host.scheduler.cancel(job.id)).toBe(true); - if (host.scheduler?.list === undefined) { - expect(host.scheduler?.list).toBeUndefined(); - expect(true).toBe(true); - host.cleanup?.(); + // `cancel` is documented to answer "was there something to + // cancel". A host that returned `true` unconditionally would let + // a caller believe it had stopped a job that is still pending — + // and a retry layer reading that answer would stop retrying a + // delivery that never happened. + expect(await host.scheduler.cancel(job.id)).toBe(false); + }); + }); - return; - } + it("gives two identical schedules independently cancellable ids", async (context) => { + await withHost(async (host) => { + if (host.scheduler === undefined) { + context.skip(`${name} does not implement SchedulerHost`); - const job = await host.scheduler.schedule("tasks/remind", { user: "ada" }, { delayMs: 10_000 }); - const jobs = await host.scheduler.list(); - const pending = jobs.find((entry) => entry.id === job.id); + return; + } - expect(pending?.functionPath).toBe("tasks/remind"); + expect.assertions(3); - // Zero, not absent. `attempts` is what makes at-least-once - // observable at all — a host that always reports 0 is either not - // retrying or not counting, and a caller cannot tell a job - // waiting between retries from one never dispatched. - expect(pending?.attempts).toBe(0); + const first = await host.scheduler.schedule("tasks/remind", { user: "ada" }, { delayMs: 10_000 }); + const second = await host.scheduler.schedule("tasks/remind", { user: "ada" }, { delayMs: 10_000 }); - host.cleanup?.(); + expect(second.id).not.toBe(first.id); + + // Same function, same args, two jobs — so cancelling one must + // leave the other pending. A host that keyed jobs by payload + // would silently drop the survivor: the caller enqueued twice, + // cancelled once, and is owed one delivery. + expect(await host.scheduler.cancel(first.id)).toBe(true); + expect(await host.scheduler.cancel(second.id)).toBe(true); + }); }); - it("keeps the pending and dead-letter listings disjoint", async () => { - expect.assertions(2); + it("lists a pending job with a zero attempt count", async (context) => { + await withHost(async (host) => { + if (host.scheduler?.list === undefined) { + context.skip(`${name} does not implement SchedulerHost.list`); - const host = await createHost(); + return; + } - if (host.scheduler?.list === undefined || host.scheduler.deadLetter === undefined || host.simulateDeadLetter === undefined) { - expect(host.simulateDeadLetter).toBeUndefined(); - expect(true).toBe(true); - host.cleanup?.(); + expect.assertions(2); - return; - } + const job = await host.scheduler.schedule("tasks/remind", { user: "ada" }, { delayMs: 10_000 }); + const jobs = await host.scheduler.list(); + const pending = jobs.find((entry) => entry.id === job.id); - const job = await host.scheduler.schedule("tasks/remind", {}, { delayMs: 10_000 }); + expect(pending?.functionPath).toBe("tasks/remind"); - await host.simulateDeadLetter(job.id); + // Zero, not absent. `attempts` is what makes at-least-once + // observable at all — a host that always reports 0 is either not + // retrying or not counting, and a caller cannot tell a job + // waiting between retries from one never dispatched. + expect(pending?.attempts).toBe(0); + }); + }); - const pending = await host.scheduler.list(); - const parked = await host.scheduler.deadLetter.list(); + it("keeps the pending and dead-letter listings disjoint", async (context) => { + await withHost(async (host) => { + if (host.scheduler?.list === undefined || host.scheduler.deadLetter === undefined || host.simulateDeadLetter === undefined) { + context.skip(`${name} does not implement scheduler.list/deadLetter/simulateDeadLetter`); - // A parked job is no longer on its way. Reporting it in both - // shows a permanently-failed job as still scheduled — the - // operator sees a queue that will drain and it never does. - expect(pending.some((entry) => entry.id === job.id)).toBe(false); - expect(parked.some((entry) => entry.id === job.id)).toBe(true); + return; + } - host.cleanup?.(); - }); + expect.assertions(2); - it("returns a requeued job to the pending set with a fresh budget", async () => { - expect.assertions(4); + const job = await host.scheduler.schedule("tasks/remind", {}, { delayMs: 10_000 }); - const host = await createHost(); + await host.simulateDeadLetter(job.id); - if (host.scheduler?.list === undefined || host.scheduler.deadLetter === undefined || host.simulateDeadLetter === undefined) { - expect(host.simulateDeadLetter).toBeUndefined(); - expect(true).toBe(true); - expect(true).toBe(true); - expect(true).toBe(true); - host.cleanup?.(); + const pending = await host.scheduler.list(); + const parked = await host.scheduler.deadLetter.list(); - return; - } + // A parked job is no longer on its way. Reporting it in both + // shows a permanently-failed job as still scheduled — the + // operator sees a queue that will drain and it never does. + expect(pending.some((entry) => entry.id === job.id)).toBe(false); + expect(parked.some((entry) => entry.id === job.id)).toBe(true); + }); + }); - const job = await host.scheduler.schedule("tasks/remind", {}, { delayMs: 10_000 }); + it("returns a requeued job to the pending set with a fresh budget", async (context) => { + await withHost(async (host) => { + if (host.scheduler?.list === undefined || host.scheduler.deadLetter === undefined || host.simulateDeadLetter === undefined) { + context.skip(`${name} does not implement scheduler.list/deadLetter/simulateDeadLetter`); - await host.simulateDeadLetter(job.id); + return; + } - expect(await host.scheduler.deadLetter.requeue(job.id)).toBe(true); + expect.assertions(4); - const jobs = await host.scheduler.list(); - const pending = jobs.find((entry) => entry.id === job.id); + const job = await host.scheduler.schedule("tasks/remind", {}, { delayMs: 10_000 }); - expect(pending).toBeDefined(); + await host.simulateDeadLetter(job.id); - // A fresh budget is the whole point: returning it with its - // exhausted count parks it again on the next failure without - // ever retrying, so the requeue would look successful and change - // nothing. - expect(pending?.attempts).toBe(0); + expect(await host.scheduler.deadLetter.requeue(job.id)).toBe(true); - // And it must LEAVE the dead-letter listing. Restoring it to - // pending while keeping the parked copy breaks the same - // disjointness the leg above pins — recovered once, listed - // forever, and recoverable again into a second live job. - const stillParked = await host.scheduler.deadLetter.list(); + const jobs = await host.scheduler.list(); + const pending = jobs.find((entry) => entry.id === job.id); - expect(stillParked.some((entry) => entry.id === job.id)).toBe(false); + expect(pending).toBeDefined(); - host.cleanup?.(); - }); + // A fresh budget is the whole point: returning it with its + // exhausted count parks it again on the next failure without + // ever retrying, so the requeue would look successful and change + // nothing. + expect(pending?.attempts).toBe(0); - it("reports a requeue of an unparked job as false", async () => { - expect.assertions(1); + // And it must LEAVE the dead-letter listing. Restoring it to + // pending while keeping the parked copy breaks the same + // disjointness the leg above pins — recovered once, listed + // forever, and recoverable again into a second live job. + const stillParked = await host.scheduler.deadLetter.list(); - const host = await createHost(); + expect(stillParked.some((entry) => entry.id === job.id)).toBe(false); + }); + }); - if (host.scheduler?.deadLetter === undefined) { - expect(host.scheduler?.deadLetter).toBeUndefined(); - host.cleanup?.(); + it("reports a requeue of an unparked job as false", async (context) => { + await withHost(async (host) => { + if (host.scheduler?.deadLetter === undefined) { + context.skip(`${name} does not implement scheduler.deadLetter`); - return; - } + return; + } - // Not parked, never existed — either way there is nothing to - // resurrect, and a host answering `true` tells an operator it - // recovered a job it did not. - expect(await host.scheduler.deadLetter.requeue("job-does-not-exist")).toBe(false); + expect.assertions(1); - host.cleanup?.(); + // Not parked, never existed — either way there is nothing to + // resurrect, and a host answering `true` tells an operator it + // recovered a job it did not. + expect(await host.scheduler.deadLetter.requeue("job-does-not-exist")).toBe(false); + }); }); }); describe("ShardKvStore", () => { // As with the scheduler, a host without a KV surface reports the gap // as its own result rather than skipping the block silently. - it("reads back a written value", async () => { - expect.assertions(2); - - const host = await createHost(); - - if (host.kv === undefined) { - expect(host.kv).toBeUndefined(); - expect(true).toBe(true); - host.cleanup?.(); + it("reads back a written value", async (context) => { + await withHost(async (host) => { + if (host.kv === undefined) { + context.skip(`${name} does not implement ShardKvStore`); - return; - } + return; + } - await host.kv.put("s:token-1", { userId: "ada" }); + expect.assertions(2); - expect(await host.kv.get("s:token-1")).toEqual({ userId: "ada" }); - expect(await host.kv.get("s:missing")).toBeUndefined(); + await host.kv.put("s:token-1", { userId: "ada" }); - host.cleanup?.(); + expect(await host.kv.get("s:token-1")).toEqual({ userId: "ada" }); + expect(await host.kv.get("s:missing")).toBeUndefined(); + }); }); - it("deletes a key idempotently", async () => { - expect.assertions(3); - - const host = await createHost(); + it("deletes a key idempotently", async (context) => { + await withHost(async (host) => { + if (host.kv === undefined) { + context.skip(`${name} does not implement ShardKvStore`); - if (host.kv === undefined) { - expect(host.kv).toBeUndefined(); - expect(true).toBe(true); - expect(true).toBe(true); - host.cleanup?.(); + return; + } - return; - } + expect.assertions(3); - await host.kv.put("k", 1); + await host.kv.put("k", 1); - expect(await host.kv.delete("k")).toBe(true); - expect(await host.kv.delete("k")).toBe(false); - expect(await host.kv.get("k")).toBeUndefined(); - - host.cleanup?.(); + expect(await host.kv.delete("k")).toBe(true); + expect(await host.kv.delete("k")).toBe(false); + expect(await host.kv.get("k")).toBeUndefined(); + }); }); // A prefix scan must return exactly the keys under the prefix — a // superset would let a GC sweep or migration touch unrelated keys. - it("enumerates exactly the keys under a prefix", async () => { - expect.assertions(2); + it("enumerates exactly the keys under a prefix", async (context) => { + await withHost(async (host) => { + if (host.kv === undefined) { + context.skip(`${name} does not implement ShardKvStore`); - const host = await createHost(); + return; + } - if (host.kv === undefined) { - expect(host.kv).toBeUndefined(); - expect(true).toBe(true); - host.cleanup?.(); + expect.assertions(2); - return; - } + await host.kv.put("s:a", 1); + await host.kv.put("s:b", 2); + await host.kv.put("other", 3); - await host.kv.put("s:a", 1); - await host.kv.put("s:b", 2); - await host.kv.put("other", 3); + const scoped = await host.kv.list({ prefix: "s:" }); + const all = await host.kv.list(); - const scoped = await host.kv.list({ prefix: "s:" }); - const all = await host.kv.list(); - - expect([...scoped.keys()].toSorted((a, b) => a.localeCompare(b))).toStrictEqual(["s:a", "s:b"]); - expect(all.size).toBe(3); - - host.cleanup?.(); + expect([...scoped.keys()].toSorted((a, b) => a.localeCompare(b))).toStrictEqual(["s:a", "s:b"]); + expect(all.size).toBe(3); + }); }); }); });