feat(api): add /healthz + /readyz probes, deprecate /health + /ready

[taitelee]

Summary

Adopts the Kubernetes-convention health-probe names from #144: GET /healthz (liveness) and GET /readyz (readiness) are now the canonical paths. The existing /health and /ready are kept as deprecated aliases of the same handlers for the v0.1.x line and are slated for removal in v0.2.0 — so nothing breaks for anyone already probing the old paths. Response bodies are unchanged (/healthz → {"status":"ok"}, /readyz → {"status":"ready"}, same boot-gated 503s as before).

WaveHouse's own tooling is repointed at the canonical names so it doesn't ride an alias we've announced for removal: the distroless health subcommand, the e2e orchestrator's readiness wait, the SDK e2e setup probe, and both Dockerfile HEALTHCHECKs. The prometheus.path reserved-collision check now also covers /healthz + /readyz, and the tracing span-skip middleware excl probe paths. Docs, AGENTS.md, and CHANGELOG.md updated to match.

Part 2 of #144 is deferred: the per-dependency drill-down probes under /healthz/{clickhouse,nats,schema,dlq} and the richer aggregate {"ready", "checks"} readiness body are left for a follow-up. This PR is a pure rename + alias.

Related Issues

Part of #144 (part 1: /healthz + /readyz rename + aliases). Intentionally not Closes — part 2 (per-dependency probes, aggregate readiness body) is deferred.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This PR migrates health probe endpoints from legacy naming (/health, /ready) to Kubernetes-canonical naming (/livez, /readyz), introduces a new public SDK liveness endpoint (/v1/health), and updates routing, validation, clients, and documentation throughout the codebase.

Changes

Kubernetes Health Probe Endpoints

Layer / File(s)	Summary
New SDK /v1/health endpoint internal/api/health.go, internal/api/health_test.go, internal/api/router.go, internal/api/router_test.go, clients/ts/src/sys.ts, clients/ts/src/namespaces.test.ts, clients/ts/src/types.ts, clients/ts/src/index.ts	A new public /v1/health endpoint returning content-free 200/503 status is registered for SDK reachability checks. TypeScript SDK health() method now targets /v1/health with return type Result<void> instead of Result<Health>. The legacy Health response type is removed from client exports.
Canonical probe routing internal/api/health.go, internal/api/router.go, internal/api/router_test.go, clients/ts/src/sys.ts	Router registers /livez and /readyz as canonical Kubernetes liveness/readiness endpoints, with /healthz as a permanent alias and /health//ready as deprecated aliases. Tracing span creation skips probe paths to reduce observability noise. TypeScript ready() method targets /readyz instead of /ready.
Boot-time degraded and recovery semantics internal/api/health.go, internal/api/health_test.go, internal/api/boot_chain_test.go, tests/integration/boot_resilience_test.go	BootState documentation describes /livez returning 503 during schema-discovery retry and 200 after recovery. Health handler tests assert /livez and /readyz behavior across boot phases. Integration tests validate sticky /livez (remains 200 post-boot) vs conditional /readyz (503 on post-boot ClickHouse outage).
CLI and orchestration probe updates cmd/wavehouse/health.go, cmd/wavehouse/health_test.go, cmd/wavehouse/main.go, scripts/orchestrator/main.go, tests/e2e/sdk/setup.ts, deployments/Dockerfile, deployments/Dockerfile.goreleaser	The wavehouse health CLI command and all probe callers (orchestrator startup wait, E2E setup, Docker HEALTHCHECK) are updated to check /livez instead of /health. Boot-time operator guidance logs and comments reference /livez degraded behavior.
Prometheus reserved path validation internal/config/config.go, internal/config/config_test.go	Prometheus path validation expands reserved endpoints from {/health, /ready} to {/livez, /readyz, /healthz, /health, /ready} to prevent shadowing of canonical and alias probe routes.
Schema discovery diagnostic references internal/discovery/discovery.go, internal/discovery/discovery_test.go	Schema retry diagnostic comments updated to reference /livez for showing boot-degraded state. Test comment reflowed without logic changes.
Documentation and changelog AGENTS.md, CHANGELOG.md, docs/src/content/docs/{api,architecture,deployment,development,sdk}.md	Agent guidance, changelog, and all documentation define /livez and /readyz as Kubernetes canonical endpoints, /healthz as permanent alias, /health and /ready as deprecated v0.1.x aliases slated for v0.2.0 removal. API docs include a liveness-vs-readiness behavior matrix and clarify /v1/health as a public SDK liveness ping.
Go toolchain version go.mod	Go version requirement updated from 1.26.3 to 1.26.4.

🎯 3 (Moderate) | ⏱️ ~25 minutes

---

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Pro by visiting https://app.coderabbit.ai/login.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[taitelee]

/gemini review

[EricAndrechek]

A quick google make it appear as though k8s has deprecated or started phasing out /healthz and recommending /readyz and /livez instead – considering we are starting from scratch here we should probably conform with the current recommendations. I also don't know what the norms are for what each endpoint must return, or what cases they return success/failures in, so additional implementation work may be needed to get it all conforming properly.

Then we also need to work out whether we need /healthz for backwards compatability with older k8s versions or not, and how (if at all) it will differ.

We also need to think about which if any of these endpoints is what we'd want to use for the docker compose health checks, and which our own e2e orchestrator uses, and what if anything should be returned along with those routes.

I also am thinking/wondering, but am unsure on the hosting and deployment conventions, if /readyz, /livez, /healthz etc. are usually on the same port/exposed to traffic like this or not. As we have it now as I understand it, if WaveHouse's port is forwarded to the internet, these k8s endpoints become public for anyone to query, whereas (I think I can't remember for sure) we had it setup so that the prometheus metrics, for instance, could optionally be hosted on a different port. Ideally it'd be the same port, or a competent devops person deploying this would filter those paths out at the reverse proxy layer so they were only addressable internally, but unsure if we should build that in as a feature too or not, worth looking into what the k8s norm is.

I DO think, however, we should have a public facing /health and/or /live or /ready or similar, that simply returns 200 OK or an error and likely no content (so we don't need to do JSON encoding on each request and don't need to cache anything), specifically for use in the SDK to check if a server is online before sending data, or to check if a particular server is healthy and accepting data when choosing between multiple in a distributed setup.

Happy to talk about this all more in person if needed today.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
🚫 Deployment cancelled View logs	wavehouse-docs	fe26e9f	Jun 03 2026, 03:20 PM

[EricAndrechek]

Only want /v1/health accessible and used by API, not readiness.