routstrd 0.4.0 → 0.4.1

package/src/daemon/wallet/cleanup.ts

@@ -0,0 +1,104 @@
+/**
+ * Pure selection helpers for the wallet cleanup command.
+ *
+ * These helpers decide *which* stuck operations are safe to clear. The actual
+ * state transitions are applied by the in-process coco wallet client so that
+ * coco-core's operation services emit their normal events and release proof
+ * reservations. Keeping the selection logic here makes it easy to unit test
+ * without a wallet database or network access.
+ */
+
+export interface MintCleanupCandidate {
+  id: string;
+  state: string;
+  /** Quote expiry in epoch seconds. `0` means unknown/not applicable. */
+  expiry: number;
+  /** Last update time in epoch milliseconds. */
+  updatedAt: number;
+  /**
+   * Last quote state observed from the mint (e.g. "PAID", "ISSUED").
+   * Unknown/undefined means no terminal observation has been recorded.
+   */
+  lastObservedRemoteState?: string;
+}
+
+export interface NonMintCleanupCandidate {
+  id: string;
+  state: string;
+  /** Last update time in epoch milliseconds. */
+  updatedAt: number;
+}
+
+export interface CleanupSelectionOptions<
+  TMint extends MintCleanupCandidate,
+  TSend extends NonMintCleanupCandidate,
+  TMelt extends NonMintCleanupCandidate,
+> {
+  mints: TMint[];
+  sends: TSend[];
+  melts: TMelt[];
+  nowMs: number;
+  minAgeMs: number;
+}
+
+export interface CleanupSelection<
+  TMint extends MintCleanupCandidate,
+  TSend extends NonMintCleanupCandidate,
+  TMelt extends NonMintCleanupCandidate,
+> {
+  mintsToFail: TMint[];
+  sendsToReclaim: TSend[];
+  meltsToCancel: TMelt[];
+}
+
+/**
+ * Select stuck operations that are old enough to be considered for clearing.
+ *
+ * - Pending mint quotes are candidates once their bolt11 quote has expired
+ *   (an expired Lightning invoice can never be paid again) and the mint has
+ *   not already reported it as PAID/ISSUED. A paid-but-unfinalized quote
+ *   still has claimable proofs, so it must go through normal recovery instead
+ *   of being failed locally.
+ *
+ *   Note that expiry alone does not prove a quote was never paid: the payment
+ *   can have happened before expiry while the daemon was down, leaving no
+ *   local observation. Callers that fail quotes automatically at startup must
+ *   therefore confirm UNPAID with the mint first (see
+ *   settleExpiredMintQuotes in coco-client.ts); only the explicit,
+ *   user-invoked cleanup command may fail candidates purely locally.
+ * - Pending sends are reclaimed (rolled back) only when they are older than
+ *   `minAgeMs`, so we never roll back a token that a receiver might still
+ *   legitimately claim.
+ * - Prepared melts are cancelled under the same age guard.
+ */
+export function selectCleanupOperations<
+  TMint extends MintCleanupCandidate,
+  TSend extends NonMintCleanupCandidate,
+  TMelt extends NonMintCleanupCandidate,
+>(
+  options: CleanupSelectionOptions<TMint, TSend, TMelt>,
+): CleanupSelection<TMint, TSend, TMelt> {
+  const { mints, sends, melts, nowMs, minAgeMs } = options;
+
+  // Expired quotes can never be paid again, but may have been paid before
+  // expiry without a local observation: this is a candidate set, and whether
+  // failing is safe without a mint round-trip depends on the caller (above).
+  const mintsToFail = mints.filter(
+    (op) =>
+      op.state === "pending" &&
+      op.expiry > 0 &&
+      op.expiry * 1000 <= nowMs &&
+      op.lastObservedRemoteState !== "PAID" &&
+      op.lastObservedRemoteState !== "ISSUED",
+  );
+
+  const sendsToReclaim = sends.filter(
+    (op) => op.state === "pending" && nowMs - op.updatedAt >= minAgeMs,
+  );
+
+  const meltsToCancel = melts.filter(
+    (op) => op.state === "prepared" && nowMs - op.updatedAt >= minAgeMs,
+  );
+
+  return { mintsToFail, sendsToReclaim, meltsToCancel };
+}

