@astroscope/health 0.1.0

package/README.md

@@ -0,0 +1,283 @@
+# @astroscope/health
+
+> **Note:** This package is in active development. APIs may change between versions.
+
+Kubernetes-style health check endpoints for Astro SSR. Provides `/livez`, `/readyz`, `/startupz`, and `/healthz` probes on a separate HTTP server.
+
+## Examples
+
+See the [demo/health](../../demo/health) directory for a working example.
+
+## Installation
+
+```bash
+npm install @astroscope/health
+```
+
+## Usage
+
+This package is designed to work with [@astroscope/boot](../boot) for lifecycle management.
+
+```ts
+// src/boot.ts
+import type { BootContext } from "@astroscope/boot";
+import { checks, probes, server } from "@astroscope/health";
+
+export async function onStartup({ dev, host, port }: BootContext) {
+  // start health server on a separate port
+  server.start({ port: 9090 });
+
+  // enable liveness immediately
+  probes.livez.enable();
+
+  // initialize your app...
+  await connectToDatabase();
+
+  // register health checks
+  checks.register("database", () => db.ping());
+
+  // enable startup probe (initialization complete)
+  probes.startupz.enable();
+
+  // enable readiness probe (ready for traffic)
+  probes.readyz.enable();
+}
+
+export async function onShutdown() {
+  // disable readiness first (stop receiving traffic)
+  probes.readyz.disable();
+
+  await disconnectFromDatabase();
+
+  // stop health server
+  await server.stop();
+}
+```
+
+## Probes
+
+### `/livez` — Liveness Probe
+
+Indicates if the process is running. If this fails, Kubernetes will restart the container.
+
+```ts
+probes.livez.enable(); // returns 200 OK
+probes.livez.disable(); // returns 503 Service Unavailable
+```
+
+### `/startupz` — Startup Probe
+
+Indicates if the application has finished initializing. Kubernetes waits for this before sending traffic or checking liveness.
+
+```ts
+probes.startupz.enable();
+probes.startupz.disable();
+```
+
+### `/readyz` — Readiness Probe
+
+Indicates if the application is ready to receive traffic. When disabled or when required health checks fail, Kubernetes removes the pod from load balancer rotation.
+
+```ts
+probes.readyz.enable();
+probes.readyz.disable();
+```
+
+The readiness probe automatically runs all non-optional health checks and returns 503 if any fail.
+
+### `/healthz` — Health Status
+
+Returns detailed JSON status of all probes and health checks. Useful for debugging and dashboards.
+
+```json
+{
+  "status": "healthy",
+  "probes": {
+    "livez": true,
+    "startupz": true,
+    "readyz": true
+  },
+  "checks": {
+    "database": {
+      "status": "healthy",
+      "latency": 12
+    },
+    "redis": {
+      "status": "unhealthy",
+      "latency": 5003,
+      "error": "check \"redis\" timed out after 5000ms"
+    }
+  }
+}
+```
+
+Status values:
+- `healthy` — all checks pass
+- `degraded` — optional checks failing, required checks pass
+- `unhealthy` — required checks failing
+
+## Health Checks
+
+Register health checks to verify dependencies are working:
+
+```ts
+import { checks } from "@astroscope/health";
+
+// return result (recommended for boolean checks)
+checks.register("database", () => ({
+  status: db.isConnected() ? "healthy" : "unhealthy",
+  error: db.isConnected() ? undefined : "connection lost",
+}));
+
+// throw-based (classic pattern)
+checks.register("cache", async () => {
+  await redis.ping(); // throws if fails
+});
+
+// with options
+checks.register({
+  name: "external-api",
+  check: () => fetch("https://api.example.com/health").then(() => {}),
+  optional: true, // doesn't affect /readyz, only /healthz status
+  timeout: 10000, // custom timeout (default: 5000ms)
+});
+```
+
+The check function can either:
+- Return `HealthCheckResult` with status and optional error
+- Return `void` (completing without error = healthy)
+- Throw an error (= unhealthy with error message)
+
+### Unregistering Checks
+
+`register()` returns an unregister function:
+
+```ts
+const unregister = checks.register({
+  name: "database",
+  check: () => db.ping(),
+});
+
+// later...
+unregister();
+```
+
+## Server Options
+
+```ts
+server.start({
+  host: "0.0.0.0", // default: "localhost"
+  port: 9090, // default: 9090
+});
+```
+
+## Kubernetes Configuration
+
+```yaml
+apiVersion: v1
+kind: Pod
+spec:
+  containers:
+    - name: app
+      ports:
+        - containerPort: 4321 # astro
+        - containerPort: 9090 # health
+      livenessProbe:
+        httpGet:
+          path: /livez
+          port: 9090
+        initialDelaySeconds: 0
+        periodSeconds: 10
+      startupProbe:
+        httpGet:
+          path: /startupz
+          port: 9090
+        failureThreshold: 30
+        periodSeconds: 2
+      readinessProbe:
+        httpGet:
+          path: /readyz
+          port: 9090
+        periodSeconds: 5
+```
+
+## API Reference
+
+### Server
+
+```ts
+import { server } from "@astroscope/health";
+
+server.start(options?: HealthServerOptions): void;
+server.stop(): Promise<void>;
+```
+
+### Probes
+
+```ts
+import { probes } from "@astroscope/health";
+
+probes.livez.enable(): void;
+probes.livez.disable(): void;
+probes.livez.get(): Promise<HealthProbeResult>;
+probes.livez.response(): Promise<Response>;
+
+// same for startupz, readyz
+
+probes.healthz.get(): Promise<HealthzResult>;
+probes.healthz.response(): Promise<Response>;
+```
+
+### Checks
+
+```ts
+import { checks } from "@astroscope/health";
+
+checks.register(name: string, check: CheckFn): () => void;
+checks.register(check: HealthCheck): () => void;
+
+// CheckFn = () => Promise<HealthCheckResult | void> | HealthCheckResult | void
+checks.getChecks(): HealthCheck[];
+checks.runAll(): Promise<Record<string, HealthCheckResult>>;
+checks.runRequired(): Promise<boolean>;
+```
+
+## Types
+
+```ts
+interface HealthCheck {
+  name: string;
+  check: () => Promise<HealthCheckResult | void> | HealthCheckResult | void;
+  optional?: boolean; // default: false
+  timeout?: number; // default: 5000
+}
+
+interface HealthCheckResult {
+  status: "healthy" | "unhealthy";
+  latency?: number;
+  error?: string;
+}
+
+interface HealthProbeResult {
+  passing: boolean;
+}
+
+interface HealthzResult {
+  status: "healthy" | "degraded" | "unhealthy";
+  probes: {
+    livez: boolean;
+    startupz: boolean;
+    readyz: boolean;
+  };
+  checks: Record<string, HealthCheckResult>;
+}
+
+interface HealthServerOptions {
+  host?: string; // default: "localhost"
+  port?: number; // default: 9090
+}
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Server configuration options.
+ */
+interface HealthServerOptions {
+    /**
+     * Host to bind the health server to.
+     * @default 'localhost'
+     */
+    host?: string | undefined;
+    /**
+     * Port to bind the health server to.
+     * @default 9090
+     */
+    port?: number | undefined;
+}
+/**
+ * Health check definition.
+ */
+interface HealthCheck {
+    /**
+     * Unique name for this health check.
+     */
+    name: string;
+    /**
+     * Function that performs the health check.
+     * Return HealthCheckResult or throw an error to indicate status.
+     * Returning void or completing without error means healthy.
+     */
+    check: () => Promise<HealthCheckResult | void> | HealthCheckResult | void;
+    /**
+     * Whether this check is optional.
+     * Optional checks don't affect the /readyz endpoint.
+     * @default false
+     */
+    optional?: boolean | undefined;
+    /**
+     * Maximum time in ms for the check to complete.
+     * @default 5000
+     */
+    timeout?: number | undefined;
+}
+/**
+ * Result of a single health check.
+ */
+interface HealthCheckResult {
+    status: 'healthy' | 'unhealthy';
+    latency?: number | undefined;
+    error?: string | undefined;
+}
+/**
+ * Result of a probe query.
+ */
+interface HealthProbeResult {
+    passing: boolean;
+}
+/**
+ * Full health status including all checks.
+ */
+interface HealthzResult {
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    probes: {
+        livez: boolean;
+        startupz: boolean;
+        readyz: boolean;
+    };
+    checks: Record<string, HealthCheckResult>;
+}
+/**
+ * Single probe interface.
+ */
+interface HealthProbe {
+    /**
+     * Enable this probe (will return 200 when called).
+     */
+    enable(): void;
+    /**
+     * Disable this probe (will return 503 when called).
+     */
+    disable(): void;
+    /**
+     * Get the current probe result.
+     */
+    get(): Promise<HealthProbeResult>;
+    /**
+     * Get a Response object for this probe.
+     */
+    response(): Promise<Response>;
+}
+/**
+ * Healthz probe interface (always returns data, used for debugging).
+ */
+interface HealthzProbe {
+    /**
+     * Get the full health status.
+     */
+    get(): Promise<HealthzResult>;
+    /**
+     * Get a Response object with JSON health data.
+     */
+    response(): Promise<Response>;
+}
+
+/**
+ * Manages the HTTP server for health endpoints.
+ */
+declare class HealthServer {
+    private instance;
+    /**
+     * Start the health check HTTP server.
+     */
+    start(options?: HealthServerOptions): void;
+    /**
+     * Stop the health check HTTP server.
+     */
+    stop(): Promise<void>;
+    private handleRequest;
+}
+declare const server: HealthServer;
+
+/**
+ * Manages probe state and provides probe endpoints.
+ */
+declare class HealthProbes {
+    private state;
+    private createProbeResponse;
+    readonly livez: HealthProbe;
+    readonly startupz: HealthProbe;
+    readonly readyz: HealthProbe;
+    readonly healthz: HealthzProbe;
+}
+declare const probes: HealthProbes;
+
+/**
+ * Manages health check registration and execution.
+ */
+declare class HealthChecks {
+    private readonly registered;
+    /**
+     * Register a health check.
+     * Returns an unregister function.
+     */
+    register(name: string, check: () => Promise<HealthCheckResult | void> | HealthCheckResult | void): () => void;
+    register(check: HealthCheck): () => void;
+    /**
+     * Run a single check with timeout.
+     */
+    private run;
+    /**
+     * Run all registered health checks.
+     */
+    runAll(): Promise<Record<string, HealthCheckResult>>;
+    /**
+     * Run only required checks and return whether they all pass.
+     */
+    runRequired(): Promise<boolean>;
+    /**
+     * Get all registered checks.
+     */
+    getChecks(): HealthCheck[];
+}
+declare const checks: HealthChecks;
+
+export { type HealthCheck, type HealthCheckResult, HealthChecks, type HealthProbe, type HealthProbeResult, HealthProbes, HealthServer, type HealthServerOptions, type HealthzProbe, type HealthzResult, checks, probes, server };

package/dist/index.js

@@ -0,0 +1,236 @@
+// src/server.ts
+import { createServer } from "http";
+
+// src/checks.ts
+var DEFAULT_TIMEOUT = 5e3;
+var HealthChecks = class {
+  registered = /* @__PURE__ */ new Map();
+  register(nameOrCheck, checkFn) {
+    const check = typeof nameOrCheck === "string" ? { name: nameOrCheck, check: checkFn } : nameOrCheck;
+    if (this.registered.has(check.name)) {
+      console.warn(`[health] overwriting existing check "${check.name}"`);
+    }
+    this.registered.set(check.name, check);
+    return () => {
+      this.registered.delete(check.name);
+    };
+  }
+  /**
+   * Run a single check with timeout.
+   */
+  async run(check) {
+    const timeout = check.timeout ?? DEFAULT_TIMEOUT;
+    const start = performance.now();
+    try {
+      const result = await Promise.race([
+        Promise.resolve(check.check()),
+        new Promise((_, reject) => {
+          setTimeout(() => reject(new Error(`check "${check.name}" timed out after ${timeout}ms`)), timeout);
+        })
+      ]);
+      const latency = Math.round(performance.now() - start);
+      if (result) {
+        return { ...result, latency };
+      }
+      return { status: "healthy", latency };
+    } catch (error) {
+      const latency = Math.round(performance.now() - start);
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      return { status: "unhealthy", latency, error: errorMessage };
+    }
+  }
+  /**
+   * Run all registered health checks.
+   */
+  async runAll() {
+    const results = {};
+    const checks2 = [...this.registered.values()];
+    const checkPromises = checks2.map(async (check) => {
+      const result = await this.run(check);
+      results[check.name] = result;
+    });
+    await Promise.all(checkPromises);
+    return results;
+  }
+  /**
+   * Run only required checks and return whether they all pass.
+   */
+  async runRequired() {
+    const requiredChecks = [...this.registered.values()].filter((check) => !check.optional);
+    if (requiredChecks.length === 0) {
+      return true;
+    }
+    const checkPromises = requiredChecks.map(async (check) => {
+      const result = await this.run(check);
+      return result.status === "healthy";
+    });
+    const results = await Promise.all(checkPromises);
+    return results.every(Boolean);
+  }
+  /**
+   * Get all registered checks.
+   */
+  getChecks() {
+    return [...this.registered.values()];
+  }
+};
+var checks = new HealthChecks();
+
+// src/probes.ts
+var HealthProbes = class {
+  state = {
+    livez: false,
+    startupz: false,
+    readyz: false
+  };
+  createProbeResponse(result) {
+    return new Response(result.passing ? "OK" : "Service Unavailable", {
+      status: result.passing ? 200 : 503,
+      headers: { "Content-Type": "text/plain" }
+    });
+  }
+  livez = {
+    enable: () => {
+      this.state.livez = true;
+    },
+    disable: () => {
+      this.state.livez = false;
+    },
+    get: async () => {
+      return { passing: this.state.livez };
+    },
+    response: async () => {
+      return this.createProbeResponse(await this.livez.get());
+    }
+  };
+  startupz = {
+    enable: () => {
+      this.state.startupz = true;
+    },
+    disable: () => {
+      this.state.startupz = false;
+    },
+    get: async () => {
+      return { passing: this.state.startupz };
+    },
+    response: async () => {
+      return this.createProbeResponse(await this.startupz.get());
+    }
+  };
+  readyz = {
+    enable: () => {
+      this.state.readyz = true;
+    },
+    disable: () => {
+      this.state.readyz = false;
+    },
+    get: async () => {
+      return { passing: this.state.readyz ? await checks.runRequired() : false };
+    },
+    response: async () => {
+      return this.createProbeResponse(await this.readyz.get());
+    }
+  };
+  healthz = {
+    get: async () => {
+      const checkResults = await checks.runAll();
+      const registered = checks.getChecks();
+      const hasUnhealthy = Object.values(checkResults).some((c) => c.status === "unhealthy");
+      const hasRequiredUnhealthy = registered.filter((check) => !check.optional).some((check) => checkResults[check.name]?.status !== "healthy");
+      let status = "healthy";
+      if (hasRequiredUnhealthy) {
+        status = "unhealthy";
+      } else if (hasUnhealthy) {
+        status = "degraded";
+      }
+      return {
+        status,
+        probes: { livez: this.state.livez, startupz: this.state.startupz, readyz: this.state.readyz },
+        checks: checkResults
+      };
+    },
+    response: async () => {
+      const result = await this.healthz.get();
+      return new Response(JSON.stringify(result, null, 2), {
+        status: 200,
+        headers: { "Content-Type": "application/json" }
+      });
+    }
+  };
+};
+var probes = new HealthProbes();
+
+// src/server.ts
+var HealthServer = class {
+  instance = null;
+  /**
+   * Start the health check HTTP server.
+   */
+  start(options = {}) {
+    if (this.instance) {
+      return;
+    }
+    const host = options.host ?? "localhost";
+    const port = options.port ?? 9090;
+    const instance = createServer(async (req, res) => {
+      try {
+        const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+        const response = await this.handleRequest(url.pathname);
+        res.statusCode = response.status;
+        for (const [key, value] of response.headers.entries()) {
+          res.setHeader(key, value);
+        }
+        const body = await response.text();
+        res.end(body);
+      } catch {
+        res.statusCode = 500;
+        res.setHeader("Content-Type", "text/plain");
+        res.end("Internal Server Error");
+      }
+    });
+    instance.listen(port, host);
+    this.instance = instance;
+  }
+  /**
+   * Stop the health check HTTP server.
+   */
+  stop() {
+    return new Promise((resolve, reject) => {
+      if (!this.instance) {
+        resolve();
+        return;
+      }
+      this.instance.close((err) => {
+        if (err) {
+          reject(err);
+        } else {
+          this.instance = null;
+          resolve();
+        }
+      });
+    });
+  }
+  async handleRequest(pathname) {
+    switch (pathname) {
+      case "/livez":
+        return probes.livez.response();
+      case "/startupz":
+        return probes.startupz.response();
+      case "/readyz":
+        return probes.readyz.response();
+      case "/healthz":
+        return probes.healthz.response();
+      default:
+        return new Response("Not Found", { status: 404 });
+    }
+  }
+};
+var server = new HealthServer();
+export {
+  HealthChecks,
+  HealthProbes,
+  HealthServer,
+  checks,
+  probes,
+  server
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@astroscope/health",
+  "version": "0.1.0",
+  "description": "Health check endpoints for Astro — livez, readyz, startupz probes",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/smnbbrv/astroscope.git",
+    "directory": "packages/health"
+  },
+  "keywords": [
+    "astro",
+    "astro-integration",
+    "health",
+    "healthcheck",
+    "probes",
+    "readiness",
+    "liveness",
+    "kubernetes",
+    "k8s"
+  ],
+  "author": "smnbbrv",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/smnbbrv/astroscope/issues"
+  },
+  "homepage": "https://github.com/smnbbrv/astroscope/tree/main/packages/health#readme",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint 'src/**/*.ts'",
+    "lint:fix": "eslint 'src/**/*.ts' --fix"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  }
+}