cartethyia 2.5.1 → 2.5.3

package/scripts/cli/command/tray.ts

@@ -1,204 +1,208 @@
-import { isNewerRelease } from "../../../src/console/updates/version-compare";
-import { resolvePackagePath } from "../../../src/config/package-paths";
-import { resolvePort } from "../../../src/config/runtime";
-import { ensureDrainToken } from "../gateway/drain-token";
-import { startGateway } from "../gateway/spawn";
-import { stopGateway } from "../gateway/stop";
-import { readInstalledVersion, readLatestPublishedVersion } from "../support/version";
-import { reportTrayStartup } from "../support/startup-signal";
-import { createTray } from "../tray";
-import { openUrl } from "../ui/background";
-import { exportBackup, resetConsoleAccount } from "./admin";
-import { printUpdateInstructions } from "./update";
-
-/**
- * Runs the gateway with a tray icon. The tray is platform-specific (`tray/`):
- * on Windows it is a PowerShell NotifyIcon, because a Node tray library leaves
- * an empty console tab open for the tray's whole lifetime, and that window is
- * owned by Windows Terminal — not by this process, so it cannot be found and
- * hidden from inside.
- *
- * The gateway it starts is detached, which is what makes the health poll below
- * necessary — see {@link TRAY_HEALTH_POLL_MS}.
- */
-
-/**
- * How often the tray asks whether the gateway is still answering.
- *
- * 10 s: often enough that an operator who stops the gateway by hand sees the
- * icon go away, and far below the cost of a request. A detached gateway can no
- * longer be waited on, so this poll is the only signal left.
- */
-const TRAY_HEALTH_POLL_MS = 10_000;
-
-/**
- * Consecutive misses to forgive before a dead gateway closes the tray.
- *
- * One refusal is not a stopped gateway — a probe can lose a race with startup
- * or a slow request — and closing the icon on one would make startup feel
- * random.
- */
-const TRAY_HEALTH_MISSES_BEFORE_CLOSE = 3;
-
-export async function startTray(): Promise<void> {
-  const port = resolvePort();
-  const drainToken = ensureDrainToken();
-  const dashboardUrl = `http://127.0.0.1:${port}/console`;
-  const repositoryUrl = "https://github.com/risunCode/cartethyia";
-  const currentVersion = await readInstalledVersion();
-
-  let gateway: Bun.Subprocess | null = null;
-  let closing = false;
-  let busy = false;
-  let resetArmed = false;
-  let latestVersion: string | null = null;
-  let closePromise: Promise<void> | undefined;
-
-  const tray = createTray({
-    iconPath: resolvePackagePath(
-      "scripts",
-      "cli",
-      "tray",
-      "assets",
-      process.platform === "win32" ? "cartethyia.ico" : "cartethyia.png",
-    ),
-    tooltip: `Cartethyia ${currentVersion}`,
-    items: [
-      { kind: "action", id: "update", title: `Cartethyia ${currentVersion} \u00b7 checking\u2026`, enabled: true },
-      { kind: "separator" },
-      { kind: "action", id: "console", title: `Open Console \u00b7 ${dashboardUrl}` },
-      { kind: "action", id: "reset", title: "Reset console password" },
-      { kind: "action", id: "backup", title: "Backup" },
-      { kind: "separator" },
-      { kind: "action", id: "exit", title: "Exit" },
-    ],
-    onSelect: (id: string) => void handleSelect(id),
-    onExit: () => void close(1),
-  });
-
-  const close = (exitCode = 0): Promise<void> => {
-    if (closePromise) return closePromise;
-    closing = true;
-    closePromise = (async () => {
-      const current: Bun.Subprocess | null = gateway;
-      gateway = null;
-      if (current) await stopGateway(current, port, drainToken);
-      await tray.close();
-      process.exitCode = exitCode;
-    })();
-    return closePromise;
-  };
-
-  const refreshVersion = async (): Promise<void> => {
-    const fetched = await readLatestPublishedVersion();
-    if (closing) return;
-    latestVersion = fetched;
-    if (fetched === null) {
-      tray.update("update", `Cartethyia ${currentVersion} \u00b7 check for updates`, true);
-      return;
-    }
-    const newer = isNewerRelease(currentVersion, fetched);
-    tray.update(
-      "update",
-      newer
-        ? `Cartethyia ${currentVersion} \u00b7 update to ${fetched}`
-        : `Cartethyia ${currentVersion} \u00b7 up to date`,
-      // Always clickable: the row opens the repository, and only offers the
-      // update command when there is something newer.
-      true,
-    );
-  };
-
-  const runUpdate = async (): Promise<void> => {
-    if (busy) return;
-    busy = true;
-    const latest = await readLatestPublishedVersion();
-    await close();
-    printUpdateInstructions(currentVersion, latest);
-    process.exit(0);
-  };
-
-  async function handleSelect(id: string): Promise<void> {
-    if (closing) return;
-    if (id === "exit") return void (await close());
-    if (id === "console") return void (await openUrl(dashboardUrl));
-    if (id === "backup") {
-      const result = await exportBackup(port, drainToken);
-      if (result !== null) {
-        console.log(
-          `Backup written to ${result.path} (${(result.bytes / 1024).toFixed(1)} KiB). Telemetry is not included.`,
-        );
-      }
-      return;
-    }
-    if (id === "reset") {
-      // A tray click cannot ask for the typed confirmation the menu uses, so
-      // the first click arms the action and the second one runs it.
-      if (!resetArmed) {
-        resetArmed = true;
-        tray.update("reset", "Reset console password \u00b7 click again to delete", true);
-        return;
-      }
-      resetArmed = false;
-      tray.update("reset", "Reset console password", true);
-      await resetConsoleAccount(port, drainToken);
-      return;
-    }
-    if (id === "update") {
-      // Nothing to install: the row is the way to the repository instead.
-      if (latestVersion === null || !isNewerRelease(currentVersion, latestVersion)) {
-        await openUrl(repositoryUrl);
-        return;
-      }
-      await runUpdate();
-    }
-  }
-
-  process.once("SIGINT", () => void close());
-  process.once("SIGTERM", () => void close());
-
-  try {
-    await tray.ready();
-    // Detached, unlike every other caller: the gateway must outlive this
-    // process. Attached, it dies with the tray — and the tray dies with the
-    // terminal that launched it, so closing that terminal took the gateway
-    // down too and "Hide to tray" left nothing serving. `stopGateway` drains
-    // over HTTP before it ever reaches for `kill()`, so detaching costs the
-    // exit path nothing: the tray can still stop the gateway on Exit.
-    gateway = await startGateway(port, drainToken, { detached: true });
-    // The launcher that spawned this tray is blocked on a signal file: it
-    // cannot read our stdio, because the tray is detached. Without this write
-    // it waits out its 60 s deadline and reports a failure for a tray that is
-    // running fine.
-    reportTrayStartup({ status: "ready", url: dashboardUrl });
-    console.log(`Cartethyia is running at ${dashboardUrl}`);
-    void refreshVersion();
-
-    let misses = 0;
-    // A detached child's `exited` never settles on Windows, so the old
-    // `await current.exited` would have parked here forever and the tray would
-    // never notice the gateway going away. Poll its health endpoint instead:
-    // that answers for a process we no longer own, which is the whole point of
-    // detaching it. The probe is the same one startup used, so a gateway that
-    // is up reads as up regardless of who spawned it.
-    while (!closing) {
-      await Bun.sleep(TRAY_HEALTH_POLL_MS);
-      if (closing || gateway === null) continue;
-      const alive = await fetch(`http://127.0.0.1:${port}/health`, {
-        signal: AbortSignal.timeout(2_000),
-      }).then((response) => response.ok).catch(() => false);
-      if (alive) {
-        misses = 0;
-        continue;
-      }
-      misses += 1;
-      if (misses < TRAY_HEALTH_MISSES_BEFORE_CLOSE) continue;
-      gateway = null;
-      console.error("Cartethyia stopped answering; the tray is closing.");
-      await close(1);
-    }
-  } catch (error) {
-    await close(1);
-    throw error;
-  }
-}
+import { isNewerRelease } from "../../../src/console/updates/version-compare";
+import { resolvePackagePath } from "../../../src/config/package-paths";
+import { resolvePort } from "../../../src/config/runtime";
+import { ensureDrainToken } from "../gateway/drain-token";
+import { startGateway } from "../gateway/spawn";
+import { stopGateway } from "../gateway/stop";
+import { readInstalledVersion, readLatestPublishedVersion } from "../support/version";
+import { reportTrayStartup } from "../support/startup-signal";
+import { createTray } from "../tray";
+import { openUrl } from "../ui/background";
+import { exportBackup, resetConsoleAccount } from "./admin";
+import { printUpdateInstructions } from "./update";
+
+/**
+ * Runs the gateway with a tray icon. The tray is platform-specific (`tray/`):
+ * on Windows it is a PowerShell NotifyIcon, because a Node tray library leaves
+ * an empty console tab open for the tray's whole lifetime, and that window is
+ * owned by Windows Terminal — not by this process, so it cannot be found and
+ * hidden from inside.
+ *
+ * The gateway it starts is detached, which is what makes the health poll below
+ * necessary — see {@link TRAY_HEALTH_POLL_MS}.
+ */
+
+/**
+ * How often the tray asks whether the gateway is still answering.
+ *
+ * 10 s: often enough that an operator who stops the gateway by hand sees the
+ * icon go away, and far below the cost of a request. A detached gateway can no
+ * longer be waited on, so this poll is the only signal left.
+ */
+const TRAY_HEALTH_POLL_MS = 10_000;
+
+/**
+ * Consecutive misses to forgive before a dead gateway closes the tray.
+ *
+ * One refusal is not a stopped gateway — a probe can lose a race with startup
+ * or a slow request — and closing the icon on one would make startup feel
+ * random.
+ */
+const TRAY_HEALTH_MISSES_BEFORE_CLOSE = 3;
+
+export async function startTray(): Promise<void> {
+  const port = resolvePort();
+  const drainToken = ensureDrainToken();
+  const dashboardUrl = `http://127.0.0.1:${port}/console`;
+  const repositoryUrl = "https://github.com/risunCode/cartethyia";
+  const currentVersion = await readInstalledVersion();
+
+  let gateway: Bun.Subprocess | null = null;
+  let closing = false;
+  let busy = false;
+  let resetArmed = false;
+  let latestVersion: string | null = null;
+  let closePromise: Promise<void> | undefined;
+
+  const tray = createTray({
+    iconPath: resolvePackagePath(
+      "scripts",
+      "cli",
+      "tray",
+      "assets",
+      process.platform === "win32" ? "cartethyia.ico" : "cartethyia.png",
+    ),
+    tooltip: `Cartethyia ${currentVersion}`,
+    items: [
+      { kind: "action", id: "update", title: `Cartethyia ${currentVersion} \u00b7 checking\u2026`, enabled: true },
+      { kind: "separator" },
+      { kind: "action", id: "console", title: `Open Console \u00b7 ${dashboardUrl}` },
+      { kind: "action", id: "reset", title: "Reset console password" },
+      { kind: "action", id: "backup", title: "Backup" },
+      { kind: "separator" },
+      { kind: "action", id: "exit", title: "Exit" },
+    ],
+    onSelect: (id: string) => void handleSelect(id),
+    onExit: () => void close(1),
+  });
+
+  const close = (exitCode = 0): Promise<void> => {
+    if (closePromise) return closePromise;
+    closing = true;
+    closePromise = (async () => {
+      const current: Bun.Subprocess | null = gateway;
+      gateway = null;
+      if (current) await stopGateway(current, port, drainToken);
+      await tray.close();
+      process.exitCode = exitCode;
+    })();
+    return closePromise;
+  };
+
+  const refreshVersion = async (): Promise<void> => {
+    const fetched = await readLatestPublishedVersion();
+    if (closing) return;
+    latestVersion = fetched;
+    if (fetched === null) {
+      tray.update("update", `Cartethyia ${currentVersion} \u00b7 check for updates`, true);
+      return;
+    }
+    const newer = isNewerRelease(currentVersion, fetched);
+    tray.update(
+      "update",
+      newer
+        ? `Cartethyia ${currentVersion} \u00b7 update to ${fetched}`
+        : `Cartethyia ${currentVersion} \u00b7 up to date`,
+      // Always clickable: the row opens the repository, and only offers the
+      // update command when there is something newer.
+      true,
+    );
+  };
+
+  const runUpdate = async (): Promise<void> => {
+    if (busy) return;
+    busy = true;
+    const latest = await readLatestPublishedVersion();
+    await close();
+    printUpdateInstructions(currentVersion, latest);
+    // The tray has no terminal of its own, so these instructions are only
+    // visible when it was started from one. Hold that terminal open long
+    // enough to copy the command, then exit.
+    await new Promise<void>((resolve) => setTimeout(resolve, 180_000));
+    process.exit(0);
+  };
+
+  async function handleSelect(id: string): Promise<void> {
+    if (closing) return;
+    if (id === "exit") return void (await close());
+    if (id === "console") return void (await openUrl(dashboardUrl));
+    if (id === "backup") {
+      const result = await exportBackup(port, drainToken);
+      if (result !== null) {
+        console.log(
+          `Backup written to ${result.path} (${(result.bytes / 1024).toFixed(1)} KiB). Telemetry is not included.`,
+        );
+      }
+      return;
+    }
+    if (id === "reset") {
+      // A tray click cannot ask for the typed confirmation the menu uses, so
+      // the first click arms the action and the second one runs it.
+      if (!resetArmed) {
+        resetArmed = true;
+        tray.update("reset", "Reset console password \u00b7 click again to delete", true);
+        return;
+      }
+      resetArmed = false;
+      tray.update("reset", "Reset console password", true);
+      await resetConsoleAccount(port, drainToken);
+      return;
+    }
+    if (id === "update") {
+      // Nothing to install: the row is the way to the repository instead.
+      if (latestVersion === null || !isNewerRelease(currentVersion, latestVersion)) {
+        await openUrl(repositoryUrl);
+        return;
+      }
+      await runUpdate();
+    }
+  }
+
+  process.once("SIGINT", () => void close());
+  process.once("SIGTERM", () => void close());
+
+  try {
+    await tray.ready();
+    // Detached, unlike every other caller: the gateway must outlive this
+    // process. Attached, it dies with the tray — and the tray dies with the
+    // terminal that launched it, so closing that terminal took the gateway
+    // down too and "Hide to tray" left nothing serving. `stopGateway` drains
+    // over HTTP before it ever reaches for `kill()`, so detaching costs the
+    // exit path nothing: the tray can still stop the gateway on Exit.
+    gateway = await startGateway(port, drainToken, { detached: true });
+    // The launcher that spawned this tray is blocked on a signal file: it
+    // cannot read our stdio, because the tray is detached. Without this write
+    // it waits out its 60 s deadline and reports a failure for a tray that is
+    // running fine.
+    reportTrayStartup({ status: "ready", url: dashboardUrl });
+    console.log(`Cartethyia is running at ${dashboardUrl}`);
+    void refreshVersion();
+
+    let misses = 0;
+    // A detached child's `exited` never settles on Windows, so the old
+    // `await current.exited` would have parked here forever and the tray would
+    // never notice the gateway going away. Poll its health endpoint instead:
+    // that answers for a process we no longer own, which is the whole point of
+    // detaching it. The probe is the same one startup used, so a gateway that
+    // is up reads as up regardless of who spawned it.
+    while (!closing) {
+      await Bun.sleep(TRAY_HEALTH_POLL_MS);
+      if (closing || gateway === null) continue;
+      const alive = await fetch(`http://127.0.0.1:${port}/health`, {
+        signal: AbortSignal.timeout(2_000),
+      }).then((response) => response.ok).catch(() => false);
+      if (alive) {
+        misses = 0;
+        continue;
+      }
+      misses += 1;
+      if (misses < TRAY_HEALTH_MISSES_BEFORE_CLOSE) continue;
+      gateway = null;
+      console.error("Cartethyia stopped answering; the tray is closing.");
+      await close(1);
+    }
+  } catch (error) {
+    await close(1);
+    throw error;
+  }
+}

package/src/boot/app.ts

@@ -15,6 +15,7 @@ import { GatewayError, publicGatewayErrorBody } from "../protocol/gateway-error"
 import { shutdownError, shutdownNotice } from "../transport/shutdown-notice";
 import type { CanonicalAdapter } from "../transport/contracts";
 import type { ApiKeyAuthorizationSnapshot } from "../security/api-key-auth";
+import { unknownApiKeyError } from "../security/api-key-auth";
 import { getDbHandle } from "../persistence/boot";
 import { isPgHandle } from "../persistence/db-pg";
 import { resolveRedisClient } from "../persistence/redis";
@@ -408,7 +409,7 @@ export function createGatewayApp(deps: GatewayAppDeps) {
     const handleModelsList = async ({ request }: { request: Request }): Promise<Response> => {
       const state = requestStateStore.require(request);
       const auth = state.authorization;
-      if (!auth) throw new GatewayError("invalid_request", 401, "This API key is unknown, revoked, or expired. Issue a new key and send it as: Authorization: Bearer <key>.");
+      if (!auth) throw unknownApiKeyError();
       const data = await queryAllowedModels(auth);
       return new Response(JSON.stringify({ object: "list", data }), {
         headers: {
@@ -431,7 +432,7 @@ export function createGatewayApp(deps: GatewayAppDeps) {
     }): Promise<Response> => {
       const state = requestStateStore.require(request);
       const auth = state.authorization;
-      if (!auth) throw new GatewayError("invalid_request", 401, "This API key is unknown, revoked, or expired. Issue a new key and send it as: Authorization: Bearer <key>.");
+      if (!auth) throw unknownApiKeyError();
       const raw = params?.["*"] ?? params?.id ?? "";
       const targetId = new URL(request.url).searchParams.get("id") ?? raw;
       const found = await publicModelStore.getPublicModelDetail(

package/src/config/spec.ts

@@ -157,7 +157,14 @@ export const CONFIG_SPEC = {
   },
 
   // Upstream request timeout + retry backoff
-  CARTETHYIA_UPSTREAM_TIMEOUT_MS: { kind: "int", default: 120_000, min: 5_000, max: 600_000 },
+  //
+  // Strictly under 90s: a client whose own deadline is 90s must never be
+  // waiting on a gateway that is still holding a request open past it, and a
+  // provider that has not answered within 75s is not answering — the request
+  // is queued upstream or the egress is stuck, and the honest move is to fail
+  // over to another account rather than burn the caller's whole budget on one.
+  // 120s outlived the clients that call this, which cap lower.
+  CARTETHYIA_UPSTREAM_TIMEOUT_MS: { kind: "int", default: 75_000, min: 5_000, max: 600_000 },
   CARTETHYIA_STREAM_STALL_TIMEOUT_MS: {
     kind: "int",
     default: 360_000,
@@ -181,7 +188,24 @@ export const CONFIG_SPEC = {
   CARTETHYIA_ACCOUNT_QUOTA_COOLDOWN_MS: { kind: "int", default: 3_600_000, min: 0, max: 86_400_000 },
   CARTETHYIA_ACCOUNT_MODEL_CAPACITY_COOLDOWN_MS: { kind: "int", default: 120_000, min: 0, max: 86_400_000 },
   CARTETHYIA_ACCOUNT_TRANSIENT_COOLDOWN_MS: { kind: "int", default: 30_000, min: 0, max: 86_400_000 },
-  CARTETHYIA_ACCOUNT_UNCLASSIFIED_COOLDOWN_MS: { kind: "int", default: 60_000, min: 0, max: 86_400_000 },
+  /**
+   * An unmapped upstream failure cools the account down for 15 minutes.
+   *
+   * It used to be 60s, which put the account straight back into rotation and
+   * re-dialled an upstream that had just answered something this gateway does
+   * not understand — so the same unknown error was retried every minute, and
+   * an account that was actually broken contributed a steady stream of failed
+   * attempts instead of one. Fifteen minutes is long enough for a transient
+   * provider condition to clear on its own and short enough that no operator
+   * action is needed to recover it. It is still a cooldown with a deadline,
+   * never `disabled`, so nothing here can strand an account.
+   */
+  CARTETHYIA_ACCOUNT_UNCLASSIFIED_COOLDOWN_MS: {
+    kind: "int",
+    default: 900_000,
+    min: 0,
+    max: 86_400_000,
+  },
   CARTETHYIA_ACCOUNT_COOLDOWN_ESCALATION_MAX_MS: { kind: "int", default: 3_600_000, min: 0, max: 86_400_000 },
   CARTETHYIA_POOL_COOLDOWN_MS: { kind: "int", default: 120_000, min: 0, max: 86_400_000 },
   CARTETHYIA_ACCOUNT_AUTH_REJECTED_COOLDOWN_MS: { kind: "int", default: 300_000, min: 0, max: 86_400_000 },

package/src/console/backup/routes.ts

@@ -78,6 +78,24 @@ const BACKUP_SCOPES = ["dashboard:write"] as const;
 const importBody = t.Object({
   password: t.String(),
   backup: t.Unknown(),
+  /**
+   * Table names to restore. Absent or empty restores every table in the file,
+   * which is what the dashboard's checklist defaults to and what the API did
+   * before selection existed.
+   */
+  tables: t.Optional(t.Array(t.String())),
+});
+
+/**
+ * The inspect body: a file, no password.
+ *
+ * Inspection writes nothing and reads no secret — it only reports which tables
+ * the file carries and which of them the live schema has — so it needs no
+ * re-authentication. Requiring the console password here would mean typing it
+ * twice for one restore.
+ */
+const inspectBody = t.Object({
+  backup: t.Unknown(),
 });
 
 const exportQuery = t.Object({
@@ -164,7 +182,12 @@ export function createBackupRoutes(config: BackupRoutesConfig): Elysia {
         // from nowhere else. A request body may not name the tenant it writes
         // into: that would let any holder of the scope import into, and
         // overwrite, a tenant they are not.
-        const result = await config.backupFor(request).restore(body.password, body.backup, access.tenantId);
+        const result = await config.backupFor(request).restore(
+          body.password,
+          body.backup,
+          access.tenantId,
+          body.tables === undefined ? undefined : { tables: body.tables },
+        );
         // Routing-visible write: the restore has committed, so the cached
         // snapshot must be rebuilt before the next `/v1/*` dispatch.
         await config.snapshotInvalidator?.invalidate();
@@ -214,5 +237,33 @@ export function createBackupRoutes(config: BackupRoutesConfig): Elysia {
       } catch (error) {
         return errorResponse(error, set, "Delete all failed");
       }
+    })
+    .post("/inspect", { body: inspectBody }, async ({ request, body, set }) => {
+      try {
+        const access = requireAnyScope(config.accessResolver(request), BACKUP_SCOPES);
+        if (access.tenantId === null) {
+          throw new ConsoleDomainError("tenant_required", 403, "Tenant isolation required");
+        }
+        // Same byte bound as the import, for the same reason: the file is
+        // parsed here too, and an unbounded one would be buffered before any
+        // validation could refuse it.
+        const declared = Number(request.headers.get("content-length") ?? "0");
+        const actualBytes = JSON.stringify(body ?? null).length;
+        if (
+          (Number.isFinite(declared) && declared > MAX_BACKUP_BYTES) ||
+          actualBytes > MAX_BACKUP_BYTES
+        ) {
+          set.status = 413;
+          return {
+            error: `backup exceeds the ${MAX_BACKUP_BYTES} byte limit`,
+            code: "request_too_large",
+          };
+        }
+        // Reads nothing and writes nothing: the checklist the restore wizard
+        // shows, so an operator can pick sections before typing a password.
+        return config.backupFor(request).inspect(body.backup);
+      } catch (error) {
+        return errorResponse(error, set, "Backup inspection failed");
+      }
     }) as unknown as Elysia;
 }