@checkstack/healthcheck-ssh-backend 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# @checkstack/healthcheck-ssh-backend
+
+## 0.0.2
+
+### Patch Changes
+
+- d20d274: Initial release of all @checkstack packages. Rebranded from Checkmate to Checkstack with new npm organization @checkstack and domain checkstack.dev.
+- Updated dependencies [d20d274]
+  - @checkstack/backend-api@0.0.2
+  - @checkstack/common@0.0.2
+  - @checkstack/healthcheck-common@0.0.2
+
+## 0.0.3
+
+### Patch Changes
+
+- Updated dependencies [b4eb432]
+- Updated dependencies [a65e002]
+  - @checkstack/backend-api@1.1.0
+  - @checkstack/common@0.2.0
+  - @checkstack/healthcheck-common@0.1.1
+
+## 0.0.2
+
+### Patch Changes
+
+- Updated dependencies [ffc28f6]
+- Updated dependencies [4dd644d]
+- Updated dependencies [71275dd]
+- Updated dependencies [ae19ff6]
+- Updated dependencies [0babb9c]
+- Updated dependencies [b55fae6]
+- Updated dependencies [b354ab3]
+- Updated dependencies [81f3f85]
+  - @checkstack/common@0.1.0
+  - @checkstack/backend-api@1.0.0
+  - @checkstack/healthcheck-common@0.1.0

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@checkstack/healthcheck-ssh-backend",
+  "version": "0.0.2",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  },
+  "dependencies": {
+    "@checkstack/backend-api": "workspace:*",
+    "@checkstack/common": "workspace:*",
+    "@checkstack/healthcheck-common": "workspace:*",
+    "ssh2": "^1.15.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.0.0",
+    "@types/ssh2": "^1.15.0",
+    "typescript": "^5.0.0",
+    "@checkstack/tsconfig": "workspace:*",
+    "@checkstack/scripts": "workspace:*"
+  }
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+import {
+  createBackendPlugin,
+  coreServices,
+} from "@checkstack/backend-api";
+import { SshHealthCheckStrategy } from "./strategy";
+import { pluginMetadata } from "./plugin-metadata";
+
+export default createBackendPlugin({
+  metadata: pluginMetadata,
+  register(env) {
+    env.registerInit({
+      deps: {
+        healthCheckRegistry: coreServices.healthCheckRegistry,
+        logger: coreServices.logger,
+      },
+      init: async ({ healthCheckRegistry, logger }) => {
+        logger.debug("🔌 Registering SSH Health Check Strategy...");
+        const strategy = new SshHealthCheckStrategy();
+        healthCheckRegistry.register(strategy);
+      },
+    });
+  },
+});

package/src/plugin-metadata.ts

@@ -0,0 +1,8 @@
+import { definePluginMetadata } from "@checkstack/common";
+
+/**
+ * Plugin metadata for the SSH Health Check backend.
+ */
+export const pluginMetadata = definePluginMetadata({
+  pluginId: "healthcheck-ssh",
+});

package/src/strategy.test.ts

