ring-implementing-readyz

name: ring:implementing-readyz description: "Implementing the canonical /readyz readiness-probe contract across Go, TypeScript, and Next.js via a 12-gate cycle: detects stack, audits compliance, then dispatches agents to build the dependency probe, url.Parse TLS detection, ValidateSaaSTLS enforcement, metrics, startup self-probe, and graceful drain, then runs reviewers. Use when a service lacks or has incomplete /readyz. Skip for libraries, CLI tools, or batch jobs."

Readyz & Self-Probe Development Cycle

When to use

• New service being created
• Service has external dependencies (DB, cache, queue, HTTP upstreams)
• Service lacks /readyz or has incomplete dependency checks
• Service missing startup self-probe, SaaS TLS enforcement, or metrics

Skip when

• Pure library package with no deployable service or HTTP server
• Task is documentation-only, configuration-only, or non-code
• Service has no external dependencies AND no network listeners
• CLI tool or batch job that does not serve HTTP traffic

You orchestrate. Agents implement. NEVER use Edit/Write/Bash on source files. All code changes go through Task(subagent_type="ring:backend-go") or Task(subagent_type="ring:backend-ts") (by language). TDD mandatory for all implementation gates (RED → GREEN → REFACTOR).

Agents:

Readiness Architecture

/readyz — runtime dependency probe for K8s readinessProbe. /health — liveness probe gated by startup self-probe.

Standards references (WebFetch by implementation agents):

Canonical response contract:

{
  "status": "healthy",
  "checks": {
    "postgres": { "status": "up", "latency_ms": 2, "tls": true },
    "redis":    { "status": "skipped", "reason": "REDIS_ENABLED=false" },
    "upstream_fees": { "status": "degraded", "breaker_state": "half-open", "latency_ms": 12 }
  },
  "version": "1.2.3",
  "deployment_mode": "saas"
}

Status vocabulary: up / down / degraded / skipped / n/a — no others.

Aggregation rule: top-level "unhealthy" + HTTP 503 if ANY check is down or degraded.

Probe logging contract (MANDATORY):

Kubernetes hits /readyz every 5s (≈17,280 calls/day per pod). Per-iteration INFO logging drowns log pipelines.

INFO/ERROR are not used by the probe handler. Steady-state observability is the job of readyz_check_status / readyz_check_duration metrics (Gate 5) — logs are diagnostic only. Access-log middleware MUST exclude /readyz, /health, /metrics from request logging — lib-observability applies this by default (defaultLogExcludedRoutes in middleware/logging.go); use middleware.WithExcludedRoutes(...) to append more paths. Services not on lib-observability must keep an explicit skipTelemetryPaths filter.

Endpoint paths:

Forbidden anti-patterns (block progression in Gate 0):

1. Response caching in front of /readyz
2. /ready alias (not /readyz)
3. /health/live + /health/ready split
4. strings.Contains(uri, "tls=true") — use url.Parse
5. Reflection on *amqp.Connection for TLS state
6. Inline TLS checks at each connection site — use ValidateSaaSTLS()
7. process.exit() in Next.js instrumentation.ts on probe failure
8. INFO log on probe success — see Probe logging contract; success is DEBUG, failure is WARN

Mandatory agent instruction (include in EVERY dispatch):

WebFetch https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/skills/implementing-readyz/SKILL.md and sre.md. Follow the canonical response contract exactly. Five-value status vocabulary. Aggregation: 503 iff any check is down or degraded. Probe logging: success at DEBUG, failure at WARN. No INFO from the probe handler. Forbidden anti-patterns 1-8: MUST NOT introduce any. TDD: RED → GREEN → REFACTOR.

Gate Overview

Gates execute sequentially. Existing /readyz code ≠ compliance. Gate 0 Phase 2 audit is mandatory.

Gate 0: Stack Detection + Audit

Orchestrator executes directly. Three phases:

Phase 1: Stack Detection

grep -rn "postgresql\|pgx" internal/ go.mod
grep -rn "mongodb\|mongo" internal/ go.mod
grep -rn "redis\|valkey" internal/ go.mod
grep -rn "rabbitmq\|amqp" internal/ go.mod
grep -rn "http.Client\|upstream" internal/
grep -rn "circuitbreaker\|gobreaker" internal/
grep "DEPLOYMENT_MODE\|saas" .env* internal/

Phase 2: Compliance Audit (S1-S10) (if /readyz code detected)

• S1: Response contract shape (all required fields present)
• S2: Status vocabulary (only 5 valid values)
• S3: Aggregation rule (503 on down/degraded)
• S4: Endpoint path (exact /readyz, not /ready)
• S5: No response caching
• S6: TLS detection uses url.Parse, not strings.Contains
• S7: ValidateSaaSTLS() called at bootstrap for SaaS mode
• S8: Three readyz metrics emitted
• S9: Startup self-probe gates /health
• S10: Probe logging follows the contract (success = DEBUG, failure = WARN; no INFO from probe handler; /readyz, /health, /metrics excluded from access log — automatic on lib-observability, manual skipTelemetryPaths otherwise)

Phase 3: Anti-Pattern Detection Check for each of the 8 forbidden anti-patterns. Any match = COMPLIANT: false.

Severity Reference