Skip to content

Horizon Endpoint Availability Prober #546

Description

@Kingsman-99

Description

Before the SDK makes any Horizon API call, it should proactively verify that the configured Horizon endpoint is reachable and returning a healthy response. This is especially important at startup and after network configuration changes. A lightweight availability prober should periodically hit the Horizon root endpoint (/), parse the history_latest_ledger field, and mark the endpoint as degraded or unavailable when the response is stale or the call fails.

Technical Context

Add src/horizonProber.ts. Calls @stellar/stellar-sdk Server.fetchRoot() to obtain HorizonApi.RootResponse. Tracks history_latest_ledger and compares it against the expected cadence (new ledger every ~5 s). Integrates with src/health.ts and src/healthDashboard.ts. Emits horizonEndpointDegraded and horizonEndpointRecovered via src/events.ts. Configured as a step in src/loadBalancer.ts health checks.

Acceptance Criteria

  • HorizonProber.probe(endpointUrl): Promise<ProbeResult> returns { reachable, latencyMs, latestLedger, isStale } within timeoutMs
  • isStale is true when history_latest_ledger has not advanced in stalenessThresholdMs (configurable, default 30 000 ms)
  • Emits horizonEndpointDegraded when two consecutive probes fail or return stale results
  • Emits horizonEndpointRecovered on the first successful non-stale probe after a degraded period
  • src/healthDashboard.ts includes the prober's last result in the dashboard snapshot
  • All CI checks (npm test, npm run build, ESLint/TypeScript) pass and the branch has no merge conflicts

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions