@checkstack/healthcheck-backend 1.9.2 → 1.10.0

package/CHANGELOG.md

@@ -1,5 +1,104 @@
 # @checkstack/healthcheck-backend
 
+## 1.10.0
+
+### Minor Changes
+
+- 8cad340: Add an AI assistant tool that lists the health checks assigned to a system.
+
+  The assistant previously had `healthcheck.status` (every check globally) but no
+  way to map a check to a system, so it had to guess which check monitored a given
+  system. It now projects `getSystemConfigurations` as the read-only tool
+  `healthcheck.listSystemChecks`: given a `systemId` (resolved from a name via
+  `catalog.listSystems`), it returns the checks assigned to that system - id, name,
+  strategy, interval, collectors/assertions, and paused state. The tool inherits
+  the source procedure's system-scoped `configuration.read` gate, so it stays
+  team-scoped and needs no new permission.
+
+- 8cad340: Add a finer per-run transport timing breakdown to health checks.
+
+  Each run now records an optional structured `metadata.timings` (DNS, connect,
+  TLS, wait/time-to-first-byte, transfer, and a `processing` catch-all for
+  non-HTTP operation time). The run-detail view renders the phases it has, in
+  transport order, and falls back to the previous Connection + Processing split
+  for older runs that lack the finer data.
+
+  For HTTP the request is issued verbatim through `fetch` (original URL, headers,
+  and body), so request behavior is identical to a plain `fetch`. The timing is
+  measured around it: `fetch` resolves at the response headers, so wait
+  (time-to-first-byte) and transfer (body) are measured exactly on the request,
+  DNS is timed at the resolve step, and connect/TLS come from a short-lived,
+  best-effort raw `net`/`tls` probe to the same already-validated IP (the request
+  socket exposes no connect/handshake events on the Bun runtime). The probe is
+  timing-only and never fails the check. The probe validates the TLS certificate
+  (against the original hostname via SNI) like the real request does - it does not
+  disable certificate validation; an unverifiable cert simply yields no TLS-phase
+  timing rather than aborting. Other transports surface the connect and operation
+  times they already measure.
+
+  The SSRF guard now validates the resolved host (rejecting cloud-metadata /
+  link-local and operator-denied ranges) as a pre-flight check and no longer pins
+  the request to the resolved IP. Pinning rewrote the URL to the IP literal and
+  moved the host to the `Host` header, which breaks HTTP/2 origins (their
+  authority comes from the URL's `:authority`, not `Host`) - that is why real
+  hosts such as `google.com` started answering 404/429 instead of 200. The
+  pre-flight validation keeps blocking static metadata/link-local targets and
+  direct denied IP literals; the only thing dropped is DNS-rebind TOCTOU
+  protection (a narrow window that pinning closed at the cost of breaking
+  legitimate HTTP/2 requests).
+
+  The run-detail "slowest" badge no longer collides with the timing bar, and a
+  genuinely sub-millisecond phase reads as "<1 ms" instead of a bare "0 ms".
+
+### Patch Changes
+
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+  - @checkstack/ai-backend@0.8.0
+  - @checkstack/ai-common@0.6.0
+  - @checkstack/automation-backend@0.9.3
+  - @checkstack/status-page-backend@0.3.0
+  - @checkstack/satellite-backend@0.7.0
+  - @checkstack/gitops-backend@0.5.12
+  - @checkstack/secrets-backend@0.2.12
+  - @checkstack/script-packages-backend@0.3.15
+  - @checkstack/backend-api@0.25.0
+  - @checkstack/notification-common@1.4.0
+  - @checkstack/healthcheck-common@1.8.0
+  - @checkstack/common@0.17.0
+  - @checkstack/incident-backend@1.8.3
+  - @checkstack/command-backend@0.2.12
+  - @checkstack/catalog-backend@1.5.3
+  - @checkstack/status-page-common@0.3.0
+  - @checkstack/catalog-common@2.4.2
+  - @checkstack/incident-common@1.6.2
+  - @checkstack/maintenance-common@1.7.2
+  - @checkstack/sdk@0.112.1
+  - @checkstack/cache-api@0.3.14
+  - @checkstack/gitops-common@0.6.5
+  - @checkstack/queue-api@0.3.14
+  - @checkstack/secrets-common@0.2.5
+  - @checkstack/signal-common@0.2.11
+  - @checkstack/cache-utils@0.2.19
+
 ## 1.9.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-backend",
-  "version": "1.9.2",
+  "version": "1.10.0",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.ts",
@@ -14,32 +14,32 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.24.1",
-    "@checkstack/ai-backend": "0.7.2",
-    "@checkstack/ai-common": "0.5.0",
-    "@checkstack/script-packages-backend": "0.3.14",
-    "@checkstack/cache-api": "0.3.13",
-    "@checkstack/cache-utils": "0.2.18",
-    "@checkstack/catalog-backend": "1.5.2",
-    "@checkstack/catalog-common": "2.4.1",
-    "@checkstack/command-backend": "0.2.11",
-    "@checkstack/common": "0.16.0",
-    "@checkstack/gitops-backend": "0.5.11",
-    "@checkstack/gitops-common": "0.6.4",
-    "@checkstack/healthcheck-common": "1.7.1",
-    "@checkstack/secrets-common": "0.2.4",
-    "@checkstack/secrets-backend": "0.2.11",
-    "@checkstack/incident-backend": "1.8.2",
-    "@checkstack/incident-common": "1.6.1",
-    "@checkstack/automation-backend": "0.9.2",
-    "@checkstack/maintenance-common": "1.7.1",
-    "@checkstack/notification-common": "1.3.4",
-    "@checkstack/queue-api": "0.3.13",
-    "@checkstack/satellite-backend": "0.6.15",
-    "@checkstack/sdk": "0.111.0",
-    "@checkstack/signal-common": "0.2.10",
-    "@checkstack/status-page-backend": "0.2.1",
-    "@checkstack/status-page-common": "0.2.0",
+    "@checkstack/backend-api": "0.25.0",
+    "@checkstack/ai-backend": "0.8.0",
+    "@checkstack/ai-common": "0.6.0",
+    "@checkstack/script-packages-backend": "0.3.15",
+    "@checkstack/cache-api": "0.3.14",
+    "@checkstack/cache-utils": "0.2.19",
+    "@checkstack/catalog-backend": "1.5.3",
+    "@checkstack/catalog-common": "2.4.2",
+    "@checkstack/command-backend": "0.2.12",
+    "@checkstack/common": "0.17.0",
+    "@checkstack/gitops-backend": "0.5.12",
+    "@checkstack/gitops-common": "0.6.5",
+    "@checkstack/healthcheck-common": "1.8.0",
+    "@checkstack/secrets-common": "0.2.5",
+    "@checkstack/secrets-backend": "0.2.12",
+    "@checkstack/incident-backend": "1.8.3",
+    "@checkstack/incident-common": "1.6.2",
+    "@checkstack/automation-backend": "0.9.3",
+    "@checkstack/maintenance-common": "1.7.2",
+    "@checkstack/notification-common": "1.4.0",
+    "@checkstack/queue-api": "0.3.14",
+    "@checkstack/satellite-backend": "0.7.0",
+    "@checkstack/sdk": "0.112.1",
+    "@checkstack/signal-common": "0.2.11",
+    "@checkstack/status-page-backend": "0.3.0",
+    "@checkstack/status-page-common": "0.3.0",
     "@hono/zod-validator": "^0.7.6",
     "drizzle-orm": "^0.45.0",
     "hono": "^4.12.25",
@@ -50,9 +50,9 @@
     "@orpc/server": "^1.14.4"
   },
   "devDependencies": {
-    "@checkstack/drizzle-helper": "0.0.5",
-    "@checkstack/scripts": "0.6.2",
-    "@checkstack/test-utils-backend": "0.1.45",
+    "@checkstack/drizzle-helper": "0.0.6",
+    "@checkstack/scripts": "0.6.3",
+    "@checkstack/test-utils-backend": "0.1.46",
     "@checkstack/tsconfig": "0.0.7",
     "@types/bun": "^1.0.0",
     "@types/tdigest": "^0.1.5",

package/src/ai/healthcheck-projection.test.ts

@@ -35,6 +35,42 @@ describe("healthcheck.status projection", () => {
   });
 });
 
+// The per-system projection is how the assistant maps a check to a system:
+// `healthcheck.status` lists every check globally with no system attribution, so
+// it must call this with a `systemId` (resolved via catalog.listSystems) to know
+// which checks are assigned to that system. Gated by the system-scoped
+// `configuration.read` rule, NOT the chat transport gate.
+describe("healthcheck.listSystemChecks projection", () => {
+  const tool = buildProjectedTool({
+    procedure: healthCheckContract.getSystemConfigurations,
+    sourcePluginMetadata: pluginMetadata,
+    procedureKey: "getSystemConfigurations",
+    name: "healthcheck.listSystemChecks",
+    description: "List the health checks assigned to a system. Read-only.",
+    effect: "read",
+    execute: deferredProjectionExecute,
+  });
+
+  test("uses the overridden tool name", () => {
+    expect(tool.name).toBe("healthcheck.listSystemChecks");
+  });
+
+  test("is classified as a read-only effect", () => {
+    expect(tool.effect).toBe("read");
+  });
+
+  test("exposes the systemId input to the model", () => {
+    const inputShape = tool.input as { shape?: Record<string, unknown> };
+    expect(inputShape.shape).toBeDefined();
+    expect(inputShape.shape?.["systemId"]).toBeDefined();
+  });
+
+  test("inherits the source procedure's access rules, not the chat gate", () => {
+    expect(tool.requiredAccessRules.length).toBeGreaterThan(0);
+    expect(tool.requiredAccessRules).not.toEqual(["ai.chat.read"]);
+  });
+});
+
 // The run-history projection lets the assistant answer timeline / root-cause
 // questions ("what issues did system X have between T1 and T2"). It must expose
 // the filter inputs (systemId, date window, statusFilter) and be gated by the

package/src/health-entity-id.test.ts

@@ -0,0 +1,73 @@
+import { describe, it, expect } from "bun:test";
+import {
+  HEALTH_ENTITY_ID_SEPARATOR,
+  encodeHealthEntityId,
+  parseHealthEntityId,
+} from "./health-entity-id";
+
+describe("encodeHealthEntityId", () => {
+  it("yields the bare system id when environmentId is undefined", () => {
+    expect(encodeHealthEntityId({ systemId: "sys-1" })).toBe("sys-1");
+  });
+
+  it("yields the bare system id when environmentId is null", () => {
+    expect(encodeHealthEntityId({ systemId: "sys-1", environmentId: null })).toBe(
+      "sys-1",
+    );
+  });
+
+  it("joins system and environment with the double-colon separator", () => {
+    expect(
+      encodeHealthEntityId({ systemId: "sys-1", environmentId: "prod" }),
+    ).toBe(`sys-1${HEALTH_ENTITY_ID_SEPARATOR}prod`);
+    expect(HEALTH_ENTITY_ID_SEPARATOR).toBe("::");
+  });
+
+  it("treats an empty-string environmentId as concrete (not a rollup)", () => {
+    // "" is neither null nor undefined, so it encodes as a per-env id.
+    expect(encodeHealthEntityId({ systemId: "sys-1", environmentId: "" })).toBe(
+      "sys-1::",
+    );
+  });
+});
+
+describe("parseHealthEntityId", () => {
+  it("decodes a bare id as the system rollup (environmentId null)", () => {
+    expect(parseHealthEntityId("sys-1")).toEqual({
+      systemId: "sys-1",
+      environmentId: null,
+    });
+  });
+
+  it("decodes a per-env id into system and environment", () => {
+    expect(parseHealthEntityId("sys-1::prod")).toEqual({
+      systemId: "sys-1",
+      environmentId: "prod",
+    });
+  });
+
+  it("splits on the FIRST separator so a later '::' stays in the env id", () => {
+    expect(parseHealthEntityId("sys-1::a::b")).toEqual({
+      systemId: "sys-1",
+      environmentId: "a::b",
+    });
+  });
+
+  it("yields an empty environmentId for a trailing separator", () => {
+    expect(parseHealthEntityId("sys-1::")).toEqual({
+      systemId: "sys-1",
+      environmentId: "",
+    });
+  });
+
+  it("round-trips an encoded per-env id", () => {
+    const encoded = encodeHealthEntityId({
+      systemId: "sys-9",
+      environmentId: "staging",
+    });
+    expect(parseHealthEntityId(encoded)).toEqual({
+      systemId: "sys-9",
+      environmentId: "staging",
+    });
+  });
+});

package/src/index.ts

@@ -314,6 +314,34 @@ export default createBackendPlugin({
           execute: deferredProjectionExecute,
         });
 
