@chaos-overlords/worker 0.9.1 → 0.9.3

package/README.md

@@ -18,17 +18,21 @@ Object namespace, whose migration lineage starts at tag `v1` with `new_sqlite_cl
 The D1 migration lineages ship in `@chaos-overlords/storage` and `@chaos-overlords/bug-reports`; point
 `wrangler d1 migrations apply` at them rather than copying them.
 
-`PUBLIC_LISTING`, `RATE_LIMIT_PER_MINUTE`, `MEMBER_RATE_LIMIT_PER_MINUTE`,
-`UPLOAD_RATE_LIMIT_PER_MINUTE`, `BUG_REPORT_RATE_LIMIT_PER_MINUTE`, `RETENTION_DAYS`,
-`ABANDONED_RETENTION_DAYS`, `BUG_REPORT_RETENTION_DAYS` and `BUG_REPORT_DAILY_STATE_MB` are vars. The
+`PUBLIC_LISTING`, `CORS_ORIGINS`, `RATE_LIMIT_PER_MINUTE`, `MEMBER_RATE_LIMIT_PER_MINUTE`,
+`UPLOAD_RATE_LIMIT_PER_MINUTE`, `BUG_REPORT_RATE_LIMIT_PER_MINUTE`,
+`MATCH_CREATION_RATE_LIMIT_PER_MINUTE`, `RETENTION_DAYS`,
+`LOBBY_RETENTION_DAYS`, `ABANDONED_RETENTION_DAYS`, `SILENT_RETENTION_DAYS`, `RETENTION_BATCH_SIZE`,
+`BUG_REPORT_RETENTION_DAYS` and `BUG_REPORT_DAILY_STATE_MB` are vars; unset, each retention window
+takes the kernel's default for a shared public server (see the multiplayer README). The
 `scheduled` handler expects a cron trigger; five minutes is the interval its sweeper is written for.
 
 **A deployment without a cron trigger has no safety net.** The sweeper is what seals a turn whose
 Durable Object alarm never fired, finishes a seal whose isolate died halfway through, re-runs the
 verdict of a match left paused by an interrupted one, and collects retention. Nothing else does any
 of it, and nothing fails loudly when it is missing: matches simply stop advancing for the players in
-them. `wrangler.dev.toml` deliberately carries no `[triggers]` block, because it is not a
-deployment — so the first thing to add to a real one is:
+them. `wrangler.dev.toml` carries the trigger so `wrangler dev --test-scheduled` exercises the same
+path, but it is not a deployment and triggers are not inherited — so the first thing to add to a
+real one is:
 
 ```toml
 [triggers]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chaos-overlords/worker",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "Cloudflare Workers runtime facade: the shared Hono app over D1, with one Durable Object per match for SSE fan-out and turn-deadline alarms.",
   "keywords": [
     "chaos-overlords",
@@ -47,17 +47,17 @@
     "provenance": true
   },
   "dependencies": {
-    "@chaos-overlords/bug-reports": "0.9.1",
-    "@chaos-overlords/contracts": "0.9.1",
-    "@chaos-overlords/kernel": "0.9.1",
-    "@chaos-overlords/server": "0.9.1",
-    "@chaos-overlords/storage": "0.9.1",
+    "@chaos-overlords/bug-reports": "0.9.3",
+    "@chaos-overlords/contracts": "0.9.3",
+    "@chaos-overlords/kernel": "0.9.3",
+    "@chaos-overlords/server": "0.9.3",
+    "@chaos-overlords/storage": "0.9.3",
     "drizzle-orm": "^0.45.2",
     "hono": "^4.13.8"
   },
   "devDependencies": {
-    "@chaos-overlords/client": "0.9.1",
-    "@chaos-overlords/conformance": "0.9.1",
+    "@chaos-overlords/client": "0.9.3",
+    "@chaos-overlords/conformance": "0.9.3",
     "@cloudflare/vitest-pool-workers": "^0.22.0",
     "@cloudflare/workers-types": "^5.20260920.1",
     "typescript": "^7.0.2",

package/src/MatchHub.ts

@@ -1,4 +1,5 @@
 import {
+  EARLY_DEADLINE_RETRY_MS,
   isDomainError,
   type MultiplayerStorage,
   type PersistedEvent,
@@ -6,7 +7,9 @@ import {
 import {
   DEFAULT_EVENT_HUB_LIMITS,
   DEFAULT_SERVER_CONFIG,
+  isActiveMember,
   LocalEventHub,
+  logStreamClosed,
 } from '@chaos-overlords/server'
 import { createSqliteStorage, sqliteSchema } from '@chaos-overlords/storage/sqlite'
 import type { DurableObjectState } from '@cloudflare/workers-types'
@@ -17,10 +20,33 @@ import { buildKernel, HUB_PATHS, workerLogger } from './kernel'
 interface PendingDeadline {
   matchId: string
   turn: number
+  /** When the alarm was set for. Absent on keys written before it was recorded. */
+  dueAtMs?: number
 }
 
 const DEADLINE_KEY = 'deadline'
 
+/**
+ * Where a deadline the kernel re-arms from inside an alarm may be set for.
+ *
+ * An alarm that the kernel finds early is re-armed for the same turn, floored against the object's
+ * `Date.now()`. That floor means nothing to the alarm scheduler when the object's clock lags it:
+ * the scheduler has already passed the time the alarm fired at, so a deadline at or before that
+ * time fires again at once, and again, building a kernel and reading D1 each time until the
+ * object's clock catches up. Having fired proves the scheduler's clock reached `fired.dueAtMs`, so
+ * the retry goes at least the kernel's retry interval past that, which bounds the rate on the
+ * scheduler's own clock. Any other turn's deadline (the successor a seal opened) is set as asked.
+ */
+function retryFloor(
+  fired: PendingDeadline,
+  next: { matchId: string; turn: number },
+  dueAtMs: number,
+): number {
+  const sameTurn = next.matchId === fired.matchId && next.turn === fired.turn
+  if (!sameTurn || fired.dueAtMs === undefined) return dueAtMs
+  return Math.max(dueAtMs, fired.dueAtMs + EARLY_DEADLINE_RETRY_MS)
+}
+
 /**
  * One instance per match. It holds the open event streams of that match (so a notification from
  * any Worker isolate reaches every subscriber) and the alarm for the open turn's deadline. The
@@ -44,6 +70,9 @@ export class MatchHub {
         // so a run of these is where a signal that only looks aborted would show up.
         abandoned: (matchId, playerId) =>
           workerLogger.info('answered an already abandoned event stream', { matchId, playerId }),
+        revalidate: (matchId, playerId) =>
+          isActiveMember(this.repositories.players, matchId, playerId),
+        closed: logStreamClosed(workerLogger),
       },
     )
   }
@@ -99,7 +128,8 @@ export class MatchHub {
       notifier: { notify: async (event) => this.hub.notify(event) },
       streams: this.hub,
       scheduler: {
-        schedule: async (input) => this.arm(input.matchId, input.turn, input.dueAt.getTime()),
+        schedule: async (input) =>
+          this.arm(input.matchId, input.turn, retryFloor(pending, input, input.dueAt.getTime())),
       },
     })
     const sealed = await kernel.turns.trySeal(pending.matchId, pending.turn, 'deadline')
@@ -109,7 +139,7 @@ export class MatchHub {
 
   /** Record which turn the alarm is for, then set the alarm. One deadline is pending at a time. */
   private async arm(matchId: string, turn: number, dueAtMs: number): Promise<void> {
-    await this.state.storage.put<PendingDeadline>(DEADLINE_KEY, { matchId, turn })
+    await this.state.storage.put<PendingDeadline>(DEADLINE_KEY, { matchId, turn, dueAtMs })
     await this.state.storage.setAlarm(dueAtMs)
   }
 

package/src/env.ts

@@ -21,14 +21,23 @@ export interface Env {
    * `BUG_REPORT_LIMITS.inlineStateBytes` are kept.
    */
   BUG_BLOBS?: R2Bucket
-  /** `"false"` stops serving `GET /api/v1/matches`; anything else (unset included) serves it. */
+  /** Shared Node/Cloudflare boolean parsing; unset serves the public lobby list. */
   PUBLIC_LISTING?: string
+  /** Comma-separated browser origins allowed to call the API. */
+  CORS_ORIGINS?: string
   RATE_LIMIT_PER_MINUTE?: string
   MEMBER_RATE_LIMIT_PER_MINUTE?: string
   UPLOAD_RATE_LIMIT_PER_MINUTE?: string
   BUG_REPORT_RATE_LIMIT_PER_MINUTE?: string
-  /** Days before a finished, abandoned or never-started match is deleted. 0 keeps everything. */
+  /** Matches created per minute across every caller, per isolate. */
+  MATCH_CREATION_RATE_LIMIT_PER_MINUTE?: string
+  /** Days before a finished or abandoned match is deleted. 0 keeps them forever. */
   RETENTION_DAYS?: string
+  /**
+   * Days before a lobby that was never started is deleted. 0 keeps them forever. Unset (or not a
+   * whole number) is three days, or 0 when `RETENTION_DAYS` is 0.
+   */
+  LOBBY_RETENTION_DAYS?: string
   /**
    * Days before a RUNNING match with nobody active in it is deleted. 0 keeps them forever.
    *
@@ -36,6 +45,14 @@ export interface Env {
    * nothing else ever collects one of those.
    */
   ABANDONED_RETENTION_DAYS?: string
+  /**
+   * Days before a running match is deleted whatever its roster says, because nothing has happened
+   * in it for that long. Unset (or not a whole number) follows `ABANDONED_RETENTION_DAYS` (three
+   * times as long).
+   */
+  SILENT_RETENTION_DAYS?: string
+  /** Matches each retention window deletes per cron run. */
+  RETENTION_BATCH_SIZE?: string
   /** Days a bug report and its R2 object are kept. 0 keeps them forever. */
   BUG_REPORT_RETENTION_DAYS?: string
   /** Attached journal megabytes accepted per rolling day across every reporter. 0 lifts the cap. */

package/src/index.ts

@@ -1,6 +1,9 @@
 import { RateLimitedError, RateLimiter } from '@chaos-overlords/kernel'
 import {
   type AppEnv,
+  configFlag,
+  configInteger,
+  configList,
   createApp,
   DEFAULT_RATE_LIMITS,
   DEFAULT_SERVER_CONFIG,
@@ -16,6 +19,13 @@ export { MatchHub } from './MatchHub'
 
 type Built = { container: ServerContainer; app: Hono<AppEnv> }
 
+type RateLimitVar =
+  | 'RATE_LIMIT_PER_MINUTE'
+  | 'MEMBER_RATE_LIMIT_PER_MINUTE'
+  | 'UPLOAD_RATE_LIMIT_PER_MINUTE'
+  | 'BUG_REPORT_RATE_LIMIT_PER_MINUTE'
+  | 'MATCH_CREATION_RATE_LIMIT_PER_MINUTE'
+
 /**
  * One container per isolate, held in module scope.
  *
@@ -48,11 +58,10 @@ export function resetContainerForTests(): void {
 
 export function buildContainer(env: Env): ServerContainer {
   const clock = { now: () => new Date() }
-  const perMinute = (raw: string | undefined, fallback: number) => {
-    const limit = Number(raw ?? fallback)
-    const effective = Number.isInteger(limit) && limit > 0 ? limit : fallback
-    return new RateLimiter(clock, { limit: effective, windowMs: 60_000 })
-  }
+  // A misconfigured var refuses every request and every cron run until it is fixed, so the error
+  // names the variable: a Worker has no startup log for it to go unnoticed in, only request errors.
+  const perMinute = (name: RateLimitVar, fallback: number) =>
+    new RateLimiter(clock, { limit: configInteger(env[name], fallback, 1, name), windowMs: 60_000 })
   const bugReports = buildBugReports(env)
   return {
     kernel: buildKernel(env),
@@ -80,21 +89,29 @@ export function buildContainer(env: Env): ServerContainer {
       },
     },
     rateLimiters: {
-      anonymous: perMinute(env.RATE_LIMIT_PER_MINUTE, DEFAULT_RATE_LIMITS.anonymousPerMinute),
-      member: perMinute(env.MEMBER_RATE_LIMIT_PER_MINUTE, DEFAULT_RATE_LIMITS.memberPerMinute),
-      upload: perMinute(env.UPLOAD_RATE_LIMIT_PER_MINUTE, DEFAULT_RATE_LIMITS.uploadPerMinute),
+      anonymous: perMinute('RATE_LIMIT_PER_MINUTE', DEFAULT_RATE_LIMITS.anonymousPerMinute),
+      member: perMinute('MEMBER_RATE_LIMIT_PER_MINUTE', DEFAULT_RATE_LIMITS.memberPerMinute),
+      upload: perMinute('UPLOAD_RATE_LIMIT_PER_MINUTE', DEFAULT_RATE_LIMITS.uploadPerMinute),
       bugReport: perMinute(
-        env.BUG_REPORT_RATE_LIMIT_PER_MINUTE,
+        'BUG_REPORT_RATE_LIMIT_PER_MINUTE',
         DEFAULT_RATE_LIMITS.bugReportPerMinute,
       ),
       bugReportState: new RateLimiter(clock, {
         limit: DEFAULT_RATE_LIMITS.bugReportStatePerDay,
         windowMs: 24 * 60 * 60 * 1000,
       }),
+      matchCreation: perMinute(
+        'MATCH_CREATION_RATE_LIMIT_PER_MINUTE',
+        DEFAULT_RATE_LIMITS.matchCreationPerMinute,
+      ),
     },
     // Listing is on unless a deployment turns it off: an unset var means the Browse screen works,
     // rather than every client being told the server lists nothing.
-    config: { ...DEFAULT_SERVER_CONFIG, publicListing: env.PUBLIC_LISTING !== 'false' },
+    config: {
+      ...DEFAULT_SERVER_CONFIG,
+      publicListing: configFlag(env.PUBLIC_LISTING, true, 'PUBLIC_LISTING'),
+      corsOrigins: configList(env.CORS_ORIGINS),
+    },
     // `CF-Connecting-IP` is authoritative here and only here: Cloudflare sets it on every request
     // that reaches a Worker and a client cannot forge it through the edge. Off Cloudflare it is a
     // header anyone can write, which is why the default resolver ignores it unless told otherwise.

package/src/kernel.ts

@@ -8,10 +8,14 @@ import {
 } from '@chaos-overlords/bug-reports'
 import {
   createKernel,
+  DEFAULT_RETENTION_BATCH_SIZE,
+  DEFAULT_RETENTION_DAYS,
   type DeadlineScheduler,
   type EventNotifier,
   type Kernel,
   type Logger,
+  type RetentionPolicy,
+  retentionPolicyFromDays,
   type StreamCloser,
 } from '@chaos-overlords/kernel'
 import { createSqliteStorage, sqliteSchema } from '@chaos-overlords/storage/sqlite'
@@ -27,8 +31,6 @@ export const workerLogger: Logger = {
 }
 
 const DAY_MS = 24 * 60 * 60 * 1000
-const DEFAULT_RETENTION_DAYS = 30
-const DEFAULT_ABANDONED_RETENTION_DAYS = 90
 
 /** A non-negative whole number from an environment variable; anything else reads as `fallback`. */
 function wholeNumber(raw: string | undefined, fallback: number): number {
@@ -36,6 +38,42 @@ function wholeNumber(raw: string | undefined, fallback: number): number {
   return Number.isInteger(value) && value >= 0 ? value : fallback
 }
 
+/** A whole number when the variable is set, `undefined` when it is unset or not a whole number. */
+function optionalWholeNumber(raw: string | undefined): number | undefined {
+  if (raw === undefined || raw === '') return undefined
+  const value = Number(raw)
+  return Number.isInteger(value) && value >= 0 ? value : undefined
+}
+
+/**
+ * The retention windows from the vars, with the kernel's defaults for any that are unset.
+ *
+ * The lobby and silent windows are only passed when they are set to a whole number, so the kernel
+ * derives them the same way it does on Node: the silent window from the abandoned one, the lobby
+ * window from `RETENTION_DAYS`'s off switch. A mistyped value reads as unset rather than as a
+ * fixed default, because a fixed silent window could end up shorter than the abandoned window and
+ * collect matches whose players are still seated. Node refuses to start on the same input; a
+ * Worker has no start to refuse, so the derived window is the safe reading.
+ */
+export function retentionPolicyFor(env: Env): RetentionPolicy {
+  const lobby = optionalWholeNumber(env.LOBBY_RETENTION_DAYS)
+  const silentLive = optionalWholeNumber(env.SILENT_RETENTION_DAYS)
+  const batchSize = wholeNumber(env.RETENTION_BATCH_SIZE, DEFAULT_RETENTION_BATCH_SIZE)
+  return retentionPolicyFromDays(
+    {
+      finished: wholeNumber(env.RETENTION_DAYS, DEFAULT_RETENTION_DAYS.finished),
+      abandonedLive: wholeNumber(
+        env.ABANDONED_RETENTION_DAYS,
+        DEFAULT_RETENTION_DAYS.abandonedLive,
+      ),
+      ...(lobby === undefined ? {} : { lobby }),
+      ...(silentLive === undefined ? {} : { silentLive }),
+    },
+    // A batch of 0 would delete nothing while looking switched on; the windows are the off switch.
+    batchSize > 0 ? batchSize : DEFAULT_RETENTION_BATCH_SIZE,
+  )
+}
+
 export const HUB_PATHS = {
   notify: '/notify',
   schedule: '/schedule',
@@ -125,18 +163,7 @@ export function buildKernel(
       clock: { now: () => new Date() },
       logger: workerLogger,
     },
-    {
-      retention: {
-        maxAgeMs: wholeNumber(env.RETENTION_DAYS, DEFAULT_RETENTION_DAYS) * DAY_MS,
-        abandonedLiveMaxAgeMs:
-          wholeNumber(env.ABANDONED_RETENTION_DAYS, DEFAULT_ABANDONED_RETENTION_DAYS) * DAY_MS,
-        // Twice the abandoned window, and without its roster test, which never collects an untimed
-        // match whose players' clients died without a `leave`.
-        silentLiveMaxAgeMs:
-          wholeNumber(env.ABANDONED_RETENTION_DAYS, DEFAULT_ABANDONED_RETENTION_DAYS) * 2 * DAY_MS,
-        batchSize: 50,
-      },
-    },
+    { retention: retentionPolicyFor(env) },
   )
 }