@checkstack/healthcheck-tcp-backend 0.0.2 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # @checkstack/healthcheck-tcp-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-tcp-backend",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "type": "module",
   "main": "src/index.ts",
   "scripts": {

package/src/banner-collector.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, it, mock } from "bun:test";
+import { BannerCollector, type BannerConfig } from "./banner-collector";
+import type { TcpTransportClient } from "./transport-client";
+
+describe("BannerCollector", () => {
+  const createMockClient = (
+    response: {
+      banner?: string;
+      connected?: boolean;
+      error?: string;
+    } = {}
+  ): TcpTransportClient => ({
+    exec: mock(() =>
+      Promise.resolve({
+        banner: response.banner,
+        connected: response.connected ?? true,
+        error: response.error,
+      })
+    ),
+  });
+
+  describe("execute", () => {
+    it("should read banner successfully", async () => {
+      const collector = new BannerCollector();
+      const client = createMockClient({ banner: "SSH-2.0-OpenSSH_8.9" });
+
+      const result = await collector.execute({
+        config: { timeout: 5000 },
+        client,
+        pluginId: "test",
+      });
+
+      expect(result.result.banner).toBe("SSH-2.0-OpenSSH_8.9");
+      expect(result.result.hasBanner).toBe(true);
+      expect(result.result.readTimeMs).toBeGreaterThanOrEqual(0);
+    });
+
+    it("should return hasBanner false when no banner", async () => {
+      const collector = new BannerCollector();
+      const client = createMockClient({ banner: undefined });
+
+      const result = await collector.execute({
+        config: { timeout: 5000 },
+        client,
+        pluginId: "test",
+      });
+
+      expect(result.result.hasBanner).toBe(false);
+    });
+
+    it("should pass correct parameters to client", async () => {
+      const collector = new BannerCollector();
+      const client = createMockClient();
+
+      await collector.execute({
+        config: { timeout: 3000 },
+        client,
+        pluginId: "test",
+      });
+
+      expect(client.exec).toHaveBeenCalledWith({
+        type: "read",
+        timeout: 3000,
+      });
+    });
+  });
+
+  describe("aggregateResult", () => {
+    it("should calculate average read time and banner rate", () => {
+      const collector = new BannerCollector();
+      const runs = [
+        {
+          id: "1",
+          status: "healthy" as const,
+          latencyMs: 10,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: { banner: "SSH-2.0", hasBanner: true, readTimeMs: 50 },
+        },
+        {
+          id: "2",
+          status: "healthy" as const,
+          latencyMs: 15,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: { hasBanner: false, readTimeMs: 100 },
+        },
+      ];
+
+      const aggregated = collector.aggregateResult(runs);
+
+      expect(aggregated.avgReadTimeMs).toBe(75);
+      expect(aggregated.bannerRate).toBe(50);
+    });
+  });
+
+  describe("metadata", () => {
+    it("should have correct static properties", () => {
+      const collector = new BannerCollector();
+
+      expect(collector.id).toBe("banner");
+      expect(collector.displayName).toBe("TCP Banner");
+      expect(collector.allowMultiple).toBe(false);
+      expect(collector.supportedPlugins).toHaveLength(1);
+    });
+  });
+});

package/src/banner-collector.ts

@@ -0,0 +1,149 @@
+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 { TcpTransportClient } from "./transport-client";
+
+// ============================================================================
+// CONFIGURATION SCHEMA
+// ============================================================================
+
+const bannerConfigSchema = z.object({
+  timeout: z
+    .number()
+    .min(100)
+    .default(5000)
+    .describe("Timeout for banner read in milliseconds"),
+});
+
+export type BannerConfig = z.infer<typeof bannerConfigSchema>;
+
+// ============================================================================
+// RESULT SCHEMAS
+// ============================================================================
+
+const bannerResultSchema = z.object({
+  banner: healthResultString({
+    "x-chart-type": "text",
+    "x-chart-label": "Banner",
+  }).optional(),
+  hasBanner: healthResultBoolean({
+    "x-chart-type": "boolean",
+    "x-chart-label": "Has Banner",
+  }),
+  readTimeMs: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Read Time",
+    "x-chart-unit": "ms",
+  }),
+});
+
+export type BannerResult = z.infer<typeof bannerResultSchema>;
+
+const bannerAggregatedSchema = z.object({
+  avgReadTimeMs: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Avg Read Time",
+    "x-chart-unit": "ms",
+  }),
+  bannerRate: healthResultNumber({
+    "x-chart-type": "gauge",
+    "x-chart-label": "Banner Rate",
+    "x-chart-unit": "%",
+  }),
+});
+
+export type BannerAggregatedResult = z.infer<typeof bannerAggregatedSchema>;
+
+// ============================================================================
+// BANNER COLLECTOR
+// ============================================================================
+
+/**
+ * Built-in TCP banner collector.
+ * Reads the initial banner/greeting from a TCP server.
+ */
+export class BannerCollector
+  implements
+    CollectorStrategy<
+      TcpTransportClient,
+      BannerConfig,
+      BannerResult,
+      BannerAggregatedResult
+    >
+{
+  id = "banner";
+  displayName = "TCP Banner";
+  description = "Read the initial banner/greeting from the server";
+
+  supportedPlugins = [pluginMetadata];
+
+  allowMultiple = false;
+
+  config = new Versioned({ version: 1, schema: bannerConfigSchema });
+  result = new Versioned({ version: 1, schema: bannerResultSchema });
+  aggregatedResult = new Versioned({
+    version: 1,
+    schema: bannerAggregatedSchema,
+  });
+
+  async execute({
+    config,
+    client,
+  }: {
+    config: BannerConfig;
+    client: TcpTransportClient;
+    pluginId: string;
+  }): Promise<CollectorResult<BannerResult>> {
+    const startTime = Date.now();
+
+    const response = await client.exec({
+      type: "read",
+      timeout: config.timeout,
+    });
+
+    const readTimeMs = Date.now() - startTime;
+
+    return {
+      result: {
+        banner: response.banner,
+        hasBanner: !!response.banner,
+        readTimeMs,
+      },
+    };
+  }
+
+  aggregateResult(
+    runs: HealthCheckRunForAggregation<BannerResult>[]
+  ): BannerAggregatedResult {
+    const times = runs
+      .map((r) => r.metadata?.readTimeMs)
+      .filter((v): v is number => typeof v === "number");
+
+    const hasBanners = runs
+      .map((r) => r.metadata?.hasBanner)
+      .filter((v): v is boolean => typeof v === "boolean");
+
+    const bannerCount = hasBanners.filter(Boolean).length;
+
+    return {
+      avgReadTimeMs:
+        times.length > 0
+          ? Math.round(times.reduce((a, b) => a + b, 0) / times.length)
+          : 0,
+      bannerRate:
+        hasBanners.length > 0
+          ? Math.round((bannerCount / hasBanners.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 { TcpHealthCheckStrategy } from "./strategy";
 import { pluginMetadata } from "./plugin-metadata";
+import { BannerCollector } from "./banner-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 TCP Health Check Strategy...");
         const strategy = new TcpHealthCheckStrategy();
         healthCheckRegistry.register(strategy);
+        collectorRegistry.register(new BannerCollector());
       },
     });
   },
 });
+
+export { pluginMetadata } from "./plugin-metadata";

package/src/strategy.test.ts

@@ -21,120 +21,72 @@ describe("TcpHealthCheckStrategy", () => {
       } as TcpSocket);
   };
 
-  describe("execute", () => {
-    it("should return healthy for successful connection", async () => {
+  describe("createClient", () => {
+    it("should return a connected client for successful connection", async () => {
       const strategy = new TcpHealthCheckStrategy(createMockSocket());
 
-      const result = await strategy.execute({
+      const connectedClient = await strategy.createClient({
         host: "localhost",
         port: 80,
         timeout: 5000,
-        readBanner: false,
       });
 
-      expect(result.status).toBe("healthy");
-      expect(result.metadata?.connected).toBe(true);
-      expect(result.metadata?.connectionTimeMs).toBeDefined();
-    });
-
-    it("should return unhealthy for connection error", async () => {
-      const strategy = new TcpHealthCheckStrategy(
-        createMockSocket({ connectError: new Error("Connection refused") })
-      );
+      expect(connectedClient.client).toBeDefined();
+      expect(connectedClient.client.exec).toBeDefined();
+      expect(connectedClient.close).toBeDefined();
 
-      const result = await strategy.execute({
-        host: "localhost",
-        port: 12345,
-        timeout: 5000,
-        readBanner: false,
-      });
-
-      expect(result.status).toBe("unhealthy");
-      expect(result.message).toContain("Connection refused");
-      expect(result.metadata?.connected).toBe(false);
+      connectedClient.close();
     });
 
-    it("should read banner when requested", async () => {
+    it("should throw for connection error", async () => {
       const strategy = new TcpHealthCheckStrategy(
-        createMockSocket({ banner: "SSH-2.0-OpenSSH" })
+        createMockSocket({ connectError: new Error("Connection refused") })
       );
 
-      const result = await strategy.execute({
-        host: "localhost",
-        port: 22,
-        timeout: 5000,
-        readBanner: true,
-      });
-
-      expect(result.status).toBe("healthy");
-      expect(result.metadata?.banner).toBe("SSH-2.0-OpenSSH");
+      await expect(
+        strategy.createClient({
+          host: "localhost",
+          port: 12345,
+          timeout: 5000,
+        })
+      ).rejects.toThrow("Connection refused");
     });
+  });
 
-    it("should pass connectionTime assertion when below threshold", async () => {
+  describe("client.exec", () => {
+    it("should return connected status for connect action", async () => {
       const strategy = new TcpHealthCheckStrategy(createMockSocket());
-
-      const result = await strategy.execute({
+      const connectedClient = await strategy.createClient({
         host: "localhost",
         port: 80,
         timeout: 5000,
-        readBanner: false,
-        assertions: [
-          { field: "connectionTime", operator: "lessThan", value: 1000 },
-        ],
       });
 
-      expect(result.status).toBe("healthy");
-    });
+      const result = await connectedClient.client.exec({ type: "connect" });
 
-    it("should pass banner assertion with matching pattern", async () => {
-      const strategy = new TcpHealthCheckStrategy(
-        createMockSocket({ banner: "SSH-2.0-OpenSSH_8.9" })
-      );
+      expect(result.connected).toBe(true);
 
-      const result = await strategy.execute({
-        host: "localhost",
-        port: 22,
-        timeout: 5000,
-        readBanner: true,
-        assertions: [{ field: "banner", operator: "contains", value: "SSH" }],
-      });
-
-      expect(result.status).toBe("healthy");
+      connectedClient.close();
     });
 
-    it("should fail banner assertion when not matching", async () => {
+    it("should read banner with read action", async () => {
       const strategy = new TcpHealthCheckStrategy(
-        createMockSocket({ banner: "HTTP/1.1 200 OK" })
+        createMockSocket({ banner: "SSH-2.0-OpenSSH" })
       );
-
-      const result = await strategy.execute({
+      const connectedClient = await strategy.createClient({
         host: "localhost",
-        port: 80,
+        port: 22,
         timeout: 5000,
-        readBanner: true,
-        assertions: [{ field: "banner", operator: "contains", value: "SSH" }],
       });
 
-      expect(result.status).toBe("unhealthy");
-      expect(result.message).toContain("Assertion failed");
-    });
-
-    it("should close socket after execution", async () => {
-      const closeMock = mock(() => {});
-      const strategy = new TcpHealthCheckStrategy(() => ({
-        connect: mock(() => Promise.resolve()),
-        read: mock(() => Promise.resolve(undefined)),
-        close: closeMock,
-      }));
-
-      await strategy.execute({
-        host: "localhost",
-        port: 80,
-        timeout: 5000,
-        readBanner: false,
+      const result = await connectedClient.client.exec({
+        type: "read",
+        timeout: 1000,
       });
 
-      expect(closeMock).toHaveBeenCalled();
+      expect(result.banner).toBe("SSH-2.0-OpenSSH");
+
+      connectedClient.close();
     });
   });
 

package/src/strategy.ts

@@ -1,35 +1,28 @@
 import {
   HealthCheckStrategy,
-  HealthCheckResult,
   HealthCheckRunForAggregation,
   Versioned,
   z,
-  timeThresholdField,
-  stringField,
-  evaluateAssertions,
+  type ConnectedClient,
 } from "@checkstack/backend-api";
 import {
   healthResultBoolean,
   healthResultNumber,
   healthResultString,
 } from "@checkstack/healthcheck-common";
+import type {
+  TcpTransportClient,
+  TcpConnectRequest,
+  TcpConnectResult,
+} from "./transport-client";
 
 // ============================================================================
 // SCHEMAS
 // ============================================================================
 
-/**
- * Assertion schema for TCP health checks using shared factories.
- */
-const tcpAssertionSchema = z.discriminatedUnion("field", [
-  timeThresholdField("connectionTime"),
-  stringField("banner"),
-]);
-
-export type TcpAssertion = z.infer<typeof tcpAssertionSchema>;
-
 /**
  * Configuration schema for TCP health checks.
+ * Connection-only parameters - action params moved to BannerCollector.
  */
 export const tcpConfigSchema = z.object({
   host: z.string().describe("Hostname or IP address"),
@@ -39,18 +32,18 @@ export const tcpConfigSchema = z.object({
     .min(100)
     .default(5000)
     .describe("Connection timeout in milliseconds"),
-  readBanner: z
-    .boolean()
-    .default(false)
-    .describe("Read initial banner/greeting from server"),
-  assertions: z
-    .array(tcpAssertionSchema)
-    .optional()
-    .describe("Validation conditions"),
 });
 
 export type TcpConfig = z.infer<typeof tcpConfigSchema>;
 
+// Legacy config type for migrations
+interface TcpConfigV1 {
+  host: string;
+  port: number;
+  timeout: number;
+  readBanner: boolean;
+}
+
 /**
  * Per-run result metadata.
  */
@@ -68,14 +61,13 @@ const tcpResultSchema = z.object({
     "x-chart-type": "text",
     "x-chart-label": "Banner",
   }).optional(),
-  failedAssertion: tcpAssertionSchema.optional(),
   error: healthResultString({
     "x-chart-type": "status",
     "x-chart-label": "Error",
   }).optional(),
 });
 
-export type TcpResult = z.infer<typeof tcpResultSchema>;
+type TcpResult = z.infer<typeof tcpResultSchema>;
 
 /**
  * Aggregated metadata for buckets.
@@ -97,7 +89,7 @@ const tcpAggregatedSchema = z.object({
   }),
 });
 
-export type TcpAggregatedResult = z.infer<typeof tcpAggregatedSchema>;
+type TcpAggregatedResult = z.infer<typeof tcpAggregatedSchema>;
 
 // ============================================================================
 // SOCKET INTERFACE (for testability)
@@ -113,8 +105,8 @@ export type SocketFactory = () => TcpSocket;
 
 // Default factory using Bun.connect
 const defaultSocketFactory: SocketFactory = () => {
-  let socket: Awaited<ReturnType<typeof Bun.connect>> | undefined;
-  let receivedData = "";
+  let connectedSocket: Awaited<ReturnType<typeof Bun.connect>> | undefined;
+  let dataBuffer = "";
 
   return {
     async connect(options: { host: string; port: number }): Promise<void> {
@@ -124,11 +116,11 @@ const defaultSocketFactory: SocketFactory = () => {
           port: options.port,
           socket: {
             open(sock) {
-              socket = sock;
+              connectedSocket = sock;
               resolve();
             },
             data(_sock, data) {
-              receivedData += new TextDecoder().decode(data);
+              dataBuffer += data.toString();
             },
             error(_sock, error) {
               reject(error);
@@ -137,23 +129,27 @@ const defaultSocketFactory: SocketFactory = () => {
               // Connection closed
             },
           },
-        }).catch(reject);
+        });
       });
     },
     async read(timeout: number): Promise<string | undefined> {
-      const start = Date.now();
-      while (Date.now() - start < timeout) {
-        if (receivedData.length > 0) {
-          const data = receivedData;
-          receivedData = "";
-          return data;
-        }
-        await new Promise((r) => setTimeout(r, 50));
-      }
-      return receivedData.length > 0 ? receivedData : undefined;
+      return new Promise((resolve) => {
+        const start = Date.now();
+        const check = () => {
+          if (dataBuffer.length > 0) {
+            resolve(dataBuffer);
+          } else if (Date.now() - start > timeout) {
+            // eslint-disable-next-line unicorn/no-useless-undefined
+            resolve(undefined);
+          } else {
+            setTimeout(check, 50);
+          }
+        };
+        check();
+      });
     },
     close(): void {
-      socket?.end();
+      connectedSocket?.end();
     },
   };
 };
@@ -163,7 +159,13 @@ const defaultSocketFactory: SocketFactory = () => {
 // ============================================================================
 
 export class TcpHealthCheckStrategy
-  implements HealthCheckStrategy<TcpConfig, TcpResult, TcpAggregatedResult>
+  implements
+    HealthCheckStrategy<
+      TcpConfig,
+      TcpTransportClient,
+      TcpResult,
+      TcpAggregatedResult
+    >
 {
   id = "tcp";
   displayName = "TCP Health Check";
@@ -176,13 +178,33 @@ export class TcpHealthCheckStrategy
   }
 
   config: Versioned<TcpConfig> = new Versioned({
-    version: 1,
+    version: 2,
     schema: tcpConfigSchema,
+    migrations: [
+      {
+        fromVersion: 1,
+        toVersion: 2,
+        description: "Remove readBanner (moved to BannerCollector)",
+        migrate: (data: TcpConfigV1): TcpConfig => ({
+          host: data.host,
+          port: data.port,
+          timeout: data.timeout,
+        }),
+      },
+    ],
   });
 
   result: Versioned<TcpResult> = new Versioned({
-    version: 1,
+    version: 2,
     schema: tcpResultSchema,
+    migrations: [
+      {
+        fromVersion: 1,
+        toVersion: 2,
+        description: "Migrate to createClient pattern (no result changes)",
+        migrate: (data: unknown) => data,
+      },
+    ],
   });
 
   aggregatedResult: Versioned<TcpAggregatedResult> = new Versioned({
@@ -193,117 +215,59 @@ export class TcpHealthCheckStrategy
   aggregateResult(
     runs: HealthCheckRunForAggregation<TcpResult>[]
   ): TcpAggregatedResult {
-    let totalConnectionTime = 0;
-    let successCount = 0;
-    let errorCount = 0;
-    let validRuns = 0;
+    const validRuns = runs.filter((r) => r.metadata);
 
-    for (const run of runs) {
-      if (run.metadata?.error) {
-        errorCount++;
-        continue;
-      }
-      if (run.status === "healthy") {
-        successCount++;
-      }
-      if (run.metadata) {
-        totalConnectionTime += run.metadata.connectionTimeMs;
-        validRuns++;
-      }
+    if (validRuns.length === 0) {
+      return { avgConnectionTime: 0, successRate: 0, errorCount: 0 };
     }
 
-    return {
-      avgConnectionTime: validRuns > 0 ? totalConnectionTime / validRuns : 0,
-      successRate: runs.length > 0 ? (successCount / runs.length) * 100 : 0,
-      errorCount,
-    };
-  }
-
-  async execute(config: TcpConfig): Promise<HealthCheckResult<TcpResult>> {
-    const validatedConfig = this.config.validate(config);
-    const start = performance.now();
-
-    const socket = this.socketFactory();
-
-    try {
-      // Set up timeout
-      const timeoutPromise = new Promise<never>((_, reject) => {
-        setTimeout(
-          () => reject(new Error("Connection timeout")),
-          validatedConfig.timeout
-        );
-      });
+    const connectionTimes = validRuns
+      .map((r) => r.metadata?.connectionTimeMs)
+      .filter((t): t is number => typeof t === "number");
 
-      // Connect to host
-      await Promise.race([
-        socket.connect({
-          host: validatedConfig.host,
-          port: validatedConfig.port,
-        }),
-        timeoutPromise,
-      ]);
+    const avgConnectionTime =
+      connectionTimes.length > 0
+        ? Math.round(
+            connectionTimes.reduce((a, b) => a + b, 0) / connectionTimes.length
+          )
+        : 0;
 
-      const connectionTimeMs = Math.round(performance.now() - start);
+    const successCount = validRuns.filter(
+      (r) => r.metadata?.connected === true
+    ).length;
+    const successRate = Math.round((successCount / validRuns.length) * 100);
 
-      // Read banner if requested
-      let banner: string | undefined;
-      if (validatedConfig.readBanner) {
-        const bannerTimeout = Math.max(
-          1000,
-          validatedConfig.timeout - connectionTimeMs
-        );
-        banner = (await socket.read(bannerTimeout)) ?? undefined;
-      }
+    const errorCount = validRuns.filter(
+      (r) => r.metadata?.error !== undefined
+    ).length;
 
-      socket.close();
+    return { avgConnectionTime, successRate, errorCount };
+  }
 
-      const result: Omit<TcpResult, "failedAssertion" | "error"> = {
-        connected: true,
-        connectionTimeMs,
-        banner,
-      };
+  async createClient(
+    config: TcpConfig
+  ): Promise<ConnectedClient<TcpTransportClient>> {
+    const validatedConfig = this.config.validate(config);
+    const socket = this.socketFactory();
 
-      // Evaluate assertions using shared utility
-      const failedAssertion = evaluateAssertions(validatedConfig.assertions, {
-        connectionTime: connectionTimeMs,
-        banner: banner ?? "",
-      });
+    await socket.connect({
+      host: validatedConfig.host,
+      port: validatedConfig.port,
+    });
 
-      if (failedAssertion) {
-        return {
-          status: "unhealthy",
-          latencyMs: connectionTimeMs,
-          message: `Assertion failed: ${failedAssertion.field} ${
-            failedAssertion.operator
-          }${"value" in failedAssertion ? ` ${failedAssertion.value}` : ""}`,
-          metadata: { ...result, failedAssertion },
-        };
-      }
+    const client: TcpTransportClient = {
+      async exec(request: TcpConnectRequest): Promise<TcpConnectResult> {
+        if (request.type === "read" && request.timeout) {
+          const banner = await socket.read(request.timeout);
+          return { connected: true, banner };
+        }
+        return { connected: true };
+      },
+    };
 
-      return {
-        status: "healthy",
-        latencyMs: connectionTimeMs,
-        message: `Connected to ${validatedConfig.host}:${
-          validatedConfig.port
-        } in ${connectionTimeMs}ms${
-          banner ? ` (banner: ${banner.slice(0, 50)}...)` : ""
-        }`,
-        metadata: result,
-      };
-    } catch (error: unknown) {
-      socket.close();
-      const end = performance.now();
-      const isError = error instanceof Error;
-      return {
-        status: "unhealthy",
-        latencyMs: Math.round(end - start),
-        message: isError ? error.message : "TCP connection failed",
-        metadata: {
-          connected: false,
-          connectionTimeMs: Math.round(end - start),
-          error: isError ? error.name : "UnknownError",
-        },
-      };
-    }
+    return {
+      client,
+      close: () => socket.close(),
+    };
   }
 }

package/src/transport-client.ts

@@ -0,0 +1,28 @@
+import type { TransportClient } from "@checkstack/common";
+
+/**
+ * TCP connection request.
+ */
+export interface TcpConnectRequest {
+  /** Action type */
+  type: "connect" | "read";
+  /** Timeout for banner read (optional) */
+  timeout?: number;
+}
+
+/**
+ * TCP connection result.
+ */
+export interface TcpConnectResult {
+  connected: boolean;
+  banner?: string;
+  error?: string;
+}
+
+/**
+ * TCP transport client for connection checks.
+ */
+export type TcpTransportClient = TransportClient<
+  TcpConnectRequest,
+  TcpConnectResult
+>;