@checkstack/healthcheck-backend 1.5.0 → 1.6.0

package/src/state-transitions.ts

@@ -1,4 +1,4 @@
-import { and, desc, eq, gte, sql } from "drizzle-orm";
+import { and, desc, eq, gte, isNull, sql } from "drizzle-orm";
 import type { HealthCheckStatus } from "@checkstack/healthcheck-common";
 import type { SafeDatabase } from "@checkstack/backend-api";
 import { healthCheckStateTransitions } from "./schema";
@@ -16,6 +16,7 @@ export async function recordStateTransition({
   db,
   systemId,
   configurationId,
+  environmentId,
   fromStatus,
   toStatus,
   now = new Date(),
@@ -23,6 +24,12 @@ export async function recordStateTransition({
   db: Db;
   systemId: string;
   configurationId: string;
+  /**
+   * Environment this transition belongs to (per-environment fan-out).
+   * null/undefined = env-less run. Kept distinct so "in status since" is
+   * env-scoped.
+   */
+  environmentId?: string | null;
   fromStatus: HealthCheckStatus | undefined;
   toStatus: HealthCheckStatus;
   now?: Date;
@@ -30,6 +37,7 @@ export async function recordStateTransition({
   await db.insert(healthCheckStateTransitions).values({
     systemId,
     configurationId,
+    environmentId: environmentId ?? null,
     fromStatus: fromStatus ?? null,
     toStatus,
     transitionedAt: now,
@@ -49,11 +57,27 @@ export async function findInStatusSince({
   db,
   systemId,
   status,
+  environmentId,
 }: {
   db: Db;
   systemId: string;
   status: HealthCheckStatus;
+  /**
+   * Environment to scope the lookup to (Phase 3b). `undefined` = system-wide
+   * (rollup; any environment + env-less). `null` = the env-less slice only. A
+   * string = that environment's transitions only. The lookup index leads with
+   * (system_id, environment_id, to_status, transitioned_at) so the env-scoped
+   * query is index-efficient.
+   */
+  environmentId?: string | null;
 }): Promise<Date | null> {
+  const envFilter =
+    environmentId === undefined
+      ? undefined
+      : environmentId === null
+        ? isNull(healthCheckStateTransitions.environmentId)
+        : eq(healthCheckStateTransitions.environmentId, environmentId);
+
   const [row] = await db
     .select({ transitionedAt: healthCheckStateTransitions.transitionedAt })
     .from(healthCheckStateTransitions)
@@ -61,6 +85,7 @@ export async function findInStatusSince({
       and(
         eq(healthCheckStateTransitions.systemId, systemId),
         eq(healthCheckStateTransitions.toStatus, status),
+        ...(envFilter ? [envFilter] : []),
       ),
     )
     .orderBy(desc(healthCheckStateTransitions.transitionedAt))
@@ -86,12 +111,18 @@ export async function countStateTransitionsInWindow({
   systemId,
   windowMinutes,
   toStatus,
+  environmentId,
   now = new Date(),
 }: {
   db: Db;
   systemId: string;
   windowMinutes: number;
   toStatus?: HealthCheckStatus;
+  /**
+   * Environment to scope the count to (Phase 3b). `undefined` = system-wide
+   * (rollup). `null` = env-less slice only. A string = that environment only.
+   */
+  environmentId?: string | null;
   now?: Date;
 }): Promise<number> {
   const windowStart = new Date(now.getTime() - windowMinutes * 60_000);
@@ -102,6 +133,13 @@ export async function countStateTransitionsInWindow({
   if (toStatus) {
     conditions.push(eq(healthCheckStateTransitions.toStatus, toStatus));
   }
+  if (environmentId !== undefined) {
+    conditions.push(
+      environmentId === null
+        ? isNull(healthCheckStateTransitions.environmentId)
+        : eq(healthCheckStateTransitions.environmentId, environmentId),
+    );
+  }
 
   const [row] = await db
     .select({ count: sql<number>`COUNT(*)::int` })

package/src/validate-configuration.test.ts

@@ -0,0 +1,205 @@
+import { describe, it, expect } from "bun:test";
+import { z } from "zod";
+import { Versioned } from "@checkstack/backend-api";
+import type {
+  HealthCheckRegistry,
+  CollectorRegistry,
+  RegisteredStrategy,
+  RegisteredCollector,
+} from "@checkstack/backend-api";
+import { collectConfigurationIssues } from "./validate-configuration";
+
+/**
+ * Build a minimal `Versioned` config wrapper from a single zod schema. The
+ * real registry wraps strategy/collector configs in a versioning chain; for
+ * validation we only exercise `parseStrictAssumingV1`, which for a v1-only
+ * chain is a strict parse of the supplied schema.
+ */
+function versionedFrom<T>(schema: z.ZodType<T>): Versioned<T> {
+  return new Versioned<T>({ version: 1, schema });
+}
+
+// A strategy config with a required, typed `url` field. The lightweight
+// "required-field present" check only looks at key presence, so a wrong TYPE
+// (number instead of string) or an unknown key slips past it — but the strict
+// migrate-then-validate path rejects both.
+const strategyConfigSchema = z.object({
+  url: z.string().url(),
+  timeout: z.number().int().min(1).default(5000),
+});
+
+const collectorConfigSchema = z.object({
+  path: z.string().min(1),
+});
+
+function makeRegistries(): {
+  registry: HealthCheckRegistry;
+  collectorRegistry: CollectorRegistry;
+} {
+  const strategy = {
+    id: "http",
+    displayName: "HTTP",
+    config: versionedFrom(strategyConfigSchema),
+    aggregatedResult: {} as RegisteredStrategy["strategy"]["aggregatedResult"],
+    createClient: async () => {
+      throw new Error("not used");
+    },
+    mergeResult: () => ({}),
+  } as unknown as RegisteredStrategy["strategy"];
+
+  const registeredStrategy: RegisteredStrategy = {
+    strategy,
+    ownerPluginId: "healthcheck-http",
+    qualifiedId: "healthcheck-http.http",
+  };
+
+  const collector = {
+    displayName: "File",
+    description: "reads a file",
+    config: versionedFrom(collectorConfigSchema),
+    result: { schema: z.object({}) },
+    supportedPlugins: [{ pluginId: "healthcheck-http" }],
+  } as unknown as RegisteredCollector["collector"];
+
+  const registeredCollector: RegisteredCollector = {
+    qualifiedId: "collector-file.file",
+    collector,
+    ownerPlugin: { pluginId: "collector-file" },
+  };
+
+  const registry: HealthCheckRegistry = {
+    register: () => {},
+    getStrategy: (id) =>
+      id === registeredStrategy.qualifiedId ? strategy : undefined,
+    getStrategies: () => [strategy],
+    getStrategiesWithMeta: () => [registeredStrategy],
+  };
+
+  const collectorRegistry: CollectorRegistry = {
+    register: () => {},
+    getCollector: (id) =>
+      id === registeredCollector.qualifiedId ? registeredCollector : undefined,
+    getCollectorsForPlugin: () => [registeredCollector],
+    getCollectors: () => [registeredCollector],
+  };
+
+  return { registry, collectorRegistry };
+}
+
+describe("collectConfigurationIssues", () => {
+  it("returns no issues for a fully valid configuration", async () => {
+    const { registry, collectorRegistry } = makeRegistries();
+    const issues = await collectConfigurationIssues({
+      input: {
+        name: "valid",
+        strategyId: "healthcheck-http.http",
+        config: { url: "https://example.test" },
+        intervalSeconds: 60,
+        collectors: [
+          {
+            id: "c1",
+            collectorId: "collector-file.file",
+            config: { path: "/tmp/x" },
+          },
+        ],
+      },
+      registry,
+      collectorRegistry,
+    });
+    expect(issues).toEqual([]);
+  });
+
+  it("rejects an unknown strategy id", async () => {
+    const { registry, collectorRegistry } = makeRegistries();
+    const issues = await collectConfigurationIssues({
+      input: {
+        name: "x",
+        strategyId: "healthcheck-http.nope",
+        config: { url: "https://example.test" },
+        intervalSeconds: 60,
+      },
+      registry,
+      collectorRegistry,
+    });
+    expect(issues.length).toBe(1);
+    expect(issues[0].path).toEqual(["strategyId"]);
+    expect(issues[0].message).toContain("Unknown");
+  });
+
+  it("rejects an unknown collector id", async () => {
+    const { registry, collectorRegistry } = makeRegistries();
+    const issues = await collectConfigurationIssues({
+      input: {
+        name: "x",
+        strategyId: "healthcheck-http.http",
+        config: { url: "https://example.test" },
+        intervalSeconds: 60,
+        collectors: [
+          { id: "c1", collectorId: "collector-file.ghost", config: {} },
+        ],
+      },
+      registry,
+      collectorRegistry,
+    });
+    expect(issues.length).toBe(1);
+    expect(issues[0].path).toEqual(["collectors", 0, "collectorId"]);
+  });
+
+  // The key deep-vs-lightweight test: `url` IS present (so the old
+  // required-field check passes) but holds the wrong TYPE. Only the strict
+  // migrate-then-validate path catches it.
+  it("rejects a deep field/type error the presence check would miss", async () => {
+    const { registry, collectorRegistry } = makeRegistries();
+    const issues = await collectConfigurationIssues({
+      input: {
+        name: "x",
+        strategyId: "healthcheck-http.http",
+        // `url` present but a number, not a URL string.
+        config: { url: 12345 },
+        intervalSeconds: 60,
+      },
+      registry,
+      collectorRegistry,
+    });
+    expect(issues.length).toBeGreaterThan(0);
+    expect(issues[0].path[0]).toBe("config");
+  });
+
+  // Strict parse also rejects unknown/typo'd keys, which a presence check
+  // (only asserting required keys EXIST) cannot.
+  it("rejects an unknown/typo'd strategy config key", async () => {
+    const { registry, collectorRegistry } = makeRegistries();
+    const issues = await collectConfigurationIssues({
+      input: {
+        name: "x",
+        strategyId: "healthcheck-http.http",
+        config: { url: "https://example.test", tiemout: 5 },
+        intervalSeconds: 60,
+      },
+      registry,
+      collectorRegistry,
+    });
+    expect(issues.length).toBeGreaterThan(0);
+    expect(issues[0].path[0]).toBe("config");
+  });
+
+  it("rejects a deep collector config error", async () => {
+    const { registry, collectorRegistry } = makeRegistries();
+    const issues = await collectConfigurationIssues({
+      input: {
+        name: "x",
+        strategyId: "healthcheck-http.http",
+        config: { url: "https://example.test" },
+        intervalSeconds: 60,
+        collectors: [
+          // `path` present but empty string -> violates min(1).
+          { id: "c1", collectorId: "collector-file.file", config: { path: "" } },
+        ],
+      },
+      registry,
+      collectorRegistry,
+    });
+    expect(issues.length).toBeGreaterThan(0);
+    expect(issues[0].path.slice(0, 2)).toEqual(["collectors", 0]);
+  });
+});

package/src/validate-configuration.ts

@@ -0,0 +1,159 @@
+/**
+ * Deep validation of a proposed health-check configuration.
+ *
+ * `CreateHealthCheckConfigurationSchema` only validates the structural shape -
+ * `config` and each collector `config` are typed as `z.record(z.unknown())`,
+ * so it never checks a value against the strategy's / collector's own schema.
+ * This module fills the gap with the SAME migrate-then-validate-strict logic
+ * the GitOps apply path uses (`parseStrictAssumingV1`), so propose-time errors
+ * match apply-time errors:
+ *
+ *   - unknown strategy / collector ids,
+ *   - strategy `config` that violates the strategy's versioned config schema
+ *     (wrong type, missing required field, AND - because validation is strict -
+ *     unknown/typo'd keys),
+ *   - each collector `config` that violates the collector's config schema.
+ *
+ * Returned issue `path`s are dot-joinable for display, e.g. `config.url` or
+ * `collectors.0.config.path`. This is the shared validator behind the
+ * `validateConfiguration` RPC; the GitOps reconcile path uses the same
+ * migrate-then-strict helper ({@link validateVersionedConfigStrict}) so the two
+ * code paths agree on what counts as valid.
+ */
+import { z } from "zod";
+import type { Versioned } from "@checkstack/backend-api";
+import type {
+  HealthCheckRegistry,
+  CollectorRegistry,
+} from "@checkstack/backend-api";
+import { extractErrorMessage } from "@checkstack/common";
+import type { ValidateConfigurationInput } from "@checkstack/healthcheck-common";
+
+export interface ConfigurationIssue {
+  path: Array<string | number>;
+  message: string;
+}
+
+/**
+ * Migrate (assuming the stored value was written at v1) then STRICT-parse a
+ * `Versioned` config. Returns the validated value on success, or the list of
+ * issues on failure. Migration errors (a broken chain or a throwing `migrate`)
+ * are reported as a single issue at `basePath` rather than thrown, so one bad
+ * config can't abort the whole validation. Shared by the `validateConfiguration`
+ * RPC and the GitOps reconcile path.
+ */
+export async function validateVersionedConfigStrict({
+  config,
+  value,
+  basePath,
+}: {
+  config: Versioned<unknown>;
+  value: unknown;
+  basePath: Array<string | number>;
+}): Promise<
+  { ok: true; value: unknown } | { ok: false; issues: ConfigurationIssue[] }
+> {
+  try {
+    const validated = await config.parseStrictAssumingV1(value);
+    return { ok: true, value: validated };
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      return {
+        ok: false,
+        issues: error.issues.map((issue) => ({
+          path: [
+            ...basePath,
+            ...issue.path.map((segment) => toPathSegment(segment)),
+          ],
+          message: issue.message,
+        })),
+      };
+    }
+    return {
+      ok: false,
+      issues: [{ path: basePath, message: extractErrorMessage(error) }],
+    };
+  }
+}
+
+/**
+ * Deep-validate a proposed configuration against the live registries WITHOUT
+ * persisting anything. Returns an empty array when the configuration is fully
+ * valid. Strategy/collector lookup is by fully-qualified id, matching the
+ * GitOps reconcile path and the create path's stored `strategyId`.
+ */
+export async function collectConfigurationIssues({
+  input,
+  registry,
+  collectorRegistry,
+}: {
+  input: ValidateConfigurationInput;
+  registry: HealthCheckRegistry;
+  collectorRegistry: CollectorRegistry;
+}): Promise<ConfigurationIssue[]> {
+  const issues: ConfigurationIssue[] = [];
+
+  // ── Strategy resolution ──────────────────────────────────────────────────
+  const allStrategies = registry.getStrategiesWithMeta();
+  const matchedStrategy = allStrategies.find(
+    (s) => s.qualifiedId === input.strategyId,
+  );
+  if (!matchedStrategy) {
+    const known = allStrategies.map((s) => s.qualifiedId).join(", ");
+    issues.push({
+      path: ["strategyId"],
+      message: `Unknown health-check strategy "${input.strategyId}". Available: ${known || "(none)"}.`,
+    });
+    // No strategy means the config can't be schema-validated; surface the
+    // strategy issue alone so the operator fixes that first.
+    return issues;
+  }
+
+  // ── Strategy config (migrate-then-validate-strict) ───────────────────────
+  const strategyResult = await validateVersionedConfigStrict({
+    config: matchedStrategy.strategy.config,
+    value: input.config,
+    basePath: ["config"],
+  });
+  if (!strategyResult.ok) {
+    issues.push(...strategyResult.issues);
+  }
+
+  // ── Collector resolution + config (migrate-then-validate-strict) ─────────
+  const allCollectors = collectorRegistry.getCollectors();
+  for (const [index, entry] of (input.collectors ?? []).entries()) {
+    const matchedCollector = allCollectors.find(
+      (c) => c.qualifiedId === entry.collectorId,
+    );
+    if (!matchedCollector) {
+      const known = allCollectors.map((c) => c.qualifiedId).join(", ");
+      issues.push({
+        path: ["collectors", index, "collectorId"],
+        message: `Unknown collector "${entry.collectorId}". Available: ${known || "(none)"}.`,
+      });
+      continue;
+    }
+
+    const collectorResult = await validateVersionedConfigStrict({
+      config: matchedCollector.collector.config,
+      value: entry.config,
+      basePath: ["collectors", index, "config"],
+    });
+    if (!collectorResult.ok) {
+      issues.push(...collectorResult.issues);
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * Zod issue paths are `PropertyKey[]` (string | number | symbol). The contract
+ * issue path is `(string | number)[]`, so coerce the rare symbol segment to its
+ * string form.
+ */
+function toPathSegment(segment: PropertyKey): string | number {
+  return typeof segment === "number" || typeof segment === "string"
+    ? segment
+    : String(segment);
+}

package/tsconfig.json

@@ -4,6 +4,12 @@
     "src"
   ],
   "references": [
+    {
+      "path": "../ai-backend"
+    },
+    {
+      "path": "../ai-common"
+    },
     {
       "path": "../automation-backend"
     },
@@ -61,6 +67,9 @@
     {
       "path": "../script-packages-backend"
     },
+    {
+      "path": "../sdk"
+    },
     {
       "path": "../secrets-backend"
     },