feat(web): add /api/health/ready endpoint with dependency health checks

CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Added a `GET /api/health/ready` endpoint that returns per-dependency health (Postgres, Redis, Zoekt) for use as a Kubernetes `readinessProbe` or load-balancer health check. The existing `GET /api/health` endpoint is unchanged and remains the liveness probe. [#1507](https://github.com/sourcebot-dev/sourcebot/pull/1507)
+
 ### Changed
 - Vulnerability triage now keeps Linear issues synchronized with current security findings.
 

docs/docs.json

@@ -217,7 +217,8 @@
                         "icon": "server",
                         "pages": [
                             "GET /api/version",
-                            "GET /api/health"
+                            "GET /api/health",
+                            "docs/api-reference/health"
                         ]
                     }
                 ]

docs/docs/api-reference/health.mdx

@@ -0,0 +1,97 @@
+---
+title: "Health Endpoints"
+description: "Liveness and readiness probes for orchestrators and monitoring systems."
+---
+
+Sourcebot exposes two public health endpoints that follow the standard Kubernetes liveness / readiness split. Both are unauthenticated and return no user data.
+
+## Liveness: `GET /api/health`
+
+Returns `200 OK` with `{ "status": "ok" }` whenever the Next.js process is running and able to handle a request. Does not touch the database, Redis, or Zoekt. Use this for Kubernetes `livenessProbe` or Docker Compose `healthcheck.test`. A failing liveness probe means the process must be restarted.
+
+```bash
+curl -fsS https://sourcebot.example.com/api/health
+# {"status":"ok"}
+```
+
+## Readiness: `GET /api/health/ready`
+
+Returns `200 OK` with `{"status":"ok", "checks":{...}}` when Postgres, Redis, and Zoekt are all reachable. Returns `503 Service Unavailable` with `{"status":"degraded", "checks":{...}}` if any dependency is unreachable. Each check runs in parallel with a 2-second per-check timeout, so the worst-case request time is bounded even when a dependency hangs.
+
+Use this for Kubernetes `readinessProbe` or a load balancer health check. A failing readiness probe means the pod should be removed from the load-balancer rotation but not restarted.
+
+### Response shape
+
+```json
+{
+  "status": "ok",
+  "checks": {
+    "postgres": { "status": "ok", "latencyMs": 3 },
+    "redis":    { "status": "ok", "latencyMs": 1 },
+    "zoekt":    { "status": "ok", "latencyMs": 12 }
+  }
+}
+```
+
+When degraded, each failed check carries an `error` field with the underlying message:
+
+```json
+{
+  "status": "degraded",
+  "checks": {
+    "postgres": { "status": "ok",    "latencyMs": 4 },
+    "redis":    { "status": "ok",    "latencyMs": 1 },
+    "zoekt":    { "status": "error", "latencyMs": 2003, "error": "zoekt check timed out after 2000ms" }
+  }
+}
+```
+
+| Check | What it probes |
+|-------|---------------|
+| `postgres` | `SELECT 1` via Prisma |
+| `redis`    | `PING` (rejects non-`PONG` responses) |
+| `zoekt`    | Empty `List` RPC (proves the gRPC channel is alive; bounded by the 2s per-check timeout) |
+
+### Example probes
+
+<Tabs>
+  <Tab title="Docker Compose">
+    ```yaml
+    services:
+      sourcebot:
+        image: sourcebot/sourcebot:latest
+        healthcheck:
+          test: ["CMD", "wget", "-qO-", "http://localhost:3000/api/health"]
+          interval: 30s
+          timeout: 5s
+          retries: 3
+        # For dependency-aware probes, point the orchestrator at /api/health/ready
+        # instead. Sourcebot's example compose file does this via a sidecar.
+    ```
+  </Tab>
+  <Tab title="Kubernetes">
+    ```yaml
+    livenessProbe:
+      httpGet:
+        path: /api/health
+        port: 3000
+      initialDelaySeconds: 30
+      periodSeconds: 30
+      timeoutSeconds: 5
+      failureThreshold: 3
+    readinessProbe:
+      httpGet:
+        path: /api/health/ready
+        port: 3000
+      initialDelaySeconds: 10
+      periodSeconds: 10
+      timeoutSeconds: 5
+      successThreshold: 1
+      failureThreshold: 3
+    ```
+  </Tab>
+</Tabs>
+
+<Note>
+The readiness probe hits the database on every call. On large deployments with many pods, a high-frequency probe interval (sub-5s) can produce noticeable background load. A 10s interval with `failureThreshold: 3` is a good starting point.
+</Note>

