milestone 26: upstream health answers for the selected period

src/web/openapi.yaml

@@ -342,7 +342,15 @@ paths:
 
   /api/upstream/health:
     get:
-      summary: Upstream pool health
+      summary: Upstream pool health for a period
+      description: |
+        Each upstream's live routing state beside its recorded outcomes over
+        the period's window, which is the same UTC-aligned window `/api/stats`
+        reports for that period. The outcome counts come from per-minute
+        history in the query log, not from process-lifetime counters, so they
+        scope to the period and survive a restart.
+      parameters:
+        - $ref: "#/components/parameters/Period"
       responses:
         "200":
           description: Per-upstream state and the availability rollup.
@@ -350,10 +358,14 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/UpstreamHealth"
+        "400":
+          $ref: "#/components/responses/BadRequest"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "429":
           $ref: "#/components/responses/RateLimited"
+        "500":
+          $ref: "#/components/responses/Internal"
         "503":
           $ref: "#/components/responses/Unavailable"
 
@@ -1826,28 +1838,71 @@ components:
           type: string
           nullable: true
 
+    UpstreamPeriodStats:
+      type: object
+      required: [attempts, successes, failures, success_rate, last_failure_at, last_failure_error]
+      properties:
+        attempts:
+          type: integer
+          description: Exchanges recorded against this upstream inside the window.
+        successes: { type: integer }
+        failures: { type: integer }
+        success_rate:
+          type: number
+          nullable: true
+          description: >
+            `successes / attempts`, from 0 to 1. Null when `attempts` is 0: no
+            observations is not perfect reliability.
+        last_failure_at:
+          type: integer
+          nullable: true
+          description: >
+            The newest failure inside the window, unix seconds. Null when the
+            window holds no failure, even if the upstream failed before it.
+        last_failure_error:
+          type: string
+          nullable: true
+          description: The error name belonging to `last_failure_at`; null exactly when it is.
+
     UpstreamHealth:
       type: object
-      required: [upstreams, available, total]
+      required: [period, since, until, available, total, complete, upstreams]
       properties:
+        period:
+          type: string
+          enum: [1h, 24h, 7d, 30d]
+        since:
+          type: integer
+          description: Window start, unix seconds, inclusive.
+        until:
+          type: integer
+          description: Window end, unix seconds, exclusive.
+        available:
+          type: integer
+          description: How many upstreams the pool would route to right now.
+        total: { type: integer }
+        complete:
+          type: boolean
+          description: >
+            No capacity drops known in this process within the selected window;
+            up to about a minute of the newest outcomes may not have flushed
+            yet, and outcomes lost in an unclean shutdown are not detectable.
         upstreams:
           type: array
+          description: The upstreams configured now; a deleted upstream's history is not returned.
           items:
             type: object
-            required: [url, enabled, available, consecutive_failures, total_successes, total_failures, success_rate, last_error]
+            required: [url, enabled, available, period]
             properties:
               url: { type: string }
-              enabled: { type: boolean }
-              available: { type: boolean }
-              consecutive_failures: { type: integer }
-              total_successes: { type: integer }
-              total_failures: { type: integer }
-              success_rate: { type: number }
-              last_error:
-                type: string
-                description: Empty when the upstream never failed.
-        available: { type: integer }
-        total: { type: integer }
+              enabled:
+                type: boolean
+                description: Live configuration, not history.
+              available:
+                type: boolean
+                description: Live state, not history; false while the upstream is backing off.
+              period:
+                $ref: "#/components/schemas/UpstreamPeriodStats"
 
     Group:
       type: object