@checkstack/healthcheck-http-backend 0.3.23 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,70 @@
 # @checkstack/healthcheck-http-backend
 
+## 0.4.0
+
+### Minor Changes
+
+- 9dcc848: Harden config-versioning so stored configs always migrate-then-validate and broken migration chains fail fast at boot.
+
+  - `@checkstack/backend-api` `Versioned<T>` gains `parseAssumingV1` (migrate-from-v1 then validate leniently, runtime path), `parseStrictAssumingV1` (migrate then validate strictly, editor path), and `validateMigrationChainFromV1()`. A standalone pure helper `assertMigrationChainFromV1({ version, migrations })` is the single shared implementation behind the constructor guard and `validateMigrationChainFromV1`.
+  - `Versioned` now validates its own v1 -> `version` chain in the constructor, which runs at module import / plugin registration. A new `no-restricted-syntax` ESLint rule bans calling `parse` / `safeParse` / `parseAsync` / `strict` directly on a `Versioned`'s `.schema` member.
+  - Auth strategy migration chains are validated at the `betterAuthExtensionPoint.addStrategy` chokepoint (`@checkstack/auth-backend`).
+  - Automation action AND trigger configs migrate-then-validate (lenient at dispatch, strict in the editor validator, recursing into `choose`/`parallel`/`repeat`/`sequence` blocks). The `run_script` / `run_shell` action configs bump to `version: 2` dropping the removed `sandbox` key, fixing the editor's `Unrecognized key: sandbox` error.
+  - Anomaly read path now validates: `getAnomalyConfig` / `getAnomalyAssignmentConfig` run stored records through `Versioned.parseRecord`; `PartialAnomalySettingsSchema` moved to `@checkstack/anomaly-common`. Notification ConfigService reads thread the migrations argument, and per-strategy `userConfig` is migrate-then-validated before `send()`.
+  - gitops-apply migrate-then-validates authored health-check config; integration connection validation routes through `safeValidate`. The latent HTTP health-check `result` schema (at `version: 3` with no migrations) now ships a pass-through v1 -> v2 -> v3 chain.
+
+  BREAKING CHANGES (fail-fast at boot, intended):
+
+  - Any `Versioned` config with `version > 1` and an incomplete or non-contiguous migration chain now throws at construction (boot) instead of failing lazily on first read. This covers every `Versioned` instance repo-wide, including future plugin types. Out-of-tree plugins shipping such a config must add the missing migration step(s); all in-repo strategies already have complete chains.
+  - An auth strategy declaring `configVersion > 1` without a complete chain throws at registration.
+  - A trigger's per-automation config is now a versioned `config: Versioned<TConfig>` instead of a bare `configSchema?`. Plugins registering triggers with `configSchema:` must wrap it: `config: new Versioned({ version: 1, schema })`. The underlying schema stays reachable via `config.schema`; triggers without per-automation config are unaffected.
+
+  State and scale: all affected reads resolve from shared Postgres / in-process registries, so every pod sees the same migrated answer. No new framework-owned current-state store.
+
+  This is a beta minor.
+
+- 9dcc848: Add environments as a first-class catalog primitive, with per-environment health-check fan-out, config templating, per-environment reactive health, and script run-context exposure.
+
+  - Catalog primitive: an environment is a sibling of groups - a named, instance-global record carrying free-form custom fields (baseUrl, region, tier, ...) that any system can belong to many-to-many. New `environments` + `systems_environments` tables, `EnvironmentSchema` + create/update schemas, `EntityService` environment CRUD and membership joins, RPC endpoints gated by a new `catalogAccess.environment` access rule, a GitOps `Environment` kind + `System.environments` extension, and frontend management (an `EnvironmentEditor`, an Environments management panel, and a per-system environment picker). The Environments card's Add/Edit/Delete affordances are gated on `catalogAccess.environment.manage`.
+  - Per-environment fan-out: run identity becomes `(systemId, configurationId, environmentId)`. Runs, aggregates, and state transitions gain a nullable `environmentId`. The health-check assignment gains an `environmentIds` selector with three modes (All / Specific / None; `null` and `[]` are distinct). The queue executor resolves the effective environment set via the catalog `resolveSystemEnvironments` read and executes one isolated run per environment.
+  - Config templating: a new `x-templatable` config-field marker renders a string field through the template engine at execute time, against `{ environment, check, system }`. A shared `renderTemplatableConfig` and a `renderTemplatePreview` helper (re-exported from `@checkstack/template-engine`) keep editor previews identical to the run-time render. The HTTP collector's `url`, `headers[].value`, and `body` are templatable, rendered per environment (the strategy client build moves inside the per-env loop); the `url`'s `.url()` validation moves post-render. Secrets resolve before templating; a field marked both secret and `x-templatable` is rejected at plugin load. `DynamicForm` shows a live "Preview" line, and the catalog `EnvironmentPreviewPicker` ("Preview as: <environment>") drives it in the collector editor (only when the schema has a templatable field).
+  - Script run-context: `CollectorRunContext` gains an optional `environment` field (`{ id, name, fields }`, metadata only). Shell collectors receive `CHECKSTACK_ENV_ID` / `_NAME` / `CHECKSTACK_ENV_<FIELD>` vars; inline TS collectors read `globalThis.context.environment`; the editor test panel mirrors both. The env-less path is unchanged.
+  - Per-environment reactive health (see BREAKING below), env-keyed read/write paths, env-qualified serialization locks, an optional `trigger.payload.environmentId`, per-environment isolation, and an `ENVIRONMENT_RESOLUTION_FAILED` signal when catalog resolution degrades to a single env-less run.
+
+  BREAKING CHANGES: the reactive `health` entity's id-shape and cardinality change. It now encodes two views: per-environment (id `"<systemId>::<environmentId>"`) and a system rollup (id `"<systemId>"`, the worst status across environments + env-less runs). The rollup PRESERVES the pre-existing system-level contract - dashboards, status badges, and automations referencing health by `systemId` keep working without re-authoring - but the entity's contract surface changed (new id-shape, higher cardinality, new payload field), so it is flagged breaking. `getBulkHealthState` parses env-qualified ids and keys results by the original id.
+
+  State and scale: membership and custom fields live only in catalog Postgres and are re-read every tick via the cross-plugin RPC; env-keyed health reads from shared `health_check_runs` / aggregates / transitions (compute-on-read). Every pod resolves the same effective set and the same per-environment health. No pod-local environment state.
+
+  Also: `unwrapSchema` in `zod-config.ts` loops instead of single-pass-stripping so multi-layer wrappers (`.optional().default()`) still resolve `x-templatable` meta. The env-less `{{ environment.* }}` run notice logs at `debug` (a legitimate recurring configuration), while the post-render HTTP `.url()` check still fails a genuinely-broken empty render with a clear "Rendered URL is invalid" error.
+
+  This is a beta minor.
+
+- 9dcc848: Health-check strategy and collector configs now migrate-then-validate when loaded, instead of being cast/rendered raw.
+
+  These configs declared `version: 2`/`3` migrations but the load path never ran them: stored values are persisted UNVERSIONED, and the executor cast them straight to the strategy/collector type. Both the execution path (`queue-executor`) and the read API (`mapConfig`, feeding router / frontend / gitops `getConfiguration`) now use assume-v1-on-read (`Versioned.parseAssumingV1`): wrap as version 1, run the declared chain, then validate. Order is preserved: migrate -> secret resolve -> template render -> execute. An unregistered strategy/collector or a failed migrate falls back to the raw stored blob rather than dropping the configuration. Every reshaper migration is now IDEMPOTENT, guarding on its legacy discriminator so already-current data passes through untouched.
+
+  BREAKING CHANGE: for any config GENUINELY at version 1 in the database (e.g. an HTTP strategy still carrying `url`/`method`, or an execute collector still carrying `command`/`args`), the declared migrations now actually RUN on load, so the loaded/returned shape changes for such rows. This is the intended fix - those fields were already supposed to have been migrated away. Configs already at the current shape are unaffected. No data backfill is performed; migration is applied on every read.
+
+  This is a beta minor.
+
+### Patch Changes
+
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+  - @checkstack/backend-api@0.21.0
+  - @checkstack/healthcheck-common@1.5.0
+  - @checkstack/common@0.13.0
+
 ## 0.3.23
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-http-backend",
-  "version": "0.3.23",
+  "version": "0.4.0",
   "type": "module",
   "main": "src/index.ts",
   "checkstack": {
@@ -14,8 +14,8 @@
     "pack": "bunx @checkstack/scripts plugin-pack"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.18.0",
-    "@checkstack/healthcheck-common": "1.3.0",
+    "@checkstack/backend-api": "0.20.0",
+    "@checkstack/healthcheck-common": "1.4.0",
     "jsonpath-plus": "^10.3.0",
     "@checkstack/common": "0.12.0"
   },