@@ -0,0 +1,245 @@
+import { describe, expect, it, mock } from "bun:test";
+import { SshHealthCheckStrategy, SshClient } from "./strategy";
+
+describe("SshHealthCheckStrategy", () => {
+  // Helper to create mock SSH client
+  const createMockClient = (
+    config: {
+      exitCode?: number;
+      stdout?: string;
+      stderr?: string;
+      execError?: Error;
+      connectError?: Error;
+    } = {}
+  ): SshClient => ({
+    connect: mock(() =>
+      config.connectError
+        ? Promise.reject(config.connectError)
+        : Promise.resolve({
+            exec: mock(() =>
+              config.execError
+                ? Promise.reject(config.execError)
+                : Promise.resolve({
+                    exitCode: config.exitCode ?? 0,
+                    stdout: config.stdout ?? "",
+                    stderr: config.stderr ?? "",
+                  })
+            ),
+            end: mock(() => {}),
+          })
+    ),
+  });
+
+  describe("execute", () => {
+    it("should return healthy for successful connection", async () => {
+      const strategy = new SshHealthCheckStrategy(createMockClient());
+
+      const result = await strategy.execute({
+        host: "localhost",
+        port: 22,
+        username: "user",
+        password: "secret",
+        timeout: 5000,
+      });
+
+      expect(result.status).toBe("healthy");
+      expect(result.metadata?.connected).toBe(true);
+    });
+
+    it("should return healthy for successful command execution", async () => {
+      const strategy = new SshHealthCheckStrategy(
+        createMockClient({ exitCode: 0, stdout: "OK" })
+      );
+
+      const result = await strategy.execute({
+        host: "localhost",
+        port: 22,
+        username: "user",
+        password: "secret",
+        timeout: 5000,
+        command: "echo OK",
+      });
+
+      expect(result.status).toBe("healthy");
+      expect(result.metadata?.commandSuccess).toBe(true);
+      expect(result.metadata?.stdout).toBe("OK");
+      expect(result.metadata?.exitCode).toBe(0);
+    });
+
+    it("should return unhealthy for connection error", async () => {
+      const strategy = new SshHealthCheckStrategy(
+        createMockClient({ connectError: new Error("Connection refused") })
+      );
+
+      const result = await strategy.execute({
+        host: "localhost",
+        port: 22,
+        username: "user",
+        password: "secret",
+        timeout: 5000,
+      });
+
+      expect(result.status).toBe("unhealthy");
+      expect(result.message).toContain("Connection refused");
+      expect(result.metadata?.connected).toBe(false);
+    });
+
+    it("should return unhealthy for non-zero exit code", async () => {
+      const strategy = new SshHealthCheckStrategy(
+        createMockClient({ exitCode: 1, stderr: "Error" })
+      );
+
+      const result = await strategy.execute({
+        host: "localhost",
+        port: 22,
+        username: "user",
+        password: "secret",
+        timeout: 5000,
+        command: "exit 1",
+      });
+
+      expect(result.status).toBe("unhealthy");
+      expect(result.metadata?.exitCode).toBe(1);
+      expect(result.metadata?.commandSuccess).toBe(false);
+    });
+
+    it("should pass connectionTime assertion when below threshold", async () => {
+      const strategy = new SshHealthCheckStrategy(createMockClient());
+
+      const result = await strategy.execute({
+        host: "localhost",
+        port: 22,
+        username: "user",
+        password: "secret",
+        timeout: 5000,
+        assertions: [
+          { field: "connectionTime", operator: "lessThan", value: 5000 },
+        ],
+      });
+
+      expect(result.status).toBe("healthy");
+    });
+
+    it("should pass exitCode assertion", async () => {
+      const strategy = new SshHealthCheckStrategy(
+        createMockClient({ exitCode: 0 })
+      );
+
+      const result = await strategy.execute({
+        host: "localhost",
+        port: 22,
+        username: "user",
+        password: "secret",
+        timeout: 5000,
+        command: "true",
+        assertions: [{ field: "exitCode", operator: "equals", value: 0 }],
+      });
+
+      expect(result.status).toBe("healthy");
+    });
+
+    it("should fail exitCode assertion when non-zero", async () => {
+      const strategy = new SshHealthCheckStrategy(
+        createMockClient({ exitCode: 1 })
+      );
+
+      const result = await strategy.execute({
+        host: "localhost",
+        port: 22,
+        username: "user",
+        password: "secret",
+        timeout: 5000,
+        command: "false",
+        assertions: [{ field: "exitCode", operator: "equals", value: 0 }],
+      });
+
+      expect(result.status).toBe("unhealthy");
+      expect(result.message).toContain("Assertion failed");
+    });
+
+    it("should pass stdout assertion", async () => {
+      const strategy = new SshHealthCheckStrategy(
+        createMockClient({ stdout: "OK: Service running" })
+      );
+
+      const result = await strategy.execute({
+        host: "localhost",
+        port: 22,
+        username: "user",
+        password: "secret",
+        timeout: 5000,
+        command: "systemctl status myservice",
+        assertions: [{ field: "stdout", operator: "contains", value: "OK" }],
+      });
+
+      expect(result.status).toBe("healthy");
+    });
+  });
+
+  describe("aggregateResult", () => {
+    it("should calculate averages correctly", () => {
+      const strategy = new SshHealthCheckStrategy();
+      const runs = [
+        {
+          id: "1",
+          status: "healthy" as const,
+          latencyMs: 100,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            connected: true,
+            connectionTimeMs: 50,
+            commandTimeMs: 10,
+            exitCode: 0,
+            commandSuccess: true,
+          },
+        },
+        {
+          id: "2",
+          status: "healthy" as const,
+          latencyMs: 150,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            connected: true,
+            connectionTimeMs: 100,
+            commandTimeMs: 20,
+            exitCode: 0,
+            commandSuccess: true,
+          },
+        },
+      ];
+
+      const aggregated = strategy.aggregateResult(runs);
+
+      expect(aggregated.avgConnectionTime).toBe(75);
+      expect(aggregated.avgCommandTime).toBe(15);
+      expect(aggregated.successRate).toBe(100);
+      expect(aggregated.errorCount).toBe(0);
+    });
+
+    it("should count errors", () => {
+      const strategy = new SshHealthCheckStrategy();
+      const runs = [
+        {
+          id: "1",
+          status: "unhealthy" as const,
+          latencyMs: 100,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            connected: false,
+            connectionTimeMs: 100,
+            commandSuccess: false,
+            error: "Connection refused",
+          },
+        },
+      ];
+
+      const aggregated = strategy.aggregateResult(runs);
+
+      expect(aggregated.errorCount).toBe(1);
+      expect(aggregated.successRate).toBe(0);
+    });
+  });
+});

