Implement readiness checks for required API dependencies

[Chigybillionz]

Closes #1515

Summary of the issue

The API exposed a health endpoint, but it only reported that the process could respond. A live process could still be unable to serve traffic if required API dependencies such as storage or Cloudflare bindings were missing or unavailable.

Root cause

GET /api/v1/health returned a static success payload and did not define separate liveness and readiness semantics. It also did not probe required production dependencies, enforce bounded dependency check timeouts, or guarantee sanitized readiness output.

Solution implemented

Separated liveness from readiness within the existing health route:

• GET /api/v1/health remains a liveness check and does not depend on external systems.
• GET /api/v1/health?check=readiness performs required dependency readiness checks.
• Readiness checks are bounded by timeouts.
• Readiness responses expose only safe dependency statuses and do not leak binding names, connection details, secrets, or internal error messages.

---

Key changes made

• Added checkApiReadiness helper for testable readiness checks.
• Added checks for required API bindings/context, storage access, and coordinator access.
• Updated the health route to return 503 when readiness fails.
• Added unit coverage for successful readiness, missing bindings, unavailable storage, timeout behavior, and sanitized output.
• Documented the liveness/readiness contract in API docs and OpenAPI metadata.

---

Trade-offs or considerations

The readiness check uses lightweight read-only probes so it can verify dependency availability without mutating production data. Dependency failures are intentionally sanitized, so operators get a clear component-level status without exposing internal configuration or connection details.

Testing steps

1. Run unit tests:

   npm test -- tests/unit/api/health.test.ts

---

2. Verify liveness returns 200 without dependency probing:
   curl -i http://localhost:8080/api/v1/health
3. Verify readiness returns 200 when required dependencies are available:
   curl -i "http://localhost:8080/api/v1/health?check=readiness"
4. Verify readiness returns 503 with sanitized dependency statuses when required storage or bindings are unavailable.

Please kindly review this task. If there are any corrections, improvements, adjustments, or merge conflicts that you notice regarding my implementation, I'd really appreciate your feedback. I'd also love to hear your overall review of my work on this branch.Thank you!

[kryputh]

@Chigybillionz fix conflict

[Chigybillionz]

Done

…

On Mon, Jul 20, 2026, 6:04 AM Uthaimin ***@***.***> wrote: *kryputh* left a comment (Stellar-Mail/stealth#1581) <#1581 (comment)> @Chigybillionz <https://github.com/Chigybillionz> fix conflict — Reply to this email directly, view it on GitHub <#1581?email_source=notifications&email_token=BMBZJ5CFM72EETJN3J3R3ZL5FWR6JA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMBRHA4TKNBTGAYKM4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#issuecomment-5018954300>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BMBZJ5BVPQY2XHQIXLU4XUL5FWR6JAVCNFSNUABGKJSXA33TNF2G64TZHMYTEMZQGQ3DGOJYGA5US43TOVSTWNBZGIZTMMRSGUZTBILWAI> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/BMBZJ5DNJU7ZPLBIG5WC5XT5FWR6JA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMBRHA4TKNBTGAYKM4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJKTGN5XXIZLSL5UW64Y> and Android <https://github.com/notifications/mobile/android/BMBZJ5FTPWIGRASS647ZKSD5FWR6JA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMBRHA4TKNBTGAYKM4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLTGN5XXIZLSL5QW4ZDSN5UWI>. Download it today! You are receiving this because you were mentioned.Message ID: ***@***.***>