package/src/migration-chain-contract.test.ts

@@ -0,0 +1,43 @@
+/**
+ * Contract test: every HTTP health-check Versioned schema that is stored
+ * UNVERSIONED and read back via assume-v1-on-read MUST have a COMPLETE,
+ * contiguous migration chain from version 1 to its current `version`.
+ *
+ * This is a pure STRUCTURAL check on the `Versioned.migrations` array
+ * (`validateMigrationChainFromV1` — no `migrate()` is run), so it carries
+ * zero per-config upkeep: the day someone bumps a schema's `version` without
+ * shipping a covering migration, `parseAssumingV1` would silently fail at
+ * runtime on a genuinely-v1 stored blob — this test turns that into a CI
+ * failure instead. It enumerates every Versioned field (config + result +
+ * aggregatedResult) of the strategy + collectors this plugin registers, so a
+ * new collector or a bumped result schema is covered automatically.
+ */
+import { describe, expect, it } from "bun:test";
+import { HttpHealthCheckStrategy } from "./strategy";
+import { RequestCollector } from "./request-collector";
+
+describe("http health-check migration-chain contract", () => {
+  const strategy = new HttpHealthCheckStrategy();
+  const collector = new RequestCollector();
+  const configs = [
+    { name: "http strategy config", config: strategy.config },
+    { name: "http strategy result", config: strategy.result },
+    { name: "http strategy aggregatedResult", config: strategy.aggregatedResult },
+    { name: "request collector config", config: collector.config },
+    { name: "request collector result", config: collector.result },
+    {
+      name: "request collector aggregatedResult",
+      config: collector.aggregatedResult,
+    },
+  ];
+
+  it("every registered Versioned schema has a complete v1->version chain", () => {
+    for (const { name, config } of configs) {
+      const problem = config.validateMigrationChainFromV1();
+      expect(
+        problem,
+        `${name} (version ${config.version}) has a broken migration chain: ${problem}`,
+      ).toBeUndefined();
+    }
+  });
+});

