Skip to main content

cpa_server/
usage.rs

1//! Go `internal/redisqueue`: the in-memory usage queue that management's
2//! `GET /observability/usage/queue` drains. The request path enqueues one JSON record
3//! per upstream request (Go `queuedUsageDetail`); records older than the retention
4//! window are pruned on every access.
5//!
6//! RESP clients on the main listener (crate::resp) subscribe to the `usage` and
7//! `errors` channels; while any usage subscriber is connected, records go to them
8//! instead of the queue, as in Go.
9
10use std::collections::VecDeque;
11use std::sync::atomic::{AtomicBool, AtomicI64, Ordering};
12use std::sync::{Mutex, PoisonError};
13use std::time::{Duration, Instant};
14
15use cpa_core::config::Config;
16
17const DEFAULT_RETENTION_SECONDS: i64 = 60;
18const MAX_RETENTION_SECONDS: i64 = 3600;
19
20pub struct UsageQueue {
21    /// Go `redisqueue.Enabled`: management routes are enabled.
22    enabled: AtomicBool,
23    /// Go `UsageStatisticsEnabled`: `observability.usage.usage-statistics-enabled`.
24    statistics: AtomicBool,
25    /// Separate, default-off final-wire observations; not a Go usage setting.
26    claude_cache: AtomicBool,
27    retention_seconds: AtomicI64,
28    items: Mutex<VecDeque<(Instant, Vec<u8>)>>,
29    usage_subscribers: std::sync::Arc<Subscribers>,
30    error_subscribers: std::sync::Arc<Subscribers>,
31}
32
33/// Go `usageSubscriberBuffer` / `errorSubscriberBuffer`.
34const SUBSCRIBER_BUFFER: usize = 256;
35/// Go `usageSupportRefreshPayload`: the first message every usage subscriber gets.
36const SUPPORT_REFRESH: &[u8] = br#"{"support_refresh":true}"#;
37/// Go `usageRefreshPayload`.
38const REFRESH: &[u8] = br#"{"refresh":true}"#;
39
40/// The last subscription ID and the live subscribers by ID.
41type SubscriberMap = (u64, std::collections::HashMap<u64, tokio::sync::mpsc::Sender<Vec<u8>>>);
42
43/// Go `queue.subscribers`: bounded channels keyed by subscription.
44#[derive(Default)]
45struct Subscribers(Mutex<SubscriberMap>);
46
47impl Subscribers {
48    fn lock(&self) -> std::sync::MutexGuard<'_, SubscriberMap> {
49        self.0.lock().unwrap_or_else(PoisonError::into_inner)
50    }
51
52    /// Go `publishToSubscribers`: whether anyone listened. A subscriber whose buffer
53    /// is full is dropped, which ends its subscription.
54    fn publish(&self, payload: &[u8]) -> bool {
55        let mut guard = self.lock();
56        if guard.1.is_empty() {
57            return false;
58        }
59        guard.1.retain(|_, tx| tx.try_send(payload.to_vec()).is_ok());
60        true
61    }
62
63    fn subscribe(self: &std::sync::Arc<Self>, greeting: Option<&[u8]>) -> Subscription {
64        let (tx, rx) = tokio::sync::mpsc::channel(SUBSCRIBER_BUFFER);
65        if let Some(greeting) = greeting {
66            let _ = tx.try_send(greeting.to_vec());
67        }
68        let mut guard = self.lock();
69        guard.0 += 1;
70        let id = guard.0;
71        guard.1.insert(id, tx);
72        Subscription {
73            messages: rx,
74            owner: std::sync::Arc::downgrade(self),
75            id,
76        }
77    }
78
79    fn clear(&self) {
80        self.lock().1.clear();
81    }
82}
83
84/// One channel subscription; dropping it unsubscribes (Go's `unsubscribe`). `messages`
85/// ends when the queue drops the subscriber (full buffer, or the queue was disabled).
86pub struct Subscription {
87    pub messages: tokio::sync::mpsc::Receiver<Vec<u8>>,
88    owner: std::sync::Weak<Subscribers>,
89    id: u64,
90}
91
92impl Drop for Subscription {
93    fn drop(&mut self) {
94        if let Some(owner) = self.owner.upgrade() {
95            owner.lock().1.remove(&self.id);
96        }
97    }
98}
99
100impl Default for UsageQueue {
101    fn default() -> Self {
102        Self {
103            enabled: AtomicBool::new(false),
104            // Go's package default; startup immediately applies the config value.
105            statistics: AtomicBool::new(true),
106            claude_cache: AtomicBool::new(false),
107            retention_seconds: AtomicI64::new(DEFAULT_RETENTION_SECONDS),
108            items: Mutex::default(),
109            usage_subscribers: std::sync::Arc::default(),
110            error_subscribers: std::sync::Arc::default(),
111        }
112    }
113}
114
115impl UsageQueue {
116    /// Applies one published config (Go server_reload.go): disabling the queue drops
117    /// everything queued; retention is clamped to 1..=3600 seconds.
118    pub fn configure(&self, management_enabled: bool, cfg: &Config) {
119        let usage = cfg.document.get("observability").and_then(|o| o.get("usage"));
120        let statistics = usage
121            .and_then(|u| u.get("usage-statistics-enabled"))
122            .and_then(serde_yaml_ng::Value::as_bool)
123            .unwrap_or(false);
124        self.claude_cache.store(
125            usage
126                .and_then(|u| u.get("claude-cache-telemetry"))
127                .and_then(serde_yaml_ng::Value::as_bool)
128                .unwrap_or(false),
129            Ordering::SeqCst,
130        );
131        let retention = usage
132            .and_then(|u| u.get("redis-usage-queue-retention-seconds"))
133            .and_then(serde_yaml_ng::Value::as_i64)
134            .unwrap_or(0);
135        self.statistics.store(statistics, Ordering::SeqCst);
136        self.retention_seconds.store(
137            if retention <= 0 {
138                DEFAULT_RETENTION_SECONDS
139            } else {
140                retention.min(MAX_RETENTION_SECONDS)
141            },
142            Ordering::SeqCst,
143        );
144        self.enabled.store(management_enabled, Ordering::SeqCst);
145        if !management_enabled {
146            self.lock().clear();
147            self.usage_subscribers.clear();
148            self.error_subscribers.clear();
149        }
150    }
151
152    /// Whether a usage record would be kept; producers can skip building one.
153    pub fn accepts(&self) -> bool {
154        self.enabled.load(Ordering::SeqCst) && self.statistics.load(Ordering::SeqCst)
155    }
156
157    pub fn wants_claude_cache(&self) -> bool {
158        self.accepts() && self.claude_cache.load(Ordering::SeqCst)
159    }
160
161    /// Queues one serialized usage record (Go `usageQueuePlugin.HandleUsage` +
162    /// `Enqueue`).
163    pub fn enqueue(&self, payload: Vec<u8>) {
164        if !self.accepts() || payload.is_empty() {
165            return;
166        }
167        // Go `Enqueue`: connected RESP subscribers take the record instead of the queue.
168        if self.usage_subscribers.publish(&payload) {
169            return;
170        }
171        let now = Instant::now();
172        let mut items = self.lock();
173        self.prune(&mut items, now);
174        items.push_back((now, payload));
175    }
176
177    /// Go `SubscribeUsage`: usage records as they are produced, after a first
178    /// `{"support_refresh":true}`.
179    pub fn subscribe_usage(&self) -> Subscription {
180        self.usage_subscribers.subscribe(Some(SUPPORT_REFRESH))
181    }
182
183    /// Go `SubscribeErrors`.
184    pub fn subscribe_errors(&self) -> Subscription {
185        self.error_subscribers.subscribe(None)
186    }
187
188    /// Go `EnqueueError`: an error event for `errors` subscribers; nothing is queued.
189    pub fn enqueue_error(&self, payload: &[u8]) {
190        if self.enabled.load(Ordering::SeqCst) && !payload.is_empty() {
191            self.error_subscribers.publish(payload);
192        }
193    }
194
195    /// Whether an error event would reach anyone; producers can skip building one.
196    pub fn wants_errors(&self) -> bool {
197        self.enabled.load(Ordering::SeqCst) && !self.error_subscribers.lock().1.is_empty()
198    }
199
200    /// Go `NotifyUsageRefresh`: tells usage subscribers the credential set changed.
201    pub fn notify_usage_refresh(&self) {
202        self.usage_subscribers.publish(REFRESH);
203    }
204
205    /// Go `PopOldest`: removes and returns up to `count` unexpired records, oldest first.
206    pub fn pop_oldest(&self, count: usize) -> Vec<Vec<u8>> {
207        if !self.enabled.load(Ordering::SeqCst) || count == 0 {
208            return Vec::new();
209        }
210        let mut items = self.lock();
211        self.prune(&mut items, Instant::now());
212        let n = count.min(items.len());
213        items.drain(..n).map(|(_, payload)| payload).collect()
214    }
215
216    fn prune(&self, items: &mut VecDeque<(Instant, Vec<u8>)>, now: Instant) {
217        let window = Duration::from_secs(self.retention_seconds.load(Ordering::SeqCst).max(1) as u64);
218        while items
219            .front()
220            .is_some_and(|(at, _)| now.saturating_duration_since(*at) > window)
221        {
222            items.pop_front();
223        }
224    }
225
226    fn lock(&self) -> std::sync::MutexGuard<'_, VecDeque<(Instant, Vec<u8>)>> {
227        self.items.lock().unwrap_or_else(PoisonError::into_inner)
228    }
229}
230
231#[cfg(test)]
232mod tests {
233    use super::*;
234
235    fn cfg(yaml: &str) -> Config {
236        Config::parse(yaml).unwrap()
237    }
238
239    #[test]
240    fn queues_only_when_management_and_statistics_are_enabled() {
241        let q = UsageQueue::default();
242        let on = cfg("observability: {usage: {usage-statistics-enabled: true}}\n");
243        q.enqueue(b"{}".to_vec());
244        assert!(q.pop_oldest(5).is_empty(), "management disabled");
245        q.configure(true, &cfg("{}\n"));
246        q.enqueue(b"{}".to_vec());
247        assert!(q.pop_oldest(5).is_empty(), "statistics default off");
248        q.configure(true, &on);
249        assert!(
250            !q.wants_claude_cache(),
251            "usage statistics alone do not enable cache telemetry"
252        );
253        for i in 0..3 {
254            q.enqueue(format!("{{\"n\":{i}}}").into_bytes());
255        }
256        assert_eq!(q.pop_oldest(2), [b"{\"n\":0}".to_vec(), b"{\"n\":1}".to_vec()]);
257        q.configure(false, &on);
258        q.configure(true, &on);
259        assert!(q.pop_oldest(5).is_empty(), "disabling clears the queue");
260        let telemetry = cfg("observability: {usage: {usage-statistics-enabled: true, claude-cache-telemetry: true}}\n");
261        q.configure(true, &telemetry);
262        assert!(q.wants_claude_cache());
263        q.configure(false, &telemetry);
264        assert!(!q.wants_claude_cache(), "telemetry also needs an accepting queue");
265    }
266
267    #[test]
268    fn retention_prunes_expired_records() {
269        let q = UsageQueue::default();
270        q.configure(
271            true,
272            &cfg("observability: {usage: {usage-statistics-enabled: true, redis-usage-queue-retention-seconds: 1}}\n"),
273        );
274        q.lock()
275            .push_back((Instant::now() - Duration::from_secs(5), b"old".to_vec()));
276        q.enqueue(b"new".to_vec());
277        assert_eq!(q.pop_oldest(5), [b"new".to_vec()]);
278        q.configure(true, &cfg("observability: {usage: {usage-statistics-enabled: true, redis-usage-queue-retention-seconds: 99999}}\n"));
279        assert_eq!(q.retention_seconds.load(Ordering::SeqCst), 3600);
280    }
281
282    /// Go redisqueue `Enqueue`, `publishToSubscribers`, `subscribe`, `clear` and
283    /// `NotifyUsageRefresh`.
284    #[test]
285    fn subscribers_take_records_and_are_dropped_when_full_or_disabled() {
286        let on = cfg("observability: {usage: {usage-statistics-enabled: true}}\n");
287        let q = UsageQueue::default();
288        q.configure(true, &on);
289        let mut usage = q.subscribe_usage();
290        assert_eq!(usage.messages.try_recv().unwrap(), SUPPORT_REFRESH);
291        q.enqueue(b"r1".to_vec());
292        assert_eq!(usage.messages.try_recv().unwrap(), b"r1");
293        assert!(q.pop_oldest(5).is_empty(), "delivered, not queued");
294        q.notify_usage_refresh();
295        assert_eq!(usage.messages.try_recv().unwrap(), REFRESH);
296        drop(usage);
297        q.enqueue(b"r2".to_vec());
298        assert_eq!(q.pop_oldest(5), [b"r2".to_vec()], "no subscriber: queued again");
299
300        // A subscriber that stops reading is dropped once its buffer is full.
301        let mut slow = q.subscribe_usage();
302        for i in 0..SUBSCRIBER_BUFFER {
303            q.enqueue(format!("{i}").into_bytes());
304        }
305        assert_eq!(q.usage_subscribers.lock().1.len(), 0, "dropped at the 256th record");
306        let mut received = 0;
307        while slow.messages.try_recv().is_ok() {
308            received += 1;
309        }
310        assert_eq!(received, SUBSCRIBER_BUFFER, "the greeting and 255 records, then closed");
311
312        // Errors reach only subscribers; disabling the queue ends every subscription.
313        let mut errors = q.subscribe_errors();
314        q.enqueue_error(b"e1");
315        assert_eq!(errors.messages.try_recv().unwrap(), b"e1");
316        q.configure(false, &on);
317        assert!(matches!(
318            errors.messages.try_recv(),
319            Err(tokio::sync::mpsc::error::TryRecvError::Disconnected)
320        ));
321    }
322}