@trolleroof/tui 0.2.5 → 0.2.6

package/src/recording/contracts.test.ts

@@ -0,0 +1,71 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import type { GameEventChunk, TraceEventChunk } from "./types.js";
+
+function contract(path: string): unknown {
+  return JSON.parse(readFileSync(join(import.meta.dir, "../../contracts", path), "utf8"));
+}
+
+describe("recording wire contracts", () => {
+  it("ships parseable version-one request and acknowledgment schemas", () => {
+    const request = contract("game-event-chunk-v1.schema.json") as {
+      properties: { schema_version: { const: number } };
+      required: string[];
+    };
+    const response = contract("ingest-response-v1.schema.json") as {
+      additionalProperties: boolean;
+      required: string[];
+      properties: Record<string, { const?: unknown }>;
+    };
+    expect(request.properties.schema_version.const).toBe(1);
+    expect(request.required).toContain("events");
+    expect(response.required).toContain("accepted_event_range");
+    expect(response.required).toEqual([
+      "accepted",
+      "duplicate",
+      "game_id",
+      "chunk_id",
+      "chunk_sequence",
+      "accepted_event_range",
+      "queued",
+      "server_received_at_ms",
+    ]);
+    expect(response.properties.queued!.const).toBe(true);
+    expect(response.additionalProperties).toBe(false);
+    expect(Object.keys(response.properties)).not.toContain("broker_partition");
+    expect(Object.keys(response.properties)).not.toContain("broker_offset");
+  });
+
+  it("ships a consistent valid request fixture", () => {
+    const fixture = contract("fixtures/valid/game-event-chunk-v1.json") as GameEventChunk;
+    expect(fixture.schema_version).toBe(1);
+    expect(fixture.event_count).toBe(fixture.events.length);
+    expect(fixture.first_event_sequence).toBe(fixture.events[0]!.event_sequence);
+    expect(fixture.last_event_sequence).toBe(fixture.events.at(-1)!.event_sequence);
+    expect(fixture.events.map((event) => event.event_sequence)).toEqual([1, 2, 3]);
+  });
+
+  it("ships a schema-two trace fixture with universal event identities", () => {
+    const schema = contract("interaction-trace-chunk-v2.schema.json") as {
+      properties: { schema_version: { const: number } };
+      required: string[];
+      $defs: { event: { required: string[] } };
+    };
+    const fixture = contract("fixtures/valid/interaction-trace-chunk-v2.json") as TraceEventChunk;
+    expect(schema.properties.schema_version.const).toBe(2);
+    expect(schema.required).toEqual(expect.arrayContaining(["user_id", "game_id", "chunk_id"]));
+    expect(schema.$defs.event.required).toEqual(
+      expect.arrayContaining(["event_id", "user_id", "game_id", "chunk_id"]),
+    );
+    expect(fixture.schema_version).toBe(2);
+    expect(fixture.client.recording_sdk_version).toBe("2");
+    expect(fixture.event_count).toBe(fixture.events.length);
+    expect(fixture.events.every((event) =>
+      event.user_id === fixture.user_id &&
+      event.game_id === fixture.game_id &&
+      event.chunk_id === fixture.chunk_id &&
+      event.event_id.startsWith("evt_")
+    )).toBe(true);
+  });
+});

package/src/recording/gameplay.test.ts