package/src/request-collector.test.ts

@@ -93,6 +93,26 @@ describe("RequestCollector", () => {
       );
     });
 
+    it("returns a clear config error when the rendered URL is invalid", async () => {
+      // The executor renders `{{ environment.* }}` into `config.url` before
+      // execute. An empty environment can produce a non-URL (e.g. "/healthz"
+      // when baseUrl is missing). The collector must surface this as a clear
+      // config error, not attempt the request.
+      const collector = new RequestCollector();
+      const client = createMockClient();
+
+      const result = await collector.execute({
+        config: { url: "/healthz", method: "GET", timeout: 5000 },
+        client,
+        pluginId: "test",
+      });
+
+      expect(result.result.success).toBe(false);
+      expect(result.result.statusCode).toBe(0);
+      expect(result.error).toContain("Rendered URL is invalid");
+      expect(client.exec).not.toHaveBeenCalled();
+    });
+
     it("should pass body to client", async () => {
       const collector = new RequestCollector();
       const client = createMockClient();

package/src/request-collector.ts

@@ -27,20 +27,34 @@ import type { HttpTransportClient } from "./transport-client";
 // ============================================================================
 
 const requestConfigSchema = z.object({
-  url: z.string().url().describe("Full URL to request"),
+  // Templatable: supports `{{ environment.baseUrl }}` etc. so one config
+  // covers N environments. The `.url()` validation moves to POST-RENDER (see
+  // `execute`) because the stored value `{{ environment.baseUrl }}/healthz` is
+  // not itself a valid URL.
+  url: configString({ "x-templatable": true }).describe(
+    "Full URL to request. Supports templating, e.g. {{ environment.baseUrl }}/healthz",
+  ),
   method: z
     .enum(["GET", "POST", "PUT", "DELETE", "HEAD"])
     .default("GET")
     .describe("HTTP method"),
   headers: z
-    .array(z.object({ name: z.string(), value: z.string() }))
+    .array(
+      z.object({
+        name: z.string(),
+        // Templatable: header values are a natural per-env case (auth hosts,
+        // tenant ids). `name` stays literal.
+        value: configString({ "x-templatable": true }),
+      }),
+    )
     .optional()
     .describe("Request headers"),
   body: configString({
     "x-editor-types": ["none", "raw", "json", "yaml", "xml", "formdata"],
+    "x-templatable": true,
   })
     .optional()
-    .describe("Request body"),
+    .describe("Request body. Supports templating, e.g. {{ environment.* }}"),
   timeout: z
     .number()
     .min(100)
@@ -48,6 +62,15 @@ const requestConfigSchema = z.object({
     .describe("Timeout in milliseconds"),
 });
 
+/**
+ * Post-render validator for the HTTP `url`. The stored value is a plain
+ * templatable string (no `.url()`); the executor renders `{{ environment.* }}`
+ * per environment, then this re-validates the CONCRETE rendered URL. A bad
+ * render (e.g. an empty environment yielding `/healthz`) surfaces as a clear
+ * config error instead of a silent pass.
+ */
+const renderedUrlSchema = z.string().url();
+
 export type RequestConfig = z.infer<typeof requestConfigSchema>;
 
 // ============================================================================
@@ -156,6 +179,26 @@ export class RequestCollector implements CollectorStrategy<
   }): Promise<CollectorResult<RequestResult>> {
     const startTime = Date.now();
 
+    // Post-render validation: the stored `url` is a plain templatable string,
+    // so `.url()` cannot run at store time. The executor has already rendered
+    // `{{ environment.* }}` into `config.url` by the time we get here; validate
+    // the CONCRETE rendered value now. A bad render (e.g. an empty environment)
+    // yields a clear config error rather than a confusing fetch failure.
+    const urlValidation = renderedUrlSchema.safeParse(config.url);
+    if (!urlValidation.success) {
+      return {
+        result: {
+          statusCode: 0,
+          statusText: "Invalid URL",
+          responseTimeMs: Date.now() - startTime,
+          body: "",
+          bodyLength: 0,
+          success: false,
+        },
+        error: `Rendered URL is invalid: ${JSON.stringify(config.url)}`,
+      };
+    }
+
     // Convert headers array to record
     const headers: Record<string, string> = {};
     for (const h of config.headers ?? []) {

package/src/strategy.test.ts

@@ -8,6 +8,37 @@ describe("HttpHealthCheckStrategy", () => {
     spyOn(globalThis, "fetch").mockRestore();
   });
 
+  describe("config migration (assume-v1-on-read)", () => {
+    it("migrates a genuine v1 blob (url/method/...) down to {timeout}", async () => {
+      const migrated = await strategy.config.parseAssumingV1({
+        url: "https://example.com",
+        method: "GET",
+        headers: [{ name: "Accept", value: "application/json" }],
+        body: "payload",
+      });
+      // v1->v2 fabricates the default timeout, v2->v3 strips the moved fields.
+      expect(migrated).toEqual({ timeout: 30_000 });
+    });
+
+    it("carries a v1 timeout through both migration steps", async () => {
+      const migrated = await strategy.config.parseAssumingV1({
+        url: "https://example.com",
+        method: "POST",
+        timeout: 12_345,
+      });
+      expect(migrated).toEqual({ timeout: 12_345 });
+    });
+
+    it("is idempotent: an already-current {timeout} blob is unchanged", async () => {
+      const migrated = await strategy.config.parseAssumingV1({ timeout: 5000 });
+      expect(migrated).toEqual({ timeout: 5000 });
+    });
+
+    it("has a complete v1->version migration chain", () => {
+      expect(strategy.config.validateMigrationChainFromV1()).toBeUndefined();
+    });
+  });
+
   describe("createClient", () => {
     it("should return a connected client", async () => {
       const connectedClient = await strategy.createClient({ timeout: 5000 });

package/src/strategy.ts

@@ -33,16 +33,19 @@ export const httpHealthCheckConfigSchema = baseStrategyConfigSchema.extend({});
 
 export type HttpHealthCheckConfig = z.infer<typeof httpHealthCheckConfigSchema>;
 
-// Legacy config types for migrations
-interface HttpConfigV1 {
-  url: string;
-  method: "GET" | "POST" | "PUT" | "DELETE" | "HEAD";
-  headers?: { name: string; value: string }[];
-  body?: string;
+// The migrate input is `unknown` per the versioning chain, so narrowing is
+// done with `typeof`/`in` guards (no casts).
+
+/** Type guard: the migrate input is a plain object whose keys can be probed. */
+function isRecord(data: unknown): data is Record<string, unknown> {
+  return typeof data === "object" && data !== null;
 }
 
-interface HttpConfigV2 extends HttpConfigV1 {
-  timeout: number;
+/** Read a numeric `timeout` field from a legacy/current config blob. */
+function readTimeout(data: unknown): number | undefined {
+  if (!isRecord(data)) return undefined;
+  const value = data.timeout;
+  return typeof value === "number" ? value : undefined;
 }
 
 /** Per-run result metadata */
@@ -91,19 +94,34 @@ export class HttpHealthCheckStrategy implements HealthCheckStrategy<
         fromVersion: 1,
         toVersion: 2,
         description: "Add timeout field",
-        migrate: (data: HttpConfigV1): HttpConfigV2 => ({
-          ...data,
-          timeout: 30_000,
-        }),
+        // IDEMPOTENT: only a genuine v1 blob carries url/method. If neither is
+        // present the data is already v2+ — pass it through untouched.
+        migrate: (data: unknown): unknown => {
+          if (isRecord(data) && ("url" in data || "method" in data)) {
+            return { ...data, timeout: readTimeout(data) ?? 30_000 };
+          }
+          return data;
+        },
       },
       {
         fromVersion: 2,
         toVersion: 3,
         description:
           "Remove url/method/headers/body (moved to RequestCollector)",
-        migrate: (data: HttpConfigV2): HttpHealthCheckConfig => ({
-          timeout: data.timeout,
-        }),
+        // IDEMPOTENT: only a genuine v2 blob still carries the moved fields. An
+        // already-v3 blob (just `{ timeout }`) passes through untouched.
+        migrate: (data: unknown): unknown => {
+          if (
+            isRecord(data) &&
+            ("url" in data ||
+              "method" in data ||
+              "headers" in data ||
+              "body" in data)
+          ) {
+            return { timeout: readTimeout(data) };
+          }
+          return data;
+        },
       },
     ],
   });
@@ -111,6 +129,25 @@ export class HttpHealthCheckStrategy implements HealthCheckStrategy<
   result: Versioned<HttpResultMetadata> = new Versioned({
     version: 3,
     schema: httpResultMetadataSchema,
+    // The result version tracks the strategy version (bumped in lockstep
+    // with the createClient refactor); the result SHAPE never changed, so
+    // these are pass-through migrations. They are required for a COMPLETE
+    // v1->v3 chain (enforced at construction) so a genuinely-v1 stored
+    // result still reads back via assume-v1-on-read.
+    migrations: [
+      {
+        fromVersion: 1,
+        toVersion: 2,
+        description: "Migrate to createClient pattern (no result changes)",
+        migrate: (data: unknown) => data,
+      },
+      {
+        fromVersion: 2,
+        toVersion: 3,
+        description: "Move request params to RequestCollector (no result changes)",
+        migrate: (data: unknown) => data,
+      },
+    ],
   });
 
   aggregatedResult = new VersionedAggregated({