@trolleroof/tui 0.2.5 → 0.2.6

package/src/results/results.test.ts

@@ -0,0 +1,383 @@
+import { mkdtempSync, 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 "../recording/store.js";
+import { TransportError } from "../recording/transport.js";
+import type { EpisodeStartedTraceEvent, EpisodeEndedTraceEvent } from "../recording/types.js";
+import type { InteractionTraceRecorder } from "../recording/trace-recorder.js";
+import {
+  enqueueCompletedResult,
+  recoverCompletedResults,
+  recoverCompletedResultsBatched,
+  resultIdForGame,
+} from "./completion.js";
+import { ResultStore } from "./store.js";
+import type { ResultTransport } from "./transport.js";
+import { ResultUploader } from "./uploader.js";
+
+const roots: string[] = [];
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+function stores() {
+  const root = mkdtempSync(join(tmpdir(), "gamepigeon-results-"));
+  roots.push(root);
+  return { recordings: new RecordingStore(root), results: new ResultStore(root) };
+}
+
+function recorder(gameId = "game_test", userId = "usr_test") {
+  return { gameId, userId, gameType: "2048" } as InteractionTraceRecorder;
+}
+
+function appendCompletedTrace(recordings: RecordingStore, index: number): void {
+  const gameId = `game_${index}`;
+  recordings.appendEvent(gameId, {
+    schema_version: 2,
+    user_id: "usr_test",
+    game_id: gameId,
+    chunk_id: `chk_${index}`,
+    event_id: `evt_${index}_start`,
+    event_sequence: 1,
+    event_version: 1,
+    event_type: "episode_started",
+    visibility: "policy",
+    client_time_ms: 1,
+    monotonic_time_us: 0,
+    payload: {
+      game_type: "2048",
+      game_version: "1",
+      ruleset_id: "classic",
+      telemetry_version: 2,
+      platform: "tui",
+      viewport: { width: 80, height: 24 },
+      control_schema: ["left"],
+      input_semantics: "terminal_impulse",
+    },
+  });
+  recordings.appendEvent(gameId, {
+    schema_version: 2,
+    user_id: "usr_test",
+    game_id: gameId,
+    chunk_id: `chk_${index}`,
+    event_id: `evt_${index}_end`,
+    event_sequence: 2,
+    event_version: 1,
+    event_type: "episode_ended",
+    visibility: "policy",
+    client_time_ms: 2,
+    monotonic_time_us: 1,
+    payload: {
+      reason: "game_over",
+      final_event_sequence: 2,
+      final_score: index,
+      duration_us: 1,
+      completed: true,
+    },
+  });
+  recordings.finalizeGame(gameId);
+}
+
+describe("result outbox", () => {
+  it("keeps result directories and files private under a permissive umask", () => {
+    const previous = process.umask(0);
+    try {
+      const { results } = stores();
+      const persisted = enqueueCompletedResult({
+        store: results,
+        recorder: recorder(),
+        score: 4,
+        completedAtMs: 1,
+      });
+      const failed = results.markFailed(persisted, "private reason");
+      expect(statSync(results.root).mode & 0o777).toBe(0o700);
+      for (const state of ["pending", "completed", "failed"]) {
+        expect(statSync(join(results.root, state)).mode & 0o777).toBe(0o700);
+      }
+      expect(statSync(join(results.root, "failed", "usr_test")).mode & 0o777).toBe(0o700);
+      expect(statSync(failed).mode & 0o777).toBe(0o600);
+      expect(statSync(`${failed}.error.txt`).mode & 0o777).toBe(0o600);
+    } finally {
+      process.umask(previous);
+    }
+  });
+
+  it.each([true, false])("enqueues one result for a terminal completion (success=%s)", (success) => {
+    const { results } = stores();
+    const persisted = enqueueCompletedResult({
+      store: results,
+      recorder: recorder(),
+      score: success ? 2048 : 256,
+      completedAtMs: 1_752_758_400_000,
+    });
+    enqueueCompletedResult({
+      store: results,
+      recorder: recorder(),
+      score: success ? 2048 : 256,
+      completedAtMs: 1_752_758_400_000,
+    });
+
+    expect(results.listPending()).toHaveLength(1);
+    expect(persisted.request).toEqual({
+      result_id: resultIdForGame("game_test"),
+      game_id: "game_test",
+      game_type: "2048",
+      score: success ? 2048 : 256,
+      completed_at: "2025-07-17T13:20:00.000Z",
+    });
+    expect(persisted.bytes).toBe(JSON.stringify(persisted.request));
+  });
+
+  it("yields while indexing a large existing result backlog", async () => {
+    const { results } = stores();
+    for (let index = 0; index < 12; index++) {
+      enqueueCompletedResult({
+        store: results,
+        recorder: recorder(`game_${index}`),
+        score: index,
+        completedAtMs: 1,
+      });
+    }
+    let yields = 0;
+    const keys = await results.listResultKeysBatched({
+      batchSize: 5,
+      yieldControl: async () => { yields++; },
+    });
+    expect(keys).toHaveLength(12);
+    expect(yields).toBe(2);
+  });
+
+  it("stops result indexing promptly when recovery is cancelled", async () => {
+    const { results } = stores();
+    for (let index = 0; index < 8; index++) {
+      enqueueCompletedResult({
+        store: results,
+        recorder: recorder(`game_${index}`),
+        score: index,
+        completedAtMs: 1,
+      });
+    }
+    const cancellation = new AbortController();
+    let yields = 0;
+    const keys = await results.listResultKeysBatched({
+      batchSize: 2,
+      signal: cancellation.signal,
+      yieldControl: async () => {
+        yields++;
+        if (yields === 2) cancellation.abort();
+      },
+    });
+
+    expect(keys).toHaveLength(4);
+    expect(results.listPending()).toHaveLength(8);
+  });
+
+  it("recovers completed episodes and ignores abandoned episodes", () => {
+    const { recordings, results } = stores();
+    const started = {
+      schema_version: 2,
+      user_id: "usr_test",
+      game_id: "game_completed",
+      chunk_id: "chk_1",
+      event_id: "evt_1",
+      event_sequence: 1,
+      event_version: 1,
+      event_type: "episode_started",
+      visibility: "policy",
+      client_time_ms: 100,
+      monotonic_time_us: 0,
+      payload: {
+        game_type: "2048",
+        game_version: "1",
+        ruleset_id: "classic",
+        telemetry_version: 2,
+        platform: "tui",
+        viewport: { width: 80, height: 24 },
+        control_schema: ["left"],
+        input_semantics: "terminal_impulse",
+      },
+    } satisfies EpisodeStartedTraceEvent;
+    const ended = {
+      ...started,
+      event_id: "evt_2",
+      event_sequence: 2,
+      event_type: "episode_ended",
+      client_time_ms: 1_752_758_400_000,
+      payload: {
+        reason: "game_over",
+        final_event_sequence: 2,
+        final_score: 512,
+        duration_us: 100,
+        completed: true,
+      },
+    } satisfies EpisodeEndedTraceEvent;
+    recordings.appendEvent("game_completed", started);
+    recordings.appendEvent("game_completed", ended);
+    recordings.finalizeGame("game_completed");
+    recordings.appendEvent("game_abandoned", { ...started, game_id: "game_abandoned" });
+    recordings.appendEvent("game_abandoned", {
+      ...ended,
+      game_id: "game_abandoned",
+      payload: { ...ended.payload, completed: false, reason: "user_quit" },
+    });
+    recordings.finalizeGame("game_abandoned");
+
+    expect(recoverCompletedResults(recordings, results)).toBe(1);
+    expect(recoverCompletedResults(recordings, results)).toBe(0);
+    expect(results.listPending().map((item) => item.request.game_id)).toEqual([
+      "game_completed",
+    ]);
+  });
+
+  it("indexes existing result ids once for a large recovery backlog", () => {
+    const { recordings, results } = stores();
+    const calls = { pending: 0, completed: 0, failed: 0 };
+    const pending = results.listPending.bind(results);
+    const completed = results.listCompleted.bind(results);
+    const failed = results.listFailed.bind(results);
+    results.listPending = (userId) => { calls.pending++; return pending(userId); };
+    results.listCompleted = (userId) => { calls.completed++; return completed(userId); };
+    results.listFailed = (userId) => { calls.failed++; return failed(userId); };
+    for (let index = 0; index < 40; index++) {
+      appendCompletedTrace(recordings, index);
+    }
+
+    expect(recoverCompletedResults(recordings, results)).toBe(40);
+    expect(calls).toEqual({ pending: 1, completed: 1, failed: 1 });
+  });
+
+  it("yields between bounded completed-game recovery batches", async () => {
+    const { recordings, results } = stores();
+    for (let index = 0; index < 20; index++) appendCompletedTrace(recordings, index);
+    const releases: Array<() => void> = [];
+    const recovery = recoverCompletedResultsBatched(recordings, results, {
+      batchSize: 5,
+      yieldControl: () => new Promise<void>((resolve) => { releases.push(resolve); }),
+    });
+
+    while (releases.length === 0) {
+      await new Promise<void>((resolve) => setTimeout(resolve, 0));
+    }
+    expect(results.listPending()).toHaveLength(5);
+    releases.shift()!();
+    while (releases.length === 0) {
+      await new Promise<void>((resolve) => setTimeout(resolve, 0));
+    }
+    expect(results.listPending()).toHaveLength(10);
+    releases.shift()!();
+    while (releases.length === 0) {
+      await new Promise<void>((resolve) => setTimeout(resolve, 0));
+    }
+    expect(results.listPending()).toHaveLength(15);
+    releases.shift()!();
+    await expect(recovery).resolves.toBe(20);
+    expect(results.listPending()).toHaveLength(20);
+  });
+
+  it("cancels completed-game recovery between batches", async () => {
+    const { recordings, results } = stores();
+    for (let index = 0; index < 10; index++) appendCompletedTrace(recordings, index);
+    const cancellation = new AbortController();
+    let yields = 0;
+    const recovered = await recoverCompletedResultsBatched(recordings, results, {
+      batchSize: 2,
+      signal: cancellation.signal,
+      yieldControl: async () => {
+        yields++;
+        if (yields === 2) cancellation.abort();
+      },
+    });
+
+    expect(recovered).toBe(4);
+    expect(results.listPending()).toHaveLength(4);
+    expect(recordings.listCompletedGames()).toHaveLength(10);
+  });
+
+  it("retries identical bytes after an ambiguous lost response", async () => {
+    const { results } = stores();
+    const persisted = enqueueCompletedResult({
+      store: results,
+      recorder: recorder(),
+      score: 1024,
+      completedAtMs: 1_752_758_400_000,
+    });
+    const bytes: string[] = [];
+    let attempts = 0;
+    const transport: ResultTransport = {
+      async send(result) {
+        bytes.push(result.bytes);
+        attempts++;
+        if (attempts === 1) throw new TransportError("connection reset", true);
+        return { accepted: true, personal_best: 1024, high_score_updated: true };
+      },
+    };
+    const uploader = new ResultUploader(results, transport, {
+      maxAttempts: 2,
+      delay: async () => undefined,
+    });
+
+    expect((await uploader.uploadPending("usr_test")).acknowledged).toBe(1);
+    expect(bytes).toEqual([persisted.bytes, persisted.bytes]);
+    expect(results.listPending()).toHaveLength(0);
+    expect(results.listCompleted()).toHaveLength(1);
+  });
+
+  it("cancels result retry waits without clearing the outbox", async () => {
+    const { results } = stores();
+    enqueueCompletedResult({
+      store: results,
+      recorder: recorder(),
+      score: 32,
+      completedAtMs: 1,
+    });
+    const controller = new AbortController();
+    let waiting = false;
+    let requests = 0;
+    const uploader = new ResultUploader(results, {
+      async send() {
+        requests++;
+        throw new TransportError("offline", true);
+      },
+    }, {
+      delay: async (_ms, signal) => {
+        waiting = true;
+        await new Promise<void>((resolve) => signal?.addEventListener("abort", () => resolve()));
+      },
+    });
+
+    const pending = uploader.uploadPending("usr_test", controller.signal);
+    await Promise.resolve();
+    expect(waiting).toBe(true);
+    controller.abort();
+    await pending;
+    expect(requests).toBe(1);
+    expect(results.listPending("usr_test")).toHaveLength(1);
+  });
+
+  it("never drains another user's results", async () => {
+    const { results } = stores();
+    enqueueCompletedResult({
+      store: results,
+      recorder: recorder("game_a", "usr_a"),
+      score: 4,
+      completedAtMs: 1,
+    });
+    enqueueCompletedResult({
+      store: results,
+      recorder: recorder("game_b", "usr_b"),
+      score: 8,
+      completedAtMs: 2,
+    });
+    const sent: string[] = [];
+    const transport: ResultTransport = {
+      async send(result) {
+        sent.push(result.userId);
+        return { accepted: true, personal_best: result.request.score, high_score_updated: true };
+      },
+    };
+    await new ResultUploader(results, transport).uploadPending("usr_b");
+    expect(sent).toEqual(["usr_b"]);
+    expect(results.listPending().map((item) => item.userId)).toEqual(["usr_a"]);
+  });
+});

package/src/results/store.ts

@@ -0,0 +1,149 @@
+import { randomUUID } from "node:crypto";
+import {
+  existsSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import { opendir } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import type { GameResultRequest, PersistedGameResult } from "./types.js";
+import { ensurePrivateDirectory, ensurePrivateFile } from "../recording/permissions.js";
+
+const SAFE_ID = /^[A-Za-z0-9._-]+$/;
+
+function assertSafeId(kind: string, value: string): void {
+  if (!SAFE_ID.test(value)) throw new Error(`${kind} is not safe for durable storage`);
+}
+
+export class ResultStore {
+  readonly root: string;
+
+  constructor(recordingRoot: string) {
+    this.root = join(recordingRoot, "results");
+    ensurePrivateDirectory(this.root);
+    for (const directory of ["pending", "completed", "failed"]) {
+      ensurePrivateDirectory(join(this.root, directory));
+    }
+  }
+
+  persist(userId: string, request: GameResultRequest): PersistedGameResult {
+    assertSafeId("user_id", userId);
+    assertSafeId("result_id", request.result_id);
+    const bytes = JSON.stringify(request);
+    const path = join(this.root, "pending", userId, `${request.result_id}.json`);
+    for (const state of ["pending", "completed", "failed"] as const) {
+      const existingPath = join(this.root, state, userId, `${request.result_id}.json`);
+      if (!existsSync(existingPath)) continue;
+      ensurePrivateFile(existingPath);
+      const existing = readFileSync(existingPath, "utf8");
+      if (existing !== bytes) {
+        throw new Error(`result ${request.result_id} has conflicting bytes`);
+      }
+      return { userId, request, path: existingPath, bytes: existing };
+    }
+    ensurePrivateDirectory(dirname(path));
+    const temporary = `${path}.tmp-${process.pid}-${randomUUID()}`;
+    writeFileSync(temporary, bytes, { flag: "wx", mode: 0o600 });
+    renameSync(temporary, path);
+    ensurePrivateFile(path);
+    return { userId, request, path, bytes };
+  }
+
+  listPending(userId?: string): PersistedGameResult[] {
+    return this.list("pending", userId);
+  }
+
+  listCompleted(userId?: string): PersistedGameResult[] {
+    return this.list("completed", userId);
+  }
+
+  listFailed(userId?: string): PersistedGameResult[] {
+    return this.list("failed", userId);
+  }
+
+  async listResultKeysBatched(options: {
+    batchSize?: number;
+    yieldControl?: () => Promise<void>;
+    signal?: AbortSignal;
+  } = {}): Promise<string[]> {
+    const batchSize = Math.max(1, options.batchSize ?? 16);
+    const yieldControl = options.yieldControl ?? (() =>
+      new Promise<void>((resolve) => setTimeout(resolve, 0))
+    );
+    const keys = new Set<string>();
+    let processed = 0;
+    for (const state of ["pending", "completed", "failed"] as const) {
+      const base = join(this.root, state);
+      if (options.signal?.aborted) return [...keys];
+      const users = await opendir(base);
+      for await (const user of users) {
+        if (options.signal?.aborted) return [...keys];
+        if (!user.isDirectory()) continue;
+        const directory = join(base, user.name);
+        ensurePrivateDirectory(directory);
+        const files = await opendir(directory);
+        for await (const file of files) {
+          if (options.signal?.aborted) return [...keys];
+          if (!file.isFile() || !file.name.endsWith(".json")) continue;
+          if (processed > 0 && processed % batchSize === 0) {
+            await yieldControl();
+            if (options.signal?.aborted) return [...keys];
+          }
+          ensurePrivateFile(join(directory, file.name));
+          keys.add(`${user.name}\0${file.name.slice(0, -".json".length)}`);
+          processed++;
+        }
+      }
+    }
+    return [...keys];
+  }
+
+  acknowledge(result: PersistedGameResult): string {
+    return this.move(result, "completed");
+  }
+
+  markFailed(result: PersistedGameResult, reason: string): string {
+    const destination = this.move(result, "failed");
+    writeFileSync(`${destination}.error.txt`, `${reason}\n`, { mode: 0o600 });
+    ensurePrivateFile(`${destination}.error.txt`);
+    return destination;
+  }
+
+  private move(result: PersistedGameResult, state: "completed" | "failed"): string {
+    const destination = join(this.root, state, result.userId, basename(result.path));
+    ensurePrivateDirectory(dirname(destination));
+    renameSync(result.path, destination);
+    ensurePrivateFile(destination);
+    return destination;
+  }
+
+  private list(state: "pending" | "completed" | "failed", userId?: string): PersistedGameResult[] {
+    const base = join(this.root, state);
+    const users = userId
+      ? [userId]
+      : readdirSync(base, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name);
+    const results: PersistedGameResult[] = [];
+    for (const owner of users.sort()) {
+      const directory = join(base, owner);
+      if (!existsSync(directory)) continue;
+      ensurePrivateDirectory(directory);
+      for (const name of readdirSync(directory).filter((entry) => entry.endsWith(".json")).sort()) {
+        const path = join(directory, name);
+        ensurePrivateFile(path);
+        const bytes = readFileSync(path, "utf8");
+        results.push({
+          userId: owner,
+          request: JSON.parse(bytes) as GameResultRequest,
+          path,
+          bytes,
+        });
+      }
+    }
+    return results;
+  }
+
+}

package/src/results/transport.ts

@@ -0,0 +1,79 @@
+import { TransportError } from "../recording/transport.js";
+import type {
+  GameResultAcknowledgment,
+  PersistedGameResult,
+} from "./types.js";
+
+type Fetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+export interface ResultTransport {
+  send(result: PersistedGameResult, signal?: AbortSignal): Promise<GameResultAcknowledgment>;
+}
+
+function validAcknowledgment(value: unknown): value is GameResultAcknowledgment {
+  return typeof value === "object" && value !== null &&
+    "accepted" in value && value.accepted === true &&
+    "personal_best" in value && Number.isInteger(value.personal_best) &&
+    "high_score_updated" in value && typeof value.high_score_updated === "boolean";
+}
+
+export class HttpResultTransport implements ResultTransport {
+  constructor(
+    private readonly endpoint: string,
+    private readonly token: string,
+    private readonly request: Fetch = globalThis.fetch,
+    private readonly timeoutMs = 10_000,
+  ) {}
+
+  async send(
+    result: PersistedGameResult,
+    signal?: AbortSignal,
+  ): Promise<GameResultAcknowledgment> {
+    const controller = new AbortController();
+    const abort = () => controller.abort(signal?.reason);
+    if (signal?.aborted) abort();
+    else signal?.addEventListener("abort", abort, { once: true });
+    const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+    timeout.unref?.();
+    try {
+      const response = await this.request(this.endpoint, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.token}`,
+          "Content-Type": "application/json",
+        },
+        body: result.bytes,
+        signal: controller.signal,
+      });
+      if (response.status !== 200 && response.status !== 202) {
+        const retryable = response.status === 408 || response.status === 425 ||
+          response.status === 429 || response.status >= 500;
+        throw new TransportError(
+          `game result returned HTTP ${response.status}: ${await response.text()}`.trim(),
+          retryable,
+        );
+      }
+      let value: unknown;
+      try {
+        value = await response.json();
+      } catch {
+        throw new TransportError("game result returned a malformed acknowledgment", false, false);
+      }
+      if (!validAcknowledgment(value)) {
+        throw new TransportError("game result returned a malformed acknowledgment", false, false);
+      }
+      return value;
+    } catch (error) {
+      if (error instanceof TransportError) throw error;
+      throw new TransportError(
+        error instanceof DOMException && error.name === "AbortError"
+          ? "game result request timed out"
+          : error instanceof Error ? error.message : String(error),
+        true,
+      );
+    } finally {
+      clearTimeout(timeout);
+      signal?.removeEventListener("abort", abort);
+    }
+  }
+}

package/src/results/types.ts

@@ -0,0 +1,20 @@
+export interface GameResultRequest {
+  result_id: string;
+  game_id: string;
+  game_type: string;
+  score: number;
+  completed_at: string;
+}
+
+export interface GameResultAcknowledgment {
+  accepted: true;
+  personal_best: number;
+  high_score_updated: boolean;
+}
+
+export interface PersistedGameResult {
+  userId: string;
+  request: GameResultRequest;
+  path: string;
+  bytes: string;
+}