@digitalpaws/starr 0.0.1

package/tests/trace-history.test.ts

@@ -0,0 +1,356 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import Database from "better-sqlite3";
+import { EventBusImpl } from "../src/events/event-bus.js";
+import { createLogger } from "../src/logging/logger.js";
+import { runMigrations, CORE_MIGRATIONS } from "../src/datastore/migrations.js";
+import { StateStore } from "../src/state/state-store.js";
+import type { EventBus } from "../src/types/plugin.js";
+
+// ── Helpers ──────────────────────────────────────────────────────
+
+function setup() {
+  const db = new Database(":memory:");
+  db.pragma("journal_mode = WAL");
+  db.pragma("foreign_keys = ON");
+  const logger = createLogger("test", "silent");
+  runMigrations(db, CORE_MIGRATIONS, logger);
+
+  const impl = new EventBusImpl(logger);
+  const coreBus: EventBus = impl.coreBus();
+
+  const store = new StateStore(db, coreBus, logger);
+
+  return { db, impl, coreBus, store };
+}
+
+/** Insert a tracked request and move it to "searching" so handlers accept events. */
+function insertRequest(store: StateStore, requestId: string) {
+  store.insert({
+    requestId,
+    contentTypeId: "starr-video/movie@1",
+    contentIdentity: "starr-video/movie@1::tmdb=" + requestId,
+    item: {
+      contentTypeId: "starr-video/movie@1",
+      title: "Test Movie",
+      externalIds: { tmdb: requestId },
+    },
+    ownerUserId: "admin",
+  });
+}
+
+// ── Trace capture ────────────────────────────────────────────────
+
+describe("trace capture", () => {
+  it("captures release.found events", () => {
+    const { coreBus, store } = setup();
+    const reqId = "req-capture-1";
+    insertRequest(store, reqId);
+
+    coreBus.emit("release.found", {
+      requestId: reqId,
+      contentTypeId: "starr-video/movie@1",
+      release: { title: "Dune 1080p", seeders: 42 },
+    });
+
+    const trace = store.getTraceLog(reqId);
+    expect(trace.length).toBe(1);
+    expect(trace[0].eventType).toBe("release.found");
+    expect(trace[0].requestId).toBe(reqId);
+    expect(trace[0].traceId).toBeTruthy(); // host-assigned
+    expect(trace[0].eventData.payload.release.title).toBe("Dune 1080p");
+  });
+
+  it("captures download.started, download.completed, download.failed, and request.failed events", () => {
+    const { coreBus, store } = setup();
+    const reqId = "req-capture-2";
+    insertRequest(store, reqId);
+
+    coreBus.emit("release.found", {
+      requestId: reqId,
+      contentTypeId: "starr-video/movie@1",
+      release: {},
+    });
+    coreBus.emit("download.started", {
+      requestId: reqId,
+      release: { id: "rel-1" },
+    });
+    coreBus.emit("download.completed", {
+      requestId: reqId,
+      release: {},
+    });
+
+    const trace = store.getTraceLog(reqId);
+    const types = trace.map((t) => t.eventType);
+    expect(types).toContain("release.found");
+    expect(types).toContain("download.started");
+    expect(types).toContain("download.completed");
+  });
+
+  it("captures transient download.failed events (retry path)", () => {
+    const { coreBus, store } = setup();
+    const reqId = "req-capture-3";
+    insertRequest(store, reqId);
+
+    coreBus.emit("release.found", {
+      requestId: reqId,
+      contentTypeId: "starr-video/movie@1",
+      release: {},
+    });
+    coreBus.emit("download.started", {
+      requestId: reqId,
+      release: { id: "rel-1" },
+    });
+    coreBus.emit("download.failed", {
+      requestId: reqId,
+      release: {},
+      error: "connection refused",
+    });
+
+    const trace = store.getTraceLog(reqId);
+    const failEntry = trace.find((t) => t.eventType === "download.failed");
+    expect(failEntry).toBeDefined();
+    expect(failEntry!.eventData.payload.error).toBe("connection refused");
+  });
+
+  it("captures request.failed events", () => {
+    const { coreBus, store } = setup();
+    const reqId = "req-capture-4";
+    insertRequest(store, reqId);
+
+    coreBus.emit("release.found", {
+      requestId: reqId,
+      contentTypeId: "starr-video/movie@1",
+      release: {},
+    });
+    coreBus.emit("request.failed", {
+      requestId: reqId,
+      reason: "no acceptable candidates",
+    });
+
+    const trace = store.getTraceLog(reqId);
+    const failEntry = trace.find((t) => t.eventType === "request.failed");
+    expect(failEntry).toBeDefined();
+    expect(failEntry!.eventData.payload.reason).toBe("no acceptable candidates");
+  });
+
+  it("stores envelope fields (traceId, correlationId, source, timestamp)", () => {
+    const { coreBus, store } = setup();
+    const reqId = "req-capture-5";
+    insertRequest(store, reqId);
+
+    coreBus.emit("release.found", {
+      requestId: reqId,
+      contentTypeId: "starr-video/movie@1",
+      release: { title: "Test" },
+    });
+
+    const trace = store.getTraceLog(reqId);
+    expect(trace.length).toBe(1);
+
+    const data = trace[0].eventData;
+    expect(data.traceId).toBeTruthy();
+    expect(typeof data.traceId).toBe("string");
+    expect(data.source).toBeTruthy();
+    expect(typeof data.source).toBe("string");
+    expect(data.timestamp).toBeTruthy();
+    // timestamp is ISO 8601 from the event envelope
+    expect(data.timestamp as string).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+    expect(typeof data.eventId).toBe("string");
+    expect(typeof data.schemaVersion).toBe("number");
+  });
+});
+
+// ── Defensive: unknown requestId ─────────────────────────────────
+
+describe("defensive: unknown requestId", () => {
+  it("does NOT capture events for unknown requestIds", () => {
+    const { coreBus, store } = setup();
+
+    // Emit an event with a requestId that has no tracked request
+    coreBus.emit("release.found", {
+      requestId: "nonexistent",
+      contentTypeId: "starr-video/movie@1",
+      release: {},
+    });
+
+    const trace = store.getTraceLog("nonexistent");
+    expect(trace.length).toBe(0);
+  });
+});
+
+// ── Trace ordering ───────────────────────────────────────────────
+
+describe("trace ordering", () => {
+  it("returns events in insertion order (oldest first)", () => {
+    const { coreBus, store } = setup();
+    const reqId = "req-order";
+    insertRequest(store, reqId);
+
+    // Emit events in a specific order
+    coreBus.emit("release.found", {
+      requestId: reqId,
+      contentTypeId: "starr-video/movie@1",
+      release: { title: "First" },
+    });
+    coreBus.emit("release.found", {
+      requestId: reqId,
+      contentTypeId: "starr-video/movie@1",
+      release: { title: "Second" },
+    });
+    coreBus.emit("release.found", {
+      requestId: reqId,
+      contentTypeId: "starr-video/movie@1",
+      release: { title: "Third" },
+    });
+
+    const trace = store.getTraceLog(reqId);
+    expect(trace.length).toBe(3);
+    expect(trace[0].eventData.payload.release.title).toBe("First");
+    expect(trace[1].eventData.payload.release.title).toBe("Second");
+    expect(trace[2].eventData.payload.release.title).toBe("Third");
+  });
+});
+
+// ── Pruning ──────────────────────────────────────────────────────
+
+describe("pruning (bounded trace)", () => {
+  it("prunes oldest entries when traceId exceeds the limit", () => {
+    const { coreBus, store } = setup();
+    const reqId = "req-prune";
+    insertRequest(store, reqId);
+
+    // The default limit is 50. Emit 55 events for the same requestId
+    // (which also share the same traceId since they're all emitted
+    // outside a handler context — each emit mints a new traceId...
+    // Wait — they are emitted from the test, not from within a handler,
+    // so each emit starts a new chain with a unique traceId.
+    //
+    // To test pruning, we need events that share a traceId. We can
+    // achieve this by emitting from within a handler so the traceId
+    // is inherited (PS2).
+
+    // Subscribe to a custom event and emit all 55 inside its handler
+    // so they share the same traceId.
+    let capturedTraceId: string | null = null;
+
+    coreBus.on("test.batch", (event) => {
+      capturedTraceId = event.traceId;
+      // Emit 55 spine events inside this handler — they all inherit
+      // the handler's traceId (PS2).
+      for (let i = 0; i < 55; i++) {
+        coreBus.emit("release.found", {
+          requestId: reqId,
+          contentTypeId: "starr-video/movie@1",
+          release: { index: i },
+        });
+      }
+    });
+
+    // Emit the trigger event to start the chain
+    coreBus.emit("test.batch", {});
+
+    expect(capturedTraceId).toBeTruthy();
+
+    const trace = store.getTraceLog(reqId);
+    // Should have at most 50 entries (pruned 5)
+    expect(trace.length).toBeLessThanOrEqual(50);
+
+    // The OLDEST 5 entries (index 0-4) should be gone.
+    // The REMAINING entries should be the most recent 50 (indexes 5-54).
+    if (trace.length === 50) {
+      const indices = trace.map(
+        (t) => (t.eventData.payload as { release: { index: number } }).release
+          .index,
+      );
+      // The lowest index should be 5 (entries 0-4 were pruned)
+      expect(Math.min(...indices)).toBe(5);
+      // The highest index should be 54
+      expect(Math.max(...indices)).toBe(54);
+    }
+  });
+});
+
+// ── Trace disabling (TRACE_HISTORY_LIMIT=0) ──────────────────────
+
+describe("trace capture disabled", () => {
+  it("default limit (50) captures events normally", () => {
+    const { coreBus, store } = setup();
+    const reqId = "req-default-limit";
+    insertRequest(store, reqId);
+
+    coreBus.emit("release.found", {
+      requestId: reqId,
+      contentTypeId: "starr-video/movie@1",
+      release: {},
+    });
+
+    const trace = store.getTraceLog(reqId);
+    expect(trace.length).toBe(1);
+  });
+
+  it("manual: STARR_TRACE_HISTORY_LIMIT=0 disables capture", () => {
+    // This test cannot run in-process because TRACE_HISTORY_LIMIT is
+    // computed at module-load time. See the Verification section for
+    // the manual test procedure.
+    expect(true).toBe(true);
+  });
+});
+
+// ── Integration: trace survives across the full lifecycle ────────
+
+describe("integration: full lifecycle trace", () => {
+  it("captures the complete happy-path trace", () => {
+    const { coreBus, store } = setup();
+    const reqId = "req-lifecycle";
+    insertRequest(store, reqId);
+
+    // Full happy path
+    coreBus.emit("release.found", {
+      requestId: reqId,
+      contentTypeId: "starr-video/movie@1",
+      release: { title: "Candidate 1" },
+    });
+    coreBus.emit("release.found", {
+      requestId: reqId,
+      contentTypeId: "starr-video/movie@1",
+      release: { title: "Candidate 2" },
+    });
+    coreBus.emit("download.started", {
+      requestId: reqId,
+      release: { id: "rel-1", title: "Dune 1080p" },
+    });
+    coreBus.emit("download.completed", {
+      requestId: reqId,
+      release: { id: "rel-1" },
+    });
+
+    const trace = store.getTraceLog(reqId);
+    expect(trace.length).toBe(4);
+
+    const types = trace.map((t) => t.eventType);
+    expect(types).toEqual([
+      "release.found",
+      "release.found",
+      "download.started",
+      "download.completed",
+    ]);
+
+    // Verify the data is preserved
+    const startedEvent = trace.find(
+      (t) => t.eventType === "download.started",
+    );
+    expect(startedEvent).toBeDefined();
+    expect(
+      (startedEvent!.eventData.payload as { release: { title: string } })
+        .release.title,
+    ).toBe("Dune 1080p");
+
+    // Verify timestamps are in order (each is ISO 8601)
+    for (let i = 1; i < trace.length; i++) {
+      expect(trace[i].timestamp >= trace[i - 1].timestamp).toBe(true);
+    }
+  });
+});

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*"]
+}

package/tsconfig.json.license

@@ -0,0 +1,2 @@
+SPDX-License-Identifier: 0BSD
+SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>