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/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-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/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-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-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-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/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" }, diff --git a/packages/platform/src/conformance/reference-host.ts b/packages/platform/src/conformance/reference-host.ts index a0880f7803..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; @@ -282,7 +292,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 +318,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; @@ -494,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, @@ -551,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); @@ -568,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); + }); }); }); });