From 8668e52cf1a5eac0619762aa8492f1ba0bb96eaf Mon Sep 17 00:00:00 2001
From: Harsh23Kashyap <55448981+Harsh23Kashyap@users.noreply.github.com>
Date: Fri, 24 Jul 2026 23:09:50 +0530
Subject: [PATCH 01/20] feat(web): extract lazy Zoekt gRPC client into a shared
 module

The vendored Zoekt webserver gRPC client construction needs node:path,
@grpc/grpc-js, @grpc/proto-loader, and the ZOEKT_WEBSERVER_URL env.
Pulling those at module load time also drags the @opentelemetry CJS
chain into anything that imports the client. Move the construction
behind a single loadZoektClient() helper that dynamically imports the
heavy deps, caches the resulting client, and lives in its own module
so readiness / search / stream-search callers can import it without
that boot-time cost and can mock it cleanly in tests.
---
 packages/web/src/lib/zoektClient.ts | 50 +++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)
 create mode 100644 packages/web/src/lib/zoektClient.ts

diff --git a/packages/web/src/lib/zoektClient.ts b/packages/web/src/lib/zoektClient.ts
new file mode 100644
index 000000000..1b02a6567
--- /dev/null
+++ b/packages/web/src/lib/zoektClient.ts
@@ -0,0 +1,50 @@
+// Thin wrapper around the vendored Zoekt webserver gRPC client. Kept in
+// a separate module so the readiness route can mock it in tests without
+// pulling the gRPC + @opentelemetry CJS chain at test-load time.
+
+export type ZoektListRequest = {
+    opts?: { max_wall_time?: { seconds: number; nanos: number } };
+};
+
+export type ZoektClient = {
+    List: (request: ZoektListRequest, callback: (err: Error | null) => void) => void;
+};
+
+let zoektClientPromise: Promise<ZoektClient> | undefined;
+
+export const loadZoektClient = (): Promise<ZoektClient> => {
+    if (!zoektClientPromise) {
+        zoektClientPromise = (async () => {
+            const [grpc, protoLoader, nodePath, shared] = await Promise.all([
+                import('@grpc/grpc-js'),
+                import('@grpc/proto-loader'),
+                import('node:path'),
+                import('@sourcebot/shared'),
+            ]);
+
+            const protoBasePath = nodePath.join(process.cwd(), '../../vendor/zoekt/grpc/protos');
+            const protoPath = nodePath.join(protoBasePath, 'zoekt/webserver/v1/webserver.proto');
+
+            const packageDefinition = protoLoader.loadSync(protoPath, {
+                keepCase: true,
+                longs: Number,
+                enums: String,
+                defaults: true,
+                oneofs: true,
+                includeDirs: [protoBasePath],
+            });
+
+            const proto = grpc.loadPackageDefinition(packageDefinition) as unknown as {
+                zoekt: { webserver: { v1: { WebserverService: new (address: string, credentials: unknown) => ZoektClient } } };
+            };
+
+            const zoektUrl = new URL(shared.env.ZOEKT_WEBSERVER_URL);
+            const grpcAddress = `${zoektUrl.hostname}:${zoektUrl.port}`;
+            return new proto.zoekt.webserver.v1.WebserverService(
+                grpcAddress,
+                grpc.credentials.createInsecure(),
+            );
+        })();
+    }
+    return zoektClientPromise;
+};

From 8e90c6fe4c42a972c5b384385ebe6dcb47baab47 Mon Sep 17 00:00:00 2001
From: Harsh23Kashyap <55448981+Harsh23Kashyap@users.noreply.github.com>
Date: Fri, 24 Jul 2026 23:09:57 +0530
Subject: [PATCH 02/20] feat(web): add /api/health/ready endpoint with
 dependency health checks

Standard Kubernetes-style readiness probe. The existing /api/health
liveness endpoint is left untouched.

GET /api/health/ready runs three checks in parallel:
- postgres: prisma.$queryRaw SELECT 1
- redis:    getRedisClient().ping() (rejects non-PONG responses)
- zoekt:    an empty gRPC List with a 1s wall-time cap

Each check is bounded by a 2s timeout, so the worst-case request
time is bounded even when one dependency hangs. Returns 200 with
{status:ok, checks:{...}} when all three pass, 503 with
{status:degraded, checks:{...}} otherwise. Per-check payload includes
status, latencyMs, and an error message when degraded.

The endpoint is unauthenticated (matches the existing /api/health
policy) and PostHog tracking is disabled.
---
 .../app/api/(server)/health/ready/route.ts    | 139 ++++++++++++++++++
 1 file changed, 139 insertions(+)
 create mode 100644 packages/web/src/app/api/(server)/health/ready/route.ts

