@c4roa0/agentpay-user 0.0.0-stage → 0.3.0

package/src/file-cache-cli.mjs

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: MPL-2.0
+// This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+// If a copy was not distributed with this file, see https://mozilla.org/MPL/2.0/.
+import { join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { resolveUserDataDir } from "./local-data-directory.mjs";
+import {
+  loadRuntimeConnection,
+  listResultFiles,
+  removeResultFile,
+} from "./runtime-client.mjs";
+export async function runFileCache(
+  args,
+  {
+    write = console.log,
+    ask = async (message) => {
+      const r = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+      });
+      try {
+        return await r.question(message + "\n> ");
+      } finally {
+        r.close();
+      }
+    },
+  } = {},
+) {
+  const dataDir = await resolveUserDataDir(),
+    state = join(dataDir, "runtime/invocations.json");
+  const [orderId, action = "list", key] = args;
+  if (
+    !/^0x[a-f0-9]{64}$/.test(orderId || "") ||
+    !["list", "remove"].includes(action) ||
+    (action === "list"
+      ? args.length > 3 || (key !== undefined && !/^[1-9][0-9]{0,5}$/.test(key))
+      : args.length !== 3)
+  ) {
+    write(
+      "Usage: agentpay orders files ORDER_ID [list PAGE]\n       agentpay orders files ORDER_ID remove FILE_KEY\nUse the full Order ID from agentpay orders details ID.",
+    );
+    return 2;
+  }
+  const connection = await loadRuntimeConnection({ dataDir });
+  if (action === "remove") {
+    if (
+      (
+        await ask(
+          "Remove this local file copy? Order history and payment are unchanged.\nType confirm to remove, or q to return.",
+        )
+      ).trim() !== "confirm"
+    )
+      return 0;
+    await removeResultFile(connection, {
+      orderId,
+      fileKey: key,
+      confirmed: true,
+    });
+    write("Local file removed. Its history is kept.");
+    return 0;
+  }
+  const page = Number(key || 1),
+    rows = await listResultFiles(connection, orderId, {
+      offset: (page - 1) * 100,
+    });
+  write("\n> Saved result files\n");
+  if (!rows.length)
+    write(
+      "No file copies saved for this Order. A link in a result is not automatically downloaded.",
+    );
+  for (const row of rows) {
+    const safe = (v) => String(v || "").replace(/[\x00-\x1f\x7f-\x9f]/g, "");
+    write(
+      `  ${safe(row.fileKey)} · ${row.state} · ${row.bytes} bytes\n  ${safe(row.filename)}${row.localPath ? "\n  " + safe(row.localPath) : ""}${row.error ? "\n  " + safe(row.error) : ""}`,
+    );
+  }
+  if (rows.length === 100)
+    write(`Next page: agentpay orders files ${orderId} list ${page + 1}`);
+  write(
+    "\nRuntime must be running; Wallet unlock is not required. File operations never make a payment.",
+  );
+  return 0;
+}

package/src/file-cache-owner.mjs

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: MPL-2.0
+// This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+// If a copy was not distributed with this file, see https://mozilla.org/MPL/2.0/.
+import { constants } from "node:fs";
+import { realpath, open, lstat } from "node:fs/promises";
+import { join } from "node:path";
+import { fileError } from "./file-download.mjs";
+const owners = new Map();
+// Keep the descriptor open for this Runtime's lifetime. OS file locks release on
+// exit, including a crash. The empty lock file remains: never unlink or replace it,
+// since another process may already have opened that same file to acquire its lock.
+export async function cacheOwner(directory) {
+  const canonical = await realpath(directory);
+  if (owners.has(canonical)) return owners.get(canonical);
+  const pending = (async () => {
+    let handle;
+    try {
+      // Load only when file caching is used. An unavailable native binding must not
+      // prevent Runtime startup, original Order checks or structured-result recovery.
+      let tryLock;
+      try {
+        ({ tryLock } = await import("fs-native-extensions"));
+      } catch {
+        throw fileError(
+          "FILE_CACHE_LOCK_UNAVAILABLE",
+          "File cache support is not installed for this system. Run npm ci in User, then restart Runtime.",
+        );
+      }
+      const path = join(canonical, "owner.lock");
+      handle = await open(
+        path,
+        constants.O_CREAT | constants.O_RDWR | (constants.O_NOFOLLOW || 0),
+        0o600,
+      );
+      const stat = await handle.stat(),
+        entry = await lstat(path);
+      if (
+        !stat.isFile() ||
+        entry.isSymbolicLink() ||
+        stat.nlink !== 1 ||
+        stat.dev !== entry.dev ||
+        stat.ino !== entry.ino ||
+        (typeof process.getuid === "function" &&
+          (stat.uid !== process.getuid() || stat.mode & 0o077))
+      ) {
+        throw fileError(
+          "FILE_CACHE_UNSAFE",
+          "File cache lock ownership or permissions need review.",
+        );
+      }
+      if (!tryLock(handle.fd))
+        throw fileError(
+          "FILE_CACHE_IN_USE",
+          "Another Runtime owns this file cache. Stop that Runtime before retrying.",
+        );
+      // Retaining handle also prevents FileHandle garbage collection closing the lock.
+      return { handle, tail: Promise.resolve(), initialized: false };
+    } catch (error) {
+      await handle?.close();
+      if (error.code?.startsWith("FILE_")) throw error;
+      throw fileError(
+        "FILE_CACHE_LOCK_UNAVAILABLE",
+        "Could not lock this cache directory. Check local filesystem support and permissions before retrying.",
+      );
+    }
+  })();
+  owners.set(canonical, pending);
+  try {
+    return await pending;
+  } catch (error) {
+    owners.delete(canonical);
+    throw error;
+  }
+}

package/src/file-cache-settings.mjs

@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: MPL-2.0
+// This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+// If a copy was not distributed with this file, see https://mozilla.org/MPL/2.0/.
+import { readPrivateJson } from "./order-review.mjs";
+export const fileCacheLimits = Object.freeze({
+  singleBytes: 100 * 1048576,
+  totalBytes: 512 * 1048576,
+  filesPerResult: 20,
+  concurrent: 2,
+  records: 10000,
+  timeoutMs: 900000,
+});
+export function validateCacheLimits(input = {}) {
+  if (
+    !input ||
+    typeof input !== "object" ||
+    Array.isArray(input) ||
+    Object.keys(input).some((k) => !Object.hasOwn(fileCacheLimits, k))
+  )
+    throw Error("Invalid file cache settings.");
+  const limits = { ...fileCacheLimits, ...input };
+  for (const [key, value] of Object.entries(limits))
+    if (!Number.isSafeInteger(value) || value < 1)
+      throw Error(`File cache ${key} must be a positive integer.`);
+  if (
+    limits.singleBytes > limits.totalBytes ||
+    limits.totalBytes > 1024 ** 4 ||
+    limits.concurrent > 16 ||
+    limits.records > 100000 ||
+    limits.filesPerResult > limits.records ||
+    limits.timeoutMs > 86400000
+  )
+    throw Error("File cache settings exceed supported bounds.");
+  return limits;
+}
+export async function readCacheLimits(statePath) {
+  try {
+    return validateCacheLimits(
+      (await readPrivateJson(statePath + ".file-cache-settings.json", 16384)) ||
+        {},
+    );
+  } catch {
+    throw Object.assign(
+      Error(
+        "File cache settings could not be read. Check the private JSON file shown by agentpay cache settings.",
+      ),
+      { code: "FILE_SETTINGS_INVALID", status: 409 },
+    );
+  }
+}