Skip to content

Add a /v1/health endpoint reporting indexer freshness per protocol #17

Description

@dubemoyibe-star

Context

There's currently no way to tell whether the indexer is actually running short of querying the database or eyeballing timestamps in the UI. Since scoring silently stopping is one of the worse failure modes for this project — the site keeps serving last-known scores while the data quietly goes stale — a machine-readable freshness signal is worth having before contributors start relying on the data.

Scope

In scope: a GET /v1/health endpoint reporting, per protocol, the last successful run timestamp, the last run status, and how long ago that was; plus an overall status derived from whether any protocol has gone longer than a configurable threshold without a successful run.
Out of scope: alerting or notification (that's covered by the indexer resilience issue), and any auth on the endpoint — this is public, non-sensitive data.

Acceptance criteria

  • GET /v1/health returns per-protocol last-successful-run time, last run status, and staleness in a machine-readable form
  • Overall status field derived from a configurable staleness threshold, not a hardcoded number
  • Returns a non-200 status when the overall state is unhealthy, so an external uptime monitor can consume it without parsing the body
  • Documented in README.md and ARCHITECTURE.md alongside the other endpoints
  • Cheap to serve — a single query, not a per-protocol fan-out

Difficulty

Intermediate — needs familiarity with the codebase or methodology

Notes / open questions

Worth thinking about whether "unhealthy" should distinguish between the indexer being down entirely versus one protocol's adapter failing while others succeed. Those are different problems and probably warrant different signals.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions