@trolleroof/tui 0.2.4 → 0.2.6

package/src/recording/uploader.ts

@@ -0,0 +1,103 @@
+import { RecordingStore } from "./store.js";
+import { TransportError, type ChunkTransport } from "./transport.js";
+import type { IngestAcknowledgment, PersistedChunk } from "./types.js";
+
+export interface UploadResult {
+  acknowledged: number;
+  failed: number;
+  pending: number;
+}
+
+export interface UploaderOptions {
+  maxAttempts?: number;
+  random?: () => number;
+  delay?: (milliseconds: number, signal?: AbortSignal) => Promise<void>;
+}
+
+const sleep = (milliseconds: number, signal?: AbortSignal) => new Promise<void>((resolve) => {
+  if (signal?.aborted) {
+    resolve();
+    return;
+  }
+  const timer = setTimeout(finish, milliseconds);
+  timer.unref?.();
+  signal?.addEventListener("abort", finish, { once: true });
+  function finish() {
+    clearTimeout(timer);
+    signal?.removeEventListener("abort", finish);
+    resolve();
+  }
+});
+
+function matches(chunk: PersistedChunk, ack: IngestAcknowledgment): boolean {
+  return ack.accepted &&
+    ack.game_id === chunk.chunk.game_id &&
+    ack.chunk_id === chunk.chunk.chunk_id &&
+    ack.chunk_sequence === chunk.chunk.chunk_sequence &&
+    ack.accepted_event_range.first === chunk.chunk.first_event_sequence &&
+    ack.accepted_event_range.last === chunk.chunk.last_event_sequence;
+}
+
+export class ChunkUploader {
+  private readonly maxAttempts: number;
+  private readonly delay: (milliseconds: number, signal?: AbortSignal) => Promise<void>;
+  private readonly random: () => number;
+
+  constructor(
+    private readonly store: RecordingStore,
+    private readonly transport: ChunkTransport,
+    options: UploaderOptions = {},
+  ) {
+    this.maxAttempts = options.maxAttempts ?? 5;
+    this.delay = options.delay ?? sleep;
+    this.random = options.random ?? Math.random;
+  }
+
+  async uploadPending(userId?: string, signal?: AbortSignal): Promise<UploadResult> {
+    if (!this.transport.enabled) return { acknowledged: 0, failed: 0, pending: 0 };
+    if (signal?.aborted) return { acknowledged: 0, failed: 0, pending: 0 };
+    const allPending = this.store.listPending();
+    const initial = userId === undefined
+      ? allPending
+      : allPending.filter((item) =>
+        item.chunk.schema_version === 2 && item.chunk.user_id === userId
+      );
+    let acknowledged = 0;
+    let failed = 0;
+    for (const chunk of initial) {
+      if (signal?.aborted) break;
+      const outcome = await this.uploadOne(chunk, signal);
+      if (outcome === "acknowledged") acknowledged++;
+      else if (outcome === "failed") failed++;
+    }
+    return { acknowledged, failed, pending: this.store.listPending().length };
+  }
+
+  private async uploadOne(
+    chunk: PersistedChunk,
+    signal?: AbortSignal,
+  ): Promise<"acknowledged" | "failed" | "pending"> {
+    for (let attempt = 1; attempt <= this.maxAttempts; attempt++) {
+      if (signal?.aborted) return "pending";
+      try {
+        const acknowledgment = await this.transport.send(chunk, signal);
+        if (!matches(chunk, acknowledgment)) return "pending";
+        this.store.acknowledge(chunk);
+        return "acknowledged";
+      } catch (error) {
+        if (signal?.aborted) return "pending";
+        const retryable = error instanceof TransportError && error.retryable;
+        if (!retryable && error instanceof TransportError && error.quarantine) {
+          this.store.markFailed(chunk, error instanceof Error ? error.message : String(error));
+          return "failed";
+        }
+        if (!retryable) return "pending";
+        if (attempt === this.maxAttempts) return "pending";
+        const exponential = 1000 * 2 ** (attempt - 1);
+        const jittered = Math.round(exponential * (0.5 + this.random()));
+        await this.delay(Math.min(jittered, 60_000), signal);
+      }
+    }
+    return "pending";
+  }
+}

package/src/results/completion.ts

