Ring:implementing Readyz

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:

| Who | Responsibility | |-----|----------------| | ring:backend-go | Go services | | ring:backend-ts | TypeScript backend/BFF | | ring:bff-ts | Next.js BFF | | ring:codebase-explorer | Gate 1 analysis | | ring:visualizing | Gate 1.5 HTML preview | | 9 defaults + triggered specialists | Gate 9 |

Readiness Architecture

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

Standards references (WebFetch by implementation agents):

| Resource | URL | |----------|-----| | Ring SRE standards | https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/sre.md | | Go bootstrap standards | https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/golang/bootstrap.md | | This skill (authoritative) | https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/skills/implementing-readyz/SKILL.md |

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.

| Outcome | Log level | |---------|-----------| | Success (all checks up) | DEBUG | | Failure (any check down/degraded) | WARN |

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:

| Stack | Readiness | Liveness | |-------|-----------|----------| | Go API | /readyz | /health | | TypeScript API | /readyz | /health | | Next.js | /api/admin/health/readyz | same |

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

| Gate | Name | Condition | Agent | |------|------|-----------|-------| | 0 | Stack Detection + /readyz Compliance Audit | Always | Orchestrator | | 1 | Codebase Analysis | Always | ring:codebase-explorer | | 1.5 | Implementation Preview (HTML report) | Always | ring:visualizing | | 2 | /readyz Endpoint Implementation | Always | ring:backend-go / ring:backend-ts (by language) | | 3 | TLS Detection (url.Parse) | Always | ring:backend-go / ring:backend-ts (by language) | | 4 | SaaS TLS Enforcement (ValidateSaaSTLS) | Always | ring:backend-go / ring:backend-ts (by language) | | 5 | Metrics Emission | Always | ring:backend-go / ring:backend-ts (by language) | | 6 | Circuit Breaker + Multi-Tenant Carve-Out | Skip only if no breakers AND single-tenant | ring:backend-go / ring:backend-ts (by language) | | 7 | Startup Self-Probe + /health + Graceful Drain | Always — NEVER skippable | ring:backend-go / ring:backend-ts (by language) | | 8 | Tests | Always | ring:backend-go / ring:backend-ts (by language) | | 9 | Code Review | Always | 9 defaults + triggered specialists in parallel | | 10 | User Validation | Always | User | | 11 | Activation Guide | Always | Orchestrator |

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

| Severity | Criteria | |----------|----------| | CRITICAL | DEPLOYMENT_MODE=saas without ValidateSaaSTLS; TLS reflection; response caching | | HIGH | Wrong status vocabulary; aggregation rule wrong; metrics not emitted; self-probe missing; INFO logging on probe success | | MEDIUM | Missing reason on skipped/n/a; drain grace too short | | LOW | Missing per-dep description; inconsistent version string |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: LerianStudio
• Source: LerianStudio/ring
• License: Apache-2.0
• Homepage: https://lerian.studio

Install and usage instructions live in the source repository linked above.