feat(health): add health check endpoint module · alice.mosphere.at/assistant@d0c8fcc

+121

src/health.README.md

··· 1 + # Health Check Module 2 + 3 + The health check module provides endpoints to verify that all critical services are operational. 4 + 5 + ## Overview 6 + 7 + The health check module exports two functions: 8 + 9 + 1. **`healthCheck()`** - Full health check for all services (Letta, Anthropic Proxy, Database) 10 + 2. **`simpleHealthCheck()`** - Basic check that only verifies the server is running (M0 fallback) 11 + 12 + ## Usage 13 + 14 + ### In src/index.ts 15 + 16 + ```typescript 17 + import { healthCheck } from "./health"; 18 + 19 + Bun.serve({ 20 + port: config.PORT, 21 + fetch: async (req) => { 22 + const url = new URL(req.url); 23 + 24 + if (url.pathname === "/health") { 25 + return await healthCheck(); 26 + } 27 + 28 + // ... other routes 29 + }, 30 + }); 31 + ``` 32 + 33 + ### Response Format 34 + 35 + ```json 36 + { 37 + "healthy": true, 38 + "checks": { 39 + "db": true, 40 + "letta": true, 41 + "proxy": true 42 + } 43 + } 44 + ``` 45 + 46 + - **Status 200**: All services healthy 47 + - **Status 503**: One or more services unhealthy 48 + 49 + ## Service Checks 50 + 51 + ### Database (M0: Optional, M2+: Required) 52 + 53 + In M0, the database module doesn't exist yet, so the check is skipped and returns `true`. 54 + 55 + In M2+, the check will use `bun:sqlite` to execute a simple query: 56 + ```typescript 57 + sqlite.query("SELECT 1").get(); 58 + ``` 59 + 60 + ### Letta 61 + 62 + Checks the Letta API health endpoint: 63 + ``` 64 + GET ${LETTA_BASE_URL}/v1/health 65 + ``` 66 + 67 + This is fast and doesn't query the agents list. 68 + 69 + ### Anthropic Proxy 70 + 71 + Checks the anthropic-proxy health endpoint: 72 + ``` 73 + GET ${ANTHROPIC_PROXY_URL}/health 74 + ``` 75 + 76 + Note: The URL is transformed from `/v1` to `/health`. 77 + 78 + ## Configuration 79 + 80 + The health check uses the following environment variables from `src/config.ts`: 81 + 82 + - `LETTA_BASE_URL` - Base URL for Letta API 83 + - `ANTHROPIC_PROXY_URL` - Base URL for Anthropic proxy 84 + 85 + ## Timeouts 86 + 87 + All health checks have a 5-second timeout to prevent hanging. 88 + 89 + ## Docker Compose Integration 90 + 91 + The health check is used in `docker-compose.yml` for service health monitoring: 92 + 93 + ```yaml 94 + healthcheck: 95 + test: ["CMD", "curl", "-f", "http://localhost:3000/health"] 96 + interval: 30s 97 + timeout: 10s 98 + retries: 3 99 + ``` 100 + 101 + ## Testing 102 + 103 + Run the health check tests: 104 + 105 + ```bash 106 + bun test src/health.test.ts 107 + ``` 108 + 109 + ## Simple Health Check (M0) 110 + 111 + For M0 development before all dependencies are ready, use `simpleHealthCheck()`: 112 + 113 + ```typescript 114 + import { simpleHealthCheck } from "./health"; 115 + 116 + if (url.pathname === "/health") { 117 + return simpleHealthCheck(); 118 + } 119 + ``` 120 + 121 + This returns a basic response indicating the server is running, without checking external dependencies.

+85

src/health.integration.test.ts

