Skip to main content

nautilus_kalshi/http/
quota.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Account-owned token admission using the shared monotonic clock boundary.
17//!
18//! Reservations cover every affected bucket atomically. Changing limits clamps retained balances;
19//! discovery never creates a fresh burst. Costs and limits expire after 60 seconds or grant expiry.
20
21use std::{
22    collections::HashMap,
23    fmt::{Debug, Display},
24    sync::Mutex,
25    time::Duration,
26};
27
28use nautilus_network::ratelimiter::clock::{Clock, MonotonicClock, Reference};
29
30use super::{
31    error::KalshiHttpError,
32    models::{AccountLimits, BucketLimit, EndpointCosts, Field},
33};
34use crate::common::{
35    consts::{BASIC_READ_TOKENS_PER_SEC, BASIC_WRITE_TOKENS_PER_SEC},
36    enums::ApiUsageTier,
37};
38
39const TOKEN_SCALE: u128 = 1_000_000_000;
40const DISCOVERY_TTL: Duration = Duration::from_secs(60);
41
42/// Shared token owner for one Kalshi account and environment.
43///
44/// Pass the same owner to data and execution transports, including transports using different
45/// API keys for that account. Public-only transports can share it with authenticated transports.
46/// Writes remain disabled until both limit and cost discovery succeed.
47#[derive(Debug)]
48pub struct KalshiQuota {
49    pub(super) refresh: tokio::sync::Mutex<()>,
50    meter: Mutex<Meter<MonotonicClock>>,
51}
52
53impl Default for KalshiQuota {
54    fn default() -> Self {
55        Self {
56            refresh: tokio::sync::Mutex::new(()),
57            meter: Mutex::new(Meter::new(MonotonicClock)),
58        }
59    }
60}
61
62impl KalshiQuota {
63    /// Creates an account owner with conservative bootstrap reads and disabled writes.
64    #[must_use]
65    pub fn new() -> Self {
66        Self::default()
67    }
68
69    pub(super) fn needs_refresh(&self) -> bool {
70        let meter = self.meter.lock().expect("quota lock is not poisoned");
71        meter.needs_refresh() || (meter.limits_loaded && meter.costs.is_none())
72    }
73
74    pub(super) fn set_limits(
75        &self,
76        limits: &AccountLimits,
77        unix_ms: i64,
78    ) -> Result<(), KalshiHttpError> {
79        self.meter
80            .lock()
81            .expect("quota lock is not poisoned")
82            .set_limits(limits, unix_ms)
83    }
84
85    pub(super) fn set_costs(&self, costs: EndpointCosts) -> Result<(), KalshiHttpError> {
86        self.meter
87            .lock()
88            .expect("quota lock is not poisoned")
89            .set_costs(costs)
90    }
91
92    pub(super) fn discovery_failed(&self) {
93        self.meter
94            .lock()
95            .expect("quota lock is not poisoned")
96            .discovery_failed();
97    }
98
99    pub(super) async fn acquire(&self, charge: &Charge) -> Result<(), KalshiHttpError> {
100        loop {
101            let wait = self
102                .meter
103                .lock()
104                .expect("quota lock is not poisoned")
105                .reserve(charge)?;
106
107            match wait {
108                None => return Ok(()),
109                Some(wait) => nautilus_network::dst::time::sleep(wait).await,
110            }
111        }
112    }
113
114    pub(super) fn batch_size(&self, charge: &Charge) -> Result<usize, KalshiHttpError> {
115        let meter = self.meter.lock().expect("quota lock is not poisoned");
116        if !meter.limits_loaded
117            || meter.needs_refresh()
118            || meter.costs_expired()
119            || meter.costs.is_none()
120        {
121            return Err(KalshiHttpError::Quota(
122                "write quota discovery is unavailable or expired",
123            ));
124        }
125
126        let size = meter.write.bucket_capacity as u128 / meter.cost(charge);
127        usize::try_from(size)
128            .ok()
129            .filter(|size| *size > 0)
130            .ok_or(KalshiHttpError::Quota(
131                "one batch item exceeds write capacity",
132            ))
133    }
134}
135
136impl Display for KalshiQuota {
137    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
138        let meter = self.meter.lock().expect("quota lock is not poisoned");
139        write!(
140            f,
141            "Read {}/s, capacity {}; write {}/s, capacity {}; limits loaded {}, costs loaded {}",
142            meter.read.refill_rate,
143            meter.read.bucket_capacity,
144            meter.write.refill_rate,
145            meter.write.bucket_capacity,
146            meter.limits_loaded,
147            meter.costs.is_some()
148        )
149    }
150}
151
152#[derive(Debug)]
153pub(super) struct Charge {
154    pub method: String,
155    pub path: String,
156    pub bucket: Bucket,
157    pub items: u32,
158}
159
160#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
161pub(super) enum Bucket {
162    Read,
163    Balance,
164    Write(u32),
165    Auto,
166}
167
168#[derive(Debug)]
169struct Meter<C: Clock> {
170    clock: C,
171    read: BucketLimit,
172    write: BucketLimit,
173    balance: BucketLimit,
174    buckets: HashMap<Bucket, Balance<C::Instant>>,
175    costs: Option<EndpointCosts>,
176    costs_refreshed: Option<C::Instant>,
177    limits_loaded: bool,
178    refreshed: Option<C::Instant>,
179    ttl: Duration,
180}
181
182impl<C: Clock> Meter<C> {
183    fn new(clock: C) -> Self {
184        Self {
185            clock,
186            read: BucketLimit {
187                refill_rate: BASIC_READ_TOKENS_PER_SEC.into(),
188                bucket_capacity: BASIC_READ_TOKENS_PER_SEC.into(),
189            },
190            write: BucketLimit {
191                refill_rate: BASIC_WRITE_TOKENS_PER_SEC.into(),
192                bucket_capacity: BASIC_WRITE_TOKENS_PER_SEC.into(),
193            },
194            balance: BucketLimit {
195                refill_rate: 1,
196                bucket_capacity: 1,
197            },
198            buckets: HashMap::new(),
199            costs: None,
200            costs_refreshed: None,
201            limits_loaded: false,
202            refreshed: None,
203            ttl: DISCOVERY_TTL,
204        }
205    }
206
207    fn needs_refresh(&self) -> bool {
208        self.refreshed.is_none_or(|last| {
209            let elapsed: u64 = self.clock.now().duration_since(last).into();
210            Duration::from_nanos(elapsed) >= self.ttl
211        }) || self.costs_expired()
212    }
213
214    fn set_limits(&mut self, limits: &AccountLimits, unix_ms: i64) -> Result<(), KalshiHttpError> {
215        for limit in [&limits.read, &limits.write] {
216            if limit.refill_rate <= 0 || limit.bucket_capacity <= 0 {
217                return Err(KalshiHttpError::Quota("nonpositive venue token limit"));
218            }
219        }
220
221        let ttl = limits
222            .grants
223            .iter()
224            .filter_map(|grant| match grant.expires_ts {
225                Field::Value(expiry) => Some(Duration::from_millis(
226                    expiry.saturating_mul(1000).saturating_sub(unix_ms).max(0) as u64,
227                )),
228                _ => None,
229            })
230            .min()
231            .unwrap_or(DISCOVERY_TTL)
232            .min(DISCOVERY_TTL);
233
234        if ttl.is_zero() {
235            return Err(KalshiHttpError::Quota("expired venue token grant"));
236        }
237
238        self.update_balances();
239        self.read = limits.read.clone();
240        self.write = limits.write.clone();
241
242        let rate = if matches!(
243            limits.usage_tier,
244            ApiUsageTier::Expert
245                | ApiUsageTier::Premier
246                | ApiUsageTier::Paragon
247                | ApiUsageTier::Prime
248                | ApiUsageTier::Prestige
249        ) {
250            5
251        } else {
252            1
253        };
254
255        self.balance = BucketLimit {
256            refill_rate: rate,
257            bucket_capacity: rate,
258        };
259
260        self.clamp_balances();
261        self.limits_loaded = true;
262        self.refreshed = Some(self.clock.now());
263        self.ttl = ttl;
264
265        Ok(())
266    }
267
268    fn set_costs(&mut self, costs: EndpointCosts) -> Result<(), KalshiHttpError> {
269        if costs.default_cost <= 0
270            || costs
271                .endpoint_costs
272                .iter()
273                .any(|cost| cost.cost <= 0 || !cost.path.starts_with('/') || cost.method.is_empty())
274        {
275            return Err(KalshiHttpError::Quota("invalid venue endpoint costs"));
276        }
277
278        self.costs = Some(costs);
279        self.costs_refreshed = Some(self.clock.now());
280        Ok(())
281    }
282
283    fn discovery_failed(&mut self) {
284        self.update_balances();
285
286        self.read = BucketLimit {
287            refill_rate: BASIC_READ_TOKENS_PER_SEC.into(),
288            bucket_capacity: BASIC_READ_TOKENS_PER_SEC.into(),
289        };
290
291        self.write = BucketLimit {
292            refill_rate: BASIC_WRITE_TOKENS_PER_SEC.into(),
293            bucket_capacity: BASIC_WRITE_TOKENS_PER_SEC.into(),
294        };
295
296        self.balance = BucketLimit {
297            refill_rate: 1,
298            bucket_capacity: 1,
299        };
300
301        self.clamp_balances();
302        self.limits_loaded = false;
303        self.costs = None;
304        self.costs_refreshed = None;
305        self.refreshed = Some(self.clock.now());
306        self.ttl = Duration::from_secs(5);
307    }
308
309    fn reserve(&mut self, charge: &Charge) -> Result<Option<Duration>, KalshiHttpError> {
310        if self.costs_expired() || (self.limits_loaded && self.needs_refresh()) {
311            self.discovery_failed();
312            self.refreshed = None;
313        }
314
315        let write = matches!(charge.bucket, Bucket::Write(_) | Bucket::Auto);
316        if write && (!self.limits_loaded || self.costs.is_none() || self.needs_refresh()) {
317            return Err(KalshiHttpError::Quota(
318                "write quota discovery is unavailable or expired",
319            ));
320        }
321
322        let cost = if charge.bucket == Bucket::Balance {
323            1
324        } else {
325            self.cost(charge)
326        };
327
328        let cost = cost
329            .checked_mul(u128::from(charge.items))
330            .ok_or(KalshiHttpError::Quota("batch token cost overflow"))?;
331
332        let keys = match charge.bucket {
333            // Current Predictions shards: https://docs.kalshi.com/getting_started/exchange_sharding
334            Bucket::Auto => vec![
335                Bucket::Write(0),
336                Bucket::Write(1),
337                Bucket::Write(2),
338                Bucket::Write(3),
339            ],
340            key => vec![key],
341        };
342
343        let now = self.clock.now();
344        let mut wait = Duration::ZERO;
345
346        for key in &keys {
347            let limit = self.limit(*key).clone();
348            if cost > limit.bucket_capacity as u128 {
349                return Err(KalshiHttpError::Quota(
350                    "request token cost exceeds bucket capacity",
351                ));
352            }
353
354            let balance = self
355                .buckets
356                .entry(*key)
357                .or_insert_with(|| Balance::new(&limit, now));
358            balance.refill(&limit, now);
359            let missing = (cost * TOKEN_SCALE).saturating_sub(balance.tokens);
360            let nanos = missing.div_ceil(limit.refill_rate as u128);
361            let nanos = u64::try_from(nanos)
362                .map_err(|_| KalshiHttpError::Quota("quota wait exceeds clock range"))?;
363            wait = wait.max(Duration::from_nanos(nanos));
364        }
365
366        if !wait.is_zero() {
367            return Ok(Some(wait));
368        }
369
370        for key in keys {
371            self.buckets
372                .get_mut(&key)
373                .expect("admitted bucket exists")
374                .tokens -= cost * TOKEN_SCALE;
375        }
376
377        Ok(None)
378    }
379
380    fn costs_expired(&self) -> bool {
381        self.costs_refreshed.is_some_and(|last| {
382            let elapsed: u64 = self.clock.now().duration_since(last).into();
383            Duration::from_nanos(elapsed) >= DISCOVERY_TTL
384        })
385    }
386
387    fn cost(&self, charge: &Charge) -> u128 {
388        let Some(costs) = &self.costs else { return 50 };
389        costs
390            .endpoint_costs
391            .iter()
392            .filter(|cost| {
393                cost.method.eq_ignore_ascii_case(&charge.method)
394                    && path_matches(&cost.path, &charge.path)
395            })
396            .max_by_key(|cost| {
397                cost.path
398                    .split('/')
399                    .filter(|part| !part.starts_with(':') && !part.starts_with('*'))
400                    .count()
401            })
402            .map_or(costs.default_cost, |cost| cost.cost) as u128
403    }
404
405    fn limit(&self, key: Bucket) -> &BucketLimit {
406        match key {
407            Bucket::Read => &self.read,
408            Bucket::Balance => &self.balance,
409            _ => &self.write,
410        }
411    }
412
413    fn update_balances(&mut self) {
414        let now = self.clock.now();
415
416        for (key, balance) in &mut self.buckets {
417            let limit = match key {
418                Bucket::Read => &self.read,
419                Bucket::Balance => &self.balance,
420                _ => &self.write,
421            };
422
423            balance.refill(limit, now);
424        }
425    }
426
427    fn clamp_balances(&mut self) {
428        for (key, balance) in &mut self.buckets {
429            let limit = match key {
430                Bucket::Read => &self.read,
431                Bucket::Balance => &self.balance,
432                _ => &self.write,
433            };
434
435            balance.tokens = balance
436                .tokens
437                .min(limit.bucket_capacity as u128 * TOKEN_SCALE);
438        }
439    }
440}
441
442#[derive(Debug)]
443struct Balance<I> {
444    tokens: u128,
445    updated: I,
446}
447
448impl<I: Reference> Balance<I> {
449    fn new(limit: &BucketLimit, now: I) -> Self {
450        Self {
451            tokens: limit.bucket_capacity as u128 * TOKEN_SCALE,
452            updated: now,
453        }
454    }
455
456    fn refill(&mut self, limit: &BucketLimit, now: I) {
457        let elapsed: u64 = now.duration_since(self.updated).into();
458        self.tokens = self
459            .tokens
460            .saturating_add(u128::from(elapsed) * limit.refill_rate as u128)
461            .min(limit.bucket_capacity as u128 * TOKEN_SCALE);
462        self.updated = now;
463    }
464}
465
466fn path_matches(pattern: &str, path: &str) -> bool {
467    let mut parts = path.trim_matches('/').split('/');
468
469    for expected in pattern.trim_matches('/').split('/') {
470        if expected.starts_with('*') {
471            return parts.next().is_some();
472        }
473
474        let Some(actual) = parts.next() else {
475            return false;
476        };
477
478        if !expected.starts_with(':') && expected != actual {
479            return false;
480        }
481    }
482
483    parts.next().is_none()
484}
485
486#[cfg(test)]
487mod tests {
488    use nautilus_network::ratelimiter::clock::FakeRelativeClock;
489    use rstest::rstest;
490
491    use super::{super::models::EndpointCost, *};
492
493    fn meter() -> Meter<FakeRelativeClock> {
494        let mut meter = Meter::new(FakeRelativeClock::default());
495        meter
496            .set_limits(
497                &AccountLimits {
498                    usage_tier: "basic".into(),
499                    read: BucketLimit {
500                        refill_rate: 20,
501                        bucket_capacity: 60,
502                    },
503                    write: BucketLimit {
504                        refill_rate: 10,
505                        bucket_capacity: 30,
506                    },
507                    grants: vec![],
508                },
509                0,
510            )
511            .unwrap();
512
513        meter
514            .set_costs(EndpointCosts {
515                default_cost: 10,
516                endpoint_costs: vec![EndpointCost {
517                    method: "DELETE".into(),
518                    path: "/trade-api/v2/portfolio/events/orders/:order_id".into(),
519                    cost: 2,
520                }],
521            })
522            .unwrap();
523
524        meter
525    }
526
527    fn charge(bucket: Bucket, items: u32) -> Charge {
528        Charge {
529            method: "POST".into(),
530            path: "/trade-api/v2/portfolio/events/orders".into(),
531            bucket,
532            items,
533        }
534    }
535
536    #[rstest]
537    fn weighted_refill_capacity_and_full_batch_admission() {
538        let mut meter = meter();
539        let batch = charge(Bucket::Write(0), 3);
540        assert_eq!(meter.reserve(&batch).unwrap(), None);
541        assert_eq!(meter.reserve(&batch).unwrap(), Some(Duration::from_secs(3)));
542        meter.clock.advance(Duration::from_millis(2_999));
543        assert_eq!(
544            meter.reserve(&batch).unwrap(),
545            Some(Duration::from_millis(1))
546        );
547        meter.clock.advance(Duration::from_millis(1));
548        assert_eq!(meter.reserve(&batch).unwrap(), None);
549        meter.clock.advance(Duration::from_secs(9));
550        assert_eq!(meter.reserve(&batch).unwrap(), None);
551        assert_eq!(
552            meter
553                .reserve(&charge(Bucket::Write(0), 4))
554                .unwrap_err()
555                .to_string(),
556            "quota admission failed: request token cost exceeds bucket capacity"
557        );
558        assert_eq!(meter.reserve(&charge(Bucket::Read, 6)).unwrap(), None);
559        assert_eq!(
560            meter.reserve(&charge(Bucket::Read, 1)).unwrap(),
561            Some(Duration::from_millis(500))
562        );
563    }
564
565    #[rstest]
566    fn shard_independence_and_atomic_auto_route() {
567        let mut meter = meter();
568        assert_eq!(meter.reserve(&charge(Bucket::Write(2), 3)).unwrap(), None);
569        assert_eq!(
570            meter.reserve(&charge(Bucket::Auto, 1)).unwrap(),
571            Some(Duration::from_secs(1))
572        );
573
574        for shard in [0, 1, 3] {
575            assert_eq!(
576                meter.reserve(&charge(Bucket::Write(shard), 3)).unwrap(),
577                None
578            );
579        }
580
581        meter.clock.advance(Duration::from_secs(1));
582        assert_eq!(meter.reserve(&charge(Bucket::Auto, 1)).unwrap(), None);
583
584        for shard in [0, 1, 2, 3] {
585            assert_eq!(
586                meter.reserve(&charge(Bucket::Write(shard), 1)).unwrap(),
587                Some(Duration::from_secs(1))
588            );
589        }
590    }
591
592    #[rstest]
593    fn endpoint_weights_and_changed_costs_apply_to_every_item() {
594        let mut meter = meter();
595        let mut cancel = charge(Bucket::Write(1), 15);
596        cancel.method = "DELETE".into();
597        cancel.path.push_str("/order-id");
598        assert_eq!(meter.reserve(&cancel).unwrap(), None);
599        assert_eq!(
600            meter.reserve(&cancel).unwrap(),
601            Some(Duration::from_secs(3))
602        );
603        meter
604            .set_costs(EndpointCosts {
605                default_cost: 5,
606                endpoint_costs: vec![],
607            })
608            .unwrap();
609
610        meter.clock.advance(Duration::from_millis(500));
611        assert_eq!(meter.reserve(&charge(Bucket::Write(1), 1)).unwrap(), None);
612    }
613
614    #[rstest]
615    fn changed_limits_clamp_without_refilling_or_erasing_depletion() {
616        let mut meter = meter();
617        assert_eq!(meter.reserve(&charge(Bucket::Write(0), 2)).unwrap(), None);
618        meter
619            .set_limits(
620                &AccountLimits {
621                    usage_tier: "advanced".into(),
622                    read: BucketLimit {
623                        refill_rate: 30,
624                        bucket_capacity: 90,
625                    },
626                    write: BucketLimit {
627                        refill_rate: 5,
628                        bucket_capacity: 15,
629                    },
630                    grants: vec![],
631                },
632                0,
633            )
634            .unwrap();
635
636        assert_eq!(meter.reserve(&charge(Bucket::Write(0), 1)).unwrap(), None);
637        assert_eq!(
638            meter.reserve(&charge(Bucket::Write(0), 1)).unwrap(),
639            Some(Duration::from_secs(2))
640        );
641    }
642
643    #[rstest]
644    fn missing_failed_and_expired_discovery_disable_writes() {
645        let mut missing = Meter::new(FakeRelativeClock::default());
646        assert!(
647            missing
648                .reserve(&charge(Bucket::Write(0), 1))
649                .unwrap_err()
650                .is_definitely_not_sent()
651        );
652        let mut meter = meter();
653        meter.clock.advance(DISCOVERY_TTL);
654        assert!(
655            meter
656                .reserve(&charge(Bucket::Write(0), 1))
657                .unwrap_err()
658                .is_definitely_not_sent()
659        );
660        assert_eq!(
661            meter.read,
662            BucketLimit {
663                refill_rate: 200,
664                bucket_capacity: 200
665            }
666        );
667        assert!(meter.costs.is_none());
668        assert_eq!(meter.reserve(&charge(Bucket::Read, 4)).unwrap(), None);
669        assert_eq!(
670            meter.reserve(&charge(Bucket::Read, 1)).unwrap(),
671            Some(Duration::from_millis(250))
672        );
673    }
674
675    #[rstest]
676    fn balance_is_separate_and_has_no_burst() {
677        let mut meter = meter();
678        assert_eq!(meter.reserve(&charge(Bucket::Balance, 1)).unwrap(), None);
679        assert_eq!(
680            meter.reserve(&charge(Bucket::Balance, 1)).unwrap(),
681            Some(Duration::from_secs(1))
682        );
683        assert_eq!(meter.reserve(&charge(Bucket::Read, 6)).unwrap(), None);
684    }
685
686    #[rstest]
687    #[case("/trade-api/v2/a/:id", "/trade-api/v2/a/id", true)]
688    #[case("/trade-api/v2/a/:id", "/trade-api/v2/a/id/more", false)]
689    #[case("/trade-api/v2/a/*rest", "/trade-api/v2/a/id/more", true)]
690    #[case("/trade-api/v2/a/:id", "/trade-api/v2/b/id", false)]
691    fn endpoint_templates(#[case] pattern: &str, #[case] path: &str, #[case] expected: bool) {
692        assert_eq!(path_matches(pattern, path), expected);
693    }
694
695    #[rstest]
696    fn public_costs_expire_without_loaded_limits() {
697        let mut meter = Meter::new(FakeRelativeClock::default());
698        meter
699            .set_costs(EndpointCosts {
700                default_cost: 10,
701                endpoint_costs: vec![],
702            })
703            .unwrap();
704
705        assert_eq!(meter.reserve(&charge(Bucket::Read, 20)).unwrap(), None);
706        assert!(meter.costs.is_some());
707        meter.clock.advance(DISCOVERY_TTL);
708        assert_eq!(meter.reserve(&charge(Bucket::Read, 4)).unwrap(), None);
709        assert!(meter.costs.is_none());
710        assert_eq!(
711            meter.reserve(&charge(Bucket::Read, 1)).unwrap(),
712            Some(Duration::from_millis(250))
713        );
714        assert!(meter.needs_refresh());
715    }
716
717    #[rstest]
718    fn expired_reservation_keeps_discovery_due() {
719        let mut meter = meter();
720        meter.clock.advance(DISCOVERY_TTL);
721        assert!(meter.reserve(&charge(Bucket::Write(0), 1)).is_err());
722        assert!(meter.needs_refresh());
723    }
724
725    #[rstest]
726    fn limit_only_refresh_does_not_extend_cost_freshness() {
727        let mut meter = meter();
728        meter.clock.advance(Duration::from_secs(30));
729
730        let limits = AccountLimits {
731            usage_tier: "basic".into(),
732            read: meter.read.clone(),
733            write: meter.write.clone(),
734            grants: vec![],
735        };
736
737        meter.set_limits(&limits, 30_000).unwrap();
738        meter.clock.advance(Duration::from_secs(29));
739        assert!(!meter.needs_refresh());
740        meter.clock.advance(Duration::from_secs(1));
741        assert!(meter.needs_refresh());
742    }
743
744    #[rstest]
745    #[case(1_000)]
746    #[case(1_001)]
747    fn received_expired_grant_is_immediately_stale(#[case] unix_ms: i64) {
748        let mut meter = meter();
749
750        let limits = AccountLimits {
751            usage_tier: "expert".into(),
752            read: meter.read.clone(),
753            write: meter.write.clone(),
754            grants: vec![super::super::models::UsageGrant {
755                exchange_instance: "event_contract".into(),
756                level: "expert".into(),
757                source: "synthetic".into(),
758                expires_ts: Field::Value(1),
759            }],
760        };
761
762        let error = meter.set_limits(&limits, unix_ms).unwrap_err();
763        assert!(matches!(
764            error,
765            KalshiHttpError::Quota("expired venue token grant")
766        ));
767    }
768
769    #[rstest]
770    fn temporary_grant_expires_at_exact_millisecond_boundary() {
771        let mut meter = meter();
772
773        let limits = AccountLimits {
774            usage_tier: "expert".into(),
775            read: meter.read.clone(),
776            write: meter.write.clone(),
777            grants: vec![super::super::models::UsageGrant {
778                exchange_instance: "event_contract".into(),
779                level: "expert".into(),
780                source: "synthetic".into(),
781                expires_ts: Field::Value(1),
782            }],
783        };
784
785        meter.set_limits(&limits, 750).unwrap();
786        meter.clock.advance(Duration::from_millis(249));
787        assert!(!meter.needs_refresh());
788        meter.clock.advance(Duration::from_millis(1));
789        assert!(meter.needs_refresh());
790        assert!(
791            meter
792                .reserve(&charge(Bucket::Write(0), 1))
793                .unwrap_err()
794                .is_definitely_not_sent()
795        );
796    }
797}