[bpacholek]

Summary

Closes #144.

To learn which nats-server a NUTS instance is connected to, or what its stream's limits and state are, an operator had to query NATS separately. Some behaviour now depends on the server version; for example, a restore keeps or replaces the creation time depending on the server (#137). Seeing it from NUTS helps triage.

Changes

• New directive health_details [bool], off by default. With it, ready_path and health_path add:
  • nats_server: version, name, cluster, domain.
  • stream_info: subjects, storage, replicas, message and byte counts, first and last sequence, consumers, max_msgs, max_bytes, max_age_seconds, max_consumers, creation time.
• No extra request. The stream details come from the stream-info read the probe already makes.
• Degraded probes. nats_server is left out while disconnected, and stream_info when the stream cannot be read. The status fields and codes are unchanged.
• Why off by default. Probe paths are often public, and the details name servers, clusters and limits. The README says so and suggests restricting the paths with Caddy matchers.
• Left out on purpose. A Prometheus nats_server_info metric (mentioned in the issue) would need its own design: several handlers share process-wide metrics, and a server label goes stale after a reconnect.
• Plumbing. Parsed in caddyfile.go (no argument means true). Documented in the README (listing, probes section with an example), CONFIGURATION, the website and the CHANGELOG. A new /details route in Caddyfile.test, and a "the response should not contain" step.

Tests

• TestHandler_HealthDetails, against an embedded server with JetStream domain hub, cluster name east, a stream with limits and one durable consumer:
  • every field of both objects;
  • no details without the directive;
  • a stream that cannot be read gives 503 with the server and no stream;
  • a disconnected handler gives 503 without a server.
• Directive. Caddyfile rows: the full config, an explicit true, and a non-boolean value that is rejected.
• Functional. The scenario "Readiness details are opt-in", comparing /details/readyz with /events/readyz; 34/34. The full suite passes under -race; lint is clean.
• Mutation.
  • gremlins: caddyfile.go 41/0, serve.go 220/0.
  • 22 hand mutants, all killed: each of the 18 fields, both branches, and both Caddyfile assignments.
• Example stack. /details/readyz reports nats-server 2.15.0 and the example's memory stream (max_msgs 10000, max_age_seconds 3600, max_consumers 10000). /events/readyz is unchanged.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!