09 - User Behaviour (Health Module)
- 1. Poll, don't push
- 2. Probe → act on status code, not body
- 3. One culprit at a time
- 4. Detail is payload-conditional
- 5. Retry discipline
- 6. Trust gradient (human screen
(proposed)) - 7. Non-behaviour (explicitly out)
Observed and expected behaviours around the health surface. Machine behaviours are the implemented contract; human behaviours are
(proposed)/(forward-looking). Sources:health.controller.ts:14-37,redis-health.indicator.ts:12-23,bullmq-health.indicator.ts:19-37,rate-limit.constants.ts:4.
1. Poll, don't push
- Behaviour: consumers ask on an interval; the server never pushes health
(no WS/SSE in
health.module.ts; theWsModuleis a separate surface). - Consequence: screen polls every 30 s (13 §2); load balancers choose their own cadence ≥ 10 s (03 §5 - the 30/min cap is a hard shared budget).
2. Probe → act on status code, not body
- 200 → healthy; 503 → unhealthy. The body (
data.status,data.info/data.error) explains which dependency (health.controller.spec.ts:21-36). - Trap: the 503 error body arrives through the error envelope
(
http-exception.filter.ts:73-81) -data.error.<key>carries the down details; do not discard the body on non-2xx (14 QA-1).
3. One culprit at a time
- Partial failure keeps healthy deps
upininfo(health.controller.spec.ts:29-35). Humans read the first red card, fix that dependency, then re-check - the combined check makes cascading diagnosis quick because it always runs all four indicators (health.controller.ts:31-36), even when one fails.
4. Detail is payload-conditional
| Indicator | Detail when up | Detail when down |
|---|---|---|
| mongodb | none (pingCheck, health.controller.ts:32) | none |
| redis | ping: 'PONG' (redis-health.indicator.ts:16) | none - bare getStatus('redis', false) (:17-22) |
| storage | none (storage-health.indicator.ts:19) | none - bare (:20-24) |
| bullmq | pendingJobs array (:30) | none - bare (:31-36) |
- Behaviour: never render a "detail" section from an up-only contract; show "no additional detail reported" (06 S2).
- Ops habit: use
pendingJobswhile up as a leading indicator - growing backlog precedes hard down (03 §2).
5. Retry discipline
- Manual retry is the human's tool; auto-retry loops on 503 are the classic abuse (and hit the 30/min shared cap).
- 429 → back off 60 s, surface countdown (06 S1 row 6).
6. Trust gradient (human screen (proposed))
- Fresh + green = high trust.
- Stale + green = low trust - "stale" badge forces attention (07 §4).
- Red = the truth the screen exists to surface; no smoothing, no
"degraded but fine" copy - the endpoint says
down, the UI saysdown(health.controller.spec.ts:29-35).