@trolleroof/tui 0.2.4 → 0.2.6

package/src/recording/transport.ts

@@ -0,0 +1,170 @@
+import type { IngestAcknowledgment, PersistedChunk } from "./types.js";
+import { resolveBackendConfig } from "../sync/config.js";
+
+type Fetch = (
+  input: string | URL | Request,
+  init?: RequestInit,
+) => Promise<Response>;
+
+export interface ChunkTransport {
+  readonly enabled: boolean;
+  send(chunk: PersistedChunk, signal?: AbortSignal): Promise<IngestAcknowledgment>;
+}
+
+export class TransportError extends Error {
+  constructor(
+    message: string,
+    readonly retryable: boolean,
+    readonly quarantine = !retryable,
+  ) {
+    super(message);
+    this.name = "TransportError";
+  }
+}
+
+export class DisabledTransport implements ChunkTransport {
+  readonly enabled = false;
+
+  async send(): Promise<IngestAcknowledgment> {
+    throw new TransportError("gameplay ingestion is not configured", true);
+  }
+}
+
+export interface HttpTransportOptions {
+  token?: string;
+  /** @deprecated Use token. */
+  apiKey?: string;
+  fetch?: Fetch;
+  timeoutMs?: number;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isAcknowledgment(value: unknown): value is IngestAcknowledgment {
+  if (!isObject(value) || !isObject(value.accepted_event_range)) return false;
+  return typeof value.accepted === "boolean" &&
+    typeof value.duplicate === "boolean" &&
+    typeof value.game_id === "string" &&
+    typeof value.chunk_id === "string" &&
+    Number.isInteger(value.chunk_sequence) &&
+    Number.isInteger(value.accepted_event_range.first) &&
+    Number.isInteger(value.accepted_event_range.last) &&
+    value.queued === true &&
+    typeof value.server_received_at_ms === "number" &&
+    Number.isInteger(value.server_received_at_ms) &&
+    value.server_received_at_ms >= 0;
+}
+
+function responseError(status: number, body: string): TransportError {
+  const retryable = status === 408 ||
+    status === 425 ||
+    status === 429 ||
+    (status >= 500 && status <= 599);
+  const detail = body.trim();
+  return new TransportError(
+    `ingestion returned HTTP ${status}${detail ? `: ${detail}` : ""}`,
+    retryable,
+  );
+}
+
+export class HttpTransport implements ChunkTransport {
+  readonly enabled = true;
+  private readonly endpoint: string;
+  private readonly apiKey: string | undefined;
+  private readonly request: Fetch;
+  private readonly timeoutMs: number;
+
+  constructor(endpoint: string, options: HttpTransportOptions = {}) {
+    const parsed = new URL(endpoint);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      throw new Error("GAMEPIGEON_INGEST_URL must use HTTP or HTTPS");
+    }
+    this.endpoint = parsed.toString();
+    this.apiKey = options.token?.trim() || options.apiKey?.trim() || undefined;
+    this.request = options.fetch ?? globalThis.fetch;
+    this.timeoutMs = options.timeoutMs ?? 10_000;
+  }
+
+  async send(persisted: PersistedChunk, signal?: AbortSignal): Promise<IngestAcknowledgment> {
+    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: {
+          ...(this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {}),
+          "Content-Type": "application/json",
+        },
+        body: persisted.bytes,
+        signal: controller.signal,
+      });
+      if (response.status !== 202) {
+        throw responseError(response.status, await response.text());
+      }
+      let value: unknown;
+      try {
+        value = await response.json();
+      } catch {
+        throw new TransportError(
+          "ingestion returned a malformed acknowledgment",
+          false,
+          false,
+        );
+      }
+      if (!isAcknowledgment(value)) {
+        throw new TransportError(
+          "ingestion returned a malformed acknowledgment",
+          false,
+          false,
+        );
+      }
+      return value;
+    } catch (error) {
+      if (error instanceof TransportError) throw error;
+      const message = error instanceof Error ? error.message : String(error);
+      throw new TransportError(
+        error instanceof DOMException && error.name === "AbortError"
+          ? "ingestion request timed out"
+          : message,
+        true,
+      );
+    } finally {
+      clearTimeout(timeout);
+      signal?.removeEventListener("abort", abort);
+    }
+  }
+}
+
+export function createChunkTransport(
+  environment: Record<string, string | undefined> = process.env,
+): ChunkTransport {
+  const config = resolveBackendConfig(environment);
+  return config
+    ? new HttpTransport(config.eventChunksUrl, {
+      token: config.token,
+    })
+    : new DisabledTransport();
+}
+
+export class FakeTransport implements ChunkTransport {
+  readonly enabled = true;
+  readonly requests: PersistedChunk[] = [];
+
+  constructor(
+    private readonly handler: (
+      chunk: PersistedChunk,
+      signal?: AbortSignal,
+    ) => Promise<IngestAcknowledgment>,
+  ) {}
+
+  async send(chunk: PersistedChunk, signal?: AbortSignal): Promise<IngestAcknowledgment> {
+    this.requests.push(chunk);
+    return this.handler(chunk, signal);
+  }
+}