package/src/strategy.ts

@@ -0,0 +1,403 @@
+import { Client } from "ssh2";
+import {
+  HealthCheckStrategy,
+  HealthCheckResult,
+  HealthCheckRunForAggregation,
+  Versioned,
+  z,
+  timeThresholdField,
+  numericField,
+  booleanField,
+  stringField,
+  evaluateAssertions,
+  configString,
+  configNumber,
+} from "@checkstack/backend-api";
+import {
+  healthResultBoolean,
+  healthResultNumber,
+  healthResultString,
+} from "@checkstack/healthcheck-common";
+
+// ============================================================================
+// SCHEMAS
+// ============================================================================
+
+/**
+ * Assertion schema for SSH health checks using shared factories.
+ */
+const sshAssertionSchema = z.discriminatedUnion("field", [
+  timeThresholdField("connectionTime"),
+  timeThresholdField("commandTime"),
+  numericField("exitCode", { min: 0 }),
+  booleanField("commandSuccess"),
+  stringField("stdout"),
+]);
+
+export type SshAssertion = z.infer<typeof sshAssertionSchema>;
+
+/**
+ * Configuration schema for SSH health checks.
+ */
+export const sshConfigSchema = z.object({
+  host: z.string().describe("SSH server hostname"),
+  port: z.number().int().min(1).max(65_535).default(22).describe("SSH port"),
+  username: z.string().describe("SSH username"),
+  password: configString({ "x-secret": true })
+    .describe("Password for authentication")
+    .optional(),
+  privateKey: configString({ "x-secret": true })
+    .describe("Private key for authentication")
+    .optional(),
+  passphrase: configString({ "x-secret": true })
+    .describe("Passphrase for private key")
+    .optional(),
+  timeout: configNumber({})
+    .min(100)
+    .default(10_000)
+    .describe("Connection timeout in milliseconds"),
+  command: configString({})
+    .optional()
+    .describe("Command to execute for health check (optional)"),
+  assertions: z
+    .array(sshAssertionSchema)
+    .optional()
+    .describe("Validation conditions"),
+});
+
+export type SshConfig = z.infer<typeof sshConfigSchema>;
+export type SshConfigInput = z.input<typeof sshConfigSchema>;
+
+/**
+ * Per-run result metadata.
+ */
+const sshResultSchema = z.object({
+  connected: healthResultBoolean({
+    "x-chart-type": "boolean",
+    "x-chart-label": "Connected",
+  }),
+  connectionTimeMs: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Connection Time",
+    "x-chart-unit": "ms",
+  }),
+  commandTimeMs: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Command Time",
+    "x-chart-unit": "ms",
+  }).optional(),
+  exitCode: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Exit Code",
+  }).optional(),
+  stdout: healthResultString({
+    "x-chart-type": "text",
+    "x-chart-label": "Stdout",
+  }).optional(),
+  stderr: healthResultString({
+    "x-chart-type": "text",
+    "x-chart-label": "Stderr",
+  }).optional(),
+  commandSuccess: healthResultBoolean({
+    "x-chart-type": "boolean",
+    "x-chart-label": "Command Success",
+  }),
+  failedAssertion: sshAssertionSchema.optional(),
+  error: healthResultString({
+    "x-chart-type": "status",
+    "x-chart-label": "Error",
+  }).optional(),
+});
+
+export type SshResult = z.infer<typeof sshResultSchema>;
+
+/**
+ * Aggregated metadata for buckets.
+ */
+const sshAggregatedSchema = z.object({
+  avgConnectionTime: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Avg Connection Time",
+    "x-chart-unit": "ms",
+  }),
+  avgCommandTime: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Avg Command Time",
+    "x-chart-unit": "ms",
+  }),
+  successRate: healthResultNumber({
+    "x-chart-type": "gauge",
+    "x-chart-label": "Success Rate",
+    "x-chart-unit": "%",
+  }),
+  errorCount: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Errors",
+  }),
+});
+
+export type SshAggregatedResult = z.infer<typeof sshAggregatedSchema>;
+
+// ============================================================================
+// SSH CLIENT INTERFACE (for testability)
+// ============================================================================
+
+export interface SshCommandResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+export interface SshConnection {
+  exec(command: string): Promise<SshCommandResult>;
+  end(): void;
+}
+
+export interface SshClient {
+  connect(config: {
+    host: string;
+    port: number;
+    username: string;
+    password?: string;
+    privateKey?: string;
+    passphrase?: string;
+    readyTimeout: number;
+  }): Promise<SshConnection>;
+}
+
+// Default client using ssh2
+const defaultSshClient: SshClient = {
+  connect(config) {
+    return new Promise((resolve, reject) => {
+      const client = new Client();
+
+      client.on("ready", () => {
+        resolve({
+          exec(command: string): Promise<SshCommandResult> {
+            return new Promise((execResolve, execReject) => {
+              client.exec(command, (err, stream) => {
+                if (err) {
+                  execReject(err);
+                  return;
+                }
+
+                let stdout = "";
+                let stderr = "";
+
+                stream.on("data", (data: Buffer) => {
+                  stdout += data.toString();
+                });
+
+                stream.stderr.on("data", (data: Buffer) => {
+                  stderr += data.toString();
+                });
+
+                stream.on("close", (code: number | null) => {
+                  execResolve({
+                    exitCode: code ?? 0,
+                    stdout: stdout.trim(),
+                    stderr: stderr.trim(),
+                  });
+                });
+
+                stream.on("error", execReject);
+              });
+            });
+          },
+          end() {
+            client.end();
+          },
+        });
+      });
+
+      client.on("error", reject);
+
+      client.connect({
+        host: config.host,
+        port: config.port,
+        username: config.username,
+        password: config.password,
+        privateKey: config.privateKey,
+        passphrase: config.passphrase,
+        readyTimeout: config.readyTimeout,
+      });
+    });
+  },
+};
+
+// ============================================================================
+// STRATEGY
+// ============================================================================
+
+export class SshHealthCheckStrategy
+  implements HealthCheckStrategy<SshConfig, SshResult, SshAggregatedResult>
+{
+  id = "ssh";
+  displayName = "SSH Health Check";
+  description = "SSH server connectivity and command execution health check";
+
+  private sshClient: SshClient;
+
+  constructor(sshClient: SshClient = defaultSshClient) {
+    this.sshClient = sshClient;
+  }
+
+  config: Versioned<SshConfig> = new Versioned({
+    version: 1,
+    schema: sshConfigSchema,
+  });
+
+  result: Versioned<SshResult> = new Versioned({
+    version: 1,
+    schema: sshResultSchema,
+  });
+
+  aggregatedResult: Versioned<SshAggregatedResult> = new Versioned({
+    version: 1,
+    schema: sshAggregatedSchema,
+  });
+
+  aggregateResult(
+    runs: HealthCheckRunForAggregation<SshResult>[]
+  ): SshAggregatedResult {
+    let totalConnectionTime = 0;
+    let totalCommandTime = 0;
+    let successCount = 0;
+    let errorCount = 0;
+    let validRuns = 0;
+    let commandRuns = 0;
+
+    for (const run of runs) {
+      if (run.metadata?.error) {
+        errorCount++;
+        continue;
+      }
+      if (run.status === "healthy") {
+        successCount++;
+      }
+      if (run.metadata) {
+        totalConnectionTime += run.metadata.connectionTimeMs;
+        if (run.metadata.commandTimeMs !== undefined) {
+          totalCommandTime += run.metadata.commandTimeMs;
+          commandRuns++;
+        }
+        validRuns++;
+      }
+    }
+
+    return {
+      avgConnectionTime: validRuns > 0 ? totalConnectionTime / validRuns : 0,
+      avgCommandTime: commandRuns > 0 ? totalCommandTime / commandRuns : 0,
+      successRate: runs.length > 0 ? (successCount / runs.length) * 100 : 0,
+      errorCount,
+    };
+  }
+
+  async execute(config: SshConfigInput): Promise<HealthCheckResult<SshResult>> {
+    const validatedConfig = this.config.validate(config);
+    const start = performance.now();
+
+    try {
+      // Connect to SSH server
+      const connection = await this.sshClient.connect({
+        host: validatedConfig.host,
+        port: validatedConfig.port,
+        username: validatedConfig.username,
+        password: validatedConfig.password,
+        privateKey: validatedConfig.privateKey,
+        passphrase: validatedConfig.passphrase,
+        readyTimeout: validatedConfig.timeout,
+      });
+
+      const connectionTimeMs = Math.round(performance.now() - start);
+
+      let commandTimeMs: number | undefined;
+      let exitCode: number | undefined;
+      let stdout: string | undefined;
+      let stderr: string | undefined;
+      let commandSuccess = true;
+
+      // Execute command if provided
+      if (validatedConfig.command) {
+        const commandStart = performance.now();
+        try {
+          const result = await connection.exec(validatedConfig.command);
+          exitCode = result.exitCode;
+          stdout = result.stdout;
+          stderr = result.stderr;
+          commandSuccess = result.exitCode === 0;
+          commandTimeMs = Math.round(performance.now() - commandStart);
+        } catch {
+          commandSuccess = false;
+          commandTimeMs = Math.round(performance.now() - commandStart);
+        }
+      }
+
+      connection.end();
+
+      const result: Omit<SshResult, "failedAssertion" | "error"> = {
+        connected: true,
+        connectionTimeMs,
+        commandTimeMs,
+        exitCode,
+        stdout,
+        stderr,
+        commandSuccess,
+      };
+
+      // Evaluate assertions using shared utility
+      const failedAssertion = evaluateAssertions(validatedConfig.assertions, {
+        connectionTime: connectionTimeMs,
+        commandTime: commandTimeMs ?? 0,
+        exitCode: exitCode ?? 0,
+        commandSuccess,
+        stdout: stdout ?? "",
+      });
+
+      if (failedAssertion) {
+        return {
+          status: "unhealthy",
+          latencyMs: connectionTimeMs + (commandTimeMs ?? 0),
+          message: `Assertion failed: ${failedAssertion.field} ${
+            failedAssertion.operator
+          }${"value" in failedAssertion ? ` ${failedAssertion.value}` : ""}`,
+          metadata: { ...result, failedAssertion },
+        };
+      }
+
+      if (!commandSuccess && validatedConfig.command) {
+        return {
+          status: "unhealthy",
+          latencyMs: connectionTimeMs + (commandTimeMs ?? 0),
+          message: `Command failed with exit code ${exitCode}`,
+          metadata: result,
+        };
+      }
+
+      const message = validatedConfig.command
+        ? `SSH connected, command executed (exit ${exitCode}) in ${commandTimeMs}ms`
+        : `SSH connected in ${connectionTimeMs}ms`;
+
+      return {
+        status: "healthy",
+        latencyMs: connectionTimeMs + (commandTimeMs ?? 0),
+        message,
+        metadata: result,
+      };
+    } catch (error: unknown) {
+      const end = performance.now();
+      const isError = error instanceof Error;
+      return {
+        status: "unhealthy",
+        latencyMs: Math.round(end - start),
+        message: isError ? error.message : "SSH connection failed",
+        metadata: {
+          connected: false,
+          connectionTimeMs: Math.round(end - start),
+          commandSuccess: false,
+          error: isError ? error.name : "UnknownError",
+        },
+      };
+    }
+  }
+}

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@checkstack/tsconfig/backend.json",
+  "include": [
+    "src"
+  ]
+}