@checkstack/healthcheck-grpc-backend 0.0.2 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # @checkstack/healthcheck-grpc-backend
 
+## 0.1.0
+
+### Minor Changes
+
+- f5b1f49: Refactored health check strategies to use `createClient()` pattern with built-in collectors.
+
+  **Strategy Changes:**
+
+  - Replaced `execute()` with `createClient()` that returns a transport client
+  - Strategy configs now only contain connection parameters
+  - Collector configs handle what to do with the connection
+
+  **Built-in Collectors Added:**
+
+  - DNS: `LookupCollector` for hostname resolution
+  - gRPC: `HealthCollector` for gRPC health protocol
+  - HTTP: `RequestCollector` for HTTP requests
+  - MySQL: `QueryCollector` for database queries
+  - Ping: `PingCollector` for ICMP ping
+  - Postgres: `QueryCollector` for database queries
+  - Redis: `CommandCollector` for Redis commands
+  - Script: `ExecuteCollector` for script execution
+  - SSH: `CommandCollector` for SSH commands
+  - TCP: `BannerCollector` for TCP banner grabbing
+  - TLS: `CertificateCollector` for certificate inspection
+
+### Patch Changes
+
+- Updated dependencies [f5b1f49]
+- Updated dependencies [f5b1f49]
+- Updated dependencies [f5b1f49]
+- Updated dependencies [f5b1f49]
+  - @checkstack/backend-api@0.1.0
+  - @checkstack/healthcheck-common@0.1.0
+  - @checkstack/common@0.0.3
+
+## 0.0.3
+
+### Patch Changes
+
+- Updated dependencies [cb82e4d]
+  - @checkstack/healthcheck-common@0.0.3
+
 ## 0.0.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-grpc-backend",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "type": "module",
   "main": "src/index.ts",
   "scripts": {

package/src/health-collector.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, it, mock } from "bun:test";
+import { HealthCollector, type HealthConfig } from "./health-collector";
+import type {
+  GrpcTransportClient,
+  GrpcHealthResponse,
+} from "./transport-client";
+
+describe("HealthCollector", () => {
+  const createMockClient = (
+    response: Partial<GrpcHealthResponse> = {}
+  ): GrpcTransportClient => ({
+    exec: mock(() =>
+      Promise.resolve({
+        status: response.status ?? "SERVING",
+        error: response.error,
+      })
+    ),
+  });
+
+  describe("execute", () => {
+    it("should check health status successfully", async () => {
+      const collector = new HealthCollector();
+      const client = createMockClient({ status: "SERVING" });
+
+      const result = await collector.execute({
+        config: { service: "" },
+        client,
+        pluginId: "test",
+      });
+
+      expect(result.result.status).toBe("SERVING");
+      expect(result.result.serving).toBe(true);
+      expect(result.result.responseTimeMs).toBeGreaterThanOrEqual(0);
+      expect(result.error).toBeUndefined();
+    });
+
+    it("should return error for NOT_SERVING status", async () => {
+      const collector = new HealthCollector();
+      const client = createMockClient({ status: "NOT_SERVING" });
+
+      const result = await collector.execute({
+        config: { service: "myservice" },
+        client,
+        pluginId: "test",
+      });
+
+      expect(result.result.status).toBe("NOT_SERVING");
+      expect(result.result.serving).toBe(false);
+      expect(result.error).toContain("NOT_SERVING");
+    });
+
+    it("should pass service name to client", async () => {
+      const collector = new HealthCollector();
+      const client = createMockClient();
+
+      await collector.execute({
+        config: { service: "my.grpc.Service" },
+        client,
+        pluginId: "test",
+      });
+
+      expect(client.exec).toHaveBeenCalledWith({
+        service: "my.grpc.Service",
+      });
+    });
+  });
+
+  describe("aggregateResult", () => {
+    it("should calculate average response time and serving rate", () => {
+      const collector = new HealthCollector();
+      const runs = [
+        {
+          id: "1",
+          status: "healthy" as const,
+          latencyMs: 10,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: { status: "SERVING", serving: true, responseTimeMs: 50 },
+        },
+        {
+          id: "2",
+          status: "healthy" as const,
+          latencyMs: 15,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: { status: "SERVING", serving: true, responseTimeMs: 100 },
+        },
+      ];
+
+      const aggregated = collector.aggregateResult(runs);
+
+      expect(aggregated.avgResponseTimeMs).toBe(75);
+      expect(aggregated.servingRate).toBe(100);
+    });
+
+    it("should calculate serving rate correctly", () => {
+      const collector = new HealthCollector();
+      const runs = [
+        {
+          id: "1",
+          status: "healthy" as const,
+          latencyMs: 10,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: { status: "SERVING", serving: true, responseTimeMs: 50 },
+        },
+        {
+          id: "2",
+          status: "unhealthy" as const,
+          latencyMs: 15,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            status: "NOT_SERVING",
+            serving: false,
+            responseTimeMs: 100,
+          },
+        },
+      ];
+
+      const aggregated = collector.aggregateResult(runs);
+
+      expect(aggregated.servingRate).toBe(50);
+    });
+  });
+
+  describe("metadata", () => {
+    it("should have correct static properties", () => {
+      const collector = new HealthCollector();
+
+      expect(collector.id).toBe("health");
+      expect(collector.displayName).toBe("gRPC Health Check");
+      expect(collector.allowMultiple).toBe(true);
+      expect(collector.supportedPlugins).toHaveLength(1);
+    });
+  });
+});

