From 0caf7cbbaadc41996822ed4b396fcd3dd6e38e2b Mon Sep 17 00:00:00 2001 From: dbowm91 Date: Tue, 17 Nov 2026 18:31:00 +0000 Subject: [PATCH 1/7] feat: report remaining usage from Codex app-server --- README.md | 2 +- docs/commands.md | 2 +- docs/plans/cli-spec.md | 29 +- plans/codex-app-server-usage-integration.md | 141 +++++ src/cli/args.rs | 17 +- src/cli/commands/usage.rs | 533 ++++++++++++++++-- src/provider/usage/codex_app_server.rs | 594 ++++++++++++++++++++ src/provider/usage/mod.rs | 1 + src/provider/usage/openai.rs | 24 +- tests/fixtures/codex_app_server.rs | 196 +++++++ 10 files changed, 1452 insertions(+), 87 deletions(-) create mode 100644 plans/codex-app-server-usage-integration.md create mode 100644 src/provider/usage/codex_app_server.rs create mode 100644 tests/fixtures/codex_app_server.rs diff --git a/README.md b/README.md index 2bb87a9..d5a72a4 100644 --- a/README.md +++ b/README.md @@ -123,7 +123,7 @@ cleared when the daemon stops. | `eggpass login` | Sign in to a provider. | | `eggpass logout` | Revoke and remove a provider credential. | | `eggpass status` | Show provider login and server state. | -| `eggpass usage` | Read subscription usage where available. | +| `eggpass usage` | Show remaining subscription usage where available. | | `eggpass run` | Start the server. Use `--foreground` to keep it in the terminal. | | `eggpass stop` / `restart` | Stop or restart the server. | | `eggpass port` / `host` | Show or change the listen address. Changes restart the server. | diff --git a/docs/commands.md b/docs/commands.md index 4727d28..e519921 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -66,7 +66,7 @@ eggpass usage --provider xai # query one provider eggpass usage --json # machine-readable report ``` -Queries provider usage directly, without needing the daemon. This is a fresh request, not a cached or polled reading. The report describes usage as reported by each provider. On the default xAI `api` upstream, the reported consumer-subscription quota is separate from inference requests, which are billed to the xAI API tier. The report's caption reflects the configured upstream. If quota is unavailable, the report may include the latest inference HTTP status kept by the daemon in memory. That endpoint reports only per-provider client-facing HTTP status codes, not prompts or response bodies. +Queries provider usage directly, without needing the daemon. This is a fresh request, not a cached or polled reading. Human-readable output shows the percentage and bar for the allowance left, plus each available reset time and countdown; JSON preserves the provider-reported fields. On the default xAI `api` upstream, the reported consumer-subscription quota is separate from inference requests, which are billed to the xAI API tier. The report's caption reflects the configured upstream. If quota is unavailable, the report may include the latest inference HTTP status kept by the daemon in memory. That endpoint reports only per-provider client-facing HTTP status codes, not prompts or response bodies. **Exit codes:** `0` if at least one provider is signed in and not every selected provider failed operationally, `1` if every selected provider failed operationally, `2` if none is signed in. diff --git a/docs/plans/cli-spec.md b/docs/plans/cli-spec.md index bf564f4..6c6312e 100644 --- a/docs/plans/cli-spec.md +++ b/docs/plans/cli-spec.md @@ -658,7 +658,7 @@ be read or written, or the arguments were wrong. ## `eggpass usage` -Report how much of the subscription allowance is used. +Report how much of the subscription allowance remains. ``` eggpass usage # every provider you are signed in to @@ -690,9 +690,9 @@ between blocks, no colour: ``` x.ai · SuperGrok - Weekly ████░░░░░░░░░░░░░░░░ 20% used - Resets Nov 20, 03:07 (UTC) - Api ██░░░░░░░░░░░░░░░░░░ 10% used + Weekly ████████████████░░░░ 80% left + Resets Nov 20, 03:07 (UTC) · in 2d 15hr + Api ██████████████████░░ 90% left Prepaid $0.00 This is your Grok subscription. `eggpass` requests are billed separately against the xAI API tier. @@ -710,18 +710,25 @@ ChatGPT - **The label column is twelve characters wide**, so every value starts in the same place. -- **The bar is twenty cells**, `█` filled and `░` empty. A non-zero - percentage always shows at least one cell, and the bar is omitted entirely - when the percentage is unavailable. -- **The number is the amount *used*.** It reads `20% used`, never `20% left`. +- **The bar is twenty cells**, `█` filled and `░` empty. It represents the + allowance left; a non-zero remainder always shows at least one cell, and the + bar is omitted entirely when the percentage is unavailable. +- **The number is the amount remaining.** It reads `80% left`. The JSON report + still preserves the provider's `used_percent` field unchanged. - **Missing is not zero.** The Grok billing endpoint is proto3 JSON and omits zero-valued scalars, so an absent percentage means the provider did not - say. It reads `unavailable`, never `0% used`. + say. It reads `unavailable`, never `0% left`. +- **A supplied duration labels its window**, such as `5-hour` or `7-day`, in + place of a generic `Primary` or `Secondary` label. Multiple Codex buckets keep + their bucket names when needed to distinguish otherwise identical windows. + A window is not invented when the provider does not report it, and there is + no separate Duration row. - **An explicit state replaces the percentage.** When the provider says the account is not eligible, that is the answer and no number is shown. - **The reset time is local**, with its offset, because `Nov 18, 09:00` alone - is ambiguous. The year appears only when it differs from the current year. - A reset more than an hour in the past is marked `(stale)`. + is ambiguous. Future resets also show a compact countdown (for example, + `in 3hr 21m` or `in 3d 15hr`); the year appears only when it differs from + the current year. A reset more than an hour in the past is marked `(stale)`. - **The caption is not optional.** On the default `api` upstream, `eggpass`'s inference is metered against the xAI API tier and does **not** draw from the consumer subscription the billing endpoint reports. The caption says diff --git a/plans/codex-app-server-usage-integration.md b/plans/codex-app-server-usage-integration.md new file mode 100644 index 0000000..a3aebb0 --- /dev/null +++ b/plans/codex-app-server-usage-integration.md @@ -0,0 +1,141 @@ +# Codex App-Server Usage Integration — Implementation Plan + +**Status:** Implementation complete. Formatting, Clippy, and all 394 workspace tests pass on macOS; the fake app-server covers the documented stdio flow without a live Codex account. Human-readable usage shows remaining percentages, provider-supplied window durations, and reset countdowns. A Windows MSVC cross-check was attempted but could not compile the existing `ring` C dependency because this macOS host lacks Windows C headers. + +**Scope:** Add an optional, local Codex app-server source for `eggpass usage` only. The existing Sign in with ChatGPT (SIWC) OAuth mechanism remains the sole authentication mechanism for Eggpass inference and is not changed by this work. + +**Research checked:** 2026-11-17 against OpenAI's Codex app-server documentation and protocol source, plus the current Eggpass usage path. + +## Goal + +When a user runs `eggpass usage`, report ChatGPT rate-limit windows from the user's existing Codex installation when the Codex CLI is installed, its app-server can start, and it has a ChatGPT-managed account. Do not require Eggpass ChatGPT OAuth for this usage-only result. If this optional source cannot answer, preserve the existing Eggpass usage behavior and output. + +The integration is a read-only consumer of Codex's documented local JSON-RPC account methods. It must not participate in inference, authorization, refresh-token exchange, account switching, login, or logout. + +## Recommended behavior + +1. In the OpenAI provider's `usage` collection path, try a local Codex app-server query before the existing Eggpass-token check. This ordering is necessary: `src/cli/commands/usage.rs:159-171` currently returns `NotSignedIn` before reaching the provider collector when Eggpass itself has no OpenAI token. +2. If Codex returns a valid ChatGPT rate-limit snapshot, convert it to the existing normalized `UsageReport` and report its source as `Codex app-server`. Make that source visible in both terminal and JSON output; the Codex account may differ from the account used for Eggpass inference. Do not print the Codex account email or other identity details. +3. If Codex is absent, unauthenticated, configured for a non-ChatGPT auth mode, incompatible, times out, exits, or returns an error/malformed response, fall through to the existing collector and exit behavior without turning the optional lookup into a command failure: + - If Eggpass has its own OpenAI token, retain the existing `Unavailable` result and message from `src/provider/usage/openai.rs:63-72`. + - If Eggpass has no OpenAI token, retain the existing `NotSignedIn` block and exit semantics from `src/cli/commands/usage.rs:95-106,192-202`. + - Render provider results through the shared human-readable formatter, which shows remaining percentages and reset countdowns where available. +4. Query only when the OpenAI provider is included in the command. Leave xAI collection, inference, and all non-usage commands unchanged. + +## App-server protocol flow + +Use the installed `codex` executable directly, without invoking a shell: + +```text +codex app-server +``` + +The official default transport is stdio with newline-delimited JSON-RPC messages. A minimal session is: + +1. Spawn the process with piped stdin/stdout; keep stderr separate from protocol output. +2. Send `initialize` with a stable Eggpass `clientInfo` name/title/version and wait for the matching response. +3. Send the `initialized` notification. +4. Send `account/read` with `refreshToken: false`; proceed only when `result.account.type` is `chatgpt`. Do not display the returned email. This is a mode check, not a login request. +5. Send `account/rateLimits/read` and wait for the matching response. No thread or turn is needed. +6. Close stdin and terminate/reap the child when the request finishes. + +Use normal account methods without opting into `experimentalApi`. Match responses by JSON-RPC `id`, tolerate/ignore unrelated notifications, and treat JSON-RPC errors as an unavailable optional source. Bound startup/RPC time, stdout line size, and total response size. On timeout or protocol failure, kill/reap the child and continue through Eggpass's existing fallback. Do not let a blocking pipe read hang `eggpass usage` indefinitely; implement a deadline-safe reader/process boundary and test it on supported platforms. + +Do not read or parse `$CODEX_HOME/auth.json`, copy Codex credentials, pass Eggpass SIWC tokens into Codex, call `account/login/*` or `account/logout`, or make direct requests to ChatGPT's internal usage endpoints. The app-server itself owns its local Codex authentication and any normal token lifecycle. Avoid exposing raw app-server output, stderr, credentials, or RPC errors in terminal output or logs. + +## Mapping rate-limit results + +OpenAI documents these fields in `account/rateLimits/read`: + +- `rateLimitsByLimitId`: optional map of metered buckets, for example `codex`. +- `rateLimits`: backward-compatible single-bucket view. +- Each bucket can include `primary` and `secondary` windows with `usedPercent`, `windowDurationMins`, and `resetsAt`. +- Buckets may also include `planType` and `rateLimitReachedType`. + +Mapping rules: + +- Prefer a non-empty `rateLimitsByLimitId` map and do not also emit its duplicate top-level `rateLimits` view. If the map is absent or empty, use `rateLimits`. +- Preserve all returned buckets and distinguish them in output. Human-readable rows use the supplied duration (for example, `5-hour` or `7-day`) instead of a generic primary/secondary label; keep the bucket name when multiple buckets would otherwise be ambiguous. +- Map `usedPercent` to the existing optional percentage, `resetsAt` to Unix seconds, and `windowDurationMins` to seconds with checked conversion. Do not assume a fixed quota period or hard-code a reset schedule. +- Missing or `null` fields mean unavailable, never zero. If no usable quota data is present, fall back to current behavior rather than displaying a zero-usage report. +- Map plan/state fields only where their meaning matches the existing model. Do not collapse distinct workspace-credit or usage-limit states into a misleading generic state; extend the normalized representation only if required to preserve the server's meaning. +- Add separate source metadata to the usage entry rather than reusing `caption`, which describes which pool the reported quota belongs to. Keep the JSON addition optional/additive when the source is not Codex. + +The existing `UsageReport`/`QuotaWindow` model already represents optional percentages, reset timestamps, and durations (`src/provider/usage/mod.rs:32-75`). The formatter uses supplied durations as inline window labels, keeps provider labels when duration is missing, shows remaining percentages and future reset countdowns, and leaves the JSON `used_percent` data unchanged. Bucket names are included when multiple Codex buckets need disambiguation; xAI collection semantics remain unchanged. + +## `account/usage/read` scope + +`account/usage/read` is documented as ChatGPT token-activity summaries and optional daily token buckets (for example lifetime tokens, peak daily tokens, and per-day tokens). It is not quota remaining or a rate-limit window. It is not required to solve the current missing-quota problem, so defer it from the first implementation unless a separate product decision expands `eggpass usage` to include a distinct token-activity section. If added later, keep it separate from quota percentages, preserve nullable/missing values, and update terminal/JSON output and tests explicitly. + +## Implementation stages + +### Stage 0 — Confirm local process compatibility + +- Confirm the supported Codex CLI executable invocation and stdio behavior on the project's supported operating systems; use `codex app-server` with default stdio transport. +- Prototype the initialize/initialized/account-read/rate-limits exchange against a test/fake app-server process. Do not inspect or alter any user's Codex credentials and do not require a live account in CI. +- Resolve process deadlines, child cleanup, executable-not-found behavior, and bounded stdout/stderr handling before integrating the query. +- Use existing `serde_json` and standard process/I/O facilities where practical; add a dependency only if a safe, portable timeout/reader implementation requires it. + +**Exit:** A bounded helper can complete the RPC flow, distinguish ChatGPT from unsupported/no account, and cleanly terminate the child on success and failure. + +### Stage 1 — Integrate the OpenAI usage fallback + +- Add a small app-server usage adapter under the provider usage code. Keep process launching and JSON-RPC concerns out of the inference provider implementation. +- Clarify the existing OpenAI collector's module comments as the SIWC-only fallback; do not leave wording that implies the new app-server source is impossible or unavailable. +- Call it for OpenAI usage before the Eggpass token short-circuit. If it returns no valid report, execute the current token-check/provider-collector logic unchanged. +- Convert bucket windows to the current report model; add optional source labeling to text and JSON output. Clearly identify that the result came from the Codex account, which may not be the Eggpass inference account. +- Do not change OAuth configuration, credentials, token storage, auth commands, `ProviderRuntime` inference behavior, upstream requests, or xAI usage. + +**Exit:** A Codex-authenticated ChatGPT account can supply usage when Eggpass OpenAI OAuth is absent; all unavailable cases retain existing output/exit behavior. + +### Stage 2 — Test the optional boundary and regressions + +Use a fake `codex` executable or injected executable path to test deterministic protocol behavior without network/account access: + +- executable missing; spawn failure; early exit; startup/RPC timeout; malformed/oversized JSONL; total-output limit; JSON-RPC error; missing or wrong response ID; notification bursts without dropping responses; +- successful initialize handshake and both account RPCs; +- ChatGPT account, no account, API-key account, and another unsupported mode; +- legacy `rateLimits` only; populated and empty `rateLimitsByLimitId`; primary/secondary windows; multiple buckets; null/missing values; zero percent; reset and duration conversion; unknown plan/state variants; +- no false zero report and no duplicate reporting of `rateLimits` plus the bucket map; +- fallback to the exact current OpenAI response when Codex is missing/unusable, both with and without Eggpass OpenAI credentials; +- Codex usage is reported without Eggpass OpenAI credentials, so `eggpass usage --provider openai` does not incorrectly return the current not-signed-in exit code; +- source labeling in text and JSON; no email, token, raw child output, or credential material in output/logs; +- existing xAI usage tests and OpenAI inference/auth tests remain unchanged and pass. + +**Exit:** All new tests use a fake process and no live service. Existing CLI, OAuth, and inference tests pass; `git diff --check`, formatting, Clippy, and workspace tests pass. + +## Out of scope + +- Replacing, extending, or otherwise changing Eggpass's current SIWC OAuth mechanism for inference. +- Supplying Eggpass tokens or account identifiers to Codex app-server. +- Any Codex login, logout, account-switching, or credential-management UI/flow. +- Direct calls to undocumented ChatGPT backend endpoints or reading Codex credential files. +- Making inference depend on Codex being installed or signed in. +- Adding `account/usage/read` token activity to the initial quota-focused implementation. +- Changes to release workflows, package publication, daemon behavior, or xAI usage. + +## Acceptance checklist + +- [x] OpenAI `usage` can query the local Codex app-server without requiring Eggpass OpenAI OAuth. +- [x] `codex app-server` is optional; missing, unauthenticated, unsupported, incompatible, malformed, or timed-out Codex falls back to current Eggpass behavior. +- [x] Codex reads are limited to account state and documented usage/rate-limit read methods; no login/logout or direct private HTTP endpoint is used. +- [x] Usage output clearly labels the Codex source and buckets, without exposing account email or secrets. +- [x] `account/usage/read` remains deferred unless separately approved as distinct token-activity output. +- [x] Eggpass inference OAuth, token storage, provider requests, xAI usage, and non-usage commands are unchanged. +- [x] Fake-process tests cover protocol success/failure, fallback behavior, and output safety; full existing Rust checks pass. + +## References + +Official OpenAI documentation and schema reviewed 2026-11-17: + +- [Codex App Server protocol and stdio transport](https://developers.openai.com/codex/app-server.md) — JSONL/JSON-RPC framing, `initialize` then `initialized`, local CLI startup, account methods, and the usage response examples. +- [Codex app-server account protocol source](https://github.com/openai/codex/blob/main/codex-rs/app-server-protocol/src/protocol/v2/account.rs) — response structures for rate-limit buckets/windows and token usage summary. + +Repository context: + +- `src/cli/commands/usage.rs:53-118` — provider collection, output, and all-not-signed-in exit behavior. +- `src/cli/commands/usage.rs:159-171` — current Eggpass token check before provider usage collection. +- `src/cli/commands/usage.rs:186-232` — current unavailable/not-signed-in terminal rendering. +- `src/provider/usage/openai.rs:57-72` — existing ChatGPT unavailable result and fallback text. +- `src/provider/usage/mod.rs:32-75,161-192` — normalized report, quota window, and provider result types. +- `Cargo.toml:63-69` — current `serde_json` and Tokio dependencies; do not make runtime dependencies a prerequisite for inference. diff --git a/src/cli/args.rs b/src/cli/args.rs index 4789e0a..a8b300f 100644 --- a/src/cli/args.rs +++ b/src/cli/args.rs @@ -28,7 +28,7 @@ pub enum Command { }, /// Report account and daemon state. Status, - /// Report how much of the subscription allowance is used. + /// Report how much of the subscription allowance remains. Usage { /// The provider to ask, when it was named. provider: Option, @@ -529,7 +529,7 @@ pub fn global_help() -> String { login Authenticate with a provider over OAuth\n \ logout Revoke and remove stored credentials\n \ status Show account and daemon state\n \ - usage Show how much of the subscription allowance is used\n \ + usage Show how much of the subscription allowance remains\n \ run Start the server as a background daemon\n \ stop Stop the running daemon\n \ restart Stop the daemon, then start it again\n \ @@ -567,7 +567,7 @@ pub fn command_help(name: &str) -> String { "status" => "eggpass status\n\nShow account state and daemon state.\n".to_string(), "usage" => { "eggpass usage [--json]\n\n\ - Show how much of the subscription allowance is used. Each provider\n\ + Show how much of the subscription allowance remains. Each provider\n\ is asked once, on this run, and the answer is printed and the\n\ command ends. Without --provider every provider you are signed in\n\ to is asked.\n\n\ @@ -794,6 +794,17 @@ mod tests { assert!(text.contains("--device"), "{text}"); } + #[test] + fn usage_help_describes_remaining_usage() { + assert!( + global_help() + .contains("usage Show how much of the subscription allowance remains") + ); + let usage = command_help("usage"); + assert!(usage.contains("allowance remains"), "{usage}"); + assert!(!usage.contains("allowance is used"), "{usage}"); + } + #[test] fn version_is_available() { assert!(matches!( diff --git a/src/cli/commands/usage.rs b/src/cli/commands/usage.rs index 2b30b8f..8bb2ee0 100644 --- a/src/cli/commands/usage.rs +++ b/src/cli/commands/usage.rs @@ -21,14 +21,14 @@ //! body carries the account's email, its user id and its balances; it goes //! to the provider and stops there. -use std::collections::BTreeMap; +use std::collections::{BTreeMap, BTreeSet}; use std::time::Duration; use serde::Serialize; use crate::cli::{CommandError, Context}; use crate::daemon::{self, DaemonState}; -use crate::provider::usage::{ProviderUsage, UsageReport}; +use crate::provider::usage::{ProviderUsage, UsageReport, WindowLabel}; use crate::provider::{ProviderId, ProviderRuntime}; use crate::timeutil; @@ -50,7 +50,7 @@ const EMPTY: char = '░'; /// How far past a reset time a window counts as stale, in seconds. const STALE_AFTER: i64 = 3_600; -/// Show how much of the subscription allowance is used. +/// Show how much of the subscription allowance remains. pub fn usage( context: &Context, provider: Option, @@ -68,16 +68,23 @@ pub fn usage( let entries: Vec = providers .into_iter() - .map(|provider| ProviderEntry { - provider, - outcome: collect_one(context, provider), - // The caption travels with the report, in the JSON as well as in - // the bars: a machine-readable number without it is as misleading - // as a number without it on the terminal. - caption: caption_for(provider, &context.config), - // The last inference is the only evidence there is about a - // provider that publishes no quota of its own. - last_inference: inferences.get(&provider).copied(), + .map(|provider| { + let (outcome, source) = collect_one(context, provider); + ProviderEntry { + provider, + outcome, + // The source is distinct from `caption`: a source identifies + // which account supplied the snapshot, while a caption names + // the pool the quota belongs to. + source, + // The caption travels with the report, in the JSON as well as in + // the bars: a machine-readable number without it is as misleading + // as a number without it on the terminal. + caption: caption_for(provider, &context.config), + // The last inference is the only evidence there is about a + // provider that publishes no quota of its own. + last_inference: inferences.get(&provider).copied(), + } }) .collect(); @@ -92,6 +99,11 @@ pub fn usage( print!("{}", render(&entries)); } + usage_exit_result(&entries) +} + +/// Decide the command status after output has been rendered. +fn usage_exit_result(entries: &[ProviderEntry]) -> Result<(), CommandError> { // A provider that is not signed in still gets a block, so the output does // not change shape — but a run in which nobody is signed in has nothing // to report at all. @@ -126,6 +138,9 @@ struct ProviderEntry { /// What it had to say. #[serde(flatten)] outcome: ProviderUsage, + /// Which account or local source supplied the usage snapshot, when relevant. + #[serde(skip_serializing_if = "Option::is_none")] + source: Option<&'static str>, /// Which pool the numbers belong to, when the provider reported any. caption: Option, /// The HTTP status the last inference to this provider was answered with. @@ -158,17 +173,51 @@ fn caption_for(provider: ProviderId, config: &crate::config::Config) -> Option ProviderUsage { - let runtime = ProviderRuntime::new(provider, &context.config, &context.paths); +/// Codex is consulted only for OpenAI usage and before Eggpass's own +/// credential check. If it cannot provide a report, the existing provider +/// path below remains the fallback. +fn collect_one(context: &Context, provider: ProviderId) -> (ProviderUsage, Option<&'static str>) { + let codex_report = (provider == ProviderId::OpenAi) + .then(crate::provider::usage::codex_app_server::collect) + .flatten(); + collect_one_with_codex_result(context, provider, codex_report) +} + +/// Apply an optional Codex report, otherwise run the existing token/collector path. +fn collect_one_with_codex_result( + context: &Context, + provider: ProviderId, + codex_report: Option, +) -> (ProviderUsage, Option<&'static str>) { + if let Some(codex_usage) = codex_outcome(provider, codex_report) { + return codex_usage; + } - match runtime.tokens.current() { + let runtime = ProviderRuntime::new(provider, &context.config, &context.paths); + let outcome = match runtime.tokens.current() { Ok(None) => ProviderUsage::NotSignedIn, Ok(Some(_)) => runtime.usage(), Err(err) => ProviderUsage::Failed { reason: format!("could not read the stored credentials ({err})"), }, + }; + (outcome, None) +} + +/// Use Codex's report only for the OpenAI usage entry. +fn codex_outcome( + provider: ProviderId, + report: Option, +) -> Option<(ProviderUsage, Option<&'static str>)> { + if provider != ProviderId::OpenAi { + return None; } + report.map(|report| { + ( + ProviderUsage::Reported { report }, + Some(crate::provider::usage::codex_app_server::SOURCE_LABEL), + ) + }) } /// Render the whole report. @@ -186,9 +235,13 @@ fn render(entries: &[ProviderEntry]) -> String { /// Render one provider's block. fn render_block(out: &mut String, entry: &ProviderEntry) { match &entry.outcome { - ProviderUsage::Reported { report } => { - render_reported(out, entry.provider, report, entry.caption.as_deref()) - } + ProviderUsage::Reported { report } => render_reported( + out, + entry.provider, + report, + entry.caption.as_deref(), + entry.source, + ), ProviderUsage::NotSignedIn => { out.push_str(entry.provider.display_name()); out.push('\n'); @@ -256,6 +309,15 @@ fn render_caption(out: &mut String, caption: Option<&str>) { out.push_str(&format!(" {caption}\n")); } +/// Render the account/source note when the reported snapshot came from Codex. +fn render_source(out: &mut String, source: Option<&str>) { + let Some(source) = source else { + return; + }; + out.push_str(&field("Source", source)); + out.push('\n'); +} + /// Render the row that says what the last inference was answered with. /// /// It is printed when the quota could not be read, and only then: a block @@ -334,6 +396,7 @@ fn render_reported( provider: ProviderId, report: &UsageReport, caption: Option<&str>, + source: Option<&str>, ) { // The heading names the plan when the provider named one. match &report.plan { @@ -347,24 +410,47 @@ fn render_reported( out.push('\n'); let now = timeutil::now_unix(); + let buckets: BTreeSet<&str> = report + .windows + .iter() + .filter_map(|window| bucket_id(&window.label)) + .collect(); + let multiple_buckets = buckets.len() > 1; for window in &report.windows { + // Use the provider's window duration when it is known. This turns + // Codex's generic Primary/Secondary buckets into useful labels such as + // 5-hour and 7-day, while preserving named windows like Grok's Weekly + // when no duration is supplied. Keep bucket names when they are needed + // to distinguish multiple reported buckets. + let label = match ( + window.duration_secs.filter(|duration| *duration > 0), + multiple_buckets.then(|| bucket_id(&window.label)).flatten(), + ) { + (Some(duration), Some(bucket)) => { + format!("{bucket} {}", duration_label(duration)) + } + (Some(duration), None) => duration_label(duration), + (None, _) => window.label.display(), + }; + // An explicit state is the provider's answer, and it replaces the // percentage entirely. if let Some(state) = &report.state { - out.push_str(&field(&window.label.display(), state.display())); + out.push_str(&field(&label, state.display())); out.push('\n'); } else { match window.used_percent { Some(percent) => { + let left = left_percent(percent); out.push_str(&field( - &window.label.display(), - &format!("{} {} used", bar(percent), percent_text(percent)), + &label, + &format!("{} {} left", bar(left), percent_text(left)), )); } // No bar at all: a bar with a question mark in it would be a // number we do not have. - None => out.push_str(&field(&window.label.display(), "unavailable")), + None => out.push_str(&field(&label, "unavailable")), } out.push('\n'); } @@ -375,7 +461,12 @@ fn render_reported( // The offset is the one in force at the reset instant, so a // reset on the far side of a daylight-saving change is right. let offset = timeutil::local_offset_seconds(resets_at).unwrap_or(0); - out.push_str(&field("Resets", &reset_text(resets_at, now, offset))); + let mut reset = reset_text(resets_at, now, offset); + if let Some(remaining) = reset_countdown(resets_at, now) { + reset.push_str(" · in "); + reset.push_str(&remaining); + } + out.push_str(&field("Resets", &reset)); out.push('\n'); } } @@ -387,11 +478,12 @@ fn render_reported( for product in &report.breakdown { match product.used_percent { Some(percent) => { + let left = left_percent(percent); out.push_str(&format!( - " {: String { - format!(" {label:= LABEL_WIDTH { + " " + } else { + "" + }; + format!(" {label: String { format!(" {: String { let rounded = round_percent(percent); let mut filled = (rounded / 100.0 * BAR_CELLS as f64).round() as i64; @@ -483,6 +580,52 @@ fn percent_text(percent: f64) -> String { } } +/// Convert the provider's used percentage into the percentage left. +fn left_percent(used_percent: f64) -> f64 { + (100.0 - used_percent).clamp(0.0, 100.0) +} + +/// A compact label for a quota-window duration. +/// +/// Exact days and hours use the adjective form that fits beside the bar +/// (`7-day`, `5-hour`). Unusual durations stay precise without a separate +/// Duration row. +fn duration_label(duration_secs: i64) -> String { + if duration_secs > 0 && duration_secs % 86_400 == 0 { + format!("{}-day", duration_secs / 86_400) + } else if duration_secs > 0 && duration_secs % 3_600 == 0 { + format!("{}-hour", duration_secs / 3_600) + } else if duration_secs > 0 && duration_secs % 60 == 0 { + format!("{}-min", duration_secs / 60) + } else { + let hours = duration_secs / 3_600; + let minutes = duration_secs % 3_600 / 60; + let seconds = duration_secs % 60; + match (hours, minutes, seconds) { + (hours, minutes, _) if hours > 0 && minutes > 0 => { + format!("{hours}h {minutes}m") + } + (hours, _, _) if hours > 0 => format!("{hours}h"), + (_, minutes, seconds) if minutes > 0 && seconds > 0 => { + format!("{minutes}m {seconds}s") + } + (_, minutes, _) if minutes > 0 => format!("{minutes}m"), + (_, _, seconds) => format!("{seconds}s"), + } + } +} + +/// Extract a Codex bucket name from its `bucket Primary/Secondary` label. +fn bucket_id(label: &WindowLabel) -> Option<&str> { + let WindowLabel::Other(label) = label else { + return None; + }; + label + .strip_suffix(" Primary") + .or_else(|| label.strip_suffix(" Secondary")) + .filter(|bucket| !bucket.is_empty()) +} + /// The reset time, in the local timezone, with its offset. /// /// The offset is printed because `Nov 18, 09:00` alone is ambiguous: a user @@ -507,6 +650,36 @@ fn reset_text(resets_at: i64, now: i64, offset: i64) -> String { text } +/// Time remaining until a future reset, at a glance precision. +fn reset_countdown(resets_at: i64, now: i64) -> Option { + let seconds = resets_at.saturating_sub(now); + if seconds <= 0 { + return None; + } + + let days = seconds / 86_400; + let hours = seconds % 86_400 / 3_600; + let minutes = seconds % 3_600 / 60; + + Some(if days > 0 { + if hours > 0 { + format!("{days}d {hours}hr") + } else { + format!("{days}d") + } + } else if hours > 0 { + if minutes > 0 { + format!("{hours}hr {minutes}m") + } else { + format!("{hours}hr") + } + } else if minutes > 0 { + format!("{minutes}m") + } else { + "under 1m".to_string() + }) +} + /// An amount in cents, as dollars. fn money(cents: i64) -> String { let sign = if cents < 0 { "-" } else { "" }; @@ -552,6 +725,7 @@ mod tests { ProviderEntry { provider: ProviderId::Xai, outcome, + source: None, caption: None, last_inference: None, } @@ -562,6 +736,7 @@ mod tests { ProviderEntry { provider: ProviderId::OpenAi, outcome, + source: None, caption: None, last_inference: Some(status), } @@ -688,25 +863,28 @@ mod tests { } #[test] - fn a_tiny_percentage_does_not_contradict_its_bar() { - // A percentage that rounds to zero reads `0% used`, so its bar is - // empty. A filled cell beside `0% used` would say otherwise. - assert_eq!(percent_text(0.04), "0%"); - assert_eq!(bar(0.04).chars().filter(|c| *c == FILLED).count(), 0); - assert_eq!(bar(0.04).chars().count(), 20); - - // A percentage that rounds to something above zero gets a cell. - assert_eq!(percent_text(0.1), "0.1%"); - assert_eq!(bar(0.1).chars().filter(|c| *c == FILLED).count(), 1); - assert_eq!(bar(0.1).chars().count(), 20); + fn a_tiny_remaining_percentage_does_not_contradict_its_bar() { + // When almost all the allowance is used, a remainder that rounds to + // zero reads `0% left` and has an empty bar. + let left = left_percent(99.96); + assert_eq!(percent_text(left), "0%"); + assert_eq!(bar(left).chars().filter(|c| *c == FILLED).count(), 0); + assert_eq!(bar(left).chars().count(), 20); + + // A remainder that rounds above zero gets a cell. + let left = left_percent(99.9); + assert_eq!(percent_text(left), "0.1%"); + assert_eq!(bar(left).chars().filter(|c| *c == FILLED).count(), 1); + assert_eq!(bar(left).chars().count(), 20); } #[test] fn the_chatgpt_block_names_the_error_codes() { let entry = ProviderEntry { provider: ProviderId::OpenAi, - caption: None, outcome: chatgpt_unavailable(), + source: None, + caption: None, last_inference: None, }; @@ -911,11 +1089,10 @@ mod tests { } #[test] - fn the_percentage_reads_as_used() { - // The number is how much is *used*, never how much is left. + fn the_bar_and_percentage_show_remaining_allowance() { let text = render(&[entry(reported(Some(40.0)))]); - assert!(text.contains("40% used"), "{text}"); - assert!(!text.contains("40% left"), "{text}"); + assert!(text.contains(&format!("{} 60% left", bar(60.0))), "{text}"); + assert!(!text.contains("40% used"), "{text}"); } #[test] @@ -934,9 +1111,9 @@ mod tests { let text = render(&[entry(ProviderUsage::Reported { report })]); assert!(text.contains("GrokBuild"), "{text}"); - assert!(text.contains("50% used"), "{text}"); + assert!(text.contains("50% left"), "{text}"); assert!(text.contains("GrokChat"), "{text}"); - assert!(text.contains("20% used"), "{text}"); + assert!(text.contains("80% left"), "{text}"); } #[test] @@ -987,8 +1164,9 @@ mod tests { fn the_json_report_names_the_provider_and_the_status() { let entries = vec![ProviderEntry { provider: ProviderId::OpenAi, - caption: None, outcome: ProviderUsage::NotSignedIn, + source: None, + caption: None, last_inference: None, }]; @@ -998,5 +1176,254 @@ mod tests { let text = serde_json::to_string(&report).unwrap(); assert!(text.contains("\"provider\":\"openai\""), "{text}"); assert!(text.contains("\"status\":\"not_signed_in\""), "{text}"); + assert!(!text.contains("\"source\":null"), "{text}"); + } + + fn context_for(directory: &std::path::Path) -> Context { + Context { + paths: crate::paths::Paths::in_directory(directory), + config: crate::config::Config::default(), + cli: crate::cli::args::Cli { + command: crate::cli::args::Command::Usage { + provider: Some(ProviderId::OpenAi), + json: false, + }, + config_path: None, + verbose: false, + }, + } + } + + fn codex_report() -> UsageReport { + UsageReport { + provider: ProviderId::OpenAi, + plan: None, + windows: vec![QuotaWindow { + label: WindowLabel::Other("codex Primary".to_string()), + used_percent: Some(25.0), + resets_at: Some(1_800_000_000), + duration_secs: Some(18_000), + }], + breakdown: Vec::new(), + credits: None, + state: None, + } + } + + #[test] + fn a_codex_report_precedes_the_missing_eggpass_credential_check() { + let directory = tempfile::tempdir().unwrap(); + let context = context_for(directory.path()); + let (outcome, source) = + collect_one_with_codex_result(&context, ProviderId::OpenAi, Some(codex_report())); + let entry = ProviderEntry { + provider: ProviderId::OpenAi, + outcome, + source, + caption: None, + last_inference: None, + }; + + assert!(matches!(&entry.outcome, ProviderUsage::Reported { .. })); + assert_eq!( + entry.source, + Some(crate::provider::usage::codex_app_server::SOURCE_LABEL) + ); + assert!(usage_exit_result(std::slice::from_ref(&entry)).is_ok()); + } + + #[test] + fn an_unavailable_codex_source_preserves_both_existing_fallbacks() { + let directory = tempfile::tempdir().unwrap(); + let context = context_for(directory.path()); + let (outcome, source) = collect_one_with_codex_result(&context, ProviderId::OpenAi, None); + assert!(matches!(&outcome, ProviderUsage::NotSignedIn)); + assert_eq!(source, None); + let error = usage_exit_result(&[ProviderEntry { + provider: ProviderId::OpenAi, + outcome, + source, + caption: None, + last_inference: None, + }]) + .unwrap_err(); + assert_eq!(error.code, 2); + assert_eq!( + error.message.as_deref(), + Some("not signed in — run `eggpass login`") + ); + + let credential = crate::auth::store::StoredAuth { + access_token: "test-only-access-token".to_string(), + refresh_token: None, + id_token: None, + token_type: "Bearer".to_string(), + scope: None, + client_id: "test-client".to_string(), + issuer: "https://auth.openai.com".to_string(), + expires_at: Some(crate::timeutil::now_unix() + 3_600), + obtained_at: crate::timeutil::now_unix(), + user_id: None, + email: None, + ext_agent_host_id: None, + plan_enabled: false, + }; + crate::auth::store::save( + &context.paths.credential_file(ProviderId::OpenAi.as_str()), + &credential, + ) + .unwrap(); + let (outcome, source) = collect_one_with_codex_result(&context, ProviderId::OpenAi, None); + assert_eq!(source, None); + assert!( + matches!( + outcome, + ProviderUsage::Unavailable { + ref reason, + ref source, + ref hint, + ref signals, + } if reason == "Sign in with ChatGPT does not expose a quota API" + && source.as_deref() == Some("not exposed by OAuth") + && hint.as_deref() == Some("https://chatgpt.com/settings/usage") + && signals.len() == 3 + ), + "unexpected fallback: {outcome:?}" + ); + } + + #[test] + fn codex_source_and_bucket_are_visible_in_text_and_json_without_identity() { + let mut entry = ProviderEntry { + provider: ProviderId::OpenAi, + outcome: ProviderUsage::Reported { + report: codex_report(), + }, + source: Some(crate::provider::usage::codex_app_server::SOURCE_LABEL), + caption: None, + last_inference: None, + }; + let text = render(std::slice::from_ref(&entry)); + assert!(text.contains("5-hour"), "{text}"); + assert!(text.contains("75% left"), "{text}"); + assert!(!text.contains("codex Primary"), "{text}"); + assert!(!text.contains("Duration"), "{text}"); + assert!(text.contains("Source Codex app-server"), "{text}"); + assert!(!text.contains("@"), "{text}"); + + let report = UsageReportJson { + providers: std::slice::from_ref(&entry), + }; + let value = serde_json::to_value(report).unwrap(); + let encoded = value.to_string(); + assert!( + encoded.contains("\"source\":\"Codex app-server"), + "{encoded}" + ); + assert!(encoded.contains("codex Primary"), "{encoded}"); + assert!(encoded.contains("\"duration_secs\":18000"), "{encoded}"); + assert!(!encoded.contains("@"), "{encoded}"); + + entry.source = None; + let legacy_json = serde_json::to_value(UsageReportJson { + providers: std::slice::from_ref(&entry), + }) + .unwrap(); + assert!(legacy_json["providers"][0].get("source").is_none()); + } + + #[test] + fn codex_usage_is_not_assigned_to_xai() { + assert!(codex_outcome(ProviderId::Xai, Some(codex_report())).is_none()); + } + + #[test] + fn durations_become_compact_window_labels() { + assert_eq!(duration_label(18_000), "5-hour"); + assert_eq!(duration_label(604_800), "7-day"); + assert_eq!(duration_label(300), "5-min"); + assert_eq!(duration_label(5_400), "90-min"); + assert_eq!(duration_label(3_661), "1h 1m"); + + let text = render(&[entry(reported(Some(40.0)))]); + assert!(text.contains("Weekly"), "{text}"); + assert!(!text.contains("Duration"), "{text}"); + } + + #[test] + fn a_named_weekly_window_is_not_relabelled_or_expanded() { + let mut report = reported_report(Some(1.0)); + report.windows[0].resets_at = + Some(timeutil::now_unix() + 3 * 86_400 + 15 * 3_600 + 30 * 60); + let text = render(&[entry(ProviderUsage::Reported { report })]); + + assert!(text.contains("Weekly"), "{text}"); + assert!(text.contains("99% left"), "{text}"); + assert!(text.contains("in 3d 15hr"), "{text}"); + assert!(!text.contains("5-hour"), "{text}"); + assert!(!text.contains("7-day"), "{text}"); + } + + #[test] + fn reset_countdowns_are_compact_and_omit_past_resets() { + let now = timeutil::parse_rfc3339_to_unix("2026-11-14T12:00:00Z").unwrap(); + assert_eq!( + reset_countdown(now + 3 * 86_400 + 15 * 3_600 + 42 * 60, now), + Some("3d 15hr".to_string()) + ); + assert_eq!( + reset_countdown(now + 3 * 3_600 + 21 * 60 + 12, now), + Some("3hr 21m".to_string()) + ); + assert_eq!(reset_countdown(now + 20, now), Some("under 1m".to_string())); + assert_eq!(reset_countdown(now, now), None); + assert_eq!(reset_countdown(now - 30, now), None); + } + + #[test] + fn each_provider_window_shows_duration_left_and_its_reset_countdown() { + let now = timeutil::now_unix(); + let mut report = codex_report(); + report.windows = vec![ + QuotaWindow { + label: WindowLabel::Other("codex Primary".to_string()), + used_percent: Some(69.0), + resets_at: Some(now + 3 * 3_600 + 21 * 60), + duration_secs: Some(18_000), + }, + QuotaWindow { + label: WindowLabel::Other("codex Secondary".to_string()), + used_percent: Some(95.0), + resets_at: Some(now + 3 * 86_400 + 15 * 3_600 + 30 * 60), + duration_secs: Some(604_800), + }, + ]; + let text = render(&[entry(ProviderUsage::Reported { report })]); + + assert!(text.contains("5-hour"), "{text}"); + assert!(text.contains("31% left"), "{text}"); + assert!(text.contains("7-day"), "{text}"); + assert!(text.contains("5% left"), "{text}"); + assert!(text.contains("in 3hr 21m"), "{text}"); + assert!(text.contains("in 3d 15hr"), "{text}"); + assert!(!text.contains("Primary"), "{text}"); + assert!(!text.contains("Secondary"), "{text}"); + assert!(!text.contains("Duration"), "{text}"); + } + + #[test] + fn multiple_codex_buckets_remain_distinguishable_with_duration_labels() { + let mut report = codex_report(); + report.windows.push(QuotaWindow { + label: WindowLabel::Other("other-model Primary".to_string()), + used_percent: Some(50.0), + resets_at: None, + duration_secs: Some(18_000), + }); + let text = render(&[entry(ProviderUsage::Reported { report })]); + + assert!(text.contains("codex 5-hour"), "{text}"); + assert!(text.contains("other-model 5-hour"), "{text}"); + assert!(!text.contains("Primary"), "{text}"); } } diff --git a/src/provider/usage/codex_app_server.rs b/src/provider/usage/codex_app_server.rs new file mode 100644 index 0000000..25a4b89 --- /dev/null +++ b/src/provider/usage/codex_app_server.rs @@ -0,0 +1,594 @@ +//! Optional ChatGPT rate-limit reads from the local Codex app-server. +//! +//! This is a usage-only source. It invokes `codex app-server` over its +//! documented stdio JSON-RPC protocol, reads the account mode without +//! refreshing it, and asks only for rate limits. It never reads Codex +//! credential files or participates in Eggpass authentication or inference. + +#[cfg(test)] +use std::ffi::OsStr; +use std::io::{self, BufRead, BufReader, Read, Write}; +use std::process::{Child, ChildStderr, ChildStdin, Command, Stdio}; +use std::sync::mpsc::{self, Receiver, SyncSender}; +use std::thread; +use std::time::{Duration, Instant}; + +use serde_json::{Value, json}; + +use super::{QuotaWindow, UsageReport, WindowLabel}; +use crate::provider::ProviderId; + +/// The fixed label shown when a quota came from Codex rather than Eggpass OAuth. +pub const SOURCE_LABEL: &str = "Codex app-server (may differ from Eggpass inference account)"; + +/// One deadline covers process startup and the complete RPC exchange. +const SESSION_TIMEOUT: Duration = Duration::from_secs(8); +/// Maximum bytes accepted on one JSONL record. +const MAX_LINE_BYTES: usize = 256 * 1024; +/// Maximum total stdout bytes accepted during one app-server session. +const MAX_STDOUT_BYTES: usize = 1024 * 1024; +/// A small bounded queue prevents a noisy child from buffering unlimited lines. +const QUEUED_LINES: usize = 16; + +/// Query the installed Codex CLI, returning `None` for every optional-source failure. +pub fn collect() -> Option { + let mut command = Command::new("codex"); + command.arg("app-server"); + collect_with_command(command, SESSION_TIMEOUT) +} + +/// Run one app-server session. Kept injectable so tests can use a fake process. +fn collect_with_command(mut command: Command, timeout: Duration) -> Option { + let deadline = Instant::now().checked_add(timeout)?; + command + .stdin(Stdio::piped()) + .stdout(Stdio::piped()) + .stderr(Stdio::piped()); + + let child = command.spawn().ok()?; + let mut process = ManagedChild::new(child); + let stdin = process.child.stdin.take()?; + process.stdin = Some(stdin); + let stdout = process.child.stdout.take()?; + let stderr = process.child.stderr.take()?; + + // Stderr is drained on a separate thread and discarded. No child output is + // retained, logged, or allowed to block the JSON-RPC channel. + drain_stderr(stderr).ok()?; + let responses = spawn_stdout_reader(stdout)?; + + let initialize = json!({ + "id": 1, + "method": "initialize", + "params": { + "clientInfo": { + "name": "eggpass", + "title": "Eggpass", + "version": env!("CARGO_PKG_VERSION") + }, + "capabilities": {} + } + }); + if !send_message(process.stdin.as_mut()?, &initialize) + || receive_response(&responses, 1, deadline).is_none() + { + return None; + } + + if !send_message(process.stdin.as_mut()?, &json!({ "method": "initialized" })) { + return None; + } + + let account_request = json!({ + "id": 2, + "method": "account/read", + "params": { "refreshToken": false } + }); + if !send_message(process.stdin.as_mut()?, &account_request) { + return None; + } + let account = receive_response(&responses, 2, deadline)?; + if account + .get("account") + .and_then(|account| account.get("type")) + .and_then(Value::as_str) + != Some("chatgpt") + { + return None; + } + + let rate_limits_request = json!({ + "id": 3, + "method": "account/rateLimits/read" + }); + if !send_message(process.stdin.as_mut()?, &rate_limits_request) { + return None; + } + let rate_limits = receive_response(&responses, 3, deadline)?; + map_rate_limits(&rate_limits) +} + +/// Ensure the direct child is closed and reaped on every return path. +struct ManagedChild { + child: Child, + stdin: Option, +} + +impl ManagedChild { + fn new(child: Child) -> Self { + Self { child, stdin: None } + } +} + +impl Drop for ManagedChild { + fn drop(&mut self) { + // Closing stdin lets a well-behaved server observe EOF before it is + // terminated. kill + wait also handles a server that ignores EOF. + self.stdin.take(); + let _ = self.child.kill(); + let _ = self.child.wait(); + } +} + +/// Drain the child's stderr without retaining its contents. +fn drain_stderr(stderr: ChildStderr) -> io::Result<()> { + thread::Builder::new() + .name("eggpass-codex-stderr".to_string()) + .spawn(move || { + let mut stderr = stderr; + let mut buffer = [0_u8; 8192]; + loop { + match stderr.read(&mut buffer) { + Ok(0) | Err(_) => break, + Ok(_) => {} + } + } + }) + .map(|_| ()) +} + +/// Start a bounded stdout reader; protocol bytes never accumulate unboundedly. +fn spawn_stdout_reader(stdout: std::process::ChildStdout) -> Option, ()>>> { + let (sender, receiver) = mpsc::sync_channel(QUEUED_LINES); + thread::Builder::new() + .name("eggpass-codex-stdout".to_string()) + .spawn(move || read_stdout_lines(stdout, sender)) + .ok()?; + Some(receiver) +} + +fn read_stdout_lines(stdout: std::process::ChildStdout, sender: SyncSender, ()>>) { + let mut reader = BufReader::new(stdout); + let mut total_bytes = 0_usize; + loop { + match read_bounded_line(&mut reader, MAX_LINE_BYTES) { + Ok(Some(line)) => { + total_bytes = match total_bytes.checked_add(line.len().saturating_add(1)) { + Some(total) if total <= MAX_STDOUT_BYTES => total, + _ => { + let _ = sender.send(Err(())); + break; + } + }; + if sender.send(Ok(line)).is_err() { + break; + } + } + Ok(None) => break, + Err(_) => { + let _ = sender.try_send(Err(())); + break; + } + } + } +} + +/// Read one newline-terminated record without allowing it to exceed `limit`. +fn read_bounded_line(reader: &mut impl BufRead, limit: usize) -> io::Result>> { + let mut line = Vec::new(); + loop { + let available = reader.fill_buf()?; + if available.is_empty() { + if line.is_empty() { + return Ok(None); + } + return Err(io::Error::new( + io::ErrorKind::UnexpectedEof, + "unterminated JSONL record", + )); + } + + let newline = available.iter().position(|byte| *byte == b'\n'); + let consumed = newline.map_or(available.len(), |index| index + 1); + let content_len = newline.map_or(consumed, |index| index); + if line + .len() + .checked_add(content_len) + .is_none_or(|length| length > limit) + { + return Err(io::Error::new( + io::ErrorKind::InvalidData, + "JSONL record exceeds the limit", + )); + } + line.extend_from_slice(&available[..content_len]); + reader.consume(consumed); + if newline.is_some() { + return Ok(Some(line)); + } + } +} + +fn send_message(stdin: &mut ChildStdin, message: &Value) -> bool { + serde_json::to_vec(message).ok().is_some_and(|message| { + stdin.write_all(&message).is_ok() && stdin.write_all(b"\n").is_ok() && stdin.flush().is_ok() + }) +} + +/// Read a response matching `id`; notifications and other response IDs are ignored. +fn receive_response( + responses: &Receiver, ()>>, + id: u64, + deadline: Instant, +) -> Option { + loop { + let remaining = deadline.saturating_duration_since(Instant::now()); + if remaining.is_zero() { + return None; + } + let line = responses.recv_timeout(remaining).ok()?.ok()?; + let value: Value = serde_json::from_slice(&line).ok()?; + let object = value.as_object()?; + + let Some(response_id) = object.get("id") else { + // A JSON-RPC notification has a method and no id. Other id-less + // objects are malformed and cannot be a useful response. + if object.get("method").and_then(Value::as_str).is_some() { + continue; + } + return None; + }; + if response_id != &Value::from(id) { + continue; + } + if object.contains_key("error") { + return None; + } + return object.get("result").cloned(); + } +} + +/// Convert the documented rate-limit result without inventing missing values. +fn map_rate_limits(result: &Value) -> Option { + let mut windows = Vec::new(); + let buckets = result + .get("rateLimitsByLimitId") + .and_then(Value::as_object) + .filter(|buckets| !buckets.is_empty()); + + if let Some(buckets) = buckets { + for (bucket_id, snapshot) in buckets { + append_snapshot_windows(&mut windows, snapshot, Some(bucket_id)); + } + } else if let Some(snapshot) = result.get("rateLimits") { + append_snapshot_windows(&mut windows, snapshot, None); + } + + if windows.is_empty() { + return None; + } + + Some(UsageReport { + provider: ProviderId::OpenAi, + plan: None, + windows, + breakdown: Vec::new(), + credits: None, + state: None, + }) +} + +fn append_snapshot_windows( + windows: &mut Vec, + snapshot: &Value, + bucket_id: Option<&str>, +) { + for (field, role) in [("primary", "Primary"), ("secondary", "Secondary")] { + let Some(window) = snapshot.get(field).filter(|window| window.is_object()) else { + continue; + }; + let used_percent = window + .get("usedPercent") + .and_then(Value::as_f64) + .filter(|percent| percent.is_finite() && (0.0..=100.0).contains(percent)); + let resets_at = window.get("resetsAt").and_then(Value::as_i64); + let duration_secs = window + .get("windowDurationMins") + .and_then(Value::as_i64) + .filter(|minutes| *minutes >= 0) + .and_then(|minutes| minutes.checked_mul(60)); + + // A window with no usable quota fields is not a zero-usage report. + if used_percent.is_none() && resets_at.is_none() && duration_secs.is_none() { + continue; + } + + let label = match bucket_id { + Some(bucket_id) => format!("{} {role}", safe_bucket_id(bucket_id)), + None => role.to_string(), + }; + windows.push(QuotaWindow { + label: WindowLabel::Other(label), + used_percent, + resets_at, + duration_secs, + }); + } +} + +/// Escape control and non-ASCII bucket-id bytes before they reach terminal output. +fn safe_bucket_id(bucket_id: &str) -> String { + let mut safe = String::new(); + for byte in bucket_id.bytes() { + if byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'_' | b'-') { + safe.push(char::from(byte)); + } else { + use std::fmt::Write as _; + let _ = write!(safe, "%{byte:02X}"); + } + if safe.len() >= 64 { + safe.truncate(64); + safe.push_str("..."); + break; + } + } + if safe.is_empty() { + "unknown".to_string() + } else { + safe + } +} + +#[cfg(test)] +fn executable_command(executable: &OsStr) -> Command { + let mut command = Command::new(executable); + command.arg("app-server"); + command +} + +#[cfg(test)] +mod tests { + use super::*; + use std::path::PathBuf; + use std::sync::OnceLock; + + static FAKE_SERVER: OnceLock<(tempfile::TempDir, PathBuf)> = OnceLock::new(); + + fn fake_server() -> &'static PathBuf { + let (_, executable) = FAKE_SERVER.get_or_init(|| { + let directory = tempfile::tempdir().expect("temporary fake-server directory"); + let source = PathBuf::from(env!("CARGO_MANIFEST_DIR")) + .join("tests/fixtures/codex_app_server.rs"); + let executable = directory.path().join(if cfg!(windows) { + "fake-codex.exe" + } else { + "fake-codex" + }); + let output = Command::new("rustc") + .arg("--edition=2024") + .arg(source) + .arg("-o") + .arg(&executable) + .output() + .expect("rustc is available while running Cargo tests"); + assert!( + output.status.success(), + "fake app-server failed to compile: {}", + String::from_utf8_lossy(&output.stderr) + ); + (directory, executable) + }); + executable + } + + fn fake_command(mode: &str) -> Command { + let mut command = executable_command(fake_server().as_os_str()); + command.env("EGGPASS_CODEX_TEST_MODE", mode); + command + } + + fn collect_fake_with_timeout(mode: &str, timeout: Duration) -> Option { + collect_with_command(fake_command(mode), timeout) + } + + fn collect_fake(mode: &str) -> Option { + collect_fake_with_timeout(mode, Duration::from_secs(2)) + } + + #[test] + fn account_rpc_flow_uses_only_read_methods_and_chatgpt_mode() { + let report = collect_fake("success").expect("the fake account has quota data"); + assert_eq!(report.provider, ProviderId::OpenAi); + assert_eq!(report.windows.len(), 2); + assert_eq!(report.windows[0].used_percent, Some(42.0)); + let serialized = serde_json::to_string(&report).unwrap(); + assert!(!serialized.contains("private-codex-account@example.invalid")); + + let stderr_report = collect_fake("stderr").expect("stderr does not break protocol reads"); + let stderr_report = serde_json::to_string(&stderr_report).unwrap(); + assert!(!stderr_report.contains("do-not-print-this-private-diagnostic")); + } + + #[test] + fn a_burst_of_unrelated_notifications_does_not_hide_the_matching_response() { + let report = collect_fake("notification_burst") + .expect("the bounded reader must backpressure rather than drop notifications"); + assert_eq!(report.windows.len(), 2); + } + + #[test] + fn account_modes_without_chatgpt_usage_are_unavailable() { + for mode in ["no_account", "api_key", "other_account"] { + assert!(collect_fake(mode).is_none(), "mode {mode} must not be used"); + } + } + + #[test] + fn missing_executable_and_spawn_failure_are_optional() { + let missing = tempfile::tempdir().unwrap().path().join("missing-codex"); + assert!( + collect_with_command( + executable_command(missing.as_os_str()), + Duration::from_millis(100) + ) + .is_none() + ); + } + + #[test] + fn early_exit_rpc_errors_and_malformed_output_are_optional() { + for mode in [ + "early_exit", + "initialize_error", + "account_error", + "rate_limits_error", + "malformed", + "oversized", + "stdout_total", + ] { + assert!(collect_fake(mode).is_none(), "mode {mode} must fall back"); + } + } + + #[test] + fn a_stalled_or_mismatched_rpc_cannot_hold_usage_open() { + for mode in [ + "stall_initialize", + "stall_account", + "stall_rate_limits", + "wrong_id", + "missing_id", + ] { + let started = Instant::now(); + assert!( + collect_fake_with_timeout(mode, Duration::from_millis(200)).is_none(), + "mode {mode} must fall back" + ); + assert!( + started.elapsed() < Duration::from_secs(3), + "mode {mode} exceeded the deadline" + ); + } + } + + #[test] + fn a_populated_bucket_map_is_preferred_and_keeps_all_windows() { + let report = collect_fake("multiple_buckets").expect("the map has quota data"); + assert_eq!(report.windows.len(), 3); + let labels: Vec<_> = report + .windows + .iter() + .map(|window| window.label.display()) + .collect(); + assert_eq!( + labels, + ["codex Primary", "codex Secondary", "other-model Primary"] + ); + assert_eq!(report.windows[0].used_percent, Some(42.0)); + assert_eq!(report.windows[0].resets_at, Some(1_800_000_000)); + assert_eq!(report.windows[0].duration_secs, Some(18_000)); + assert!( + !report + .windows + .iter() + .any(|window| window.used_percent == Some(99.0)) + ); + } + + #[test] + fn legacy_and_empty_bucket_map_results_are_supported() { + for mode in ["legacy", "empty_buckets"] { + let report = collect_fake(mode).expect("legacy quota data is available"); + assert_eq!(report.windows.len(), 1); + assert_eq!(report.windows[0].label.display(), "Primary"); + assert_eq!(report.windows[0].used_percent, Some(9.0)); + } + } + + #[test] + fn null_and_missing_fields_stay_unavailable_instead_of_becoming_zero() { + let report = collect_fake("nullable_fields").expect("a real zero percentage is usable"); + assert_eq!(report.windows.len(), 1); + assert_eq!(report.windows[0].used_percent, Some(0.0)); + assert_eq!(report.windows[0].duration_secs, Some(300)); + assert_eq!(report.windows[0].resets_at, None); + + assert!(collect_fake("no_data").is_none()); + } + + #[test] + fn unknown_plan_and_limit_states_do_not_masquerade_as_generic_states() { + let report = collect_fake("unknown_variants").expect("the quota window is usable"); + assert_eq!(report.plan, None); + assert_eq!(report.state, None); + } + + #[test] + fn invalid_values_are_ignored_and_duration_conversion_is_checked() { + let invalid_percent = json!({ + "rateLimits": { "primary": { "usedPercent": 150, "resetsAt": 1_800_000_000 } } + }); + let report = map_rate_limits(&invalid_percent).expect("the reset is still useful"); + assert_eq!(report.windows[0].used_percent, None); + assert_eq!(report.windows[0].resets_at, Some(1_800_000_000)); + + let overflow = json!({ + "rateLimits": { "primary": { "usedPercent": null, "windowDurationMins": i64::MAX } } + }); + assert!(map_rate_limits(&overflow).is_none()); + } + + #[test] + fn bucket_ids_cannot_inject_terminal_control_sequences() { + let result = json!({ + "rateLimitsByLimitId": { + "codex\u{1b}[31m": { "primary": { "usedPercent": 10 } } + } + }); + let report = map_rate_limits(&result).unwrap(); + assert_eq!(report.windows[0].label.display(), "codex%1B%5B31m Primary"); + } + + #[test] + fn each_jsonl_record_is_bounded_and_must_be_terminated() { + assert!(read_bounded_line(&mut BufReader::new(&b"12345\n"[..]), 4).is_err()); + assert!(read_bounded_line(&mut BufReader::new(&b"unterminated"[..]), 20).is_err()); + assert_eq!( + read_bounded_line(&mut BufReader::new(&b"{}\n"[..]), 2).unwrap(), + Some(b"{}".to_vec()) + ); + } + + #[test] + fn notification_records_are_ignored_until_the_matching_id_arrives() { + let (sender, receiver) = mpsc::channel(); + sender + .send(Ok(br#"{"method":"account/updated"}"#.to_vec())) + .unwrap(); + sender + .send(Ok(br#"{"id":99,"result":{}}"#.to_vec())) + .unwrap(); + sender + .send(Ok(br#"{"id":1,"result":{"ready":true}}"#.to_vec())) + .unwrap(); + let result = receive_response(&receiver, 1, Instant::now() + Duration::from_secs(1)); + assert_eq!(result, Some(json!({"ready": true}))); + } + + #[test] + fn source_label_does_not_expose_the_account_identity() { + assert!(SOURCE_LABEL.contains("Codex app-server")); + assert!(SOURCE_LABEL.contains("may differ from Eggpass inference account")); + assert!(!SOURCE_LABEL.contains('@')); + } +} diff --git a/src/provider/usage/mod.rs b/src/provider/usage/mod.rs index be86db0..15ca8b5 100644 --- a/src/provider/usage/mod.rs +++ b/src/provider/usage/mod.rs @@ -22,6 +22,7 @@ //! truth is "the provider did not say". Every percentage is therefore an //! [`Option`], and there is no `unwrap_or(0.0)` anywhere on this path. +pub mod codex_app_server; pub mod openai; pub mod xai; diff --git a/src/provider/usage/openai.rs b/src/provider/usage/openai.rs index 7a64610..77adb4b 100644 --- a/src/provider/usage/openai.rs +++ b/src/provider/usage/openai.rs @@ -1,22 +1,10 @@ -//! The ChatGPT usage collector. +//! The Sign in with ChatGPT (SIWC) usage fallback. //! -//! ChatGPT has no usable quota endpoint for a Sign in with ChatGPT -//! credential, and that is not a gap in this implementation — it is the -//! documented shape of the thing. -//! -//! The Codex app-server does expose `account/rateLimits/read`, and the -//! response shape is exactly right: `usedPercent` is an integer 0–100, -//! `resetsAt` is unix seconds, `planType` enumerates the plans. But the -//! app-server reads a *Codex-managed* ChatGPT login out of -//! `$CODEX_HOME/auth.json`, and behind that call it reaches a private, -//! undocumented consumer backend, `chatgpt.com/backend-api/wham/usage`, which -//! needs a `chatgpt-account-id` header. A Sign in with ChatGPT credential -//! carries no workspace id, and there is no documented way to read one out of -//! it: the SIWC documentation says plainly that *"Email and `sub` are not -//! workspace identifiers"* — the workspace is bound server-side to the issued -//! client id. Refreshing there would break as well, because Codex refreshes -//! with its own client id and a foreign refresh token does not refresh -//! there. +//! The optional Codex app-server source is queried separately by +//! [`super::codex_app_server`]. This collector describes only what Eggpass's +//! own SIWC credential can report: the SIWC API does not expose quota windows, +//! so the honest fallback is an unavailable result with the provider's +//! documented signals and usage page. //! //! The SIWC documentation enumerates every endpoint it defines, and none of //! them returns quota. The only quota signals it publishes are error codes, diff --git a/tests/fixtures/codex_app_server.rs b/tests/fixtures/codex_app_server.rs new file mode 100644 index 0000000..ed8d418 --- /dev/null +++ b/tests/fixtures/codex_app_server.rs @@ -0,0 +1,196 @@ +use std::io::{self, BufRead, Write}; +use std::thread; +use std::time::Duration; + +fn main() { + let mode = std::env::var("EGGPASS_CODEX_TEST_MODE").unwrap_or_default(); + let stdin = io::stdin(); + let mut stdout = io::stdout().lock(); + let mut stage = 0_u8; + + for line in stdin.lock().lines() { + let Ok(line) = line else { return }; + let method = if line.contains("\"method\":\"initialize\"") { + Some("initialize") + } else if line.contains("\"method\":\"initialized\"") { + Some("initialized") + } else if line.contains("\"method\":\"account/read\"") { + Some("account/read") + } else if line.contains("\"method\":\"account/rateLimits/read\"") { + Some("account/rateLimits/read") + } else { + None + }; + let Some(method) = method else { return }; + + if mode == "early_exit" { + return; + } + if mode == "stall_initialize" && method == "initialize" { + thread::sleep(Duration::from_secs(30)); + return; + } + if mode == "stall_account" && method == "account/read" { + thread::sleep(Duration::from_secs(30)); + return; + } + if mode == "stall_rate_limits" && method == "account/rateLimits/read" { + thread::sleep(Duration::from_secs(30)); + return; + } + + match method { + "initialize" => { + if stage != 0 + || !line.contains("\"name\":\"eggpass\"") + || !line.contains("\"version\":") + || line.contains("\"experimentalApi\":true") + { + send_error(&mut stdout, id(&line), "bad initialize request"); + return; + } + stage = 1; + if mode == "malformed" { + let _ = writeln!(stdout, "not-json"); + let _ = stdout.flush(); + return; + } + if mode == "oversized" { + let _ = writeln!(stdout, "{}", "x".repeat(300 * 1024)); + let _ = stdout.flush(); + return; + } + if mode == "stdout_total" { + let payload = "x".repeat(220 * 1024); + for _ in 0..5 { + let _ = writeln!( + stdout, + "{{\"method\":\"noise\",\"params\":{{\"data\":\"{payload}\"}}}}" + ); + } + let _ = stdout.flush(); + thread::sleep(Duration::from_secs(30)); + return; + } + if mode == "stderr" { + eprintln!("do-not-print-this-private-diagnostic"); + } + if mode == "initialize_error" { + send_error(&mut stdout, id(&line), "initialization failed"); + return; + } + if mode == "wrong_id" { + send_response( + &mut stdout, + Some(id(&line).unwrap_or(0) + 99), + "{\"ready\":true}", + ); + continue; + } + if mode == "missing_id" { + let _ = writeln!(stdout, "{{\"result\":{{\"ready\":true}}}}"); + let _ = stdout.flush(); + continue; + } + if mode == "notification_burst" { + for _ in 0..64 { + let _ = + writeln!(stdout, "{{\"method\":\"account/updated\",\"params\":{{}}}}"); + } + send_response(&mut stdout, id(&line), "{\"ready\":true}"); + continue; + } + let _ = writeln!(stdout, "{{\"method\":\"account/updated\",\"params\":{{}}}}"); + send_response(&mut stdout, id(&line), "{\"ready\":true}"); + } + "initialized" => { + if stage != 1 { + return; + } + stage = 2; + } + "account/read" => { + if stage != 2 || !line.contains("\"refreshToken\":false") { + send_error(&mut stdout, id(&line), "bad account request"); + return; + } + stage = 3; + if mode == "account_error" { + send_error(&mut stdout, id(&line), "account read failed"); + return; + } + let account = match mode.as_str() { + "no_account" => "null", + "api_key" => "{\"type\":\"apiKey\"}", + "other_account" => "{\"type\":\"gcp\"}", + _ => { + "{\"type\":\"chatgpt\",\"email\":\"private-codex-account@example.invalid\"}" + } + }; + send_response( + &mut stdout, + id(&line), + &format!("{{\"account\":{account}}}"), + ); + } + "account/rateLimits/read" => { + if stage != 3 { + send_error(&mut stdout, id(&line), "bad rate-limits request"); + return; + } + if mode == "rate_limits_error" { + send_error(&mut stdout, id(&line), "rate limits read failed"); + return; + } + let result = rate_limits(&mode); + send_response(&mut stdout, id(&line), result); + return; + } + _ => return, + } + } +} + +fn id(line: &str) -> Option { + let tail = line.split_once("\"id\":")?.1; + let digits: String = tail.chars().take_while(char::is_ascii_digit).collect(); + digits.parse().ok() +} + +fn send_response(stdout: &mut impl Write, id: Option, result: &str) { + let Some(id) = id else { return }; + let _ = writeln!(stdout, "{{\"id\":{id},\"result\":{result}}}"); + let _ = stdout.flush(); +} + +fn send_error(stdout: &mut impl Write, id: Option, message: &str) { + let Some(id) = id else { return }; + let _ = writeln!( + stdout, + "{{\"id\":{id},\"error\":{{\"code\":-32000,\"message\":\"{message}\"}}}}" + ); + let _ = stdout.flush(); +} + +fn rate_limits(mode: &str) -> &'static str { + match mode { + "multiple_buckets" => { + r#"{"rateLimitsByLimitId":{"codex":{"primary":{"usedPercent":42,"windowDurationMins":300,"resetsAt":1800000000},"secondary":{"usedPercent":0,"windowDurationMins":10080,"resetsAt":1801000000},"planType":"future_plan","rateLimitReachedType":"workspace_owner_credits_depleted"},"other-model":{"primary":{"usedPercent":25}}},"rateLimits":{"primary":{"usedPercent":99}}}"# + } + "legacy" | "empty_buckets" => { + r#"{"rateLimitsByLimitId":{},"rateLimits":{"primary":{"usedPercent":9,"windowDurationMins":60,"resetsAt":1800000000}}}"# + } + "nullable_fields" => { + r#"{"rateLimitsByLimitId":{"codex":{"primary":{"usedPercent":null,"windowDurationMins":null,"resetsAt":null},"secondary":{"usedPercent":0,"windowDurationMins":5}},"empty":{"primary":{"usedPercent":null,"windowDurationMins":null,"resetsAt":null}}}}"# + } + "no_data" => { + r#"{"rateLimitsByLimitId":{},"rateLimits":{"primary":{"usedPercent":null,"windowDurationMins":null,"resetsAt":null}}}"# + } + "unknown_variants" => { + r#"{"rateLimits":{"primary":{"usedPercent":12,"planType":"future_plan","rateLimitReachedType":"workspace_member_credits_depleted"}}}"# + } + _ => { + r#"{"rateLimits":{"primary":{"usedPercent":42,"windowDurationMins":300,"resetsAt":1800000000},"secondary":{"usedPercent":7,"windowDurationMins":10080,"resetsAt":1801000000}}}"# + } + } +} From cac185dad194fb3b05d15719bf89f55f282f6146 Mon Sep 17 00:00:00 2001 From: dbowm91 Date: Tue, 17 Nov 2026 19:04:38 +0000 Subject: [PATCH 2/7] fix: satisfy latest Clippy in Codex usage reader --- src/provider/usage/codex_app_server.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/provider/usage/codex_app_server.rs b/src/provider/usage/codex_app_server.rs index 25a4b89..46ca086 100644 --- a/src/provider/usage/codex_app_server.rs +++ b/src/provider/usage/codex_app_server.rs @@ -200,7 +200,7 @@ fn read_bounded_line(reader: &mut impl BufRead, limit: usize) -> io::Result Date: Wed, 18 Nov 2026 19:49:34 +0000 Subject: [PATCH 3/7] feat: add cached daemon usage API --- docs/commands.md | 10 +- docs/configuration.md | 2 +- docs/how-it-works.md | 8 +- plans/daemon-usage-api-implementation.md | 129 ++++ src/cli/commands/run.rs | 33 +- src/cli/commands/usage.rs | 151 +++-- src/provider/mod.rs | 8 - src/provider/usage/codex_app_server.rs | 23 +- src/provider/usage/mod.rs | 23 +- src/provider/usage/openai.rs | 13 +- src/provider/usage/report.rs | 173 +++++ src/provider/usage/xai.rs | 145 +++-- src/server/chat.rs | 2 +- src/server/mod.rs | 18 +- src/server/models.rs | 2 +- src/server/router.rs | 5 + src/server/tests.rs | 170 ++++- src/server/usage.rs | 769 +++++++++++++++++++++++ 18 files changed, 1506 insertions(+), 178 deletions(-) create mode 100644 plans/daemon-usage-api-implementation.md create mode 100644 src/provider/usage/report.rs create mode 100644 src/server/usage.rs diff --git a/docs/commands.md b/docs/commands.md index e519921..a714334 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -66,10 +66,18 @@ eggpass usage --provider xai # query one provider eggpass usage --json # machine-readable report ``` -Queries provider usage directly, without needing the daemon. This is a fresh request, not a cached or polled reading. Human-readable output shows the percentage and bar for the allowance left, plus each available reset time and countdown; JSON preserves the provider-reported fields. On the default xAI `api` upstream, the reported consumer-subscription quota is separate from inference requests, which are billed to the xAI API tier. The report's caption reflects the configured upstream. If quota is unavailable, the report may include the latest inference HTTP status kept by the daemon in memory. That endpoint reports only per-provider client-facing HTTP status codes, not prompts or response bodies. +Queries provider usage directly, without needing the daemon. By default it queries only providers enabled in configuration. `--provider` can select one enabled provider; selecting a disabled provider, or running the command when none are enabled, returns an actionable configuration error. Human-readable output shows the percentage and bar for the allowance left, plus each available reset time and countdown; JSON preserves the provider-reported fields. On the default xAI `api` upstream, the reported consumer-subscription quota is separate from inference requests, which are billed to the xAI API tier. The report's caption reflects the configured upstream. If quota is unavailable, the report may include the latest inference HTTP status kept by the daemon in memory. That endpoint reports only per-provider client-facing HTTP status codes, not prompts or response bodies. **Exit codes:** `0` if at least one provider is signed in and not every selected provider failed operationally, `1` if every selected provider failed operationally, `2` if none is signed in. +### Authenticated daemon endpoint: GET /v1/usage + +The daemon also serves `GET /v1/usage` for clients that need a usage report over HTTP. Send the configured or issued Eggpass client key in `Authorization: Bearer ` or `X-Api-Key: `. The response body uses the same `{"providers":[...]}` JSON structure as `eggpass usage --json`; it includes only enabled providers. If every provider is disabled, the endpoint returns a completed empty list. OpenAI/ChatGPT usage is queried only when that provider is enabled; the optional Codex app-server result may describe a different account from Eggpass's inference credential. + +A complete report is retained only in daemon memory for 600 seconds from completion. Cache hits do not contact providers. A cold or expired request starts one shared refresh and its initiating client waits at most 30 seconds; if still running, that client receives `504` and the refresh continues. Other requests while it is active receive `202` with `Retry-After`. Timed-out providers alone are retried, for at most three retries after the initial attempt, spaced 5, 15, and 30 seconds apart. xAI usage HTTP requests have bounded 15-second request/body timeouts (and a 5-second connect cap); OAuth refresh requests have a 60-second total deadline, and the optional local Codex session has an 8-second deadline. + +On success, responses include `Cache-Control: private, no-store`, `X-Eggpass-Usage-Age` (integer seconds), and `X-Eggpass-Usage-Updated-At` (RFC 3339 UTC). `last_inference` is attached from the daemon's current in-memory state on each response. After all timeout retries fail, the last successful report is returned with `X-Eggpass-Usage-Stale: true` during a 600-second cooldown; if no successful report exists, the endpoint returns `503` with `Retry-After`. A process restart clears the snapshot and cooldown. There is no polling, disk persistence, or force-refresh operation. + ## `run`, `stop`, and `restart` ```sh diff --git a/docs/configuration.md b/docs/configuration.md index b3251a1..5b8d3ed 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -74,7 +74,7 @@ The advanced `[oauth.xai]` settings are `client_id`, `issuer`, `scopes`, and `re A client key is required to start the server, including when it listens only on loopback. Use `eggpass key add` to create a numbered, revocable key, or set `api_key` for one static key. The static key is readable in the config. Issued keys are shown once and stored as salted hashes. Clients may send either as `Authorization: Bearer ` or `X-Api-Key: `. -The server listens on loopback by default. Binding to a non-loopback address exposes the proxy and the provider accounts it can use to the network. A key is required for that bind. The `GET /health` and `GET /v1/last-inference` probes are unauthenticated: health returns a JSON object with `status`, `service`, and a version string; last-inference returns only per-provider client-facing HTTP status codes. All other API requests require a valid key. +The server listens on loopback by default. Binding to a non-loopback address exposes the proxy and the provider accounts it can use to the network. A key is required for that bind. The `GET /health` and `GET /v1/last-inference` probes are unauthenticated: health returns a JSON object with `status`, `service`, and a version string; last-inference returns only per-provider client-facing HTTP status codes. `GET /v1/usage` is not an unauthenticated probe: it requires a valid Eggpass client key like every other data endpoint. It returns quota data for enabled providers, so do not expose it without protecting the server. Eggpass runs locally, but inference requests are sent to the provider selected by routing. Prompts and request content are transmitted to xAI or ChatGPT for inference; they do not stay on this machine. `eggpass usage` also contacts providers directly to query usage, and `eggpass status` may contact them to count available models. diff --git a/docs/how-it-works.md b/docs/how-it-works.md index 518a5b7..acca352 100644 --- a/docs/how-it-works.md +++ b/docs/how-it-works.md @@ -73,11 +73,9 @@ Streaming responses are forwarded as chunks arrive. The proxy does not buffer the full answer before sending it to the client. Provider errors keep their status codes and error details where supported. -The `eggpass usage` command fetches current usage where a provider exposes it. -For ChatGPT, the OAuth flow has no quota endpoint, so the command reports usage -as unavailable rather than estimating it. The daemon keeps only the most recent -client-facing inference status for each provider in memory. It is not written -to a file and disappears when the daemon stops. +The `eggpass usage` command fetches current usage where a provider exposes it, and both it and the daemon endpoint query only providers enabled in configuration. For ChatGPT, the OAuth flow has no quota endpoint, so usage is unavailable rather than estimated; when OpenAI is enabled, the optional local Codex app-server may provide a report from a separate account. + +The authenticated `GET /v1/usage` endpoint returns the CLI-compatible JSON report. It caches one complete snapshot in memory for 10 minutes, starts at most one demand-triggered refresh, and never polls or writes usage data to disk. Its initiating request waits up to 30 seconds; if that deadline expires it gets `504` while the finite refresh continues. Concurrent requests get `202` with `Retry-After`. A refresh retries only timed-out providers, up to three times at 5/15/30-second intervals. Each xAI billing/settings request is capped at 15 seconds; OAuth refresh has a 60-second total deadline and Codex has an 8-second session deadline. Success adds age and update-time headers; after retry exhaustion, a previous successful snapshot is marked stale during a 10-minute cooldown, or `503` is returned if no good snapshot exists. A daemon restart clears the cache. The latest inference status is read afresh for every report response. ## Updates diff --git a/plans/daemon-usage-api-implementation.md b/plans/daemon-usage-api-implementation.md new file mode 100644 index 0000000..1256b6a --- /dev/null +++ b/plans/daemon-usage-api-implementation.md @@ -0,0 +1,129 @@ +# On-Demand Daemon Usage API — Implementation Plan + +**Status:** Implemented; final automated checks and installed-binary smoke test passed. + +**Implementation and verification:** Added the authenticated in-memory usage API, enabled-provider reporting shared with the CLI, finite timeout retries, freshness metadata, tests, and endpoint documentation. `cargo fmt --all`, `cargo check --workspace --all-targets --locked`, `cargo test --workspace --all-targets --locked`, strict workspace Clippy, and `git diff --check` passed (368 Eggpass tests, 30 auth-crate tests, and 10 OAuth integration tests). Installed from this checkout with `cargo install --path . --locked --force`; `/Users/davidbowman/.cargo/bin/eggpass --version` reports `0.1.1`. An isolated installed-binary smoke test verified unauthenticated `401`, authenticated `200` with `{"providers":[]}` when both providers are disabled, `Cache-Control`/age/update headers, and reuse of the cached timestamp. The smoke test made no live provider calls. + +**Research checked:** 2026-11-18 against the current `eggpass` source and docs. + +**Scope:** Add an authenticated daemon endpoint that returns the same machine-readable usage report as `eggpass usage --json`, with both paths collecting only providers enabled in configuration. Collect only when requested, retain one recent report in daemon memory for a 10-minute TTL, and allow only a finite, demand-triggered background retry job after a client wait timeout; no scheduled/background polling or file persistence. + +## Goal + +Provide Gregg and other authorized clients a stable JSON usage endpoint without letting frequent polling cause frequent provider queries. For a given cache snapshot, requests inside the TTL reuse the same report. Once it is absent or expired, one request triggers a refresh; concurrent misses share that refresh. The cache disappears on daemon shutdown/restart. + +The initial endpoint is proposed as `GET /v1/usage`. It must not expose provider credentials, account email, or raw upstream payloads. + +## Repository baseline and implementation seams + +- `src/cli/commands/usage.rs:127-180` currently builds a report for all `ProviderId`s by default, adds each provider's source/caption and last-inference status, then prints either human-readable text or JSON. The JSON wrapper is `{"providers":[...]}`. The CLI's `ProviderEntry` and `UsageReportJson` types and collection functions are private (`src/cli/commands/usage.rs:211-299`). The selected behavior is to change the CLI and API collection to include only providers enabled in configuration. +- The serialized provider outcomes are already structured and reusable: `ProviderUsage` has `reported`, `not_signed_in`, `unavailable`, and `failed` states, and `UsageReport` carries normalized windows, breakdown, credits, and state (`src/provider/usage/mod.rs:33-48,162-193`). xAI's caption explains which billing pool the numbers represent. +- xAI collection calls the billing endpoint, then best-effort fetches settings for the plan name (`src/provider/usage/xai.rs:71-153,188-206`). Those requests use the configured provider timeouts. The defaults allow up to 30 minutes for the global/body timeout (`src/config.rs:252-274`; `src/upstream.rs:138-148`). +- OpenAI usage first tries the local `codex app-server`, then falls back to the Eggpass Sign in with ChatGPT collector (`src/cli/commands/usage.rs:252-282`). The Codex helper has an eight-second session deadline (`src/provider/usage/codex_app_server.rs:21-38`). The SIWC fallback does not query quota; it returns an explicit unavailable result (`src/provider/usage/openai.rs:45-61`). A daemon using this path needs `codex` available on its `PATH` to return the optional Codex result, and that account may differ from the Eggpass inference account. +- The daemon already keeps last inference statuses in memory (`src/server/mod.rs:89-94`, `src/inference.rs:10-35`) and serves them at `/v1/last-inference` (`src/server/inference.rs:19-27`). +- Routes are added in `src/server/router.rs:5-45`; request routing and authorization are in `src/server/mod.rs:231-335`. Only `/health` and `/v1/last-inference` are exempt from API-key authorization. The authority guard remains active for them as well (`src/server/guard.rs:20-48`). The HTTP server handles connections on separate threads (`src/server/http.rs:197-245`). +- `ServerContext` currently has no usage cache, full config, or paths (`src/server/mod.rs:60-94`). The daemon creates `ProviderHandle`s only for enabled providers (`src/cli/commands/run.rs:198-215`), while the CLI usage command currently iterates all providers. The selected behavior is to change the CLI to use the daemon's enabled-provider scope; when OpenAI/ChatGPT is disabled, do not invoke the optional Codex usage process. A shared collector must not create independent `TokenManager`s for enabled providers: separate refresh mutexes could race while rotating the same credentials. +- The historical shipped plan notes that `GET /v1/usage` was deferred when no reliable usage path existed (`plans/shipped-2026-11-13.md:161-163`). The CLI usage collectors now provide the report path this API can reuse. + +## Proposed first-release behavior + +1. **Route and methods:** Add `GET /v1/usage`. Existing path normalization means `/usage` also resolves consistently for clients whose base URL already ends in `/v1`. Other methods return the existing `405` response with `Allow: GET`. Treat this as a bodyless GET in the request-body gate (`src/server/mod.rs:240-249`). +2. **Authorization:** Require a valid Eggpass client key. Do not add this route to the unauthenticated probe exceptions. Reject unauthorized requests before consulting the cache or starting collection. Preserve the existing Host/authority guard. +3. **Response compatibility and provider scope:** Reuse the CLI JSON schema: top-level `providers` array, provider outcome/status, optional source, caption, and last-inference field. Change both the CLI and API to collect only providers enabled in configuration; omit disabled providers from the array and do not invoke Codex when OpenAI is disabled. Return HTTP 200 when a report is complete, including provider-level `failed`, `unavailable`, or `not_signed_in` outcomes. A request that reaches its refresh wait deadline before a report is ready returns a timeout response instead. +4. **Cache policy:** Keep one most-recent complete usage snapshot and its completion time in process memory, shared through `ServerContext`. Use `Instant` for expiry and a 600-second TTL from a completed collection; structured provider outcomes such as unavailable or non-timeout failures are still complete results. Do not persist the report or add a periodic polling task. A restart starts cold. +5. **Demand-triggered refresh and client deadline:** A cache miss/expiry starts one refresh job. The initiating request waits at most 30 seconds; if the refresh is still running, return an HTTP timeout to that client while allowing the already-started job to continue. Do not hold the cache mutex while provider calls or process startup run. No client timeout may start a duplicate job. +6. **Finite background retries:** If a provider collection times out, keep the same demand-triggered job alive and retry only that provider, up to three times after the initial attempt, with delays of 5, 15, and 30 seconds. Do not repeat successful provider collections. If retries succeed, atomically store the completed report and start its 600-second TTL then. This is a finite retry sequence, not scheduled/background polling. If the client wait expires, return 504; later requests during the active job return 202 with `Retry-After`. On exhaustion, preserve the last good report as stale and apply a 600-second cooldown; if no good report exists, return 503 with `Retry-After`. +7. **Last inference:** Attach the daemon's current `InferenceState` snapshot when serializing each response. The CLI obtains last-inference information afresh (`src/cli/commands/usage.rs:412-449`); caching the complete assembled JSON would make that field stale for up to ten minutes. +8. **Freshness and HTTP caching:** Keep the JSON body compatible and return `Cache-Control: private, no-store`. Add `X-Eggpass-Usage-Age` as integer seconds and `X-Eggpass-Usage-Updated-At` as an RFC 3339 UTC timestamp. Add `X-Eggpass-Usage-Stale: true` when returning a previously successful snapshot after refresh retries have been exhausted. +9. **Bounded collection:** Use a 30-second client wait deadline independent of the existing provider timeout defaults, which allow up to 30 minutes for an xAI request (`src/config.rs:252-274`; `src/upstream.rs:138-148`). The background retry job must also be finite and must not keep a request handler occupied after the client deadline. + +## User-selected decisions + +On 2026-11-18, the user selected: + +- **Provider scope:** Query only providers enabled in configuration. Change the CLI usage command to match the API; omit disabled providers from the `providers` array. If OpenAI/ChatGPT is disabled, do not invoke the Codex usage process. +- **Client wait deadline and retries:** Give a client at most 30 seconds to wait for a cache-miss/expired-cache refresh. If the response deadline expires, return a timeout to that client but continue the same finite refresh job in the background, with up to three spaced retries after a timeout. Store the result in memory if a retry succeeds. The retry job is demand-triggered and must not become periodic polling. +- **Freshness metadata:** Preserve the CLI-compatible JSON body and add `X-Eggpass-Usage-Age` (integer seconds) and `X-Eggpass-Usage-Updated-At` (RFC 3339 UTC timestamp) response headers. Also set `Cache-Control: private, no-store`. + +## Confirmed timeout/retry policy + +On 2026-11-18, the user selected the following details: + +- One initial attempt plus up to three retries (four attempts maximum), with retry delays of 5, 15, and 30 seconds. Retry only the provider whose collection timed out; do not repeat successful provider collections. +- The request that starts a cold/expired refresh waits up to 30 seconds, then returns HTTP 504 if the report is still being refreshed. The demand-triggered refresh job continues independently of that response. +- A later request while the same job is active returns HTTP 202 with `Retry-After`, rather than holding another request thread open or starting another refresh. +- If retries are exhausted, retain the previous successful report as stale and start an in-memory 600-second retry cooldown. Return the stale report with its age/update headers plus `X-Eggpass-Usage-Stale: true`. If no successful report exists, return HTTP 503 with `Retry-After` during the cooldown. + +The 600-second success-cache TTL begins when a new report is stored. The separate cooldown begins after the final failed attempt. Neither a timeout response nor a pending response writes to disk or starts periodic polling. + +## Implementation stages + +### Stage 0 — Confirm API and cache contract + +- Implement the selected `GET /v1/usage` contract: API-key authentication, enabled providers only in both CLI and API, 30-second client wait, finite timeout retries, freshness headers, and a 600-second in-memory success-cache TTL. +- Implement the confirmed retry count/spacing, 202 pending response, stale-snapshot, and 600-second cooldown behavior after retries are exhausted. +- Keep the implementation process-local and single-snapshot; no database, file, cross-process cache, or periodic refresh scheduler. + +**Exit:** The route, report provider set, freshness contract, retry lifecycle, failure behavior, and latency bounds are explicit. + +### Stage 1 — Extract reusable usage collection/report assembly + +- Move the serializable report DTO and provider collection/assembly logic out of the CLI-only private implementation into a shared usage service or provider-usage module. +- Preserve the CLI JSON schema, source labels, xAI caption, provider order, and Codex-first OpenAI behavior for providers enabled in configuration. +- Change the CLI's provider selection to filter by `config.providers.get(id).enabled`; disabled providers are omitted, and a disabled OpenAI provider must not start `codex app-server`. +- Provide daemon collection access to the necessary configuration and provider credentials without duplicating `TokenManager` refresh locks. +- Keep `last_inference` supplied from current daemon state at response time. + +**Exit:** CLI tests preserve the existing JSON/text formatting for enabled providers while explicitly covering the new disabled-provider filtering; the shared collector can be called from both CLI and daemon paths without live-account requirements in tests. + +### Stage 2 — Add the daemon route and TTL cache + +- Add the `Usage` route and `GET` dispatch; make it bodyless and subject to existing authority and client-key checks. +- Add a small cache state to the shared server context: optional last successful snapshot, monotonic completion time, one demand-triggered refresh job, in-progress coordination, and a retry cooldown. +- Implement cache-hit, cold-miss, expiry, single-flight, and 30-second client wait behavior. A timed-out client does not cancel the finite retry job; later requests while it is active receive `202` with `Retry-After`. Keep provider calls outside the cache lock and avoid logging report bodies or credentials. +- Preserve completed provider outcomes in the active refresh candidate and retry only timed-out providers, up to three retries after the initial attempt (5/15/30 seconds). Do not repeat successful provider collections. Commit the complete candidate atomically on success; after exhaustion, retain the last complete report as stale with a 600-second cooldown, or return `503` with `Retry-After` if no good report exists. Set `Retry-After` to the next scheduled retry or the remaining cooldown, as applicable. + +- Serialize the shared report in the existing schema and add `Cache-Control: private, no-store`, age/update headers, and a stale marker on stale responses. + +**Exit:** Fresh requests are served from memory; a miss starts one finite refresh job; concurrent misses do not duplicate provider calls; the 504/202/stale/503 behavior is implemented; no periodic refresh or disk activity is introduced. + +### Stage 3 — Test behavior without live provider calls + +- Unit-test the cache/refresh worker with an injected collector and controllable clock: cold miss, fresh hit, expiry, 30-second caller timeout without job cancellation, spaced retries, single-flight across concurrent callers, success timestamp/TTL, retry exhaustion, and empty cache after a new daemon instance. +- Extend server integration tests for path routing, `GET`/405 behavior, bodyless handling, required key, Host guard, JSON shape, freshness headers, 202/504/503 responses and `Retry-After`, and no collection on unauthorized requests. +- Use fake upstream/collector seams to assert the number of billing/settings requests across cold, fresh, timeout, retry, and expired requests. Existing xAI collection uses hard-coded live endpoints, so provide injection for tests instead of calling those endpoints. +- Cover OpenAI's Codex success/fallback behavior using its existing fake-process pattern; assert that disabled OpenAI does not launch Codex and that no email, token, or raw upstream/process payload appears in the API body or logs. +- Verify `last_inference` freshness behavior, provider-level failure responses, CLI filtering to enabled providers, and preservation of the CLI JSON schema/format for enabled providers. Test 504 on the initial client deadline, 202 plus `Retry-After` while the shared job remains active, stale-data headers/cooldown after retry exhaustion, and 503 plus `Retry-After` when no prior report exists. + +**Exit:** Cache and route tests are deterministic, parallel expiry tests prove one refresh, and no test depends on a live account or external provider service. + +### Stage 4 — Document and review + +- Document the endpoint, response examples, key requirement, 10-minute report TTL, 30-second client wait, finite timeout-retry schedule, 202/504/503 behavior, freshness/stale headers, cooldown, restart behavior, and the optional Codex account distinction. +- Update current endpoint and security references in `docs/configuration.md`, `docs/how-it-works.md`, `docs/commands.md`, and any maintained API route list. +- Run formatting, Clippy, workspace tests, relevant server/usage tests, and `git diff --check`; review the scoped diff and preserve unrelated worktree changes. + +**Exit:** API docs agree with route/auth behavior; checks pass; no unrelated changes are staged or overwritten. + +## Acceptance checklist + +- [x] `GET /v1/usage` returns the CLI-compatible `providers` JSON shape for enabled providers only. +- [x] The CLI also collects only providers enabled in configuration; disabled OpenAI never invokes Codex, and disabled providers are omitted from the report. +- [x] Route requires an Eggpass key and keeps the authority guard; unauthorized requests never collect usage. +- [x] A cold/expired request waits at most 30 seconds; on expiry the client receives 504 while the single refresh job continues. +- [x] Timed-out provider collections get at most three retries after the initial attempt, at 5/15/30-second spacing; only the timed-out provider is retried, and success stores the complete report with a 600-second TTL. +- [x] Later requests during an active refresh receive 202 with `Retry-After`; they neither block another server thread nor start duplicate upstream collection. +- [x] After exhausted retries, a previous report is returned as stale with age/update/stale headers during a 600-second cooldown; with no prior report, the API returns 503 with `Retry-After`. +- [x] Response headers expose age and update time; the body remains CLI-compatible and uses no-store HTTP caching. +- [x] Usage data exists only in daemon memory; there is no scheduled or open-ended polling, disk persistence, or forced-refresh endpoint. +- [x] Last-inference values are fresh per response. +- [x] Tests use controlled collectors/stubs; no live account/provider service is required. +- [x] CLI formatting/schema remains compatible for enabled providers; docs describe provider filtering, auth, cache/retry behavior, latency, headers, and Codex account sourcing. + +## Out of scope + +- Changing provider OAuth, inference, token storage, or the `eggpass usage` command's meaning. +- Periodic or open-ended provider polling, writing usage snapshots to files, or retaining usage history. A finite set of spaced retries is in scope only for a refresh already triggered by an API request. +- Adding a public unauthenticated usage route, force-refresh query parameter, or configurable TTL in the first version. +- Adding OpenAI quota support through undocumented ChatGPT endpoints; the existing SIWC fallback remains unavailable unless Codex app-server supplies a report. +- Inspecting or changing the `eggstack/gregg` repository as part of this daemon-only implementation plan. diff --git a/src/cli/commands/run.rs b/src/cli/commands/run.rs index 4c9085b..f03abed 100644 --- a/src/cli/commands/run.rs +++ b/src/cli/commands/run.rs @@ -210,7 +210,7 @@ fn serve(context: &Context) -> Result<(), CommandError> { ProviderHandle { spec: runtime.spec, upstream, - tokens: runtime.tokens, + tokens: std::sync::Arc::new(runtime.tokens), }, ); } @@ -229,6 +229,36 @@ fn serve(context: &Context) -> Result<(), CommandError> { .map_err(|err| CommandError::new(err.to_string()))?, ); + let usage_provider_ids: Vec = ProviderId::all() + .into_iter() + .filter(|provider| providers.contains_key(provider)) + .collect(); + let usage_tokens: HashMap> = + providers + .iter() + .map(|(provider, handle)| (*provider, std::sync::Arc::clone(&handle.tokens))) + .collect(); + let usage_xai_upstream = context.config.providers.xai.upstream; + let usage_timeouts = crate::provider::usage::report::bounded_timeouts(context.config.timeouts); + let usage_cache = std::sync::Arc::new(crate::server::usage::UsageCache::new( + usage_provider_ids, + move |provider| { + let tokens = usage_tokens + .get(&provider) + .expect("the usage provider is enabled in the daemon"); + let codex = (provider == ProviderId::OpenAi) + .then(crate::provider::usage::codex_app_server::collect_detailed); + crate::provider::usage::report::collect_entry( + provider, + usage_xai_upstream, + tokens, + usage_timeouts, + codex, + crate::provider::usage::xai::BILLING_BASE_URL, + ) + }, + )); + let server_context = Arc::new(ServerContext { host: context.config.host.clone(), port: context.config.port, @@ -242,6 +272,7 @@ fn serve(context: &Context) -> Result<(), CommandError> { // The status of the last inference to each provider, kept in memory // for `eggpass usage` to report. inferences: Arc::new(crate::inference::InferenceState::new()), + usage_cache, }); daemon::write_info( diff --git a/src/cli/commands/usage.rs b/src/cli/commands/usage.rs index 8bb2ee0..7d68345 100644 --- a/src/cli/commands/usage.rs +++ b/src/cli/commands/usage.rs @@ -24,10 +24,11 @@ use std::collections::{BTreeMap, BTreeSet}; use std::time::Duration; -use serde::Serialize; - use crate::cli::{CommandError, Context}; use crate::daemon::{self, DaemonState}; +#[cfg(test)] +use crate::provider::usage::report::codex_outcome; +use crate::provider::usage::report::{ProviderEntry, UsageReportJson, enabled_provider_ids}; use crate::provider::usage::{ProviderUsage, UsageReport, WindowLabel}; use crate::provider::{ProviderId, ProviderRuntime}; use crate::timeutil; @@ -56,10 +57,7 @@ pub fn usage( provider: Option, json: bool, ) -> Result<(), CommandError> { - let providers: Vec = match provider { - Some(provider) => vec![provider], - None => ProviderId::all().to_vec(), - }; + let providers = selected_provider_ids(provider, &context.config)?; // What the last inference to each provider was answered with. The daemon // keeps it in memory, so there is nothing to read when it is not @@ -102,6 +100,30 @@ pub fn usage( usage_exit_result(&entries) } +/// Resolve the CLI's explicit provider choice against the enabled-provider policy. +fn selected_provider_ids( + requested: Option, + config: &crate::config::Config, +) -> Result, CommandError> { + match requested { + Some(provider) if config.providers.get(provider).enabled => Ok(vec![provider]), + Some(provider) => Err(CommandError::new(format!( + "provider {} is disabled in configuration", + provider.as_str() + ))), + None => { + let enabled = enabled_provider_ids(config); + if enabled.is_empty() { + Err(CommandError::new( + "no providers are enabled in configuration", + )) + } else { + Ok(enabled) + } + } + } +} + /// Decide the command status after output has been rendered. fn usage_exit_result(entries: &[ProviderEntry]) -> Result<(), CommandError> { // A provider that is not signed in still gets a block, so the output does @@ -130,34 +152,6 @@ fn usage_exit_result(entries: &[ProviderEntry]) -> Result<(), CommandError> { Ok(()) } -/// One provider's answer, with the provider it belongs to. -#[derive(Serialize)] -struct ProviderEntry { - /// The provider. - provider: ProviderId, - /// What it had to say. - #[serde(flatten)] - outcome: ProviderUsage, - /// Which account or local source supplied the usage snapshot, when relevant. - #[serde(skip_serializing_if = "Option::is_none")] - source: Option<&'static str>, - /// Which pool the numbers belong to, when the provider reported any. - caption: Option, - /// The HTTP status the last inference to this provider was answered with. - /// - /// It is here for every provider, including the ones that reported a - /// quota: a machine-readable report should carry the facts, not only the - /// ones that happen to be printed. - last_inference: Option, -} - -/// The machine-readable form of the report. -#[derive(Serialize)] -struct UsageReportJson<'a> { - /// One entry per provider. - providers: &'a [ProviderEntry], -} - /// The note that says which pool a provider's numbers belong to. /// /// Only x.ai has one: the billing endpoint reports the consumer @@ -171,53 +165,45 @@ fn caption_for(provider: ProviderId, config: &crate::config::Config) -> Option (ProviderUsage, Option<&'static str>) { - let codex_report = (provider == ProviderId::OpenAi) - .then(crate::provider::usage::codex_app_server::collect) - .flatten(); - collect_one_with_codex_result(context, provider, codex_report) + let codex = (provider == ProviderId::OpenAi) + .then(crate::provider::usage::codex_app_server::collect_detailed); + collect_one_with_codex_collection(context, provider, codex) } -/// Apply an optional Codex report, otherwise run the existing token/collector path. +/// Compatibility wrapper used by the existing CLI collector tests. +#[cfg(test)] fn collect_one_with_codex_result( context: &Context, provider: ProviderId, codex_report: Option, ) -> (ProviderUsage, Option<&'static str>) { - if let Some(codex_usage) = codex_outcome(provider, codex_report) { - return codex_usage; - } - - let runtime = ProviderRuntime::new(provider, &context.config, &context.paths); - let outcome = match runtime.tokens.current() { - Ok(None) => ProviderUsage::NotSignedIn, - Ok(Some(_)) => runtime.usage(), - Err(err) => ProviderUsage::Failed { - reason: format!("could not read the stored credentials ({err})"), + let codex = (provider == ProviderId::OpenAi).then_some( + crate::provider::usage::codex_app_server::CodexCollection { + report: codex_report, + timed_out: false, }, - }; - (outcome, None) + ); + collect_one_with_codex_collection(context, provider, codex) } -/// Use Codex's report only for the OpenAI usage entry. -fn codex_outcome( +fn collect_one_with_codex_collection( + context: &Context, provider: ProviderId, - report: Option, -) -> Option<(ProviderUsage, Option<&'static str>)> { - if provider != ProviderId::OpenAi { - return None; - } - report.map(|report| { - ( - ProviderUsage::Reported { report }, - Some(crate::provider::usage::codex_app_server::SOURCE_LABEL), - ) - }) + codex: Option, +) -> (ProviderUsage, Option<&'static str>) { + let runtime = ProviderRuntime::new(provider, &context.config, &context.paths); + let collected = crate::provider::usage::report::collect_entry( + provider, + context.config.providers.xai.upstream, + &runtime.tokens, + context.config.timeouts, + codex, + crate::provider::usage::xai::BILLING_BASE_URL, + ); + (collected.entry.outcome, collected.entry.source) } /// Render the whole report. @@ -1179,6 +1165,33 @@ mod tests { assert!(!text.contains("\"source\":null"), "{text}"); } + #[test] + fn usage_selects_only_enabled_providers_and_rejects_disabled_selections() { + let mut config = crate::config::Config::default(); + config.providers.xai.enabled = false; + assert_eq!( + selected_provider_ids(None, &config).unwrap(), + vec![ProviderId::OpenAi] + ); + + let error = selected_provider_ids(Some(ProviderId::Xai), &config).unwrap_err(); + assert!( + error + .message + .unwrap_or_default() + .contains("xai is disabled") + ); + + config.providers.openai.enabled = false; + let error = selected_provider_ids(None, &config).unwrap_err(); + assert!( + error + .message + .unwrap_or_default() + .contains("no providers are enabled") + ); + } + fn context_for(directory: &std::path::Path) -> Context { Context { paths: crate::paths::Paths::in_directory(directory), diff --git a/src/provider/mod.rs b/src/provider/mod.rs index e708d3e..573a5f9 100644 --- a/src/provider/mod.rs +++ b/src/provider/mod.rs @@ -185,8 +185,6 @@ pub struct ProviderRuntime { pub client: crate::auth::OAuthClient, /// The token manager. pub tokens: crate::auth::TokenManager, - /// How long a request to this provider may take. - pub timeouts: crate::config::Timeouts, } impl ProviderRuntime { @@ -211,14 +209,8 @@ impl ProviderRuntime { spec, client, tokens, - timeouts: config.timeouts, } } - - /// What this provider can say about its own allowance. - pub fn usage(&self) -> usage::ProviderUsage { - usage::collect(self.spec.id, self) - } } /// The client id in the stored credential, when there is one. diff --git a/src/provider/usage/codex_app_server.rs b/src/provider/usage/codex_app_server.rs index 46ca086..deb4e7d 100644 --- a/src/provider/usage/codex_app_server.rs +++ b/src/provider/usage/codex_app_server.rs @@ -30,11 +30,28 @@ const MAX_STDOUT_BYTES: usize = 1024 * 1024; /// A small bounded queue prevents a noisy child from buffering unlimited lines. const QUEUED_LINES: usize = 16; -/// Query the installed Codex CLI, returning `None` for every optional-source failure. -pub fn collect() -> Option { +/// A Codex usage read, distinguishing an elapsed session deadline from other +/// optional-source failures so the daemon retries only an actual timeout. +#[derive(Debug, Clone)] +pub(crate) struct CodexCollection { + pub report: Option, + pub timed_out: bool, +} + +/// Query Codex and retain whether its bounded session deadline elapsed. +pub(crate) fn collect_detailed() -> CodexCollection { let mut command = Command::new("codex"); command.arg("app-server"); - collect_with_command(command, SESSION_TIMEOUT) + collect_detailed_with_command(command, SESSION_TIMEOUT) +} + +fn collect_detailed_with_command(command: Command, timeout: Duration) -> CodexCollection { + let started = Instant::now(); + let report = collect_with_command(command, timeout); + CodexCollection { + timed_out: report.is_none() && started.elapsed() >= timeout, + report, + } } /// Run one app-server session. Kept injectable so tests can use a fake process. diff --git a/src/provider/usage/mod.rs b/src/provider/usage/mod.rs index 15ca8b5..247e1b3 100644 --- a/src/provider/usage/mod.rs +++ b/src/provider/usage/mod.rs @@ -24,11 +24,21 @@ pub mod codex_app_server; pub mod openai; +pub mod report; pub mod xai; use serde::Serialize; -use crate::provider::{ProviderId, ProviderRuntime}; +use crate::provider::ProviderId; + +/// One provider usage attempt and whether it ended because of a timeout. +#[derive(Debug, Clone)] +pub struct ProviderCollection { + /// The provider's structured answer. + pub outcome: ProviderUsage, + /// Whether a bounded attempt timed out and should be retried. + pub timed_out: bool, +} /// What a provider can say about its own allowance. #[derive(Debug, Clone, Serialize)] @@ -216,17 +226,6 @@ impl std::fmt::Display for UsageError { impl std::error::Error for UsageError {} -/// Ask a provider what it can say about its allowance. -/// -/// The caller decides which providers to ask; this only routes the question -/// to the provider that can answer it. -pub fn collect(provider: ProviderId, runtime: &ProviderRuntime) -> ProviderUsage { - match provider { - ProviderId::Xai => xai::collect(runtime), - ProviderId::OpenAi => openai::collect(runtime), - } -} - /// Strip the proto enum prefix from a period type. /// /// `USAGE_PERIOD_TYPE_WEEKLY` reads as `WEEKLY`; a type from another diff --git a/src/provider/usage/openai.rs b/src/provider/usage/openai.rs index 77adb4b..e339dc2 100644 --- a/src/provider/usage/openai.rs +++ b/src/provider/usage/openai.rs @@ -23,7 +23,6 @@ //! honest answer is that the number is unavailable, with the reasons and the //! codes the provider does publish. -use crate::provider::ProviderRuntime; use crate::provider::usage::ProviderUsage; /// The page OpenAI points users at for their own usage. @@ -51,7 +50,8 @@ pub const SIGNALS: &[&str] = &[ /// a quota API. It does not say "ChatGPT has no usage information": the user /// has usage information, OpenAI just does not publish a way to read it with /// this credential. -pub fn collect(_runtime: &ProviderRuntime) -> ProviderUsage { +/// The structured fallback when no Codex usage report is available. +pub fn unavailable() -> ProviderUsage { ProviderUsage::Unavailable { reason: "Sign in with ChatGPT does not expose a quota API".to_string(), source: Some(SOURCE.to_string()), @@ -63,7 +63,6 @@ pub fn collect(_runtime: &ProviderRuntime) -> ProviderUsage { #[cfg(test)] mod tests { use super::*; - use crate::provider::ProviderId; #[test] fn the_signals_name_the_documented_codes() { @@ -85,13 +84,7 @@ mod tests { #[test] fn the_answer_names_the_source_and_the_place_to_look() { - let runtime = crate::provider::ProviderRuntime::new( - ProviderId::OpenAi, - &crate::config::Config::default(), - &crate::paths::Paths::in_directory(std::path::Path::new(".")), - ); - - match collect(&runtime) { + match unavailable() { ProviderUsage::Unavailable { reason, source, diff --git a/src/provider/usage/report.rs b/src/provider/usage/report.rs new file mode 100644 index 0000000..36a9db2 --- /dev/null +++ b/src/provider/usage/report.rs @@ -0,0 +1,173 @@ +//! Shared machine-readable usage report assembly for the CLI and daemon API. + +use serde::Serialize; + +use crate::auth::refresh::TokenManager; +use crate::config::{Timeouts, Upstream}; +use crate::provider::usage::{ProviderUsage, UsageReport, xai}; +use crate::provider::{ProviderId, usage::codex_app_server::CodexCollection}; + +/// One provider's answer, with the provider it belongs to. +#[derive(Debug, Clone, Serialize)] +pub(crate) struct ProviderEntry { + pub provider: ProviderId, + #[serde(flatten)] + pub outcome: ProviderUsage, + #[serde(skip_serializing_if = "Option::is_none")] + pub source: Option<&'static str>, + pub caption: Option, + pub last_inference: Option, +} + +/// The machine-readable form shared with eggpass usage --json. +#[derive(Serialize)] +pub(crate) struct UsageReportJson<'a> { + pub providers: &'a [ProviderEntry], +} + +/// A provider collection plus whether a retry is warranted. +#[derive(Debug, Clone)] +pub(crate) struct CollectedEntry { + pub entry: ProviderEntry, + pub timed_out: bool, +} + +/// Providers which are enabled in the effective configuration, in display order. +pub(crate) fn enabled_provider_ids(config: &crate::config::Config) -> Vec { + ProviderId::all() + .into_iter() + .filter(|provider| config.providers.get(*provider).enabled) + .collect() +} + +/// Use Codex's report only for the OpenAI usage entry. +pub(crate) fn codex_outcome( + provider: ProviderId, + report: Option, +) -> Option<(ProviderUsage, Option<&'static str>)> { + if provider != ProviderId::OpenAi { + return None; + } + report.map(|report| { + ( + ProviderUsage::Reported { report }, + Some(crate::provider::usage::codex_app_server::SOURCE_LABEL), + ) + }) +} + +/// Collect one provider using the existing shared token manager. +pub(crate) fn collect_entry( + provider: ProviderId, + xai_upstream: Upstream, + tokens: &TokenManager, + timeouts: Timeouts, + codex: Option, + billing_base_url: &str, +) -> CollectedEntry { + let codex_timed_out = codex.as_ref().is_some_and(|result| result.timed_out); + let codex_report = codex.and_then(|result| result.report); + + let (outcome, source, timed_out) = if provider == ProviderId::OpenAi { + if let Some((outcome, source)) = codex_outcome(provider, codex_report) { + (outcome, source, false) + } else { + let outcome = match tokens.current() { + Ok(None) => ProviderUsage::NotSignedIn, + Ok(Some(_)) => crate::provider::usage::openai::unavailable(), + Err(err) => ProviderUsage::Failed { + reason: format!("could not read the stored credentials ({err})"), + }, + }; + (outcome, None, codex_timed_out) + } + } else { + match tokens.current() { + Ok(None) => (ProviderUsage::NotSignedIn, None, false), + Ok(Some(_)) => { + let result = xai::collect_detailed(tokens, timeouts, billing_base_url); + (result.outcome, None, result.timed_out) + } + Err(err) => ( + ProviderUsage::Failed { + reason: format!("could not read the stored credentials ({err})"), + }, + None, + false, + ), + } + }; + + CollectedEntry { + entry: ProviderEntry { + provider, + outcome, + source, + caption: (provider == ProviderId::Xai).then(|| xai::caption(xai_upstream).to_string()), + last_inference: None, + }, + timed_out, + } +} + +/// Apply a fresh daemon inference snapshot without changing the cached report. +pub(crate) fn attach_inferences( + entries: &[ProviderEntry], + inferences: &std::collections::BTreeMap, +) -> Vec { + entries + .iter() + .cloned() + .map(|mut entry| { + entry.last_inference = inferences.get(&entry.provider).copied(); + entry + }) + .collect() +} + +/// Keep an API-triggered xAI attempt bounded even when inference requests have long timeouts. +/// The configured timeout remains in force for inference and for the interactive CLI. +pub(crate) fn bounded_timeouts(timeouts: Timeouts) -> Timeouts { + const MAX_USAGE_REQUEST: u64 = 15; + const MAX_CONNECT: u64 = 5; + Timeouts { + connect_seconds: timeouts.connect_seconds.min(MAX_CONNECT), + global_seconds: timeouts.global_seconds.min(MAX_USAGE_REQUEST), + body_seconds: timeouts.body_seconds.min(MAX_USAGE_REQUEST), + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn enabled_provider_filter_preserves_display_order() { + let mut config = crate::config::Config::default(); + config.providers.xai.enabled = false; + assert_eq!(enabled_provider_ids(&config), vec![ProviderId::OpenAi]); + config.providers.openai.enabled = false; + assert!(enabled_provider_ids(&config).is_empty()); + } + + #[test] + fn api_timeouts_are_capped_without_extending_user_limits() { + let bounded = bounded_timeouts(Timeouts { + connect_seconds: 30, + global_seconds: 1_800, + body_seconds: 1_800, + }); + assert_eq!(bounded.connect_seconds, 5); + assert_eq!(bounded.global_seconds, 15); + assert_eq!(bounded.body_seconds, 15); + + let shorter = bounded_timeouts(Timeouts { + connect_seconds: 2, + global_seconds: 8, + body_seconds: 9, + }); + assert_eq!(shorter.connect_seconds, 2); + assert_eq!(shorter.global_seconds, 8); + assert_eq!(shorter.body_seconds, 9); + } +} diff --git a/src/provider/usage/xai.rs b/src/provider/usage/xai.rs index a26c2b3..412fa2e 100644 --- a/src/provider/usage/xai.rs +++ b/src/provider/usage/xai.rs @@ -18,7 +18,6 @@ use serde_json::Value; -use crate::provider::ProviderRuntime; use crate::provider::usage::{ Credits, ProductUsage, ProviderUsage, QuotaState, QuotaWindow, UsageError, UsageReport, WindowLabel, @@ -68,62 +67,48 @@ pub fn caption(upstream: crate::config::Upstream) -> &'static str { } } -/// Ask x.ai what it can say about the allowance. -pub fn collect(runtime: &ProviderRuntime) -> ProviderUsage { - // The request goes to the URL the docs above name. The assertion catches - // a path that drifted away from it. +/// Collect usage with an explicit timeout and endpoint, preserving timeout +/// classification for the daemon's finite retry policy. +pub fn collect_detailed( + tokens: &crate::auth::refresh::TokenManager, + timeouts: crate::config::Timeouts, + base_url: &str, +) -> crate::provider::usage::ProviderCollection { debug_assert_eq!(format!("{BILLING_BASE_URL}{BILLING_PATH}"), BILLING_URL); debug_assert_eq!(format!("{BILLING_BASE_URL}{SETTINGS_PATH}"), SETTINGS_URL); - let client = - UpstreamClient::for_endpoint(BILLING_BASE_URL, &headers(runtime), runtime.timeouts); - - let mut response = match send_with_auth( - &client, - &runtime.tokens, - Method::Get, - BILLING_PATH, - &[], - None, - ) { + let client = UpstreamClient::for_endpoint(base_url, &headers(tokens), timeouts); + let mut response = match send_with_auth(&client, tokens, Method::Get, BILLING_PATH, &[], None) { Ok(response) => response, - Err(err) => { - return ProviderUsage::Failed { - reason: describe(&err), - }; - } + Err(err) => return failed(describe(&err), is_timeout(&err)), }; match response.status { 200 => {} - 401 => { - return ProviderUsage::Failed { - reason: "the provider rejected the token".to_string(), - }; - } + 401 => return failed("the provider rejected the token".to_string(), false), 404 => { - return ProviderUsage::Failed { - reason: "the endpoint is not available (HTTP 404)".to_string(), - }; + return failed( + "the endpoint is not available (HTTP 404)".to_string(), + false, + ); } 429 => { - return ProviderUsage::Failed { - reason: "the provider is rate-limiting this account".to_string(), - }; - } - status => { - return ProviderUsage::Failed { - reason: format!("the provider answered HTTP {status}"), - }; + return failed( + "the provider is rate-limiting this account".to_string(), + false, + ); } + status => return failed(format!("the provider answered HTTP {status}"), false), } let body = match response.read_to_vec() { Ok(body) => body, Err(err) => { - return ProviderUsage::Failed { - reason: format!("could not read the provider's answer ({err})"), - }; + let timed_out = err.kind() == std::io::ErrorKind::TimedOut; + return failed( + format!("could not read the provider's answer ({err})"), + timed_out, + ); } }; @@ -131,26 +116,50 @@ pub fn collect(runtime: &ProviderRuntime) -> ProviderUsage { Ok(report) => report, Err(err) => { crate::logging::warn(&format!("billing response: {err}")); - return ProviderUsage::Failed { - reason: err.to_string(), - }; + return failed(err.to_string(), false); } }; - // The plan name is enrichment, not the feature. A failure here omits the - // label; the usage still prints. - report.plan = fetch_plan(&client, runtime); + // Plan lookup is best-effort enrichment. A settings timeout does not make + // an otherwise complete billing report incomplete or retryable. + report.plan = fetch_plan(&client, tokens); - if report.says_nothing() { - return ProviderUsage::Unavailable { + let outcome = if report.says_nothing() { + ProviderUsage::Unavailable { reason: "the provider reported no usage information".to_string(), source: None, hint: None, signals: Vec::new(), - }; + } + } else { + ProviderUsage::Reported { report } + }; + crate::provider::usage::ProviderCollection { + outcome, + timed_out: false, } +} - ProviderUsage::Reported { report } +fn failed(reason: String, timed_out: bool) -> crate::provider::usage::ProviderCollection { + crate::provider::usage::ProviderCollection { + outcome: ProviderUsage::Failed { reason }, + timed_out, + } +} + +fn is_timeout(err: &UpstreamError) -> bool { + match err { + UpstreamError::Network(message) => is_timeout_message(message), + UpstreamError::Token(crate::auth::refresh::TokenError::Auth(err)) => { + is_timeout_message(&err.to_string()) + } + _ => false, + } +} + +fn is_timeout_message(message: &str) -> bool { + let message = message.to_ascii_lowercase(); + message.contains("timed out") || message.contains("timeout") } /// The headers the billing request carries. @@ -160,7 +169,7 @@ pub fn collect(runtime: &ProviderRuntime) -> ProviderUsage { /// `x-grok-client-identifier` or `x-authenticateresponse`: those belong to /// proxy-routed inference, not to billing, and `eggpass`'s own provider spec /// attaches the identifier to inference requests. -fn headers(runtime: &ProviderRuntime) -> Vec<(&'static str, String)> { +fn headers(tokens: &crate::auth::refresh::TokenManager) -> Vec<(&'static str, String)> { let mut headers = vec![ (TOKEN_AUTH_HEADER, TOKEN_AUTH_VALUE.to_string()), ("Accept", "application/json".to_string()), @@ -172,8 +181,7 @@ fn headers(runtime: &ProviderRuntime) -> Vec<(&'static str, String)> { // The official client sends the user id; it is not required here, but it // costs nothing and the proxy is happier with it. - if let Some(user_id) = runtime - .tokens + if let Some(user_id) = tokens .current() .ok() .flatten() @@ -188,16 +196,12 @@ fn headers(runtime: &ProviderRuntime) -> Vec<(&'static str, String)> { /// The plan name, from the settings endpoint. /// /// Best effort: any failure means no plan name, not a failed report. -fn fetch_plan(client: &UpstreamClient, runtime: &ProviderRuntime) -> Option { - let mut response = send_with_auth( - client, - &runtime.tokens, - Method::Get, - SETTINGS_PATH, - &[], - None, - ) - .ok()?; +fn fetch_plan( + client: &UpstreamClient, + tokens: &crate::auth::refresh::TokenManager, +) -> Option { + let mut response = + send_with_auth(client, tokens, Method::Get, SETTINGS_PATH, &[], None).ok()?; if response.status != 200 { return None; } @@ -691,4 +695,19 @@ mod tests { let build = caption(crate::config::Upstream::Build); assert!(build.contains("draws from"), "{build}"); } + + #[test] + fn only_transport_or_oauth_deadlines_are_retryable_timeouts() { + assert!(is_timeout(&UpstreamError::Network( + "operation timed out".to_string() + ))); + assert!(!is_timeout(&UpstreamError::Network( + "connection refused".to_string() + ))); + assert!(is_timeout_message("OAuth HTTP request timed out")); + assert!(!is_timeout_message("OAuth network request failed")); + assert!(!is_timeout(&UpstreamError::Protocol( + "invalid response".to_string() + ))); + } } diff --git a/src/server/chat.rs b/src/server/chat.rs index 507f565..f25001d 100644 --- a/src/server/chat.rs +++ b/src/server/chat.rs @@ -90,7 +90,7 @@ pub fn complete(request: &Request, context: &ServerContext) -> Response { let mut response = match upstream::send_with_auth( &handle.upstream, - &handle.tokens, + handle.tokens.as_ref(), Method::Post, &target, &forwarded, diff --git a/src/server/mod.rs b/src/server/mod.rs index 02220c5..124efab 100644 --- a/src/server/mod.rs +++ b/src/server/mod.rs @@ -15,6 +15,7 @@ pub mod models; pub mod router; pub mod sse; pub mod translate; +pub mod usage; #[cfg(test)] mod tests; @@ -27,6 +28,7 @@ mod keep_body_tests { fn health_does_not_keep_a_body() { assert!(!keep_body_for("/health")); assert!(!keep_body_for("/healthz")); + assert!(!keep_body_for("/v1/usage")); assert!(keep_body_for("/v1/chat/completions")); assert!(keep_body_for("/v1/models")); } @@ -54,7 +56,7 @@ pub struct ProviderHandle { /// The client the requests go out through. pub upstream: UpstreamClient, /// Hands out access tokens, refreshing them when needed. - pub tokens: TokenManager, + pub tokens: Arc, } /// Everything a request handler needs. @@ -91,6 +93,8 @@ pub struct ServerContext { /// It is kept in memory and nowhere else: `eggpass usage` reports it for /// a provider that does not publish a quota of its own. pub inferences: Arc, + /// One in-memory on-demand usage snapshot and its refresh coordinator. + pub usage_cache: Arc, } impl ServerContext { @@ -244,7 +248,7 @@ fn gate_decision(request: &Request, context: &ServerContext) -> http::GateDecisi fn keep_body_for(path: &str) -> bool { !matches!( router::route(path), - router::Route::Health | router::Route::LastInference + router::Route::Health | router::Route::LastInference | router::Route::Usage ) } @@ -315,6 +319,10 @@ fn handle_request(request: Request, context: &ServerContext) -> Response { "GET" => inference::handle(context), _ => method_not_allowed(method, "GET"), }, + router::Route::Usage => match method { + "GET" => usage::handle(context), + _ => method_not_allowed(method, "GET"), + }, router::Route::Models => match method { "GET" => models::list(&request, context), _ => method_not_allowed(method, "GET"), @@ -486,6 +494,9 @@ mod authorisation_tests { upstream_in_flight: Arc::new(AtomicUsize::new(0)), max_upstream_requests: DEFAULT_MAX_UPSTREAM_REQUESTS, inferences: Arc::new(crate::inference::InferenceState::new()), + usage_cache: Arc::new(usage::UsageCache::new(Vec::new(), |_| { + unreachable!("no providers") + })), } } @@ -674,6 +685,9 @@ mod authorisation_tests { upstream_in_flight: Arc::new(AtomicUsize::new(0)), max_upstream_requests: 2, inferences: Arc::new(crate::inference::InferenceState::new()), + usage_cache: Arc::new(usage::UsageCache::new(Vec::new(), |_| { + unreachable!("no providers") + })), }; assert!(context.take_upstream_slot()); diff --git a/src/server/models.rs b/src/server/models.rs index e503f6a..6079865 100644 --- a/src/server/models.rs +++ b/src/server/models.rs @@ -71,7 +71,7 @@ fn merged_catalogue(context: &ServerContext) -> Result, String> { let mut response = match upstream::send_with_auth( &handle.upstream, - &handle.tokens, + handle.tokens.as_ref(), Method::Get, "/v1/models", &[], diff --git a/src/server/router.rs b/src/server/router.rs index 611c408..1bcf83f 100644 --- a/src/server/router.rs +++ b/src/server/router.rs @@ -15,6 +15,8 @@ pub enum Route { Model(String), /// `GET /v1/last-inference` LastInference, + /// `GET /v1/usage` + Usage, /// `GET /health` Health, /// Anything else. @@ -37,6 +39,7 @@ pub fn route(path: &str) -> Route { "/v1/responses" => Route::Responses, "/v1/models" => Route::Models, "/v1/last-inference" => Route::LastInference, + "/v1/usage" => Route::Usage, other => match other.strip_prefix("/v1/models/") { Some(id) if !id.is_empty() => Route::Model(id.to_string()), _ => Route::NotFound, @@ -63,6 +66,8 @@ mod tests { assert_eq!(route("/healthz"), Route::Health); assert_eq!(route("/v1/last-inference"), Route::LastInference); assert_eq!(route("/last-inference"), Route::LastInference); + assert_eq!(route("/v1/usage"), Route::Usage); + assert_eq!(route("/usage"), Route::Usage); } #[test] diff --git a/src/server/tests.rs b/src/server/tests.rs index f09bda1..fb948b9 100644 --- a/src/server/tests.rs +++ b/src/server/tests.rs @@ -223,6 +223,7 @@ struct Harness { inferences: Arc, /// The provider the harness serves. provider: ProviderId, + usage_calls: Arc, _directory: tempfile::TempDir, } @@ -358,7 +359,7 @@ fn harness_with_spec( ProviderHandle { spec: spec.clone(), upstream, - tokens, + tokens: Arc::new(tokens), }, ); @@ -368,6 +369,35 @@ fn harness_with_spec( let inferences = Arc::new(crate::inference::InferenceState::new()); + let usage_calls = Arc::new(AtomicUsize::new(0)); + let usage_calls_for_collector = Arc::clone(&usage_calls); + let usage_tokens = Arc::clone( + &providers + .get(&spec.id) + .expect("provider is registered") + .tokens, + ); + let usage_base_url = stub.base_url(); + let usage_timeouts = crate::config::Timeouts { + connect_seconds: 1, + global_seconds: 1, + body_seconds: 1, + }; + let usage_cache = Arc::new(crate::server::usage::UsageCache::new( + vec![spec.id], + move |provider| { + usage_calls_for_collector.fetch_add(1, std::sync::atomic::Ordering::SeqCst); + crate::provider::usage::report::collect_entry( + provider, + crate::config::Upstream::Api, + usage_tokens.as_ref(), + usage_timeouts, + None, + &usage_base_url, + ) + }, + )); + let context = Arc::new(ServerContext { host: "127.0.0.1".to_string(), port, @@ -379,6 +409,7 @@ fn harness_with_spec( upstream_in_flight: Arc::new(AtomicUsize::new(0)), max_upstream_requests: crate::server::DEFAULT_MAX_UPSTREAM_REQUESTS, inferences: Arc::clone(&inferences), + usage_cache, }); let running = Arc::clone(&server); @@ -392,6 +423,7 @@ fn harness_with_spec( keys, inferences, provider: spec.id, + usage_calls, _directory: directory, } } @@ -1190,6 +1222,142 @@ fn a_streamed_response_without_a_content_type_reaches_a_streaming_client() { assert!(text.contains("[DONE]"), "{text}"); } +#[test] +fn usage_route_is_authenticated_cached_and_attaches_fresh_inference_state() { + let stub = Stub::start(|request| { + if request.path == crate::provider::usage::xai::BILLING_PATH { + Reply::json( + 200, + r#"{"config":{"currentPeriod":{"type":"USAGE_PERIOD_TYPE_WEEKLY","start":"2026-11-13T03:07:08Z","end":"2026-11-20T03:07:08Z"},"creditUsagePercent":42.0,"productUsage":[{"product":"GrokChat","usagePercent":42.0}]}}"#, + ) + } else if request.path == crate::provider::usage::xai::SETTINGS_PATH { + Reply::json(200, r#"{"plan":"SuperGrok"}"#) + } else { + Reply::json(404, "{}") + } + }); + let harness = harness(&stub, "secret-key", "grok-token"); + + let unauthorized = agent() + .get(harness.url("/usage")) + .call() + .expect("the proxy answers"); + assert_eq!(unauthorized.status(), 401); + assert_eq!( + harness + .usage_calls + .load(std::sync::atomic::Ordering::SeqCst), + 0 + ); + assert!( + stub.requests().is_empty(), + "unauthorized requests must not collect" + ); + + let first = agent() + .get(harness.url("/usage")) + .header("Authorization", "Bearer secret-key") + .call() + .expect("the usage route answers"); + assert_eq!(first.status(), 200); + let headers = first.headers(); + assert_eq!( + headers + .get("cache-control") + .and_then(|value| value.to_str().ok()), + Some("private, no-store") + ); + assert!( + headers + .get("x-eggpass-usage-age") + .and_then(|value| value.to_str().ok()) + .and_then(|value| value.parse::().ok()) + .is_some(), + "age header must be integer seconds" + ); + assert!( + headers + .get("x-eggpass-usage-updated-at") + .and_then(|value| value.to_str().ok()) + .is_some_and(|value| value.ends_with('Z')), + "updated-at must be an RFC 3339 UTC timestamp" + ); + let first_body = read_json_body(first); + assert_eq!(first_body["providers"].as_array().unwrap().len(), 1); + assert_eq!(first_body["providers"][0]["provider"], "xai"); + assert_eq!(first_body["providers"][0]["status"], "reported"); + assert_eq!( + first_body["providers"][0]["last_inference"], + serde_json::Value::Null + ); + assert!(!first_body.to_string().contains("user@example.com")); + assert!(!first_body.to_string().contains("grok-token")); + + let upstream = stub.requests(); + assert_eq!( + upstream.len(), + 2, + "cold collection calls billing and settings once" + ); + assert!( + upstream + .iter() + .any(|request| request.path == crate::provider::usage::xai::BILLING_PATH) + ); + assert!( + upstream + .iter() + .any(|request| request.path == crate::provider::usage::xai::SETTINGS_PATH) + ); + assert_eq!( + harness + .usage_calls + .load(std::sync::atomic::Ordering::SeqCst), + 1 + ); + + harness.inferences.record(ProviderId::Xai, 429); + let cached = agent() + .get(harness.url("/v1/usage")) + .header("Authorization", "Bearer secret-key") + .call() + .expect("the cached report answers"); + assert_eq!(cached.status(), 200); + let cached_body = read_json_body(cached); + assert_eq!(cached_body["providers"][0]["last_inference"], 429); + assert_eq!( + harness + .usage_calls + .load(std::sync::atomic::Ordering::SeqCst), + 1 + ); + assert_eq!( + stub.requests().len(), + 2, + "a fresh cache hit must not query upstream" + ); + + let method = agent() + .post(harness.url("/v1/usage")) + .header("Authorization", "Bearer secret-key") + .send("{}") + .expect("the route reports its allowed method"); + assert_eq!(method.status(), 405); + assert_eq!( + method + .headers() + .get("allow") + .and_then(|value| value.to_str().ok()), + Some("GET") + ); + assert_eq!( + harness + .usage_calls + .load(std::sync::atomic::Ordering::SeqCst), + 1 + ); +} + #[test] fn a_native_responses_request_is_forwarded_untouched() { // A Responses-only provider speaks the Responses API natively. A request diff --git a/src/server/usage.rs b/src/server/usage.rs new file mode 100644 index 0000000..b4202e3 --- /dev/null +++ b/src/server/usage.rs @@ -0,0 +1,769 @@ +//! Authenticated daemon usage route and its process-local refresh cache. + +use std::panic::{AssertUnwindSafe, catch_unwind}; +use std::sync::{Arc, Condvar, Mutex, MutexGuard}; +use std::thread; +use std::time::{Duration, Instant}; + +use crate::provider::ProviderId; +use crate::provider::usage::{ + ProviderUsage, + report::{CollectedEntry, ProviderEntry, UsageReportJson, attach_inferences}, +}; +use crate::timeutil; + +const CACHE_TTL: Duration = Duration::from_secs(600); +const CLIENT_WAIT: Duration = Duration::from_secs(30); +const RETRY_DELAYS: [Duration; 3] = [ + Duration::from_secs(5), + Duration::from_secs(15), + Duration::from_secs(30), +]; +const FAILURE_COOLDOWN: Duration = Duration::from_secs(600); +const CACHE_CONTROL: &str = "private, no-store"; + +/// Usage collection callback, supplied by the daemon with shared token managers. +type Collector = dyn Fn(ProviderId) -> CollectedEntry + Send + Sync + 'static; + +/// Tunable only inside deterministic cache tests; production uses DEFAULT_POLICY. +#[derive(Debug, Clone, Copy)] +struct CachePolicy { + ttl: Duration, + client_wait: Duration, + retry_delays: [Duration; 3], + cooldown: Duration, +} + +const DEFAULT_POLICY: CachePolicy = CachePolicy { + ttl: CACHE_TTL, + client_wait: CLIENT_WAIT, + retry_delays: RETRY_DELAYS, + cooldown: FAILURE_COOLDOWN, +}; + +/// A complete cached report. Monotonic time controls expiry; wall time is only +/// used for the public RFC 3339 update header. +#[derive(Clone)] +struct Snapshot { + entries: Vec, + completed_at: Instant, + updated_at_unix: i64, +} + +#[derive(Default)] +struct CacheState { + snapshot: Option, + refresh: Option, + cooldown_until: Option, +} + +struct RefreshState { + next_retry_at: Option, + retry_after_hint: u64, +} + +/// What the route should return from the cache coordinator. +enum CacheResponse { + Complete { snapshot: Snapshot, stale: bool }, + Pending { retry_after: u64 }, + TimedOut { retry_after: u64 }, + Unavailable { retry_after: u64 }, +} + +/// One process-local usage cache and one finite, request-triggered refresh job. +pub struct UsageCache { + providers: Vec, + collector: Arc, + state: Arc>, + changed: Arc, + policy: CachePolicy, +} + +impl UsageCache { + /// Create a cold cache over only the providers selected for this daemon. + pub fn new(providers: Vec, collector: F) -> UsageCache + where + F: Fn(ProviderId) -> CollectedEntry + Send + Sync + 'static, + { + UsageCache::with_policy(providers, collector, DEFAULT_POLICY) + } + + fn with_policy(providers: Vec, collector: F, policy: CachePolicy) -> UsageCache + where + F: Fn(ProviderId) -> CollectedEntry + Send + Sync + 'static, + { + UsageCache { + providers, + collector: Arc::new(collector), + state: Arc::new(Mutex::new(CacheState::default())), + changed: Arc::new(Condvar::new()), + policy, + } + } + + /// Return a fresh snapshot, or trigger/share one finite refresh. + fn get(&self) -> CacheResponse { + let now = Instant::now(); + let mut state = lock(&self.state); + if let Some(response) = response_for_state(&state, now, self.policy) { + // A request arriving after another one started never waits on its + // handler thread; it gets 202 and the scheduled retry hint. + return response; + } + + state.cooldown_until = None; + state.refresh = Some(RefreshState { + next_retry_at: None, + retry_after_hint: self.policy.retry_delays[0].as_secs().max(1), + }); + drop(state); + + let providers = self.providers.clone(); + let collector = Arc::clone(&self.collector); + let worker_state = Arc::clone(&self.state); + let changed = Arc::clone(&self.changed); + let policy = self.policy; + if thread::Builder::new() + .name("eggpass-usage-refresh".to_string()) + .spawn(move || run_refresh(providers, collector, worker_state, changed, policy)) + .is_err() + { + let mut state = lock(&self.state); + state.refresh = None; + self.changed.notify_all(); + return CacheResponse::Unavailable { retry_after: 1 }; + } + + self.wait_for_started_refresh() + } + + fn wait_for_started_refresh(&self) -> CacheResponse { + let deadline = Instant::now() + self.policy.client_wait; + let mut state = lock(&self.state); + loop { + let now = Instant::now(); + if state.refresh.is_none() { + if let Some(response) = response_for_state(&state, now, self.policy) { + return response; + } + return CacheResponse::Unavailable { retry_after: 1 }; + } + + let remaining = deadline.saturating_duration_since(now); + if remaining.is_zero() { + return CacheResponse::TimedOut { + retry_after: retry_after(&state, now), + }; + } + let (next, timeout) = self + .changed + .wait_timeout(state, remaining) + .unwrap_or_else(|poisoned| poisoned.into_inner()); + state = next; + if timeout.timed_out() && state.refresh.is_some() { + return CacheResponse::TimedOut { + retry_after: retry_after(&state, Instant::now()), + }; + } + } + } +} + +fn run_refresh( + providers: Vec, + collector: Arc, + state: Arc>, + changed: Arc, + policy: CachePolicy, +) { + let mut entries = Vec::with_capacity(providers.len()); + let mut timed_out = Vec::new(); + for provider in providers { + let result = collect_safely(collector.as_ref(), provider); + if result.timed_out { + timed_out.push(provider); + } + entries.push(result.entry); + } + + if timed_out.is_empty() { + finish_success(entries, &state, &changed); + return; + } + + for (retry_index, delay) in policy.retry_delays.iter().copied().enumerate() { + { + let mut current = lock(&state); + if let Some(refresh) = current.refresh.as_mut() { + refresh.next_retry_at = Some(Instant::now() + delay); + refresh.retry_after_hint = delay.as_secs().max(1); + } + changed.notify_all(); + } + thread::sleep(delay); + { + let mut current = lock(&state); + if let Some(refresh) = current.refresh.as_mut() { + refresh.next_retry_at = None; + refresh.retry_after_hint = policy + .retry_delays + .get(retry_index + 1) + .map(|next| next.as_secs().max(1)) + .unwrap_or(1); + } + } + + let retrying = std::mem::take(&mut timed_out); + for provider in retrying { + let result = collect_safely(collector.as_ref(), provider); + if let Some(entry) = entries.iter_mut().find(|entry| entry.provider == provider) { + *entry = result.entry; + } + if result.timed_out { + timed_out.push(provider); + } + } + + if timed_out.is_empty() { + finish_success(entries, &state, &changed); + return; + } + } + + let mut current = lock(&state); + current.refresh = None; + current.cooldown_until = Some(Instant::now() + policy.cooldown); + changed.notify_all(); +} + +fn collect_safely(collector: &Collector, provider: ProviderId) -> CollectedEntry { + match catch_unwind(AssertUnwindSafe(|| collector(provider))) { + Ok(result) => result, + Err(_) => CollectedEntry { + entry: ProviderEntry { + provider, + outcome: ProviderUsage::Failed { + reason: "the usage collector failed unexpectedly".to_string(), + }, + source: None, + caption: None, + last_inference: None, + }, + timed_out: false, + }, + } +} + +fn finish_success(entries: Vec, state: &Mutex, changed: &Condvar) { + let mut current = lock(state); + current.snapshot = Some(Snapshot { + entries, + completed_at: Instant::now(), + updated_at_unix: timeutil::now_unix(), + }); + current.refresh = None; + current.cooldown_until = None; + changed.notify_all(); +} + +fn response_for_state( + state: &CacheState, + now: Instant, + policy: CachePolicy, +) -> Option { + if let Some(snapshot) = &state.snapshot + && now.saturating_duration_since(snapshot.completed_at) < policy.ttl + { + return Some(CacheResponse::Complete { + snapshot: snapshot.clone(), + stale: false, + }); + } + + if let Some(until) = state.cooldown_until.filter(|until| *until > now) { + let retry_after = seconds_ceil(until.saturating_duration_since(now)); + return Some(match &state.snapshot { + Some(snapshot) => CacheResponse::Complete { + snapshot: snapshot.clone(), + stale: true, + }, + None => CacheResponse::Unavailable { retry_after }, + }); + } + + state.refresh.as_ref().map(|_| CacheResponse::Pending { + retry_after: retry_after(state, now), + }) +} + +fn retry_after(state: &CacheState, now: Instant) -> u64 { + state.refresh.as_ref().map_or(1, |refresh| { + refresh + .next_retry_at + .map(|at| seconds_ceil(at.saturating_duration_since(now))) + .unwrap_or(refresh.retry_after_hint.max(1)) + }) +} + +fn seconds_ceil(duration: Duration) -> u64 { + duration.as_secs() + u64::from(duration.subsec_nanos() > 0) +} + +fn lock(mutex: &Mutex) -> MutexGuard<'_, T> { + mutex + .lock() + .unwrap_or_else(|poisoned| poisoned.into_inner()) +} + +/// Serve the authenticated usage route after the common request guard passed. +pub(crate) fn handle(context: &super::ServerContext) -> super::Response { + match context.usage_cache.get() { + CacheResponse::Complete { snapshot, stale } => { + let inferences = context.inferences.snapshot(); + let entries = attach_inferences(&snapshot.entries, &inferences); + let body = match serde_json::to_string(&UsageReportJson { + providers: &entries, + }) { + Ok(body) => body, + Err(_) => { + return api_error( + 500, + "the usage report could not be serialized", + "usage_report_serialization_failed", + None, + ); + } + }; + let age = Instant::now() + .saturating_duration_since(snapshot.completed_at) + .as_secs(); + let mut response = super::Response::json(200, body); + response.headers.extend([ + ("Cache-Control".to_string(), CACHE_CONTROL.to_string()), + ("X-Eggpass-Usage-Age".to_string(), age.to_string()), + ( + "X-Eggpass-Usage-Updated-At".to_string(), + timeutil::format_rfc3339(snapshot.updated_at_unix), + ), + ]); + if stale { + response + .headers + .push(("X-Eggpass-Usage-Stale".to_string(), "true".to_string())); + } + response + } + CacheResponse::Pending { retry_after } => api_error( + 202, + "a usage report refresh is already in progress", + "usage_refresh_pending", + Some(retry_after), + ), + CacheResponse::TimedOut { retry_after } => api_error( + 504, + "the usage report refresh did not finish within 30 seconds", + "usage_refresh_timeout", + Some(retry_after), + ), + CacheResponse::Unavailable { retry_after } => api_error( + 503, + "the usage report is temporarily unavailable", + "usage_refresh_unavailable", + Some(retry_after), + ), + } +} + +fn api_error(status: u16, message: &str, code: &str, retry_after: Option) -> super::Response { + let mut response = super::openai_error_with_code(status, message, "server_error", Some(code)); + response + .headers + .push(("Cache-Control".to_string(), CACHE_CONTROL.to_string())); + if let Some(seconds) = retry_after { + response + .headers + .push(("Retry-After".to_string(), seconds.max(1).to_string())); + } + response +} + +#[cfg(test)] +mod tests { + use super::*; + use std::sync::atomic::{AtomicUsize, Ordering}; + use std::sync::mpsc::{self, Receiver}; + + fn policy(client_wait: Duration, retry_delays: [Duration; 3]) -> CachePolicy { + CachePolicy { + ttl: Duration::from_secs(600), + client_wait, + retry_delays, + cooldown: Duration::from_millis(100), + } + } + + fn entry(provider: ProviderId, timed_out: bool) -> CollectedEntry { + CollectedEntry { + entry: ProviderEntry { + provider, + outcome: if timed_out { + ProviderUsage::Failed { + reason: "provider request timed out".to_string(), + } + } else { + ProviderUsage::Unavailable { + reason: "test fixture outcome".to_string(), + source: None, + hint: None, + signals: Vec::new(), + } + }, + source: None, + caption: None, + last_inference: None, + }, + timed_out, + } + } + + fn wait_until_idle(cache: &UsageCache, timeout: Duration) -> bool { + let deadline = Instant::now() + timeout; + let mut state = lock(&cache.state); + while state.refresh.is_some() { + let remaining = deadline.saturating_duration_since(Instant::now()); + if remaining.is_zero() { + return false; + } + let (next, result) = cache + .changed + .wait_timeout(state, remaining) + .unwrap_or_else(|poisoned| poisoned.into_inner()); + state = next; + if result.timed_out() && state.refresh.is_some() { + return false; + } + } + true + } + + #[test] + fn production_policy_matches_the_selected_contract() { + assert_eq!(DEFAULT_POLICY.ttl, Duration::from_secs(600)); + assert_eq!(DEFAULT_POLICY.client_wait, Duration::from_secs(30)); + assert_eq!( + DEFAULT_POLICY.retry_delays, + [ + Duration::from_secs(5), + Duration::from_secs(15), + Duration::from_secs(30), + ] + ); + assert_eq!(DEFAULT_POLICY.cooldown, Duration::from_secs(600)); + } + + #[test] + fn a_fresh_snapshot_is_reused_and_an_expired_snapshot_refreshes_once() { + let calls = Arc::new(AtomicUsize::new(0)); + let counted = Arc::clone(&calls); + let policy = policy(Duration::from_millis(300), [Duration::ZERO; 3]); + let cache = UsageCache::with_policy( + vec![ProviderId::Xai], + move |provider| { + counted.fetch_add(1, Ordering::SeqCst); + entry(provider, false) + }, + policy, + ); + + assert!(matches!( + cache.get(), + CacheResponse::Complete { stale: false, .. } + )); + assert!(matches!( + cache.get(), + CacheResponse::Complete { stale: false, .. } + )); + assert_eq!(calls.load(Ordering::SeqCst), 1); + + { + let mut state = lock(&cache.state); + state.snapshot.as_mut().unwrap().completed_at = + Instant::now() - policy.ttl - Duration::from_millis(1); + } + assert!(matches!( + cache.get(), + CacheResponse::Complete { stale: false, .. } + )); + assert_eq!(calls.load(Ordering::SeqCst), 2); + } + + #[test] + fn a_client_timeout_does_not_cancel_or_duplicate_the_active_refresh() { + let calls = Arc::new(AtomicUsize::new(0)); + let counted = Arc::clone(&calls); + let (release_tx, release_rx) = mpsc::channel(); + let release_rx = Arc::new(Mutex::new(release_rx)); + let wait_for_release = Arc::clone(&release_rx); + let cache = UsageCache::with_policy( + vec![ProviderId::Xai], + move |provider| { + counted.fetch_add(1, Ordering::SeqCst); + let _ = recv_release(&wait_for_release); + entry(provider, false) + }, + policy(Duration::from_millis(10), [Duration::ZERO; 3]), + ); + + assert!(matches!(cache.get(), CacheResponse::TimedOut { .. })); + assert!(matches!( + cache.get(), + CacheResponse::Pending { retry_after: 1.. } + )); + assert_eq!(calls.load(Ordering::SeqCst), 1); + release_tx.send(()).unwrap(); + assert!(wait_until_idle(&cache, Duration::from_millis(300))); + assert!(matches!( + cache.get(), + CacheResponse::Complete { stale: false, .. } + )); + assert_eq!(calls.load(Ordering::SeqCst), 1); + } + + fn recv_release(receiver: &Arc>>) -> Result<(), mpsc::RecvTimeoutError> { + receiver + .lock() + .unwrap_or_else(|poisoned| poisoned.into_inner()) + .recv_timeout(Duration::from_secs(1)) + } + + #[test] + fn retries_only_the_timed_out_provider_and_respects_each_delay() { + let xai_calls = Arc::new(AtomicUsize::new(0)); + let openai_calls = Arc::new(AtomicUsize::new(0)); + let observed = Arc::new(Mutex::new(Vec::new())); + let xai_counter = Arc::clone(&xai_calls); + let openai_counter = Arc::clone(&openai_calls); + let observed_times = Arc::clone(&observed); + let delays = [ + Duration::from_millis(2), + Duration::from_millis(5), + Duration::from_millis(8), + ]; + let cache = UsageCache::with_policy( + vec![ProviderId::Xai, ProviderId::OpenAi], + move |provider| match provider { + ProviderId::Xai => { + observed_times.lock().unwrap().push(Instant::now()); + let attempt = xai_counter.fetch_add(1, Ordering::SeqCst); + entry(provider, attempt < 3) + } + ProviderId::OpenAi => { + openai_counter.fetch_add(1, Ordering::SeqCst); + entry(provider, false) + } + }, + policy(Duration::from_millis(300), delays), + ); + + assert!(matches!( + cache.get(), + CacheResponse::Complete { stale: false, .. } + )); + assert_eq!(xai_calls.load(Ordering::SeqCst), 4); + assert_eq!(openai_calls.load(Ordering::SeqCst), 1); + let observed = observed.lock().unwrap(); + assert_eq!(observed.len(), 4); + for (index, delay) in delays.iter().enumerate() { + assert!(observed[index + 1].duration_since(observed[index]) >= *delay); + } + } + + #[test] + fn retry_exhaustion_serves_only_the_previous_report_as_stale() { + let calls = Arc::new(AtomicUsize::new(0)); + let counted = Arc::clone(&calls); + let policy = policy(Duration::from_millis(300), [Duration::ZERO; 3]); + let cache = UsageCache::with_policy( + vec![ProviderId::Xai], + move |provider| { + counted.fetch_add(1, Ordering::SeqCst); + entry(provider, true) + }, + policy, + ); + { + let mut state = lock(&cache.state); + state.snapshot = Some(Snapshot { + entries: vec![entry(ProviderId::Xai, false).entry], + completed_at: Instant::now() - policy.ttl - Duration::from_secs(1), + updated_at_unix: 1_800_000_000, + }); + } + + assert!(matches!( + cache.get(), + CacheResponse::Complete { stale: true, .. } + )); + assert_eq!(calls.load(Ordering::SeqCst), 4); + assert!(matches!( + cache.get(), + CacheResponse::Complete { stale: true, .. } + )); + assert_eq!(calls.load(Ordering::SeqCst), 4); + } + + #[test] + fn retry_exhaustion_without_a_good_snapshot_returns_503_during_cooldown() { + let calls = Arc::new(AtomicUsize::new(0)); + let counted = Arc::clone(&calls); + let cache = UsageCache::with_policy( + vec![ProviderId::Xai], + move |provider| { + counted.fetch_add(1, Ordering::SeqCst); + entry(provider, true) + }, + policy(Duration::from_millis(300), [Duration::ZERO; 3]), + ); + + assert!(matches!( + cache.get(), + CacheResponse::Unavailable { retry_after: 1.. } + )); + assert_eq!(calls.load(Ordering::SeqCst), 4); + assert!(matches!( + cache.get(), + CacheResponse::Unavailable { retry_after: 1.. } + )); + assert_eq!(calls.load(Ordering::SeqCst), 4); + } + + #[test] + fn a_new_empty_cache_is_cold_and_returns_an_empty_provider_list() { + let calls = Arc::new(AtomicUsize::new(0)); + let counted = Arc::clone(&calls); + let cache = UsageCache::new(Vec::new(), move |provider| { + counted.fetch_add(1, Ordering::SeqCst); + entry(provider, false) + }); + match cache.get() { + CacheResponse::Complete { + snapshot, + stale: false, + } => assert!(snapshot.entries.is_empty()), + _ => panic!("an empty enabled-provider set completes with an empty report"), + } + assert_eq!(calls.load(Ordering::SeqCst), 0); + assert!(lock(&cache.state).snapshot.is_some()); + } + + fn route_context(cache: UsageCache) -> (crate::server::ServerContext, tempfile::TempDir) { + let directory = tempfile::tempdir().unwrap(); + let keys = + Arc::new(crate::keys::KeyStore::open(directory.path().join("keys.json")).unwrap()); + let context = crate::server::ServerContext { + host: "127.0.0.1".to_string(), + port: 8484, + api_key: "route-test-key".to_string(), + keys, + providers: std::collections::HashMap::new(), + default_provider: ProviderId::Xai, + routing: crate::config::Routing::default(), + upstream_in_flight: Arc::new(std::sync::atomic::AtomicUsize::new(0)), + max_upstream_requests: crate::server::DEFAULT_MAX_UPSTREAM_REQUESTS, + inferences: Arc::new(crate::inference::InferenceState::new()), + usage_cache: Arc::new(cache), + }; + (context, directory) + } + + fn response_header<'a>(response: &'a crate::server::Response, name: &str) -> Option<&'a str> { + response + .headers + .iter() + .find(|(key, _)| key.eq_ignore_ascii_case(name)) + .map(|(_, value)| value.as_str()) + } + + #[test] + fn the_route_returns_504_then_202_while_one_refresh_continues() { + let (release_tx, release_rx) = mpsc::channel(); + let release_rx = Arc::new(Mutex::new(release_rx)); + let wait_for_release = Arc::clone(&release_rx); + let cache = UsageCache::with_policy( + vec![ProviderId::Xai], + move |provider| { + let _ = recv_release(&wait_for_release); + entry(provider, false) + }, + policy(Duration::from_millis(10), [Duration::ZERO; 3]), + ); + let (context, _directory) = route_context(cache); + + let timed_out = handle(&context); + assert_eq!(timed_out.status, 504); + assert_eq!(response_header(&timed_out, "Retry-After"), Some("1")); + assert_eq!( + response_header(&timed_out, "Cache-Control"), + Some(CACHE_CONTROL) + ); + + let pending = handle(&context); + assert_eq!(pending.status, 202); + assert!(response_header(&pending, "Retry-After").is_some()); + release_tx.send(()).unwrap(); + assert!(wait_until_idle( + &context.usage_cache, + Duration::from_millis(300) + )); + assert_eq!(handle(&context).status, 200); + } + + #[test] + fn the_route_marks_a_stale_snapshot_and_returns_503_without_one() { + let policy = policy(Duration::from_millis(300), [Duration::ZERO; 3]); + let stale_cache = UsageCache::with_policy( + vec![ProviderId::Xai], + |provider| entry(provider, true), + policy, + ); + { + let mut state = lock(&stale_cache.state); + state.snapshot = Some(Snapshot { + entries: vec![entry(ProviderId::Xai, false).entry], + completed_at: Instant::now() - policy.ttl - Duration::from_secs(1), + updated_at_unix: 1_800_000_000, + }); + } + let (stale_context, _stale_directory) = route_context(stale_cache); + let stale = handle(&stale_context); + assert_eq!(stale.status, 200); + assert_eq!( + response_header(&stale, "X-Eggpass-Usage-Stale"), + Some("true") + ); + assert!( + response_header(&stale, "X-Eggpass-Usage-Age") + .and_then(|value| value.parse::().ok()) + .is_some_and(|age| age >= 600) + ); + assert_eq!( + response_header(&stale, "Cache-Control"), + Some(CACHE_CONTROL) + ); + + let empty_cache = UsageCache::with_policy( + vec![ProviderId::Xai], + |provider| entry(provider, true), + policy, + ); + let (empty_context, _empty_directory) = route_context(empty_cache); + let empty = handle(&empty_context); + assert_eq!(empty.status, 503); + assert!(response_header(&empty, "Retry-After").is_some()); + assert_eq!( + response_header(&empty, "Cache-Control"), + Some(CACHE_CONTROL) + ); + assert_eq!(handle(&empty_context).status, 503); + } +} From e2f8772cd249f5629c4bee822d24bca1f9932932 Mon Sep 17 00:00:00 2001 From: dbowm91 Date: Wed, 18 Nov 2026 20:05:33 +0000 Subject: [PATCH 4/7] fix: avoid Windows Instant underflow in usage tests --- src/server/usage.rs | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/src/server/usage.rs b/src/server/usage.rs index b4202e3..36caf97 100644 --- a/src/server/usage.rs +++ b/src/server/usage.rs @@ -103,7 +103,10 @@ impl UsageCache { /// Return a fresh snapshot, or trigger/share one finite refresh. fn get(&self) -> CacheResponse { - let now = Instant::now(); + self.get_at(Instant::now()) + } + + fn get_at(&self, now: Instant) -> CacheResponse { let mut state = lock(&self.state); if let Some(response) = response_for_state(&state, now, self.policy) { // A request arriving after another one started never waits on its @@ -485,13 +488,9 @@ mod tests { )); assert_eq!(calls.load(Ordering::SeqCst), 1); - { - let mut state = lock(&cache.state); - state.snapshot.as_mut().unwrap().completed_at = - Instant::now() - policy.ttl - Duration::from_millis(1); - } + let expired_at = Instant::now() + cache.policy.ttl; assert!(matches!( - cache.get(), + cache.get_at(expired_at), CacheResponse::Complete { stale: false, .. } )); assert_eq!(calls.load(Ordering::SeqCst), 2); @@ -582,7 +581,8 @@ mod tests { fn retry_exhaustion_serves_only_the_previous_report_as_stale() { let calls = Arc::new(AtomicUsize::new(0)); let counted = Arc::clone(&calls); - let policy = policy(Duration::from_millis(300), [Duration::ZERO; 3]); + let mut policy = policy(Duration::from_millis(300), [Duration::ZERO; 3]); + policy.ttl = Duration::ZERO; let cache = UsageCache::with_policy( vec![ProviderId::Xai], move |provider| { @@ -595,7 +595,7 @@ mod tests { let mut state = lock(&cache.state); state.snapshot = Some(Snapshot { entries: vec![entry(ProviderId::Xai, false).entry], - completed_at: Instant::now() - policy.ttl - Duration::from_secs(1), + completed_at: Instant::now(), updated_at_unix: 1_800_000_000, }); } @@ -720,7 +720,8 @@ mod tests { #[test] fn the_route_marks_a_stale_snapshot_and_returns_503_without_one() { - let policy = policy(Duration::from_millis(300), [Duration::ZERO; 3]); + let mut policy = policy(Duration::from_millis(300), [Duration::ZERO; 3]); + policy.ttl = Duration::ZERO; let stale_cache = UsageCache::with_policy( vec![ProviderId::Xai], |provider| entry(provider, true), @@ -730,7 +731,7 @@ mod tests { let mut state = lock(&stale_cache.state); state.snapshot = Some(Snapshot { entries: vec![entry(ProviderId::Xai, false).entry], - completed_at: Instant::now() - policy.ttl - Duration::from_secs(1), + completed_at: Instant::now(), updated_at_unix: 1_800_000_000, }); } @@ -744,8 +745,9 @@ mod tests { assert!( response_header(&stale, "X-Eggpass-Usage-Age") .and_then(|value| value.parse::().ok()) - .is_some_and(|age| age >= 600) + .is_some() ); + assert!(response_header(&stale, "X-Eggpass-Usage-Updated-At").is_some()); assert_eq!( response_header(&stale, "Cache-Control"), Some(CACHE_CONTROL) From 5287f70c26b27ad55af48bb432491e9141aa17aa Mon Sep 17 00:00:00 2001 From: dbowm91 Date: Thu, 19 Nov 2026 18:09:58 +0000 Subject: [PATCH 5/7] test: isolate Windows usage-key ACL validation --- Cargo.toml | 2 +- src/cli/commands/run.rs | 8 + src/main.rs | 1 + src/paths.rs | 15 +- src/server/mod.rs | 166 +++++++++++- src/server/tests.rs | 34 +++ src/server/usage.rs | 1 + src/usage_key.rs | 545 ++++++++++++++++++++++++++++++++++++++++ 8 files changed, 768 insertions(+), 4 deletions(-) create mode 100644 src/usage_key.rs diff --git a/Cargo.toml b/Cargo.toml index a2a1861..6ea8b16 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -72,7 +72,7 @@ daemonize = "0.5.0" nix = { version = "0.31.3", features = ["signal", "process", "term"] } [target.'cfg(windows)'.dependencies] -windows-sys = { version = "0.61.2", features = ["Win32_Foundation", "Win32_System_Threading"] } +windows-sys = { version = "0.61.2", features = ["Win32_Foundation", "Win32_Security", "Win32_Security_Authorization", "Win32_Storage_FileSystem", "Win32_System_Threading"] } [dev-dependencies] tempfile = "3.27.0" diff --git a/src/cli/commands/run.rs b/src/cli/commands/run.rs index f03abed..52edab5 100644 --- a/src/cli/commands/run.rs +++ b/src/cli/commands/run.rs @@ -259,10 +259,18 @@ fn serve(context: &Context) -> Result<(), CommandError> { }, )); + let usage_key = + crate::usage_key::UsageKey::create(context.paths.usage_key_file()).map_err(|err| { + CommandError::new(format!( + "could not create the private daemon usage credential: {err}" + )) + })?; + let server_context = Arc::new(ServerContext { host: context.config.host.clone(), port: context.config.port, api_key: context.config.api_key.clone(), + usage_key: usage_key.token().to_string(), keys, providers, default_provider, diff --git a/src/main.rs b/src/main.rs index cdab860..bd6b566 100644 --- a/src/main.rs +++ b/src/main.rs @@ -19,6 +19,7 @@ mod server; mod timeutil; mod update; mod upstream; +mod usage_key; use cli::args::ParseOutcome; diff --git a/src/paths.rs b/src/paths.rs index f5d60be..74552c3 100644 --- a/src/paths.rs +++ b/src/paths.rs @@ -3,12 +3,12 @@ //! Resolution order for the configuration directory: //! //! 1. `$EGGPASS_HOME` when set — relocates *every* file (config, credentials, -//! pid, log). Useful for tests and for running a second instance. +//! usage key, pid, log). Useful for tests and for running a second instance. //! 2. `$XDG_CONFIG_HOME/eggpass` when set. //! 3. `~/.config/eggpass`. //! //! The `--config ` flag overrides only the configuration *file*; the -//! credential, pid and log files stay in the resolved directory. +//! credential, usage-key, pid and log files stay in the resolved directory. use std::path::{Path, PathBuf}; @@ -22,6 +22,8 @@ pub const LOG_FILE_NAME: &str = "eggpass.log"; pub const CREDENTIALS_DIR_NAME: &str = "credentials"; /// Name of the file holding the keys `eggpass` issues to its clients. pub const KEY_STORE_FILE_NAME: &str = "keys.json"; +/// Name of the daemon-managed CLI-only usage credential file. +pub const USAGE_KEY_FILE_NAME: &str = "usage.key"; /// The legacy single-provider credential file, kept for the migration. pub const LEGACY_AUTH_FILE_NAME: &str = "auth.json"; /// The name this project had before the rename. @@ -120,6 +122,11 @@ impl Paths { self.dir.join(KEY_STORE_FILE_NAME) } + /// The daemon-managed usage-only credential (not moved by `--config`). + pub fn usage_key_file(&self) -> PathBuf { + self.dir.join(USAGE_KEY_FILE_NAME) + } + /// The daemon pid file. pub fn pid_file(&self) -> PathBuf { self.dir.join(PID_FILE_NAME) @@ -294,6 +301,10 @@ mod tests { paths.pid_file(), Path::new("/tmp/eggpass-test-home/eggpass.pid") ); + assert_eq!( + paths.usage_key_file(), + Path::new("/tmp/eggpass-test-home/usage.key") + ); } #[test] diff --git a/src/server/mod.rs b/src/server/mod.rs index 124efab..079ab73 100644 --- a/src/server/mod.rs +++ b/src/server/mod.rs @@ -73,6 +73,10 @@ pub struct ServerContext { /// Empty means there is no such key. The keys `eggpass` issued are /// accepted as well. pub api_key: String, + /// The exact runtime bearer secret authorized only for bodyless `GET /v1/usage`. + /// + /// This is never counted as a configured client key. + pub usage_key: String, /// The keys `eggpass` issued to its clients. pub keys: Arc, /// The providers that are available. @@ -390,7 +394,40 @@ pub fn is_authorized(context: &ServerContext, request: &Request) -> bool { } } - false + usage_key_authorized(context, request) +} + +/// Whether the dedicated runtime secret is presented for its sole allowed request. +fn usage_key_authorized(context: &ServerContext, request: &Request) -> bool { + if context.usage_key.is_empty() + || request.method != "GET" + || request.target != "/v1/usage" + || !request.body.is_empty() + || request + .headers + .iter() + .any(|(name, _)| name.eq_ignore_ascii_case("transfer-encoding")) + { + return false; + } + + if request + .headers + .iter() + .any(|(name, value)| name.eq_ignore_ascii_case("content-length") && value.trim() != "0") + { + return false; + } + + request.headers.iter().any(|(name, value)| { + if !name.eq_ignore_ascii_case("authorization") { + return false; + } + let Some(token) = strip_bearer(value.trim()) else { + return false; + }; + crate::keys::constant_time_eq(token.as_bytes(), context.usage_key.as_bytes()) + }) } /// The keys a request presents. @@ -487,6 +524,7 @@ mod authorisation_tests { host: "127.0.0.1".to_string(), port: 8484, api_key: key.to_string(), + usage_key: "usage-only-secret".to_string(), keys: empty_store(), providers: HashMap::new(), default_provider: ProviderId::Xai, @@ -513,6 +551,19 @@ mod authorisation_tests { } } + fn request_at(method: &str, target: &str, headers: Vec<(&str, &str)>, body: &[u8]) -> Request { + Request { + method: method.to_string(), + target: target.to_string(), + version: "HTTP/1.1".to_string(), + headers: headers + .into_iter() + .map(|(name, value)| (name.to_string(), value.to_string())) + .collect(), + body: body.to_vec(), + } + } + fn health_request() -> Request { Request { method: "GET".to_string(), @@ -523,6 +574,118 @@ mod authorisation_tests { } } + #[test] + fn the_usage_secret_is_limited_to_the_exact_bearer_usage_get() { + let context = context_with_key("regular-secret"); + let valid = request_at( + "GET", + "/v1/usage", + vec![("Authorization", "Bearer usage-only-secret")], + &[], + ); + assert!(is_authorized(&context, &valid)); + + for request in [ + request_at( + "POST", + "/v1/usage", + vec![("Authorization", "Bearer usage-only-secret")], + &[], + ), + request_at("GET", "/v1/usage?key=usage-only-secret", vec![], &[]), + request_at( + "GET", + "/usage", + vec![("Authorization", "Bearer usage-only-secret")], + &[], + ), + request_at( + "GET", + "/v1/models", + vec![("Authorization", "Bearer usage-only-secret")], + &[], + ), + request_at( + "GET", + "/v1/usage", + vec![("X-Api-Key", "usage-only-secret")], + &[], + ), + request_at( + "GET", + "/v1/usage", + vec![("Authorization", "Bearer usage-only-secretx")], + &[], + ), + request_at( + "GET", + "/v1/usage", + vec![("Authorization", "Bearer sage-only-secret")], + &[], + ), + request_at( + "GET", + "/v1/usage", + vec![ + ("Authorization", "Bearer usage-only-secret"), + ("Content-Length", "1"), + ], + &[], + ), + request_at( + "GET", + "/v1/usage", + vec![ + ("Authorization", "Bearer usage-only-secret"), + ("Transfer-Encoding", "chunked"), + ], + &[], + ), + request_at( + "GET", + "/v1/usage", + vec![("Authorization", "Bearer usage-only-secret")], + b"body", + ), + ] { + assert!( + !is_authorized(&context, &request), + "scoped credential accepted an out-of-scope request" + ); + } + + // The same regular key keeps its existing full route scope and accepted presentations. + assert!(is_authorized( + &context, + &request_at( + "GET", + "/v1/models", + vec![("Authorization", "Bearer regular-secret")], + &[] + ), + )); + } + + #[test] + fn the_usage_secret_does_not_count_as_a_configured_client_key() { + let context = context_with_key(""); + let request = request_at( + "GET", + "/v1/usage", + vec![("Authorization", "Bearer usage-only-secret")], + &[], + ); + assert!(!keys_configured(&context)); + assert!(!is_authorized(&context, &request)); + assert_eq!( + pre_authorize(&request, &context) + .expect("no regular key") + .status, + 401 + ); + assert!(context.keys.is_empty()); + } + #[test] fn a_server_with_no_key_refuses_everything() { let context = context_with_key(""); @@ -678,6 +841,7 @@ mod authorisation_tests { host: "127.0.0.1".to_string(), port: 8484, api_key: String::new(), + usage_key: String::new(), keys: empty_store(), providers: HashMap::new(), default_provider: ProviderId::Xai, diff --git a/src/server/tests.rs b/src/server/tests.rs index fb948b9..2107824 100644 --- a/src/server/tests.rs +++ b/src/server/tests.rs @@ -402,6 +402,7 @@ fn harness_with_spec( host: "127.0.0.1".to_string(), port, api_key: api_key.to_string(), + usage_key: "server-test-usage-key".to_string(), keys: Arc::clone(&keys), providers, default_provider: spec.id, @@ -1358,6 +1359,39 @@ fn usage_route_is_authenticated_cached_and_attaches_fresh_inference_state() { ); } +#[test] +fn the_daemon_usage_credential_cannot_authorize_other_routes() { + let stub = Stub::start(|_| Reply::json(404, "{}")); + let harness = harness(&stub, "regular-client-key", "provider-token"); + let secret = "server-test-usage-key"; + + let usage = agent() + .get(harness.url("/v1/usage")) + .header("Authorization", &format!("Bearer {secret}")) + .call() + .expect("the scoped usage request answers"); + assert_eq!(usage.status(), 200); + + let models = agent() + .get(harness.url("/v1/models")) + .header("Authorization", &format!("Bearer {secret}")) + .call() + .expect("the proxy rejects out-of-scope credentials"); + assert_eq!(models.status(), 401); + + let inference = agent() + .post(harness.url("/v1/chat/completions")) + .header("Authorization", &format!("Bearer {secret}")) + .header("Content-Type", "application/json") + .send(chat_body().to_string()) + .expect("the proxy rejects the scoped credential"); + assert_eq!(inference.status(), 401); + assert!( + harness.keys.is_empty(), + "the runtime secret is not an issued client key" + ); +} + #[test] fn a_native_responses_request_is_forwarded_untouched() { // A Responses-only provider speaks the Responses API natively. A request diff --git a/src/server/usage.rs b/src/server/usage.rs index 36caf97..2c946eb 100644 --- a/src/server/usage.rs +++ b/src/server/usage.rs @@ -664,6 +664,7 @@ mod tests { host: "127.0.0.1".to_string(), port: 8484, api_key: "route-test-key".to_string(), + usage_key: String::new(), keys, providers: std::collections::HashMap::new(), default_provider: ProviderId::Xai, diff --git a/src/usage_key.rs b/src/usage_key.rs new file mode 100644 index 0000000..a48d819 --- /dev/null +++ b/src/usage_key.rs @@ -0,0 +1,545 @@ +//! Daemon-managed, route-scoped runtime credential for the CLI usage report. +//! +//! This secret is intentionally separate from the regular client-key store. +//! It is generated on every daemon start, stored only in a private runtime +//! file, and removed on graceful shutdown when the file still contains this +//! daemon's token. + +use std::fs::{self, File, OpenOptions}; +use std::io::{self, Read, Write}; +use std::path::{Path, PathBuf}; + +use base64::Engine; +use base64::engine::general_purpose::URL_SAFE_NO_PAD; +use rand::Rng; + +const TOKEN_BYTES: usize = 32; +const TOKEN_CHARS: usize = 43; +const TEMP_ATTEMPTS: usize = 8; + +/// A runtime usage secret and its cleanup lease. +pub(crate) struct UsageKey { + path: PathBuf, + token: String, +} + +impl UsageKey { + /// Generate and atomically persist a fresh daemon token. + pub(crate) fn create(path: impl Into) -> io::Result { + let path = path.into(); + let parent = path + .parent() + .filter(|p| !p.as_os_str().is_empty()) + .unwrap_or(Path::new(".")); + fs::create_dir_all(parent)?; + protect_path(parent, true)?; + + let token = generate_token(); + write_private_atomic(&path, token.as_bytes())?; + Ok(Self { path, token }) + } + + /// The exact bearer token held by the daemon. + pub(crate) fn token(&self) -> &str { + &self.token + } + + /// Read a bounded, correctly shaped token without including its contents in errors. + pub(crate) fn read(path: &Path) -> io::Result { + let file = File::open(path)?; + let metadata = file.metadata()?; + if metadata.len() != TOKEN_CHARS as u64 { + return Err(io::Error::new( + io::ErrorKind::InvalidData, + "invalid usage credential file", + )); + } + + let mut bytes = Vec::with_capacity(TOKEN_CHARS); + file.take((TOKEN_CHARS + 1) as u64) + .read_to_end(&mut bytes)?; + if !valid_token_bytes(&bytes) { + return Err(io::Error::new( + io::ErrorKind::InvalidData, + "invalid usage credential file", + )); + } + String::from_utf8(bytes).map_err(|_| { + io::Error::new(io::ErrorKind::InvalidData, "invalid usage credential file") + }) + } +} + +impl Drop for UsageKey { + fn drop(&mut self) { + let Ok(file) = File::open(&self.path) else { + return; + }; + let Ok(metadata) = file.metadata() else { + return; + }; + if metadata.len() != self.token.len() as u64 { + return; + } + let mut bytes = Vec::with_capacity(self.token.len()); + if file + .take((self.token.len() + 1) as u64) + .read_to_end(&mut bytes) + .is_err() + { + return; + } + if crate::keys::constant_time_eq(&bytes, self.token.as_bytes()) { + let _ = fs::remove_file(&self.path); + } + } +} + +fn generate_token() -> String { + let mut bytes = [0u8; TOKEN_BYTES]; + rand::rng().fill_bytes(&mut bytes); + URL_SAFE_NO_PAD.encode(bytes) +} + +fn valid_token_bytes(bytes: &[u8]) -> bool { + bytes.len() == TOKEN_CHARS + && bytes + .iter() + .all(|byte| byte.is_ascii_alphanumeric() || *byte == b'-' || *byte == b'_') +} + +fn write_private_atomic(path: &Path, bytes: &[u8]) -> io::Result<()> { + let parent = path + .parent() + .filter(|p| !p.as_os_str().is_empty()) + .unwrap_or(Path::new(".")); + let file_name = path.file_name().ok_or_else(|| { + io::Error::new( + io::ErrorKind::InvalidInput, + "usage credential path has no file name", + ) + })?; + + for _ in 0..TEMP_ATTEMPTS { + let temporary = parent.join(format!( + ".{}.tmp.{}.{}", + file_name.to_string_lossy(), + std::process::id(), + random_component(), + )); + let mut options = OpenOptions::new(); + options.write(true).create_new(true); + #[cfg(unix)] + { + use std::os::unix::fs::OpenOptionsExt; + options.mode(0o600); + } + + let mut file = match options.open(&temporary) { + Ok(file) => file, + Err(error) if error.kind() == io::ErrorKind::AlreadyExists => continue, + Err(error) => return Err(error), + }; + + let result = (|| { + // On Windows this installs a protected, current-user-only DACL + // before any token bytes are written. Unix uses mode 0600 above. + protect_path(&temporary, false)?; + file.write_all(bytes)?; + file.sync_all()?; + drop(file); + replace_file(&temporary, path) + })(); + if result.is_err() { + let _ = fs::remove_file(&temporary); + return result; + } + + // Persist the directory entry when the platform supports syncing it. + if let Ok(directory) = File::open(parent) { + let _ = directory.sync_all(); + } + return Ok(()); + } + + Err(io::Error::new( + io::ErrorKind::AlreadyExists, + "could not allocate a unique usage credential temporary file", + )) +} + +fn random_component() -> String { + let mut bytes = [0u8; 16]; + rand::rng().fill_bytes(&mut bytes); + URL_SAFE_NO_PAD.encode(bytes) +} + +#[cfg(unix)] +fn protect_path(path: &Path, directory: bool) -> io::Result<()> { + use std::os::unix::fs::PermissionsExt; + fs::set_permissions( + path, + fs::Permissions::from_mode(if directory { 0o700 } else { 0o600 }), + ) +} + +#[cfg(windows)] +fn protect_path(path: &Path, directory: bool) -> io::Result<()> { + use std::ffi::OsStr; + use std::iter::once; + use std::os::windows::ffi::OsStrExt; + use std::ptr::{null, null_mut}; + + use windows_sys::Win32::Foundation::{CloseHandle, LocalFree}; + use windows_sys::Win32::Security::Authorization::{ + ConvertSidToStringSidW, ConvertStringSecurityDescriptorToSecurityDescriptorW, + SDDL_REVISION_1, + }; + use windows_sys::Win32::Security::{ + DACL_SECURITY_INFORMATION, EqualSid, GetTokenInformation, + PROTECTED_DACL_SECURITY_INFORMATION, SetFileSecurityW, TOKEN_QUERY, TOKEN_USER, TokenUser, + }; + use windows_sys::Win32::System::Threading::{GetCurrentProcess, OpenProcessToken}; + + // SAFETY: the process pseudo-handle is valid and the output handle is writable. + let mut token_handle = null_mut(); + if unsafe { OpenProcessToken(GetCurrentProcess(), TOKEN_QUERY, &mut token_handle) } == 0 { + return Err(io::Error::last_os_error()); + } + struct TokenHandle(windows_sys::Win32::Foundation::HANDLE); + impl Drop for TokenHandle { + fn drop(&mut self) { + // SAFETY: this wrapper owns the handle returned by OpenProcessToken. + unsafe { CloseHandle(self.0) }; + } + } + let token_handle = TokenHandle(token_handle); + + let mut needed = 0u32; + // SAFETY: this is the documented size query; no output buffer is supplied. + unsafe { + GetTokenInformation(token_handle.0, TokenUser, null_mut(), 0, &mut needed); + } + if needed == 0 { + return Err(io::Error::last_os_error()); + } + let mut token_user = vec![0usize; (needed as usize).div_ceil(std::mem::size_of::())]; + // SAFETY: the aligned buffer is sized from the preceding TokenUser query. + if unsafe { + GetTokenInformation( + token_handle.0, + TokenUser, + token_user.as_mut_ptr().cast(), + needed, + &mut needed, + ) + } == 0 + { + return Err(io::Error::last_os_error()); + } + // SAFETY: GetTokenInformation filled a correctly aligned TOKEN_USER value. + let user = unsafe { &*token_user.as_ptr().cast::() }; + let mut sid_text = null_mut(); + // SAFETY: the SID came from the current process token and sid_text is writable. + if unsafe { ConvertSidToStringSidW(user.User.Sid, &mut sid_text) } == 0 { + return Err(io::Error::last_os_error()); + } + let sid = unsafe { + let mut length = 0usize; + while *sid_text.add(length) != 0 { + length += 1; + } + String::from_utf16_lossy(std::slice::from_raw_parts(sid_text, length)) + }; + // SAFETY: sid_text was allocated by ConvertSidToStringSidW. + unsafe { LocalFree(sid_text.cast()) }; + + let inheritance = if directory { "OICI" } else { "" }; + let descriptor_text: Vec = OsStr::new(&format!("D:P(A;{inheritance};FA;;;{sid})")) + .encode_wide() + .chain(once(0)) + .collect(); + let mut descriptor = null_mut(); + // SAFETY: descriptor_text is nul-terminated, descriptor is writable, and + // the descriptor is freed below with LocalFree. + if unsafe { + ConvertStringSecurityDescriptorToSecurityDescriptorW( + descriptor_text.as_ptr(), + SDDL_REVISION_1, + &mut descriptor, + null_mut(), + ) + } == 0 + { + return Err(io::Error::last_os_error()); + } + + let path_wide: Vec = path.as_os_str().encode_wide().chain(once(0)).collect(); + // SAFETY: both pointers remain valid for the call; the descriptor contains + // a protected DACL granting full access only to the current token's user SID. + let result = unsafe { + SetFileSecurityW( + path_wide.as_ptr(), + DACL_SECURITY_INFORMATION | PROTECTED_DACL_SECURITY_INFORMATION, + descriptor, + ) + }; + let error = (result == 0).then(io::Error::last_os_error); + // SAFETY: descriptor was allocated by the Windows SDDL conversion API. + unsafe { LocalFree(descriptor.cast()) }; + error.map_or(Ok(()), Err) +} + +#[cfg(not(any(unix, windows)))] +fn protect_path(_path: &Path, _directory: bool) -> io::Result<()> { + Err(io::Error::new( + io::ErrorKind::PermissionDenied, + "private usage credential permissions are unsupported on this platform", + )) +} + +#[cfg(unix)] +fn replace_file(from: &Path, to: &Path) -> io::Result<()> { + fs::rename(from, to) +} + +#[cfg(windows)] +fn replace_file(from: &Path, to: &Path) -> io::Result<()> { + use std::iter::once; + use std::os::windows::ffi::OsStrExt; + use windows_sys::Win32::Storage::FileSystem::{ + MOVEFILE_REPLACE_EXISTING, MOVEFILE_WRITE_THROUGH, MoveFileExW, + }; + + let from_wide: Vec = from.as_os_str().encode_wide().chain(once(0)).collect(); + let to_wide: Vec = to.as_os_str().encode_wide().chain(once(0)).collect(); + // SAFETY: both paths are valid nul-terminated UTF-16 strings. The replace + // flag gives rotation atomic replacement semantics on Windows. + if unsafe { + MoveFileExW( + from_wide.as_ptr(), + to_wide.as_ptr(), + MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH, + ) + } == 0 + { + Err(io::Error::last_os_error()) + } else { + Ok(()) + } +} + +#[cfg(not(any(unix, windows)))] +fn replace_file(from: &Path, to: &Path) -> io::Result<()> { + fs::rename(from, to) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn rotation_replaces_the_token_and_old_cleanup_cannot_remove_it() { + let directory = tempfile::tempdir().unwrap(); + let path = directory.path().join("usage.key"); + let first = UsageKey::create(&path).unwrap(); + let first_token = first.token().to_owned(); + assert!(valid_token_bytes(first_token.as_bytes())); + assert!(crate::keys::constant_time_eq( + UsageKey::read(&path).unwrap().as_bytes(), + first_token.as_bytes() + )); + + let second = UsageKey::create(&path).unwrap(); + let second_token = second.token().to_owned(); + assert!( + !crate::keys::constant_time_eq(first_token.as_bytes(), second_token.as_bytes()), + "daemon starts rotate the usage credential" + ); + + drop(first); + assert!(crate::keys::constant_time_eq( + UsageKey::read(&path).unwrap().as_bytes(), + second_token.as_bytes() + )); + drop(second); + assert!(!path.exists(), "matching graceful cleanup removes the file"); + } + + #[test] + fn a_failed_private_file_creation_is_reported() { + let directory = tempfile::tempdir().unwrap(); + let not_a_directory = directory.path().join("file"); + fs::write(¬_a_directory, "not a directory").unwrap(); + let error = UsageKey::create(not_a_directory.join("usage.key")) + .err() + .expect("creation under a file fails"); + assert_ne!(error.kind(), io::ErrorKind::NotFound); + } + + #[cfg(unix)] + #[test] + fn the_directory_and_secret_file_are_owner_only() { + use std::os::unix::fs::PermissionsExt; + + let directory = tempfile::tempdir().unwrap(); + let data = directory.path().join("eggpass"); + let path = data.join("usage.key"); + let key = UsageKey::create(&path).unwrap(); + let dir_mode = fs::metadata(&data).unwrap().permissions().mode() & 0o777; + let file_mode = fs::metadata(&path).unwrap().permissions().mode() & 0o777; + assert_eq!(dir_mode, 0o700); + assert_eq!(file_mode, 0o600); + drop(key); + } + + #[cfg(windows)] + #[test] + fn the_directory_and_secret_file_have_current_user_only_dacls() { + let directory = tempfile::tempdir().unwrap(); + let data = directory.path().join("eggpass"); + let path = data.join("usage.key"); + let key = UsageKey::create(&path).unwrap(); + assert!(windows_acl_is_current_user_only(&data, true)); + assert!(windows_acl_is_current_user_only(&path, false)); + drop(key); + } + + #[cfg(windows)] + fn windows_acl_is_current_user_only(path: &Path, directory: bool) -> bool { + use std::iter::once; + use std::os::windows::ffi::OsStrExt; + use std::ptr::null_mut; + use windows_sys::Win32::Foundation::CloseHandle; + use windows_sys::Win32::Security::{ + ACCESS_ALLOWED_ACE, ACCESS_ALLOWED_ACE_TYPE, ACL_SIZE_INFORMATION, AclSizeInformation, + CONTAINER_INHERIT_ACE, DACL_SECURITY_INFORMATION, EqualSid, GetAce, GetAclInformation, + GetFileSecurityW, GetSecurityDescriptorDacl, GetTokenInformation, OBJECT_INHERIT_ACE, + TOKEN_QUERY, TOKEN_USER, TokenUser, + }; + use windows_sys::Win32::System::Threading::{GetCurrentProcess, OpenProcessToken}; + + let path_wide: Vec = path.as_os_str().encode_wide().chain(once(0)).collect(); + let mut required = 0u32; + // SAFETY: size query for the DACL security descriptor. + unsafe { + GetFileSecurityW( + path_wide.as_ptr(), + DACL_SECURITY_INFORMATION, + null_mut(), + 0, + &mut required, + ) + }; + if required == 0 { + return false; + } + let mut descriptor = + vec![0usize; (required as usize).div_ceil(std::mem::size_of::())]; + // SAFETY: the aligned descriptor buffer has the required size. + if unsafe { + GetFileSecurityW( + path_wide.as_ptr(), + DACL_SECURITY_INFORMATION, + descriptor.as_mut_ptr().cast(), + required, + &mut required, + ) + } == 0 + { + return false; + } + let mut dacl_present = 0; + let mut dacl = null_mut(); + let mut dacl_defaulted = 0; + // SAFETY: descriptor contains the DACL requested above. + if unsafe { + GetSecurityDescriptorDacl( + descriptor.as_mut_ptr().cast(), + &mut dacl_present, + &mut dacl, + &mut dacl_defaulted, + ) + } == 0 + || dacl_present == 0 + || dacl.is_null() + { + return false; + } + let mut acl_info = ACL_SIZE_INFORMATION { + AceCount: 0, + AclBytesInUse: 0, + AclBytesFree: 0, + }; + // SAFETY: dacl is valid and acl_info is writable. + if unsafe { + GetAclInformation( + dacl, + (&mut acl_info as *mut ACL_SIZE_INFORMATION).cast(), + std::mem::size_of::() as u32, + AclSizeInformation, + ) + } == 0 + || acl_info.AceCount != 1 + { + return false; + } + let mut ace_ptr = null_mut(); + // SAFETY: index 0 exists because AceCount is one. + if unsafe { GetAce(dacl, 0, &mut ace_ptr) } == 0 || ace_ptr.is_null() { + return false; + } + let ace = unsafe { &*ace_ptr.cast::() }; + let ace_sid = (&ace.SidStart as *const u32).cast_mut().cast(); + + let mut token = null_mut(); + // SAFETY: the process pseudo-handle is valid and token output is writable. + if unsafe { OpenProcessToken(GetCurrentProcess(), TOKEN_QUERY, &mut token) } == 0 { + return false; + } + let mut needed = 0u32; + // SAFETY: size query for TokenUser. + unsafe { GetTokenInformation(token, TokenUser, null_mut(), 0, &mut needed) }; + if needed == 0 { + unsafe { CloseHandle(token) }; + return false; + } + let mut user_buffer = + vec![0usize; (needed as usize).div_ceil(std::mem::size_of::())]; + // SAFETY: the aligned buffer has the queried size. + if unsafe { + GetTokenInformation( + token, + TokenUser, + user_buffer.as_mut_ptr().cast(), + needed, + &mut needed, + ) + } == 0 + { + unsafe { CloseHandle(token) }; + return false; + } + let user = unsafe { &*user_buffer.as_ptr().cast::() }; + let same_user = unsafe { EqualSid(ace_sid, user.User.Sid) } != 0; + unsafe { CloseHandle(token) }; + let expected_flags = if directory { + OBJECT_INHERIT_ACE | CONTAINER_INHERIT_ACE + } else { + 0 + }; + same_user + && ace.Header.AceType == ACCESS_ALLOWED_ACE_TYPE + && ace.Header.AceFlags == expected_flags + } + + #[test] + fn invalid_usage_file_is_rejected_without_echoing_contents() { + let directory = tempfile::tempdir().unwrap(); + let path = directory.path().join("usage.key"); + fs::write(&path, "not-a-token").unwrap(); + let error = UsageKey::read(&path).unwrap_err(); + assert_eq!(error.kind(), io::ErrorKind::InvalidData); + assert_eq!(error.to_string(), "invalid usage credential file"); + } +} From 34ec6f52a2d42d10fbdef07e3d5ad5ef01f75162 Mon Sep 17 00:00:00 2001 From: dbowm91 Date: Thu, 19 Nov 2026 18:31:46 +0000 Subject: [PATCH 6/7] fix: complete usage-only credential integration --- src/cli/commands/usage.rs | 792 +++++++++++++++++++++++++++++++++-- src/provider/mod.rs | 10 + src/provider/usage/mod.rs | 18 +- src/provider/usage/openai.rs | 2 +- src/provider/usage/report.rs | 8 +- src/usage_key.rs | 21 +- 6 files changed, 800 insertions(+), 51 deletions(-) diff --git a/src/cli/commands/usage.rs b/src/cli/commands/usage.rs index 7d68345..0f05efe 100644 --- a/src/cli/commands/usage.rs +++ b/src/cli/commands/usage.rs @@ -22,6 +22,12 @@ //! to the provider and stops there. use std::collections::{BTreeMap, BTreeSet}; +use std::io::{self, IsTerminal, Write}; +use std::sync::{ + Arc, + atomic::{AtomicBool, Ordering}, +}; +use std::thread::{self, JoinHandle}; use std::time::Duration; use crate::cli::{CommandError, Context}; @@ -32,6 +38,8 @@ use crate::provider::usage::report::{ProviderEntry, UsageReportJson, enabled_pro use crate::provider::usage::{ProviderUsage, UsageReport, WindowLabel}; use crate::provider::{ProviderId, ProviderRuntime}; use crate::timeutil; +use crate::usage_key::UsageKey; +use serde::Deserialize; /// The width of the label column, so every value starts in the same place. const LABEL_WIDTH: usize = 12; @@ -51,6 +59,74 @@ const EMPTY: char = '░'; /// How far past a reset time a window counts as stale, in seconds. const STALE_AFTER: i64 = 3_600; +/// Shows progress while provider usage requests are in flight. +/// +/// The spinner is deliberately sent to an interactive stderr only, so piping +/// either output format remains clean. Its worker erases only its own line +/// before returning control to the report output. +struct UsageSpinner { + running: Option>, + worker: Option>, +} + +impl UsageSpinner { + fn start(message: &'static str) -> Self { + if !io::stderr().is_terminal() { + return Self { + running: None, + worker: None, + }; + } + + let running = Arc::new(AtomicBool::new(true)); + let thread_running = Arc::clone(&running); + let worker = thread::Builder::new() + .name("eggpass-usage-spinner".to_string()) + .spawn(move || { + const FRAMES: [&str; 10] = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]; + + // Avoid flashing the spinner when a request finishes quickly. + thread::sleep(Duration::from_millis(120)); + + let mut stderr = io::stderr().lock(); + let mut frame = 0; + let mut displayed = false; + while thread_running.load(Ordering::Acquire) { + if write!(stderr, "\r\x1b[2K{} {message}", FRAMES[frame]).is_err() + || stderr.flush().is_err() + { + break; + } + displayed = true; + frame = (frame + 1) % FRAMES.len(); + thread::sleep(Duration::from_millis(80)); + } + + if displayed { + let _ = write!(stderr, "\r\x1b[2K"); + let _ = stderr.flush(); + } + }) + .ok(); + + Self { + running: Some(running), + worker, + } + } +} + +impl Drop for UsageSpinner { + fn drop(&mut self) { + if let Some(running) = self.running.take() { + running.store(false, Ordering::Release); + } + if let Some(worker) = self.worker.take() { + let _ = worker.join(); + } + } +} + /// Show how much of the subscription allowance remains. pub fn usage( context: &Context, @@ -59,33 +135,30 @@ pub fn usage( ) -> Result<(), CommandError> { let providers = selected_provider_ids(provider, &context.config)?; - // What the last inference to each provider was answered with. The daemon - // keeps it in memory, so there is nothing to read when it is not - // running. - let inferences = last_inferences(context); + let spinner = UsageSpinner::start("Fetching usage metrics"); - let entries: Vec = providers - .into_iter() - .map(|provider| { + let cached = try_cached_usage(context, &providers); + let (entries, stale) = report_with_fallback( + &providers, + cached, + || last_inferences(context), + |provider| { let (outcome, source) = collect_one(context, provider); ProviderEntry { provider, outcome, - // The source is distinct from `caption`: a source identifies - // which account supplied the snapshot, while a caption names - // the pool the quota belongs to. + // A source identifies which account supplied the snapshot; the caption names the quota pool. source, - // The caption travels with the report, in the JSON as well as in - // the bars: a machine-readable number without it is as misleading - // as a number without it on the terminal. caption: caption_for(provider, &context.config), - // The last inference is the only evidence there is about a - // provider that publishes no quota of its own. - last_inference: inferences.get(&provider).copied(), + last_inference: None, } - }) - .collect(); + }, + )?; + drop(spinner); + if stale { + let _ = write_stale_cache_notice(&mut io::stderr().lock(), true); + } if json { let report = UsageReportJson { providers: &entries, @@ -124,6 +197,252 @@ fn selected_provider_ids( } } +#[derive(Deserialize)] +struct UsageReportResponse { + providers: Vec, +} + +#[derive(Debug)] +struct CachedUsageReport { + entries: Vec, + stale: bool, +} + +enum DaemonUsageResponse { + Cached(CachedUsageReport), + NotFound, + Status { + status: u16, + retry_after: Option, + }, +} + +enum DaemonFetchError { + Transport, + InvalidResponse, +} + +const MAX_DAEMON_USAGE_BODY: u64 = 1024 * 1024; + +/// Try the daemon's report before collecting directly from providers. +fn try_cached_usage( + context: &Context, + providers: &[ProviderId], +) -> Result, CommandError> { + let state = daemon::state( + &context.paths.pid_file(), + &context.config.host, + context.config.port, + ); + try_cached_usage_with( + state, + &context.paths.usage_key_file(), + providers, + fetch_daemon_usage, + || { + daemon::state( + &context.paths.pid_file(), + &context.config.host, + context.config.port, + ) + }, + ) +} + +/// State machine kept injectable so all fallback branches can be tested locally. +fn try_cached_usage_with( + initial_state: DaemonState, + key_path: &std::path::Path, + providers: &[ProviderId], + mut fetch: F, + mut recheck_state: S, +) -> Result, CommandError> +where + F: FnMut(&str, u16, &str, &[ProviderId]) -> Result, + S: FnMut() -> DaemonState, +{ + let DaemonState::Running { host, port, .. } = initial_state else { + return Ok(None); + }; + let Ok(secret) = UsageKey::read(key_path) else { + // A missing or unreadable runtime secret cannot authorize the daemon + // request. Preserve the direct collector as the safe compatibility path. + return Ok(None); + }; + + match fetch(daemon::probe_host(&host), port, &secret, providers) { + Ok(DaemonUsageResponse::Cached(report)) => Ok(Some(report)), + Ok(DaemonUsageResponse::NotFound) => Ok(None), + Ok(DaemonUsageResponse::Status { + status, + retry_after, + }) => Err(daemon_status_error(status, retry_after)), + Err(DaemonFetchError::InvalidResponse) => Err(CommandError::new( + "the daemon returned an invalid usage report; direct provider checks were not run", + )), + Err(DaemonFetchError::Transport) => match recheck_state() { + DaemonState::Stopped | DaemonState::Stale { .. } => Ok(None), + DaemonState::Running { .. } => Err(CommandError::new( + "the daemon still appears to be running but its usage endpoint could not be reached; check `eggpass status` or restart the daemon", + )), + }, + } +} + +fn daemon_status_error(status: u16, retry_after: Option) -> CommandError { + let retry = retry_after.map_or_else(String::new, |seconds| { + format!("; retry after at least {seconds} second(s)") + }); + if matches!(status, 202 | 503 | 504) { + return CommandError::new(format!( + "the daemon has no completed usage report available (HTTP {status}){retry}; direct provider checks were not run" + )); + } + if matches!(status, 401 | 403) { + return CommandError::new(format!( + "the daemon rejected the usage-only credential (HTTP {status}); restart the daemon and retry `eggpass usage`" + )); + } + CommandError::new(format!( + "the daemon usage request failed with HTTP {status}{retry}; direct provider checks were not run" + )) +} + +fn fetch_daemon_usage( + host: &str, + port: u16, + secret: &str, + providers: &[ProviderId], +) -> Result { + fetch_daemon_usage_with_timeouts( + host, + port, + secret, + providers, + Duration::from_secs(2), + Duration::from_secs(35), + ) +} + +/// Fetch with injectable deadlines so the response timeout is testable locally. +fn fetch_daemon_usage_with_timeouts( + host: &str, + port: u16, + secret: &str, + providers: &[ProviderId], + connect_timeout: Duration, + total_timeout: Duration, +) -> Result { + let url = format!("http://{host}:{port}/v1/usage"); + let config = ureq::Agent::config_builder() + .http_status_as_error(false) + .proxy(None) + .timeout_connect(Some(connect_timeout)) + // The production total deadline includes the server's cold-cache wait. + .timeout_global(Some(total_timeout)) + .build(); + let agent = ureq::Agent::new_with_config(config); + let authorization = format!("Bearer {secret}"); + let response = agent + .get(&url) + .header("Authorization", &authorization) + .call() + .map_err(|_| DaemonFetchError::Transport)?; + let status = response.status().as_u16(); + if status == 404 { + return Ok(DaemonUsageResponse::NotFound); + } + let retry_after = response + .headers() + .get("Retry-After") + .and_then(|value| value.to_str().ok()) + .and_then(|value| value.parse::().ok()) + .filter(|seconds| *seconds > 0); + if status != 200 { + return Ok(DaemonUsageResponse::Status { + status, + retry_after, + }); + } + let stale = response + .headers() + .get("X-Eggpass-Usage-Stale") + .and_then(|value| value.to_str().ok()) + .is_some_and(|value| value.eq_ignore_ascii_case("true")); + let body = response + .into_body() + .with_config() + .limit(MAX_DAEMON_USAGE_BODY + 1) + .read_to_vec() + .map_err(|_| DaemonFetchError::Transport)?; + if body.len() as u64 > MAX_DAEMON_USAGE_BODY { + return Err(DaemonFetchError::InvalidResponse); + } + let response: UsageReportResponse = + serde_json::from_slice(&body).map_err(|_| DaemonFetchError::InvalidResponse)?; + let entries = select_cached_entries(response.providers, providers) + .map_err(|_| DaemonFetchError::InvalidResponse)?; + Ok(DaemonUsageResponse::Cached(CachedUsageReport { + entries, + stale, + })) +} + +fn select_cached_entries( + entries: Vec, + selected: &[ProviderId], +) -> Result, ()> { + let mut by_provider = BTreeMap::new(); + for entry in entries { + if let ProviderUsage::Reported { report } = &entry.outcome + && report.provider != entry.provider + { + return Err(()); + } + if by_provider.insert(entry.provider, entry).is_some() { + return Err(()); + } + } + selected + .iter() + .map(|provider| by_provider.remove(provider).ok_or(())) + .collect() +} + +fn report_with_fallback( + providers: &[ProviderId], + cached: Result, CommandError>, + direct_inferences: impl FnOnce() -> BTreeMap, + mut direct_collect: C, +) -> Result<(Vec, bool), CommandError> +where + C: FnMut(ProviderId) -> ProviderEntry, +{ + if let Some(report) = cached? { + return Ok((report.entries, report.stale)); + } + let inferences = direct_inferences(); + let entries = providers + .iter() + .copied() + .map(|provider| { + let mut entry = direct_collect(provider); + entry.last_inference = inferences.get(&provider).copied(); + entry + }) + .collect(); + Ok((entries, false)) +} + +fn write_stale_cache_notice(writer: &mut impl Write, stale: bool) -> io::Result<()> { + if stale { + writeln!( + writer, + "warning: daemon usage cache is stale; showing its last successful report" + )?; + } + Ok(()) +} /// Decide the command status after output has been rendered. fn usage_exit_result(entries: &[ProviderEntry]) -> Result<(), CommandError> { // A provider that is not signed in still gets a block, so the output does @@ -167,7 +486,7 @@ fn caption_for(provider: ProviderId, config: &crate::config::Config) -> Option (ProviderUsage, Option<&'static str>) { +fn collect_one(context: &Context, provider: ProviderId) -> (ProviderUsage, Option) { let codex = (provider == ProviderId::OpenAi) .then(crate::provider::usage::codex_app_server::collect_detailed); collect_one_with_codex_collection(context, provider, codex) @@ -179,7 +498,7 @@ fn collect_one_with_codex_result( context: &Context, provider: ProviderId, codex_report: Option, -) -> (ProviderUsage, Option<&'static str>) { +) -> (ProviderUsage, Option) { let codex = (provider == ProviderId::OpenAi).then_some( crate::provider::usage::codex_app_server::CodexCollection { report: codex_report, @@ -193,7 +512,7 @@ fn collect_one_with_codex_collection( context: &Context, provider: ProviderId, codex: Option, -) -> (ProviderUsage, Option<&'static str>) { +) -> (ProviderUsage, Option) { let runtime = ProviderRuntime::new(provider, &context.config, &context.paths); let collected = crate::provider::usage::report::collect_entry( provider, @@ -226,7 +545,7 @@ fn render_block(out: &mut String, entry: &ProviderEntry) { entry.provider, report, entry.caption.as_deref(), - entry.source, + entry.source.as_deref(), ), ProviderUsage::NotSignedIn => { out.push_str(entry.provider.display_name()); @@ -262,7 +581,7 @@ fn render_block(out: &mut String, entry: &ProviderEntry) { out.push('\n'); } if !signals.is_empty() { - out.push_str(&field("Signals", signals[0])); + out.push_str(&field("Signals", &signals[0])); out.push('\n'); for signal in &signals[1..] { out.push_str(&continuation(signal)); @@ -735,9 +1054,9 @@ mod tests { source: Some("not exposed by OAuth".to_string()), hint: Some("https://chatgpt.com/settings/usage".to_string()), signals: vec![ - "429 subscription_sharing_usage_limit_exceeded", - "503 subscription_sharing_usage_unavailable", - "403 subscription_sharing_user_not_eligible", + "429 subscription_sharing_usage_limit_exceeded".to_string(), + "503 subscription_sharing_usage_unavailable".to_string(), + "403 subscription_sharing_user_not_eligible".to_string(), ], } } @@ -1240,7 +1559,7 @@ mod tests { assert!(matches!(&entry.outcome, ProviderUsage::Reported { .. })); assert_eq!( entry.source, - Some(crate::provider::usage::codex_app_server::SOURCE_LABEL) + Some(crate::provider::usage::codex_app_server::SOURCE_LABEL.to_string()) ); assert!(usage_exit_result(std::slice::from_ref(&entry)).is_ok()); } @@ -1312,7 +1631,7 @@ mod tests { outcome: ProviderUsage::Reported { report: codex_report(), }, - source: Some(crate::provider::usage::codex_app_server::SOURCE_LABEL), + source: Some(crate::provider::usage::codex_app_server::SOURCE_LABEL.to_string()), caption: None, last_inference: None, }; @@ -1440,3 +1759,420 @@ mod tests { assert!(!text.contains("Primary"), "{text}"); } } + +#[cfg(test)] +mod daemon_cache_tests { + use super::*; + use std::io::{BufRead, BufReader, Write}; + use std::net::TcpListener; + use std::path::PathBuf; + use std::sync::atomic::{AtomicUsize, Ordering}; + use std::sync::mpsc::{self, Receiver}; + + struct HttpStub { + port: u16, + request: Receiver, + } + + fn http_stub(status: u16, body: String, headers: &[(&str, &str)]) -> HttpStub { + let listener = TcpListener::bind("127.0.0.1:0").expect("bind local stub"); + let port = listener.local_addr().expect("local stub address").port(); + let (send, request) = mpsc::channel(); + let headers: Vec<(String, String)> = headers + .iter() + .map(|(name, value)| ((*name).to_string(), (*value).to_string())) + .collect(); + std::thread::spawn(move || { + let (mut stream, _) = listener.accept().expect("accept local request"); + let mut reader = BufReader::new(stream.try_clone().expect("clone stream")); + let mut raw_request = String::new(); + loop { + let mut line = String::new(); + reader.read_line(&mut line).expect("read request head"); + if line.is_empty() || line == "\r\n" { + break; + } + raw_request.push_str(&line); + } + let _ = send.send(raw_request); + let mut response = + format!("HTTP/1.1 {status} Stub\r\nContent-Type: application/json\r\n"); + for (name, value) in headers { + response.push_str(&format!("{name}: {value}\r\n")); + } + response.push_str(&format!( + "Content-Length: {}\r\nConnection: close\r\n\r\n{body}", + body.len() + )); + stream + .write_all(response.as_bytes()) + .expect("write stub response"); + stream.flush().expect("flush stub response"); + }); + HttpStub { port, request } + } + + fn running(port: u16) -> DaemonState { + DaemonState::Running { + pid: 1, + host: "127.0.0.1".to_string(), + port, + } + } + + fn sample_entry(provider: ProviderId, last_inference: Option) -> ProviderEntry { + ProviderEntry { + provider, + outcome: ProviderUsage::Reported { + report: UsageReport { + provider, + plan: Some("test plan".to_string()), + windows: Vec::new(), + breakdown: Vec::new(), + credits: None, + state: None, + }, + }, + source: None, + caption: None, + last_inference, + } + } + + fn report_body(entries: &[ProviderEntry]) -> String { + serde_json::to_string(&UsageReportJson { providers: entries }).expect("serialize fixture") + } + + fn usage_key_path(directory: &tempfile::TempDir) -> (PathBuf, UsageKey) { + let path = directory.path().join("usage.key"); + let key = UsageKey::create(&path).expect("create test usage key"); + (path, key) + } + + fn fetch_local( + host: &str, + port: u16, + secret: &str, + selected: &[ProviderId], + ) -> Result { + fetch_daemon_usage(host, port, secret, selected) + } + + #[test] + fn a_fresh_daemon_report_uses_the_bearer_header_and_skips_direct_collection() { + let directory = tempfile::tempdir().unwrap(); + let (key_path, key) = usage_key_path(&directory); + let body = report_body(&[sample_entry(ProviderId::Xai, Some(429))]); + let stub = http_stub(200, body, &[]); + let cached = try_cached_usage_with( + running(stub.port), + &key_path, + &[ProviderId::Xai], + fetch_local, + || running(stub.port), + ) + .expect("daemon response parses"); + + let raw_request = stub.request.recv_timeout(Duration::from_secs(2)).unwrap(); + let mut lines = raw_request.lines(); + assert_eq!(lines.next(), Some("GET /v1/usage HTTP/1.1")); + let authorization = lines + .find_map(|line| { + let (name, value) = line.split_once(':')?; + name.eq_ignore_ascii_case("authorization") + .then_some(value.trim()) + }) + .unwrap_or_default(); + let expected = format!("Bearer {}", key.token()); + assert!(crate::keys::constant_time_eq( + authorization.as_bytes(), + expected.as_bytes() + )); + assert!( + !raw_request + .lines() + .next() + .unwrap_or_default() + .contains(key.token()) + ); + + let direct_calls = AtomicUsize::new(0); + let (entries, stale) = report_with_fallback( + &[ProviderId::Xai], + Ok(cached), + || panic!("cache hit must not fetch last-inference separately"), + |provider| { + direct_calls.fetch_add(1, Ordering::SeqCst); + sample_entry(provider, None) + }, + ) + .expect("cached report selected"); + assert!(!stale); + assert_eq!(direct_calls.load(Ordering::SeqCst), 0); + assert_eq!(entries[0].last_inference, Some(429)); + } + + #[test] + fn a_stale_cached_report_warns_on_stderr_without_changing_json_stdout() { + let directory = tempfile::tempdir().unwrap(); + let (key_path, _key) = usage_key_path(&directory); + let body = report_body(&[sample_entry(ProviderId::Xai, Some(503))]); + let stub = http_stub(200, body, &[("X-Eggpass-Usage-Stale", "true")]); + let cached = try_cached_usage_with( + running(stub.port), + &key_path, + &[ProviderId::Xai], + fetch_local, + || running(stub.port), + ) + .expect("stale response is valid"); + assert!(stub.request.recv_timeout(Duration::from_secs(2)).is_ok()); + + let (entries, stale) = report_with_fallback( + &[ProviderId::Xai], + Ok(cached), + BTreeMap::new, + sample_entry_with_no_inference, + ) + .unwrap(); + let mut stderr = Vec::new(); + write_stale_cache_notice(&mut stderr, stale).unwrap(); + let stdout = serde_json::to_string_pretty(&UsageReportJson { + providers: &entries, + }) + .unwrap(); + let stderr = String::from_utf8(stderr).unwrap(); + assert!(stderr.contains("cache is stale")); + assert!(!stdout.contains("cache is stale")); + let value: serde_json::Value = serde_json::from_str(&stdout).unwrap(); + assert_eq!(value["providers"][0]["last_inference"], 503); + } + + fn sample_entry_with_no_inference(provider: ProviderId) -> ProviderEntry { + sample_entry(provider, None) + } + + #[test] + fn route_404_falls_back_but_pending_cooldown_and_auth_errors_do_not() { + let directory = tempfile::tempdir().unwrap(); + let (key_path, _key) = usage_key_path(&directory); + + let not_found = http_stub(404, "{}".to_string(), &[]); + let fallback = try_cached_usage_with( + running(not_found.port), + &key_path, + &[ProviderId::Xai], + fetch_local, + || running(not_found.port), + ) + .unwrap(); + assert!(fallback.is_none()); + assert!( + not_found + .request + .recv_timeout(Duration::from_secs(2)) + .is_ok() + ); + + for (status, retry_after) in [ + (202, Some("3")), + (503, Some("7")), + (504, Some("11")), + (401, None), + (403, None), + ] { + let headers: Vec<(&str, &str)> = retry_after + .into_iter() + .map(|value| ("Retry-After", value)) + .collect(); + let stub = http_stub(status, "{}".to_string(), &headers); + let result = try_cached_usage_with( + running(stub.port), + &key_path, + &[ProviderId::Xai], + fetch_local, + || running(stub.port), + ); + let error = result.expect_err("non-404 statuses are surfaced"); + let message = error.message.unwrap_or_default(); + assert!(message.contains(&status.to_string())); + if let Some(seconds) = retry_after { + assert!(message.contains(seconds)); + } + assert!(!message.contains("usage.key")); + assert!(stub.request.recv_timeout(Duration::from_secs(2)).is_ok()); + + let direct_calls = AtomicUsize::new(0); + let direct_error = report_with_fallback( + &[ProviderId::Xai], + Err(CommandError::new(message)), + || panic!("error must not query the direct fallback"), + |provider| { + direct_calls.fetch_add(1, Ordering::SeqCst); + sample_entry(provider, None) + }, + ); + assert!(direct_error.is_err()); + assert_eq!(direct_calls.load(Ordering::SeqCst), 0); + } + } + + #[test] + fn malformed_success_is_visible_and_never_bypassed() { + let directory = tempfile::tempdir().unwrap(); + let (key_path, _key) = usage_key_path(&directory); + let stub = http_stub(200, "provider identity secret".to_string(), &[]); + let result = try_cached_usage_with( + running(stub.port), + &key_path, + &[ProviderId::Xai], + fetch_local, + || running(stub.port), + ); + let error = result.expect_err("malformed JSON must fail"); + let message = error.message.unwrap_or_default(); + assert!(message.contains("invalid usage report")); + assert!(!message.contains("provider identity secret")); + assert!(stub.request.recv_timeout(Duration::from_secs(2)).is_ok()); + } + + #[test] + fn a_silent_daemon_response_hits_the_configured_deadline() { + use std::time::Instant; + + let listener = TcpListener::bind("127.0.0.1:0").expect("bind silent local stub"); + let port = listener.local_addr().expect("silent stub address").port(); + let server = std::thread::spawn(move || { + let (stream, _) = listener.accept().expect("accept local request"); + let mut reader = BufReader::new(stream); + let mut line = String::new(); + loop { + line.clear(); + reader.read_line(&mut line).expect("read request head"); + if line.is_empty() || line == "\r\n" { + break; + } + } + std::thread::sleep(Duration::from_millis(200)); + }); + + let started = Instant::now(); + let result = fetch_daemon_usage_with_timeouts( + "127.0.0.1", + port, + "test-only-secret", + &[ProviderId::Xai], + Duration::from_secs(1), + Duration::from_millis(50), + ); + assert!(matches!(result, Err(DaemonFetchError::Transport))); + assert!(started.elapsed() < Duration::from_secs(1)); + server.join().expect("silent stub finishes"); + } + + #[test] + fn direct_fallback_occurs_only_for_missing_state_or_stale_connection() { + let directory = tempfile::tempdir().unwrap(); + let missing = directory.path().join("missing.key"); + let fetch_calls = AtomicUsize::new(0); + let mut rechecks = 0; + let absent_key = try_cached_usage_with( + running(1), + &missing, + &[ProviderId::Xai], + |_, _, _, _| { + fetch_calls.fetch_add(1, Ordering::SeqCst); + Err(DaemonFetchError::Transport) + }, + || { + rechecks += 1; + DaemonState::Stopped + }, + ) + .unwrap(); + assert!(absent_key.is_none()); + assert_eq!(fetch_calls.load(Ordering::SeqCst), 0); + assert_eq!(rechecks, 0); + + let malformed = directory.path().join("malformed.key"); + std::fs::write(&malformed, "not-a-usage-token").unwrap(); + let unreadable_key = try_cached_usage_with( + running(1), + &malformed, + &[ProviderId::Xai], + |_, _, _, _| panic!("an invalid key file must not reach the daemon"), + || panic!("an invalid key file does not need a daemon-state recheck"), + ) + .unwrap(); + assert!(unreadable_key.is_none()); + let direct_calls = AtomicUsize::new(0); + let (entries, _) = report_with_fallback( + &[ProviderId::Xai], + Ok(unreadable_key), + BTreeMap::new, + |provider| { + direct_calls.fetch_add(1, Ordering::SeqCst); + sample_entry_with_no_inference(provider) + }, + ) + .unwrap(); + assert_eq!(entries.len(), 1); + assert_eq!(direct_calls.load(Ordering::SeqCst), 1); + + let (key_path, _key) = usage_key_path(&directory); + let stale = try_cached_usage_with( + running(1), + &key_path, + &[ProviderId::Xai], + |_, _, _, _| Err(DaemonFetchError::Transport), + || DaemonState::Stale { pid: 1 }, + ) + .unwrap(); + assert!(stale.is_none()); + + let still_running = try_cached_usage_with( + running(1), + &key_path, + &[ProviderId::Xai], + |_, _, _, _| Err(DaemonFetchError::Transport), + || running(1), + ); + assert!(still_running.is_err()); + + for state in [DaemonState::Stopped, DaemonState::Stale { pid: 1 }] { + let fallback = try_cached_usage_with( + state, + &key_path, + &[ProviderId::Xai], + |_, _, _, _| panic!("no request when daemon is not running"), + || DaemonState::Stopped, + ) + .unwrap(); + let direct_calls = AtomicUsize::new(0); + let (entries, _) = report_with_fallback( + &[ProviderId::Xai], + Ok(fallback), + BTreeMap::new, + |provider| { + direct_calls.fetch_add(1, Ordering::SeqCst); + sample_entry_with_no_inference(provider) + }, + ) + .unwrap(); + assert_eq!(entries.len(), 1); + assert_eq!(direct_calls.load(Ordering::SeqCst), 1); + } + } + + #[test] + fn provider_selection_is_applied_to_the_cached_report() { + let entries = vec![ + sample_entry(ProviderId::Xai, Some(200)), + sample_entry(ProviderId::OpenAi, Some(429)), + ]; + let selected = select_cached_entries(entries, &[ProviderId::OpenAi]).unwrap(); + assert_eq!(selected.len(), 1); + assert_eq!(selected[0].provider, ProviderId::OpenAi); + assert_eq!(selected[0].last_inference, Some(429)); + } +} diff --git a/src/provider/mod.rs b/src/provider/mod.rs index 573a5f9..5ffefb6 100644 --- a/src/provider/mod.rs +++ b/src/provider/mod.rs @@ -30,6 +30,16 @@ impl serde::Serialize for ProviderId { } } +impl<'de> serde::Deserialize<'de> for ProviderId { + fn deserialize(deserializer: D) -> Result + where + D: serde::Deserializer<'de>, + { + let value = ::deserialize(deserializer)?; + Self::parse(&value).ok_or_else(|| serde::de::Error::custom("unknown provider")) + } +} + impl ProviderId { /// The identifier used in configuration and on disk. pub fn as_str(self) -> &'static str { diff --git a/src/provider/usage/mod.rs b/src/provider/usage/mod.rs index 247e1b3..2b36c92 100644 --- a/src/provider/usage/mod.rs +++ b/src/provider/usage/mod.rs @@ -27,7 +27,7 @@ pub mod openai; pub mod report; pub mod xai; -use serde::Serialize; +use serde::{Deserialize, Serialize}; use crate::provider::ProviderId; @@ -41,7 +41,7 @@ pub struct ProviderCollection { } /// What a provider can say about its own allowance. -#[derive(Debug, Clone, Serialize)] +#[derive(Debug, Clone, Deserialize, Serialize)] pub struct UsageReport { /// The provider the report is about. pub provider: ProviderId, @@ -71,7 +71,7 @@ impl UsageReport { } /// One quota window. -#[derive(Debug, Clone, Serialize)] +#[derive(Debug, Clone, Deserialize, Serialize)] pub struct QuotaWindow { /// The label the window is printed under. pub label: WindowLabel, @@ -86,7 +86,7 @@ pub struct QuotaWindow { } /// The name of a quota window. -#[derive(Debug, Clone, Serialize)] +#[derive(Debug, Clone, Deserialize, Serialize)] // The normalised model names every window kind a provider may report, so a // second provider does not have to change the model to add one. Only the // kinds a provider actually reports are built today. @@ -119,7 +119,7 @@ impl WindowLabel { } /// A product's share of the same allowance. -#[derive(Debug, Clone, Serialize)] +#[derive(Debug, Clone, Deserialize, Serialize)] pub struct ProductUsage { /// The product id, as the provider spells it. pub product: String, @@ -130,7 +130,7 @@ pub struct ProductUsage { } /// Purchased credit. -#[derive(Debug, Clone, Serialize)] +#[derive(Debug, Clone, Deserialize, Serialize)] pub struct Credits { /// A prepaid balance, in cents. pub prepaid_cents: Option, @@ -144,7 +144,7 @@ pub struct Credits { /// /// An explicit state is the provider's answer, and it takes precedence over /// a calculated percentage. -#[derive(Debug, Clone, Serialize, PartialEq, Eq)] +#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq)] #[serde(rename_all = "snake_case")] // The mechanism names every state a provider may report. Only the ones the // providers report today are built; the rest wait for a field that says so. @@ -170,7 +170,7 @@ impl QuotaState { } /// What one provider had to say. -#[derive(Debug, Clone, Serialize)] +#[derive(Debug, Clone, Deserialize, Serialize)] #[serde(tag = "status", rename_all = "snake_case")] pub enum ProviderUsage { /// The provider reported usage. @@ -193,7 +193,7 @@ pub enum ProviderUsage { /// Where the user can see it, when there is such a place. hint: Option, /// The error codes the provider does publish, when it publishes any. - signals: Vec<&'static str>, + signals: Vec, }, /// The attempt failed. Failed { diff --git a/src/provider/usage/openai.rs b/src/provider/usage/openai.rs index e339dc2..54523b0 100644 --- a/src/provider/usage/openai.rs +++ b/src/provider/usage/openai.rs @@ -56,7 +56,7 @@ pub fn unavailable() -> ProviderUsage { reason: "Sign in with ChatGPT does not expose a quota API".to_string(), source: Some(SOURCE.to_string()), hint: Some(USAGE_PAGE.to_string()), - signals: SIGNALS.to_vec(), + signals: SIGNALS.iter().map(|signal| (*signal).to_string()).collect(), } } diff --git a/src/provider/usage/report.rs b/src/provider/usage/report.rs index 36a9db2..ae5817e 100644 --- a/src/provider/usage/report.rs +++ b/src/provider/usage/report.rs @@ -1,6 +1,6 @@ //! Shared machine-readable usage report assembly for the CLI and daemon API. -use serde::Serialize; +use serde::{Deserialize, Serialize}; use crate::auth::refresh::TokenManager; use crate::config::{Timeouts, Upstream}; @@ -8,13 +8,13 @@ use crate::provider::usage::{ProviderUsage, UsageReport, xai}; use crate::provider::{ProviderId, usage::codex_app_server::CodexCollection}; /// One provider's answer, with the provider it belongs to. -#[derive(Debug, Clone, Serialize)] +#[derive(Debug, Clone, Deserialize, Serialize)] pub(crate) struct ProviderEntry { pub provider: ProviderId, #[serde(flatten)] pub outcome: ProviderUsage, #[serde(skip_serializing_if = "Option::is_none")] - pub source: Option<&'static str>, + pub source: Option, pub caption: Option, pub last_inference: Option, } @@ -102,7 +102,7 @@ pub(crate) fn collect_entry( entry: ProviderEntry { provider, outcome, - source, + source: source.map(str::to_owned), caption: (provider == ProviderId::Xai).then(|| xai::caption(xai_upstream).to_string()), last_inference: None, }, diff --git a/src/usage_key.rs b/src/usage_key.rs index a48d819..3f0a768 100644 --- a/src/usage_key.rs +++ b/src/usage_key.rs @@ -188,7 +188,7 @@ fn protect_path(path: &Path, directory: bool) -> io::Result<()> { use std::ffi::OsStr; use std::iter::once; use std::os::windows::ffi::OsStrExt; - use std::ptr::{null, null_mut}; + use std::ptr::null_mut; use windows_sys::Win32::Foundation::{CloseHandle, LocalFree}; use windows_sys::Win32::Security::Authorization::{ @@ -196,8 +196,8 @@ fn protect_path(path: &Path, directory: bool) -> io::Result<()> { SDDL_REVISION_1, }; use windows_sys::Win32::Security::{ - DACL_SECURITY_INFORMATION, EqualSid, GetTokenInformation, - PROTECTED_DACL_SECURITY_INFORMATION, SetFileSecurityW, TOKEN_QUERY, TOKEN_USER, TokenUser, + DACL_SECURITY_INFORMATION, GetTokenInformation, PROTECTED_DACL_SECURITY_INFORMATION, + SetFileSecurityW, TOKEN_QUERY, TOKEN_USER, TokenUser, }; use windows_sys::Win32::System::Threading::{GetCurrentProcess, OpenProcessToken}; @@ -407,15 +407,18 @@ mod tests { #[cfg(windows)] fn windows_acl_is_current_user_only(path: &Path, directory: bool) -> bool { + // ACCESS_ALLOWED_ACE_TYPE is 0 in the Win32 security API. + const ACCESS_ALLOWED_ACE_TYPE: u8 = 0; + use std::iter::once; use std::os::windows::ffi::OsStrExt; use std::ptr::null_mut; use windows_sys::Win32::Foundation::CloseHandle; use windows_sys::Win32::Security::{ - ACCESS_ALLOWED_ACE, ACCESS_ALLOWED_ACE_TYPE, ACL_SIZE_INFORMATION, AclSizeInformation, - CONTAINER_INHERIT_ACE, DACL_SECURITY_INFORMATION, EqualSid, GetAce, GetAclInformation, - GetFileSecurityW, GetSecurityDescriptorDacl, GetTokenInformation, OBJECT_INHERIT_ACE, - TOKEN_QUERY, TOKEN_USER, TokenUser, + ACCESS_ALLOWED_ACE, ACL_SIZE_INFORMATION, AclSizeInformation, CONTAINER_INHERIT_ACE, + DACL_SECURITY_INFORMATION, EqualSid, GetAce, GetAclInformation, GetFileSecurityW, + GetSecurityDescriptorDacl, GetTokenInformation, OBJECT_INHERIT_ACE, TOKEN_QUERY, + TOKEN_USER, TokenUser, }; use windows_sys::Win32::System::Threading::{GetCurrentProcess, OpenProcessToken}; @@ -523,8 +526,8 @@ mod tests { let user = unsafe { &*user_buffer.as_ptr().cast::() }; let same_user = unsafe { EqualSid(ace_sid, user.User.Sid) } != 0; unsafe { CloseHandle(token) }; - let expected_flags = if directory { - OBJECT_INHERIT_ACE | CONTAINER_INHERIT_ACE + let expected_flags: u8 = if directory { + (OBJECT_INHERIT_ACE | CONTAINER_INHERIT_ACE) as u8 } else { 0 }; From 93596c2253c3b32303d42a95b81b974c5a1358ac Mon Sep 17 00:00:00 2001 From: dbowm91 Date: Thu, 19 Nov 2026 19:17:25 +0000 Subject: [PATCH 7/7] docs: record Windows usage-key CI result --- .../daemon-usage-cli-cache-implementation.md | 126 ++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 plans/daemon-usage-cli-cache-implementation.md diff --git a/plans/daemon-usage-cli-cache-implementation.md b/plans/daemon-usage-cli-cache-implementation.md new file mode 100644 index 0000000..3da87a0 --- /dev/null +++ b/plans/daemon-usage-cli-cache-implementation.md @@ -0,0 +1,126 @@ +# Reuse the daemon usage cache from the CLI + +**Status:** Local implementation and validation are complete. Windows MSVC tests (including the current-user-only usage-key ACL test) and the Windows release build passed in [CI run #44588788169](https://github.com/eggstack/eggpass/actions/runs/44588788169) at commit `34ec6f52a2d42d10fbdef07e3d5ad5ef01f75162`. + +## Goal + +Change `eggpass usage` to prefer the daemon's existing cached usage report, while retaining today's direct provider collection when the daemon is unavailable. Give the CLI a separate, daemon-managed usage credential that can read only the usage endpoint. Do not change the meaning or scope of regular Eggpass API keys. + +This is a CLI/authentication integration plan, not a plan to build another usage cache. The authenticated `GET /v1/usage` route, its in-memory 600-second cache, single-flight refresh, finite retries, response shape, and freshness headers already exist in the current source. The CLI currently collects provider usage directly on each run and only makes a separate best-effort daemon request for last-inference state. + +## Research findings and design decision + +- The CLI collection is in `src/cli/commands/usage.rs:129-178, 246-284`; its report DTO and enabled-provider selection are in `src/provider/usage/report.rs`. Existing output includes provider results, source/caption, and last-inference status. +- The daemon cache and `GET /v1/usage` response are in `src/server/usage.rs`. The route is registered in `src/server/router.rs`, and request auth/dispatch is centralized in `src/server/mod.rs`. +- All protected routes currently require a configured regular key. The daemon also refuses to start without one (`src/cli/commands/run.rs`). Issued regular keys are salted hashes in `src/keys.rs`; the daemon verifies them through the shared auth path. Preserve these properties. +- Paths are rooted in the resolved Eggpass data directory. A `--config` override changes only the config file path, not the key store or other runtime files (`src/paths.rs`). The existing Unix private writer uses atomic replacement and 0700/0600 modes, but the current permission helper is a no-op on Windows. A new secret cannot rely on that no-op as adequate Windows protection. +- **Recommendation:** use a separate, high-entropy runtime secret and authorize it by exact match only for `GET /v1/usage`. Do not infer its scope from a prefix/suffix, strip a marker, or insert it into the regular key store. A recognizable prefix is unnecessary; if ever used for display, it is only a label and must not affect authorization. +- Keep the secret in a dedicated runtime file under the resolved data directory, not in `config.toml`, the ordinary key store, command output, or logs. Rotate it for each daemon start. The CLI reads it locally and sends it in an Authorization Bearer header; do not put it in the URL/query string. + +## Security and compatibility contract + +1. **Least privilege:** the usage secret is accepted only for a bodyless `GET` to the usage route. It must fail authentication for inference, model, health/other, and any other route, including when an illustrative marker is removed or altered. Compare the entire token; never strip characters and never dispatch to a usage-key lookup solely because a candidate has a prefix. +2. **Regular keys unchanged:** regular config keys and issued keys retain their current accepted transports and full route scope. A valid regular key continues to work on the usage endpoint and every route it works on today. Do not change regular-key verification, listing, labels, hashing, or revocation behavior. +3. **No elevation of daemon startup:** the usage secret does not count as a configured client key, is not returned by key-list commands, and cannot satisfy `require_key`. Preserve the current fail-closed behavior when there are no regular keys, including for loopback clients. +4. **No loopback exception:** keep the existing authority/Host guard and authenticated-route checks. The usage token is not a reason to exempt localhost or weaken auth. +5. **Credential handling:** generate at least 256 bits of cryptographically secure randomness. Store the complete token only in its dedicated private file and in daemon memory. Use exact constant-time comparison. Do not log it, include it in errors, or expose it through a command, API response, config dump, debug output, or key listing. Treat usage data itself as sensitive even though the token has narrower access. +6. **File security and lifecycle:** add a path accessor such as `Paths::usage_key_file()`, rooted beside other Eggpass runtime files and unaffected by `--config`. Write atomically; create the Unix file as 0600 inside the 0700 data directory. On Windows, establish and test a current-user-only ACL for both directory and file; fail daemon startup closed if user-only protection cannot be established. Do not treat the existing non-Unix permission no-op as protection. Rotate/replace the token before the daemon reports ready. On graceful shutdown, remove the file only if it still contains this daemon's token; a crash may leave a stale file, but the next start must replace it before serving. A stopped daemon's leftover file must not authorize anything. +7. **Header scope:** accept the usage secret only from the Authorization Bearer header used by the CLI. Do not accept it from a query parameter. Keep existing regular-key header/query behavior unchanged. + +## CLI behavior + +Refactor `eggpass usage` into a daemon-attempt phase followed by the existing direct-collection phase. Keep formatting, JSON stdout, exit status rules, provider selection, and direct collector behavior compatible. + +- Resolve daemon state using the existing pid/host/port mechanism. If it is stopped or stale, use the existing direct provider collector without attempting the daemon request. +- If the daemon is running, read the dedicated usage-secret file. If the file is missing or cannot be read, use direct collection; do not print the secret or a file's contents in an error. +- Request `GET /v1/usage` with the secret as a Bearer header. Use bounded connect/overall timeouts appropriate for a local cache endpoint and status-aware HTTP handling. Never place the secret in a URL. +- On HTTP 200, parse the existing CLI-compatible JSON shape into the same report model and use the existing render/JSON/exit-result path. Respect an explicit provider selection by selecting that provider from the response. The daemon's fresh last-inference field should be used rather than making a second request. Preserve the JSON body shape and stdout; if the response has `X-Eggpass-Usage-Stale: true`, explain that cached data is stale on stderr only. +- On HTTP 404, use direct collection for compatibility with a running daemon that does not implement this route. +- If the request has a connection failure, recheck daemon state. Use direct collection only if that recheck confirms the daemon stopped or stale. If it still appears to be running, report the daemon communication failure instead of silently bypassing its cache. +- Do **not** fall back to direct provider calls for HTTP 202, 503, or 504. Those statuses represent an active refresh or cooldown, and fetching providers directly would bypass the daemon's single-flight/retry policy. Surface an actionable CLI error while preserving the HTTP status/retry context where practical. +- Treat HTTP 401/403 and malformed successful responses as errors, not as permission to silently fall back. This makes a stale/mismatched secret visible and prevents fallback from hiding an authentication/configuration defect. Do not retry by stripping a prefix or trying variants of the secret. +- A valid regular API key is not needed by the CLI for the daemon request; the scoped secret is sufficient for this route only. Direct fallback continues to use the existing local provider credential flow, not the scoped secret. + +## Implementation stages + +### Stage 1 — Add the runtime secret lifecycle + +- Add the dedicated path to `Paths`; document that config-file overrides do not relocate it. +- Add a focused secret-file helper or safely extract/reuse the private atomic-file writer without changing regular-key semantics. Use an unpredictable temporary filename opened with create-new semantics; avoid following attacker-planted temporary symlinks. Apply restrictive permissions/ACL before the secret can be read by another process. +- Generate a new URL-safe opaque token from a cryptographic RNG for each daemon launch. Do not add a prefix-based auth class. Atomically write the token, load the same exact bytes into server context, and ensure startup cannot report ready if creation/protection fails. +- Remove the matching secret on graceful shutdown without deleting a different daemon's rotated token. Do not persist or modify a config field. + +**Exit:** the daemon has one high-entropy runtime secret, stored only in the dedicated protected file and process memory; rotation/restart and shutdown behavior are defined and tested on supported platforms. + +### Stage 2 — Add route-specific authentication + +- Keep common authority validation and regular-key checks as they are. Add a separate exact-match usage-secret check in the shared auth path, gated by both the usage route and GET method, and by Authorization Bearer presentation only. +- Ensure the regular-key-present guard still executes: the runtime usage secret must not satisfy startup or `keys_configured` requirements and must not open a server whose regular keys have been removed. +- Ensure other methods/routes do not become authorized via the usage secret. Do not change the unauthenticated health/last-inference exceptions. + +**Exit:** existing normal-key behavior is unchanged; only the exact current usage secret can authorize GET usage, and it cannot authorize inference or any other route. + +### Stage 3 — Prefer the cached daemon response in `eggpass usage` + +- Add a small typed result for the daemon attempt (use cached report, fall back to direct collection, or return an error) so status handling is explicit and testable. +- Reuse the daemon-state and local HTTP patterns, but send the scoped Bearer key and request the existing endpoint. Add bounded transport timeouts and response parsing without logging credentials or provider payloads. +- Feed a successful daemon report through the existing CLI render/JSON and exit-code logic. Keep stdout exactly in the current schema; send stale-cache notice to stderr. Preserve provider override behavior and use last-inference already present in the API report. +- Keep direct collectors untouched as the fallback path. Apply the state-recheck rule on connection failure and never bypass 202/503/504. + +**Exit:** a live daemon's complete or stale cached response avoids provider calls; unavailable/unsupported daemon cases retain direct checks; pending/cooldown/auth failures have explicit non-bypass behavior. + +### Stage 4 — Deterministic security, fallback, and regression tests + +- **Secret files:** test resolved path behavior, config override separation, rotation, atomic replacement, restrictive Unix modes, Windows current-user ACL, failure-closed startup, and matching-token cleanup. Ensure no test output includes token bytes. +- **Authorization:** integration-test the scoped key on GET usage, and rejection on inference/models/other routes and wrong method. Test wrong/modified token and a token with any illustrative prefix removed; assert route scope comes from exact full-token matching, not parsing. Test that regular configured and issued keys still work unchanged. Verify the scoped token is absent from key listing and does not let a no-regular-key daemon start or serve protected routes. Retain authority/Host guard tests for loopback. +- **CLI HTTP behavior:** use a local stub server and injected collector counter. Assert HTTP 200 uses the cached report and makes zero direct provider calls; stale 200 warns only on stderr; 404 uses direct collection; stopped/stale daemon and missing key use direct collection; a connection failure falls back only after a stopped/stale recheck; a still-running connection failure, 401/403, malformed body, 202, 503, and 504 do not call direct collectors. Verify response timeout, headers, key transport, and absence of the secret from URL/log/error output. +- **Output compatibility:** test unchanged text and JSON stdout shape, provider filtering, exit-code semantics, and last-inference data for daemon and direct paths. Ensure stderr notices do not contaminate piped JSON. +- Use fake/local responses only; no provider credentials, live provider requests, real daemon network, or secret-bearing test snapshots are required. + +**Exit:** all new behavior is covered without live accounts or providers, including the security boundary and every fallback branch. + +### Stage 5 — Documentation and validation + +- Document that `eggpass usage` uses the daemon cache when available, that a separate private usage-only runtime key is generated/rotated, that it is not a regular API key, and that regular keys remain unchanged. Document stale/pending/cooldown and direct fallback behavior without exposing implementation tokens or implying that usage data is non-sensitive. +- Update current daemon usage/auth and CLI command documentation; keep API response docs consistent with the already-implemented cache route. +- Run formatting, workspace tests, strict Clippy, and `git diff --check`; add targeted server/auth/CLI tests. The earlier Windows run #25 lacked `src/usage_key.rs`; the current run #44588788169 at `34ec6f52a2d42d10fbdef07e3d5ad5ef01f75162` passed the Windows ACL test and release build. Review only the scoped diff and preserve unrelated worktree changes; do not include unrelated files. + +**Exit:** docs match actual behavior; local formatting, workspace tests, Clippy, and diff checks pass. Windows ACL validation is complete: the Windows MSVC tests and release build passed on CI run #44588788169 for commit `34ec6f52a2d42d10fbdef07e3d5ad5ef01f75162`. + +## Acceptance checklist + +- [x] CLI prefers the daemon's existing cached usage report when the daemon is reachable and the scoped credential is usable. +- [x] Direct provider collection remains the fallback when daemon is stopped/stale, route is unsupported, or scoped key is absent/unreadable; connection errors fall back only after confirming the daemon is stopped/stale. +- [x] HTTP 202/503/504 never trigger direct provider calls; authentication/parse errors are visible and do not trigger a silent bypass. +- [x] The usage-only secret is random, private, rotated per daemon start, and separate from config and regular keys. +- [x] Exact secret grants only GET usage; it cannot authorize inference, another route, or wrong method, even if any illustrative prefix/suffix is removed. +- [x] Regular client-key scope/behavior, key listing/revocation, startup key requirement, and loopback/authority protections are unchanged. +- [x] Windows file/directory access is protected by a current-user-only ACL; inability to protect the secret fails closed. +- [x] CLI text and JSON stdout remain compatible; stale-cache information is written to stderr only. +- [x] Tests cover security and fallback behavior without live provider access; docs describe credential storage, scope, rotation, and fallback. +- [x] Unrelated auth/release work remained excluded from the clean PR branch. + +## Completion record + +- Prior local macOS validation passed: cargo fmt --all -- --check; cargo test --workspace --all-targets --locked (422 tests); cargo clippy --workspace --all-targets --locked -- -D warnings; git diff --check. The clean PR worktree at `34ec6f52a2d42d10fbdef07e3d5ad5ef01f75162` separately passed `cargo fmt --all -- --check`, `cargo clippy --all-targets --locked -- -D warnings`, and `cargo test --all-targets --locked` (391 tests), plus `git diff --check`. +- Earlier Actions run [#25](https://github.com/eggstack/eggpass/actions/runs/44387410491) passed at `a626ef7561e096342a4d83f7d2ca452b9b52b873` but did not include `src/usage_key.rs`, so it was not ACL validation. Current [CI run #44588788169](https://github.com/eggstack/eggpass/actions/runs/44588788169) on draft PR [#5](https://github.com/eggstack/eggpass/pull/5), at `34ec6f52a2d42d10fbdef07e3d5ad5ef01f75162`, passed all jobs: release-workflow drift, Linux formatting/Clippy/tests/release build, and Windows MSVC tests/release build. The Windows log confirms `usage_key::tests::the_directory_and_secret_file_have_current_user_only_dacls ... ok`; the Windows test suite reported 378 passed. The first draft run caught missing CLI deserialization integration and Windows ACL test import/type errors; these were fixed before this successful run. +- Draft PR [#5](https://github.com/eggstack/eggpass/pull/5) contains the usage CLI/cache feature stack and scoped usage credential; unrelated local auth/release work was excluded. No release was published or PR merged. + +## Out of scope + +- Reimplementing or changing the existing daemon usage cache, its TTL, refresh/retry policy, endpoint schema, or freshness headers. +- Making any endpoint unauthenticated, weakening loopback authentication, or accepting the scoped secret for inference. +- Adding the scoped secret to `keys.json`, `eggpass key list`, normal config, or regular-key verification/storage semantics. +- Replacing direct provider collection as a fallback or performing direct collection when the daemon reports an active refresh/cooldown. +- Provider API/OAuth changes, config rewrite/migration, periodic usage polling, or exposing credentials in command output/logs. + +## Relevant source references + +- `src/cli/commands/usage.rs:129-178, 246-284, 400-435` — direct collection, output, daemon-state/last-inference probe. +- `src/server/usage.rs:321-357` — existing cache response and freshness behavior. +- `src/server/mod.rs:231-298, 363-435` — request guard, shared authentication, key presentation. +- `src/server/router.rs:5-45` — existing route map. +- `src/cli/commands/run.rs:98-129, 189-295` — regular-key startup guard, providers and cache setup. +- `src/keys.rs:182-205, 236-249, 346-407` — regular key issue/verify and private file writer. +- `src/paths.rs:5-11, 156-195, 198-219` — data-directory resolution, config override semantics, platform permission helper. +- `docs/commands.md:73-79` — current CLI/daemon usage documentation.