@iislee/opencodex 2.11.0 → 2.31.0

package/src/integrations/store.ts

@@ -0,0 +1,103 @@
+/**
+ * One store, bound once.
+ *
+ * Passing a directory per call was not enough: retention would honor it while
+ * records, the journal and snapshots still resolved the global root, so an
+ * operation that believed itself isolated could read and mutate the developer's
+ * real store. Every method here derives from one `root`, and `io()` binds the
+ * bookkeeping seams to that same store so the two can never point at different
+ * roots.
+ *
+ * Design of record: devlog/_fin/260802_client_toggle_api/006 §Config-dir seam.
+ */
+import {
+  appendOperation,
+  captureSnapshot,
+  clearPruneFailure,
+  countSnapshots,
+  findOperation,
+  listOperations,
+  markPruneFailure,
+  pruneSnapshots,
+  readMaintenance,
+  readSnapshot,
+  type JournalEntry,
+  type MaintenanceState,
+  type SnapshotRef,
+} from "./journal";
+import { fileIO, type IntegrationIO } from "./config-io";
+import {
+  deleteRecord,
+  integrationsDir,
+  readRecords,
+  writeRecord,
+  type OwnershipRecord,
+} from "./ownership";
+import type { IntegrationClientId } from "./registry";
+
+export interface IntegrationStateStore {
+  /** The integrations directory itself — never a config root to resolve again. */
+  readonly root: string;
+  readRecords(): Partial<Record<IntegrationClientId, OwnershipRecord>>;
+  putRecord(record: OwnershipRecord): void;
+  dropRecord(clientId: IntegrationClientId): void;
+  appendJournal(entry: JournalEntry): void;
+  listOperations(clientId?: IntegrationClientId, limit?: number): JournalEntry[];
+  findOperation(opId: string): JournalEntry | null;
+  captureSnapshot(clientId: IntegrationClientId, opId: string, text: string | null): SnapshotRef;
+  readSnapshot(entry: JournalEntry):
+    | { kind: "none" }
+    | { kind: "stored"; text: string; path: string }
+    | { kind: "expired" };
+  countSnapshots(clientId: IntegrationClientId): number | null;
+  pruneSnapshots(clientId: IntegrationClientId): { ok: true } | { ok: false; error: string };
+  readMaintenance(): MaintenanceState;
+  markPruneFailure(clientId: IntegrationClientId, error: string): void;
+  clearPruneFailure(clientId: IntegrationClientId): void;
+  retryPendingPrunes(): void;
+  /** Filesystem seam with bookkeeping bound to THIS store. */
+  io(): IntegrationIO;
+}
+
+/**
+ * Bind every integration state path to ONE root.
+ *
+ * Ownership-manifest note: writes go through `atomicWriteFile`, which records
+ * the target in the opencodex uninstall manifest. That registration is scoped
+ * by `manifestRelativePath` and refuses any path outside the process config
+ * dir, so a store rooted in a temp dir — the shape every test uses — touches
+ * no global state. A store rooted UNDER the real config dir does register its
+ * files there, which is correct: those files genuinely are opencodex-owned and
+ * should be removed on uninstall.
+ */
+export function createIntegrationStateStore(root: string = integrationsDir()): IntegrationStateStore {
+  const dir = root;
+  const store: IntegrationStateStore = {
+    root: dir,
+    readRecords: () => readRecords(dir),
+    putRecord: record => writeRecord(record, dir),
+    dropRecord: clientId => deleteRecord(clientId, dir),
+    appendJournal: entry => appendOperation(entry, dir),
+    listOperations: (clientId, limit) => listOperations(clientId, limit, dir),
+    findOperation: opId => findOperation(opId, dir),
+    captureSnapshot: (clientId, opId, text) => captureSnapshot(clientId, opId, text, dir),
+    readSnapshot: entry => readSnapshot(entry, dir),
+    countSnapshots: clientId => countSnapshots(clientId, dir),
+    pruneSnapshots: clientId => pruneSnapshots(clientId, dir),
+    readMaintenance: () => readMaintenance(dir),
+    markPruneFailure: (clientId, error) => markPruneFailure(clientId, error, dir),
+    clearPruneFailure: clientId => clearPruneFailure(clientId, dir),
+    retryPendingPrunes: () => {
+      for (const clientId of Object.keys(store.readMaintenance().pruneFailures) as IntegrationClientId[]) {
+        if (store.pruneSnapshots(clientId).ok) store.clearPruneFailure(clientId);
+      }
+    },
+    io: () => ({
+      ...fileIO(),
+      appendJournal: entry => store.appendJournal(entry),
+      putRecord: record => store.putRecord(record),
+      dropRecord: clientId => store.dropRecord(clientId),
+    }),
+  };
+  return store;
+}