package/src/health-collector.ts

@@ -0,0 +1,150 @@
+import {
+  Versioned,
+  z,
+  type HealthCheckRunForAggregation,
+  type CollectorResult,
+  type CollectorStrategy,
+} from "@checkstack/backend-api";
+import {
+  healthResultNumber,
+  healthResultString,
+  healthResultBoolean,
+} from "@checkstack/healthcheck-common";
+import { pluginMetadata } from "./plugin-metadata";
+import type { GrpcTransportClient } from "./transport-client";
+
+// ============================================================================
+// CONFIGURATION SCHEMA
+// ============================================================================
+
+const healthConfigSchema = z.object({
+  service: z
+    .string()
+    .default("")
+    .describe("Service name to check (empty for overall)"),
+});
+
+export type HealthConfig = z.infer<typeof healthConfigSchema>;
+
+// ============================================================================
+// RESULT SCHEMAS
+// ============================================================================
+
+const healthResultSchema = z.object({
+  status: healthResultString({
+    "x-chart-type": "text",
+    "x-chart-label": "Status",
+  }),
+  serving: healthResultBoolean({
+    "x-chart-type": "boolean",
+    "x-chart-label": "Serving",
+  }),
+  responseTimeMs: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Response Time",
+    "x-chart-unit": "ms",
+  }),
+});
+
+export type HealthResult = z.infer<typeof healthResultSchema>;
+
+const healthAggregatedSchema = z.object({
+  avgResponseTimeMs: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Avg Response Time",
+    "x-chart-unit": "ms",
+  }),
+  servingRate: healthResultNumber({
+    "x-chart-type": "gauge",
+    "x-chart-label": "Serving Rate",
+    "x-chart-unit": "%",
+  }),
+});
+
+export type HealthAggregatedResult = z.infer<typeof healthAggregatedSchema>;
+
+// ============================================================================
+// HEALTH COLLECTOR
+// ============================================================================
+
+/**
+ * Built-in gRPC health collector.
+ * Checks gRPC health status using the standard Health Checking Protocol.
+ */
+export class HealthCollector
+  implements
+    CollectorStrategy<
+      GrpcTransportClient,
+      HealthConfig,
+      HealthResult,
+      HealthAggregatedResult
+    >
+{
+  id = "health";
+  displayName = "gRPC Health Check";
+  description = "Check gRPC service health status";
+
+  supportedPlugins = [pluginMetadata];
+
+  allowMultiple = true;
+
+  config = new Versioned({ version: 1, schema: healthConfigSchema });
+  result = new Versioned({ version: 1, schema: healthResultSchema });
+  aggregatedResult = new Versioned({
+    version: 1,
+    schema: healthAggregatedSchema,
+  });
+
+  async execute({
+    config,
+    client,
+  }: {
+    config: HealthConfig;
+    client: GrpcTransportClient;
+    pluginId: string;
+  }): Promise<CollectorResult<HealthResult>> {
+    const startTime = Date.now();
+
+    const response = await client.exec({
+      service: config.service,
+    });
+
+    const responseTimeMs = Date.now() - startTime;
+    const serving = response.status === "SERVING";
+
+    return {
+      result: {
+        status: response.status,
+        serving,
+        responseTimeMs,
+      },
+      error:
+        response.error ?? (serving ? undefined : `Status: ${response.status}`),
+    };
+  }
+
+  aggregateResult(
+    runs: HealthCheckRunForAggregation<HealthResult>[]
+  ): HealthAggregatedResult {
+    const times = runs
+      .map((r) => r.metadata?.responseTimeMs)
+      .filter((v): v is number => typeof v === "number");
+
+    const servingResults = runs
+      .map((r) => r.metadata?.serving)
+      .filter((v): v is boolean => typeof v === "boolean");
+
+    const servingCount = servingResults.filter(Boolean).length;
+
+    return {
+      avgResponseTimeMs:
+        times.length > 0
+          ? Math.round(times.reduce((a, b) => a + b, 0) / times.length)
+          : 0,
+      servingRate:
+        servingResults.length > 0
+          ? Math.round((servingCount / servingResults.length) * 100)
+          : 0,
+    };
+  }
+}

