Improve /health endpoint to report dependency status

[prodbycorne]

Overview

The current /health endpoint returns a static { status: 'ok' }. It gives no insight into whether Redis is reachable, Horizon RPC is responsive, or price sources are functional — making it useless as a readiness probe or for on-call triage.

New Response Format

{
  "status": "degraded",
  "uptime_seconds": 3847,
  "checks": {
    "redis": { "status": "ok", "latency_ms": 2 },
    "horizon": { "status": "ok", "latency_ms": 89, "ledger": 52341200 },
    "coingecko": { "status": "ok", "circuit": "closed" },
    "coinmarketcap": { "status": "degraded", "circuit": "open", "reason": "rate_limited" },
    "stellar_dex": { "status": "ok", "circuit": "closed" }
  }
}

Status rules:

• ok: all checks pass
• degraded: at least one non-critical check failing (price source)
• error: critical dependency (Redis) is unreachable

HTTP status codes:

• ok → 200
• degraded → 200 (load balancer keeps it in rotation)
• error → 503

Implementation

• Run all dependency checks in parallel with Promise.allSettled
• Redis check: redis.ping() with 2s timeout
• Horizon check: fetch / endpoint (returns ledger info) with 5s timeout
• Price source check: report circuit breaker state (no live HTTP call)

Acceptance Criteria

• /health returns dependency check map
• All checks run in parallel (< 5s total)
• Redis unreachable → 503 status
• Price source circuit state included
• Response includes uptime_seconds
• Tests for ok, degraded, and error scenarios
• Kubernetes readiness probe compatible

[midenotch]

Hello,

I would like to express my interest in implementing the enhanced health and readiness monitoring endpoint.

As a Fullstack Engineer with extensive experience building production APIs, distributed systems, monitoring infrastructure, and cloud-native applications, I understand that a health endpoint should provide actionable operational insight rather than simply indicating whether the application process is running.

The current implementation returns a static response, which makes it difficult to diagnose dependency failures, perform effective on-call triage, or integrate with Kubernetes readiness and monitoring systems. I would be excited to implement a comprehensive health-check solution that provides meaningful visibility into the platform's operational state.

For this task, I would:

• Design a structured health response that reports application status, uptime, and dependency-specific diagnostics.

• Implement parallel dependency checks using Promise.allSettled() to ensure the endpoint remains fast and resilient even when individual services are degraded.

• Add Redis health verification using redis.ping() with configurable timeout handling and latency measurement.

• Add Horizon connectivity checks with ledger reporting and response-time tracking.

• Integrate circuit breaker state reporting for CoinGecko, CoinMarketCap, and Stellar DEX providers without introducing additional external API calls.

• Implement health aggregation logic that correctly categorizes system state as:

  • ok when all dependencies are healthy
  • degraded when non-critical services are unavailable
  • error when critical infrastructure such as Redis is unreachable

• Return appropriate HTTP status codes to support load balancers, orchestrators, and Kubernetes readiness probes.

• Include application uptime metrics to improve observability and troubleshooting.

• Create comprehensive test coverage for healthy, degraded, and failure scenarios, including timeout and dependency outage conditions.

• Document the health contract so future integrations, dashboards, and monitoring systems can reliably consume the endpoint.

Beyond the acceptance criteria, I would focus on maintainability and operational visibility by ensuring the implementation is extensible, making it straightforward to add future dependency checks without modifying the overall health aggregation architecture.

My experience building backend systems with Node.js, TypeScript, Redis, monitoring integrations, and fault-tolerant service architectures positions me well to deliver a reliable, production-ready solution that improves both system observability and operational confidence.

Thank you for your consideration. I would be excited to contribute this enhancement and help strengthen the platform's monitoring and reliability capabilities.

[grantfox-oss]

🦊 GrantFox — @midenotch has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #24)
2. Your PR will be reviewed by the SmartDropLabs maintainers

Good luck! Track your progress on GrantFox.