@@ -0,0 +1,70 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import type { Game, StepResult } from "../core/game.js";
+import { recordGameAction } from "./gameplay.js";
+import { GameplayRecorder } from "./recorder.js";
+import { RecordingStore } from "./store.js";
+
+const roots: string[] = [];
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+class TestGame implements Game<{ value: number }, "advance" | "noop"> {
+  readonly name = "test";
+  readonly actions = ["advance", "noop"] as const;
+  value = 0;
+  reset(): void {
+    this.value = 0;
+  }
+  step(action: "advance" | "noop"): StepResult {
+    if (action === "noop") {
+      return { reward: 0, moved: false, done: false, success: false };
+    }
+    this.value++;
+    return { reward: 1, moved: true, done: false, success: false };
+  }
+  state(): { value: number } {
+    return { value: this.value };
+  }
+  score(): number {
+    return this.value;
+  }
+}
+
+describe("recordGameAction", () => {
+  it("records state before and after both player no-ops and environment actions", () => {
+    const root = mkdtempSync(join(tmpdir(), "gamepigeon-gameplay-"));
+    roots.push(root);
+    const store = new RecordingStore(root);
+    const recorder = new GameplayRecorder({
+      store,
+      gameType: "test",
+      gameVersion: "1",
+      seed: 1,
+      initialState: { value: 0 },
+      createGameId: () => "game_test",
+    });
+    const game = new TestGame();
+
+    expect(recordGameAction(game, recorder, "noop", "player").moved).toBe(false);
+    expect(recordGameAction(game, recorder, "advance", "environment").moved).toBe(true);
+    recorder.flush();
+
+    const actions = store.listPending()[0]!.chunk.events.filter(
+      (event) => event.event_type === "action",
+    );
+    expect(actions.map((event) => [
+      event.source,
+      event.payload.action,
+      event.payload.state_before,
+      event.payload.state_after,
+    ])).toEqual([
+      ["player", "noop", { value: 0 }, { value: 0 }],
+      ["environment", "advance", { value: 0 }, { value: 1 }],
+    ]);
+    recorder.shutdown();
+  });
+});

package/src/recording/gameplay.ts

@@ -0,0 +1,18 @@
+import type { Game, StepResult } from "../core/game.js";
+import type { GameplayRecorder } from "./recorder.js";
+import type { ActionSource } from "./types.js";
+
+export function recordGameAction<State, Action extends string>(
+  game: Game<State, Action>,
+  recorder: GameplayRecorder | null,
+  action: Action,
+  source: ActionSource,
+): StepResult {
+  const stateBefore = game.state();
+  const result = game.step(action);
+  const stateAfter = game.state();
+  recorder?.recordAction({
+    action, source, stateBefore, result, stateAfter,
+  });
+  return result;
+}

package/src/recording/http-transport.test.ts

