axusage 3.4.1 → 3.5.0

package/README.md

@@ -153,12 +153,12 @@ Prometheus output emits text metrics suitable for scraping.
 
 ## Serve Mode
 
-`axusage serve` starts an HTTP server that exposes Prometheus metrics at `/metrics` for scraping, with automatic polling.
+`axusage serve` starts an HTTP server exposing usage data at `/metrics` (Prometheus) and `/usage` (JSON). An initial fetch runs at startup to pre-populate the cache (enabling `/health` to return a meaningful status from the first connection). After that, no background polling runs: subsequent requests within the cache window are served instantly, and the first request after the cache expires triggers a refresh (blocking on `/usage`, non-blocking on `/metrics`).
 
 ### Usage
 
 ```bash
-# Start with defaults (port 3848, poll every 5 minutes)
+# Start with defaults (port 3848, max cache age 5 minutes)
 axusage serve
 
 # Custom configuration
@@ -170,17 +170,18 @@ AXUSAGE_PORT=9090 AXUSAGE_INTERVAL=60 axusage serve
 
 ### Options
 
-| Flag                   | Env Var            | Default     | Description                 |
-| ---------------------- | ------------------ | ----------- | --------------------------- |
-| `--port <port>`        | `AXUSAGE_PORT`     | `3848`      | Port to listen on           |
-| `--host <host>`        | `AXUSAGE_HOST`     | `127.0.0.1` | Host to bind to             |
-| `--interval <seconds>` | `AXUSAGE_INTERVAL` | `300`       | Polling interval in seconds |
-| `--service <service>`  | `AXUSAGE_SERVICE`  | all         | Service to monitor          |
+| Flag                   | Env Var            | Default     | Description              |
+| ---------------------- | ------------------ | ----------- | ------------------------ |
+| `--port <port>`        | `AXUSAGE_PORT`     | `3848`      | Port to listen on        |
+| `--host <host>`        | `AXUSAGE_HOST`     | `127.0.0.1` | Host to bind to          |
+| `--interval <seconds>` | `AXUSAGE_INTERVAL` | `300`       | Max cache age in seconds |
+| `--service <service>`  | `AXUSAGE_SERVICE`  | all         | Service to monitor       |
 
 ### Endpoints
 
-- `GET /metrics` — Prometheus text exposition (`text/plain; version=0.0.4`). Returns 503 if no data has been fetched yet.
-- `GET /health` — JSON health status with version, last refresh time, tracked services, and errors.
+- `GET /metrics` — Prometheus text exposition (`text/plain; version=0.0.4`). Serves cached data immediately; triggers a background refresh when stale. Returns 503 when all services are currently failing.
+- `GET /usage` — JSON array of usage objects (one per service). Waits for a fresh snapshot when stale. Returns 503 if no data is available. Date fields (e.g. `resetsAt`) are serialized as ISO 8601 strings.
+- `GET /health` — JSON health status with version, last refresh time, tracked services, and errors. Always responds immediately from cached state without triggering a refresh.
 
 ### Container Deployment
 

package/dist/cli.js

@@ -31,10 +31,10 @@ const program = new Command()
     .addHelpText("after", () => `\nExamples:\n  # Fetch usage for all services\n  ${packageJson.name}\n\n  # JSON output for a single service\n  ${packageJson.name} --service claude --format json\n\n  # TSV output for piping to cut, awk, sort\n  ${packageJson.name} --format tsv | tail -n +2 | awk -F'\\t' '{print $1, $4"%"}'\n\n  # Filter Prometheus metrics with standard tools\n  ${packageJson.name} --format prometheus | grep axusage_utilization_percent\n\n  # Check authentication status for all services\n  ${packageJson.name} --auth-status\n\nSources config file: ${getCredentialSourcesPath()}\n(or set AXUSAGE_SOURCES to JSON to bypass file)\n\n${formatRequiresHelpText()}\nOverride CLI paths: AXUSAGE_CLAUDE_PATH, AXUSAGE_CODEX_PATH, AXUSAGE_GEMINI_PATH, AXUSAGE_GH_PATH\n`);
 program
     .command("serve")
-    .description("Start HTTP server exposing Prometheus metrics at /metrics")
+    .description("Start HTTP server exposing Prometheus metrics at /metrics and usage JSON at /usage")
     .option("-p, --port <port>", "Port to listen on (env: AXUSAGE_PORT)")
     .option("-H, --host <host>", "Host to bind to (env: AXUSAGE_HOST)")