package/src/recording/types.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+import { createChunkId, createEventId, createGameId, createUserId } from "./ids.js";
+import { RECORDING_SCHEMA_VERSION, RECORDING_SDK_VERSION } from "./types.js";
+
+describe("recording contracts", () => {
+  it("uses schema version two", () => {
+    expect(RECORDING_SCHEMA_VERSION).toBe(2);
+    expect(RECORDING_SDK_VERSION).toBe("2");
+  });
+
+  it("creates prefixed stable identifiers", () => {
+    const uuid = () => "00000000-0000-4000-8000-000000000001";
+    expect(createUserId(uuid)).toBe("usr_00000000-0000-4000-8000-000000000001");
+    expect(createGameId(uuid)).toBe("game_00000000-0000-4000-8000-000000000001");
+    expect(createEventId(uuid)).toBe("evt_00000000-0000-4000-8000-000000000001");
+    expect(createChunkId(uuid)).toBe("chk_00000000-0000-4000-8000-000000000001");
+  });
+});

package/src/recording/types.ts

@@ -0,0 +1,326 @@
+import type { StepResult } from "../core/game.js";
+
+export const RECORDING_SCHEMA_VERSION = 2 as const;
+export const RECORDING_SDK_VERSION = "2";
+
+export type TerminalColor = number | string | null;
+
+export interface TerminalCell {
+  glyph: string;
+  foreground: TerminalColor;
+  background: TerminalColor;
+  attributes: number;
+  width: number;
+}
+
+export interface PositionedTerminalCell extends TerminalCell {
+  x: number;
+  y: number;
+}
+
+export interface TerminalCellChange {
+  x: number;
+  y: number;
+  cell: TerminalCell | null;
+}
+
+export interface ObservationCaptureTiming {
+  generated_time_us: number;
+  delivered_time_us: number;
+  dropped_observations: number;
+}
+
+export interface FullTerminalObservation {
+  observation_id: string;
+  representation: "terminal_grid_v1";
+  width: number;
+  height: number;
+  state_hash: string;
+  cells: PositionedTerminalCell[];
+  capture_timing?: ObservationCaptureTiming;
+  caused_by_event_id?: string;
+}
+
+export interface DeltaTerminalObservation {
+  observation_id: string;
+  representation: "terminal_grid_delta_v1";
+  base_observation_id: string;
+  width: number;
+  height: number;
+  state_hash: string;
+  changed_cells: TerminalCellChange[];
+  capture_timing?: ObservationCaptureTiming;
+  caused_by_event_id?: string;
+}
+
+export type TerminalObservation = FullTerminalObservation | DeltaTerminalObservation;
+
+export interface EngineStateObservation {
+  observation_id: string;
+  representation: "engine_state_v1";
+  state: unknown;
+  caused_by_event_id?: string;
+}
+
+export type PolicyObservation = TerminalObservation | EngineStateObservation;
+
+export type TraceVisibility = "policy" | "privileged";
+export type TraceActor = "human" | "model" | "heuristic" | "random" | "environment";
+export type EpisodeEndReason =
+  | "game_over"
+  | "won"
+  | "lost"
+  | "user_quit"
+  | "restart"
+  | "timeout"
+  | "client_closed"
+  | "engine_error";
+
+interface TraceEventBase {
+  schema_version: typeof RECORDING_SCHEMA_VERSION;
+  user_id: string;
+  game_id: string;
+  chunk_id: string;
+  event_id: string;
+  event_sequence: number;
+  event_version: 1;
+  event_type: string;
+  visibility: TraceVisibility;
+  client_time_ms: number;
+  monotonic_time_us: number;
+  simulation_tick?: number;
+  payload: unknown;
+}
+
+export interface EpisodeStartedTraceEvent extends TraceEventBase {
+  event_type: "episode_started";
+  visibility: "policy";
+  payload: {
+    game_type: string;
+    game_version: string;
+    ruleset_id: string;
+    telemetry_version: 2;
+    platform: "tui" | "overlay";
+    viewport: { width: number; height: number };
+    control_schema: string[];
+    input_semantics: "terminal_impulse" | "engine_impulse";
+  };
+}
+
+export interface ObservationTraceEvent extends TraceEventBase {
+  event_type: "observation";
+  visibility: "policy";
+  payload: PolicyObservation;
+}
+
+export interface ControlChangedTraceEvent extends TraceEventBase {
+  event_type: "control_changed";
+  visibility: "policy";
+  payload: {
+    based_on_observation_id: string | null;
+    control: string;
+    action: string;
+    kind: "impulse";
+    actor: TraceActor;
+    action_received_us?: number;
+  };
+}
+
+export interface ControlCheckpointTraceEvent extends TraceEventBase {
+  event_type: "control_checkpoint";
+  visibility: "policy";
+  payload: {
+    held_controls: string[];
+    input_semantics: "terminal_impulse" | "engine_impulse";
+  };
+}
+
+export interface OutcomeChangedTraceEvent extends TraceEventBase {
+  event_type: "outcome_changed";
+  visibility: "policy";
+  payload: {
+    score_before: number;
+    score_after: number;
+    score_delta: number;
+    engine_reward: number;
+    reward_spec_id: "engine_v1";
+    terminal: boolean;
+    caused_by_event_id: string;
+    progress?: Record<string, number | string | boolean | null>;
+    performance?: {
+      action_received_us: number;
+      action_applied_us: number;
+      action_completed_us: number;
+      queueing_delay_us: number;
+      simulation_tick_duration_us: number;
+    };
+  };
+}
+
+export type CheckpointReason =
+  | "episode_start"
+  | "periodic"
+  | "random_outcome"
+  | "terminal"
+  | "episode_end";
+
+export interface EngineCheckpointTraceEvent extends TraceEventBase {
+  event_type: "engine_checkpoint";
+  visibility: "privileged";
+  payload: {
+    state_version: 1;
+    reason: CheckpointReason;
+    state: unknown;
+    state_hash?: string;
+    seed?: number;
+    random_effects?: unknown;
+    caused_by_event_id?: string;
+  };
+}
+
+export interface EpisodeEndedTraceEvent extends TraceEventBase {
+  event_type: "episode_ended";
+  visibility: "policy";
+  payload: {
+    reason: EpisodeEndReason;
+    final_event_sequence: number;
+    final_score: number;
+    duration_us: number;
+    completed: boolean;
+  };
+}
+
+export type TraceEvent =
+  | EpisodeStartedTraceEvent
+  | ObservationTraceEvent
+  | ControlChangedTraceEvent
+  | ControlCheckpointTraceEvent
+  | OutcomeChangedTraceEvent
+  | EngineCheckpointTraceEvent
+  | EpisodeEndedTraceEvent;
+
+export interface TraceEventChunk {
+  schema_version: typeof RECORDING_SCHEMA_VERSION;
+  user_id: string;
+  game_id: string;
+  game_type: string;
+  game_version: string;
+  chunk_id: string;
+  chunk_sequence: number;
+  first_event_sequence: number;
+  last_event_sequence: number;
+  event_count: number;
+  created_at_ms: number;
+  client: {
+    platform: "tui";
+    application_version: string;
+    recording_sdk_version: string;
+  };
+  events: TraceEvent[];
+}
+
+export type EventSource = "player" | "environment" | "system";
+export type ActionSource = Exclude<EventSource, "system">;
+export type GameOutcome = "completed" | "abandoned";
+
+interface EventBase {
+  event_id: string;
+  event_sequence: number;
+  event_version: 1;
+  source: EventSource;
+  client_time_ms: number;
+  monotonic_time_ms: number;
+}
+
+export interface GameStartedEvent extends EventBase {
+  event_type: "game_started";
+  source: "system";
+  payload: {
+    game_type: string;
+    game_version: string;
+    seed: number;
+    initial_state: unknown;
+  };
+}
+
+export interface ActionEvent extends EventBase {
+  event_type: "action";
+  source: "player" | "environment";
+  payload: {
+    action: string;
+    state_before: unknown;
+    result: Omit<StepResult, "randomEffects">;
+    state_after: unknown;
+    random_effects?: unknown;
+  };
+}
+
+export interface GameEndedEvent extends EventBase {
+  event_type: "game_ended";
+  source: "system";
+  payload: {
+    outcome: GameOutcome;
+    final_state: unknown;
+    final_score: number;
+    success: boolean;
+    final_event_sequence: number;
+  };
+}
+
+export type GameEvent = GameStartedEvent | ActionEvent | GameEndedEvent;
+
+export interface GameEventChunk {
+  schema_version: 1;
+  game_id: string;
+  game_type: string;
+  game_version: string;
+  chunk_id: string;
+  chunk_sequence: number;
+  first_event_sequence: number;
+  last_event_sequence: number;
+  event_count: number;
+  created_at_ms: number;
+  client: {
+    platform: "tui";
+    application_version: string;
+    recording_sdk_version: string;
+  };
+  events: GameEvent[];
+}
+
+export type RecordedEvent = GameEvent | TraceEvent;
+export type RecordedEventChunk = GameEventChunk | TraceEventChunk;
+
+export function isTraceEvent(event: RecordedEvent): event is TraceEvent {
+  return "schema_version" in event && event.schema_version === 2;
+}
+
+export function isGameEvent(event: RecordedEvent): event is GameEvent {
+  return !("schema_version" in event);
+}
+
+export function isTraceEventChunk(chunk: RecordedEventChunk): chunk is TraceEventChunk {
+  return chunk.schema_version === 2;
+}
+
+export interface PersistedChunk {
+  chunk: RecordedEventChunk;
+  path: string;
+  bytes: string;
+}
+
+export interface IngestAcknowledgment {
+  accepted: boolean;
+  duplicate: boolean;
+  game_id: string;
+  chunk_id: string;
+  chunk_sequence: number;
+  accepted_event_range: { first: number; last: number };
+  queued: true;
+  server_received_at_ms: number;
+}
+
+export interface RecordingHealth {
+  status: "healthy" | "degraded";
+  last_error?: string;
+}