package/src/integrations/writer-lock.ts

@@ -0,0 +1,98 @@
+import { rm, writeFile } from "node:fs/promises";
+
+const LOCK_DEADLINE_MS = 2_000;
+const LOCK_DELAYS_MS = [20, 40, 80, 160, 200] as const;
+
+export interface IntegrationWriterLockSeams {
+  writeFile: (
+    path: string,
+    payload: string,
+    options: { flag: "wx"; mode: 0o600 },
+  ) => Promise<void>;
+  removeFile: (path: string) => Promise<void>;
+  now: () => number;
+  delay: (milliseconds: number) => Promise<void>;
+  pid: number;
+}
+
+export class IntegrationWriterLockBusyError extends Error {
+  constructor(readonly lockPath: string) {
+    super("integration_mutation_busy");
+    this.name = "IntegrationWriterLockBusyError";
+  }
+}
+
+export class IntegrationWriterLockIOError extends Error {
+  constructor(readonly lockPath: string, readonly operation: "acquire" | "release", cause: unknown) {
+    // The management route returns Error.message to its caller. Keep the
+    // private config path and OS diagnostic on typed fields/cause, not the wire.
+    super(`integration writer lock ${operation} failed`, { cause });
+    this.name = "IntegrationWriterLockIOError";
+  }
+}
+
+const defaultSeams: IntegrationWriterLockSeams = {
+  writeFile: async (path, payload, options) => { await writeFile(path, payload, options); },
+  // Match DSH rc.6: an already-absent lock is a successful release.
+  removeFile: async path => { await rm(path, { force: true }); },
+  now: () => Date.now(),
+  delay: milliseconds => new Promise(resolve => setTimeout(resolve, milliseconds)),
+  pid: process.pid,
+};
+
+function errorCode(error: unknown): string | undefined {
+  return typeof error === "object" && error !== null && "code" in error
+    ? String((error as { code?: unknown }).code)
+    : undefined;
+}
+
+/**
+ * Hold the exact sibling `<settings>.lock` around one complete transaction.
+ * A contender is never deleted: release runs only after our exclusive create
+ * succeeded.
+ */
+export async function withIntegrationWriterLock<T>(
+  configPath: string,
+  operation: () => Promise<T>,
+  seams: IntegrationWriterLockSeams = defaultSeams,
+  suffix: ".lock" = ".lock",
+): Promise<T> {
+  const lockPath = `${configPath}${suffix}`;
+  const startedAt = seams.now();
+  let delayIndex = 0;
+  for (;;) {
+    try {
+      await seams.writeFile(lockPath, `${seams.pid}\n`, { flag: "wx", mode: 0o600 });
+      break;
+    } catch (error) {
+      if (errorCode(error) !== "EEXIST") {
+        throw new IntegrationWriterLockIOError(lockPath, "acquire", error);
+      }
+      const elapsedMs = seams.now() - startedAt;
+      if (elapsedMs >= LOCK_DEADLINE_MS) {
+        throw new IntegrationWriterLockBusyError(lockPath);
+      }
+      const backoffMs = LOCK_DELAYS_MS[Math.min(delayIndex, LOCK_DELAYS_MS.length - 1)]!;
+      // Keep the final retry inside the advertised two-second deadline.
+      const delayMs = Math.min(backoffMs, LOCK_DEADLINE_MS - elapsedMs);
+      delayIndex += 1;
+      await seams.delay(delayMs);
+    }
+  }
+
+  let outcome: { ok: true; value: T } | { ok: false; error: unknown };
+  try {
+    outcome = { ok: true, value: await operation() };
+  } catch (error) {
+    outcome = { ok: false, error };
+  }
+  try {
+    await seams.removeFile(lockPath);
+  } catch (error) {
+    // Cleanup cannot replace the protected operation's actual failure.
+    if (!outcome.ok) throw outcome.error;
+    throw new IntegrationWriterLockIOError(lockPath, "release", error);
+  }
+  if (!outcome.ok) throw outcome.error;
+  return outcome.value;
+}