@@ -0,0 +1,197 @@
+import { describe, expect, it } from "vitest";
+import {
+  DisabledTransport,
+  HttpTransport,
+  TransportError,
+  createChunkTransport,
+} from "./transport.js";
+import type { GameEventChunk, IngestAcknowledgment, PersistedChunk, RecordedEventChunk } from "./types.js";
+
+function persisted(): PersistedChunk {
+  const chunk: GameEventChunk = {
+    schema_version: 1,
+    game_id: "game_test",
+    game_type: "2048",
+    game_version: "1",
+    chunk_id: "chk_test",
+    chunk_sequence: 1,
+    first_event_sequence: 1,
+    last_event_sequence: 1,
+    event_count: 1,
+    created_at_ms: 1,
+    client: {
+      platform: "tui",
+      application_version: "test",
+      recording_sdk_version: "1",
+    },
+    events: [{
+      event_id: "evt_test",
+      event_sequence: 1,
+      event_type: "game_started",
+      event_version: 1,
+      source: "system",
+      client_time_ms: 1,
+      monotonic_time_ms: 0,
+      payload: {
+        game_type: "2048",
+        game_version: "1",
+        seed: 1,
+        initial_state: {},
+      },
+    }],
+  };
+  return {
+    chunk,
+    path: "/pending/chunk.json",
+    bytes: JSON.stringify(chunk),
+  };
+}
+
+function acknowledgment(chunk: RecordedEventChunk): IngestAcknowledgment {
+  return {
+    accepted: true,
+    duplicate: false,
+    game_id: chunk.game_id,
+    chunk_id: chunk.chunk_id,
+    chunk_sequence: chunk.chunk_sequence,
+    accepted_event_range: {
+      first: chunk.first_event_sequence,
+      last: chunk.last_event_sequence,
+    },
+    queued: true,
+    server_received_at_ms: 2,
+  };
+}
+
+describe("HttpTransport", () => {
+  it("posts the exact persisted bytes and returns the acknowledgment", async () => {
+    const value = persisted();
+    let requestUrl = "";
+    let requestInit: RequestInit | undefined;
+    const transport = new HttpTransport(
+      "http://127.0.0.1:8765/v1/game-event-chunks",
+      {
+        apiKey: "test-secret",
+        fetch: async (input, init) => {
+          requestUrl = String(input);
+          requestInit = init;
+          return Response.json(acknowledgment(value.chunk), { status: 202 });
+        },
+      },
+    );
+
+    expect(await transport.send(value)).toEqual(acknowledgment(value.chunk));
+    expect(requestUrl).toBe("http://127.0.0.1:8765/v1/game-event-chunks");
+    expect(requestInit?.method).toBe("POST");
+    expect(requestInit?.body).toBe(value.bytes);
+    expect(requestInit?.headers).toEqual({
+      Authorization: "Bearer test-secret",
+      "Content-Type": "application/json",
+    });
+  });
+
+  it.each([408, 425, 429, 500, 503])("treats HTTP %s as retryable", async (status) => {
+    const transport = new HttpTransport("http://localhost/ingest", {
+      fetch: async () => new Response("unavailable", { status }),
+    });
+    await expect(transport.send(persisted())).rejects.toMatchObject({
+      name: "TransportError",
+      retryable: true,
+    });
+  });
+
+  it.each([400, 401, 409, 413])("treats HTTP %s as permanent", async (status) => {
+    const transport = new HttpTransport("http://localhost/ingest", {
+      fetch: async () => new Response("invalid", { status }),
+    });
+    await expect(transport.send(persisted())).rejects.toMatchObject({
+      name: "TransportError",
+      retryable: false,
+    });
+  });
+
+  it("treats network failures as retryable", async () => {
+    const transport = new HttpTransport("http://localhost/ingest", {
+      fetch: async () => { throw new TypeError("connection refused"); },
+    });
+    await expect(transport.send(persisted())).rejects.toEqual(
+      new TransportError("connection refused", true),
+    );
+  });
+
+  it("keeps malformed successful acknowledgments ambiguous", async () => {
+    const transport = new HttpTransport("http://localhost/ingest", {
+      fetch: async () => Response.json({ accepted: true }, { status: 202 }),
+    });
+    await expect(transport.send(persisted())).rejects.toMatchObject({
+      retryable: false,
+      quarantine: false,
+      message: "ingestion returned a malformed acknowledgment",
+    });
+  });
+
+  it("accepts an acknowledgment without the retired broker fields", async () => {
+    const value = persisted();
+    const ack = acknowledgment(value.chunk);
+    const transport = new HttpTransport("http://localhost/ingest", {
+      fetch: async () => Response.json(ack, { status: 202 }),
+    });
+
+    expect(await transport.send(value)).toEqual(ack);
+    expect(ack).not.toHaveProperty("broker_partition");
+    expect(ack).not.toHaveProperty("broker_offset");
+  });
+
+  it.each([
+    ["omits queued", (ack: IngestAcknowledgment) => {
+      const { queued: _queued, ...rest } = ack;
+      return rest;
+    }],
+    ["reports queued false", (ack: IngestAcknowledgment) => ({ ...ack, queued: false })],
+  ])("rejects an acknowledgment that %s", async (_name, mutate) => {
+    const value = persisted();
+    const transport = new HttpTransport("http://localhost/ingest", {
+      fetch: async () => Response.json(mutate(acknowledgment(value.chunk)), { status: 202 }),
+    });
+
+    await expect(transport.send(value)).rejects.toMatchObject({
+      retryable: false,
+      quarantine: false,
+      message: "ingestion returned a malformed acknowledgment",
+    });
+  });
+});
+
+describe("createChunkTransport", () => {
+  it("stays disabled without an ingestion URL", () => {
+    expect(createChunkTransport({})).toBeInstanceOf(DisabledTransport);
+  });
+
+  it("enables HTTP when the ingestion URL is configured", () => {
+    const transport = createChunkTransport({
+      GAMEPIGEON_INGEST_URL: "http://127.0.0.1:8765/v1/game-event-chunks",
+      GAMEPIGEON_INGEST_API_KEY: "test-secret",
+    });
+    expect(transport).toBeInstanceOf(HttpTransport);
+    expect(transport.enabled).toBe(true);
+  });
+
+  it("targets Cloudflare by default when only the backend token is configured", () => {
+    const transport = createChunkTransport({
+      GAMEPIGEON_BACKEND_TOKEN: "retro_user_token",
+    }) as HttpTransport;
+
+    expect(transport).toBeInstanceOf(HttpTransport);
+    expect((transport as unknown as { endpoint: string }).endpoint)
+      .toBe("https://api.runretroarcade.com/v1/game-event-chunks");
+  });
+
+  it("prefers the backend URL and token", () => {
+    const transport = createChunkTransport({
+      GAMEPIGEON_BACKEND_URL: "https://retro.example",
+      GAMEPIGEON_BACKEND_TOKEN: "retro_user_token",
+    });
+    expect(transport).toBeInstanceOf(HttpTransport);
+    expect(transport.enabled).toBe(true);
+  });
+});