packages/web/src/app/api/(server)/health/ready/route.test.ts

@@ -0,0 +1,199 @@
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({
+    unsafePrisma: {
+        $queryRaw: vi.fn(),
+    },
+    redisPing: vi.fn(),
+    zoektList: vi.fn(),
+}));
+
+vi.mock('server-only', () => ({}));
+
+vi.mock('@/prisma', () => ({
+    __unsafePrisma: mocks.unsafePrisma,
+}));
+
+vi.mock('@/lib/redis', () => ({
+    getRedisClient: () => ({
+        ping: mocks.redisPing,
+    }),
+}));
+
+vi.mock('@/lib/posthog', () => ({
+    captureEvent: vi.fn(),
+}));
+
+vi.mock('@/lib/zoektClient', () => ({
+    loadZoektClient: () => ({
+        List: mocks.zoektList,
+    }),
+}));
+
+vi.mock('@sourcebot/shared', () => ({
+    createLogger: () => ({
+        debug: vi.fn(),
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+    }),
+}));
+
+const { GET } = await import('./route');
+
+describe('GET /api/health/ready', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        mocks.unsafePrisma.$queryRaw.mockResolvedValue([{ '?column?': 1 }]);
+        mocks.redisPing.mockResolvedValue('PONG');
+        mocks.zoektList.mockImplementation(
+            (_request: unknown, callback: (err: Error | null) => void) => {
+                callback(null);
+            },
+        );
+    });
+
+    test('returns 200 with status:ok when all three dependencies are reachable', async () => {
+        const response = await GET();
+        const body = await response.json();
+
+        expect(response.status).toBe(200);
+        expect(body.status).toBe('ok');
+        expect(body.checks.postgres.status).toBe('ok');
+        expect(body.checks.redis.status).toBe('ok');
+        expect(body.checks.zoekt.status).toBe('ok');
+        expect(typeof body.checks.postgres.latencyMs).toBe('number');
+        expect(typeof body.checks.redis.latencyMs).toBe('number');
+        expect(typeof body.checks.zoekt.latencyMs).toBe('number');
+    });
+
+    test('returns 503 with status:degraded and a postgres error when Postgres is unreachable', async () => {
+        mocks.unsafePrisma.$queryRaw.mockRejectedValue(new Error('connection refused'));
+
+        const response = await GET();
+        const body = await response.json();
+
+        expect(response.status).toBe(503);
+        expect(body.status).toBe('degraded');
+        expect(body.checks.postgres.status).toBe('error');
+        expect(body.checks.postgres.error).toBe('connection refused');
+        expect(body.checks.redis.status).toBe('ok');
+        expect(body.checks.zoekt.status).toBe('ok');
+    });
+
+    test('returns 503 with status:degraded and a redis error when Redis ping fails', async () => {
+        mocks.redisPing.mockRejectedValue(new Error('redis down'));
+
+        const response = await GET();
+        const body = await response.json();
+
+        expect(response.status).toBe(503);
+        expect(body.status).toBe('degraded');
+        expect(body.checks.postgres.status).toBe('ok');
+        expect(body.checks.redis.status).toBe('error');
+        expect(body.checks.redis.error).toBe('redis down');
+        expect(body.checks.zoekt.status).toBe('ok');
+    });
+
+    test('returns 503 with status:degraded when the Zoekt gRPC call errors', async () => {
+        mocks.zoektList.mockImplementation(
+            (_request: unknown, callback: (err: Error | null) => void) => {
+                callback(new Error('UNAVAILABLE: zoekt not reachable'));
+            },
+        );
+
+        const response = await GET();
+        const body = await response.json();
+
+        expect(response.status).toBe(503);
+        expect(body.status).toBe('degraded');
+        expect(body.checks.zoekt.status).toBe('error');
+        expect(body.checks.zoekt.error).toContain('UNAVAILABLE');
+        expect(body.checks.postgres.status).toBe('ok');
+        expect(body.checks.redis.status).toBe('ok');
+    });
+
+    test('returns 503 with status:degraded when Redis returns a non-PONG response', async () => {
+        mocks.redisPing.mockResolvedValue('NOT-PONG');
+
+        const response = await GET();
+        const body = await response.json();
+
+        expect(response.status).toBe(503);
+        expect(body.status).toBe('degraded');
+        expect(body.checks.redis.status).toBe('error');
+        expect(body.checks.redis.error).toContain('unexpected ping response');
+    });
+
+    test('runs all three checks in parallel (Promise.all)', async () => {
+        const delay = 50;
+        mocks.unsafePrisma.$queryRaw.mockImplementation(
+            () => new Promise((resolve) => setTimeout(() => resolve([{}]), delay)),
+        );
+        mocks.redisPing.mockImplementation(
+            () => new Promise((resolve) => setTimeout(() => resolve('PONG'), delay)),
+        );
+        mocks.zoektList.mockImplementation(
+            (_request: unknown, callback: (err: Error | null) => void) => {
+                setTimeout(() => callback(null), delay);
+            },
+        );
+
+        const start = Date.now();
+        const response = await GET();
+        const elapsed = Date.now() - start;
+        const body = await response.json();
+
+        expect(response.status).toBe(200);
+        expect(body.status).toBe('ok');
+        // Generous upper bound to avoid flakes; serial would be ~3x delay.
+        expect(elapsed).toBeLessThan(delay * 2.5);
+    });
+
+    test('does not surface check rejections as unhandled promise rejections', async () => {
+        // The check rejects synchronously (well within the 2s timeout). The
+        // no-op `.catch` attached in `withTimeout` must absorb that
+        // rejection so the Node process does not log an
+        // unhandled-promise-rejection warning while the readiness request
+        // has already moved on.
+        const checkRejection = new Error('check rejected');
+        const unhandled: unknown[] = [];
+        const onUnhandled = (err: unknown) => { unhandled.push(err); };
+        process.on('unhandledRejection', onUnhandled);
+
+        try {
+            mocks.unsafePrisma.$queryRaw.mockRejectedValue(checkRejection);
+            mocks.redisPing.mockResolvedValue('PONG');
+            mocks.zoektList.mockImplementation(
+                (_request: unknown, callback: (err: Error | null) => void) => {
+                    callback(null);
+                },
+            );
+
+            const response = await GET();
+            const body = await response.json();
+
+            expect(response.status).toBe(503);
+            expect(body.checks.postgres.status).toBe('error');
+            // Give the rejection microtask a chance to fire and propagate.
+            await new Promise((resolve) => setTimeout(resolve, 50));
+            expect(unhandled).not.toContain(checkRejection);
+        } finally {
+            process.off('unhandledRejection', onUnhandled);
+        }
+    });
+
+    test('issues the Zoekt List RPC with empty options (max_wall_time is a SearchOptions field, not ListOptions)', async () => {
+        // Regression guard: the earlier draft of the Zoekt probe passed
+        // `{ opts: { max_wall_time: ... } }` to the `List` RPC. That field
+        // belongs to `SearchOptions` and is silently ignored by `List`
+        // (whose `ListOptions` only carries `field`). The 2s client-side
+        // timeout is the only thing that actually bounds the call. The
+        // probe must therefore issue the smallest valid request, which is
+        // an empty options object.
+        const response = await GET();
+        expect(response.status).toBe(200);
+        expect(mocks.zoektList).toHaveBeenCalledTimes(1);
+        expect(mocks.zoektList).toHaveBeenCalledWith({}, expect.any(Function));
+    });
+});