1use 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 enabled: AtomicBool,
23 statistics: AtomicBool,
25 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
33const SUBSCRIBER_BUFFER: usize = 256;
35const SUPPORT_REFRESH: &[u8] = br#"{"support_refresh":true}"#;
37const REFRESH: &[u8] = br#"{"refresh":true}"#;
39
40type SubscriberMap = (u64, std::collections::HashMap<u64, tokio::sync::mpsc::Sender<Vec<u8>>>);
42
43#[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 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
84pub 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 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 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 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 pub fn enqueue(&self, payload: Vec<u8>) {
164 if !self.accepts() || payload.is_empty() {
165 return;
166 }
167 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 pub fn subscribe_usage(&self) -> Subscription {
180 self.usage_subscribers.subscribe(Some(SUPPORT_REFRESH))
181 }
182
183 pub fn subscribe_errors(&self) -> Subscription {
185 self.error_subscribers.subscribe(None)
186 }
187
188 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 pub fn wants_errors(&self) -> bool {
197 self.enabled.load(Ordering::SeqCst) && !self.error_subscribers.lock().1.is_empty()
198 }
199
200 pub fn notify_usage_refresh(&self) {
202 self.usage_subscribers.publish(REFRESH);
203 }
204
205 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 #[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 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 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}