cartethyia 2.5.9 → 2.6.0

package/scripts/cli/start.ts

@@ -1,82 +1,85 @@
-import { resolvePort } from "../../src/config/runtime";
-import { ensureDrainToken } from "./instance";
-import { clearInstanceLock, pidAlive, readInstanceLock, writeInstanceLock } from "./instance";
-import { blockedPortMessage, listenPortErrorMessage, probeListenPort } from "./port";
-
-/**
- * Runs the gateway in the foreground, in this process.
- *
- * A foreground run still needs a drain token on disk: the gateway registers
- * `/admin/drain` only when one is set, and "Hide to tray" hands this run to a
- * tray that drains it through that route.
- *
- * Unlike the menu and tray paths this one does not spawn a child, so the
- * port-busy check has to happen here too — otherwise a stale gateway makes a
- * plain `cartethyia start` fail from inside `src/main` with a message that says
- * nothing about what to do.
- */
-export async function startForeground(): Promise<void> {
-  const token = ensureDrainToken();
-  process.env.CARTETHYIA_DRAIN_TOKEN ??= token;
-  const port = resolvePort();
-  const probe = await probeListenPort(port);
-  if (probe.status === "blocked" && probe.code !== "EADDRINUSE") {
-    throw new Error(listenPortErrorMessage(port, probe));
-  }
-  const blocker = await inspectPortHolder(port, token);
-  if (blocker !== null) throw new Error(blocker);
-  writeInstanceLock(port, process.pid, token);
-  await import("../../src/main");
-}
-
-/**
- * What to tell the operator when the port is already taken, or `null` when the
- * port is free (or was freed).
- *
- * Same rule as the spawned path: only ever stop a gateway that proves it is
- * this install's own. A drain request is token-gated, so a 401 means another
- * Cartethyia install and anything else is not a gateway at all — neither may be
- * touched, and both are reported instead.
- */
-async function inspectPortHolder(port: number, token: string): Promise<string | null> {
-  const up = await fetch(`http://127.0.0.1:${port}/health`, {
-    signal: AbortSignal.timeout(1_000),
-  }).catch(() => null);
-  if (up === null) {
-    // Port is free. Drop a stale marker from a crashed run so the next start
-    // does not read a dead pid as a live gateway.
-    const lock = readInstanceLock();
-    if (lock !== null && lock.port === port && !pidAlive(lock.pid)) clearInstanceLock();
-    return null;
-  }
-  const response = await fetch(`http://127.0.0.1:${port}/admin/drain`, {
-    method: "POST",
-    headers: { "x-drain-token": token },
-    signal: AbortSignal.timeout(3_000),
-  }).catch(() => null);
-  if (response === null) {
-    return blockedPortMessage(port);
-  }
-  if (response.status === 401) {
-    return `Another Cartethyia gateway is already running on port ${port} under a different install. Stop it from its own terminal or tray — this install will not stop a gateway it does not own.`;
-  }
-  if (response.status === 403) {
-    return `Port ${port} refused a drain from loopback. Stop what holds it, then start again.`;
-  }
-  if (response.status !== 202) {
-    return `Port ${port} is busy and refused to drain (HTTP ${response.status}). Stop it manually, then start again.`;
-  }
-  // Drain accepted; wait for the port to actually close.
-  const deadline = Date.now() + 30_000;
-  while (Date.now() < deadline) {
-    const stillUp = await fetch(`http://127.0.0.1:${port}/health`, {
-      signal: AbortSignal.timeout(500),
-    }).catch(() => null);
-    if (stillUp === null) {
-      clearInstanceLock();
-      return null;
-    }
-    await Bun.sleep(200);
-  }
-  return `The gateway on port ${port} accepted a drain but did not release the port within 30 seconds. Stop it manually, then start again.`;
-}
+import { resolvePort } from "../../src/config/runtime";
+import { ensureDrainToken } from "./instance";
+import { clearInstanceLock, pidAlive, readInstanceLock, writeInstanceLock } from "./instance";
+import { blockedPortMessage, listenPortErrorMessage, probeListenPort } from "./port";
+
+/**
+ * Runs the gateway in the foreground, in this process.
+ *
+ * A foreground run still needs a drain token on disk: the gateway registers
+ * `/admin/drain` only when one is set, and "Hide to tray" hands this run to a
+ * tray that drains it through that route.
+ *
+ * Unlike the menu and tray paths this one does not spawn a child, so the
+ * port-busy check has to happen here too — otherwise a stale gateway makes a
+ * plain `cartethyia start` fail from inside `src/main` with a message that says
+ * nothing about what to do.
+ */
+export async function startForeground(): Promise<void> {
+  const token = ensureDrainToken();
+  process.env.CARTETHYIA_DRAIN_TOKEN ??= token;
+  const port = resolvePort();
+  const probe = await probeListenPort(port);
+  if (probe.status === "blocked" && probe.code !== "EADDRINUSE") {
+    throw new Error(listenPortErrorMessage(port, probe));
+  }
+  const blocker = await inspectPortHolder(port, token);
+  if (blocker !== null) throw new Error(blocker);
+  writeInstanceLock(port, process.pid, token);
+  // dynamic-import: `src/main` boots the gateway as a side effect of module
+  // evaluation. Importing it statically would start the server before the
+  // port probe + instance-lock sequence above has a chance to refuse the run.
+  await import("../../src/main");
+}
+
+/**
+ * What to tell the operator when the port is already taken, or `null` when the
+ * port is free (or was freed).
+ *
+ * Same rule as the spawned path: only ever stop a gateway that proves it is
+ * this install's own. A drain request is token-gated, so a 401 means another
+ * Cartethyia install and anything else is not a gateway at all — neither may be
+ * touched, and both are reported instead.
+ */
+async function inspectPortHolder(port: number, token: string): Promise<string | null> {
+  const up = await fetch(`http://127.0.0.1:${port}/health`, {
+    signal: AbortSignal.timeout(1_000),
+  }).catch(() => null);
+  if (up === null) {
+    // Port is free. Drop a stale marker from a crashed run so the next start
+    // does not read a dead pid as a live gateway.
+    const lock = readInstanceLock();
+    if (lock !== null && lock.port === port && !pidAlive(lock.pid)) clearInstanceLock();
+    return null;
+  }
+  const response = await fetch(`http://127.0.0.1:${port}/admin/drain`, {
+    method: "POST",
+    headers: { "x-drain-token": token },
+    signal: AbortSignal.timeout(3_000),
+  }).catch(() => null);
+  if (response === null) {
+    return blockedPortMessage(port);
+  }
+  if (response.status === 401) {
+    return `Another Cartethyia gateway is already running on port ${port} under a different install. Stop it from its own terminal or tray — this install will not stop a gateway it does not own.`;
+  }
+  if (response.status === 403) {
+    return `Port ${port} refused a drain from loopback. Stop what holds it, then start again.`;
+  }
+  if (response.status !== 202) {
+    return `Port ${port} is busy and refused to drain (HTTP ${response.status}). Stop it manually, then start again.`;
+  }
+  // Drain accepted; wait for the port to actually close.
+  const deadline = Date.now() + 30_000;
+  while (Date.now() < deadline) {
+    const stillUp = await fetch(`http://127.0.0.1:${port}/health`, {
+      signal: AbortSignal.timeout(500),
+    }).catch(() => null);
+    if (stillUp === null) {
+      clearInstanceLock();
+      return null;
+    }
+    await Bun.sleep(200);
+  }
+  return `The gateway on port ${port} accepted a drain but did not release the port within 30 seconds. Stop it manually, then start again.`;
+}