package/src/index.ts

@@ -1,9 +1,7 @@
-import {
-  createBackendPlugin,
-  coreServices,
-} from "@checkstack/backend-api";
+import { createBackendPlugin, coreServices } from "@checkstack/backend-api";
 import { GrpcHealthCheckStrategy } from "./strategy";
 import { pluginMetadata } from "./plugin-metadata";
+import { HealthCollector } from "./health-collector";
 
 export default createBackendPlugin({
   metadata: pluginMetadata,
@@ -11,13 +9,17 @@ export default createBackendPlugin({
     env.registerInit({
       deps: {
         healthCheckRegistry: coreServices.healthCheckRegistry,
+        collectorRegistry: coreServices.collectorRegistry,
         logger: coreServices.logger,
       },
-      init: async ({ healthCheckRegistry, logger }) => {
+      init: async ({ healthCheckRegistry, collectorRegistry, logger }) => {
         logger.debug("🔌 Registering gRPC Health Check Strategy...");
         const strategy = new GrpcHealthCheckStrategy();
         healthCheckRegistry.register(strategy);
+        collectorRegistry.register(new HealthCollector());
       },
     });
   },
 });
+
+export { pluginMetadata } from "./plugin-metadata";

package/src/strategy.test.ts

@@ -2,14 +2,14 @@ import { describe, expect, it, mock } from "bun:test";
 import {
   GrpcHealthCheckStrategy,
   GrpcHealthClient,
-  GrpcHealthStatus,
+  GrpcHealthStatusType,
 } from "./strategy";
 
 describe("GrpcHealthCheckStrategy", () => {
   // Helper to create mock gRPC client
   const createMockClient = (
     config: {
-      status?: GrpcHealthStatus;
+      status?: GrpcHealthStatusType;
       error?: Error;
     } = {}
   ): GrpcHealthClient => ({
@@ -20,127 +20,94 @@ describe("GrpcHealthCheckStrategy", () => {
     ),
   });
 
-  describe("execute", () => {
-    it("should return healthy for SERVING status", async () => {
+  describe("createClient", () => {
+    it("should return a connected client", async () => {
       const strategy = new GrpcHealthCheckStrategy(createMockClient());
 
-      const result = await strategy.execute({
+      const connectedClient = await strategy.createClient({
         host: "localhost",
         port: 50051,
         timeout: 5000,
       });
 
-      expect(result.status).toBe("healthy");
-      expect(result.metadata?.connected).toBe(true);
-      expect(result.metadata?.status).toBe("SERVING");
+      expect(connectedClient.client).toBeDefined();
+      expect(connectedClient.client.exec).toBeDefined();
+      expect(connectedClient.close).toBeDefined();
+
+      connectedClient.close();
     });
+  });
 
-    it("should return unhealthy for NOT_SERVING status", async () => {
-      const strategy = new GrpcHealthCheckStrategy(
-        createMockClient({ status: "NOT_SERVING" })
-      );
+  describe("client.exec (health check action)", () => {
+    it("should return SERVING status for healthy service", async () => {
+      const strategy = new GrpcHealthCheckStrategy(createMockClient());
 
-      const result = await strategy.execute({
+      const connectedClient = await strategy.createClient({
         host: "localhost",
         port: 50051,
         timeout: 5000,
       });
 
-      expect(result.status).toBe("unhealthy");
-      expect(result.message).toContain("NOT_SERVING");
-      expect(result.metadata?.status).toBe("NOT_SERVING");
-    });
+      const result = await connectedClient.client.exec({ service: "" });
 
-    it("should return unhealthy for SERVICE_UNKNOWN status", async () => {
-      const strategy = new GrpcHealthCheckStrategy(
-        createMockClient({ status: "SERVICE_UNKNOWN" })
-      );
+      expect(result.status).toBe("SERVING");
 
-      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");
+      connectedClient.close();
     });
 
-    it("should return unhealthy for connection error", async () => {
+    it("should return NOT_SERVING status for unhealthy service", async () => {
       const strategy = new GrpcHealthCheckStrategy(
-        createMockClient({ error: new Error("Connection refused") })
+        createMockClient({ status: "NOT_SERVING" })
       );
 
-      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({
+      const connectedClient = await strategy.createClient({
         host: "localhost",
         port: 50051,
         timeout: 5000,
-        assertions: [
-          { field: "responseTime", operator: "lessThan", value: 5000 },
-        ],
       });
 
-      expect(result.status).toBe("healthy");
-    });
+      const result = await connectedClient.client.exec({ service: "" });
 
-    it("should pass status assertion", async () => {
-      const strategy = new GrpcHealthCheckStrategy(createMockClient());
+      expect(result.status).toBe("NOT_SERVING");
 
-      const result = await strategy.execute({
-        host: "localhost",
-        port: 50051,
-        timeout: 5000,
-        assertions: [{ field: "status", operator: "equals", value: "SERVING" }],
-      });
-
-      expect(result.status).toBe("healthy");
+      connectedClient.close();
     });
 
-    it("should fail status assertion when not matching", async () => {
+    it("should return error for connection failure", async () => {
       const strategy = new GrpcHealthCheckStrategy(
-        createMockClient({ status: "NOT_SERVING" })
+        createMockClient({ error: new Error("Connection refused") })
       );
 
-      const result = await strategy.execute({
+      const connectedClient = await strategy.createClient({
         host: "localhost",
         port: 50051,
         timeout: 5000,
-        assertions: [{ field: "status", operator: "equals", value: "SERVING" }],
       });
 
-      expect(result.status).toBe("unhealthy");
-      expect(result.message).toContain("Assertion failed");
+      const result = await connectedClient.client.exec({ service: "" });
+
+      expect(result.error).toContain("Connection refused");
+
+      connectedClient.close();
     });
 
     it("should check specific service", async () => {
       const mockClient = createMockClient();
       const strategy = new GrpcHealthCheckStrategy(mockClient);
 
-      await strategy.execute({
+      const connectedClient = await strategy.createClient({
         host: "localhost",
         port: 50051,
-        service: "my.custom.Service",
         timeout: 5000,
       });
 
+      await connectedClient.client.exec({ service: "my.custom.Service" });
+
       expect(mockClient.check).toHaveBeenCalledWith(
         expect.objectContaining({ service: "my.custom.Service" })
       );
+
+      connectedClient.close();
     });
   });
 

package/src/strategy.ts

@@ -1,19 +1,21 @@
 import * as grpc from "@grpc/grpc-js";
 import {
   HealthCheckStrategy,
-  HealthCheckResult,
   HealthCheckRunForAggregation,
   Versioned,
   z,
-  timeThresholdField,
-  enumField,
-  evaluateAssertions,
+  type ConnectedClient,
 } from "@checkstack/backend-api";
 import {
   healthResultBoolean,
   healthResultNumber,
   healthResultString,
 } from "@checkstack/healthcheck-common";
+import type {
+  GrpcTransportClient,
+  GrpcHealthRequest,
+  GrpcHealthResponse,
+} from "./transport-client";
 
 // ============================================================================
 // SCHEMAS
@@ -21,26 +23,15 @@ import {
 
 /**
  * gRPC Health Checking Protocol status values
- * https://github.com/grpc/grpc/blob/master/doc/health-checking.md
  */
-const GrpcHealthStatus = z.enum([
+export 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>;
+export type GrpcHealthStatusType = z.infer<typeof GrpcHealthStatus>;
 
 /**
  * Configuration schema for gRPC health checks.
@@ -51,17 +42,13 @@ export const grpcConfigSchema = z.object({
   service: z
     .string()
     .default("")
-    .describe("Service name to check (empty for overall server health)"),
-  useTls: z.boolean().default(false).describe("Use TLS/SSL connection"),
+    .describe("Service name to check (empty for server health)"),
+  useTls: z.boolean().default(false).describe("Use TLS 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>;
@@ -80,18 +67,17 @@ const grpcResultSchema = z.object({
     "x-chart-label": "Response Time",
     "x-chart-unit": "ms",
   }),
-  status: GrpcHealthStatus.meta({
+  status: healthResultString({
     "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>;
+type GrpcResult = z.infer<typeof grpcResultSchema>;
 
 /**
  * Aggregated metadata for buckets.
@@ -117,7 +103,7 @@ const grpcAggregatedSchema = z.object({
   }),
 });
 
-export type GrpcAggregatedResult = z.infer<typeof grpcAggregatedSchema>;
+type GrpcAggregatedResult = z.infer<typeof grpcAggregatedSchema>;
 
 // ============================================================================
 // GRPC CLIENT INTERFACE (for testability)
@@ -130,60 +116,56 @@ export interface GrpcHealthClient {
     service: string;
     useTls: boolean;
     timeout: number;
-  }): Promise<{ status: GrpcHealthStatus }>;
+  }): Promise<{ status: GrpcHealthStatusType }>;
 }
 
 // Default client using @grpc/grpc-js
 const defaultGrpcClient: GrpcHealthClient = {
-  async check(options) {
+  check(options) {
     return new Promise((resolve, reject) => {
+      const address = `${options.host}:${options.port}`;
       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 client = new grpc.Client(address, credentials);
+
+      // Use the standard gRPC Health Checking Protocol
+      const healthCheckPath = "/grpc.health.v1.Health/Check";
+
+      const methodDefinition: grpc.MethodDefinition<
+        { service: string },
+        { status: number }
+      > = {
+        path: healthCheckPath,
+        requestStream: false,
+        responseStream: false,
+        requestSerialize: (message: { service: string }) =>
+          Buffer.from(JSON.stringify(message)),
+        requestDeserialize: (data: Buffer) => JSON.parse(data.toString()),
+        responseSerialize: (message: { status: number }) =>
+          Buffer.from(JSON.stringify(message)),
+        responseDeserialize: (data: Buffer) => JSON.parse(data.toString()),
+      };
 
       const deadline = new Date(Date.now() + options.timeout);
 
-      client.Check(
+      client.makeUnaryRequest(
+        methodDefinition.path,
+        methodDefinition.requestSerialize,
+        methodDefinition.responseDeserialize,
         { service: options.service },
         { deadline },
-        (
-          err: grpc.ServiceError | null,
-          response: { status: number } | undefined
-        ) => {
+        (error, response) => {
           client.close();
 
-          if (err) {
-            reject(err);
+          if (error) {
+            reject(error);
             return;
           }
 
-          // Map status number to enum
-          const statusMap: Record<number, GrpcHealthStatus> = {
+          // Map status codes to enum values
+          const statusMap: Record<number, GrpcHealthStatusType> = {
             0: "UNKNOWN",
             1: "SERVING",
             2: "NOT_SERVING",
@@ -204,7 +186,13 @@ const defaultGrpcClient: GrpcHealthClient = {
 // ============================================================================
 
 export class GrpcHealthCheckStrategy
-  implements HealthCheckStrategy<GrpcConfig, GrpcResult, GrpcAggregatedResult>
+  implements
+    HealthCheckStrategy<
+      GrpcConfig,
+      GrpcTransportClient,
+      GrpcResult,
+      GrpcAggregatedResult
+    >
 {
   id = "grpc";
   displayName = "gRPC Health Check";
@@ -218,13 +206,29 @@ export class GrpcHealthCheckStrategy
   }
 
   config: Versioned<GrpcConfig> = new Versioned({
-    version: 1,
+    version: 2, // Bumped for createClient pattern
     schema: grpcConfigSchema,
+    migrations: [
+      {
+        fromVersion: 1,
+        toVersion: 2,
+        description: "Migrate to createClient pattern (no config changes)",
+        migrate: (data: unknown) => data,
+      },
+    ],
   });
 
   result: Versioned<GrpcResult> = new Versioned({
-    version: 1,
+    version: 2,
     schema: grpcResultSchema,
+    migrations: [
+      {
+        fromVersion: 1,
+        toVersion: 2,
+        description: "Migrate to createClient pattern (no result changes)",
+        migrate: (data: unknown) => data,
+      },
+    ],
   });
 
   aggregatedResult: Versioned<GrpcAggregatedResult> = new Versioned({
@@ -235,109 +239,74 @@ export class GrpcHealthCheckStrategy
   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++;
-      }
+    const validRuns = runs.filter((r) => r.metadata);
+
+    if (validRuns.length === 0) {
+      return {
+        avgResponseTime: 0,
+        successRate: 0,
+        errorCount: 0,
+        servingCount: 0,
+      };
     }
 
+    const responseTimes = validRuns
+      .map((r) => r.metadata?.responseTimeMs)
+      .filter((t): t is number => typeof t === "number");
+
+    const avgResponseTime =
+      responseTimes.length > 0
+        ? Math.round(
+            responseTimes.reduce((a, b) => a + b, 0) / responseTimes.length
+          )
+        : 0;
+
+    const servingCount = validRuns.filter(
+      (r) => r.metadata?.status === "SERVING"
+    ).length;
+    const successRate = Math.round((servingCount / validRuns.length) * 100);
+
+    const errorCount = validRuns.filter(
+      (r) => r.metadata?.error !== undefined
+    ).length;
+
     return {
-      avgResponseTime: validRuns > 0 ? totalResponseTime / validRuns : 0,
-      successRate: runs.length > 0 ? (successCount / runs.length) * 100 : 0,
+      avgResponseTime,
+      successRate,
       errorCount,
       servingCount,
     };
   }
 
-  async execute(
+  async createClient(
     config: GrpcConfigInput
-  ): Promise<HealthCheckResult<GrpcResult>> {
+  ): Promise<ConnectedClient<GrpcTransportClient>> {
     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,
-        };
-      }
+    const client: GrpcTransportClient = {
+      exec: async (request: GrpcHealthRequest): Promise<GrpcHealthResponse> => {
+        try {
+          const result = await this.grpcClient.check({
+            host: validatedConfig.host,
+            port: validatedConfig.port,
+            service: request.service,
+            useTls: validatedConfig.useTls,
+            timeout: validatedConfig.timeout,
+          });
+          return { status: result.status };
+        } catch (error_) {
+          const error =
+            error_ instanceof Error ? error_.message : String(error_);
+          return { status: "UNKNOWN", error };
+        }
+      },
+    };
 
-      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",
-        },
-      };
-    }
+    return {
+      client,
+      close: () => {
+        // gRPC client is per-request, nothing to close
+      },
+    };
   }
 }

package/src/transport-client.ts

@@ -0,0 +1,24 @@
+import type { TransportClient } from "@checkstack/common";
+
+/**
+ * gRPC health check request.
+ */
+export interface GrpcHealthRequest {
+  service: string;
+}
+
+/**
+ * gRPC health check response.
+ */
+export interface GrpcHealthResponse {
+  status: "UNKNOWN" | "SERVING" | "NOT_SERVING" | "SERVICE_UNKNOWN";
+  error?: string;
+}
+
+/**
+ * gRPC transport client for health checks.
+ */
+export type GrpcTransportClient = TransportClient<
+  GrpcHealthRequest,
+  GrpcHealthResponse
+>;