Skip to main content

cpa_exec/
codex_quota.rs

1//! Codex passive quota observation: `codex.rate_limits` WebSocket events and error-frame
2//! headers normalised into `X-Codex-*` headers (helps/codex_quota.go), and the
3//! provider-scoped signal snapshot Go keeps per credential (sdk/cliproxy/auth/quota_signals.go).
4//!
5//! Snapshots replace, never merge: each attempt's observed headers become the credential's
6//! new snapshot. The store is bounded by the number of credentials that have been used.
7
8use std::collections::{BTreeMap, HashMap};
9use std::sync::Mutex;
10use std::time::SystemTime;
11
12use gjson::Kind;
13use http::HeaderMap;
14
15const MAX_ADDITIONAL: usize = 8;
16const MAX_SIGNALS: usize = 64;
17const MAX_SIGNAL_VALUE: usize = 512;
18const QUOTA_MARKERS: [&str; 8] = [
19    "-allowed",
20    "-limit-reached",
21    "-limit-name",
22    "-used-percent",
23    "-window-minutes",
24    "-reset-after-seconds",
25    "-reset-at",
26    "-over-secondary-limit-percent",
27];
28
29/// Header name → value, in the order Go would set them.
30pub type Headers = Vec<(String, String)>;
31
32fn set(out: &mut Headers, name: String, value: String) {
33    match out.iter_mut().find(|(k, _)| k.eq_ignore_ascii_case(&name)) {
34        Some(slot) => slot.1 = value,
35        None => out.push((name, value)),
36    }
37}
38
39/// `codexQuotaScalarValue`: strings trimmed, numbers and booleans raw.
40fn scalar(v: &gjson::Value<'_>) -> String {
41    match v.kind() {
42        Kind::String => v.str().trim().to_owned(),
43        Kind::Number | Kind::True | Kind::False => v.json().trim().to_owned(),
44        _ => String::new(),
45    }
46}
47
48fn first<'a>(object: &'a gjson::Value<'a>, paths: &[&'a str]) -> gjson::Value<'a> {
49    for path in paths {
50        let v = object.get(path);
51        if v.exists() && v.kind() != Kind::Null {
52            return v;
53        }
54    }
55    gjson::Value::default()
56}
57
58fn first_string(object: &gjson::Value<'_>, paths: &[&str]) -> String {
59    paths
60        .iter()
61        .map(|p| scalar(&first(object, &[p])))
62        .find(|s| !s.is_empty())
63        .unwrap_or_default()
64}
65
66fn set_scalar(out: &mut Headers, name: &str, object: &gjson::Value<'_>, paths: &[&str]) -> bool {
67    let value = scalar(&first(object, paths));
68    if value.is_empty() {
69        return false;
70    }
71    set(out, name.to_owned(), value);
72    true
73}
74
75fn valid_identifier(s: &str) -> bool {
76    let s = s.trim();
77    !s.is_empty()
78        && s.len() <= 256
79        && s.chars()
80            .all(|c| c.is_ascii_alphanumeric() || matches!(c, '_' | '-' | '.'))
81}
82
83fn valid_text(s: &str) -> bool {
84    let s = s.trim();
85    !s.is_empty() && s.len() <= 256 && !s.contains(['\r', '\n'])
86}
87
88/// `normalizeCodexQuotaHeaderIdentifier`.
89fn header_identifier(value: &str) -> Option<String> {
90    let value = value.trim();
91    if value.is_empty() || value.len() > 128 {
92        return None;
93    }
94    let mut out = String::with_capacity(value.len());
95    let mut last_dash = false;
96    for c in value.chars() {
97        if c.is_ascii_alphanumeric() || matches!(c, '.' | '_' | '-') {
98            out.push(c);
99            last_dash = false;
100        } else if !last_dash {
101            out.push('-');
102            last_dash = true;
103        }
104    }
105    let id = out.trim_matches(['-', '_', '.']).to_owned();
106    valid_identifier(&id).then_some(id)
107}
108
109fn add_rate_limit(out: &mut Headers, prefix: &str, info: &gjson::Value<'_>) -> bool {
110    if info.kind() != Kind::Object {
111        return false;
112    }
113    let mut changed = set_scalar(out, &format!("{prefix}Allowed"), info, &["allowed"]);
114    changed |= set_scalar(
115        out,
116        &format!("{prefix}Limit-Reached"),
117        info,
118        &["limit_reached", "limitReached"],
119    );
120    for (key, label) in [("primary", "Primary"), ("secondary", "Secondary")] {
121        let window = first(info, &[key]);
122        if window.kind() != Kind::Object {
123            continue;
124        }
125        let used = first(&window, &["used_percent", "usedPercent"]);
126        let minutes = first(&window, &["window_minutes", "windowMinutes"]);
127        let after = first(&window, &["reset_after_seconds", "resetAfterSeconds"]);
128        let at = first(&window, &["reset_at", "resetAt"]);
129        let has_after = after.exists() && after.i64() >= 0;
130        let has_at = at.exists() && at.i64() > 0;
131        if !used.exists()
132            || !minutes.exists()
133            || !(0.0..=100.0).contains(&used.f64())
134            || minutes.i64() <= 0
135            || (!has_after && !has_at)
136        {
137            continue;
138        }
139        let p = format!("{prefix}{label}-");
140        set_scalar(
141            out,
142            &format!("{p}Used-Percent"),
143            &window,
144            &["used_percent", "usedPercent"],
145        );
146        set_scalar(
147            out,
148            &format!("{p}Window-Minutes"),
149            &window,
150            &["window_minutes", "windowMinutes"],
151        );
152        if has_after {
153            set_scalar(
154                out,
155                &format!("{p}Reset-After-Seconds"),
156                &window,
157                &["reset_after_seconds", "resetAfterSeconds"],
158            );
159        }
160        if has_at {
161            set_scalar(out, &format!("{p}Reset-At"), &window, &["reset_at", "resetAt"]);
162        }
163        changed = true;
164    }
165    changed
166}
167
168/// Go `http.CanonicalHeaderKey`.
169fn canonical(name: &str) -> String {
170    let mut upper = true;
171    name.chars()
172        .map(|c| {
173            let out = if upper {
174                c.to_ascii_uppercase()
175            } else {
176                c.to_ascii_lowercase()
177            };
178            upper = c == '-';
179            out
180        })
181        .collect()
182}
183
184fn is_quota_header(name: &str) -> bool {
185    let lower = name.trim().to_ascii_lowercase();
186    if lower == "retry-after" || lower.starts_with("x-ratelimit-") {
187        return true;
188    }
189    if lower == "x-codex-active-limit" || lower == "x-codex-plan-type" || lower.starts_with("x-codex-credits-") {
190        return true;
191    }
192    lower.starts_with("x-codex-") && QUOTA_MARKERS.iter().any(|m| lower.contains(m))
193}
194
195/// `ParseCodexQuotaEventHeaders`: headers from a `codex.rate_limits` event, or the quota
196/// headers carried by an `error` frame. `None` for any other payload.
197pub fn event_headers(payload: &str) -> Option<Headers> {
198    let root = gjson::parse(payload);
199    let kind = event_kind(payload.as_bytes())?;
200    let mut out = Headers::new();
201    if kind == EventKind::Error {
202        let headers = root.get("headers");
203        if headers.kind() != Kind::Object {
204            return None;
205        }
206        headers.each(|key, value| {
207            let name = canonical(key.str().trim());
208            let value = scalar(&value);
209            if is_quota_header(&name) && !value.is_empty() {
210                set(&mut out, name, value);
211            }
212            true
213        });
214        return (!out.is_empty()).then_some(out);
215    }
216    let mut has = add_rate_limit(&mut out, "X-Codex-", &first(&root, &["rate_limits", "rateLimit"]));
217    let additional = first(&root, &["additional_rate_limits", "additionalRateLimits"]);
218    if matches!(additional.kind(), Kind::Object | Kind::Array) {
219        let mut count = 0;
220        let is_array = additional.kind() == Kind::Array;
221        additional.each(|key, value| {
222            if count >= MAX_ADDITIONAL {
223                return false;
224            }
225            let name = if is_array {
226                first_string(&value, &["limit_name", "limitName", "name"])
227            } else {
228                key.str().trim().to_owned()
229            };
230            let Some(id) = header_identifier(&name) else {
231                return true;
232            };
233            let nested = first(&value, &["rate_limit", "rateLimit"]);
234            let info = if nested.exists() { nested } else { value };
235            let prefix = format!("X-Codex-Additional-{id}-");
236            if add_rate_limit(&mut out, &prefix, &info) {
237                if valid_text(&name) {
238                    set(&mut out, format!("{prefix}Limit-Name"), name);
239                }
240                has = true;
241                count += 1;
242            }
243            true
244        });
245    }
246    has |= add_rate_limit(
247        &mut out,
248        "X-Codex-Code-Review-",
249        &first(&root, &["code_review_rate_limits", "codeReviewRateLimits"]),
250    );
251    let credits = first(&root, &["credits"]);
252    if credits.kind() == Kind::Object {
253        has |= set_scalar(
254            &mut out,
255            "X-Codex-Credits-Has-Credits",
256            &credits,
257            &["has_credits", "hasCredits"],
258        );
259        has |= set_scalar(&mut out, "X-Codex-Credits-Unlimited", &credits, &["unlimited"]);
260        has |= set_scalar(&mut out, "X-Codex-Credits-Balance", &credits, &["balance"]);
261    }
262    if !has {
263        return None;
264    }
265    let active = first_string(
266        &root,
267        &["metered_limit_name", "meteredLimitName", "limit_name", "limitName"],
268    );
269    if valid_identifier(&active) {
270        set(&mut out, "X-Codex-Active-Limit".into(), active);
271    }
272    let plan = first_string(&root, &["plan_type", "planType"]);
273    if valid_text(&plan) {
274        set(&mut out, "X-Codex-Plan-Type".into(), plan);
275    }
276    Some(out)
277}
278
279#[derive(PartialEq, Eq)]
280enum EventKind {
281    Error,
282    RateLimits,
283}
284
285/// `codexQuotaEventKind`: a `"type"` key in the first 256 bytes, no full parse.
286fn event_kind(payload: &[u8]) -> Option<EventKind> {
287    let end = payload.len().min(256);
288    let p = &payload[..end];
289    let mut i = 0;
290    while i + 6 < end {
291        if &p[i..i + 6] != b"\"type\"" {
292            i += 1;
293            continue;
294        }
295        let mut j = i + 6;
296        while j < end && matches!(p[j], b' ' | b'\t' | b'\r' | b'\n') {
297            j += 1;
298        }
299        if j >= end || p[j] != b':' {
300            i += 1;
301            continue;
302        }
303        j += 1;
304        while j < end && matches!(p[j], b' ' | b'\t' | b'\r' | b'\n') {
305            j += 1;
306        }
307        if p[j..].starts_with(b"\"error\"") {
308            return Some(EventKind::Error);
309        }
310        if p[j..].starts_with(b"\"codex.rate_limits\"") {
311            return Some(EventKind::RateLimits);
312        }
313        i += 1;
314    }
315    None
316}
317
318/// `collectQuotaSignals("codex", headers)`: the Codex quota headers, ranked, capped at 64.
319pub fn collect_signals(headers: &HeaderMap) -> BTreeMap<String, String> {
320    let mut values: Vec<(String, String)> = Vec::new();
321    for name in headers.keys() {
322        let canonical = canonical(name.as_str());
323        let lower = canonical.to_ascii_lowercase();
324        let accepted = lower == "retry-after" || lower.starts_with("x-ratelimit-") || {
325            lower.starts_with("x-codex-")
326                && (lower == "x-codex-active-limit"
327                    || lower == "x-codex-plan-type"
328                    || lower.starts_with("x-codex-credits-")
329                    || QUOTA_MARKERS.iter().any(|m| lower.contains(m)))
330        };
331        let Some(value) = headers.get_all(name).iter().next_back() else {
332            continue;
333        };
334        let Ok(value) = value.to_str() else { continue };
335        let value = value.trim();
336        if !accepted
337            || value.is_empty()
338            || value.len() > MAX_SIGNAL_VALUE
339            || value.chars().any(|c| (c as u32) < 0x20 || c == '\u{7f}')
340        {
341            continue;
342        }
343        values.push((canonical, value.to_owned()));
344    }
345    let rank = |name: &str| {
346        let lower = name.to_ascii_lowercase();
347        match () {
348            _ if lower == "retry-after" => 0,
349            _ if lower == "x-codex-plan-type"
350                || lower == "x-codex-active-limit"
351                || lower.starts_with("x-codex-credits-") =>
352            {
353                1
354            }
355            _ if lower == "x-codex-allowed"
356                || lower == "x-codex-limit-reached"
357                || lower.starts_with("x-codex-primary-")
358                || lower.starts_with("x-codex-secondary-") =>
359            {
360                2
361            }
362            _ if lower.starts_with("x-codex-code-review-") => 3,
363            _ if lower.starts_with("x-codex-additional-") => 5,
364            _ if lower.starts_with("x-codex-") => 4,
365            _ => 6,
366        }
367    };
368    values.sort_by(|a, b| rank(&a.0).cmp(&rank(&b.0)).then_with(|| a.0.cmp(&b.0)));
369    values.into_iter().take(MAX_SIGNALS).collect()
370}
371
372/// The latest passive quota snapshot per credential.
373#[derive(Debug, Clone, PartialEq, Eq)]
374pub struct Snapshot {
375    pub observed_at: SystemTime,
376    pub signals: BTreeMap<String, String>,
377}
378
379/// One credential's snapshots: its own and one per model (Go `Auth.Quota` and
380/// `ModelState.Quota`).
381#[derive(Default)]
382struct Entry {
383    credential: Option<Snapshot>,
384    models: BTreeMap<String, Snapshot>,
385}
386
387#[derive(Default)]
388pub struct QuotaSignals {
389    snapshots: Mutex<HashMap<String, Entry>>,
390}
391
392impl QuotaSignals {
393    /// Go `ObserveResponseHeadersForProvider` on the credential and on `model`'s state
394    /// (`canonicalModelKey`): replaced when `headers` carry any Codex quota signal,
395    /// untouched otherwise.
396    // ponytail: Go keys model state by the conductor's state model; executors see the
397    // upstream model, which differs only for aliases mapped to another upstream name.
398    pub fn observe(&self, credential_id: &str, model: &str, headers: &HeaderMap) {
399        self.record(credential_id, model, collect_signals(headers), SystemTime::now());
400    }
401
402    /// Stores one response's already collected `signals` as the credential's and
403    /// `model`'s snapshot; empty signals leave both untouched. Providers with their own
404    /// header rules (Claude) share this store.
405    pub(crate) fn record(
406        &self,
407        credential_id: &str,
408        model: &str,
409        signals: BTreeMap<String, String>,
410        observed_at: SystemTime,
411    ) {
412        if signals.is_empty() {
413            return;
414        }
415        let snapshot = Snapshot { observed_at, signals };
416        let mut snapshots = self.snapshots.lock().expect("quota snapshots");
417        let entry = snapshots.entry(credential_id.to_owned()).or_default();
418        let model = cpa_core::registry::dynamic::canonical_model(model);
419        if !model.is_empty() {
420            entry.models.insert(model.to_owned(), snapshot.clone());
421        }
422        entry.credential = Some(snapshot);
423    }
424
425    /// The credential's latest snapshot (`quota`).
426    pub fn snapshot(&self, credential_id: &str) -> Option<Snapshot> {
427        self.snapshots
428            .lock()
429            .expect("quota snapshots")
430            .get(credential_id)
431            .and_then(|e| e.credential.clone())
432    }
433
434    /// The latest snapshot per model (`model_quotas`), empty when none was observed.
435    pub fn model_snapshots(&self, credential_id: &str) -> BTreeMap<String, Snapshot> {
436        self.snapshots
437            .lock()
438            .expect("quota snapshots")
439            .get(credential_id)
440            .map(|e| e.models.clone())
441            .unwrap_or_default()
442    }
443
444    /// Drops state for credentials that no longer exist.
445    pub fn retain(&self, keep: impl Fn(&str) -> bool) {
446        self.snapshots.lock().expect("quota snapshots").retain(|id, _| keep(id));
447    }
448}
449
450/// Merges event-derived headers into an attempt's observed header set.
451pub(crate) fn merge(target: &mut HeaderMap, headers: &Headers) {
452    for (name, value) in headers {
453        if let (Ok(name), Ok(value)) = (
454            http::HeaderName::try_from(name.as_str()),
455            http::HeaderValue::from_str(value),
456        ) {
457            target.insert(name, value);
458        }
459    }
460}