Admin API

The admin listener is optional. When configured via admin.bind, it exposes three endpoints.

Path	Purpose
GET /healthz	Liveness check.
GET /readyz	Readiness check for listener lifecycle, discovered broker health, and broker route allocation.
GET /metrics	Prometheus-style runtime, tenant, broker, route, and readiness metrics.

Readiness semantics

/readyz reports three states, each with an HTTP status:

• status=ready (HTTP 200) — the runtime is accepting traffic and every non-retired discovered broker is both probe-ready and mapped to a proxy route for the active listener sets.
• status=degraded (HTTP 503) — at least one broker is usable, but Klamm cannot fully virtualize the discovered cluster. Typical causes: a broker is stale, unready, or outside the configured port range.
• status=not_ready (HTTP 503) — the runtime is not ready, or no upstream broker is currently usable.

Fail-closed rewrites

Broker-address-bearing responses fail closed if a response references a broker ID without a proxy route. Klamm does not partially rewrite such responses: leaking an upstream host or advertising a dead route would break the cluster-virtualization boundary.

The corresponding /metrics output includes:

• Readiness state and reason gauges
• Counts of stale, unmapped, and unready brokers
• Fail-closed rewrite counters

Example

Once Klamm is running with admin.bind: "127.0.0.1:28080":

curl -sS http://127.0.0.1:28080/readyz | jq

{
  "status": "ready",
  "listener_sets": [
    { "name": "plaintext", "state": "serving" }
  ],
  "brokers": {
    "known": 3,
    "ready": 3,
    "mapped": 3,
    "stale": 0
  }
}

The exact response shape is not yet stable. Until the admin surface is versioned, treat /readyz as a boolean signal — HTTP 200 means accept traffic, HTTP 503 means do not.