package/src/daemon/wallet/coco-client.test.ts

@@ -14,7 +14,10 @@ import {
   assertLegacyCocodNotRunning,
   claimLegacyCocodPidFile,
   createCocoClient,
+  isZombieProcess,
+  settleExpiredMintQuotes,
   stopLegacyCocod,
+  type ExpiredMintQuoteSource,
 } from "./coco-client";
 
 type GuardOptions = NonNullable<
@@ -42,6 +45,19 @@ function socketOnly(path: string): boolean {
   return path === SOCKET_PATH;
 }
 
+async function waitForWalletUnlocked(
+  client: Awaited<ReturnType<typeof createCocoClient>>,
+): Promise<void> {
+  const deadline = Date.now() + 30_000;
+  while (Date.now() < deadline) {
+    const status = await client.getStatus();
+    if (status === "UNLOCKED") return;
+    if (status === "ERROR") throw new Error("Wallet recovery failed");
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+  throw new Error("Timed out waiting for wallet recovery to complete");
+}
+
 describe("default mint functionality", () => {
   it("automatically adds default mint when no mints exist", async () => {
     const walletDir = join(makeTempDir(), "wallet");
@@ -192,7 +208,7 @@ describe("legacy cocod wallet migration", () => {
       enableNpc: false,
     });
     try {
-      expect(await client.getStatus()).toBe("UNLOCKED");
+      await waitForWalletUnlocked(client);
       expect(await client.getBalances()).toEqual({ [mintUrl]: 10 });
     } finally {
       await client.dispose?.();
@@ -214,13 +230,29 @@ describe("legacy cocod wallet migration", () => {
   });
 });
 
+describe("isZombieProcess", () => {
+  it("recognizes Linux proc stat zombie state", () => {
+    expect(
+      isZombieProcess(4242, () => "4242 (routstrd worker) Z 1 4242 4242"),
+    ).toBe(true);
+  });
+
+  it("does not mistake a running process or unreadable proc entry for a zombie", () => {
+    expect(isZombieProcess(4242, () => "4242 (bun) S 1 4242 4242")).toBe(false);
+    expect(
+      isZombieProcess(4242, () => {
+        throw Object.assign(new Error("missing"), { code: "ENOENT" });
+      }),
+    ).toBe(false);
+  });
+});
+
 describe("assertLegacyCocodNotRunning", () => {
-  it("does not probe when the legacy socket and PID file do not exist", async () => {
+  it("does not probe when the legacy socket does not exist", async () => {
     const fetchImpl = mock<LegacyFetch>(async () => new Response("pong"));
 
     await assertLegacyCocodNotRunning({
       socketPath: SOCKET_PATH,
-      pidFilePath: PID_FILE_PATH,
       pathExists: () => false,
       fetchImpl,
     });
@@ -236,7 +268,6 @@ describe("assertLegacyCocodNotRunning", () => {
     await expect(
       assertLegacyCocodNotRunning({
         socketPath: SOCKET_PATH,
-        pidFilePath: PID_FILE_PATH,
         pathExists: socketOnly,
         fetchImpl,
       }),
@@ -257,7 +288,6 @@ describe("assertLegacyCocodNotRunning", () => {
       await expect(
         assertLegacyCocodNotRunning({
           socketPath: SOCKET_PATH,
-          pidFilePath: PID_FILE_PATH,
           pathExists: socketOnly,
           fetchImpl,
         }),
@@ -277,14 +307,13 @@ describe("assertLegacyCocodNotRunning", () => {
     await expect(
       assertLegacyCocodNotRunning({
         socketPath: SOCKET_PATH,
-        pidFilePath: PID_FILE_PATH,
         pathExists: socketOnly,
         fetchImpl,
       }),
     ).resolves.toBeUndefined();
   });
 
-  it("refuses to continue when the legacy PID is still running", async () => {
+  it("allows a live shared PID owner when no cocod socket exists", async () => {
     const fetchImpl = mock<LegacyFetch>(async () =>
       Response.json({ output: "pong" }),
     );
@@ -292,38 +321,26 @@ describe("assertLegacyCocodNotRunning", () => {
     await expect(
       assertLegacyCocodNotRunning({
         socketPath: SOCKET_PATH,
-        pidFilePath: PID_FILE_PATH,
         pathExists: (path) => path === PID_FILE_PATH,
-        readFile: () => "4242\n",
-        isProcessRunning: (pid) => pid === 4242,
         fetchImpl,
       }),
-    ).rejects.toThrow("Legacy cocod daemon is still running with PID 4242");
+    ).resolves.toBeUndefined();
 
     expect(fetchImpl).not.toHaveBeenCalled();
   });
 
-  it("ignores a stale PID file when no socket exists", async () => {
-    await expect(
-      assertLegacyCocodNotRunning({
-        socketPath: SOCKET_PATH,
-        pidFilePath: PID_FILE_PATH,
-        pathExists: (path) => path === PID_FILE_PATH,
-        readFile: () => "4242\n",
-        isProcessRunning: () => false,
-      }),
-    ).resolves.toBeUndefined();
-  });
+  it("allows a live shared PID owner when the cocod socket is stale", async () => {
+    const fetchImpl = mock<LegacyFetch>(async () => {
+      throw Object.assign(new Error("socket unavailable"), {
+        code: "ECONNREFUSED",
+      });
+    });
 
-  it("ignores the caller's own migration lock PID", async () => {
     await expect(
       assertLegacyCocodNotRunning({
         socketPath: SOCKET_PATH,
-        pidFilePath: PID_FILE_PATH,
-        pathExists: (path) => path === PID_FILE_PATH,
-        readFile: () => "4242\n",
-        isProcessRunning: () => true,
-        ignorePid: 4242,
+        pathExists: () => true,
+        fetchImpl,
       }),
     ).resolves.toBeUndefined();
   });
@@ -336,7 +353,6 @@ describe("assertLegacyCocodNotRunning", () => {
     await expect(
       assertLegacyCocodNotRunning({
         socketPath: SOCKET_PATH,
-        pidFilePath: PID_FILE_PATH,
         pathExists: socketOnly,
         fetchImpl,
       }),
@@ -453,7 +469,7 @@ describe("claimLegacyCocodPidFile", () => {
         readFile: () => "4242",
         isProcessRunning: () => true,
       }),
-    ).toThrow("Another cocod or routstrd process may be starting");
+    ).toThrow("PID 4242 is still running and holds it");
   });
 
   it("replaces a confirmed stale PID file before claiming it", () => {
@@ -505,4 +521,149 @@ describe("claimLegacyCocodPidFile", () => {
     release();
     expect(removed).toBe(false);
   });
+
+  it("registers and removes synchronous process-exit cleanup", () => {
+    const before = process.listenerCount("exit");
+    const release = claimLegacyCocodPidFile({
+      pidFilePath: PID_FILE_PATH,
+      pid: 4242,
+      openExclusive: () => 7,
+      writePid: () => {},
+      closeFile: () => {},
+      readFile: () => "4242",
+      removeFile: () => {},
+    });
+
+    expect(process.listenerCount("exit")).toBe(before + 1);
+    release();
+    expect(process.listenerCount("exit")).toBe(before);
+  });
+});
+
+describe("settleExpiredMintQuotes", () => {
+  const EXPIRED_S = 1_000_000; // epoch seconds, long past
+  const NOW_MS = 2_000_000_000_000;
+
+  function pendingMintOp(overrides: Record<string, unknown> = {}) {
+    return {
+      id: "op-1",
+      mintUrl: "https://mint.example.com",
+      quoteId: "quote-1",
+      state: "pending",
+      expiry: EXPIRED_S,
+      updatedAt: NOW_MS - 60_000,
+      lastObservedRemoteState: undefined,
+      ...overrides,
+    };
+  }
+
+  function fakeSource(
+    ops: Array<Record<string, unknown>>,
+    behavior: {
+      observe?: (id: string) => Promise<{ category: "waiting" | "ready" | "completed" | "terminal" }>;
+    } = {},
+  ) {
+    const failPendingOperation = mock(
+      async (
+        _op: { id: string },
+        _failure: { reason: string; retryable?: boolean; observedAt: number },
+      ) => ({}),
+    );
+    const observePendingOperation = mock(
+      behavior.observe ??
+        (async (
+          _id: string,
+        ): Promise<{ category: "waiting" | "ready" | "completed" | "terminal" }> => ({
+          category: "waiting",
+        })),
+    );
+    const source = {
+      ops: { mint: { listPending: async () => ops } },
+      mintOperationService: { observePendingOperation, failPendingOperation },
+    } as unknown as ExpiredMintQuoteSource;
+    return { source, observePendingOperation, failPendingOperation };
+  }
+
+  it("fails an expired quote locally when its mint confirms it is unpaid", async () => {
+    const op = pendingMintOp();
+    const { source, failPendingOperation } = fakeSource([op]);
+
+    const result = await settleExpiredMintQuotes(source, NOW_MS);
+
+    expect(result).toEqual({ failed: 1, leftForRecovery: 0, unobserved: 0 });
+    expect(failPendingOperation).toHaveBeenCalledTimes(1);
+    expect(failPendingOperation.mock.calls[0]?.[0]).toEqual({ id: "op-1" });
+  });
+
+  it("leaves an expired quote observed as PAID for mint recovery", async () => {
+    const op = pendingMintOp();
+    const { source, failPendingOperation } = fakeSource([op], {
+      observe: async () => ({ category: "ready" }),
+    });
+
+    const result = await settleExpiredMintQuotes(source, NOW_MS);
+
+    expect(result).toEqual({ failed: 0, leftForRecovery: 1, unobserved: 0 });
+    expect(failPendingOperation).not.toHaveBeenCalled();
+  });
+
+  it("leaves an expired quote observed as ISSUED for mint recovery", async () => {
+    const op = pendingMintOp();
+    const { source, failPendingOperation } = fakeSource([op], {
+      observe: async () => ({ category: "completed" }),
+    });
+
+    const result = await settleExpiredMintQuotes(source, NOW_MS);
+
+    expect(result).toEqual({ failed: 0, leftForRecovery: 1, unobserved: 0 });
+    expect(failPendingOperation).not.toHaveBeenCalled();
+  });
+
+  it("leaves quotes pending when their mint cannot be checked", async () => {
+    const op = pendingMintOp();
+    const { source, failPendingOperation } = fakeSource([op], {
+      observe: async () => {
+        throw new Error("Network request failed");
+      },
+    });
+
+    const result = await settleExpiredMintQuotes(source, NOW_MS);
+
+    expect(result).toEqual({ failed: 0, leftForRecovery: 0, unobserved: 1 });
+    expect(failPendingOperation).not.toHaveBeenCalled();
+  });
+
+  it("stops observing once the shared deadline is exhausted", async () => {
+    const ops = [
+      pendingMintOp({ id: "op-1", quoteId: "q-1" }),
+      pendingMintOp({ id: "op-2", quoteId: "q-2" }),
+    ];
+    const { source, failPendingOperation } = fakeSource(ops, {
+      // A hung mint: the observation never settles.
+      observe: () => new Promise(() => {}),
+    });
+
+    const started = Date.now();
+    const result = await settleExpiredMintQuotes(source, NOW_MS, 50);
+
+    expect(Date.now() - started).toBeLessThan(5_000);
+    expect(result).toEqual({ failed: 0, leftForRecovery: 0, unobserved: 2 });
+    expect(failPendingOperation).not.toHaveBeenCalled();
+  });
+
+  it("does not touch unexpired or already-observed quotes", async () => {
+    const ops = [
+      pendingMintOp({ id: "unexpired", expiry: NOW_MS / 1000 + 600 }),
+      pendingMintOp({ id: "seen-paid", lastObservedRemoteState: "PAID" }),
+      pendingMintOp({ id: "seen-issued", lastObservedRemoteState: "ISSUED" }),
+    ];
+    const { source, observePendingOperation, failPendingOperation } =
+      fakeSource(ops);
+
+    const result = await settleExpiredMintQuotes(source, NOW_MS);
+
+    expect(result).toEqual({ failed: 0, leftForRecovery: 0, unobserved: 0 });
+    expect(observePendingOperation).not.toHaveBeenCalled();
+    expect(failPendingOperation).not.toHaveBeenCalled();
+  });
 });