@checkstack/healthcheck-tcp-backend 0.2.23 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @checkstack/healthcheck-tcp-backend
 
+## 0.3.0
+
+### Minor Changes
+
+- 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.2.23
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-tcp-backend",
-  "version": "0.2.23",
+  "version": "0.3.0",
   "type": "module",
   "main": "src/index.ts",
   "checkstack": {
@@ -14,9 +14,9 @@
     "pack": "bunx @checkstack/scripts plugin-pack"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.18.0",
+    "@checkstack/backend-api": "0.20.0",
     "@checkstack/common": "0.12.0",
-    "@checkstack/healthcheck-common": "1.3.0"
+    "@checkstack/healthcheck-common": "1.4.0"
   },
   "devDependencies": {
     "@types/bun": "^1.0.0",

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

@@ -0,0 +1,38 @@
+/**
+ * Contract test: every TCP health-check Versioned schema stored UNVERSIONED
+ * and read back via assume-v1-on-read MUST have a COMPLETE, contiguous
+ * migration chain from version 1 to its current `version`. Pure STRUCTURAL
+ * check (`validateMigrationChainFromV1`); enumerates every Versioned field
+ * (config + result + aggregatedResult) of this plugin's strategy + collectors
+ * so a new collector or a bumped result schema is covered automatically. See
+ * the HTTP plugin's equivalent test for the full rationale.
+ */
+import { describe, expect, it } from "bun:test";
+import { TcpHealthCheckStrategy } from "./strategy";
+import { BannerCollector } from "./banner-collector";
+
+describe("tcp health-check migration-chain contract", () => {
+  const strategy = new TcpHealthCheckStrategy();
+  const collector = new BannerCollector();
+  const configs = [
+    { name: "tcp strategy config", config: strategy.config },
+    { name: "tcp strategy result", config: strategy.result },
+    { name: "tcp strategy aggregatedResult", config: strategy.aggregatedResult },
+    { name: "banner collector config", config: collector.config },
+    { name: "banner collector result", config: collector.result },
+    {
+      name: "banner 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/strategy.test.ts

@@ -161,4 +161,42 @@ describe("TcpHealthCheckStrategy", () => {
       expect(aggregated.errorCount.count).toBe(1);
     });
   });
+
+  describe("config migration (assume-v1-on-read)", () => {
+    const strategy = new TcpHealthCheckStrategy();
+
+    it("migrates a genuine v1 blob (readBanner present) to {host, port, timeout}", async () => {
+      const migrated = await strategy.config.parseAssumingV1({
+        host: "example.com",
+        port: 443,
+        timeout: 5000,
+        readBanner: true,
+      });
+      expect(migrated).toEqual({ host: "example.com", port: 443, timeout: 5000 });
+    });
+
+    it("is idempotent: an already-current {host, port, timeout} blob is unchanged", async () => {
+      const migrated = await strategy.config.parseAssumingV1({
+        host: "db.internal",
+        port: 5432,
+        timeout: 3000,
+      });
+      expect(migrated).toEqual({ host: "db.internal", port: 5432, timeout: 3000 });
+    });
+
+    it("passes through a v1 row that omitted readBanner (already v2-shaped)", async () => {
+      // A v1 config that never carried readBanner already matches the v2 shape,
+      // so the guard correctly treats it as a no-op passthrough.
+      const migrated = await strategy.config.parseAssumingV1({
+        host: "host.local",
+        port: 22,
+        timeout: 2000,
+      });
+      expect(migrated).toEqual({ host: "host.local", port: 22, timeout: 2000 });
+    });
+
+    it("has a complete v1->version migration chain", () => {
+      expect(strategy.config.validateMigrationChainFromV1()).toBeUndefined();
+    });
+  });
 });

package/src/strategy.ts

@@ -42,12 +42,26 @@ export const tcpConfigSchema = baseStrategyConfigSchema.extend({
 
 export type TcpConfig = z.infer<typeof tcpConfigSchema>;
 
-// Legacy config type for migrations
-interface TcpConfigV1 {
-  host: string;
-  port: number;
-  timeout: number;
-  readBanner: boolean;
+// 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;
+}
+
+/** Read a string field from a config blob. */
+function readString(data: unknown, key: string): string | undefined {
+  if (!isRecord(data)) return undefined;
+  const value = data[key];
+  return typeof value === "string" ? value : undefined;
+}
+
+/** Read a numeric field from a config blob. */
+function readNumber(data: unknown, key: string): number | undefined {
+  if (!isRecord(data)) return undefined;
+  const value = data[key];
+  return typeof value === "number" ? value : undefined;
 }
 
 /**
@@ -203,11 +217,19 @@ export class TcpHealthCheckStrategy implements HealthCheckStrategy<
         fromVersion: 1,
         toVersion: 2,
         description: "Remove readBanner (moved to BannerCollector)",
-        migrate: (data: TcpConfigV1): TcpConfig => ({
-          host: data.host,
-          port: data.port,
-          timeout: data.timeout,
-        }),
+        // IDEMPOTENT: only a genuine v1 blob still carries `readBanner`. A v1
+        // row that happened to omit `readBanner` already matches the v2 shape
+        // (`{ host, port, timeout }`), so passthrough is correct there too.
+        migrate: (data: unknown): unknown => {
+          if (isRecord(data) && "readBanner" in data) {
+            return {
+              host: readString(data, "host"),
+              port: readNumber(data, "port"),
+              timeout: readNumber(data, "timeout"),
+            };
+          }
+          return data;
+        },
       },
     ],
   });