fix: report provider dependency health in /status

openapi.json

@@ -545,12 +545,10 @@
                       "nullable": true
                     },
                     "latestLedger": {
-                      "type": "integer",
-                      "nullable": true
+                      "type": "integer"
                     },
                     "lagLedgers": {
-                      "type": "integer",
-                      "nullable": true
+                      "type": "integer"
                     },
                     "startedAt": {
                       "type": "string",
@@ -562,51 +560,71 @@
                     "totalIndexed": {
                       "type": "integer"
                     },
-                    "networks": {
-                      "type": "object",
-                      "additionalProperties": {
+                    "status": {
+                      "type": "string",
+                      "enum": [
+                        "healthy",
+                        "degraded"
+                      ]
+                    },
+                    "dependencies": {
+                      "type": "array",
+                      "items": {
                         "type": "object",
                         "properties": {
-                          "lastIndexedLedger": {
-                            "type": "integer",
-                            "nullable": true
+                          "name": {
+                            "type": "string"
                           },
-                          "latestLedger": {
-                            "type": "integer",
-                            "nullable": true
+                          "status": {
+                            "type": "string",
+                            "enum": [
+                              "ok",
+                              "degraded",
+                              "down",
+                              "unknown"
+                            ]
                           },
-                          "lagLedgers": {
+                          "lastCheckedAt": {
+                            "type": "string",
+                            "nullable": true,
+                            "format": "date-time"
+                          },
+                          "lastOkAt": {
+                            "type": "string",
+                            "nullable": true,
+                            "format": "date-time"
+                          },
+                          "latencyMs": {
                             "type": "integer",
                             "nullable": true
                           },
-                          "running": {
-                            "type": "boolean"
-                          },
-                          "reason": {
-                            "type": "string"
+                          "detail": {
+                            "type": "string",
+                            "nullable": true
                           }
                         },
                         "required": [
-                          "lastIndexedLedger",
-                          "latestLedger",
-                          "lagLedgers",
-                          "running"
-                        ],
-                        "additionalProperties": {
-                          "nullable": true
-                        }
+                          "name",
+                          "status",
+                          "lastCheckedAt",
+                          "lastOkAt",
+                          "latencyMs",
+                          "detail"
+                        ]
                       }
                     }
                   },
                   "required": [
                     "ok",
                     "lastIndexedLedger",
                     "latestLedger",
-                    "lagLedgers"
-                  ],
-                  "additionalProperties": {
-                    "nullable": true
-                  }
+                    "lagLedgers",
+                    "startedAt",
+                    "uptimeSeconds",
+                    "totalIndexed",
+                    "status",
+                    "dependencies"
+                  ]
                 }
               }
             }
@@ -4722,11 +4740,11 @@
             "schema": {
               "type": "string",
               "nullable": true,
-              "description": "The amount being sent, in whole units of the asset. When given and a percentage fee is configured, each fee is computed for it; without it each fee is the floor. Optional because shipped clients predate it.",
+              "description": "The amount being sent, in whole units of the asset. When given and a percentage fee is computed for it; without it each fee is the floor. Optional because shipped clients predate it.",
               "example": "25"
             },
             "required": false,
-            "description": "The amount being sent, in whole units of the asset. When given and a percentage fee is configured, each fee is computed for it; without it each fee is the floor. Optional because shipped clients predate it.",
+            "description": "The amount being sent, in whole units of the asset. When given and a percentage fee is computed for it; without it each fee is the floor. Optional because shipped clients predate it.",
             "name": "amount",
             "in": "query"
           }

src/api.ts

@@ -32,6 +32,7 @@ import { networkMiddleware, requestNetwork } from "./middleware/network";
 import { renderMetrics, metricsContentType, httpRequestsTotal, httpRequestDurationSeconds } from "./metrics";
 import { getAllCachedTokens, getCachedTokenDecimals } from "./tokenCache";
 import { toDisplayAmount } from "./amount";
