@checkstack/healthcheck-jenkins-backend 0.2.0

package/src/strategy.test.ts

@@ -0,0 +1,198 @@
+import { describe, expect, it, spyOn, afterEach } from "bun:test";
+import { JenkinsHealthCheckStrategy } from "./strategy";
+
+describe("JenkinsHealthCheckStrategy", () => {
+  const strategy = new JenkinsHealthCheckStrategy();
+
+  afterEach(() => {
+    spyOn(globalThis, "fetch").mockRestore();
+  });
+
+  describe("createClient", () => {
+    it("should return a connected client with exec function", async () => {
+      const connectedClient = await strategy.createClient({
+        baseUrl: "https://jenkins.example.com",
+        username: "admin",
+        apiToken: "api-token-123",
+        timeout: 5000,
+      });
+
+      expect(connectedClient.client).toBeDefined();
+      expect(connectedClient.client.exec).toBeDefined();
+      expect(connectedClient.close).toBeDefined();
+    });
+
+    it("should allow closing the client without error", async () => {
+      const connectedClient = await strategy.createClient({
+        baseUrl: "https://jenkins.example.com",
+        username: "admin",
+        apiToken: "api-token-123",
+        timeout: 5000,
+      });
+
+      expect(() => connectedClient.close()).not.toThrow();
+    });
+  });
+
+  describe("client.exec", () => {
+    it("should return successful response for valid request", async () => {
+      spyOn(globalThis, "fetch").mockResolvedValue(
+        new Response(JSON.stringify({ mode: "NORMAL", numExecutors: 2 }), {
+          status: 200,
+          statusText: "OK",
+          headers: { "X-Jenkins": "2.426.1" },
+        })
+      );
+
+      const connectedClient = await strategy.createClient({
+        baseUrl: "https://jenkins.example.com",
+        username: "admin",
+        apiToken: "api-token-123",
+        timeout: 5000,
+      });
+
+      const result = await connectedClient.client.exec({
+        path: "/api/json",
+      });
+
+      expect(result.statusCode).toBe(200);
+      expect(result.error).toBeUndefined();
+      expect(result.jenkinsVersion).toBe("2.426.1");
+      expect(result.data).toEqual({ mode: "NORMAL", numExecutors: 2 });
+
+      connectedClient.close();
+    });
+
+    it("should include query parameters in request", async () => {
+      let capturedUrl = "";
+      spyOn(globalThis, "fetch").mockImplementation((async (
+        url: RequestInfo | URL
+      ) => {
+        capturedUrl = url.toString();
+        return new Response(JSON.stringify({}), { status: 200 });
+      }) as unknown as typeof fetch);
+
+      const connectedClient = await strategy.createClient({
+        baseUrl: "https://jenkins.example.com",
+        username: "admin",
+        apiToken: "api-token-123",
+        timeout: 5000,
+      });
+
+      await connectedClient.client.exec({
+        path: "/api/json",
+        query: { tree: "jobs[name,color]" },
+      });
+
+      expect(capturedUrl).toContain("/api/json?");
+      expect(capturedUrl).toContain("tree=jobs%5Bname%2Ccolor%5D");
+
+      connectedClient.close();
+    });
+
+    it("should send Basic Auth header", async () => {
+      let capturedHeaders: Record<string, string> | undefined;
+      spyOn(globalThis, "fetch").mockImplementation((async (
+        _url: RequestInfo | URL,
+        options?: RequestInit
+      ) => {
+        capturedHeaders = options?.headers as Record<string, string>;
+        return new Response(JSON.stringify({}), { status: 200 });
+      }) as unknown as typeof fetch);
+
+      const connectedClient = await strategy.createClient({
+        baseUrl: "https://jenkins.example.com",
+        username: "admin",
+        apiToken: "api-token-123",
+        timeout: 5000,
+      });
+
+      await connectedClient.client.exec({ path: "/api/json" });
+
+      expect(capturedHeaders?.["Authorization"]).toContain("Basic ");
+      const decoded = Buffer.from(
+        capturedHeaders?.["Authorization"]?.replace("Basic ", "") || "",
+        "base64"
+      ).toString();
+      expect(decoded).toBe("admin:api-token-123");
+
+      connectedClient.close();
+    });
+
+    it("should return error for HTTP error response", async () => {
+      spyOn(globalThis, "fetch").mockResolvedValue(
+        new Response(null, { status: 401, statusText: "Unauthorized" })
+      );
+
+      const connectedClient = await strategy.createClient({
+        baseUrl: "https://jenkins.example.com",
+        username: "admin",
+        apiToken: "wrong-token",
+        timeout: 5000,
+      });
+
+      const result = await connectedClient.client.exec({ path: "/api/json" });
+
+      expect(result.statusCode).toBe(401);
+      expect(result.error).toBe("HTTP 401: Unauthorized");
+      expect(result.data).toBeUndefined();
+
+      connectedClient.close();
+    });
+
+    it("should return error for network failure", async () => {
+      spyOn(globalThis, "fetch").mockRejectedValue(new Error("Network error"));
+
+      const connectedClient = await strategy.createClient({
+        baseUrl: "https://jenkins.example.com",
+        username: "admin",
+        apiToken: "api-token-123",
+        timeout: 5000,
+      });
+
+      const result = await connectedClient.client.exec({ path: "/api/json" });
+
+      expect(result.statusCode).toBe(0);
+      expect(result.error).toBe("Network error");
+      expect(result.data).toBeUndefined();
+
+      connectedClient.close();
+    });
+  });
+
+  describe("aggregateResult", () => {
+    it("should calculate success rate from runs", () => {
+      const runs: Parameters<typeof strategy.aggregateResult>[0] = [
+        {
+          status: "healthy" as const,
+          latencyMs: 100,
+          metadata: { connected: true, responseTimeMs: 150 },
+        },
+        {
+          status: "healthy" as const,
+          latencyMs: 200,
+          metadata: { connected: true, responseTimeMs: 200 },
+        },
+        {
+          status: "unhealthy" as const,
+          latencyMs: 50,
+          metadata: { connected: false, error: "Connection failed" },
+        },
+      ];
+
+      const aggregated = strategy.aggregateResult(runs);
+
+      expect(aggregated.successRate).toBe(67); // 2/3
+      expect(aggregated.avgResponseTimeMs).toBe(175); // (150+200)/2
+      expect(aggregated.errorCount).toBe(1);
+    });
+
+    it("should handle empty runs", () => {
+      const aggregated = strategy.aggregateResult([]);
+
+      expect(aggregated.successRate).toBe(0);
+      expect(aggregated.avgResponseTimeMs).toBe(0);
+      expect(aggregated.errorCount).toBe(0);
+    });
+  });
+});