@@ -0,0 +1,100 @@
+import { createHash } from "node:crypto";
+import type { RecordingStore } from "../recording/store.js";
+import { isTraceEvent } from "../recording/types.js";
+import type { InteractionTraceRecorder } from "../recording/trace-recorder.js";
+import { ResultStore } from "./store.js";
+import type { GameResultRequest, PersistedGameResult } from "./types.js";
+
+export function resultIdForGame(gameId: string): string {
+  return `res_${createHash("sha256").update(gameId).digest("hex").slice(0, 32)}`;
+}
+
+export function enqueueCompletedResult(input: {
+  store: ResultStore;
+  recorder: InteractionTraceRecorder;
+  score: number;
+  completedAtMs: number;
+}): PersistedGameResult {
+  return input.store.persist(input.recorder.userId, {
+    result_id: resultIdForGame(input.recorder.gameId),
+    game_id: input.recorder.gameId,
+    game_type: input.recorder.gameType,
+    score: input.score,
+    completed_at: new Date(input.completedAtMs).toISOString(),
+  });
+}
+
+export function recoverCompletedResults(
+  recordings: RecordingStore,
+  results: ResultStore,
+): number {
+  const existingResultIds = new Set([
+    ...results.listPending(),
+    ...results.listCompleted(),
+    ...results.listFailed(),
+  ].map((item) => `${item.userId}\0${item.request.result_id}`));
+  let recovered = 0;
+  for (const game of recordings.listCompletedGames()) {
+    recovered += recoverCompletedGame(game, results, existingResultIds);
+  }
+  return recovered;
+}
+
+export interface BatchedRecoveryOptions {
+  batchSize?: number;
+  yieldControl?: () => Promise<void>;
+  signal?: AbortSignal;
+}
+
+export async function recoverCompletedResultsBatched(
+  recordings: RecordingStore,
+  results: ResultStore,
+  options: BatchedRecoveryOptions = {},
+): Promise<number> {
+  const batchSize = Math.max(1, options.batchSize ?? 16);
+  const yieldControl = options.yieldControl ?? (() =>
+    new Promise<void>((resolve) => setTimeout(resolve, 0))
+  );
+  const existingResultIds = new Set(await results.listResultKeysBatched({
+    batchSize,
+    yieldControl,
+    signal: options.signal,
+  }));
+  if (options.signal?.aborted) return 0;
+  let recovered = 0;
+  for await (const game of recordings.iterateCompletedGamesBatched({
+    batchSize,
+    yieldControl,
+    signal: options.signal,
+  })) {
+    if (options.signal?.aborted) break;
+    recovered += recoverCompletedGame(game, results, existingResultIds);
+  }
+  return recovered;
+}
+
+function recoverCompletedGame(
+  game: ReturnType<RecordingStore["readCompletedGame"]>,
+  results: ResultStore,
+  existingResultIds: Set<string>,
+): number {
+  const events = game.events.filter(isTraceEvent);
+  const started = events.find((event) => event.event_type === "episode_started");
+  const ended = [...events].reverse().find((event) => event.event_type === "episode_ended");
+  if (!started || !ended || ended.event_type !== "episode_ended" || !ended.payload.completed) {
+    return 0;
+  }
+  const request: GameResultRequest = {
+    result_id: resultIdForGame(game.gameId),
+    game_id: game.gameId,
+    game_type: started.payload.game_type,
+    score: ended.payload.final_score,
+    completed_at: new Date(ended.client_time_ms).toISOString(),
+  };
+  const resultKey = `${started.user_id}\0${request.result_id}`;
+  const existed = existingResultIds.has(resultKey);
+  results.persist(started.user_id, request);
+  if (existed) return 0;
+  existingResultIds.add(resultKey);
+  return 1;
+}

