@checkstack/healthcheck-grpc-backend 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# @checkstack/healthcheck-grpc-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,23 @@
+{
+  "name": "@checkstack/healthcheck-grpc-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:*",
+    "@grpc/grpc-js": "^1.9.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.0.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 { GrpcHealthCheckStrategy } 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 gRPC Health Check Strategy...");
+        const strategy = new GrpcHealthCheckStrategy();
+        healthCheckRegistry.register(strategy);
+      },
+    });
+  },
+});

package/src/plugin-metadata.ts

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

package/src/strategy.test.ts

@@ -0,0 +1,222 @@
+import { describe, expect, it, mock } from "bun:test";
+import {
+  GrpcHealthCheckStrategy,
+  GrpcHealthClient,
+  GrpcHealthStatus,
+} from "./strategy";
+
+describe("GrpcHealthCheckStrategy", () => {
+  // Helper to create mock gRPC client
+  const createMockClient = (
+    config: {
+      status?: GrpcHealthStatus;
+      error?: Error;
+    } = {}
+  ): GrpcHealthClient => ({
+    check: mock(() =>
+      config.error
+        ? Promise.reject(config.error)
+        : Promise.resolve({ status: config.status ?? "SERVING" })
+    ),
+  });
+
+  describe("execute", () => {
+    it("should return healthy for SERVING status", async () => {
+      const strategy = new GrpcHealthCheckStrategy(createMockClient());
+
+      const result = await strategy.execute({
+        host: "localhost",
+        port: 50051,
+        timeout: 5000,
+      });
+
+      expect(result.status).toBe("healthy");
+      expect(result.metadata?.connected).toBe(true);
+      expect(result.metadata?.status).toBe("SERVING");
+    });
+
+    it("should return unhealthy for NOT_SERVING status", async () => {
+      const strategy = new GrpcHealthCheckStrategy(
+        createMockClient({ status: "NOT_SERVING" })
+      );
+
+      const result = await strategy.execute({
+        host: "localhost",
+        port: 50051,
+        timeout: 5000,
+      });
+
+      expect(result.status).toBe("unhealthy");
+      expect(result.message).toContain("NOT_SERVING");
+      expect(result.metadata?.status).toBe("NOT_SERVING");
+    });
+
+    it("should return unhealthy for SERVICE_UNKNOWN status", async () => {
+      const strategy = new GrpcHealthCheckStrategy(
+        createMockClient({ status: "SERVICE_UNKNOWN" })
+      );
+
+      const result = await strategy.execute({
+        host: "localhost",
+        port: 50051,
+        service: "my.service",
+        timeout: 5000,
+      });
+
+      expect(result.status).toBe("unhealthy");
+      expect(result.message).toContain("SERVICE_UNKNOWN");
+    });
+
+    it("should return unhealthy for connection error", async () => {
+      const strategy = new GrpcHealthCheckStrategy(
+        createMockClient({ error: new Error("Connection refused") })
+      );
+
+      const result = await strategy.execute({
+        host: "localhost",
+        port: 50051,
+        timeout: 5000,
+      });
+
+      expect(result.status).toBe("unhealthy");
+      expect(result.message).toContain("Connection refused");
+      expect(result.metadata?.connected).toBe(false);
+    });
+
+    it("should pass responseTime assertion when below threshold", async () => {
+      const strategy = new GrpcHealthCheckStrategy(createMockClient());
+
+      const result = await strategy.execute({
+        host: "localhost",
+        port: 50051,
+        timeout: 5000,
+        assertions: [
+          { field: "responseTime", operator: "lessThan", value: 5000 },
+        ],
+      });
+
+      expect(result.status).toBe("healthy");
+    });
+
+    it("should pass status assertion", async () => {
+      const strategy = new GrpcHealthCheckStrategy(createMockClient());
+
+      const result = await strategy.execute({
+        host: "localhost",
+        port: 50051,
+        timeout: 5000,
+        assertions: [{ field: "status", operator: "equals", value: "SERVING" }],
+      });
+
+      expect(result.status).toBe("healthy");
+    });
+
+    it("should fail status assertion when not matching", async () => {
+      const strategy = new GrpcHealthCheckStrategy(
+        createMockClient({ status: "NOT_SERVING" })
+      );
+
+      const result = await strategy.execute({
+        host: "localhost",
+        port: 50051,
+        timeout: 5000,
+        assertions: [{ field: "status", operator: "equals", value: "SERVING" }],
+      });
+
+      expect(result.status).toBe("unhealthy");
+      expect(result.message).toContain("Assertion failed");
+    });
+
+    it("should check specific service", async () => {
+      const mockClient = createMockClient();
+      const strategy = new GrpcHealthCheckStrategy(mockClient);
+
+      await strategy.execute({
+        host: "localhost",
+        port: 50051,
+        service: "my.custom.Service",
+        timeout: 5000,
+      });
+
+      expect(mockClient.check).toHaveBeenCalledWith(
+        expect.objectContaining({ service: "my.custom.Service" })
+      );
+    });
+  });
+
+  describe("aggregateResult", () => {
+    it("should calculate averages correctly", () => {
+      const strategy = new GrpcHealthCheckStrategy();
+      const runs = [
+        {
+          id: "1",
+          status: "healthy" as const,
+          latencyMs: 10,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            connected: true,
+            responseTimeMs: 5,
+            status: "SERVING" as const,
+          },
+        },
+        {
+          id: "2",
+          status: "healthy" as const,
+          latencyMs: 20,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            connected: true,
+            responseTimeMs: 15,
+            status: "SERVING" as const,
+          },
+        },
+      ];
+
+      const aggregated = strategy.aggregateResult(runs);
+
+      expect(aggregated.avgResponseTime).toBe(10);
+      expect(aggregated.successRate).toBe(100);
+      expect(aggregated.servingCount).toBe(2);
+      expect(aggregated.errorCount).toBe(0);
+    });
+
+    it("should count errors and non-serving", () => {
+      const strategy = new GrpcHealthCheckStrategy();
+      const runs = [
+        {
+          id: "1",
+          status: "unhealthy" as const,
+          latencyMs: 10,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            connected: true,
+            responseTimeMs: 5,
+            status: "NOT_SERVING" as const,
+          },
+        },
+        {
+          id: "2",
+          status: "unhealthy" as const,
+          latencyMs: 0,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            connected: false,
+            responseTimeMs: 0,
+            status: "UNKNOWN" as const,
+            error: "Connection refused",
+          },
+        },
+      ];
+
+      const aggregated = strategy.aggregateResult(runs);
+
+      expect(aggregated.errorCount).toBe(1);
+      expect(aggregated.servingCount).toBe(0);
+      expect(aggregated.successRate).toBe(0);
+    });
+  });
+});