+        // The per-system ASSIGNMENT of checks: given a `systemId`, list the
+        // health checks assigned to that system (id, name, strategy, interval,
+        // collectors/assertions, paused state). This is the mapping
+        // `healthcheck.status` lacks - `getConfigurations` lists every check
+        // GLOBALLY with no system attribution, so from it alone the assistant
+        // cannot tell WHICH check monitors a given system (it would have to
+        // guess). The assistant resolves a system NAME to its id via
+        // catalog.listSystems, then calls this to attribute a named/failing
+        // check to the right system. Same system-scoped `configuration.read`
+        // gate as the dashboard's per-system configuration view.
+        env.getExtensionPoint(aiToolProjectionExtensionPoint).expose({
+          procedure: healthCheckContract.getSystemConfigurations,
+          sourcePluginMetadata: pluginMetadata,
+          procedureKey: "getSystemConfigurations",
+          name: "healthcheck.listSystemChecks",
+          description:
+            "List the health checks ASSIGNED to a specific system, given its " +
+            "`systemId` (resolve a system NAME to its id with " +
+            "catalog.listSystems first). Returns each assigned check's id, " +
+            "name, strategy, interval, collectors/assertions, and paused " +
+            "state. Use this to answer 'which checks monitor system X' or to " +
+            "attribute a specific or failing check to a system - " +
+            "healthcheck.status lists ALL checks globally WITHOUT the " +
+            "system mapping. Read-only.",
+          effect: "read",
+          execute: deferredProjectionExecute,
+        });
+
         // Historical run-by-run check results, filterable by system, time
         // window, and status. Complements `healthcheck.status` (which is only
         // CURRENT state): this is how the assistant answers "what issues did

package/src/queue-executor.ts

@@ -8,10 +8,12 @@ import {
   type BaseStrategyConfig,
   type ConnectedClient,
   type TransportClient,
+  type TransportTimings,
   type CollectorRunContext,
   type AdvisoryLockService,
   renderTemplatableConfig,
 } from "@checkstack/backend-api";
+import type { RunTimings } from "@checkstack/healthcheck-common";
 import { QueueManager } from "@checkstack/queue-api";
 import {
   healthCheckConfigurations,
@@ -91,6 +93,39 @@ function toHealthEntityView(state: AggregatedHealth): HealthEntityState {
   };
 }
 
+/** The known transport timing phase keys, in transport order. */
+const RUN_TIMING_KEYS = [
+  "dnsMs",
+  "connectMs",
+  "tlsMs",
+  "waitMs",
+  "transferMs",
+  "processingMs",
+] as const;
+
+/**
+ * Build the run's `metadata.timings` from a connected client's surfaced
+ * transport timings, keeping only present, finite, non-negative phases. Returns
+ * `undefined` when no usable phase was measured so the field is omitted (old
+ * runs and single-phase strategies stay on the coarse fallback in the UI).
+ */
+function extractRunTimings(
+  connectedClient: ConnectedClient<TransportClient<never, unknown>> | undefined,
+): RunTimings | undefined {
+  const raw: TransportTimings | undefined = connectedClient?.timings;
+  if (!raw) return undefined;
+  const result: RunTimings = {};
+  let any = false;
+  for (const key of RUN_TIMING_KEYS) {
+    const value = raw[key];
+    if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
+      result[key] = value;
+      any = true;
+    }
+  }
+  return any ? result : undefined;
+}
+
 /**
  * Emit the checkCompleted hook if available, plus the narrower
  * `checkFailed` hook when the result wasn't `healthy` (so operators
@@ -1003,6 +1038,12 @@ async function executeHealthCheckJob(props: {
     const status = hasCollectorError ? "unhealthy" : "healthy";
     const totalLatencyMs = Math.round(performance.now() - start);
 
+    // Lift the strategy's structured transport timings (DNS / connect / TLS /
+    // wait / transfer / processing) into the run metadata when the connected
+    // client surfaced any. Strategies that cannot measure sub-phases leave this
+    // undefined and the frontend falls back to the coarse connection split.
+    const timings = extractRunTimings(connectedClient);
+
     const result = {
       status: status as "healthy" | "unhealthy",
       latencyMs: totalLatencyMs,
@@ -1012,6 +1053,7 @@ async function executeHealthCheckJob(props: {
       metadata: {
         connected: true,
         connectionTimeMs,
+        ...(timings ? { timings } : {}),
         collectors: collectorResults,
       },
     };