package/src/results/http-result-transport.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from "vitest";
+import type { PersistedGameResult } from "./types.js";
+import { HttpResultTransport } from "./transport.js";
+
+const persisted: PersistedGameResult = {
+  userId: "usr_test",
+  path: "/pending/result.json",
+  request: {
+    result_id: "res_test",
+    game_id: "game_test",
+    game_type: "2048",
+    score: 1024,
+    completed_at: "2026-07-17T12:00:00.000Z",
+  },
+  bytes: '{"result_id":"res_test","game_id":"game_test","game_type":"2048","score":1024,"completed_at":"2026-07-17T12:00:00.000Z"}',
+};
+
+describe("HttpResultTransport", () => {
+  it.each([200, 202])("accepts HTTP %s and posts the exact outbox bytes", async (status) => {
+    let body: BodyInit | null | undefined;
+    let headers: HeadersInit | undefined;
+    const transport = new HttpResultTransport(
+      "https://retro.example/v1/game-results",
+      "retro_user_token",
+      async (_input, init) => {
+        body = init?.body;
+        headers = init?.headers;
+        return Response.json({
+          accepted: true,
+          personal_best: 1024,
+          high_score_updated: true,
+        }, { status });
+      },
+    );
+    await expect(transport.send(persisted)).resolves.toMatchObject({ accepted: true });
+    expect(body).toBe(persisted.bytes);
+    expect(headers).toEqual({
+      Authorization: "Bearer retro_user_token",
+      "Content-Type": "application/json",
+    });
+  });
+
+  it.each([408, 425, 429, 500, 503])("treats HTTP %s as retryable", async (status) => {
+    const transport = new HttpResultTransport(
+      "https://retro.example/v1/game-results",
+      "retro_token",
+      async () => new Response("later", { status }),
+    );
+    await expect(transport.send(persisted)).rejects.toMatchObject({ retryable: true });
+  });
+
+  it.each([400, 401, 403, 409, 413])("quarantines permanent HTTP %s failures", async (status) => {
+    const transport = new HttpResultTransport(
+      "https://retro.example/v1/game-results",
+      "retro_token",
+      async () => new Response("invalid", { status }),
+    );
+    await expect(transport.send(persisted)).rejects.toMatchObject({
+      retryable: false,
+      quarantine: true,
+    });
+  });
+
+  it("keeps malformed successful responses ambiguous", async () => {
+    const transport = new HttpResultTransport(
+      "https://retro.example/v1/game-results",
+      "retro_token",
+      async () => Response.json({ accepted: false }),
+    );
+    await expect(transport.send(persisted)).rejects.toMatchObject({
+      retryable: false,
+      quarantine: false,
+    });
+  });
+});

package/src/results/local-score.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { localScoreForCompletion } from "./local-score.js";
+
+const completion = {
+  gameId: "game_test",
+  gameType: "2048",
+  variationId: "classic",
+  score: 512,
+  success: false,
+  endedAtMs: 2_000,
+  startedAtMs: 500,
+  platform: "overlay" as const,
+};
+
+describe("local score completion", () => {
+  it("builds the existing completed-result fields for a natural completion", () => {
+    expect(localScoreForCompletion({ ...completion, outcome: "completed" })).toEqual({
+      game_id: "game_test",
+      game_type: "2048",
+      variation_id: "classic",
+      score: 512,
+      success: false,
+      completed_at: "1970-01-01T00:00:02.000Z",
+      duration_ms: 1_500,
+      platform: "overlay",
+    });
+  });
+
+  it("does not create a score for quit, restart, or shutdown paths", () => {
+    expect(localScoreForCompletion({ ...completion, outcome: "abandoned" })).toBeNull();
+  });
+});

package/src/results/local-score.ts

@@ -0,0 +1,39 @@
+import type { GameResultRequest } from "./types.js";
+
+export interface LocalScoreInput
+  extends Pick<GameResultRequest, "game_id" | "game_type" | "score" | "completed_at"> {
+  variation_id: string;
+  success: boolean;
+  duration_ms: number;
+  platform: "terminal" | "overlay";
+}
+
+export interface LocalScoreEntry extends LocalScoreInput {
+  schema_version: 1;
+  personal_best: number;
+  high_score_updated: boolean;
+}
+
+export function localScoreForCompletion(input: {
+  outcome: "completed" | "abandoned";
+  gameId: string;
+  gameType: string;
+  variationId: string;
+  score: number;
+  success: boolean;
+  endedAtMs: number;
+  startedAtMs: number;
+  platform: LocalScoreInput["platform"];
+}): LocalScoreInput | null {
+  if (input.outcome !== "completed") return null;
+  return {
+    game_id: input.gameId,
+    game_type: input.gameType,
+    variation_id: input.variationId,
+    score: input.score,
+    success: input.success,
+    completed_at: new Date(input.endedAtMs).toISOString(),
+    duration_ms: Math.max(0, input.endedAtMs - input.startedAtMs),
+    platform: input.platform,
+  };
+}