package/src/strategy.ts

@@ -0,0 +1,343 @@
+import * as grpc from "@grpc/grpc-js";
+import {
+  HealthCheckStrategy,
+  HealthCheckResult,
+  HealthCheckRunForAggregation,
+  Versioned,
+  z,
+  timeThresholdField,
+  enumField,
+  evaluateAssertions,
+} from "@checkstack/backend-api";
+import {
+  healthResultBoolean,
+  healthResultNumber,
+  healthResultString,
+} from "@checkstack/healthcheck-common";
+
+// ============================================================================
+// SCHEMAS
+// ============================================================================
+
+/**
+ * gRPC Health Checking Protocol status values
+ * https://github.com/grpc/grpc/blob/master/doc/health-checking.md
+ */
+const GrpcHealthStatus = z.enum([
+  "UNKNOWN",
+  "SERVING",
+  "NOT_SERVING",
+  "SERVICE_UNKNOWN",
+]);
+export type GrpcHealthStatus = z.infer<typeof GrpcHealthStatus>;
+
+/**
+ * Assertion schema for gRPC health checks using shared factories.
+ * Uses enumField for status to render a dropdown with valid status values.
+ */
+const grpcAssertionSchema = z.discriminatedUnion("field", [
+  timeThresholdField("responseTime"),
+  enumField("status", GrpcHealthStatus.options),
+]);
+
+export type GrpcAssertion = z.infer<typeof grpcAssertionSchema>;
+
+/**
+ * Configuration schema for gRPC health checks.
+ */
+export const grpcConfigSchema = z.object({
+  host: z.string().describe("gRPC server hostname"),
+  port: z.number().int().min(1).max(65_535).describe("gRPC port"),
+  service: z
+    .string()
+    .default("")
+    .describe("Service name to check (empty for overall server health)"),
+  useTls: z.boolean().default(false).describe("Use TLS/SSL connection"),
+  timeout: z
+    .number()
+    .min(100)
+    .default(5000)
+    .describe("Request timeout in milliseconds"),
+  assertions: z
+    .array(grpcAssertionSchema)
+    .optional()
+    .describe("Validation conditions"),
+});
+
+export type GrpcConfig = z.infer<typeof grpcConfigSchema>;
+export type GrpcConfigInput = z.input<typeof grpcConfigSchema>;
+
+/**
+ * Per-run result metadata.
+ */
+const grpcResultSchema = z.object({
+  connected: healthResultBoolean({
+    "x-chart-type": "boolean",
+    "x-chart-label": "Connected",
+  }),
+  responseTimeMs: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Response Time",
+    "x-chart-unit": "ms",
+  }),
+  status: GrpcHealthStatus.meta({
+    "x-chart-type": "text",
+    "x-chart-label": "Status",
+  }),
+  failedAssertion: grpcAssertionSchema.optional(),
+  error: healthResultString({
+    "x-chart-type": "status",
+    "x-chart-label": "Error",
+  }).optional(),
+});
+
+export type GrpcResult = z.infer<typeof grpcResultSchema>;
+
+/**
+ * Aggregated metadata for buckets.
+ */
+const grpcAggregatedSchema = z.object({
+  avgResponseTime: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Avg Response 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",
+  }),
+  servingCount: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Serving",
+  }),
+});
+
+export type GrpcAggregatedResult = z.infer<typeof grpcAggregatedSchema>;
+
+// ============================================================================
+// GRPC CLIENT INTERFACE (for testability)
+// ============================================================================
+
+export interface GrpcHealthClient {
+  check(options: {
+    host: string;
+    port: number;
+    service: string;
+    useTls: boolean;
+    timeout: number;
+  }): Promise<{ status: GrpcHealthStatus }>;
+}
+
+// Default client using @grpc/grpc-js
+const defaultGrpcClient: GrpcHealthClient = {
+  async check(options) {
+    return new Promise((resolve, reject) => {
+      const credentials = options.useTls
+        ? grpc.credentials.createSsl()
+        : grpc.credentials.createInsecure();
+
+      // Create health check client manually using makeGenericClientConstructor
+      const HealthService = grpc.makeGenericClientConstructor(
+        {
+          Check: {
+            path: "/grpc.health.v1.Health/Check",
+            requestStream: false,
+            responseStream: false,
+            requestSerialize: (message: { service: string }) =>
+              Buffer.from(JSON.stringify(message)),
+            requestDeserialize: (data: Buffer) =>
+              JSON.parse(data.toString()) as { service: string },
+            responseSerialize: (message: { status: number }) =>
+              Buffer.from(JSON.stringify(message)),
+            responseDeserialize: (data: Buffer) =>
+              JSON.parse(data.toString()) as { status: number },
+          },
+        },
+        "grpc.health.v1.Health"
+      );
+
+      const client = new HealthService(
+        `${options.host}:${options.port}`,
+        credentials
+      );
+
+      const deadline = new Date(Date.now() + options.timeout);
+
+      client.Check(
+        { service: options.service },
+        { deadline },
+        (
+          err: grpc.ServiceError | null,
+          response: { status: number } | undefined
+        ) => {
+          client.close();
+
+          if (err) {
+            reject(err);
+            return;
+          }
+
+          // Map status number to enum
+          const statusMap: Record<number, GrpcHealthStatus> = {
+            0: "UNKNOWN",
+            1: "SERVING",
+            2: "NOT_SERVING",
+            3: "SERVICE_UNKNOWN",
+          };
+
+          resolve({
+            status: statusMap[response?.status ?? 0] ?? "UNKNOWN",
+          });
+        }
+      );
+    });
+  },
+};
+
+// ============================================================================
+// STRATEGY
+// ============================================================================
+
+export class GrpcHealthCheckStrategy
+  implements HealthCheckStrategy<GrpcConfig, GrpcResult, GrpcAggregatedResult>
+{
+  id = "grpc";
+  displayName = "gRPC Health Check";
+  description =
+    "gRPC server health check using the standard Health Checking Protocol";
+
+  private grpcClient: GrpcHealthClient;
+
+  constructor(grpcClient: GrpcHealthClient = defaultGrpcClient) {
+    this.grpcClient = grpcClient;
+  }
+
+  config: Versioned<GrpcConfig> = new Versioned({
+    version: 1,
+    schema: grpcConfigSchema,
+  });
+
+  result: Versioned<GrpcResult> = new Versioned({
+    version: 1,
+    schema: grpcResultSchema,
+  });
+
+  aggregatedResult: Versioned<GrpcAggregatedResult> = new Versioned({
+    version: 1,
+    schema: grpcAggregatedSchema,
+  });
+
+  aggregateResult(
+    runs: HealthCheckRunForAggregation<GrpcResult>[]
+  ): GrpcAggregatedResult {
+    let totalResponseTime = 0;
+    let successCount = 0;
+    let errorCount = 0;
+    let servingCount = 0;
+    let validRuns = 0;
+
+    for (const run of runs) {
+      if (run.metadata?.error) {
+        errorCount++;
+        continue;
+      }
+      if (run.status === "healthy") {
+        successCount++;
+      }
+      if (run.metadata) {
+        totalResponseTime += run.metadata.responseTimeMs;
+        if (run.metadata.status === "SERVING") {
+          servingCount++;
+        }
+        validRuns++;
+      }
+    }
+
+    return {
+      avgResponseTime: validRuns > 0 ? totalResponseTime / validRuns : 0,
+      successRate: runs.length > 0 ? (successCount / runs.length) * 100 : 0,
+      errorCount,
+      servingCount,
+    };
+  }
+
+  async execute(
+    config: GrpcConfigInput
+  ): Promise<HealthCheckResult<GrpcResult>> {
+    const validatedConfig = this.config.validate(config);
+    const start = performance.now();
+
+    try {
+      const response = await this.grpcClient.check({
+        host: validatedConfig.host,
+        port: validatedConfig.port,
+        service: validatedConfig.service,
+        useTls: validatedConfig.useTls,
+        timeout: validatedConfig.timeout,
+      });
+
+      const responseTimeMs = Math.round(performance.now() - start);
+
+      const result: Omit<GrpcResult, "failedAssertion" | "error"> = {
+        connected: true,
+        responseTimeMs,
+        status: response.status,
+      };
+
+      // Evaluate assertions using shared utility
+      const failedAssertion = evaluateAssertions(validatedConfig.assertions, {
+        responseTime: responseTimeMs,
+        status: response.status,
+      });
+
+      if (failedAssertion) {
+        return {
+          status: "unhealthy",
+          latencyMs: responseTimeMs,
+          message: `Assertion failed: ${failedAssertion.field} ${
+            failedAssertion.operator
+          }${"value" in failedAssertion ? ` ${failedAssertion.value}` : ""}`,
+          metadata: { ...result, failedAssertion },
+        };
+      }
+
+      // Check if service is SERVING
+      if (response.status !== "SERVING") {
+        return {
+          status: "unhealthy",
+          latencyMs: responseTimeMs,
+          message: `gRPC health status: ${response.status}`,
+          metadata: result,
+        };
+      }
+
+      return {
+        status: "healthy",
+        latencyMs: responseTimeMs,
+        message: `gRPC service ${
+          validatedConfig.service || "(root)"
+        } is SERVING`,
+        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 : "gRPC health check failed",
+        metadata: {
+          connected: false,
+          responseTimeMs: Math.round(end - start),
+          status: "UNKNOWN",
+          error: isError ? error.name : "UnknownError",
+        },
+      };
+    }
+  }
+}

package/tsconfig.json

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