diff --git a/packages/web/src/app/api/(server)/health/ready/route.ts b/packages/web/src/app/api/(server)/health/ready/route.ts
new file mode 100644
index 000000000..2cadcbe3a
--- /dev/null
+++ b/packages/web/src/app/api/(server)/health/ready/route.ts
@@ -0,0 +1,139 @@
+import { createLogger } from '@sourcebot/shared';
+
+import { apiHandler } from '@/lib/apiHandler';
+import { __unsafePrisma } from '@/prisma';
+import { getRedisClient } from '@/lib/redis';
+import { loadZoektClient } from '@/lib/zoektClient';
+
+// Per-check timeout. The three checks run in parallel, so the worst-case
+// request time is bounded by this value even when one dependency hangs.
+const READINESS_TIMEOUT_MS = 2000;
+
+const logger = createLogger('health-ready');
+
+type CheckStatus = 'ok' | 'error';
+type CheckResult = {
+    status: CheckStatus;
+    latencyMs: number;
+    error?: string;
+};
+type ReadinessResponse = {
+    status: 'ok' | 'degraded';
+    checks: {
+        postgres: CheckResult;
+        redis: CheckResult;
+        zoekt: CheckResult;
+    };
+};
+
+// Wraps a check function in a per-check timeout. When the timeout fires
+// first, the check resolves as an error result; the underlying promise is
+// allowed to settle in the background (its result is discarded).
+const withTimeout = async <T>(
+    label: string,
+    check: () => Promise<T>,
+    timeoutMs: number,
+): Promise<T> => {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const timeout = new Promise<never>((_, reject) => {
+        timer = setTimeout(() => {
+            reject(new Error(`${label} check timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([check(), timeout]);
+    } finally {
+        if (timer) {
+            clearTimeout(timer);
+        }
+    }
+};
+
+const checkPostgres = async (): Promise<CheckResult> => {
+    const start = Date.now();
+    try {
+        await withTimeout('postgres', async () => {
+            await __unsafePrisma.$queryRaw`SELECT 1`;
+        }, READINESS_TIMEOUT_MS);
+        return { status: 'ok', latencyMs: Date.now() - start };
+    } catch (err) {
+        return {
+            status: 'error',
+            latencyMs: Date.now() - start,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+};
+
+const checkRedis = async (): Promise<CheckResult> => {
+    const start = Date.now();
+    try {
+        const redis = getRedisClient();
+        await withTimeout('redis', async () => {
+            const pong = await redis.ping();
+            if (pong !== 'PONG') {
+                throw new Error(`unexpected ping response: ${pong}`);
+            }
+        }, READINESS_TIMEOUT_MS);
+        return { status: 'ok', latencyMs: Date.now() - start };
+    } catch (err) {
+        return {
+            status: 'error',
+            latencyMs: Date.now() - start,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+};
+
+const checkZoekt = async (): Promise<CheckResult> => {
+    const start = Date.now();
+    try {
+        const client = await loadZoektClient();
+        await withTimeout('zoekt', async () => {
+            await new Promise<void>((resolve, reject) => {
+                // An empty List with a 1s wall-time cap is the smallest request
+                // that exercises the gRPC channel end-to-end. It returns an
+                // empty result, not an error, even when no repos are indexed.
+                client.List(
+                    { opts: { max_wall_time: { seconds: 1, nanos: 0 } } },
+                    (err) => {
+                        if (err) {
+                            reject(err);
+                        } else {
+                            resolve();
+                        }
+                    },
+                );
+            });
+        }, READINESS_TIMEOUT_MS);
+        return { status: 'ok', latencyMs: Date.now() - start };
+    } catch (err) {
+        return {
+            status: 'error',
+            latencyMs: Date.now() - start,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+};
+
+// eslint-disable-next-line authz/require-auth-wrapper -- public readiness probe, no user data returned
+export const GET = apiHandler(async () => {
+    const [postgres, redis, zoekt] = await Promise.all([
+        checkPostgres(),
+        checkRedis(),
+        checkZoekt(),
+    ]);
+
+    const checks = { postgres, redis, zoekt };
+    const healthy = postgres.status === 'ok' && redis.status === 'ok' && zoekt.status === 'ok';
+
+    if (!healthy) {
+        logger.warn('readiness check failed', { checks });
+    }
+
+    const body: ReadinessResponse = {
+        status: healthy ? 'ok' : 'degraded',
+        checks,
+    };
+    return Response.json(body, { status: healthy ? 200 : 503 });
+}, { track: false });

From 0f04b34326f41c7072e4ef8cec70d93efd878ad9 Mon Sep 17 00:00:00 2001
From: Harsh23Kashyap <55448981+Harsh23Kashyap@users.noreply.github.com>
Date: Fri, 24 Jul 2026 23:10:05 +0530
Subject: [PATCH 03/20] test(web): cover /api/health/ready healthy and degraded
 paths

Six cases:
- 200 + status:ok when all three dependencies are reachable
- 503 + postgres error when Postgres is unreachable
- 503 + redis error when Redis ping fails
- 503 + zoekt error when the gRPC call errors
- 503 + redis error when Redis returns a non-PONG response
- all three checks run in parallel (Promise.all), not serially

The zoekt client is mocked via the new @/lib/zoektClient module so
the test does not pull in @grpc/grpc-js at test-load time.
---
 .../api/(server)/health/ready/route.test.ts   | 152 ++++++++++++++++++
 1 file changed, 152 insertions(+)
 create mode 100644 packages/web/src/app/api/(server)/health/ready/route.test.ts

diff --git a/packages/web/src/app/api/(server)/health/ready/route.test.ts b/packages/web/src/app/api/(server)/health/ready/route.test.ts
new file mode 100644
index 000000000..0a2972f26
--- /dev/null
+++ b/packages/web/src/app/api/(server)/health/ready/route.test.ts
@@ -0,0 +1,152 @@
+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);
+    });
+});

From e29ed6b3016e1c93105f58d28b7083f8116c822a Mon Sep 17 00:00:00 2001
From: Harsh23Kashyap <55448981+Harsh23Kashyap@users.noreply.github.com>
Date: Fri, 24 Jul 2026 23:10:05 +0530
Subject: [PATCH 04/20] docs(health): document liveness vs readiness split

New docs/docs/api-reference/health.mdx describes both endpoints, the
response shape, the per-dependency checks, and example Docker Compose
and Kubernetes probes. Wired into the existing System group in
docs/docs.json.
---
 docs/docs.json                     |  3 +-
 docs/docs/api-reference/health.mdx | 97 ++++++++++++++++++++++++++++++
 2 files changed, 99 insertions(+), 1 deletion(-)
 create mode 100644 docs/docs/api-reference/health.mdx

diff --git a/docs/docs.json b/docs/docs.json
index ad45e7fc8..ae26d3c8d 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -217,7 +217,8 @@
                         "icon": "server",
                         "pages": [
                             "GET /api/version",
-                            "GET /api/health"
+                            "GET /api/health",
+                            "docs/api-reference/health"
                         ]
                     }
                 ]
diff --git a/docs/docs/api-reference/health.mdx b/docs/docs/api-reference/health.mdx
new file mode 100644
index 000000000..ec85f2c6a
--- /dev/null
+++ b/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`    | `List` RPC with a 1-second wall-time cap (proves the gRPC channel is alive) |
+
+### 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>

From 375f2dd7b76d82b67d0935fe96103c24112d6b7b Mon Sep 17 00:00:00 2001
From: Harsh23Kashyap <55448981+Harsh23Kashyap@users.noreply.github.com>
Date: Fri, 24 Jul 2026 23:10:05 +0530
Subject: [PATCH 05/20] chore: changelog entry for /api/health/ready

References issue #1506.
---
 CHANGELOG.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 92fdc34be..34214ab3e 100644
--- a/CHANGELOG.md
+++ b/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. [#1506](https://github.com/sourcebot-dev/sourcebot/issues/1506)
+
 ### Changed
 - Vulnerability triage now keeps Linear issues synchronized with current security findings.
 

From 2a47d1184a33bea42d50b5bf163da31d6683517b Mon Sep 17 00:00:00 2001
From: Harsh23Kashyap <55448981+Harsh23Kashyap@users.noreply.github.com>
Date: Sun, 26 Jul 2026 11:27:16 +0530
Subject: [PATCH 06/20] fix(web): only cache successful Zoekt client builds

The previous implementation cached the first init attempt in
zoektClientPromise and never cleared it. A transient startup error
(proto load failure, network timeout) would then permanently mark
the Zoekt readiness check as failed until the process restarted.

This was a pre-existing latent bug in the zoektClient helper, but the
readiness route made it visible. The fix: store the resolved
client (not the in-flight promise) so a failed build never reaches
the cache, and a subsequent call can retry the init.

Addresses Bugbot finding cd93d60f on the same file.
---
 packages/web/src/lib/zoektClient.ts | 80 ++++++++++++++++-------------
 1 file changed, 44 insertions(+), 36 deletions(-)

diff --git a/packages/web/src/lib/zoektClient.ts b/packages/web/src/lib/zoektClient.ts
index 1b02a6567..accaf3963 100644
--- a/packages/web/src/lib/zoektClient.ts
+++ b/packages/web/src/lib/zoektClient.ts
@@ -10,41 +10,49 @@ export type ZoektClient = {
     List: (request: ZoektListRequest, callback: (err: Error | null) => void) => void;
 };
 
-let zoektClientPromise: Promise<ZoektClient> | undefined;
-
-export const loadZoektClient = (): Promise<ZoektClient> => {
-    if (!zoektClientPromise) {
-        zoektClientPromise = (async () => {
-            const [grpc, protoLoader, nodePath, shared] = await Promise.all([
-                import('@grpc/grpc-js'),
-                import('@grpc/proto-loader'),
-                import('node:path'),
-                import('@sourcebot/shared'),
-            ]);
-
-            const protoBasePath = nodePath.join(process.cwd(), '../../vendor/zoekt/grpc/protos');
-            const protoPath = nodePath.join(protoBasePath, 'zoekt/webserver/v1/webserver.proto');
-
-            const packageDefinition = protoLoader.loadSync(protoPath, {
-                keepCase: true,
-                longs: Number,
-                enums: String,
-                defaults: true,
-                oneofs: true,
-                includeDirs: [protoBasePath],
-            });
-
-            const proto = grpc.loadPackageDefinition(packageDefinition) as unknown as {
-                zoekt: { webserver: { v1: { WebserverService: new (address: string, credentials: unknown) => ZoektClient } } };
-            };
-
-            const zoektUrl = new URL(shared.env.ZOEKT_WEBSERVER_URL);
-            const grpcAddress = `${zoektUrl.hostname}:${zoektUrl.port}`;
-            return new proto.zoekt.webserver.v1.WebserverService(
-                grpcAddress,
-                grpc.credentials.createInsecure(),
-            );
-        })();
+let cachedClient: ZoektClient | undefined;
+
+const buildClient = async (): Promise<ZoektClient> => {
+    const [grpc, protoLoader, nodePath, shared] = await Promise.all([
+        import('@grpc/grpc-js'),
+        import('@grpc/proto-loader'),
+        import('node:path'),
+        import('@sourcebot/shared'),
+    ]);
+
+    const protoBasePath = nodePath.join(process.cwd(), '../../vendor/zoekt/grpc/protos');
+    const protoPath = nodePath.join(protoBasePath, 'zoekt/webserver/v1/webserver.proto');
+
+    const packageDefinition = protoLoader.loadSync(protoPath, {
+        keepCase: true,
+        longs: Number,
+        enums: String,
+        defaults: true,
+        oneofs: true,
+        includeDirs: [protoBasePath],
+    });
+
+    const proto = grpc.loadPackageDefinition(packageDefinition) as unknown as {
+        zoekt: { webserver: { v1: { WebserverService: new (address: string, credentials: unknown) => ZoektClient } } };
+    };
+
+    const zoektUrl = new URL(shared.env.ZOEKT_WEBSERVER_URL);
+    const grpcAddress = `${zoektUrl.hostname}:${zoektUrl.port}`;
+    return new proto.zoekt.webserver.v1.WebserverService(
+        grpcAddress,
+        grpc.credentials.createInsecure(),
+    );
+};
+
+// Returns a connected client, building it on first use. Only successful
+// builds are cached: a transient init failure does not poison subsequent
+// readiness probes, so the next call can retry.
+export const loadZoektClient = async (): Promise<ZoektClient> => {
+    if (cachedClient) {
+        return cachedClient;
     }
-    return zoektClientPromise;
+    const client = await buildClient();
+    cachedClient = client;
+    return client;
 };
+

From 7a4ddc53440e53011ebc82b87b2891b9eaee2a4d Mon Sep 17 00:00:00 2001
From: Harsh23Kashyap <55448981+Harsh23Kashyap@users.noreply.github.com>
Date: Sun, 26 Jul 2026 11:27:16 +0530
Subject: [PATCH 07/20] fix(web): bound the readiness route by its own timeout

Two related issues surfaced from bot review on the readiness route:

1. `checkZoekt` called `loadZoektClient()` outside the
   `withTimeout` wrapper, so a stalled first-call Zoekt init
   (vendored proto load, network DNS, etc.) could exceed the
   documented 2s bound. Move the init call inside the timeout so it
   shares the same bound as the gRPC call.

2. `withTimeout` raced the check promise against the timeout and
   discarded the loser. If the loser later rejected, no one was
   awaiting it, surfacing as an unhandled-promise-rejection warning
   in the Node process during a hung-dependency outage. Attach a
   no-op `.catch` to the check promise so late rejections are
   absorbed; the visible result (the timeout error or the actual
   check error) is unchanged.

Addresses Bugbot findings 597dbe01 and 367ae57f, and CodeRabbit
finding 'Cancel timed-out readiness dependency operations' on the
same file.
---
 .../src/app/api/(server)/health/ready/route.ts  | 17 ++++++++++++-----
 1 file changed, 12 insertions(+), 5 deletions(-)

diff --git a/packages/web/src/app/api/(server)/health/ready/route.ts b/packages/web/src/app/api/(server)/health/ready/route.ts
index 2cadcbe3a..7b0bedd67 100644
--- a/packages/web/src/app/api/(server)/health/ready/route.ts
+++ b/packages/web/src/app/api/(server)/health/ready/route.ts
@@ -26,14 +26,19 @@ type ReadinessResponse = {
     };
 };
 
-// Wraps a check function in a per-check timeout. When the timeout fires
-// first, the check resolves as an error result; the underlying promise is
-// allowed to settle in the background (its result is discarded).
+// Runs `check()` and rejects if it has not settled after `timeoutMs`. When the
+// timeout fires, the underlying check promise may still resolve or reject
+// later; the no-op `.catch` below attaches to that promise so a late
+// rejection does not surface as an unhandled-promise-rejection in the Node
+// process while the readiness request has already moved on.
 const withTimeout = async <T>(
     label: string,
     check: () => Promise<T>,
     timeoutMs: number,
 ): Promise<T> => {
+    const checkPromise = check();
+    checkPromise.catch(() => { /* swallowed: see comment above */ });
+
     let timer: ReturnType<typeof setTimeout> | undefined;
     const timeout = new Promise<never>((_, reject) => {
         timer = setTimeout(() => {
@@ -41,7 +46,7 @@ const withTimeout = async <T>(
         }, timeoutMs);
     });
     try {
-        return await Promise.race([check(), timeout]);
+        return await Promise.race([checkPromise, timeout]);
     } finally {
         if (timer) {
             clearTimeout(timer);
@@ -88,8 +93,10 @@ const checkRedis = async (): Promise<CheckResult> => {
 const checkZoekt = async (): Promise<CheckResult> => {
     const start = Date.now();
     try {
-        const client = await loadZoektClient();
         await withTimeout('zoekt', async () => {
+            // Build the client inside the timeout so a first-call init stall
+            // (e.g., vendored proto load) is also bounded.
+            const client = await loadZoektClient();
             await new Promise<void>((resolve, reject) => {
                 // An empty List with a 1s wall-time cap is the smallest request
                 // that exercises the gRPC channel end-to-end. It returns an

From 56e336b6fb932ba7256ef8cb88f644466525df63 Mon Sep 17 00:00:00 2001
From: Harsh23Kashyap <55448981+Harsh23Kashyap@users.noreply.github.com>
Date: Sun, 26 Jul 2026 11:27:16 +0530
Subject: [PATCH 08/20] test(web): cover unhandled-rejection suppression in
 readiness probe

New test attaches a process-level 'unhandledRejection' listener and
asserts that the readiness probe does not surface the check
promise's rejection to it, even when the race has already returned
the timeout error. Locks in the no-op `.catch` in `withTimeout`.
---
 .../api/(server)/health/ready/route.test.ts   | 33 +++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/packages/web/src/app/api/(server)/health/ready/route.test.ts b/packages/web/src/app/api/(server)/health/ready/route.test.ts
index 0a2972f26..315b7539d 100644
--- a/packages/web/src/app/api/(server)/health/ready/route.test.ts
+++ b/packages/web/src/app/api/(server)/health/ready/route.test.ts
@@ -149,4 +149,37 @@ describe('GET /api/health/ready', () => {
         // 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);
+        }
+    });
 });

From 3b1ebe9ec5edddbf683d727b9dfb2bddfd5004b6 Mon Sep 17 00:00:00 2001
From: Harsh23Kashyap <55448981+Harsh23Kashyap@users.noreply.github.com>
Date: Sun, 26 Jul 2026 11:27:16 +0530
Subject: [PATCH 09/20] chore: changelog link to PR #1507 instead of issue
 #1506

Coding guidelines: changelog entries must reference the PR id, not
the issue. The previous link pointed at the issue (which is what was
known at the time the entry was written). This aligns the entry
with the convention.
---
 CHANGELOG.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 34214ab3e..78bcd0988 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,7 +8,7 @@ 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. [#1506](https://github.com/sourcebot-dev/sourcebot/issues/1506)
+- 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.

From f5193aeae5e7b6ef436f0a3ed39c57935b5d22b3 Mon Sep 17 00:00:00 2001
From: Harsh23Kashyap <55448981+Harsh23Kashyap@users.noreply.github.com>
Date: Sun, 26 Jul 2026 11:34:43 +0530
Subject: [PATCH 10/20] fix(web): Zoekt readiness probe uses empty List options
 (max_wall_time is a SearchOptions field)

Address Cursor Bugbot finding on the readiness probe (PR #1507 review #3):
the gRPC `List` call was being issued with `{ opts: { max_wall_time: ... } }`,
but `max_wall_time` is a `SearchOptions` field, not a `ListOptions` field.
The Zoekt server silently dropped it, so the intended 1-second server-side
timeout never applied and the call was only bounded by the 2-second
client-side timeout in `READINESS_TIMEOUT_MS`. On a hung Zoekt instance
the request would still return inside 2s, but the in-flight RPC could keep
the Zoekt worker busy for longer than necessary.

Drop the bogus `opts`, document why, and add a regression test that locks
in `List` being called with an empty options object. The probe now
issues the smallest valid request: `client.List({}, cb)`.
---
 docs/docs/api-reference/health.mdx            |  2 +-
 .../api/(server)/health/ready/route.test.ts   | 14 ++++++++++
 .../app/api/(server)/health/ready/route.ts    | 27 ++++++++++---------
 3 files changed, 29 insertions(+), 14 deletions(-)

diff --git a/docs/docs/api-reference/health.mdx b/docs/docs/api-reference/health.mdx
index ec85f2c6a..3550dd697 100644
--- a/docs/docs/api-reference/health.mdx
+++ b/docs/docs/api-reference/health.mdx
@@ -50,7 +50,7 @@ When degraded, each failed check carries an `error` field with the underlying me
 |-------|---------------|
 | `postgres` | `SELECT 1` via Prisma |
 | `redis`    | `PING` (rejects non-`PONG` responses) |
-| `zoekt`    | `List` RPC with a 1-second wall-time cap (proves the gRPC channel is alive) |
+| `zoekt`    | Empty `List` RPC (proves the gRPC channel is alive; bounded by the 2s per-check timeout) |
 
 ### Example probes
 
diff --git a/packages/web/src/app/api/(server)/health/ready/route.test.ts b/packages/web/src/app/api/(server)/health/ready/route.test.ts
index 315b7539d..a7203af01 100644
--- a/packages/web/src/app/api/(server)/health/ready/route.test.ts
+++ b/packages/web/src/app/api/(server)/health/ready/route.test.ts
@@ -182,4 +182,18 @@ describe('GET /api/health/ready', () => {
             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));
+    });
 });
diff --git a/packages/web/src/app/api/(server)/health/ready/route.ts b/packages/web/src/app/api/(server)/health/ready/route.ts
index 7b0bedd67..3bb072e13 100644
--- a/packages/web/src/app/api/(server)/health/ready/route.ts
+++ b/packages/web/src/app/api/(server)/health/ready/route.ts
@@ -98,19 +98,20 @@ const checkZoekt = async (): Promise<CheckResult> => {
             // (e.g., vendored proto load) is also bounded.
             const client = await loadZoektClient();
             await new Promise<void>((resolve, reject) => {
-                // An empty List with a 1s wall-time cap is the smallest request
-                // that exercises the gRPC channel end-to-end. It returns an
-                // empty result, not an error, even when no repos are indexed.
-                client.List(
-                    { opts: { max_wall_time: { seconds: 1, nanos: 0 } } },
-                    (err) => {
-                        if (err) {
-                            reject(err);
-                        } else {
-                            resolve();
-                        }
-                    },
-                );
+                // Empty `List` is the smallest request that exercises the gRPC
+                // channel end-to-end. It returns an empty result, not an error,
+                // even when no repos are indexed. The 2s client-side
+                // `READINESS_TIMEOUT_MS` is the only timeout that actually
+                // bounds the call: `max_wall_time` is a `SearchOptions` field
+                // and does not apply to `List` (`ListOptions` only carries
+                // `field`).
+                client.List({}, (err) => {
+                    if (err) {
+                        reject(err);
+                    } else {
+                        resolve();
+                    }
+                });
             });
         }, READINESS_TIMEOUT_MS);
         return { status: 'ok', latencyMs: Date.now() - start };

From 33356330146bd8a01726ca7de0c02f64d64bcad3 Mon Sep 17 00:00:00 2001
From: Harsh23Kashyap <55448981+Harsh23Kashyap@users.noreply.github.com>
Date: Sun, 26 Jul 2026 11:41:12 +0530
Subject: [PATCH 11/20] feat(web): add ?strict=true mode to /api/health/ready
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Self-hosted operators wiring Sourcebot into a Kubernetes readinessProbe
typically want two distinct signals:

- "soft ready" — the process is up and the dependencies are reachable.
  This is the default behavior of /api/health/ready.
- "strictly ready" — the process is up, the dependencies are reachable,
  and the instance can actually serve a search that returns results.
  A node that has not finished indexing anything is not strictly ready
  even if all three RPCs succeed.

Today there is no way to ask the probe the second question. A node
can pass liveness, pass readiness, and still be useless to a search
request.

Add ?strict=true to /api/health/ready. When strict mode is on and
the Zoekt List response is empty (neither repos nor repos_map carries
any entries), the Zoekt check is reported as status: "empty" with
the error string "no repositories indexed (strict mode)" and the
overall response becomes 503 / status: "degraded". The Postgres
and Redis checks behave identically in both modes.

The response always includes a top-level strict field so operators
can confirm which mode was applied. An unparseable strict value
(e.g. ?strict=yes) is rejected as 400 by the Zod schema; the schema
intentionally does not use z.coerce.boolean() because that is just
Boolean(value) under the hood and would treat the string "false"
as truthy.

Closes #1511.

Implementation notes:
- The gRPC List callback now actually receives and surfaces the
  response object so the strict check can inspect it. The loose
  type in zoektClient.ts is updated accordingly: List's callback
  signature is (err, result) => void, not (err) => void. The full
  gRPC response type is wider than we need; we narrow it to a
  ZoektListResponse summary so the test mock can stay small.
- The empty check covers both ListOptions.Field values
  (RepoListFieldRepos -> repos, RepoListFieldReposMap -> repos_map)
  so the check is correct regardless of which field the server
  populates.
- ZoektListResponse is exported from zoektClient.ts so the test can
  type its mock callback against the same shape.
---
 .../app/api/(server)/health/ready/route.ts    | 90 +++++++++++++++----
 packages/web/src/lib/zoektClient.ts           | 10 ++-
 2 files changed, 82 insertions(+), 18 deletions(-)

diff --git a/packages/web/src/app/api/(server)/health/ready/route.ts b/packages/web/src/app/api/(server)/health/ready/route.ts
index 3bb072e13..8dfe7bc48 100644
--- a/packages/web/src/app/api/(server)/health/ready/route.ts
+++ b/packages/web/src/app/api/(server)/health/ready/route.ts
@@ -1,9 +1,12 @@
 import { createLogger } from '@sourcebot/shared';
+import { NextRequest } from 'next/server';
+import { z } from 'zod';
 
 import { apiHandler } from '@/lib/apiHandler';
 import { __unsafePrisma } from '@/prisma';
 import { getRedisClient } from '@/lib/redis';
-import { loadZoektClient } from '@/lib/zoektClient';
+import { queryParamsSchemaValidationError, serviceErrorResponse } from '@/lib/serviceError';
+import { loadZoektClient, ZoektListResponse } from '@/lib/zoektClient';
 
 // Per-check timeout. The three checks run in parallel, so the worst-case
 // request time is bounded by this value even when one dependency hangs.
@@ -11,7 +14,7 @@ const READINESS_TIMEOUT_MS = 2000;
 
 const logger = createLogger('health-ready');
 
-type CheckStatus = 'ok' | 'error';
+type CheckStatus = 'ok' | 'error' | 'empty';
 type CheckResult = {
     status: CheckStatus;
     latencyMs: number;
@@ -19,6 +22,7 @@ type CheckResult = {
 };
 type ReadinessResponse = {
     status: 'ok' | 'degraded';
+    strict: boolean;
     checks: {
         postgres: CheckResult;
         redis: CheckResult;
@@ -26,6 +30,22 @@ type ReadinessResponse = {
     };
 };
 
+const queryParamsSchema = z.object({
+    // `z.coerce.boolean()` is a footgun here: it just calls `Boolean(value)`
+    // under the hood, which would treat the string `"false"` as truthy.
+    // Instead, accept only the two literal strings we mean to support and
+    // transform to the matching boolean. Anything else (including absent)
+    // either defaults to false or surfaces as a 400.
+    strict: z
+        .string()
+        .optional()
+        .refine(
+            (v) => v === undefined || v === 'true' || v === 'false',
+            { message: 'strict must be "true" or "false"' },
+        )
+        .transform((v) => v === 'true'),
+});
+
 // Runs `check()` and rejects if it has not settled after `timeoutMs`. When the
 // timeout fires, the underlying check promise may still resolve or reject
 // later; the no-op `.catch` below attaches to that promise so a late
@@ -90,30 +110,52 @@ const checkRedis = async (): Promise<CheckResult> => {
     }
 };
 
-const checkZoekt = async (): Promise<CheckResult> => {
+const checkZoekt = async (strict: boolean): Promise<CheckResult> => {
     const start = Date.now();
     try {
-        await withTimeout('zoekt', async () => {
+        // The List response is captured so the strict path can decide
+        // whether the empty-shard case is acceptable or not.
+        const response = await withTimeout('zoekt', async () => {
             // Build the client inside the timeout so a first-call init stall
             // (e.g., vendored proto load) is also bounded.
             const client = await loadZoektClient();
-            await new Promise<void>((resolve, reject) => {
-                // Empty `List` is the smallest request that exercises the gRPC
-                // channel end-to-end. It returns an empty result, not an error,
-                // even when no repos are indexed. The 2s client-side
-                // `READINESS_TIMEOUT_MS` is the only timeout that actually
-                // bounds the call: `max_wall_time` is a `SearchOptions` field
-                // and does not apply to `List` (`ListOptions` only carries
-                // `field`).
-                client.List({}, (err) => {
+            return await new Promise<ZoektListResponse>((resolve, reject) => {
+                // Empty `List` is the smallest request that exercises the
+                // gRPC channel end-to-end. It returns an empty result, not
+                // an error, even when no repos are indexed. The 2s
+                // client-side `READINESS_TIMEOUT_MS` is the only timeout
+                // that actually bounds the call: `max_wall_time` is a
+                // `SearchOptions` field and does not apply to `List`
+                // (`ListOptions` only carries `field`).
+                client.List({}, (err, result) => {
                     if (err) {
                         reject(err);
                     } else {
-                        resolve();
+                        resolve(result);
                     }
                 });
             });
         }, READINESS_TIMEOUT_MS);
+
+        if (strict) {
+            // "Empty" means neither `repos` (Field = RepoListFieldRepos) nor
+            // `repos_map` (Field = RepoListFieldReposMap) carries any
+            // entries. Both arrays/objects are always returned by the gRPC
+            // stub, so the only thing we have to defend against is
+            // unexpected `undefined` (e.g. a stub mismatch).
+            const repos = Array.isArray(response.repos) ? response.repos : [];
+            const reposMap = response.repos_map && typeof response.repos_map === 'object'
+                ? response.repos_map
+                : {};
+            if (repos.length === 0 && Object.keys(reposMap).length === 0) {
+                return {
+                    status: 'empty',
+                    latencyMs: Date.now() - start,
+                    error: 'no repositories indexed (strict mode)',
+                };
+            }
+        }
+
         return { status: 'ok', latencyMs: Date.now() - start };
     } catch (err) {
         return {
@@ -125,22 +167,36 @@ const checkZoekt = async (): Promise<CheckResult> => {
 };
 
 // eslint-disable-next-line authz/require-auth-wrapper -- public readiness probe, no user data returned
-export const GET = apiHandler(async () => {
+export const GET = apiHandler(async (request: NextRequest) => {
+    const rawParams = {
+        strict: request.nextUrl.searchParams.get('strict') ?? undefined,
+    };
+    const parsed = queryParamsSchema.safeParse(rawParams);
+
+    if (!parsed.success) {
+        return serviceErrorResponse(
+            queryParamsSchemaValidationError(parsed.error)
+        );
+    }
+
+    const { strict } = parsed.data;
+
     const [postgres, redis, zoekt] = await Promise.all([
         checkPostgres(),
         checkRedis(),
-        checkZoekt(),
+        checkZoekt(strict),
     ]);
 
     const checks = { postgres, redis, zoekt };
     const healthy = postgres.status === 'ok' && redis.status === 'ok' && zoekt.status === 'ok';
 
     if (!healthy) {
-        logger.warn('readiness check failed', { checks });
+        logger.warn('readiness check failed', { checks, strict });
     }
 
     const body: ReadinessResponse = {
         status: healthy ? 'ok' : 'degraded',
+        strict,
         checks,
     };
     return Response.json(body, { status: healthy ? 200 : 503 });
diff --git a/packages/web/src/lib/zoektClient.ts b/packages/web/src/lib/zoektClient.ts
index accaf3963..e0418746a 100644
--- a/packages/web/src/lib/zoektClient.ts
+++ b/packages/web/src/lib/zoektClient.ts
@@ -6,8 +6,16 @@ export type ZoektListRequest = {
     opts?: { max_wall_time?: { seconds: number; nanos: number } };
 };
 
+// Loose summary of the `List` response. The full gRPC type is much wider
+// (see `proto/zoekt/webserver/v1/ListResponse.ts`); we only need the bits
+// the readiness probe inspects, so callers can mock it with a small object.
+export type ZoektListResponse = {
+    repos?: unknown[];
+    repos_map?: Record<number, unknown>;
+};
+
 export type ZoektClient = {
-    List: (request: ZoektListRequest, callback: (err: Error | null) => void) => void;
+    List: (request: ZoektListRequest, callback: (err: Error | null, result: ZoektListResponse) => void) => void;
 };
 
 let cachedClient: ZoektClient | undefined;

From 8ff1624d39f4dd0320f0d991d635fa971fd521b5 Mon Sep 17 00:00:00 2001
From: Harsh23Kashyap <55448981+Harsh23Kashyap@users.noreply.github.com>
Date: Sun, 26 Jul 2026 11:41:17 +0530
Subject: [PATCH 12/20] test(web): cover strict mode and invalid-param paths in
 readiness probe

Seven new test cases for the ?strict=true mode on /api/health/ready:

- Returns 200 with strict:true when Zoekt has at least one indexed repo.
- Returns 503 with zoekt.status:"empty" when Zoekt has no indexed
  repos (default Field = RepoListFieldRepos, empty repos array).
- Returns 503 in strict mode when the Zoekt response uses
  repos_map (Field = RepoListFieldReposMap, empty map).
- Returns 200 in strict mode when repos_map is non-empty.
- Backward-compat: returns 200 with strict:false and zoekt.status:"ok"
  when Zoekt has zero repos (the default behavior must NOT consider
  empty shards as a failure unless strict mode is requested).
- Treats an absent strict parameter as strict:false.
- Returns 400 with a clear error message when ?strict=yes (anything
  other than the literal strings "true" or "false" fails the
  Zod refinement).

The existing eight tests are updated to pass a minimal NextRequest
stand-in (via a new makeRequest helper) so the route can read the
strict query parameter, and the Zoekt List mock now passes a
response object to its callback (the route inspects the response in
strict mode).
---
 .../api/(server)/health/ready/route.test.ts   | 159 ++++++++++++++++--
 1 file changed, 144 insertions(+), 15 deletions(-)

diff --git a/packages/web/src/app/api/(server)/health/ready/route.test.ts b/packages/web/src/app/api/(server)/health/ready/route.test.ts
index a7203af01..a33102d5f 100644
--- a/packages/web/src/app/api/(server)/health/ready/route.test.ts
+++ b/packages/web/src/app/api/(server)/health/ready/route.test.ts
@@ -1,4 +1,5 @@
 import { beforeEach, describe, expect, test, vi } from 'vitest';
+import { NextRequest } from 'next/server';
 
 const mocks = vi.hoisted(() => ({
     unsafePrisma: {
@@ -41,24 +42,37 @@ vi.mock('@sourcebot/shared', () => ({
 
 const { GET } = await import('./route');
 
+// Minimal NextRequest stand-in. We only need `nextUrl.searchParams`; the
+// runtime calls are not exercised.
+const makeRequest = (search: Record<string, string> = {}): NextRequest => {
+    const params = new URLSearchParams(search);
+    const url = `http://localhost/api/health/ready?${params.toString()}`;
+    return new NextRequest(url);
+};
+
+// Default Zoekt response: a single indexed repo. Tests that need a different
+// shape override the mock in their own `beforeEach` / `mockImplementationOnce`.
+const defaultZoektResponse = { repos: [{}] };
+
 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);
+            (_request: unknown, callback: (err: Error | null, response?: { repos?: unknown[]; repos_map?: Record<number, unknown> }) => void) => {
+                callback(null, defaultZoektResponse);
             },
         );
     });
 
-    test('returns 200 with status:ok when all three dependencies are reachable', async () => {
-        const response = await GET();
+    test('returns 200 with status:ok and strict:false when all three dependencies are reachable', async () => {
+        const response = await GET(makeRequest());
         const body = await response.json();
 
         expect(response.status).toBe(200);
         expect(body.status).toBe('ok');
+        expect(body.strict).toBe(false);
         expect(body.checks.postgres.status).toBe('ok');
         expect(body.checks.redis.status).toBe('ok');
         expect(body.checks.zoekt.status).toBe('ok');
@@ -70,7 +84,7 @@ describe('GET /api/health/ready', () => {
     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 response = await GET(makeRequest());
         const body = await response.json();
 
         expect(response.status).toBe(503);
@@ -84,7 +98,7 @@ describe('GET /api/health/ready', () => {
     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 response = await GET(makeRequest());
         const body = await response.json();
 
         expect(response.status).toBe(503);
@@ -102,7 +116,7 @@ describe('GET /api/health/ready', () => {
             },
         );
 
-        const response = await GET();
+        const response = await GET(makeRequest());
         const body = await response.json();
 
         expect(response.status).toBe(503);
@@ -116,7 +130,7 @@ describe('GET /api/health/ready', () => {
     test('returns 503 with status:degraded when Redis returns a non-PONG response', async () => {
         mocks.redisPing.mockResolvedValue('NOT-PONG');
 
-        const response = await GET();
+        const response = await GET(makeRequest());
         const body = await response.json();
 
         expect(response.status).toBe(503);
@@ -134,13 +148,13 @@ describe('GET /api/health/ready', () => {
             () => new Promise((resolve) => setTimeout(() => resolve('PONG'), delay)),
         );
         mocks.zoektList.mockImplementation(
-            (_request: unknown, callback: (err: Error | null) => void) => {
-                setTimeout(() => callback(null), delay);
+            (_request: unknown, callback: (err: Error | null, response?: { repos?: unknown[]; repos_map?: Record<number, unknown> }) => void) => {
+                setTimeout(() => callback(null, defaultZoektResponse), delay);
             },
         );
 
         const start = Date.now();
-        const response = await GET();
+        const response = await GET(makeRequest());
         const elapsed = Date.now() - start;
         const body = await response.json();
 
@@ -165,12 +179,12 @@ describe('GET /api/health/ready', () => {
             mocks.unsafePrisma.$queryRaw.mockRejectedValue(checkRejection);
             mocks.redisPing.mockResolvedValue('PONG');
             mocks.zoektList.mockImplementation(
-                (_request: unknown, callback: (err: Error | null) => void) => {
-                    callback(null);
+                (_request: unknown, callback: (err: Error | null, response?: { repos?: unknown[]; repos_map?: Record<number, unknown> }) => void) => {
+                    callback(null, defaultZoektResponse);
                 },
             );
 
-            const response = await GET();
+            const response = await GET(makeRequest());
             const body = await response.json();
 
             expect(response.status).toBe(503);
@@ -191,9 +205,124 @@ describe('GET /api/health/ready', () => {
         // 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();
+        const response = await GET(makeRequest());
         expect(response.status).toBe(200);
         expect(mocks.zoektList).toHaveBeenCalledTimes(1);
         expect(mocks.zoektList).toHaveBeenCalledWith({}, expect.any(Function));
     });
+
+    describe('?strict=true', () => {
+        test('returns 200 with status:ok and strict:true when Zoekt has at least one indexed repo', async () => {
+            mocks.zoektList.mockImplementation(
+                (_request: unknown, callback: (err: Error | null, response?: { repos?: unknown[]; repos_map?: Record<number, unknown> }) => void) => {
+                    callback(null, { repos: [{ repository: { name: 'foo' } }] });
+                },
+            );
+
+            const response = await GET(makeRequest({ strict: 'true' }));
+            const body = await response.json();
+
+            expect(response.status).toBe(200);
+            expect(body.status).toBe('ok');
+            expect(body.strict).toBe(true);
+            expect(body.checks.zoekt.status).toBe('ok');
+        });
+
+        test('returns 503 with status:degraded and zoekt.status:"empty" when Zoekt has no indexed repos', async () => {
+            mocks.zoektList.mockImplementation(
+                (_request: unknown, callback: (err: Error | null, response?: { repos?: unknown[]; repos_map?: Record<number, unknown> }) => void) => {
+                    callback(null, { repos: [] });
+                },
+            );
+
+            const response = await GET(makeRequest({ strict: 'true' }));
+            const body = await response.json();
+
+            expect(response.status).toBe(503);
+            expect(body.status).toBe('degraded');
+            expect(body.strict).toBe(true);
+            expect(body.checks.zoekt.status).toBe('empty');
+            expect(body.checks.zoekt.error).toContain('no repositories indexed');
+            expect(body.checks.postgres.status).toBe('ok');
+            expect(body.checks.redis.status).toBe('ok');
+        });
+
+        test('returns 503 in strict mode when the Zoekt response uses repos_map (RepoListFieldReposMap)', async () => {
+            // The gRPC server may return `repos_map` (a numeric-keyed object)
+            // when `ListOptions.Field = RepoListFieldReposMap`. Empty
+            // `repos_map` should also be treated as empty in strict mode.
+            mocks.zoektList.mockImplementation(
+                (_request: unknown, callback: (err: Error | null, response?: { repos?: unknown[]; repos_map?: Record<number, unknown> }) => void) => {
+                    callback(null, { repos_map: {} });
+                },
+            );
+
+            const response = await GET(makeRequest({ strict: 'true' }));
+            const body = await response.json();
+
+            expect(response.status).toBe(503);
+            expect(body.checks.zoekt.status).toBe('empty');
+        });
+
+        test('returns 200 in strict mode when repos_map is non-empty', async () => {
+            mocks.zoektList.mockImplementation(
+                (_request: unknown, callback: (err: Error | null, response?: { repos?: unknown[]; repos_map?: Record<number, unknown> }) => void) => {
+                    callback(null, { repos_map: { 1: { repository: { name: 'bar' } } } });
+                },
+            );
+
+            const response = await GET(makeRequest({ strict: 'true' }));
+            const body = await response.json();
+
+            expect(response.status).toBe(200);
+            expect(body.checks.zoekt.status).toBe('ok');
+        });
+    });
+
+    describe('?strict=false and absent', () => {
+        test('returns 200 with strict:false and zoekt.status:ok when Zoekt has zero repos', async () => {
+            // Backward-compat: the default behavior must NOT consider an
+            // empty Zoekt shard set as a failure. Operators who do not opt
+            // in to strict mode should see the same response as before.
+            mocks.zoektList.mockImplementation(
+                (_request: unknown, callback: (err: Error | null, response?: { repos?: unknown[]; repos_map?: Record<number, unknown> }) => void) => {
+                    callback(null, { repos: [] });
+                },
+            );
+
+            const response = await GET(makeRequest({ strict: 'false' }));
+            const body = await response.json();
+
+            expect(response.status).toBe(200);
+            expect(body.status).toBe('ok');
+            expect(body.strict).toBe(false);
+            expect(body.checks.zoekt.status).toBe('ok');
+        });
+
+        test('treats an absent strict parameter as strict:false', async () => {
+            mocks.zoektList.mockImplementation(
+                (_request: unknown, callback: (err: Error | null, response?: { repos?: unknown[]; repos_map?: Record<number, unknown> }) => void) => {
+                    callback(null, { repos: [] });
+                },
+            );
+
+            const response = await GET(makeRequest());
+            const body = await response.json();
+
+            expect(response.status).toBe(200);
+            expect(body.strict).toBe(false);
+            expect(body.checks.zoekt.status).toBe('ok');
+        });
+    });
+
+    describe('invalid ?strict value', () => {
+        test('returns 400 with a clear error message when strict is not parseable', async () => {
+            const response = await GET(makeRequest({ strict: 'yes' }));
+            const body = await response.json();
+
+            expect(response.status).toBe(400);
+            expect(body.message).toBeDefined();
+            expect(body.message).toMatch(/strict/);
+        });
+    });
 });

From a238ee3e3b4fe0d91c44f1d779d8b41aff1b1491 Mon Sep 17 00:00:00 2001
From: Harsh23Kashyap <55448981+Harsh23Kashyap@users.noreply.github.com>
Date: Sun, 26 Jul 2026 11:41:21 +0530
Subject: [PATCH 13/20] docs(health): document the ?strict=true readiness mode

Adds a 'Strict mode' subsection to docs/docs/api-reference/health.mdx
that explains the operator motivation, the new response fields
(strict top-level, zoekt.status:"empty"), and the distinction
between error and empty in the Zoekt check's status field.

Updates the response-shape examples to include the new strict
field and adds a Kubernetes readinessProbe snippet that points at
the strict path for deployments that should not receive traffic
until the shard set is non-empty.
---
 docs/docs/api-reference/health.mdx | 33 ++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/docs/docs/api-reference/health.mdx b/docs/docs/api-reference/health.mdx
index 3550dd697..9641c8799 100644
--- a/docs/docs/api-reference/health.mdx
+++ b/docs/docs/api-reference/health.mdx
@@ -20,11 +20,40 @@ Returns `200 OK` with `{"status":"ok", "checks":{...}}` when Postgres, Redis, an
 
 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.
 
+### Strict mode
+
+Add `?strict=true` to require the Zoekt shard set to be non-empty as well. The default mode only confirms the dependencies are reachable; strict mode confirms the instance can actually serve a search that returns results. A freshly-started instance, or one whose connection sync has silently failed, returns `503` until at least one repository is indexed.
+
+```bash
+curl -fsS 'https://sourcebot.example.com/api/health/ready?strict=true' | jq .status
+# "ok"     — Postgres, Redis, AND Zoekt (with at least one indexed repo) are healthy
+# "degraded" — something failed, see `checks` for which
+```
+
+The response always includes a top-level `strict` field so the operator can confirm the mode that was applied:
+
+```json
+{
+  "status": "degraded",
+  "strict": true,
+  "checks": {
+    "postgres": { "status": "ok",    "latencyMs": 3 },
+    "redis":    { "status": "ok",    "latencyMs": 1 },
+    "zoekt":    { "status": "empty", "latencyMs": 18, "error": "no repositories indexed (strict mode)" }
+  }
+}
+```
+
+The Zoekt check distinguishes the two failure modes in its `status` field:
+- `error` — the gRPC call itself failed (Zoekt unreachable, timeout, etc.).
+- `empty` — strict mode is on and the shard set is empty. The dependency is healthy; the instance is just not yet useful.
+
 ### Response shape
 
 ```json
 {
   "status": "ok",
+  "strict": false,
   "checks": {
     "postgres": { "status": "ok", "latencyMs": 3 },
     "redis":    { "status": "ok", "latencyMs": 1 },
@@ -38,6 +67,7 @@ When degraded, each failed check carries an `error` field with the underlying me
 ```json
 {
   "status": "degraded",
+  "strict": false,
   "checks": {
     "postgres": { "status": "ok",    "latencyMs": 4 },
     "redis":    { "status": "ok",    "latencyMs": 1 },
@@ -88,6 +118,9 @@ When degraded, each failed check carries an `error` field with the underlying me
       timeoutSeconds: 5
       successThreshold: 1
       failureThreshold: 3
+    # For deployments that should not receive traffic until the shard set
+    # is non-empty, switch to the strict readiness probe:
+    #   path: /api/health/ready?strict=true
     ```
   </Tab>
 </Tabs>

From 6166565db439a905725b14f10a86e68564f6cd22 Mon Sep 17 00:00:00 2001
From: Harsh23Kashyap <55448981+Harsh23Kashyap@users.noreply.github.com>
Date: Sun, 26 Jul 2026 11:41:21 +0530
Subject: [PATCH 14/20] chore: changelog entry for ?strict=true readiness mode

Adds an Added entry under [Unreleased] for the new ?strict=true
query parameter on /api/health/ready, referencing issue #1511.
---
 CHANGELOG.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 78bcd0988..8b8a3a7a2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 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)
+- Added a `?strict=true` query parameter to `GET /api/health/ready`. When set, the endpoint reports `503 / status: "degraded"` and `zoekt.status: "empty"` if the Zoekt shard set contains no indexed repositories, distinguishing "Zoekt is unreachable" from "Zoekt is up but the instance is not yet useful" for orchestrators. Default behavior is unchanged. [#1511](https://github.com/sourcebot-dev/sourcebot/issues/1511)
 
 ### Changed
 - Vulnerability triage now keeps Linear issues synchronized with current security findings.

From aed1a21f7f1db0ec3eab4a37ae989fc599eaff9b Mon Sep 17 00:00:00 2001
From: Harsh23Kashyap <55448981+Harsh23Kashyap@users.noreply.github.com>
Date: Sun, 26 Jul 2026 11:43:26 +0530
Subject: [PATCH 15/20] style(web): tighten comments and pull a repeated test
 type alias

- route.ts: trim a couple of over-explained comments around the strict
  Zoekt check; the proto's __Output type already guarantees the shape
  we read, so the defensive 'stub mismatch' framing is unnecessary.
- route.test.ts: pull the verbose ZoektListCallback type out to a
  single alias so the seven mockImplementation blocks stop carrying
  the same 80-character inline signature.
- health.mdx: drop em dashes per the docs style guide.
---
 docs/docs/api-reference/health.mdx            |  8 ++---
 .../api/(server)/health/ready/route.test.ts   | 29 ++++++++++++-------
 .../app/api/(server)/health/ready/route.ts    | 24 ++++++---------
 3 files changed, 31 insertions(+), 30 deletions(-)

diff --git a/docs/docs/api-reference/health.mdx b/docs/docs/api-reference/health.mdx
index 9641c8799..bafc8cfa2 100644
--- a/docs/docs/api-reference/health.mdx
+++ b/docs/docs/api-reference/health.mdx
@@ -26,8 +26,8 @@ Add `?strict=true` to require the Zoekt shard set to be non-empty as well. The d
 
 ```bash
 curl -fsS 'https://sourcebot.example.com/api/health/ready?strict=true' | jq .status
-# "ok"     — Postgres, Redis, AND Zoekt (with at least one indexed repo) are healthy
-# "degraded" — something failed, see `checks` for which
+# "ok"       Postgres, Redis, and Zoekt (with at least one indexed repo) are healthy
+# "degraded" Something failed, see `checks` for which
 ```
 
 The response always includes a top-level `strict` field so the operator can confirm the mode that was applied:
@@ -45,8 +45,8 @@ The response always includes a top-level `strict` field so the operator can conf
 ```
 
 The Zoekt check distinguishes the two failure modes in its `status` field:
-- `error` — the gRPC call itself failed (Zoekt unreachable, timeout, etc.).
-- `empty` — strict mode is on and the shard set is empty. The dependency is healthy; the instance is just not yet useful.
+- `error`. The gRPC call itself failed (Zoekt unreachable, timeout, etc.).
+- `empty`. Strict mode is on and the shard set is empty. The dependency is healthy; the instance is just not yet useful.
 
 ### Response shape
 
diff --git a/packages/web/src/app/api/(server)/health/ready/route.test.ts b/packages/web/src/app/api/(server)/health/ready/route.test.ts
index a33102d5f..0a78522ef 100644
--- a/packages/web/src/app/api/(server)/health/ready/route.test.ts
+++ b/packages/web/src/app/api/(server)/health/ready/route.test.ts
@@ -50,17 +50,24 @@ const makeRequest = (search: Record<string, string> = {}): NextRequest => {
     return new NextRequest(url);
 };
 
-// Default Zoekt response: a single indexed repo. Tests that need a different
-// shape override the mock in their own `beforeEach` / `mockImplementationOnce`.
+// Default Zoekt response: a single indexed repo. Tests that need a
+// different shape override the mock implementation locally.
 const defaultZoektResponse = { repos: [{}] };
 
+// gRPC callback shape: (err, response) => void. Pulled out so the seven
+// `mocks.zoektList.mockImplementation(...)` blocks below stay short.
+type ZoektListCallback = (
+    err: Error | null,
+    response?: { repos?: unknown[]; repos_map?: Record<number, unknown> },
+) => void;
+
 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, response?: { repos?: unknown[]; repos_map?: Record<number, unknown> }) => void) => {
+            (_request: unknown, callback: ZoektListCallback) => {
                 callback(null, defaultZoektResponse);
             },
         );
@@ -148,7 +155,7 @@ describe('GET /api/health/ready', () => {
             () => new Promise((resolve) => setTimeout(() => resolve('PONG'), delay)),
         );
         mocks.zoektList.mockImplementation(
-            (_request: unknown, callback: (err: Error | null, response?: { repos?: unknown[]; repos_map?: Record<number, unknown> }) => void) => {
+            (_request: unknown, callback: ZoektListCallback) => {
                 setTimeout(() => callback(null, defaultZoektResponse), delay);
             },
         );
@@ -179,7 +186,7 @@ describe('GET /api/health/ready', () => {
             mocks.unsafePrisma.$queryRaw.mockRejectedValue(checkRejection);
             mocks.redisPing.mockResolvedValue('PONG');
             mocks.zoektList.mockImplementation(
-                (_request: unknown, callback: (err: Error | null, response?: { repos?: unknown[]; repos_map?: Record<number, unknown> }) => void) => {
+                (_request: unknown, callback: ZoektListCallback) => {
                     callback(null, defaultZoektResponse);
                 },
             );
@@ -214,7 +221,7 @@ describe('GET /api/health/ready', () => {
     describe('?strict=true', () => {
         test('returns 200 with status:ok and strict:true when Zoekt has at least one indexed repo', async () => {
             mocks.zoektList.mockImplementation(
-                (_request: unknown, callback: (err: Error | null, response?: { repos?: unknown[]; repos_map?: Record<number, unknown> }) => void) => {
+                (_request: unknown, callback: ZoektListCallback) => {
                     callback(null, { repos: [{ repository: { name: 'foo' } }] });
                 },
             );
@@ -230,7 +237,7 @@ describe('GET /api/health/ready', () => {
 
         test('returns 503 with status:degraded and zoekt.status:"empty" when Zoekt has no indexed repos', async () => {
             mocks.zoektList.mockImplementation(
-                (_request: unknown, callback: (err: Error | null, response?: { repos?: unknown[]; repos_map?: Record<number, unknown> }) => void) => {
+                (_request: unknown, callback: ZoektListCallback) => {
                     callback(null, { repos: [] });
                 },
             );
@@ -252,7 +259,7 @@ describe('GET /api/health/ready', () => {
             // when `ListOptions.Field = RepoListFieldReposMap`. Empty
             // `repos_map` should also be treated as empty in strict mode.
             mocks.zoektList.mockImplementation(
-                (_request: unknown, callback: (err: Error | null, response?: { repos?: unknown[]; repos_map?: Record<number, unknown> }) => void) => {
+                (_request: unknown, callback: ZoektListCallback) => {
                     callback(null, { repos_map: {} });
                 },
             );
@@ -266,7 +273,7 @@ describe('GET /api/health/ready', () => {
 
         test('returns 200 in strict mode when repos_map is non-empty', async () => {
             mocks.zoektList.mockImplementation(
-                (_request: unknown, callback: (err: Error | null, response?: { repos?: unknown[]; repos_map?: Record<number, unknown> }) => void) => {
+                (_request: unknown, callback: ZoektListCallback) => {
                     callback(null, { repos_map: { 1: { repository: { name: 'bar' } } } });
                 },
             );
@@ -285,7 +292,7 @@ describe('GET /api/health/ready', () => {
             // empty Zoekt shard set as a failure. Operators who do not opt
             // in to strict mode should see the same response as before.
             mocks.zoektList.mockImplementation(
-                (_request: unknown, callback: (err: Error | null, response?: { repos?: unknown[]; repos_map?: Record<number, unknown> }) => void) => {
+                (_request: unknown, callback: ZoektListCallback) => {
                     callback(null, { repos: [] });
                 },
             );
@@ -301,7 +308,7 @@ describe('GET /api/health/ready', () => {
 
         test('treats an absent strict parameter as strict:false', async () => {
             mocks.zoektList.mockImplementation(
-                (_request: unknown, callback: (err: Error | null, response?: { repos?: unknown[]; repos_map?: Record<number, unknown> }) => void) => {
+                (_request: unknown, callback: ZoektListCallback) => {
                     callback(null, { repos: [] });
                 },
             );
diff --git a/packages/web/src/app/api/(server)/health/ready/route.ts b/packages/web/src/app/api/(server)/health/ready/route.ts
index 8dfe7bc48..d9f5e220f 100644
--- a/packages/web/src/app/api/(server)/health/ready/route.ts
+++ b/packages/web/src/app/api/(server)/health/ready/route.ts
@@ -31,11 +31,9 @@ type ReadinessResponse = {
 };
 
 const queryParamsSchema = z.object({
-    // `z.coerce.boolean()` is a footgun here: it just calls `Boolean(value)`
-    // under the hood, which would treat the string `"false"` as truthy.
-    // Instead, accept only the two literal strings we mean to support and
-    // transform to the matching boolean. Anything else (including absent)
-    // either defaults to false or surfaces as a 400.
+    // `z.coerce.boolean()` is a footgun: it just calls `Boolean(value)` and
+    // would treat the string `"false"` as truthy. Accept only the two
+    // literal strings we mean to support and transform to a boolean.
     strict: z
         .string()
         .optional()
@@ -114,7 +112,7 @@ const checkZoekt = async (strict: boolean): Promise<CheckResult> => {
     const start = Date.now();
     try {
         // The List response is captured so the strict path can decide
-        // whether the empty-shard case is acceptable or not.
+        // whether the empty-shard case is acceptable.
         const response = await withTimeout('zoekt', async () => {
             // Build the client inside the timeout so a first-call init stall
             // (e.g., vendored proto load) is also bounded.
@@ -138,15 +136,11 @@ const checkZoekt = async (strict: boolean): Promise<CheckResult> => {
         }, READINESS_TIMEOUT_MS);
 
         if (strict) {
-            // "Empty" means neither `repos` (Field = RepoListFieldRepos) nor
-            // `repos_map` (Field = RepoListFieldReposMap) carries any
-            // entries. Both arrays/objects are always returned by the gRPC
-            // stub, so the only thing we have to defend against is
-            // unexpected `undefined` (e.g. a stub mismatch).
-            const repos = Array.isArray(response.repos) ? response.repos : [];
-            const reposMap = response.repos_map && typeof response.repos_map === 'object'
-                ? response.repos_map
-                : {};
+            // Check both `repos` (Field = RepoListFieldRepos) and
+            // `repos_map` (Field = RepoListFieldReposMap) so the result is
+            // correct regardless of which field the server populates.
+            const repos = response.repos ?? [];
+            const reposMap = response.repos_map ?? {};
             if (repos.length === 0 && Object.keys(reposMap).length === 0) {
                 return {
                     status: 'empty',

From 3fa3c63cef493a5b28adc887dcce608bbbbdf452 Mon Sep 17 00:00:00 2001
From: Harsh23Kashyap <55448981+Harsh23Kashyap@users.noreply.github.com>
Date: Sun, 26 Jul 2026 11:49:17 +0530
Subject: [PATCH 16/20] fix(web): handle undefined Zoekt List response in the
 readiness probe

Address Cursor Bugbot finding on PR #1512: a malformed gRPC response
can fire the List callback with `err === null` and `result === undefined`.
Without a guard, the route would throw on `response.repos` and the
failure would surface as a generic Node unhandled-rejection path
instead of the controlled `error` status that the response shape
advertises.

`zoektSearch` applies the same `error || !response` pattern
(`features/search/zoektSearcher.ts`). Reject with a clear error
message when the callback fires with no error but no response either,
matching that contract.

Added a regression test that fires the List callback with
`callback(null, undefined)` and asserts the response carries
`zoekt.status:"error"` and `zoekt.error` mentioning the missing
response.
---
 .../api/(server)/health/ready/route.test.ts   | 24 +++++++++++++++++++
 .../app/api/(server)/health/ready/route.ts    |  8 +++++++
 2 files changed, 32 insertions(+)

diff --git a/packages/web/src/app/api/(server)/health/ready/route.test.ts b/packages/web/src/app/api/(server)/health/ready/route.test.ts
index 0a78522ef..3e88ada59 100644
--- a/packages/web/src/app/api/(server)/health/ready/route.test.ts
+++ b/packages/web/src/app/api/(server)/health/ready/route.test.ts
@@ -218,6 +218,30 @@ describe('GET /api/health/ready', () => {
         expect(mocks.zoektList).toHaveBeenCalledWith({}, expect.any(Function));
     });
 
+    test('reports zoekt.status:"error" (not a thrown exception) when the gRPC callback fires with no response', async () => {
+        // Regression guard: a malformed gRPC response can fire the callback
+        // with `err === null` and `result === undefined`. Without the
+        // `!result` check the route would throw on `response.repos` and
+        // surface the failure as a generic Node unhandled-rejection path
+        // instead of the controlled `error` status. `zoektSearch` applies
+        // the same `error || !response` guard.
+        mocks.zoektList.mockImplementation(
+            (_request: unknown, callback: ZoektListCallback) => {
+                callback(null, undefined);
+            },
+        );
+
+        const response = await GET(makeRequest());
+        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('no response');
+        expect(body.checks.postgres.status).toBe('ok');
+        expect(body.checks.redis.status).toBe('ok');
+    });
+
     describe('?strict=true', () => {
         test('returns 200 with status:ok and strict:true when Zoekt has at least one indexed repo', async () => {
             mocks.zoektList.mockImplementation(
diff --git a/packages/web/src/app/api/(server)/health/ready/route.ts b/packages/web/src/app/api/(server)/health/ready/route.ts
index d9f5e220f..d5e6b9bbb 100644
--- a/packages/web/src/app/api/(server)/health/ready/route.ts
+++ b/packages/web/src/app/api/(server)/health/ready/route.ts
@@ -126,8 +126,16 @@ const checkZoekt = async (strict: boolean): Promise<CheckResult> => {
                 // `SearchOptions` field and does not apply to `List`
                 // (`ListOptions` only carries `field`).
                 client.List({}, (err, result) => {
+                    // `zoektSearch` rejects when the callback fires with
+                    // no error but no response either (see
+                    // `features/search/zoektSearcher.ts`). Do the same
+                    // here: a missing result would otherwise throw on
+                    // `response.repos` and surface as a generic `error`
+                    // instead of the intended `empty` strict-mode status.
                     if (err) {
                         reject(err);
+                    } else if (!result) {
+                        reject(new Error('zoekt List RPC returned no response'));
                     } else {
                         resolve(result);
                     }

From a92eceb01b2f3923211e07022e1160925aefea98 Mon Sep 17 00:00:00 2001
From: Harsh23Kashyap <55448981+Harsh23Kashyap@users.noreply.github.com>
Date: Sun, 26 Jul 2026 11:57:13 +0530
Subject: [PATCH 17/20] fix(web): set 500MB gRPC message size limits on the
 readiness probe Zoekt client

Address Cursor Bugbot finding on PR #1512 (zoektClient.ts#L48-L52):
the readiness probe's Zoekt client was created without
`grpc.max_receive_message_length` / `grpc.max_send_message_length`,
while `zoektSearcher` uses 500MB. A healthy Zoekt instance with a
large repo catalog could hit the default 4MB gRPC receive cap, fail
the probe, and report `zoekt.status:"error"` even though search
against the same backend would succeed.

Match the channel options `zoektSearcher` uses (500MB receive / send)
so a healthy Zoekt does not fail the probe on a large catalog. Also
loosens the constructor type in zoektClient.ts to accept the third
`options` argument; the loose type was previously hard-coded to two
parameters, which would have rejected this change at tsc time.
---
 packages/web/src/lib/zoektClient.ts | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/packages/web/src/lib/zoektClient.ts b/packages/web/src/lib/zoektClient.ts
index e0418746a..8e161ed66 100644
--- a/packages/web/src/lib/zoektClient.ts
+++ b/packages/web/src/lib/zoektClient.ts
@@ -41,14 +41,22 @@ const buildClient = async (): Promise<ZoektClient> => {
     });
 
     const proto = grpc.loadPackageDefinition(packageDefinition) as unknown as {
-        zoekt: { webserver: { v1: { WebserverService: new (address: string, credentials: unknown) => ZoektClient } } };
+        zoekt: { webserver: { v1: { WebserverService: new (address: string, credentials: unknown, options?: Record<string, unknown>) => ZoektClient } } };
     };
 
     const zoektUrl = new URL(shared.env.ZOEKT_WEBSERVER_URL);
     const grpcAddress = `${zoektUrl.hostname}:${zoektUrl.port}`;
+    // Match the channel options used by `zoektSearcher` so a healthy Zoekt
+    // instance with a large repo catalog does not fail the probe just
+    // because the default 4MB gRPC receive cap is smaller than the
+    // response.
     return new proto.zoekt.webserver.v1.WebserverService(
         grpcAddress,
         grpc.credentials.createInsecure(),
+        {
+            'grpc.max_receive_message_length': 500 * 1024 * 1024, // 500MB
+            'grpc.max_send_message_length': 500 * 1024 * 1024,    // 500MB
+        },
     );
 };
 

From 4ef628d11e250bd2103633d5b72af56b6969f381 Mon Sep 17 00:00:00 2001
From: Harsh23Kashyap <55448981+Harsh23Kashyap@users.noreply.github.com>
Date: Sun, 26 Jul 2026 11:57:13 +0530
Subject: [PATCH 18/20] fix(web): do not leak upstream error details on the
 unauthenticated readiness probe

Address CodeRabbit security finding on PR #1512: the readiness route
returns raw `err.message` from Prisma / Redis / gRPC in the public
JSON response. Since the route is unauthenticated and may be reachable
at a public URL, those messages can leak internal hostnames, ports,
or connection details to any caller.

- Add a new `errorDetail` field on the per-check `CheckResult` that
  carries the raw `err.message`.
- Replace the public `error` field on degraded checks with a generic
  "<label> check failed: see server logs" string.
- The GET handler logs the FULL per-check result (with `errorDetail`)
  when the overall probe is degraded, so operators still have the
  diagnostic detail on the server side.
- The response body uses a stripped view that omits `errorDetail`.

Tests updated: the four degraded-path tests now assert the generic
public error string, that the internal message (containing fake
hostnames) does not appear in the response, that `errorDetail` is
undefined on the wire, and that the full message is present in the
server-side log call.
---
 .../api/(server)/health/ready/route.test.ts   | 45 +++++++++++++------
 .../app/api/(server)/health/ready/route.ts    | 40 ++++++++++++++---
 2 files changed, 66 insertions(+), 19 deletions(-)

diff --git a/packages/web/src/app/api/(server)/health/ready/route.test.ts b/packages/web/src/app/api/(server)/health/ready/route.test.ts
index 3e88ada59..b49269304 100644
--- a/packages/web/src/app/api/(server)/health/ready/route.test.ts
+++ b/packages/web/src/app/api/(server)/health/ready/route.test.ts
@@ -35,11 +35,13 @@ vi.mock('@sourcebot/shared', () => ({
     createLogger: () => ({
         debug: vi.fn(),
         info: vi.fn(),
-        warn: vi.fn(),
+        warn: mockLoggerWarn,
         error: vi.fn(),
     }),
 }));
 
+const mockLoggerWarn = vi.fn();
+
 const { GET } = await import('./route');
 
 // Minimal NextRequest stand-in. We only need `nextUrl.searchParams`; the
@@ -88,8 +90,9 @@ describe('GET /api/health/ready', () => {
         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'));
+    test('returns 503 with status:degraded and a generic postgres error when Postgres is unreachable', async () => {
+        const internalError = new Error('connection refused: host=db.internal.example.com:5432');
+        mocks.unsafePrisma.$queryRaw.mockRejectedValue(internalError);
 
         const response = await GET(makeRequest());
         const body = await response.json();
@@ -97,13 +100,22 @@ describe('GET /api/health/ready', () => {
         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');
+        // The public error is generic. The internal message (which
+        // contains the host:port) must not leak.
+        expect(body.checks.postgres.error).toBe('postgres check failed: see server logs');
+        expect(body.checks.postgres.error).not.toContain('db.internal.example.com');
+        expect(body.checks.postgres.errorDetail).toBeUndefined();
         expect(body.checks.redis.status).toBe('ok');
         expect(body.checks.zoekt.status).toBe('ok');
+
+        // The full error detail is preserved on the server-side log call.
+        const warnCall = mockLoggerWarn.mock.calls[mockLoggerWarn.mock.calls.length - 1];
+        expect(JSON.stringify(warnCall)).toContain('db.internal.example.com');
     });
 
-    test('returns 503 with status:degraded and a redis error when Redis ping fails', async () => {
-        mocks.redisPing.mockRejectedValue(new Error('redis down'));
+    test('returns 503 with status:degraded and a generic redis error when Redis ping fails', async () => {
+        const internalError = new Error('redis down: redis://10.0.0.42:6379');
+        mocks.redisPing.mockRejectedValue(internalError);
 
         const response = await GET(makeRequest());
         const body = await response.json();
@@ -112,14 +124,17 @@ describe('GET /api/health/ready', () => {
         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.redis.error).toBe('redis check failed: see server logs');
+        expect(body.checks.redis.error).not.toContain('10.0.0.42');
+        expect(body.checks.redis.errorDetail).toBeUndefined();
         expect(body.checks.zoekt.status).toBe('ok');
     });
 
-    test('returns 503 with status:degraded when the Zoekt gRPC call errors', async () => {
+    test('returns 503 with status:degraded and a generic zoekt error when the gRPC call fails', async () => {
+        const internalError = new Error('UNAVAILABLE: zoekt-web-0.zoekt.svc.cluster.local:6070');
         mocks.zoektList.mockImplementation(
-            (_request: unknown, callback: (err: Error | null) => void) => {
-                callback(new Error('UNAVAILABLE: zoekt not reachable'));
+            (_request: unknown, callback: ZoektListCallback) => {
+                callback(internalError);
             },
         );
 
@@ -129,7 +144,9 @@ describe('GET /api/health/ready', () => {
         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.zoekt.error).toBe('zoekt check failed: see server logs');
+        expect(body.checks.zoekt.error).not.toContain('cluster.local');
+        expect(body.checks.zoekt.errorDetail).toBeUndefined();
         expect(body.checks.postgres.status).toBe('ok');
         expect(body.checks.redis.status).toBe('ok');
     });
@@ -143,7 +160,9 @@ describe('GET /api/health/ready', () => {
         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');
+        // "unexpected ping response" is the internal message; the public
+        // path should not include it.
+        expect(body.checks.redis.error).toBe('redis check failed: see server logs');
     });
 
     test('runs all three checks in parallel (Promise.all)', async () => {
@@ -237,7 +256,7 @@ describe('GET /api/health/ready', () => {
         expect(response.status).toBe(503);
         expect(body.status).toBe('degraded');
         expect(body.checks.zoekt.status).toBe('error');
-        expect(body.checks.zoekt.error).toContain('no response');
+        expect(body.checks.zoekt.error).toBe('zoekt check failed: see server logs');
         expect(body.checks.postgres.status).toBe('ok');
         expect(body.checks.redis.status).toBe('ok');
     });
diff --git a/packages/web/src/app/api/(server)/health/ready/route.ts b/packages/web/src/app/api/(server)/health/ready/route.ts
index d5e6b9bbb..e3d4948aa 100644
--- a/packages/web/src/app/api/(server)/health/ready/route.ts
+++ b/packages/web/src/app/api/(server)/health/ready/route.ts
@@ -18,7 +18,14 @@ type CheckStatus = 'ok' | 'error' | 'empty';
 type CheckResult = {
     status: CheckStatus;
     latencyMs: number;
+    /** Client-safe error description. Optional; present when status !== 'ok'. */
     error?: string;
+    /**
+     * Server-side error detail. Never sent over the wire: the public
+     * `error` field is the only one that ends up in the JSON response.
+     * Logged by the GET handler when the overall probe is degraded.
+     */
+    errorDetail?: string;
 };
 type ReadinessResponse = {
     status: 'ok' | 'degraded';
@@ -72,6 +79,13 @@ const withTimeout = async <T>(
     }
 };
 
+// The readiness route is unauthenticated and may be reachable at a public
+// URL, so per-check error strings returned to the caller are intentionally
+// generic. The full `err` is preserved on the `CheckResult` (under
+// `errorDetail`) and logged server-side; the public `error` field carries
+// only the check label and a hint about the failure mode.
+const PUBLIC_ERROR = (label: string, detail: string) => `${label} check failed: ${detail}`;
+
 const checkPostgres = async (): Promise<CheckResult> => {
     const start = Date.now();
     try {
@@ -83,7 +97,8 @@ const checkPostgres = async (): Promise<CheckResult> => {
         return {
             status: 'error',
             latencyMs: Date.now() - start,
-            error: err instanceof Error ? err.message : String(err),
+            error: PUBLIC_ERROR('postgres', 'see server logs'),
+            errorDetail: err instanceof Error ? err.message : String(err),
         };
     }
 };
@@ -103,7 +118,8 @@ const checkRedis = async (): Promise<CheckResult> => {
         return {
             status: 'error',
             latencyMs: Date.now() - start,
-            error: err instanceof Error ? err.message : String(err),
+            error: PUBLIC_ERROR('redis', 'see server logs'),
+            errorDetail: err instanceof Error ? err.message : String(err),
         };
     }
 };
@@ -163,7 +179,8 @@ const checkZoekt = async (strict: boolean): Promise<CheckResult> => {
         return {
             status: 'error',
             latencyMs: Date.now() - start,
-            error: err instanceof Error ? err.message : String(err),
+            error: PUBLIC_ERROR('zoekt', 'see server logs'),
+            errorDetail: err instanceof Error ? err.message : String(err),
         };
     }
 };
@@ -189,17 +206,28 @@ export const GET = apiHandler(async (request: NextRequest) => {
         checkZoekt(strict),
     ]);
 
-    const checks = { postgres, redis, zoekt };
+    // `errorDetail` is server-side only and must never reach the response
+    // body. The full per-check result (including `errorDetail`) is what
+    // the logger emits; the public response uses the stripped view.
+    const stripDetail = ({ errorDetail: _errorDetail, ...publicCheck }: CheckResult) => publicCheck;
+    const publicChecks = {
+        postgres: stripDetail(postgres),
+        redis: stripDetail(redis),
+        zoekt: stripDetail(zoekt),
+    };
     const healthy = postgres.status === 'ok' && redis.status === 'ok' && zoekt.status === 'ok';
 
     if (!healthy) {
-        logger.warn('readiness check failed', { checks, strict });
+        logger.warn('readiness check failed', {
+            checks: { postgres, redis, zoekt },
+            strict,
+        });
     }
 
     const body: ReadinessResponse = {
         status: healthy ? 'ok' : 'degraded',
         strict,
-        checks,
+        checks: publicChecks,
     };
     return Response.json(body, { status: healthy ? 200 : 503 });
 }, { track: false });

From 2b8b833deae21dd439c75e9226e5cf7a653ac998 Mon Sep 17 00:00:00 2001
From: Harsh23Kashyap <55448981+Harsh23Kashyap@users.noreply.github.com>
Date: Sun, 26 Jul 2026 11:57:17 +0530
Subject: [PATCH 19/20] docs(navigation): drop the duplicate GET /api/health
 entry from docs.json

Address CodeRabbit finding on PR #1512: `docs/api-reference/health.mdx`
already documents both `/api/health` (Liveness section) and
`/api/health/ready` (Readiness section), so the mdx page is the
canonical doc for the health endpoints. The standalone `GET /api/health`
entry under the System group was sourced from the OpenAPI document
and duplicated the liveness info as a second nav item.

Remove the `GET /api/health` entry. `docs/api-reference/health`
becomes the single nav entry for both endpoints.
---
 docs/docs.json | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docs/docs.json b/docs/docs.json
index ae26d3c8d..419db0dbb 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -217,7 +217,6 @@
                         "icon": "server",
                         "pages": [
                             "GET /api/version",
-                            "GET /api/health",
                             "docs/api-reference/health"
                         ]
                     }

From 44e43bfe0584416c644d1c5eb1df9a48a70b7ea1 Mon Sep 17 00:00:00 2001
From: Harsh23Kashyap <55448981+Harsh23Kashyap@users.noreply.github.com>
Date: Sun, 26 Jul 2026 11:57:17 +0530
Subject: [PATCH 20/20] chore: link the changelog entry to PR #1512 instead of
 issue #1511

Address CodeRabbit finding on PR #1512: per the project changelog
format guideline, entries should link to the PR, not the issue.
---
 CHANGELOG.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8b8a3a7a2..68ec74841 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 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)
-- Added a `?strict=true` query parameter to `GET /api/health/ready`. When set, the endpoint reports `503 / status: "degraded"` and `zoekt.status: "empty"` if the Zoekt shard set contains no indexed repositories, distinguishing "Zoekt is unreachable" from "Zoekt is up but the instance is not yet useful" for orchestrators. Default behavior is unchanged. [#1511](https://github.com/sourcebot-dev/sourcebot/issues/1511)
+- Added a `?strict=true` query parameter to `GET /api/health/ready`. When set, the endpoint reports `503 / status: "degraded"` and `zoekt.status: "empty"` if the Zoekt shard set contains no indexed repositories, distinguishing "Zoekt is unreachable" from "Zoekt is up but the instance is not yet useful" for orchestrators. Default behavior is unchanged. [#1512](https://github.com/sourcebot-dev/sourcebot/pull/1512)
 
 ### Changed
 - Vulnerability triage now keeps Linear issues synchronized with current security findings.