package/src/strategy.ts

@@ -0,0 +1,228 @@
+import {
+  HealthCheckStrategy,
+  HealthCheckRunForAggregation,
+  Versioned,
+  z,
+  configString,
+  configNumber,
+  type ConnectedClient,
+} from "@checkstack/backend-api";
+import {
+  healthResultNumber,
+  healthResultString,
+} from "@checkstack/healthcheck-common";
+import type {
+  JenkinsTransportClient,
+  JenkinsRequest,
+  JenkinsResponse,
+} from "./transport-client";
+
+// ============================================================================
+// SCHEMAS
+// ============================================================================
+
+/**
+ * Jenkins health check configuration schema.
+ * Provides connectivity settings for the Jenkins API.
+ */
+export const jenkinsConfigSchema = z.object({
+  baseUrl: z
+    .string()
+    .url()
+    .describe("Jenkins server URL (e.g., https://jenkins.example.com)"),
+  username: configString({}).describe(
+    "Jenkins username for API authentication"
+  ),
+  apiToken: configString({ "x-secret": true }).describe(
+    "Jenkins API token (generate from User > Configure > API Token)"
+  ),
+  timeout: configNumber({})
+    .int()
+    .min(1000)
+    .default(30_000)
+    .describe("Request timeout in milliseconds"),
+});
+
+export type JenkinsConfig = z.infer<typeof jenkinsConfigSchema>;
+
+/** Per-run result metadata */
+const jenkinsResultSchema = z.object({
+  connected: z.boolean().meta({
+    "x-chart-type": "boolean",
+    "x-chart-label": "Connected",
+  }),
+  responseTimeMs: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Response Time",
+    "x-chart-unit": "ms",
+  }).optional(),
+  error: healthResultString({
+    "x-chart-type": "status",
+    "x-chart-label": "Error",
+  }).optional(),
+});
+
+type JenkinsResult = z.infer<typeof jenkinsResultSchema>;
+
+/** Aggregated metadata for buckets */
+const jenkinsAggregatedSchema = z.object({
+  successRate: healthResultNumber({
+    "x-chart-type": "gauge",
+    "x-chart-label": "Success Rate",
+    "x-chart-unit": "%",
+  }),
+  avgResponseTimeMs: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Avg Response Time",
+    "x-chart-unit": "ms",
+  }),
+  errorCount: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Errors",
+  }),
+});
+
+type JenkinsAggregatedResult = z.infer<typeof jenkinsAggregatedSchema>;
+
+// ============================================================================
+// STRATEGY
+// ============================================================================
+
+export class JenkinsHealthCheckStrategy
+  implements
+    HealthCheckStrategy<
+      JenkinsConfig,
+      JenkinsTransportClient,
+      JenkinsResult,
+      JenkinsAggregatedResult
+    >
+{
+  id = "jenkins";
+  displayName = "Jenkins Health Check";
+  description = "Monitor Jenkins CI/CD server health and job status";
+
+  config: Versioned<JenkinsConfig> = new Versioned({
+    version: 1,
+    schema: jenkinsConfigSchema,
+  });
+
+  result: Versioned<JenkinsResult> = new Versioned({
+    version: 1,
+    schema: jenkinsResultSchema,
+  });
+
+  aggregatedResult: Versioned<JenkinsAggregatedResult> = new Versioned({
+    version: 1,
+    schema: jenkinsAggregatedSchema,
+  });
+
+  /**
+   * Create a Jenkins transport client for API requests.
+   */
+  async createClient(
+    config: JenkinsConfig
+  ): Promise<ConnectedClient<JenkinsTransportClient>> {
+    const validatedConfig = this.config.validate(config);
+    const baseUrl = validatedConfig.baseUrl.replace(/\/$/, ""); // Remove trailing slash
+
+    // Create Basic Auth header
+    const authHeader = `Basic ${Buffer.from(
+      `${validatedConfig.username}:${validatedConfig.apiToken}`
+    ).toString("base64")}`;
+
+    const client: JenkinsTransportClient = {
+      async exec(request: JenkinsRequest): Promise<JenkinsResponse> {
+        // Build URL with query params
+        let url = `${baseUrl}${request.path}`;
+        if (request.query && Object.keys(request.query).length > 0) {
+          const params = new URLSearchParams(request.query);
+          url += `?${params.toString()}`;
+        }
+
+        const controller = new AbortController();
+        const timeoutId = setTimeout(
+          () => controller.abort(),
+          validatedConfig.timeout
+        );
+
+        try {
+          const response = await fetch(url, {
+            method: "GET",
+            headers: {
+              Authorization: authHeader,
+              Accept: "application/json",
+            },
+            signal: controller.signal,
+          });
+
+          clearTimeout(timeoutId);
+
+          // Get Jenkins version from header
+          const jenkinsVersion = response.headers.get("X-Jenkins") || undefined;
+
+          if (!response.ok) {
+            return {
+              statusCode: response.status,
+              data: undefined,
+              error: `HTTP ${response.status}: ${response.statusText}`,
+              jenkinsVersion,
+            };
+          }
+
+          const data = await response.json();
+
+          return {
+            statusCode: response.status,
+            data,
+            jenkinsVersion,
+          };
+        } catch (error) {
+          clearTimeout(timeoutId);
+
+          const errorMessage =
+            error instanceof Error ? error.message : String(error);
+          return {
+            statusCode: 0,
+            data: undefined,
+            error: errorMessage,
+          };
+        }
+      },
+    };
+
+    return {
+      client,
+      close: () => {
+        // HTTP is stateless, nothing to close
+      },
+    };
+  }
+
+  aggregateResult(
+    runs: HealthCheckRunForAggregation<JenkinsResult>[]
+  ): JenkinsAggregatedResult {
+    const validRuns = runs.filter((r) => r.metadata);
+
+    if (validRuns.length === 0) {
+      return { successRate: 0, avgResponseTimeMs: 0, errorCount: 0 };
+    }
+
+    const responseTimes = validRuns
+      .map((r) => r.metadata?.responseTimeMs)
+      .filter((t): t is number => typeof t === "number");
+
+    const successCount = validRuns.filter((r) => r.metadata?.connected).length;
+    const errorCount = validRuns.filter((r) => r.metadata?.error).length;
+
+    return {
+      successRate: Math.round((successCount / validRuns.length) * 100),
+      avgResponseTimeMs:
+        responseTimes.length > 0
+          ? Math.round(
+              responseTimes.reduce((a, b) => a + b, 0) / responseTimes.length
+            )
+          : 0,
+      errorCount,
+    };
+  }
+}

package/src/transport-client.ts

@@ -0,0 +1,38 @@
+import type { TransportClient } from "@checkstack/common";
+
+// ============================================================================
+// JENKINS TRANSPORT TYPES
+// ============================================================================
+
+/**
+ * Jenkins API request configuration.
+ */
+export interface JenkinsRequest {
+  /** API path relative to base URL (e.g., "/api/json", "/job/my-job/api/json") */
+  path: string;
+  /** Optional query parameters (e.g., { tree: "jobs[name,color]" }) */
+  query?: Record<string, string>;
+}
+
+/**
+ * Jenkins API response result.
+ */
+export interface JenkinsResponse {
+  /** HTTP status code */
+  statusCode: number;
+  /** Parsed JSON response data */
+  data: unknown;
+  /** Error message if request failed */
+  error?: string;
+  /** Jenkins version from X-Jenkins header */
+  jenkinsVersion?: string;
+}
+
+/**
+ * Jenkins transport client type.
+ * Requests are API paths with optional query params, results include parsed JSON.
+ */
+export type JenkinsTransportClient = TransportClient<
+  JenkinsRequest,
+  JenkinsResponse
+>;

package/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "@checkstack/tsconfig/backend.json"
+}