def-game 5.0.1 → 5.1.0-timeout.0

package/README.md

@@ -39,7 +39,7 @@ V5 は破壊的変更です。GameRule、GameEngine、TaskQueue に関する型
 
 ## Worker generator（5.0.1）
 
-Selfish で検証した Hono Worker、SQLite-backed Durable Object、waki.work JWT 認証、Hibernation WebSocket、保存・配信処理を生成します。GameDefinition の契約変更はありません。現在は timeout / Effect 実行なしの構成が対象です。
+Hono Worker、SQLite-backed Durable Object、waki.work JWT 認証、Hibernation WebSocket、保存・配信処理を生成します。GameDefinition の契約変更はありません。標準構成は timeout / Effect 実行なしです。開発版では下記の timeout オプションを追加しています。
 
 server package に `def-game.worker.json` を作ります。全パスはこの設定ファイルのディレクトリ基準です。
 
@@ -62,7 +62,9 @@ npx def-game generate-worker --config def-game.worker.json
 npx def-game generate-worker --config def-game.worker.json --check
 ```
 
-生成対象は `outputDir` 内の `index.ts`、`session.ts`、`auth.ts`、`env.ts`、`runtime/parse.ts`、`runtime/game-adapter.ts` と、`entry`、`wranglerConfig` の計8ファイルです。Hono / jose は利用側の runtime dependency で、generator 自体に実行時依存はありません。Selfish は Hono 4.13.7、jose 6.2.12、Wrangler 4.131.1 で検証しています。
+生成対象は `outputDir` 内の `index.ts`、`session.ts`、`auth.ts`、`env.ts`、`runtime/parse.ts`、`runtime/game-adapter.ts` と、`entry`、`wranglerConfig` の計8ファイルです。Hono / jose は利用側の runtime dependency で、generator 自体に実行時依存はありません。
+
+生成コードは Node.js 24.20.0、TypeScript 5.6.3、Hono 4.13.7、jose 6.2.12、Wrangler 4.131.1、`@cloudflare/workers-types` 5.20260911.1 の環境で、ビルド・型チェック・HTTP / WebSocket / Durable Object の通信テストを確認しています。
 
 ゲーム側は既存ファイルとして `adapter` を用意し、次を export します。このファイル、domain、shared は生成・上書きしません。
 
@@ -94,3 +96,26 @@ npm pack
 npm pack / npm publish の前に prepack で型チェック・ビルド・テストが実行されます。build は dist を作り直すため、削除した旧 API の生成物が混入しません。公開対象は dist、bin、templates、package.json、README、LICENSE です。
 
 main にレビュー済みの変更を反映した後、公開する version と認証アカウントを確認し、検証済みのパッケージを npm publish で公開します。
+
+
+## Decision timeout（5.1.0-timeout.0 開発版）
+
+生成設定に `"timeout": true` を追加すると、DO Alarm と system command 配送を生成します。未指定または false なら従来の構成です。開発版は npm 未公開です。
+
+`GameAdapter<State, Command, View, Error, Effect>` に次の任意の接続点を設定します。
+
+```ts
+timeout: {
+  effect: (effect) => /* { type: "schedule", decisionId: string, deadline: number }
+                        または { type: "cancel", decisionId: string } */,
+  command: (decisionId) => /* ゲーム固有の system command */,
+}
+```
+
+ゲームは新しい decision で再利用しない ID と期限を発行します。同じ decision 内の部分完了では Effect を出しません。default action・pending actors・bot policy はゲーム側に残します。runtime は State を解釈せず、1つの現在予約を保存します。独立した複数の同時 decision のスケジューラーではありません。
+
+状態・予約・Alarm は同じ storage transaction で確定します。Alarm は保存済み予約から system command を生成し、古い発火が新しい予約を期限前に処理しないよう再予約します。domain も ID・期限を検証してください。期限を迎えた予約は成功した遷移と同じ transaction で消費し、次の予約があれば置き換えます。失敗は例外として伝播し Cloudflare の有限回の再試行に委ねます。無制限の再試行・外部 Effect の配送は含みません。
+
+このオプションで扱う Effect は timeout の予約・解除のみです。外部通知と異なり、Alarm は状態と原子的に保存するローカルな永続化処理です。外部サービス呼び出しは transaction 内に追加しないでください。
+
+実行環境の検証: Node.js 24、TypeScript 5.6、Hono 4.13、jose 6.2、Wrangler 4.131、Cloudflare Vitest plugin 1.1。標準構成・任意構成の生成一致を generator テストで確認しています。

package/bin/def-game.cjs

@@ -11,7 +11,7 @@ Usage: def-game generate-worker --config <file.json> [--force | --check]
 Generate a Hono Worker, SQLite Durable Object, waki.work authentication and Wrangler config.
 --force  Replace differing output files (never edits the game adapter).
 --check  Verify generated files match without writing anything.
-Node.js 20+ is required. Timeout and Effect execution are not included in this version.`;
+Node.js 20+ is required. Set timeout: true in the config to generate decision timeout scheduling.`;
 
 function relativeImport(from, target) {
   let value = path.relative(path.dirname(from), target).split(path.sep).join('/').replace(/\.ts$/, '.js');
@@ -39,7 +39,8 @@ function main(args) {
   const root = path.dirname(configPath);
   const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
   if (!config || typeof config !== 'object' || Array.isArray(config)) throw new Error('Config must be an object');
-  const allowed = new Set(['outputDir', 'adapter', 'entry', 'wranglerConfig', 'name', 'assets', 'compatibilityDate']);
+  const allowed = new Set(['outputDir', 'adapter', 'entry', 'wranglerConfig', 'name', 'assets', 'compatibilityDate', 'timeout']);
+  if (config.timeout !== undefined && typeof config.timeout !== 'boolean') throw new Error('timeout must be boolean');
   for (const key of Object.keys(config)) if (!allowed.has(key)) throw new Error(`Unknown config key: ${key}`);
   const required = (key) => {
     if (typeof config[key] !== 'string' || !config[key].trim() || config[key].includes('\0')) throw new Error(`Invalid config: ${key}`);
@@ -83,7 +84,8 @@ function main(args) {
   };
   for (const file of ['index.ts', 'session.ts', 'auth.ts', 'env.ts', 'runtime/parse.ts', 'runtime/game-adapter.ts']) {
     const target = path.join(outputDir, file);
-    const source = fs.readFileSync(path.join(__dirname, '../templates/worker', file), 'utf8');
+    const template = config.timeout && ['session.ts', 'runtime/game-adapter.ts'].includes(file) ? path.join('timeout', file) : file;
+    const source = fs.readFileSync(path.join(__dirname, '../templates/worker', template), 'utf8');
     add(target, source.replaceAll('__ADAPTER_IMPORT__', relativeImport(target, adapter)));
   }
   add(entry, `export { default, SessionDurableObject } from ${relativeImport(entry, path.join(outputDir, 'index.ts'))};\n`);

package/dist/game-definition.d.ts

@@ -11,7 +11,8 @@ export type CommandContext<ActorId> = {
 };
 /**
  * 成功時は次の安定状態と副作用の宣言、失敗時はゲーム上の拒否理由を返す。
- * 実行側は成功した状態を保存してから Effect を処理する。
+ * 実行側は成功した状態を保存してから外部 Effect を処理する。
+ * 同じストレージ内の Alarm 予約などは、状態と原子的に保存できる。
  */
 export type TransitionResult<State, Effect, Error> = {
     readonly ok: true;

package/dist/game-definition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"game-definition.d.ts","sourceRoot":"","sources":["../src/game-definition.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,cAAc,CAAC,OAAO,IAC5B;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEpC;;;GAGG;AACH,MAAM,MAAM,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAC3C;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC,GACC;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAEpD;;;GAGG;AACH,MAAM,WAAW,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK;IACxE,0CAA0C;IAC1C,kBAAkB,IAAI,KAAK,CAAC;IAE5B;;;;OAIG;IACH,aAAa,CACT,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,cAAc,CAAC,OAAO,CAAC,GACjC,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IAE1C;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;CACjD"}
+{"version":3,"file":"game-definition.d.ts","sourceRoot":"","sources":["../src/game-definition.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,cAAc,CAAC,OAAO,IAC5B;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEpC;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAC3C;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC,GACC;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAEpD;;;GAGG;AACH,MAAM,WAAW,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK;IACxE,0CAA0C;IAC1C,kBAAkB,IAAI,KAAK,CAAC;IAE5B;;;;OAIG;IACH,aAAa,CACT,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,cAAc,CAAC,OAAO,CAAC,GACjC,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IAE1C;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;CACjD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "def-game",
-  "version": "5.0.1",
+  "version": "5.1.0-timeout.0",
   "description": "Game definition contracts and an in-memory simulator for turn-based games",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/templates/worker/timeout/runtime/game-adapter.ts

@@ -0,0 +1,18 @@
+import type { GameDefinition } from "def-game";
+
+export type TimeoutEffect =
+  | { readonly type: "schedule"; readonly decisionId: string; readonly deadline: number }
+  | { readonly type: "cancel"; readonly decisionId: string };
+
+/** Runtime never interprets State. The adapter translates game effects and timeout commands. */
+export interface GameAdapter<State, Command, View, Error, Effect = never> {
+  readonly game: GameDefinition<State, Command, string, View, Effect, Error>;
+  readonly parseCreate: (input: unknown) => Command | null;
+  readonly parseJoin: (input: unknown) => Command | null;
+  readonly parseCommand: (input: unknown) => Command | null;
+  readonly canConnect: (state: State, actorId: string) => boolean;
+  readonly timeout?: {
+    readonly effect: (effect: Effect) => TimeoutEffect;
+    readonly command: (decisionId: string) => Command;
+  };
+}

package/templates/worker/timeout/session.ts

@@ -0,0 +1,152 @@
+import { DurableObject } from "cloudflare:workers";
+import { gameAdapter, type State, type ServerMessage, type ProtocolError } from __ADAPTER_IMPORT__;
+import type { Env } from "./env.js";
+import { isRecord, parseCommandRequest } from "./runtime/parse.js";
+
+const STATE_KEY = "game-state";
+const TIMEOUT_KEY = "decision-timeout";
+type Reservation = { decisionId: string; deadline: number };
+type Success = Extract<ReturnType<typeof gameAdapter.game.handleCommand>, { ok: true }>;
+
+/** 生成対象の Session runtime。ゲーム固有の判断は gameAdapter だけを通して呼ぶ。 */
+export class SessionDurableObject extends DurableObject<Env> {
+  // State の独自キャッシュを持たない。再起動時にも Storage と attachment だけで復元する。
+  async fetch(request: Request): Promise<Response> {
+    return this.ctx.blockConcurrencyWhile(async () => {
+      const actorId = request.headers.get("x-actor-id");
+      const fail = (code: ProtocolError["code"], status: number) => Response.json({ ok: false, error: { code } }, { status });
+      if (!actorId) return fail("AuthenticationRequired", 401);
+      const path = new URL(request.url).pathname;
+      const stored = await this.ctx.storage.get<State>(STATE_KEY);
+      if (path === "/connect" && request.method === "GET") {
+        if (stored === undefined) return fail("SessionNotFound", 404);
+        if (!gameAdapter.canConnect(stored, actorId)) return fail("NotSessionMember", 403);
+        const viewState = gameAdapter.game.project(stored, actorId);
+        const pair = new WebSocketPair();
+        pair[1].serializeAttachment({ actorId });
+        this.ctx.acceptWebSocket(pair[1]);
+        this.send(pair[1], { type: "ViewStateEvent", viewState });
+        return new Response(null, { status: 101, webSocket: pair[0] });
+      }
+      if (request.method !== "POST" || (path !== "/create" && path !== "/join")) return fail("InvalidRequest", 400);
+      if (path === "/create" && stored !== undefined) return fail("InvalidRequest", 409);
+      if (path === "/join" && stored === undefined) return fail("SessionNotFound", 404);
+      let body: unknown;
+      try { body = await request.json(); } catch { return fail("InvalidRequest", 400); }
+      const command = path === "/create" ? gameAdapter.parseCreate(body) : gameAdapter.parseJoin(body);
+      if (command === null) return fail("InvalidRequest", 400);
+      const result = gameAdapter.game.handleCommand(stored === undefined ? gameAdapter.game.createInitialState() : stored, command, { origin: "actor", actorId });
+      if (!result.ok) return Response.json(result, { status: 409 });
+      // 作成と作成者の参加は、この1回の保存で確定する。
+      if (result.state !== stored || result.effects.length > 0) {
+        try { await this.commit(result); } catch { return fail("InternalError", 500); }
+        this.broadcast(result.state);
+      }
+      return Response.json({ ok: true });
+    });
+  }
+
+  async webSocketMessage(socket: WebSocket, raw: string | ArrayBuffer): Promise<void> {
+    await this.ctx.blockConcurrencyWhile(async () => {
+      const parsed = parseCommandRequest(raw);
+      const command = parsed ? gameAdapter.parseCommand(parsed.command) : null;
+      if (!parsed || command === null) {
+        this.send(socket, { type: "ProtocolErrorEvent", error: { code: "InvalidRequest" } });
+        return;
+      }
+      try {
+        const attachment: unknown = socket.deserializeAttachment();
+        const state = await this.ctx.storage.get<State>(STATE_KEY);
+        if (state === undefined || !isRecord(attachment) || typeof attachment.actorId !== "string" || !gameAdapter.canConnect(state, attachment.actorId)) {
+          this.send(socket, { type: "GameCommandResponse", requestId: parsed.requestId, ok: false, error: { code: "NotSessionMember" } });
+          return;
+        }
+        const result = gameAdapter.game.handleCommand(state, command, { origin: "actor", actorId: attachment.actorId });
+        if (!result.ok) {
+          this.send(socket, { type: "GameCommandResponse", requestId: parsed.requestId, ok: false, error: result.error });
+          return;
+        }
+        await this.commit(result);
+        this.send(socket, { type: "GameCommandResponse", requestId: parsed.requestId, ok: true });
+        this.broadcast(result.state);
+      } catch {
+        console.error("Session command failed");
+        this.send(socket, { type: "GameCommandResponse", requestId: parsed.requestId, ok: false, error: { code: "InternalError" } });
+      }
+    });
+  }
+
+  /** Commit state, reservation and alarm together. No external effects inside the transaction. */
+  private async commit(result: Success, consumedDecisionId?: string): Promise<void> {
+    const effects = result.effects.map(effect => {
+      if (!gameAdapter.timeout) throw new Error("Timeout adapter required for effects");
+      return gameAdapter.timeout.effect(effect);
+    });
+    await this.ctx.storage.transaction(async txn => {
+      await txn.put(STATE_KEY, result.state);
+      if (consumedDecisionId !== undefined) {
+        const current = await txn.get<Reservation>(TIMEOUT_KEY);
+        if (current?.decisionId === consumedDecisionId) {
+          await txn.delete(TIMEOUT_KEY);
+          await txn.deleteAlarm();
+        }
+      }
+      for (const effect of effects) {
+        if (effect.type === "schedule") {
+          if (!effect.decisionId || !Number.isFinite(effect.deadline)) throw new Error("Invalid timeout reservation");
+          await txn.put(TIMEOUT_KEY, { decisionId: effect.decisionId, deadline: effect.deadline });
+          await txn.setAlarm(effect.deadline);
+        } else {
+          const current = await txn.get<Reservation>(TIMEOUT_KEY);
+          if (current?.decisionId === effect.decisionId) {
+            await txn.delete(TIMEOUT_KEY);
+            await txn.deleteAlarm();
+          }
+        }
+      }
+    });
+  }
+
+  async alarm(): Promise<void> {
+    await this.ctx.blockConcurrencyWhile(async () => {
+      const reservation = await this.ctx.storage.get<Reservation>(TIMEOUT_KEY);
+      if (!reservation) return;
+      // An old alarm can wake after a new reservation replaced it. Never expire that decision early.
+      if (Date.now() < reservation.deadline) {
+        await this.ctx.storage.setAlarm(reservation.deadline);
+        return;
+      }
+      const state = await this.ctx.storage.get<State>(STATE_KEY);
+      if (state === undefined || !gameAdapter.timeout) throw new Error("Missing timeout state or adapter");
+      const result = gameAdapter.game.handleCommand(state, gameAdapter.timeout.command(reservation.decisionId), { origin: "system" });
+      if (!result.ok) throw new Error("Timeout command rejected");
+      // Failed commits throw so Cloudflare can retry. Delivery failure never rolls back committed state.
+      await this.commit(result, reservation.decisionId);
+      this.broadcast(result.state);
+    });
+  }
+
+  private broadcast(state: State): void {
+    for (const socket of this.ctx.getWebSockets()) {
+      try {
+        const attachment: unknown = socket.deserializeAttachment();
+        if (!isRecord(attachment) || typeof attachment.actorId !== "string" || !gameAdapter.canConnect(state, attachment.actorId)) continue;
+        this.send(socket, { type: "ViewStateEvent", viewState: gameAdapter.game.project(state, attachment.actorId) });
+      } catch {
+        console.error("Session view delivery failed");
+        this.close(socket);
+      }
+    }
+  }
+
+  private send(socket: WebSocket, message: ServerMessage): void {
+    try { socket.send(JSON.stringify(message)); } catch { this.close(socket); }
+  }
+
+  private close(socket: WebSocket): void {
+    try { socket.close(1011, "Delivery failed"); } catch { /* 切断済み。確定済みの保存結果へ影響させない。 */ }
+  }
+
+  webSocketClose(socket: WebSocket, code: number, reason: string): void { socket.close(code === 1005 || code === 1006 || code === 1015 ? 1000 : code, reason); }
+  webSocketError(socket: WebSocket): void { socket.close(1011, "Connection error"); }
+}