@digitalpaws/starr 0.0.1

package/src/state/state-store.ts

@@ -0,0 +1,621 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import type Database from "better-sqlite3";
+import type { ContentItemBase } from "@digitalpaws/starr-types-core";
+import type { EventBus, Logger, StarrEvent } from "../types/plugin.js";
+import { env } from "node:process";
+
+// ── Types ──────────────────────────────────────────────────
+
+/** Union of the v1 status values (§4). */
+export type RequestStatus =
+  | "requested"
+  | "searching"
+  | "downloading"
+  | "downloaded"
+  | "importing"
+  | "imported"
+  | "failed";
+
+/** The domain record as stored and returned to callers. */
+export interface TrackedRequest {
+  requestId: string;
+  contentTypeId: string;
+  contentIdentity: string;
+  item: ContentItemBase;
+  ownerUserId: string;
+  watchers: string[];
+  status: RequestStatus;
+  statusDetail?: string;
+  chosenReleaseId?: string;
+  attempts: number;
+  libraryId?: string;
+  libraryName?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** Minimal data needed to insert a new tracked request. */
+export interface TrackedRequestData {
+  requestId: string;
+  contentTypeId: string;
+  contentIdentity: string;
+  item: ContentItemBase;
+  ownerUserId: string;
+  libraryId?: string;
+}
+
+/** A single captured spine event stored in the trace log. */
+export interface TraceEntry {
+  id: number;
+  traceId: string;
+  requestId: string;
+  eventType: string;
+  /** JSON-serialized event envelope (envelope fields + payload). */
+  eventData: Record<string, unknown>;
+  timestamp: string;
+}
+
+// ── Row mapping helper ─────────────────────────────────────
+
+function rowToRequest(row: Record<string, unknown>): TrackedRequest {
+  return {
+    requestId: row.request_id as string,
+    contentTypeId: row.content_type_id as string,
+    contentIdentity: row.content_identity as string,
+    item: JSON.parse(row.item as string) as ContentItemBase,
+    ownerUserId: row.owner_user_id as string,
+    watchers: JSON.parse(row.watchers as string) as string[],
+    status: row.status as RequestStatus,
+    statusDetail: (row.status_detail as string) || undefined,
+    chosenReleaseId: (row.chosen_release_id as string) || undefined,
+    attempts: row.attempts as number,
+    libraryId: (row.library_id as string) || undefined,
+    createdAt: row.created_at as string,
+    updatedAt: row.updated_at as string,
+  };
+}
+
+/**
+ * Maximum number of trace entries retained per traceId.
+ * Set via STARR_TRACE_HISTORY_LIMIT env var; defaults to 50.
+ * Values ≤ 0 disable trace capture entirely.
+ */
+const TRACE_HISTORY_LIMIT = (() => {
+  const raw = env.STARR_TRACE_HISTORY_LIMIT;
+  if (raw === undefined || raw === "") return 50;
+  const n = Number(raw);
+  if (Number.isNaN(n)) {
+    // We don't have a logger at module scope — the state store
+    // constructor will log a warning if the env var is invalid.
+    return 50;
+  }
+  return Math.max(0, Math.floor(n));
+})();
+
+// ── StateStore class ───────────────────────────────────────
+
+export class StateStore {
+  private db: Database.Database;
+  private bus: EventBus;
+  private logger: Logger;
+
+  // Prepared statements — created once in constructor
+  private stmtGetByRequestId: Database.Statement;
+  private stmtFindByIdentity: Database.Statement;
+  private stmtInsert: Database.Statement;
+  private stmtUpdateStatus: Database.Statement;
+  private stmtIncrementAttempts: Database.Statement;
+  private stmtAddWatcher: Database.Statement;
+  private stmtListByUser: Database.Statement;
+  private stmtInsertTrace: Database.Statement;
+  private stmtGetIdsByTraceId: Database.Statement;
+  private stmtGetTraceByRequestId: Database.Statement;
+  private stmtResetAttempts: Database.Statement;
+  private stmtResetForRetry: Database.Statement;
+  private stmtDeleteRequest: Database.Statement;
+  private stmtDeleteTraceByRequestId: Database.Statement;
+
+  constructor(
+    db: Database.Database,
+    bus: EventBus,
+    logger: Logger,
+  ) {
+    this.db = db;
+    this.bus = bus;
+    this.logger = logger.child("state-store");
+
+    // Compile prepared statements once
+    this.stmtGetByRequestId = db.prepare(
+      "SELECT * FROM tracked_requests WHERE request_id = @requestId",
+    );
+    this.stmtFindByIdentity = db.prepare(
+      `SELECT * FROM tracked_requests
+       WHERE content_identity = @identity AND status != 'failed'
+       ORDER BY created_at DESC
+       LIMIT 1`,
+    );
+    this.stmtInsert = db.prepare(
+      `INSERT INTO tracked_requests
+         (request_id, content_type_id, content_identity, item,
+          owner_user_id, watchers, status, attempts, library_id, created_at, updated_at)
+       VALUES
+         (@requestId, @contentTypeId, @contentIdentity, @item,
+          @ownerUserId, '[]', 'requested', 0,
+          @libraryId,
+          datetime('now'), datetime('now'))`,
+    );
+    this.stmtUpdateStatus = db.prepare(
+      `UPDATE tracked_requests
+       SET status = @status,
+           status_detail = @detail,
+           chosen_release_id = COALESCE(@chosenReleaseId, chosen_release_id),
+           updated_at = datetime('now')
+       WHERE request_id = @requestId`,
+    );
+    this.stmtIncrementAttempts = db.prepare(
+      `UPDATE tracked_requests
+       SET attempts = attempts + 1, updated_at = datetime('now')
+       WHERE request_id = @requestId`,
+    );
+    this.stmtAddWatcher = db.prepare(
+      `UPDATE tracked_requests
+       SET watchers = @watchers, updated_at = datetime('now')
+       WHERE request_id = @requestId`,
+    );
+    this.stmtListByUser = db.prepare(
+      `SELECT * FROM tracked_requests
+       WHERE owner_user_id = @userId
+          OR watchers LIKE @pattern
+       ORDER BY created_at DESC`,
+    );
+
+    // Trace log — prepared statements
+    this.stmtInsertTrace = db.prepare(
+      `INSERT INTO trace_log (trace_id, request_id, event_type, event_data, timestamp)
+       VALUES (@traceId, @requestId, @eventType, @eventData, @timestamp)`,
+    );
+    this.stmtGetIdsByTraceId = db.prepare(
+      `SELECT id FROM trace_log
+       WHERE trace_id = @traceId
+       ORDER BY id ASC`,
+    );
+    this.stmtGetTraceByRequestId = db.prepare(
+      `SELECT * FROM trace_log
+       WHERE request_id = @requestId
+       ORDER BY id ASC`,
+    );
+    this.stmtResetAttempts = db.prepare(
+      `UPDATE tracked_requests
+       SET attempts = 0, updated_at = datetime('now')
+       WHERE request_id = @requestId`,
+    );
+
+    this.stmtResetForRetry = db.prepare(
+      `UPDATE tracked_requests
+       SET status = 'requested',
+           status_detail = @detail,
+           chosen_release_id = NULL,
+           attempts = 0,
+           updated_at = datetime('now')
+       WHERE request_id = @requestId`,
+    );
+
+    this.stmtDeleteRequest = db.prepare(
+      `DELETE FROM tracked_requests WHERE request_id = @requestId`,
+    );
+    this.stmtDeleteTraceByRequestId = db.prepare(
+      `DELETE FROM trace_log WHERE request_id = @requestId`,
+    );
+
+    // Subscribe to acquisition spine events
+    this.subscribe();
+  }
+
+  // ── Public API ───────────────────────────────────────────
+
+  /** Retrieve a single tracked request by its domain id. */
+  getByRequestId(requestId: string): TrackedRequest | undefined {
+    const row = this.stmtGetByRequestId.get({ requestId }) as
+      | Record<string, unknown>
+      | undefined;
+    return row ? rowToRequest(row) : undefined;
+  }
+
+  /**
+   * Find a non-failed tracked request with the given content identity.
+   * Used by request intake for de-duplication (DU1).
+   * Returns the most recently created match, or undefined.
+   */
+  findByContentIdentity(contentIdentity: string): TrackedRequest | undefined {
+    const row = this.stmtFindByIdentity.get({ identity: contentIdentity }) as
+      | Record<string, unknown>
+      | undefined;
+    return row ? rowToRequest(row) : undefined;
+  }
+
+  /**
+   * Insert a brand-new tracked request with status ``requested``.
+   * Called by request intake after de-dup check (DU3).
+   */
+  insert(data: TrackedRequestData): void {
+    this.stmtInsert.run({
+      requestId: data.requestId,
+      contentTypeId: data.contentTypeId,
+      contentIdentity: data.contentIdentity,
+      item: JSON.stringify(data.item),
+      ownerUserId: data.ownerUserId,
+      libraryId: data.libraryId ?? null,
+    });
+    this.logger.debug("tracked request created", {
+      requestId: data.requestId,
+      contentIdentity: data.contentIdentity,
+      libraryId: data.libraryId,
+    });
+  }
+
+  /**
+   * Add a userId to the watchers array of an existing request.
+   * Called by request intake when re-attaching to an existing request (DU2).
+   * No-op if the user is already the owner or a watcher.
+   */
+  addWatcher(requestId: string, userId: string): void {
+    const req = this.getByRequestId(requestId);
+    if (!req) {
+      this.logger.warn("addWatcher: unknown requestId", { requestId });
+      return;
+    }
+    if (req.ownerUserId === userId || req.watchers.includes(userId)) {
+      return; // already attached
+    }
+    const updated = [...req.watchers, userId];
+    this.stmtAddWatcher.run({
+      requestId,
+      watchers: JSON.stringify(updated),
+    });
+    this.logger.debug("watcher added", { requestId, userId });
+  }
+
+  /**
+   * Return the ordered trace history for a tracked request.
+   *
+   * Returns an array of TraceEntry, oldest first. Returns an empty array
+   * if the requestId is unknown or has no captured events.
+   *
+   * This is the data surface for the admin "activity" view (DBG2).
+   * The UI (Task 022) renders the returned data; this task only provides
+   * the query.
+   */
+  getTraceLog(requestId: string): TraceEntry[] {
+    const rows = this.stmtGetTraceByRequestId.all({ requestId }) as Array<
+      Record<string, unknown>
+    >;
+    return rows.map((row) => ({
+      id: row.id as number,
+      traceId: row.trace_id as string,
+      requestId: row.request_id as string,
+      eventType: row.event_type as string,
+      eventData: JSON.parse(row.event_data as string) as Record<string, unknown>,
+      timestamp: row.timestamp as string,
+    }));
+  }
+
+  // ── Retry ───────────────────────────────────────────────
+
+  /**
+   * Reset a tracked request to 'requested' for a manual retry.
+   *
+   * Clears chosenReleaseId, resets attempts to 0, sets status to
+   * 'requested' with a detail message. This is called from the
+   * retry endpoint before re-emitting content.requested.
+   *
+   * Uses a transaction for atomicity.
+   * Emits item.updated so the UI reflects the change immediately.
+   */
+  resetAndRetry(requestId: string): void {
+    const txn = this.db.transaction(() => {
+      // Reset status, clear chosenReleaseId, reset attempts in one statement
+      this.stmtResetForRetry.run({
+        requestId,
+        detail: "Retrying — restarted by user",
+      });
+    });
+    txn();
+
+    // Emit item.updated so the UI updates live
+    this.bus.emit("item.updated", {
+      requestId,
+      status: "requested",
+      detail: "Retrying — restarted by user",
+    });
+
+    this.logger.info("request reset for retry", { requestId });
+  }
+
+  // ── Delete ──────────────────────────────────────────────
+
+  /**
+   * Permanently delete a tracked request and its associated
+   * trace-log entries. This is unconditional (any status).
+   *
+   * Returns true if a row was deleted, false if the requestId
+   * did not exist.
+   */
+  deleteRequest(requestId: string): boolean {
+    const txn = this.db.transaction(() => {
+      // 1. Delete trace log entries for this request
+      this.stmtDeleteTraceByRequestId.run({ requestId });
+
+      // 2. Delete the request itself
+      const info = this.stmtDeleteRequest.run({ requestId });
+      return info.changes > 0;
+    });
+
+    const deleted = txn();
+
+    if (deleted) {
+      this.logger.info("request deleted", { requestId });
+    } else {
+      this.logger.warn("deleteRequest: requestId not found", { requestId });
+    }
+
+    // Note: we deliberately do NOT emit item.updated here.
+    // Deletion is handled on the UI side by removing the item from
+    // the local store and/or navigating away.
+
+    return deleted;
+  }
+
+  /**
+   * Return ALL tracked requests (admin only).
+   */
+  getLibraryPath(requestId: string): string | undefined {
+    const row = this.db
+      .prepare("SELECT library_path FROM library_paths WHERE request_id = ?")
+      .get(requestId) as { library_path: string } | undefined;
+    return row?.library_path;
+  }
+
+  getAllRequests(): TrackedRequest[] {
+    const rows = this.db
+      .prepare("SELECT * FROM tracked_requests ORDER BY created_at DESC")
+      .all() as any[];
+    return rows.map((row: any) => rowToRequest(row));
+  }
+
+  /**
+   * List tracked requests visible to a given user (owner or watcher).
+   * Used by the UI to show the request list (UI-ST2).
+   */
+  listByUser(userId: string): TrackedRequest[] {
+    // The LIKE pattern searches for the userId inside the JSON watchers array.
+    // e.g. '%"admin"%' matches ["admin"] or ["alice","admin"].
+    const rows = this.stmtListByUser.all({
+      userId,
+      pattern: `%"${userId}"%`,
+    }) as Array<Record<string, unknown>>;
+    return rows.map(rowToRequest);
+  }
+
+  // ── Trace capture ────────────────────────────────────────
+
+  /**
+   * Capture a spine event into the trace log. Stores the full event data
+   * (envelope fields + payload) as JSON, then prunes if the per-traceId
+   * count exceeds TRACE_HISTORY_LIMIT.
+   *
+   * This is a no-op if TRACE_HISTORY_LIMIT is 0 (trace capture disabled).
+   */
+  private captureTraceEvent(event: StarrEvent, requestId: string): void {
+    if (TRACE_HISTORY_LIMIT === 0) return;
+
+    const eventData = {
+      eventId: event.id,
+      traceId: event.traceId,
+      correlationId: event.correlationId,
+      source: event.source,
+      schemaVersion: event.schemaVersion,
+      timestamp: event.timestamp,
+      payload: event.payload,
+    };
+
+    // 1. Insert the new entry
+    this.stmtInsertTrace.run({
+      traceId: event.traceId,
+      requestId,
+      eventType: event.type,
+      eventData: JSON.stringify(eventData),
+      timestamp: event.timestamp,
+    });
+
+    // 2. Fetch all entry ids for this traceId, oldest first
+    const rows = this.stmtGetIdsByTraceId.all({
+      traceId: event.traceId,
+    }) as Array<{ id: number }>;
+
+    // 3. Prune if over the limit — delete the oldest excess entries
+    if (rows.length > TRACE_HISTORY_LIMIT) {
+      const excess = rows.length - TRACE_HISTORY_LIMIT;
+      const deleteIds = rows.slice(0, excess).map((r) => r.id);
+
+      // Use a one-off prepared statement for deletes
+      const deleteStmt = this.db.prepare("DELETE FROM trace_log WHERE id = ?");
+      for (const id of deleteIds) {
+        deleteStmt.run(id);
+      }
+
+      this.logger.debug("trace pruned", {
+        traceId: event.traceId,
+        deleted: excess,
+        remaining: TRACE_HISTORY_LIMIT,
+      });
+    }
+  }
+
+  // ── Event subscription ───────────────────────────────────
+
+  private subscribe(): void {
+    this.bus.on("release.found", this.onReleaseFound.bind(this));
+    this.bus.on("download.started", this.onDownloadStarted.bind(this));
+    this.bus.on("download.completed", this.onDownloadCompleted.bind(this));
+    this.bus.on("download.failed", this.onDownloadFailed.bind(this));
+    this.bus.on("request.failed", this.onRequestFailed.bind(this));
+    this.bus.on("import.started", this.onImportStarted.bind(this));
+    this.bus.on("import.completed", this.onImportCompleted.bind(this));
+    this.bus.on("import.failed", this.onImportFailed.bind(this));
+  }
+
+  private onReleaseFound(event: StarrEvent): void {
+    const { requestId } = event.payload as { requestId: string };
+    const req = this.getByRequestId(requestId);
+    if (!req) {
+      this.logger.warn("release.found for unknown requestId", { requestId });
+      return;
+    }
+    this.captureTraceEvent(event, requestId);
+    // Transition: requested → searching (first candidate arrived)
+    if (req.status === "requested") {
+      this.updateStatus(requestId, "searching");
+    }
+    // If already searching (or beyond), just more candidates — no status change.
+  }
+
+  private onDownloadStarted(event: StarrEvent): void {
+    const payload = event.payload as {
+      requestId: string;
+      release?: { id?: string; title?: string };
+    };
+    const req = this.getByRequestId(payload.requestId);
+    if (!req) {
+      this.logger.warn("download.started for unknown requestId", {
+        requestId: payload.requestId,
+      });
+      return;
+    }
+    this.captureTraceEvent(event, payload.requestId);
+
+    // Increment the display-only attempts counter (SM4)
+    this.incrementAttempts(payload.requestId);
+
+    // Transition: searching → downloading (defensive: also from 'requested')
+    if (req.status === "searching" || req.status === "requested") {
+      const releaseId = payload.release?.id ?? payload.release?.title ?? undefined;
+      this.updateStatus(payload.requestId, "downloading", undefined, releaseId);
+    }
+  }
+
+  private onDownloadCompleted(event: StarrEvent): void {
+    const { requestId } = event.payload as { requestId: string };
+    const req = this.getByRequestId(requestId);
+    if (!req) {
+      this.logger.warn("download.completed for unknown requestId", { requestId });
+      return;
+    }
+    this.captureTraceEvent(event, requestId);
+    // Terminal success — only if not already terminal
+    if (req.status !== "failed" && req.status !== "downloaded" && req.status !== "imported") {
+      this.updateStatus(requestId, "downloaded");
+    }
+  }
+
+  private onDownloadFailed(event: StarrEvent): void {
+    const { requestId } = event.payload as { requestId: string };
+    const req = this.getByRequestId(requestId);
+    if (!req) {
+      this.logger.warn("download.failed for unknown requestId", { requestId });
+      return;
+    }
+    this.captureTraceEvent(event, requestId);
+    // Transient failure: go back to searching, NEVER to failed (SM1)
+    if (req.status === "downloading") {
+      this.updateStatus(
+        requestId,
+        "searching",
+        `retrying (attempt ${req.attempts})`,
+      );
+    }
+  }
+
+  private onImportStarted(event: StarrEvent): void {
+    const { requestId } = event.payload as { requestId: string };
+    const req = this.getByRequestId(requestId);
+    if (!req) return;
+    if (req.status === "downloaded") {
+      this.updateStatus(requestId, "importing");
+    }
+  }
+
+  private onImportCompleted(event: StarrEvent): void {
+    const { requestId } = event.payload as { requestId: string };
+    const req = this.getByRequestId(requestId);
+    if (!req) return;
+    if (req.status === "importing") {
+      this.updateStatus(requestId, "imported");
+    }
+  }
+
+  private onImportFailed(event: StarrEvent): void {
+    const payload = event.payload as { requestId: string; error?: string };
+    const req = this.getByRequestId(payload.requestId);
+    if (!req) return;
+    if (req.status === "importing") {
+      this.updateStatus(payload.requestId, "downloaded",
+        `Import failed: ${payload.error ?? "unknown error"}`);
+    }
+  }
+
+  private onRequestFailed(event: StarrEvent): void {
+    const payload = event.payload as { requestId: string; reason?: string };
+    const req = this.getByRequestId(payload.requestId);
+    if (!req) {
+      this.logger.warn("request.failed for unknown requestId", {
+        requestId: payload.requestId,
+      });
+      return;
+    }
+    this.captureTraceEvent(event, payload.requestId);
+    // Terminal failure — the ONLY path to 'failed' (SM2, SP1a)
+    if (req.status !== "failed" && req.status !== "downloaded" && req.status !== "imported") {
+      this.updateStatus(payload.requestId, "failed", payload.reason);
+    }
+  }
+
+  // ── Internal helpers ──────────────────────────────────────
+
+  /**
+   * Update status, optional detail, and optional chosenReleaseId.
+   * Emits item.updated on every call (the caller guards transitions,
+   * so duplicate emissions are not a concern).
+   */
+  private updateStatus(
+    requestId: string,
+    status: RequestStatus,
+    detail?: string,
+    chosenReleaseId?: string,
+  ): void {
+    this.stmtUpdateStatus.run({
+      requestId,
+      status,
+      detail: detail ?? null,
+      chosenReleaseId: chosenReleaseId ?? null,
+    });
+
+    // Emit item.updated — the single event the UI relies on (SP2, UI-ST1)
+    const payload: { requestId: string; status: string; detail?: string } = {
+      requestId,
+      status,
+    };
+    if (detail !== undefined) {
+      payload.detail = detail;
+    }
+    this.bus.emit("item.updated", payload);
+
+    this.logger.debug("status updated", { requestId, status, detail });
+  }
+
+  /** Increment the attempts counter by 1. Called on download.started (SM4). */
+  private incrementAttempts(requestId: string): void {
+    this.stmtIncrementAttempts.run({ requestId });
+  }
+}

package/src/state/trace-store.ts

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import type { TraceEntry, StateStore } from "./state-store.js";
+
+/**
+ * Module-level reference to the state store, set by the host bootstrap.
+ * This avoids circular imports between route modules and the host.
+ */
+let stateStore: StateStore | null = null;
+
+/**
+ * Initialize the trace-store wrapper with a reference to the StateStore.
+ * Called from main.ts after the web server and state store are created.
+ */
+export function initTraceStore(store: StateStore): void {
+  stateStore = store;
+}
+
+/**
+ * Retrieve trace events for a given requestId.
+ * Returns an empty array if the state store isn't available or no events exist.
+ */
+export function getTraceEvents(requestId: string): TraceEntry[] {
+  if (!stateStore) return [];
+  return stateStore.getTraceLog(requestId);
+}