package/src/recording/uploader.test.ts

@@ -0,0 +1,193 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { RecordingStore } from "./store.js";
+import { DisabledTransport, FakeTransport, TransportError } from "./transport.js";
+import { ChunkUploader } from "./uploader.js";
+import type { GameEventChunk, IngestAcknowledgment } from "./types.js";
+
+const roots: string[] = [];
+afterEach(() => {
+  vi.useRealTimers();
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+function setup(): { store: RecordingStore; chunk: GameEventChunk } {
+  const root = mkdtempSync(join(tmpdir(), "gamepigeon-upload-"));
+  roots.push(root);
+  const store = new RecordingStore(root);
+  const chunk: GameEventChunk = {
+    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: 1,
+    event_count: 1,
+    created_at_ms: 1,
+    client: { platform: "tui", application_version: "dev", recording_sdk_version: "1" },
+    events: [{
+      event_id: "evt_1",
+      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: {} },
+    }],
+  };
+  store.persistChunk(chunk);
+  return { store, chunk };
+}
+
+function ack(chunk: GameEventChunk): 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("ChunkUploader", () => {
+  it("returns before scanning pending files when transport is disabled", async () => {
+    const { store } = setup();
+    store.listPending = () => { throw new Error("pending backlog was scanned"); };
+    await expect(new ChunkUploader(store, new DisabledTransport()).uploadPending())
+      .resolves.toEqual({ acknowledged: 0, failed: 0, pending: 0 });
+  });
+
+  it("leaves pending chunks untouched when transport is disabled", async () => {
+    const { store } = setup();
+    const result = await new ChunkUploader(store, new DisabledTransport()).uploadPending();
+    expect(result).toEqual({ acknowledged: 0, failed: 0, pending: 0 });
+    expect(store.listPending()).toHaveLength(1);
+  });
+
+  it("moves a chunk only after a matching acknowledgment", async () => {
+    const { store, chunk } = setup();
+    const transport = new FakeTransport(async () => ack(chunk));
+    const result = await new ChunkUploader(store, transport).uploadPending();
+    expect(result.acknowledged).toBe(1);
+    expect(store.listPending()).toHaveLength(0);
+    expect(transport.requests[0]?.bytes).toBe(JSON.stringify(chunk));
+  });
+
+  it("retains a chunk when acknowledgment does not match", async () => {
+    const { store, chunk } = setup();
+    const transport = new FakeTransport(async () => ({ ...ack(chunk), chunk_id: "chk_wrong" }));
+    const result = await new ChunkUploader(store, transport).uploadPending();
+    expect(result.failed).toBe(0);
+    expect(store.listPending()).toHaveLength(1);
+  });
+
+  it("retains a chunk after an ambiguous malformed 202 response", async () => {
+    const { store } = setup();
+    const transport = new FakeTransport(async () => {
+      throw new TransportError("malformed acknowledgment", false, false);
+    });
+    const result = await new ChunkUploader(store, transport).uploadPending();
+    expect(result).toEqual({ acknowledged: 0, failed: 0, pending: 1 });
+    expect(store.listFailed()).toHaveLength(0);
+  });
+
+  it("retries retryable failures with backoff", async () => {
+    const { store, chunk } = setup();
+    let attempts = 0;
+    const delays: number[] = [];
+    const transport = new FakeTransport(async () => {
+      attempts++;
+      if (attempts < 3) throw new TransportError("offline", true);
+      return ack(chunk);
+    });
+    const uploader = new ChunkUploader(store, transport, {
+      maxAttempts: 3,
+      delay: async (ms) => { delays.push(ms); },
+      random: () => 0.5,
+    });
+    expect((await uploader.uploadPending()).acknowledged).toBe(1);
+    expect(delays).toEqual([1000, 2000]);
+  });
+
+  it("adds jitter and caps retry delays at one minute", async () => {
+    const { store } = setup();
+    const delays: number[] = [];
+    const transport = new FakeTransport(async () => {
+      throw new TransportError("offline", true);
+    });
+    const uploader = new ChunkUploader(store, transport, {
+      maxAttempts: 8,
+      delay: async (ms) => { delays.push(ms); },
+      random: () => 0.5,
+    });
+    expect((await uploader.uploadPending()).pending).toBe(1);
+    expect(delays).toEqual([
+      1_000, 2_000, 4_000, 8_000, 16_000, 32_000, 60_000,
+    ]);
+  });
+
+  it("cancels retry waits and leaves persisted chunks pending", async () => {
+    const { store } = setup();
+    const controller = new AbortController();
+    let waiting = false;
+    const transport = new FakeTransport(async () => {
+      throw new TransportError("offline", true);
+    });
+    const uploader = new ChunkUploader(store, transport, {
+      maxAttempts: 5,
+      delay: async (_ms, signal) => {
+        waiting = true;
+        await new Promise<void>((resolve) => signal?.addEventListener("abort", () => resolve()));
+      },
+    });
+
+    const pending = uploader.uploadPending(undefined, controller.signal);
+    while (!waiting) await Promise.resolve();
+    expect(waiting).toBe(true);
+    controller.abort();
+    await pending;
+    expect(transport.requests).toHaveLength(1);
+    expect(store.listPending()).toHaveLength(1);
+  });
+
+  it("clears the default retry timer when cancellation is requested", async () => {
+    vi.useFakeTimers();
+    const { store } = setup();
+    const controller = new AbortController();
+    let requests = 0;
+    const uploader = new ChunkUploader(store, new FakeTransport(async () => {
+      requests++;
+      throw new TransportError("offline", true);
+    }));
+
+    const pending = uploader.uploadPending(undefined, controller.signal);
+    for (let index = 0; index < 20 && vi.getTimerCount() === 0; index++) {
+      await Promise.resolve();
+    }
+    expect(requests).toBe(1);
+    expect(vi.getTimerCount()).toBe(1);
+    controller.abort();
+    await pending;
+    expect(vi.getTimerCount()).toBe(0);
+    expect(store.listPending()).toHaveLength(1);
+  });
+
+  it("quarantines permanent failures", async () => {
+    const { store } = setup();
+    const transport = new FakeTransport(async () => {
+      throw new TransportError("invalid schema", false);
+    });
+    const result = await new ChunkUploader(store, transport).uploadPending();
+    expect(result.failed).toBe(1);
+    expect(store.listPending()).toHaveLength(0);
+    expect(store.listFailed()).toHaveLength(1);
+  });
+});