package/scripts/cli/startup-signal.ts

@@ -1,23 +1,23 @@
-import { writeFileSync } from "node:fs";
-
-/**
- * Reports tray readiness to the launcher that is waiting on a signal file.
- *
- * The tray is spawned detached with no stdio, so the launcher cannot read its
- * output; a one-shot file is the only channel that survives the parent exiting.
- * `flag: "wx"` makes the write fail rather than overwrite, which keeps a late
- * report from replacing the failure the launcher already acted on.
- */
-export type TrayStartupSignal =
-  | { readonly status: "ready"; readonly url: string }
-  | { readonly status: "failed"; readonly message: string };
-
-export function reportTrayStartup(signal: TrayStartupSignal): void {
-  const signalPath = process.env.CARTETHYIA_TRAY_STARTUP_SIGNAL;
-  if (!signalPath) return;
-  try {
-    writeFileSync(signalPath, JSON.stringify(signal), { encoding: "utf8", flag: "wx" });
-  } catch {
-    // The launcher may have timed out and removed the one-shot signal file.
-  }
-}
+import { writeFileSync } from "node:fs";
+
+/**
+ * Reports tray readiness to the launcher that is waiting on a signal file.
+ *
+ * The tray is spawned detached with no stdio, so the launcher cannot read its
+ * output; a one-shot file is the only channel that survives the parent exiting.
+ * `flag: "wx"` makes the write fail rather than overwrite, which keeps a late
+ * report from replacing the failure the launcher already acted on.
+ */
+export type TrayStartupSignal =
+  | { readonly status: "ready"; readonly url: string }
+  | { readonly status: "failed"; readonly message: string };
+
+export function reportTrayStartup(signal: TrayStartupSignal): void {
+  const signalPath = process.env.CARTETHYIA_TRAY_STARTUP_SIGNAL;
+  if (!signalPath) return;
+  try {
+    writeFileSync(signalPath, JSON.stringify(signal), { encoding: "utf8", flag: "wx" });
+  } catch {
+    // The launcher may have timed out and removed the one-shot signal file.
+  }
+}

