@trolleroof/tui 0.2.4 → 0.2.6

package/src/recording/recorder.ts

@@ -0,0 +1,464 @@
+import type { StepResult } from "../core/game.js";
+import { buildChunk, estimatedBytes } from "./chunks.js";
+import {
+  resolveRecordingConfig,
+  type RecordingConfig,
+} from "./config.js";
+import { createChunkId, createEventId, createGameId } from "./ids.js";
+import {
+  RecordingStore,
+  type ReadonlyRecoveryChunkIndex,
+  type RecoveryChunkIndex,
+} from "./store.js";
+import { DisabledTransport, type ChunkTransport } from "./transport.js";
+import type {
+  ActionEvent,
+  ActionSource,
+  GameEndedEvent,
+  GameEvent,
+  EventSource,
+  GameOutcome,
+  GameStartedEvent,
+  RecordingHealth,
+} from "./types.js";
+import { ChunkUploader } from "./uploader.js";
+
+export interface RecorderOptions {
+  store: RecordingStore;
+  gameType: string;
+  gameVersion: string;
+  seed: number;
+  initialState: unknown;
+  applicationVersion?: string;
+  config?: Partial<RecordingConfig>;
+  transport?: ChunkTransport;
+  wallTimeMs?: () => number;
+  monotonicTimeMs?: () => number;
+  createGameId?: () => string;
+  createEventId?: () => string;
+  createChunkId?: () => string;
+}
+
+export interface RecordActionInput {
+  action: string;
+  source: ActionSource;
+  stateBefore: unknown;
+  result: StepResult;
+  stateAfter: unknown;
+}
+
+export interface EndGameInput {
+  outcome: GameOutcome;
+  finalState: unknown;
+  finalScore: number;
+  success: boolean;
+}
+
+function cloneSnapshot<T>(value: T): T {
+  return structuredClone(value);
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export class GameplayRecorder {
+  readonly gameId: string;
+
+  private readonly store: RecordingStore;
+  private readonly gameType: string;
+  private readonly gameVersion: string;
+  private readonly applicationVersion: string;
+  private readonly config: RecordingConfig;
+  private readonly uploader: ChunkUploader;
+  private readonly wallTimeMs: () => number;
+  private monotonicOrigin: number | null = null;
+  private readonly monotonicTimeMs: () => number;
+  private readonly nextEventId: () => string;
+  private readonly nextChunkId: () => string;
+  private readonly buffered: GameEvent[] = [];
+  private nextEventSequence = 1;
+  private nextChunkSequence = 1;
+  private flushTimer: ReturnType<typeof setTimeout> | null = null;
+  private uploadRequested = false;
+  private uploadInFlight: Promise<void> | null = null;
+  private ended = false;
+  private recordingHealth: RecordingHealth = { status: "healthy" };
+
+  constructor(options: RecorderOptions) {
+    this.store = options.store;
+    this.gameType = options.gameType;
+    this.gameVersion = options.gameVersion;
+    this.applicationVersion = options.applicationVersion ?? "dev";
+    this.config = resolveRecordingConfig(options.config);
+    this.wallTimeMs = options.wallTimeMs ?? Date.now;
+    this.monotonicTimeMs = options.monotonicTimeMs ?? (() => performance.now());
+    this.gameId = (options.createGameId ?? createGameId)();
+    this.nextEventId = options.createEventId ?? createEventId;
+    this.nextChunkId = options.createChunkId ?? createChunkId;
+    this.uploader = new ChunkUploader(
+      this.store,
+      options.transport ?? new DisabledTransport(),
+    );
+
+    const event: GameStartedEvent = {
+      ...this.envelope("system"),
+      event_type: "game_started",
+      payload: {
+        game_type: this.gameType,
+        game_version: this.gameVersion,
+        seed: options.seed,
+        initial_state: cloneSnapshot(options.initialState),
+      },
+    };
+    this.append(event);
+    this.startUpload();
+  }
+
+  health(): RecordingHealth {
+    return { ...this.recordingHealth };
+  }
+
+  recordAction(input: RecordActionInput): void {
+    if (this.ended) return;
+    try {
+      const stateBefore = cloneSnapshot(input.stateBefore);
+      const stateAfter = cloneSnapshot(input.stateAfter);
+      const clonedRandomEffects = input.result.randomEffects === undefined
+        ? undefined
+        : cloneSnapshot(input.result.randomEffects);
+      const result = {
+        reward: input.result.reward,
+        moved: input.result.moved,
+        done: input.result.done,
+        success: input.result.success,
+      };
+      const event: ActionEvent = {
+        ...this.envelope(input.source),
+        event_type: "action",
+        payload: {
+          action: input.action,
+          state_before: stateBefore,
+          result,
+          state_after: stateAfter,
+          ...(clonedRandomEffects === undefined
+            ? {}
+            : { random_effects: clonedRandomEffects }),
+        },
+      };
+      this.append(event);
+    } catch (error) {
+      this.degrade(error);
+    }
+  }
+
+  endGame(input: EndGameInput): void {
+    if (this.ended) return;
+    try {
+      const finalSequence = this.nextEventSequence;
+      const event: GameEndedEvent = {
+        ...this.envelope("system"),
+        event_type: "game_ended",
+        payload: {
+          outcome: input.outcome,
+          final_state: cloneSnapshot(input.finalState),
+          final_score: input.finalScore,
+          success: input.success,
+          final_event_sequence: finalSequence,
+        },
+      };
+      this.append(event);
+    } catch (error) {
+      this.degrade(error);
+    }
+    this.ended = true;
+    this.flush();
+    if (this.buffered.length === 0) {
+      this.attempt(() => this.store.finalizeGame(this.gameId));
+    }
+    this.startUpload();
+  }
+
+  flush(): void {
+    this.clearFlushTimer();
+    try {
+      this.flushBuffered();
+    } catch (error) {
+      this.degrade(error);
+    }
+    if (this.buffered.length > 0) this.scheduleFlush();
+    this.startUpload();
+  }
+
+  private flushBuffered(): void {
+    while (this.buffered.length > 0) {
+      const events = this.takeChunkEvents();
+      const chunk = buildChunk({
+        gameId: this.gameId,
+        gameType: this.gameType,
+        gameVersion: this.gameVersion,
+        chunkId: this.nextChunkId(),
+        chunkSequence: this.nextChunkSequence,
+        createdAtMs: this.wallTimeMs(),
+        applicationVersion: this.applicationVersion,
+        events,
+      });
+      if (!this.attempt(() => this.store.persistChunk(chunk))) break;
+      this.buffered.splice(0, events.length);
+      this.nextChunkSequence++;
+    }
+  }
+
+  shutdown(): void {
+    this.clearFlushTimer();
+    this.flush();
+    this.startUpload();
+  }
+
+  async drainUploads(): Promise<void> {
+    this.flush();
+    while (this.uploadInFlight) {
+      await this.uploadInFlight;
+    }
+  }
+
+  private envelope<Source extends EventSource>(source: Source) {
+    const monotonicNow = this.monotonicTimeMs();
+    this.monotonicOrigin ??= monotonicNow;
+    return {
+      event_id: this.nextEventId(),
+      event_sequence: this.nextEventSequence++,
+      event_version: 1 as const,
+      source,
+      client_time_ms: this.wallTimeMs(),
+      monotonic_time_ms: Math.max(0, monotonicNow - this.monotonicOrigin),
+    };
+  }
+
+  private append(event: GameEvent): void {
+    this.attempt(() => this.store.appendEvent(this.gameId, event));
+    this.buffered.push(event);
+    if (
+      this.buffered.length >= this.config.maxEventsPerChunk ||
+      estimatedBytes(this.buffered) >= this.config.maxEstimatedChunkBytes
+    ) {
+      this.flush();
+    } else {
+      this.scheduleFlush();
+    }
+  }
+
+  private takeChunkEvents(): GameEvent[] {
+    const selected: GameEvent[] = [];
+    for (const event of this.buffered) {
+      if (selected.length >= this.config.maxEventsPerChunk) break;
+      if (
+        selected.length > 0 &&
+        estimatedBytes([...selected, event]) > this.config.maxEstimatedChunkBytes
+      ) {
+        break;
+      }
+      selected.push(event);
+    }
+    return selected;
+  }
+
+  private scheduleFlush(): void {
+    if (this.flushTimer || this.ended) return;
+    this.flushTimer = setTimeout(() => {
+      this.flushTimer = null;
+      this.flush();
+    }, this.config.flushIntervalMs);
+    this.flushTimer.unref?.();
+  }
+
+  private clearFlushTimer(): void {
+    if (!this.flushTimer) return;
+    clearTimeout(this.flushTimer);
+    this.flushTimer = null;
+  }
+
+  private startUpload(): void {
+    if (this.uploadInFlight) {
+      this.uploadRequested = true;
+      return;
+    }
+    this.uploadRequested = false;
+    this.uploadInFlight = this.uploader.uploadPending()
+      .then(() => undefined)
+      .catch((error: unknown) => {
+        this.degrade(error);
+      })
+      .finally(() => {
+        this.uploadInFlight = null;
+        if (this.uploadRequested) {
+          this.uploadRequested = false;
+          this.startUpload();
+        }
+      });
+  }
+
+  private attempt<T>(operation: () => T): T | undefined {
+    try {
+      return operation();
+    } catch (error) {
+      this.degrade(error);
+      return undefined;
+    }
+  }
+
+  private degrade(error: unknown): void {
+    this.recordingHealth = {
+      status: "degraded",
+      last_error: errorMessage(error),
+    };
+  }
+}
+
+export interface RecoveryOptions {
+  applicationVersion?: string;
+  config?: Partial<RecordingConfig>;
+  createChunkId?: () => string;
+  wallTimeMs?: () => number;
+}
+
+export interface RecoveryResult {
+  games: number;
+  chunks: number;
+  events: number;
+}
+
+export function recoverActiveRecordings(
+  store: RecordingStore,
+  options: RecoveryOptions = {},
+): RecoveryResult {
+  const persisted = [...store.listPending(), ...store.listFailed(), ...store.listCompletedChunks()];
+  return recoverActiveRecordingGames(
+    store,
+    options,
+    store.listActiveGameIds(),
+    indexChunksByGame(persisted),
+  );
+}
+
+export async function recoverActiveRecordingsBatched(
+  store: RecordingStore,
+  options: RecoveryOptions & {
+    batchSize?: number;
+    yieldControl?: () => Promise<void>;
+    signal?: AbortSignal;
+    persistedByGame?: ReadonlyRecoveryChunkIndex;
+  } = {},
+): Promise<RecoveryResult> {
+  const batchSize = Math.max(1, options.batchSize ?? 16);
+  const yieldControl = options.yieldControl ?? (() =>
+    new Promise<void>((resolve) => setTimeout(resolve, 0))
+  );
+  const persistedByGame = options.persistedByGame ?? await store.buildRecoveryChunkIndex({
+    batchSize,
+    yieldControl,
+    signal: options.signal,
+  });
+  if (options.signal?.aborted) return { games: 0, chunks: 0, events: 0 };
+  const total: RecoveryResult = { games: 0, chunks: 0, events: 0 };
+  for await (const gameId of store.iterateActiveGameIdsBatched({
+    batchSize,
+    yieldControl,
+    signal: options.signal,
+  })) {
+    if (options.signal?.aborted) break;
+    const batch = recoverActiveRecordingGames(
+      store,
+      options,
+      [gameId],
+      persistedByGame,
+    );
+    total.games += batch.games;
+    total.chunks += batch.chunks;
+    total.events += batch.events;
+  }
+  return total;
+}
+
+function recoverActiveRecordingGames(
+  store: RecordingStore,
+  options: RecoveryOptions,
+  gameIds: string[],
+  persistedByGame: ReadonlyRecoveryChunkIndex,
+): RecoveryResult {
+  const config = resolveRecordingConfig(options.config);
+  const nextChunkId = options.createChunkId ?? createChunkId;
+  const wallTimeMs = options.wallTimeMs ?? Date.now;
+  const result: RecoveryResult = { games: 0, chunks: 0, events: 0 };
+
+  for (const gameId of gameIds) {
+    const events = store.readActiveEvents(gameId);
+    const started = events.find(
+      (event): event is GameStartedEvent => event.event_type === "game_started",
+    );
+    if (!started) continue;
+    const existing = persistedByGame.get(gameId) ?? [];
+    const assignedThrough = Math.max(
+      0,
+      ...existing.map((item) => item.chunk.last_event_sequence),
+    );
+    let chunkSequence = Math.max(
+      0,
+      ...existing.map((item) => item.chunk.chunk_sequence),
+    ) + 1;
+    const unassigned = events.filter(
+      (event) => event.event_sequence > assignedThrough,
+    );
+    if (unassigned.length === 0) {
+      if (events.at(-1)?.event_type === "game_ended") {
+        store.finalizeGame(gameId);
+      }
+      continue;
+    }
+    result.games++;
+
+    while (unassigned.length > 0) {
+      const selected: GameEvent[] = [];
+      while (
+        unassigned.length > 0 &&
+        selected.length < config.maxEventsPerChunk
+      ) {
+        const event = unassigned[0]!;
+        if (
+          selected.length > 0 &&
+          estimatedBytes([...selected, event]) > config.maxEstimatedChunkBytes
+        ) {
+          break;
+        }
+        selected.push(unassigned.shift()!);
+      }
+      store.persistChunk(buildChunk({
+        gameId,
+        gameType: started.payload.game_type,
+        gameVersion: started.payload.game_version,
+        chunkId: nextChunkId(),
+        chunkSequence,
+        createdAtMs: wallTimeMs(),
+        applicationVersion: options.applicationVersion ?? "dev",
+        events: selected,
+      }));
+      chunkSequence++;
+      result.chunks++;
+      result.events += selected.length;
+    }
+    if (events.at(-1)?.event_type === "game_ended") store.finalizeGame(gameId);
+  }
+  return result;
+}
+
+function indexChunksByGame(
+  persisted: ReturnType<RecordingStore["listPending"]>,
+): RecoveryChunkIndex {
+  const persistedByGame: RecoveryChunkIndex = new Map();
+  for (const item of persisted) {
+    const game = persistedByGame.get(item.chunk.game_id) ?? [];
+    game.push(item);
+    persistedByGame.set(item.chunk.game_id, game);
+  }
+  return persistedByGame;
+}

package/src/recording/store.test.ts

@@ -0,0 +1,231 @@
+import { appendFileSync, chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { RecordingStore } from "./store.js";
+import type { GameEvent, GameEventChunk } from "./types.js";
+
+const roots: string[] = [];
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+function root(): string {
+  const dir = mkdtempSync(join(tmpdir(), "gamepigeon-recording-"));
+  roots.push(dir);
+  return dir;
+}
+
+function event(sequence: number): GameEvent {
+  return {
+    event_id: `evt_${sequence}`,
+    event_sequence: sequence,
+    event_type: sequence === 1 ? "game_started" : "action",
+    event_version: 1,
+    source: sequence === 1 ? "system" : "player",
+    client_time_ms: sequence,
+    monotonic_time_ms: sequence,
+    payload: sequence === 1
+      ? { game_type: "2048", game_version: "1", seed: 7, initial_state: { board: [] } }
+      : { action: "left", state_before: {}, result: { reward: 0, moved: false, done: false, success: false }, state_after: {} },
+  } as GameEvent;
+}
+
+function chunk(): GameEventChunk {
+  const events = [event(1), event(2)];
+  return {
+    schema_version: 1,
+    game_id: "game_1",
+    game_type: "2048",
+    game_version: "1",
+    chunk_id: "chk_1",
+    chunk_sequence: 1,
+    first_event_sequence: 1,
+    last_event_sequence: 2,
+    event_count: events.length,
+    created_at_ms: 10,
+    client: { platform: "tui", application_version: "dev", recording_sdk_version: "1" },
+    events,
+  };
+}
+
+describe("RecordingStore", () => {
+  it("enforces private directory and file modes under a permissive umask", () => {
+    const previous = process.umask(0);
+    try {
+      const dir = root();
+      const store = new RecordingStore(dir);
+      store.appendEvent("game_1", event(1));
+      const persisted = store.persistChunk(chunk());
+      const failed = store.markFailed(persisted, "private reason");
+      expect(statSync(dir).mode & 0o777).toBe(0o700);
+      for (const directory of ["active", "pending", "failed", "completed", "completed/games", "completed/chunks"]) {
+        expect(statSync(join(dir, directory)).mode & 0o777).toBe(0o700);
+      }
+      expect(statSync(store.activePath("game_1")).mode & 0o777).toBe(0o600);
+      expect(statSync(failed).mode & 0o777).toBe(0o600);
+      expect(statSync(`${failed}.error.txt`).mode & 0o777).toBe(0o600);
+    } finally {
+      process.umask(previous);
+    }
+  });
+
+  it("creates the recording directory contract", () => {
+    const dir = root();
+    new RecordingStore(dir);
+    for (const name of ["active", "pending", "failed", "completed/games", "completed/chunks"]) {
+      expect(existsSync(join(dir, name))).toBe(true);
+    }
+  });
+
+  it("appends events to an active JSONL log", () => {
+    const store = new RecordingStore(root());
+    store.appendEvent("game_1", event(1));
+    store.appendEvent("game_1", event(2));
+    expect(store.readActiveEvents("game_1").map((item) => item.event_sequence)).toEqual([1, 2]);
+  });
+
+  it("persists immutable exact chunk bytes", () => {
+    const store = new RecordingStore(root());
+    const value = chunk();
+    const persisted = store.persistChunk(value);
+    const bytes = readFileSync(persisted.path, "utf8");
+    expect(bytes).toBe(JSON.stringify(value));
+    expect(store.persistChunk(value).bytes).toBe(bytes);
+    expect(() => store.persistChunk({ ...value, created_at_ms: 11 })).toThrow("conflicting bytes");
+  });
+
+  it("yields while indexing a large persisted recovery backlog", async () => {
+    const store = new RecordingStore(root());
+    for (let index = 0; index < 12; index++) {
+      store.persistChunk({
+        ...chunk(),
+        game_id: `game_${index}`,
+        chunk_id: `chk_${index}`,
+      });
+    }
+    let yields = 0;
+    const persisted = await store.listRecoveryChunksBatched({
+      batchSize: 5,
+      yieldControl: async () => { yields++; },
+    });
+    expect(persisted).toHaveLength(12);
+    expect(yields).toBe(2);
+  });
+
+  it("cancels chunk indexing at a batch boundary without touching later files", async () => {
+    const store = new RecordingStore(root());
+    for (let index = 0; index < 8; index++) {
+      store.persistChunk({
+        ...chunk(),
+        game_id: `game_${index}`,
+        chunk_id: `chk_${index}`,
+      });
+    }
+    const cancellation = new AbortController();
+    let yields = 0;
+    const indexed = await store.buildRecoveryChunkIndex({
+      batchSize: 2,
+      signal: cancellation.signal,
+      yieldControl: async () => {
+        yields++;
+        if (yields === 2) cancellation.abort();
+      },
+    });
+
+    expect(yields).toBe(2);
+    expect([...indexed.values()].flat()).toHaveLength(4);
+    expect(store.listPending()).toHaveLength(8);
+  });
+
+  it("builds one linear per-game chunk index", async () => {
+    class CountingStore extends RecordingStore {
+      reads = 0;
+
+      protected override readChunk(path: string) {
+        this.reads++;
+        return super.readChunk(path);
+      }
+    }
+    const store = new CountingStore(root());
+    for (let game = 0; game < 6; game++) {
+      for (let sequence = 1; sequence <= 3; sequence++) {
+        store.persistChunk({
+          ...chunk(),
+          game_id: `game_${game}`,
+          chunk_id: `chk_${game}_${sequence}`,
+          chunk_sequence: sequence,
+        });
+      }
+    }
+    let yields = 0;
+    const indexed = await store.buildRecoveryChunkIndex({
+      batchSize: 4,
+      yieldControl: async () => { yields++; },
+    });
+
+    expect(indexed.size).toBe(6);
+    expect([...indexed.values()].every((items) => items.length === 3)).toBe(true);
+    expect(store.reads).toBe(18);
+    expect(yields).toBe(4);
+  });
+
+  it("moves only acknowledged chunks into completed storage", () => {
+    const store = new RecordingStore(root());
+    const persisted = store.persistChunk(chunk());
+    const destination = store.acknowledge(persisted);
+    expect(existsSync(persisted.path)).toBe(false);
+    expect(existsSync(destination)).toBe(true);
+  });
+
+  it("quarantines permanent failures", () => {
+    const store = new RecordingStore(root());
+    const persisted = store.persistChunk(chunk());
+    const destination = store.markFailed(persisted, "invalid schema");
+    expect(existsSync(destination)).toBe(true);
+    expect(readFileSync(`${destination}.error.txt`, "utf8")).toContain("invalid schema");
+  });
+
+  it("finalizes the active game log", () => {
+    const store = new RecordingStore(root());
+    store.appendEvent("game_1", event(1));
+    const destination = store.finalizeGame("game_1");
+    expect(destination).not.toBeNull();
+    expect(existsSync(destination!)).toBe(true);
+    expect(store.readActiveEvents("game_1")).toEqual([]);
+  });
+
+  it("lists completed game logs for local inspection", () => {
+    const store = new RecordingStore(root());
+    store.appendEvent("game_1", event(1));
+    store.finalizeGame("game_1");
+    expect(store.listCompletedGames()).toEqual([{ gameId: "game_1", events: [event(1)] }]);
+  });
+
+  it("tightens preexisting completed-game directories and logs when listed", () => {
+    const previous = process.umask(0);
+    try {
+      const dir = root();
+      const store = new RecordingStore(dir);
+      store.appendEvent("game_legacy", event(1));
+      const path = store.finalizeGame("game_legacy")!;
+      chmodSync(join(dir, "completed"), 0o777);
+      chmodSync(join(dir, "completed", "games"), 0o777);
+      chmodSync(path, 0o666);
+
+      expect(store.listCompletedGames()).toHaveLength(1);
+      expect(statSync(join(dir, "completed")).mode & 0o777).toBe(0o700);
+      expect(statSync(join(dir, "completed", "games")).mode & 0o777).toBe(0o700);
+      expect(statSync(path).mode & 0o777).toBe(0o600);
+    } finally {
+      process.umask(previous);
+    }
+  });
+
+  it("recovers valid events before a torn final JSONL write", () => {
+    const store = new RecordingStore(root());
+    store.appendEvent("game_1", event(1));
+    appendFileSync(store.activePath("game_1"), "{\"event_id\":");
+    expect(store.readActiveEvents("game_1")).toEqual([event(1)]);
+  });
+});