feat(web): add ?strict=true mode to /api/health/ready for empty-shard detection

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Added a `GET /api/health/ready` endpoint that returns per-dependency health (Postgres, Redis, Zoekt) for use as a Kubernetes `readinessProbe` or load-balancer health check. The existing `GET /api/health` endpoint is unchanged and remains the liveness probe. [#1507](https://github.com/sourcebot-dev/sourcebot/pull/1507)
+- 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.
 

docs/docs.json

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

docs/docs/api-reference/health.mdx

@@ -0,0 +1,130 @@
+---
+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.
+
+### 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 },
+    "zoekt":    { "status": "ok", "latencyMs": 12 }
+  }
+}
+```
+
+When degraded, each failed check carries an `error` field with the underlying message:
+
+```json
+{
+  "status": "degraded",
+  "strict": false,
+  "checks": {
+    "postgres": { "status": "ok",    "latencyMs": 4 },
+    "redis":    { "status": "ok",    "latencyMs": 1 },
+    "zoekt":    { "status": "error", "latencyMs": 2003, "error": "zoekt check timed out after 2000ms" }
+  }
+}
+```
+
+| Check | What it probes |
+|-------|---------------|
+| `postgres` | `SELECT 1` via Prisma |
+| `redis`    | `PING` (rejects non-`PONG` responses) |
+| `zoekt`    | Empty `List` RPC (proves the gRPC channel is alive; bounded by the 2s per-check timeout) |
+
+### Example probes
+
+<Tabs>
+  <Tab title="Docker Compose">
+    ```yaml
+    services:
+      sourcebot:
+        image: sourcebot/sourcebot:latest
+        healthcheck:
+          test: ["CMD", "wget", "-qO-", "http://localhost:3000/api/health"]
+          interval: 30s
+          timeout: 5s
+          retries: 3
+        # For dependency-aware probes, point the orchestrator at /api/health/ready
+        # instead. Sourcebot's example compose file does this via a sidecar.
+    ```
+  </Tab>
+  <Tab title="Kubernetes">
+    ```yaml
+    livenessProbe:
+      httpGet:
+        path: /api/health
+        port: 3000
+      initialDelaySeconds: 30
+      periodSeconds: 30
+      timeoutSeconds: 5
+      failureThreshold: 3
+    readinessProbe:
+      httpGet:
+        path: /api/health/ready
+        port: 3000
+      initialDelaySeconds: 10
+      periodSeconds: 10
+      timeoutSeconds: 5
+      successThreshold: 1
+      failureThreshold: 3
+    # 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>
+
+<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>