Skip to main content

cpa_plugin/store/
rate_limit.rs

1//! The GitHub API rate limiter (internal/pluginstore/github_rate_limit.go): cooldowns
2//! per request identity (network scope and credentials), shared across release
3//! metadata and API asset downloads.
4
5use cpa_core::gostr::GoStr;
6use std::collections::HashMap;
7use std::sync::Mutex;
8use std::time::{Duration, SystemTime};
9
10use super::auth::Headers;
11
12/// A GitHub API cooldown, without response bodies or credentials.
13#[derive(Debug, Clone, PartialEq, Eq)]
14pub struct RateLimitError {
15    pub status: u16,
16    pub retry_at: SystemTime,
17}
18
19impl std::fmt::Display for RateLimitError {
20    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
21        let at = self
22            .retry_at
23            .duration_since(SystemTime::UNIX_EPOCH)
24            .ok()
25            .and_then(|d| i64::try_from(d.as_secs()).ok())
26            .and_then(|secs| chrono::DateTime::from_timestamp(secs, 0));
27        match at {
28            Some(at) => write!(
29                f,
30                "GitHub API rate limited; retry after {}",
31                at.format("%Y-%m-%dT%H:%M:%SZ")
32            ),
33            None => f.write_str("GitHub API rate limited"),
34        }
35    }
36}
37
38impl RateLimitError {
39    /// Go `RetryAfterSeconds`: rounded up, never negative.
40    pub fn retry_after_seconds(&self, now: SystemTime) -> i64 {
41        match self.retry_at.duration_since(now) {
42            Ok(delay) if !delay.is_zero() => {
43                let secs = delay.as_secs() as i64;
44                if delay.subsec_nanos() != 0 { secs + 1 } else { secs }
45            }
46            _ => 0,
47        }
48    }
49}
50
51#[derive(Debug, Clone, Default)]
52struct Cooldown {
53    retry_at: Option<SystemTime>,
54    status: u16,
55    failures: u8,
56}
57
58#[derive(Default)]
59struct State {
60    entries: HashMap<String, Cooldown>,
61    next_prune_at: Option<SystemTime>,
62}
63
64/// Go `GitHubRateLimiter`. Clients without their own share the process-wide one.
65#[derive(Default)]
66pub struct GitHubRateLimiter {
67    state: Mutex<State>,
68    now: Option<fn() -> SystemTime>,
69}
70
71/// 9999-12-31T23:59:59Z, the latest `X-Ratelimit-Reset` kept as sent.
72const MAX_RESET: u64 = 253_402_300_799;
73
74static DEFAULT_LIMITER: std::sync::LazyLock<GitHubRateLimiter> = std::sync::LazyLock::new(GitHubRateLimiter::default);
75
76impl GitHubRateLimiter {
77    /// A limiter on a fixed clock (tests).
78    pub fn with_clock(now: fn() -> SystemTime) -> Self {
79        Self {
80            state: Mutex::default(),
81            now: Some(now),
82        }
83    }
84
85    pub(super) fn shared() -> &'static GitHubRateLimiter {
86        &DEFAULT_LIMITER
87    }
88
89    fn now(&self) -> SystemTime {
90        self.now.map_or_else(SystemTime::now, |f| f())
91    }
92
93    /// Go `check`: an active cooldown for the key is an error.
94    pub(super) fn check(&self, key: &str) -> Result<(), RateLimitError> {
95        if key.is_empty() {
96            return Ok(());
97        }
98        let mut state = self.state.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
99        let now = self.now();
100        prune(&mut state, now);
101        match state.entries.get(key) {
102            Some(entry) if entry.retry_at.is_some_and(|at| now < at) => Err(RateLimitError {
103                status: entry.status,
104                retry_at: entry.retry_at.unwrap_or(now),
105            }),
106            _ => Ok(()),
107        }
108    }
109
110    /// Go `observe`: records the response's limits; a rate-limit rejection is an
111    /// error. A late success never clears another request's cooldown.
112    pub(super) fn observe(
113        &self,
114        key: &str,
115        status: u16,
116        headers: &Headers,
117        body: Option<&[u8]>,
118    ) -> Result<(), RateLimitError> {
119        if key.is_empty() {
120            return Ok(());
121        }
122        let mut state = self.state.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
123        let now = self.now();
124        prune(&mut state, now);
125        let mut entry = state.entries.get(key).cloned().unwrap_or_default();
126        let header = |name: &str| {
127            headers
128                .get(name)
129                .and_then(|v| v.first())
130                .map(|v| v.trim().to_owned())
131                .unwrap_or_default()
132        };
133        let remaining_zero = header("X-Ratelimit-Remaining") == "0";
134        let mut retry_at = retry_after(&header("Retry-After"), now);
135        let rate_limited = status == 429
136            || (status == 403 && (remaining_zero || retry_at.is_some() || body.is_some_and(rate_limit_message)));
137        if !rate_limited && !remaining_zero {
138            if (200..300).contains(&status) && entry.retry_at.is_none_or(|at| now >= at) {
139                state.entries.remove(key);
140            }
141            return Ok(());
142        }
143        if remaining_zero
144            && let Ok(reset) = header("X-Ratelimit-Reset").parse::<i64>()
145            && reset > 0
146        {
147            // Go keeps any reset; it is capped at year 9999 so the time stays
148            // representable and printable.
149            let reset_at = SystemTime::UNIX_EPOCH + Duration::from_secs((reset as u64).min(MAX_RESET));
150            if retry_at.is_none_or(|at| reset_at > at) {
151                retry_at = Some(reset_at);
152            }
153        }
154        let retry_at = match retry_at.filter(|at| *at > now) {
155            Some(at) => at,
156            None => {
157                if !rate_limited {
158                    return Ok(());
159                }
160                // Headerless secondary limits: one minute, doubling to an hour.
161                let delay = (Duration::from_secs(60) * (1u32 << entry.failures)).min(Duration::from_secs(3600));
162                if entry.failures < 6 {
163                    entry.failures += 1;
164                }
165                now + delay
166            }
167        };
168        if entry.retry_at.is_none_or(|at| retry_at > at) {
169            entry.retry_at = Some(retry_at);
170        }
171        entry.status = if rate_limited { status } else { 429 };
172        let error = RateLimitError {
173            status,
174            retry_at: entry.retry_at.unwrap_or(retry_at),
175        };
176        state.entries.insert(key.to_owned(), entry);
177        if rate_limited { Err(error) } else { Ok(()) }
178    }
179}
180
181/// Go `pruneLocked`: entries an hour past their cooldown go, at most hourly.
182fn prune(state: &mut State, now: SystemTime) {
183    if state.next_prune_at.is_some_and(|at| now < at) {
184        return;
185    }
186    let hour = Duration::from_secs(3600);
187    state.entries.retain(|_, e| {
188        e.retry_at
189            .is_some_and(|at| at.checked_add(hour).is_none_or(|end| now < end))
190    });
191    state.next_prune_at = now.checked_add(hour);
192}
193
194/// Go `githubRetryAfter`: delta seconds or an HTTP date.
195fn retry_after(value: &str, now: SystemTime) -> Option<SystemTime> {
196    let value = value.trim();
197    if let Ok(seconds) = value.parse::<i64>()
198        && (0..=i64::MAX / 1_000_000_000).contains(&seconds)
199    {
200        return Some(now + Duration::from_secs(seconds as u64));
201    }
202    http_date(value)
203}
204
205/// `http.ParseTime`: RFC 1123 (`GMT`), RFC 850, or ANSI C asctime.
206fn http_date(value: &str) -> Option<SystemTime> {
207    for layout in [
208        "%a, %d %b %Y %H:%M:%S GMT",
209        "%A, %d-%b-%y %H:%M:%S GMT",
210        "%a %b %e %H:%M:%S %Y",
211    ] {
212        if let Ok(t) = chrono::NaiveDateTime::parse_from_str(value, layout) {
213            return Some(t.and_utc().into());
214        }
215    }
216    None
217}
218
219crate::go_struct! {
220    /// The body Go's `githubRateLimitMessage` decodes.
221    pub struct RateLimitBody("pluginstore.githubRateLimitBody") {
222        "message" => message: String,
223    }
224}
225
226/// Go `githubRateLimitMessage`: `json.Unmarshal` into the struct (keys matched case
227/// insensitively; any decode error means no).
228fn rate_limit_message(body: &[u8]) -> bool {
229    let Ok(decoded) = crate::gojson::from_slice::<RateLimitBody>(body) else {
230        return false;
231    };
232    let text = decoded.message.go_lower();
233    text.contains("secondary rate limit")
234        || text.contains("api rate limit exceeded")
235        || text.contains("abuse detection")
236}
237
238/// Go `githubRateLimitKey`: GitHub API requests only, by request identity.
239pub(super) fn github_rate_limit_key(
240    request_url: &str,
241    network_scope: &str,
242    headers: &Headers,
243    authenticated: bool,
244) -> String {
245    let Some(parsed) = super::url::parse(request_url) else {
246        return String::new();
247    };
248    if !parsed.scheme.eq_ignore_ascii_case("https")
249        || !parsed.hostname.eq_ignore_ascii_case("api.github.com")
250        || !(parsed.port.is_empty() || parsed.port == "443")
251    {
252        return String::new();
253    }
254    format!(
255        "api.github.com/{}",
256        super::client::request_identity(network_scope, headers, authenticated)
257    )
258}
259
260#[cfg(test)]
261mod tests {
262    use super::*;
263
264    fn at(secs: u64) -> SystemTime {
265        SystemTime::UNIX_EPOCH + Duration::from_secs(secs)
266    }
267
268    #[test]
269    fn cooldowns_follow_go() {
270        let limiter = GitHubRateLimiter::with_clock(|| SystemTime::UNIX_EPOCH + Duration::from_secs(1_000));
271        let h = |pairs: &[(&str, &str)]| -> Headers {
272            pairs
273                .iter()
274                .map(|(k, v)| ((*k).to_owned(), vec![(*v).to_owned()]))
275                .collect()
276        };
277        // Headerless secondary limit: one minute.
278        let err = limiter
279            .observe(
280                "k",
281                403,
282                &h(&[]),
283                Some(br#"{"message":"You have exceeded a secondary rate limit"}"#),
284            )
285            .unwrap_err();
286        assert_eq!(err.retry_at, at(1_060));
287        assert!(limiter.check("k").is_err());
288        // The reset header extends a remaining=0 answer, even a successful one.
289        assert!(
290            limiter
291                .observe(
292                    "j",
293                    200,
294                    &h(&[("X-Ratelimit-Remaining", "0"), ("X-Ratelimit-Reset", "5000")]),
295                    None
296                )
297                .is_ok()
298        );
299        assert_eq!(limiter.check("j").unwrap_err().retry_at, at(5_000));
300        assert_eq!(limiter.check("j").unwrap_err().status, 429);
301        let err = limiter
302            .observe("r", 429, &h(&[("Retry-After", "30")]), None)
303            .unwrap_err();
304        assert_eq!(err.retry_after_seconds(at(1_000)), 30);
305        assert_eq!(
306            err.to_string(),
307            "GitHub API rate limited; retry after 1970-01-01T00:17:10Z"
308        );
309    }
310
311    /// An absurd reset header neither panics now nor on the requests after it.
312    #[test]
313    fn extreme_resets_stay_usable() {
314        let limiter = GitHubRateLimiter::with_clock(|| SystemTime::UNIX_EPOCH + Duration::from_secs(1_000));
315        for (key, reset) in [("a", "10000000000000"), ("b", "9223372036854775807")] {
316            let headers: Headers = [
317                ("X-Ratelimit-Remaining".to_owned(), vec!["0".to_owned()]),
318                ("X-Ratelimit-Reset".to_owned(), vec![reset.to_owned()]),
319            ]
320            .into_iter()
321            .collect();
322            let err = limiter.observe(key, 403, &headers, None).unwrap_err();
323            assert_eq!(err.retry_at, at(MAX_RESET));
324            assert_eq!(
325                err.to_string(),
326                "GitHub API rate limited; retry after 9999-12-31T23:59:59Z"
327            );
328            assert_eq!(limiter.check(key).unwrap_err().retry_at, at(MAX_RESET));
329        }
330        // Later requests prune past the stored entries without overflowing.
331        let mut state = limiter.state.lock().unwrap();
332        state.next_prune_at = None;
333        prune(&mut state, at(1_000));
334        assert_eq!(state.entries.len(), 2);
335        drop(state);
336        assert!(limiter.check("other").is_ok());
337        assert!(limiter.observe("other", 200, &Headers::new(), None).is_ok());
338        // A time past chrono's range still prints.
339        let far = RateLimitError {
340            status: 429,
341            retry_at: at(1 << 50),
342        };
343        assert_eq!(far.to_string(), "GitHub API rate limited");
344    }
345}