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