feat(api): add queue_health monitoring endpoint

Merged
RI
3mo ago
+792-50

Summary (AI generated)

  • Added GET /queue_health to audit every pgmq queue and return 200/ok or 503/ko, matching the /replication monitoring pattern.
  • Health criteria cover unread stale messages (read_ct=0 past cron-derived threshold), stuck retries (read_ct > 5), queue depth, stale archives (>2 days), recent archive ramp-up, and missing queue/archive tables.
  • Response includes thresholds, human-readable healthy/unhealthy criteria, per-queue metrics, reasons, and reason details for each failure.
  • Wired through Supabase function queue_health, Cloudflare API route, and unit tests for evaluation helpers.

Motivation (AI generated)

Operators need a single monitorable endpoint that proves queues are being consumed and archives are not silently growing. Without this, stuck unread work and archive ramp-up are hard to catch before they impact processing latency or database size.

Business Impact (AI generated)

Faster detection of queue consumer failures reduces update/webhook/cron processing delays and avoids archive/storage growth incidents that can pressure production Postgres.

Test Plan (AI generated)

  • Unit tests for queue health criteria and cron interval derivation (tests/queue-health.unit.test.ts)
  • Call GET /queue_health with apisecret against a healthy environment and expect HTTP 200 + status: "ok"
  • Seed a stale unread message / stuck read_ct / old archive row and expect HTTP 503 with matching reasons and reason_details
  • Confirm non-admin JWT gets 403 and missing auth gets 401

Generated with AI

Open in Web Open in Cursor 

Summary by CodeRabbit

  • New Features

    • Added a new GET /queue_health endpoint for authorized administrators to check the health of message queues.
    • Returns an overall status summary (healthy vs. unhealthy) with per-queue findings across backlog, unread staleness, stuck reads, and archive delays.
    • Includes configurable access behavior to reach the endpoint without JWT verification.

  • Tests

    • Added unit tests covering queue name validation, schedule/interval parsing, threshold handling, and health evaluation scenarios.