package/src/recording/identity.test.ts

@@ -0,0 +1,26 @@
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { resolveRecordingUserId } from "./identity.js";
+
+const roots: string[] = [];
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+describe("recording user identity", () => {
+  it("persists one pseudonymous user id for offline sessions", () => {
+    const root = mkdtempSync(join(tmpdir(), "gamepigeon-identity-"));
+    roots.push(root);
+    const uuid = () => "00000000-0000-4000-8000-000000000001";
+    const first = resolveRecordingUserId({ root, uuid });
+    const second = resolveRecordingUserId({
+      root,
+      uuid: () => "00000000-0000-4000-8000-000000000002",
+    });
+    expect(first).toBe("usr_00000000-0000-4000-8000-000000000001");
+    expect(second).toBe(first);
+    expect(readFileSync(join(root, "user_id"), "utf8")).toBe(`${first}\n`);
+  });
+});

package/src/recording/identity.ts

@@ -0,0 +1,38 @@
+import { randomUUID } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { createUserId } from "./ids.js";
+
+export interface RecordingIdentityOptions {
+  root?: string;
+  uuid?: () => string;
+}
+
+export function resolveRecordingUserId(
+  options: RecordingIdentityOptions = {},
+): string {
+  const root = options.root ?? join(homedir(), ".tui-gamepigeon");
+  const path = join(root, "user_id");
+  try {
+    if (existsSync(path)) {
+      const existing = readFileSync(path, "utf8").trim();
+      if (/^usr_[A-Za-z0-9._-]+$/.test(existing)) return existing;
+    }
+  } catch {
+    // Regenerate an invalid or unreadable local identity.
+  }
+
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const userId = createUserId(options.uuid ?? randomUUID);
+  const temporary = `${path}.tmp-${process.pid}-${randomUUID()}`;
+  writeFileSync(temporary, `${userId}\n`, { mode: 0o600 });
+  renameSync(temporary, path);
+  return userId;
+}

package/src/recording/ids.ts

@@ -0,0 +1,27 @@
+import { randomUUID } from "node:crypto";
+
+type UuidFactory = () => string;
+
+function createPrefixedId(prefix: string, uuid: UuidFactory): string {
+  return `${prefix}_${uuid()}`;
+}
+
+export function createUserId(uuid: UuidFactory = randomUUID): string {
+  return createPrefixedId("usr", uuid);
+}
+
+export function createGameId(uuid: UuidFactory = randomUUID): string {
+  return createPrefixedId("game", uuid);
+}
+
+export function createEventId(uuid: UuidFactory = randomUUID): string {
+  return createPrefixedId("evt", uuid);
+}
+
+export function createChunkId(uuid: UuidFactory = randomUUID): string {
+  return createPrefixedId("chk", uuid);
+}
+
+export function createObservationId(uuid: UuidFactory = randomUUID): string {
+  return createPrefixedId("obs", uuid);
+}

package/src/recording/permissions.ts

@@ -0,0 +1,10 @@
+import { chmodSync, mkdirSync } from "node:fs";
+
+export function ensurePrivateDirectory(path: string): void {
+  mkdirSync(path, { recursive: true, mode: 0o700 });
+  chmodSync(path, 0o700);
+}
+
+export function ensurePrivateFile(path: string): void {
+  chmodSync(path, 0o600);
+}