@checkstack/healthcheck-ping-backend 0.3.21 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,77 @@
 # @checkstack/healthcheck-ping-backend
 
+## 0.4.0
+
+### Minor Changes
+
+- 43e4484: Extend `{{ … }}` environment templating across every built-in health-check type
+  and add editor UX for it, so one check config can cover N environments (mirrors
+  the existing HTTP `url` pattern).
+
+  Templatable connection/target fields now marked `x-templatable`:
+
+  - TLS: `host`, `servername`; TCP: `host`; Ping: `host`; gRPC: `host`, `service`.
+  - MySQL / Postgres: `host`, `database`, `user`, `query`.
+  - SSH: `host`, `username`, `command`; Redis: `host`, `args`; RCON: `host`,
+    `command`.
+  - DNS: `hostname`, `nameserver`; Jenkins: `url` (`baseUrl`), `jobName`;
+    Container: `endpoint`, `container`.
+  - SNMP: `host` (strategy), `oid` (collector).
+  - Script (shell): `cwd` (working directory).
+
+  This closes the last gaps so the coverage is now truly every built-in
+  health-check type. The Script collectors' `script` bodies are deliberately NOT
+  templatable: rendering `{{ … }}` into shell/TypeScript source would splice env
+  values into executed code. Per-environment data reaches those scripts safely via
+  the reserved `CHECKSTACK_ENV_*` shell vars (shell collector) and
+  `globalThis.context.environment` (inline collector) instead.
+
+  Because templating strips `{{ }}` and renders an undefined variable to an empty
+  string, every REQUIRED templatable field now has a post-render config-error
+  guard so an empty/invalid render is treated as a transport failure instead of a
+  silent "healthy" empty probe. Strategy connection fields (host, database, user,
+  endpoint, container, Jenkins base URL, SNMP host) throw from `createClient`;
+  collector target fields (query, command, hostname, jobName, SNMP oid) return a
+  `CollectorResult` with an `error`. Jenkins `baseUrl` moves its `.url()` validation to post-render.
+  Secret fields (passwords/tokens/keys) are never templatable; optional fields
+  (SNI `servername`, gRPC `service`, DNS `nameserver`, Redis `args`, Script `cwd`)
+  are templatable but not non-empty-guarded, since an empty render is a legitimate
+  "unset". SSRF/egress guards continue to run on the rendered host (rendering
+  happens before `createClient`).
+
+  Editor UX (`@checkstack/ui` + `@checkstack/healthcheck-frontend`):
+
+  - The environment "Preview as" picker + live preview line now also apply to the
+    strategy (connection) form, not just collector forms, so host/port templates
+    preview too.
+  - A single-line templatable field shows a small "Templating" badge next to its
+    label and, when a completion provider is supplied, renders a
+    `TemplateValueInput` with `{{ … }}` autocomplete. The health-check editor
+    seeds the provider with the fixed `environment.* / check.* / system.*`
+    namespace (`createReferenceCompletionProvider`, new `@checkstack/ui` export),
+    and `DynamicForm` gains a `templatableFieldsOnly` prop so only `x-templatable`
+    fields become template inputs (automation keeps templating every string field).
+
+  BREAKING CHANGE: none. Existing non-templatable configs and stored values are
+  unaffected; only fields explicitly marked `x-templatable` change behavior.
+
+  The `@checkstack/ai-backend` bump reflects the regenerated docs index for the
+  updated health-check collector and config-schema templating documentation.
+
+  Thanks to [@stuajnht](https://github.com/stuajnht) for the valuable feedback.
+
+### Patch Changes
+
+- Updated dependencies [43e4484]
+- Updated dependencies [43e4484]
+- Updated dependencies [43e4484]
+- Updated dependencies [43e4484]
+- Updated dependencies [43e4484]
+- Updated dependencies [43e4484]
+- Updated dependencies [43e4484]
+  - @checkstack/healthcheck-common@1.16.0
+  - @checkstack/backend-api@0.31.1
+
 ## 0.3.21
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-ping-backend",
-  "version": "0.3.21",
+  "version": "0.4.0",
   "type": "module",
   "main": "src/index.ts",
   "checkstack": {
@@ -14,9 +14,9 @@
     "pack": "bunx @checkstack/scripts plugin-pack"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.31.0",
+    "@checkstack/backend-api": "0.31.1",
     "@checkstack/common": "0.22.0",
-    "@checkstack/healthcheck-common": "1.15.0"
+    "@checkstack/healthcheck-common": "1.16.0"
   },
   "devDependencies": {
     "@types/bun": "^1.0.0",

package/src/ping-collector.test.ts

@@ -64,6 +64,57 @@ describe("PingCollector", () => {
       expect(result.error).toBe("Host unreachable");
     });
 
+    it("pings a concrete (already-rendered) host", async () => {
+      // The executor renders `{{ environment.host }}` upstream, so execute always
+      // sees a concrete value; verify it is forwarded to the transport client.
+      const collector = new PingCollector();
+      const client = createMockClient();
+
+      const result = await collector.execute({
+        config: { host: "rendered.example.com", count: 3, timeout: 5000 },
+        client,
+        pluginId: "test",
+      });
+
+      expect(client.exec).toHaveBeenCalledWith({
+        host: "rendered.example.com",
+        count: 3,
+        timeout: 5000,
+      });
+      expect(result.error).toBeUndefined();
+    });
+
+    it("returns a transport error when the rendered host is empty", async () => {
+      // An env-less run renders `{{ environment.host }}` to "". A required target
+      // that renders empty is a config error, not a silent healthy probe.
+      const collector = new PingCollector();
+      const client = createMockClient();
+
+      const result = await collector.execute({
+        config: { host: "", count: 3, timeout: 5000 },
+        client,
+        pluginId: "test",
+      });
+
+      expect(result.error).toContain("Rendered host is empty");
+      expect(result.result.packetLoss).toBe(100);
+      expect(client.exec).not.toHaveBeenCalled();
+    });
+
+    it("returns a transport error when the rendered host is whitespace-only", async () => {
+      const collector = new PingCollector();
+      const client = createMockClient();
+
+      const result = await collector.execute({
+        config: { host: "   ", count: 3, timeout: 5000 },
+        client,
+        pluginId: "test",
+      });
+
+      expect(result.error).toContain("Rendered host is empty");
+      expect(client.exec).not.toHaveBeenCalled();
+    });
+
     it("should pass correct parameters to client", async () => {
       const collector = new PingCollector();
       const client = createMockClient();

package/src/ping-collector.ts

@@ -7,6 +7,7 @@ import {
   mergeAverage,
   VersionedAggregated,
   aggregatedAverage,
+  configString,
   type InferAggregatedResult,
 } from "@checkstack/backend-api";
 import {
@@ -21,7 +22,15 @@ import type { PingTransportClient } from "./transport-client";
 // ============================================================================
 
 const pingConfigSchema = z.object({
-  host: z.string().min(1).describe("Hostname or IP address to ping"),
+  // Templatable: supports `{{ environment.host }}` so one config covers N
+  // environments. `.min(1)` still guards the STORED value (a `{{ }}` template is
+  // non-empty); the CONCRETE rendered host is re-checked POST-RENDER in
+  // `execute` because an empty render must not run as a successful probe.
+  host: configString({ "x-templatable": true })
+    .min(1)
+    .describe(
+      "Hostname or IP address to ping. Supports templating, e.g. {{ environment.host }}",
+    ),
   count: z
     .number()
     .int()
@@ -38,6 +47,13 @@ const pingConfigSchema = z.object({
 
 export type PingConfig = z.infer<typeof pingConfigSchema>;
 
+/**
+ * Post-render validator for the rendered `host`. An empty render (e.g. an
+ * env-less run resolving `{{ environment.host }}` to "") is a config error that
+ * prevents the probe - transport-failure semantics - not a healthy empty ping.
+ */
+const renderedHostSchema = z.string().trim().min(1);
+
 // ============================================================================
 // RESULT SCHEMAS
 // ============================================================================
@@ -180,8 +196,27 @@ export class PingCollector implements CollectorStrategy<
     client: PingTransportClient;
     pluginId: string;
   }): Promise<CollectorResult<PingResult>> {
+    // Post-render guard: `host` is a templatable string, so the concrete value
+    // is re-validated here after the executor rendered `{{ environment.* }}`.
+    // An empty render is a config error - fail as a transport failure rather
+    // than spawning a ping against an empty host.
+    const host = renderedHostSchema.safeParse(config.host);
+    if (!host.success) {
+      return {
+        result: {
+          packetsSent: 0,
+          packetsReceived: 0,
+          // No packet could reach an empty host: report total loss. The run is
+          // already short-circuited to unhealthy by the `error` below.
+          packetLoss: 100,
+        },
+        error: `Rendered host is empty: ${JSON.stringify(config.host)}. ` +
+          `Check the {{ environment.* }} templating for this environment.`,
+      };
+    }
+
     const response = await client.exec({
-      host: config.host,
+      host: host.data,
       count: config.count,
       timeout: config.timeout,
     });