+import { getDependencyStatus, dependencyStatusBoundMs } from "./dependencies";
 
 // ─── RPC Health Check Cache ───────────────────────────────────────────────
 // Keyed by network (#163): one cache entry would let a healthy testnet RPC
@@ -464,6 +465,7 @@ export function createApp(): express.Application {
       const rpcSuccess = latestLedgerResult.status === "fulfilled" && typeof latestLedgerResult.value === "number";
       const latestLedger = rpcSuccess ? latestLedgerResult.value : null;
       const stats = getIndexerStats(selected);
+      const dependencies = getDependencyStatus();
 
       // Per-network progress (#161). The top-level fields above stay as they
       // were so existing consumers are unaffected; this reports each loop
@@ -504,7 +506,7 @@ export function createApp(): express.Application {
       );
       const byNetwork = Object.fromEntries(perNetwork);
 
-      if (rpcSuccess && latestLedger !== null) {
+      if (rpcSuccess && latestLedger !== null && dependencies.railsUsable) {
         res.json({
           ok: true,
           status: "healthy",
@@ -519,6 +521,8 @@ export function createApp(): express.Application {
           lagLedgers: latestLedger - (lastIndexedLedger ?? latestLedger),
           ...stats,
           networks: byNetwork,
+          dependencies,
+          dependency_status_bound_ms: dependencyStatusBoundMs,
         });
       } else {
         res.setHeader("X-Data-Stale", "true");
@@ -533,13 +537,15 @@ export function createApp(): express.Application {
           as_of_ledger: lastIndexedLedger ?? undefined,
           lastIndexedLedger,
           last_indexed_ledger: lastIndexedLedger,
-          latestLedger: null,
-          lagLedgers: null,
+          latestLedger: rpcSuccess ? latestLedger : null,
+          lagLedgers: rpcSuccess && latestLedger !== null ? latestLedger - (lastIndexedLedger ?? latestLedger) : null,
           ...stats,
           // Also reported when degraded — with two loops, "RPC is down" is
           // usually true of one chain only, and the top-level nulls above
           // cannot say which.
           networks: byNetwork,
+          dependencies,
+          dependency_status_bound_ms: dependencyStatusBoundMs,
         });
       }
     } catch (err) {

src/dependencies.ts

@@ -0,0 +1,45 @@
+export const dependencyStatusBoundMs: number = 15 * 60 * 1000;
+
+const dependencyOutcomes = new Map<string, { status: string; lastChecked: string | null; latencyMs?: number; error?: string }>();
+
+export function recordDependencyOutcome(
+  name: string,
+  success: boolean,
+  latencyMs?: number,
+  error?: string,
+): void {
+  const now = new Date().toISOString();
+  const status = success ? "healthy" : "unavailable";
+  dependencyOutcomes.set(name, { status, lastChecked: now, latencyMs, error });
+}
+
+export function getDependencyStatus(): {
+  railsUsable: boolean;
+  dependencies: Record<string, { status: string; lastChecked: string | null; latencyMs?: number; error?: string }>;
+  boundMs: number;
+} {
+  const allHealthy = Array.from(dependencyOutcomes.values()).every(
+    (dep) => dep.status === "healthy",
+  );
+  // With no recorded outcomes, rails are assumed usable; an observed failure
+  // flips this to degraded.
+  const railsUsable = dependencyOutcomes.size === 0 || allHealthy;
+
+  const dependencies: Record<string, {
+    status: string;
+    lastChecked: string | null;
+    latencyMs?: number;
+    error?: string;
+  }> = {};
+
+  for (const [name, dep] of dependencyOutcomes) {
+    dependencies[name] = {
+      status: dep.status,
+      lastChecked: dep.lastChecked ?? null,
+      latencyMs: dep.latencyMs,
+      error: dep.error,
+    };
+  }
+
+  return { railsUsable, dependencies, boundMs: dependencyStatusBoundMs };
+}

src/dependencyHealth.ts

@@ -0,0 +1,3 @@
+import { recordDependencyOutcome } from "./dependencies";
+
+export { recordDependencyOutcome };