package/scripts/cli/telemetry.ts

@@ -0,0 +1,70 @@
+/**
+ * `carte telemetry reconcile` — recovers telemetry rows the SQL table missed.
+ *
+ * The durable record is `telemetry_events`, written in the same transaction as
+ * the request's admission/usage accounting. The raw JSONL files are an
+ * at-least-once mirror: a crash between the raw append and the commit can
+ * leave a line whose row never landed. This command drains that gap, and is
+ * also how a deployment that predates the SQL table gets its history back.
+ *
+ * It talks to the database directly (not through the gateway) because the
+ * gateway may be down — a reconciliation is exactly what you run after an
+ * incident — and because the job is lease-guarded, so it is safe even with the
+ * gateway up and writing.
+ */
+
+import { bootDatabase, closeDb, getDb } from "../../src/persistence/boot";
+import { reconcileTelemetry } from "../../src/observability/telemetry-reconciliation";
+
+function usage(): string {
+  return [
+    "Usage:",
+    "  cartethyia telemetry reconcile --verify   report the gap, write nothing",
+    "  cartethyia telemetry reconcile --apply    insert the missing rows",
+    "",
+    "--verify is read-only and takes no lease, so it is safe to run while the",
+    "gateway is serving. --apply holds a lease for the duration of the run;",
+    "a second invocation reports `lease_held` and exits without writing.",
+    "",
+    "Usage counters (telemetry_usage_totals) are never modified: they were",
+    "charged at request time, and re-charging from a backfill would inflate",
+    "every dashboard figure for the affected window.",
+  ].join("\n");
+}
+
+export async function telemetry(argv: readonly string[]): Promise<void> {
+  const mode = argv.find((arg) => arg === "--apply" || arg === "--verify");
+  if (mode === undefined) {
+    console.error(`No mode given.\n\n${usage()}`);
+    process.exitCode = 2;
+    return;
+  }
+
+  await bootDatabase();
+  try {
+    const report = await reconcileTelemetry(getDb(), { verify: mode === "--verify" });
+    if (!report.ran) {
+      const why =
+        report.skippedReason === "lease_held"
+          ? "another runner holds the lease — try again later"
+          : report.skippedReason === "no_files"
+            ? "no eligible raw telemetry files (the current and previous UTC hour are always skipped)"
+            : "checkpoint is up to date — nothing to reconcile";
+      console.log(`telemetry reconcile (${mode}): skipped — ${why}`);
+      return;
+    }
+    console.log(
+      [
+        `telemetry reconcile (${mode}): done`,
+        `  files completed : ${report.filesCompleted}`,
+        `  events examined : ${report.eventsExamined}`,
+        `  events inserted : ${report.eventsInserted}`,
+        `  conflicts       : ${report.conflicts} (already present)`,
+        `  bytes read      : ${report.bytesRead}`,
+      ].join("\n"),
+    );
+  } finally {
+    await closeDb().catch(() => undefined);
+  }
+}
+