-    .option("--interval <seconds>", "Polling interval in seconds (env: AXUSAGE_INTERVAL)")
+    .option("--interval <seconds>", "Max cache age in seconds (env: AXUSAGE_INTERVAL)")
     .option("-s, --service <service>", "Service to monitor (env: AXUSAGE_SERVICE, default: all)")
     .action(async (options) => {
     await serveCommand(options);

package/dist/commands/serve-command.d.ts

@@ -1,11 +1,30 @@
 /**
- * Serve command handler — starts an HTTP server exposing Prometheus metrics.
+ * Serve command handler — starts an HTTP server exposing usage data.
  */
+import { type ServerState } from "../server/routes.js";
+import type { ServiceResult } from "../types/domain.js";
 type ServeCommandOptions = {
     readonly port?: string;
     readonly host?: string;
     readonly interval?: string;
     readonly service?: string;
 };
+type UsageCache = {
+    readonly getState: () => ServerState | undefined;
+    /** Waits for a fresh snapshot before returning. Use for data endpoints where staleness is unacceptable. */
+    readonly getFreshState: () => Promise<ServerState | undefined>;
+    /** Serves the current snapshot immediately; triggers a background refresh when stale.
+     *  Blocks only if no snapshot exists yet (first ever request). Use for Prometheus /metrics
+     *  where scrape latency matters more than strict freshness. */
+    readonly getStateStaleWhileRevalidate: () => Promise<ServerState | undefined>;
+};
+/**
+ * Creates an on-demand usage cache. Data is fetched via `doFetch` when a
+ * caller requests fresh state and the cached snapshot is older than `intervalMs`.
+ * Concurrent callers during a refresh all receive the same in-flight promise.
+ * When all services fail, the cache retries after a short backoff (≤5s) rather
+ * than waiting the full interval.
+ */
+export declare function createUsageCache(doFetch: () => Promise<ServiceResult[]>, intervalMs: number): UsageCache;
 export declare function serveCommand(options: ServeCommandOptions): Promise<void>;
 export {};

package/dist/commands/serve-command.js

@@ -1,13 +1,76 @@
 /**
- * Serve command handler — starts an HTTP server exposing Prometheus metrics.
+ * Serve command handler — starts an HTTP server exposing usage data.
  */
 import { getServeConfig } from "../config/serve-config.js";
 import { selectServicesToQuery } from "./fetch-service-usage.js";
 import { fetchServicesInParallel } from "./usage-command.js";
-import { formatPrometheusMetrics } from "../utils/format-prometheus-metrics.js";
 import { createServer } from "../server/server.js";
-import { createHealthRouter, createMetricsRouter } from "../server/routes.js";
+import { createHealthRouter, createMetricsRouter, createUsageRouter, } from "../server/routes.js";
 import { getAvailableServices } from "../services/service-adapter-registry.js";
+/**
+ * Creates an on-demand usage cache. Data is fetched via `doFetch` when a
+ * caller requests fresh state and the cached snapshot is older than `intervalMs`.
+ * Concurrent callers during a refresh all receive the same in-flight promise.
+ * When all services fail, the cache retries after a short backoff (≤5s) rather
+ * than waiting the full interval.
+ */
+export function createUsageCache(doFetch, intervalMs) {
+    let state;
+    let refreshPromise;
+    async function doRefresh() {
+        const results = await doFetch();
+        const usage = [];
+        const errors = [];
+        for (const { service, result } of results) {
+            if (result.ok) {
+                usage.push(result.value);
+            }
+            else {
+                const statusSuffix = result.error.status === undefined
+                    ? ""
+                    : ` (HTTP ${String(result.error.status)})`;
+                errors.push(`${service}: fetch failed${statusSuffix}`);
+                console.error(`Warning: Failed to fetch ${service}: ${result.error.message}`);
+            }
+        }
+        state = { usage, refreshedAt: new Date(), errors };
+    }
+    function ensureFresh() {
+        const age = state === undefined ? Infinity : Date.now() - state.refreshedAt.getTime();
+        // If the last refresh produced no data (all services failed), retry on a
+        // short backoff so the server recovers promptly after transient failures
+        // rather than waiting the full cache interval.
+        const hasData = state !== undefined && state.usage.length > 0;
+        const maxAge = hasData ? intervalMs : Math.min(intervalMs, 5000);
+        if (age < maxAge)
+            return Promise.resolve();
+        refreshPromise ??= doRefresh().finally(() => {
+            refreshPromise = undefined;
+        });
+        return refreshPromise;
+    }
+    return {
+        getState: () => state,
+        getFreshState: async () => {
+            await ensureFresh();
+            return state;
+        },
+        getStateStaleWhileRevalidate: async () => {
+            if (state === undefined) {
+                // No snapshot yet — block until we have something to serve.
+                await ensureFresh();
+            }
+            else {
+                // Serve the current snapshot immediately; kick off a background
+                // refresh if stale. Errors are logged; callers are not affected.
+                void ensureFresh().catch((error) => {
+                    console.error("Background metrics refresh failed:", error);
+                });
+            }
+            return state;
+        },
+    };
+}
 export async function serveCommand(options) {
     const config = getServeConfig(options);
     const availableServices = getAvailableServices();
@@ -20,70 +83,14 @@ export async function serveCommand(options) {
         return;
     }
     const servicesToQuery = selectServicesToQuery(config.service);
-    // Cached state
-    let cachedMetrics;
-    let lastRefreshTime;
-    let lastRefreshErrors = [];
-    let refreshing = false;
-    async function refreshMetrics() {
-        if (refreshing)
-            return;
-        refreshing = true;
-        try {
-            const results = await fetchServicesInParallel(servicesToQuery);
-            const successes = [];
-            const errors = [];
-            for (const { service, result } of results) {
-                if (result.ok) {
-                    successes.push(result.value);
-                }
-                else {
-                    const statusSuffix = result.error.status === undefined
-                        ? ""
-                        : ` (HTTP ${String(result.error.status)})`;
-                    errors.push(`${service}: fetch failed${statusSuffix}`);
-                    console.error(`Warning: Failed to fetch ${service}: ${result.error.message}`);
-                }
-            }
-            lastRefreshErrors = errors;
-            lastRefreshTime = new Date();
-            // All services failed → clear cache so /metrics returns 503 instead of
-            // serving stale data that could mask outages in Prometheus alerting.
-            cachedMetrics =
-                successes.length > 0
-                    ? await formatPrometheusMetrics(successes)
-                    : undefined;
-        }
-        finally {
-            refreshing = false; // eslint-disable-line require-atomic-updates -- single-threaded guard, no race
-        }
-    }
-    // Initial fetch
-    console.error(`Fetching initial metrics for: ${servicesToQuery.join(", ")}`);
-    await refreshMetrics();
-    // Create server
-    const healthRouter = createHealthRouter(() => ({
-        lastRefreshTime,
-        services: servicesToQuery,
-        errors: lastRefreshErrors,
-        hasMetrics: cachedMetrics !== undefined,
-    }));
-    const metricsRouter = createMetricsRouter(() => ({
-        metrics: cachedMetrics,
-    }));
-    const server = createServer(config, [healthRouter, metricsRouter]);
-    // Graceful shutdown handler — registered before start so signals during
-    // startup are handled. process.once ensures at-most-one invocation per signal.
-    // Object wrapper lets the shutdown closure reference the interval assigned
-    // after server.start(), without needing a reassignable `let`.
-    const poll = {
-        intervalId: undefined,
-    };
+    const cache = createUsageCache(() => fetchServicesInParallel(servicesToQuery), config.intervalMs);
+    const server = createServer(config, [
+        createHealthRouter(servicesToQuery, cache.getState),
+        createMetricsRouter(cache.getStateStaleWhileRevalidate),
+        createUsageRouter(cache.getFreshState),
+    ]);
     const shutdown = () => {
         console.error("\nShutting down...");
-        if (poll.intervalId !== undefined)
-            clearInterval(poll.intervalId);
-        // Force-exit if server.stop() hangs (e.g. keep-alive connections not closing)
         const forceExit = setTimeout(() => {
             console.error("Shutdown timed out, forcing exit");
             // eslint-disable-next-line unicorn/no-process-exit -- CLI graceful shutdown
@@ -103,14 +110,10 @@ export async function serveCommand(options) {
     };
     process.once("SIGTERM", shutdown);
     process.once("SIGINT", shutdown);
-    // Start server first — if this throws (e.g. EADDRINUSE), no polling interval
-    // is left dangling keeping the process alive.
+    // Pre-populate the cache before accepting connections so /health returns a
+    // meaningful status immediately (important for container readiness checks).
+    console.error(`Fetching initial data for: ${servicesToQuery.join(", ")}`);
+    await cache.getFreshState();
     await server.start();
-    // Start polling only after a successful listen.
-    poll.intervalId = setInterval(() => {
-        void refreshMetrics().catch((error) => {
-            console.error("Unexpected error during metrics refresh:", error);
-        });
-    }, config.intervalMs);
-    console.error(`Polling every ${String(config.intervalMs / 1000)}s for: ${servicesToQuery.join(", ")}`);
+    console.error(`Serving usage for: ${servicesToQuery.join(", ")} (max age: ${String(config.intervalMs / 1000)}s)`);
 }

package/dist/server/routes.d.ts

@@ -2,17 +2,16 @@
  * Route handlers for axusage serve mode.
  */
 import { Router } from "express";
-type HealthStatus = {
-    readonly lastRefreshTime: Date | undefined;
-    readonly services: readonly string[];
+import type { ServiceUsageData } from "../types/domain.js";
+/** Snapshot produced by each refresh cycle. */
+export type ServerState = {
+    readonly usage: readonly ServiceUsageData[];
+    readonly refreshedAt: Date;
     readonly errors: readonly string[];
-    readonly hasMetrics: boolean;
-};
-type MetricsStatus = {
-    readonly metrics: string | undefined;
 };
 /** Create router for GET /health */
-export declare function createHealthRouter(getStatus: () => HealthStatus): Router;
-/** Create router for GET /metrics */
-export declare function createMetricsRouter(getMetrics: () => MetricsStatus): Router;
-export {};
+export declare function createHealthRouter(services: readonly string[], getState: () => ServerState | undefined): Router;
+/** Create router for GET /metrics (Prometheus text exposition) */
+export declare function createMetricsRouter(getState: () => Promise<ServerState | undefined>): Router;
+/** Create router for GET /usage (JSON) */
+export declare function createUsageRouter(getFreshState: () => Promise<ServerState | undefined>): Router;

package/dist/server/routes.js

@@ -3,35 +3,64 @@
  */
 import { Router } from "express";
 import packageJson from "../../package.json" with { type: "json" };
+import { formatPrometheusMetrics } from "../utils/format-prometheus-metrics.js";
+import { toJsonObject } from "../utils/format-service-usage.js";
 /** Create router for GET /health */
-export function createHealthRouter(getStatus) {
+export function createHealthRouter(services, getState) {
     const router = Router();
     router.get("/health", (_request, response) => {
-        const status = getStatus();
-        const healthy = status.hasMetrics;
+        const state = getState();
+        const healthy = state !== undefined && state.usage.length > 0;
         response.status(healthy ? 200 : 503).json({
             status: healthy ? "ok" : "degraded",
             version: packageJson.version,
-            lastRefresh: status.lastRefreshTime?.toISOString(),
-            services: status.services,
-            errors: status.errors,
+            lastRefresh: state?.refreshedAt.toISOString(),
+            services,
+            errors: state?.errors ?? [],
         });
     });
     return router;
 }
-/** Create router for GET /metrics */
-export function createMetricsRouter(getMetrics) {
+/** Create router for GET /metrics (Prometheus text exposition) */
+export function createMetricsRouter(getState) {
     const router = Router();
-    router.get("/metrics", (_request, response) => {
-        const { metrics } = getMetrics();
-        if (!metrics) {
+    // Memoize the rendered Prometheus text by the state snapshot's refreshedAt
+    // timestamp. Scrapes within the same cache window reuse the same Promise,
+    // avoiding recreating prom-client Registry/Gauge objects on each request.
+    // Assignments happen synchronously (before any await) so require-atomic-updates
+    // is satisfied and concurrent scrapes naturally coalesce onto one render.
+    let memoFor;
+    let memoPromise = Promise.resolve("");
+    router.get("/metrics", async (_request, response) => {
+        const state = await getState();
+        const usage = state?.usage;
+        if (!usage || usage.length === 0) {
             response.status(503).type("text/plain").send("No data yet\n");
             return;
         }
+        if (memoFor !== state.refreshedAt) {
+            memoFor = state.refreshedAt;
+            memoPromise = formatPrometheusMetrics(usage);
+        }
+        const text = await memoPromise;
         response
             .status(200)
             .type("text/plain; version=0.0.4; charset=utf-8")
-            .send(metrics);
+            .send(text);
+    });
+    return router;
+}
+/** Create router for GET /usage (JSON) */
+export function createUsageRouter(getFreshState) {
+    const router = Router();
+    router.get("/usage", async (_request, response) => {
+        const state = await getFreshState();
+        const usage = state?.usage;
+        if (!usage || usage.length === 0) {
+            response.status(503).json({ error: "No data yet" });
+            return;
+        }
+        response.status(200).json(usage.map((entry) => toJsonObject(entry)));
     });
     return router;
 }

package/package.json

@@ -2,7 +2,7 @@
   "name": "axusage",
   "author": "Łukasz Jerciński",
   "license": "MIT",
-  "version": "3.4.1",
+  "version": "3.5.0",
   "description": "Monitor API usage across Claude, ChatGPT, GitHub Copilot, and Gemini from a single CLI",
   "repository": {
     "type": "git",