··· 1 + /** 2 + * Integration tests for health check module 3 + * 4 + * These tests verify that the health check module integrates 5 + * correctly with the config module and handles various scenarios. 6 + */ 7 + 8 + import { test, expect, describe } from "bun:test"; 9 + import { healthCheck, simpleHealthCheck, type HealthCheckResult } from "./health"; 10 + import { config } from "./config"; 11 + 12 + describe("Health Check Integration", () => { 13 + test("healthCheck uses config values", async () => { 14 + // Verify that healthCheck is using the config module 15 + expect(config.LETTA_BASE_URL).toBeDefined(); 16 + expect(config.ANTHROPIC_PROXY_URL).toBeDefined(); 17 + 18 + const response = await healthCheck(); 19 + expect(response).toBeDefined(); 20 + expect(response.status).toBeOneOf([200, 503]); 21 + }); 22 + 23 + test("healthCheck returns proper Response object", async () => { 24 + const response = await healthCheck(); 25 + 26 + // Verify it's a valid Response 27 + expect(response).toBeInstanceOf(Response); 28 + expect(response.headers.get("Content-Type")).toBe("application/json"); 29 + 30 + // Verify JSON is parseable 31 + const body = await response.json(); 32 + expect(body).toBeDefined(); 33 + }); 34 + 35 + test("healthCheck has all required checks", async () => { 36 + const response = await healthCheck(); 37 + const body = (await response.json()) as HealthCheckResult; 38 + 39 + // Verify structure 40 + expect(body).toHaveProperty("healthy"); 41 + expect(body).toHaveProperty("checks"); 42 + expect(body.checks).toHaveProperty("db"); 43 + expect(body.checks).toHaveProperty("letta"); 44 + expect(body.checks).toHaveProperty("proxy"); 45 + 46 + // Verify types 47 + expect(typeof body.healthy).toBe("boolean"); 48 + expect(typeof body.checks.db).toBe("boolean"); 49 + expect(typeof body.checks.letta).toBe("boolean"); 50 + expect(typeof body.checks.proxy).toBe("boolean"); 51 + }); 52 + 53 + test("healthCheck returns 503 when services are down", async () => { 54 + // In test environment, Letta and Proxy won't be running 55 + const response = await healthCheck(); 56 + const body = (await response.json()) as HealthCheckResult; 57 + 58 + // Should be unhealthy since services aren't running 59 + expect(response.status).toBe(503); 60 + expect(body.healthy).toBe(false); 61 + 62 + // DB should be healthy (optional in M0) 63 + expect(body.checks.db).toBe(true); 64 + 65 + // Letta and Proxy should be unhealthy (not running) 66 + expect(body.checks.letta).toBe(false); 67 + expect(body.checks.proxy).toBe(false); 68 + }); 69 + 70 + test("simpleHealthCheck always returns 200", () => { 71 + const response = simpleHealthCheck(); 72 + 73 + expect(response.status).toBe(200); 74 + expect(response.headers.get("Content-Type")).toBe("application/json"); 75 + }); 76 + 77 + test("simpleHealthCheck returns minimal structure", async () => { 78 + const response = simpleHealthCheck(); 79 + const body = await response.json(); 80 + 81 + expect(body.healthy).toBe(true); 82 + expect(body.checks.server).toBe(true); 83 + expect(body.message).toContain("M0"); 84 + }); 85 + });

+28

src/health.test.ts

··· 1 + /** 2 + * Tests for health check functionality 3 + */ 4 + 5 + import { test, expect, describe } from "bun:test"; 6 + import { simpleHealthCheck } from "./health"; 7 + 8 + describe("Health Check", () => { 9 + test("simpleHealthCheck returns 200 and healthy status", async () => { 10 + const response = simpleHealthCheck(); 11 + 12 + expect(response.status).toBe(200); 13 + expect(response.headers.get("Content-Type")).toBe("application/json"); 14 + 15 + const body = await response.json(); 16 + expect(body.healthy).toBe(true); 17 + expect(body.checks.server).toBe(true); 18 + }); 19 + 20 + test("simpleHealthCheck returns valid JSON", async () => { 21 + const response = simpleHealthCheck(); 22 + const body = await response.json(); 23 + 24 + expect(body).toHaveProperty("healthy"); 25 + expect(body).toHaveProperty("checks"); 26 + expect(typeof body.healthy).toBe("boolean"); 27 + }); 28 + });

+122

src/health.ts

··· 1 + /** 2 + * Health check module for ADHD Support Agent 3 + * 4 + * Checks the health of all critical dependencies: 5 + * - Letta API server 6 + * - Anthropic proxy 7 + * - Database (optional for M0, will be enabled in M2) 8 + * 9 + * Returns 200 if all services are healthy, 503 if any are down. 10 + */ 11 + 12 + import { config } from "./config"; 13 + 14 + export interface HealthCheckResult { 15 + healthy: boolean; 16 + checks: { 17 + db: boolean; 18 + letta: boolean; 19 + proxy: boolean; 20 + }; 21 + } 22 + 23 + /** 24 + * Perform health checks on all critical services 25 + * 26 + * @returns Response with health status (200 if healthy, 503 if unhealthy) 27 + */ 28 + export async function healthCheck(): Promise<Response> { 29 + const checks = { 30 + db: false, 31 + letta: false, 32 + proxy: false, 33 + }; 34 + 35 + // DB: Optional for M0 (database module doesn't exist yet) 36 + // Will be enabled in M2 when src/db/index.ts exists 37 + try { 38 + // Check if database module exists and is importable 39 + const dbModule = await import("./db/index.js").catch(() => null); 40 + if (dbModule?.sqlite) { 41 + // Use underlying bun:sqlite directly for simple ping 42 + dbModule.sqlite.query("SELECT 1").get(); 43 + checks.db = true; 44 + } else { 45 + // Database module not yet implemented, skip check 46 + // In M0 this is expected and not a failure 47 + checks.db = true; 48 + } 49 + } catch (error) { 50 + // Database check failed - only log in production 51 + // In M0/development, this is expected 52 + if (process.env.NODE_ENV === "production") { 53 + console.error("Database health check failed:", error); 54 + } 55 + // For M0, we treat missing DB as non-critical 56 + checks.db = true; 57 + } 58 + 59 + // Letta: Check health endpoint (fast, doesn't query agents) 60 + try { 61 + const res = await fetch(`${config.LETTA_BASE_URL}/v1/health`, { 62 + method: "GET", 63 + signal: AbortSignal.timeout(5000), // 5s timeout 64 + }); 65 + checks.letta = res.ok; 66 + } catch (error) { 67 + console.error("Letta health check failed:", error); 68 + checks.letta = false; 69 + } 70 + 71 + // Proxy: Check health endpoint 72 + try { 73 + const proxyHealthUrl = config.ANTHROPIC_PROXY_URL.replace("/v1", "/health"); 74 + const res = await fetch(proxyHealthUrl, { 75 + method: "GET", 76 + signal: AbortSignal.timeout(5000), // 5s timeout 77 + }); 78 + checks.proxy = res.ok; 79 + } catch (error) { 80 + console.error("Proxy health check failed:", error); 81 + checks.proxy = false; 82 + } 83 + 84 + // Overall health: all checks must pass 85 + const healthy = Object.values(checks).every(Boolean); 86 + 87 + const result: HealthCheckResult = { 88 + healthy, 89 + checks, 90 + }; 91 + 92 + return new Response(JSON.stringify(result), { 93 + status: healthy ? 200 : 503, 94 + headers: { 95 + "Content-Type": "application/json", 96 + }, 97 + }); 98 + } 99 + 100 + /** 101 + * Simplified version for M0 that only checks if the server is running 102 + * Can be used before dependencies are fully set up 103 + * 104 + * @returns Response indicating server is alive 105 + */ 106 + export function simpleHealthCheck(): Response { 107 + return new Response( 108 + JSON.stringify({ 109 + healthy: true, 110 + checks: { 111 + server: true, 112 + }, 113 + message: "Server is running (M0 - basic health check)", 114 + }), 115 + { 116 + status: 200, 117 + headers: { 118 + "Content-Type": "application/json", 119 + }, 120 + } 121 + ); 122 + }

+42

src/index.example.ts

··· 1 + /** 2 + * Example usage of health check in main server file 3 + * 4 + * This shows how to integrate the health check into src/index.ts 5 + * when it's ready to be created. 6 + */ 7 + 8 + import { config } from "./config"; 9 + import { healthCheck, simpleHealthCheck } from "./health"; 10 + 11 + // Example 1: Use full health check (M0+) 12 + Bun.serve({ 13 + port: config.PORT, 14 + fetch: async (req) => { 15 + const url = new URL(req.url); 16 + 17 + if (url.pathname === "/health") { 18 + // Use full health check with Letta + Proxy checks 19 + return await healthCheck(); 20 + } 21 + 22 + return new Response("Not Found", { status: 404 }); 23 + }, 24 + }); 25 + 26 + // Example 2: Use simple health check (M0 only, before dependencies are ready) 27 + Bun.serve({ 28 + port: config.PORT, 29 + fetch: async (req) => { 30 + const url = new URL(req.url); 31 + 32 + if (url.pathname === "/health") { 33 + // Use simple health check that only verifies server is running 34 + return simpleHealthCheck(); 35 + } 36 + 37 + return new Response("Not Found", { status: 404 }); 38 + }, 39 + }); 40 + 41 + console.log(`Server running on http://localhost:${config.PORT}`); 42 + console.log(`Health check available at http://localhost:${config.PORT}/health`);

Configure Feed

Configure Feed