Skip to main content

nautilus_common/
throttler.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//! Message throttling and rate limiting functionality.
17//!
18//! This module provides throttling capabilities to control the rate of message processing
19//! and prevent system overload. The throttler can buffer, drop, or delay messages based
20//! on configured rate limits and time intervals.
21
22use std::{
23    any::Any,
24    cell::{RefCell, UnsafeCell},
25    collections::VecDeque,
26    fmt::{Debug, Display},
27    marker::PhantomData,
28    num::{NonZeroU64, NonZeroUsize},
29    rc::Rc,
30};
31
32use nautilus_core::{DurationNanos, UnixNanos, correctness::FAILED};
33use serde::{Deserialize, Serialize};
34use ustr::Ustr;
35
36use crate::{
37    actor::{
38        Actor,
39        registry::{register_actor, try_get_actor_unchecked, with_actor_registry},
40    },
41    clock::Clock,
42    msgbus::{self, Endpoint, Handler, MStr, ShareableMessageHandler},
43    timer::{TimeEvent, TimeEventCallback},
44};
45
46const MAX_INITIAL_TIMESTAMPS_CAPACITY: usize = 1024;
47
48/// Throttler rate limits messages by dropping or buffering them.
49///
50/// Throttler takes messages of type T and callback of type F for dropping
51/// or processing messages.
52///
53/// The throttler stores its limit and interval as non-zero values from
54/// [`RateLimit`]. Internal counters, buffers, and timer state stay private so
55/// callers can observe state without breaking rate-limit invariants.
56///
57/// # Callback contract
58///
59/// The `output_send` and `output_drop` callbacks are invoked inline from
60/// [`Throttler::send`] and the drain handler. They must not reenter the
61/// throttler (for example by calling `send` synchronously), since the
62/// throttler mutates its buffer and window state through `UnsafeCell` without
63/// borrow-check protection. Route side effects through an asynchronous queue
64/// when in doubt.
65///
66/// # Buffered mode contract
67///
68/// Buffered mode (`output_drop` is `None`) drains through a message-bus
69/// endpoint registered by [`Throttler::to_actor`]. An embedded throttler that
70/// is never registered cannot drain: any buffered messages accumulate without
71/// bound. Embedded throttlers that can reach the limit must therefore use
72/// drop mode (provide `output_drop`), where the `send()` auto-reset provides
73/// recovery.
74pub struct Throttler<T, F> {
75    clock: Rc<RefCell<dyn Clock>>,
76    actor_id: Ustr,
77    timer_name: Ustr,
78    limit: NonZeroUsize,
79    interval_ns: NonZeroU64,
80    large_limit: bool,
81    buffer: VecDeque<T>,
82    timestamps: VecDeque<UnixNanos>,
83    is_limiting: bool,
84    recv_count: usize,
85    sent_count: usize,
86    output_send: F,
87    output_drop: Option<F>,
88}
89
90impl<T, F> Actor for Throttler<T, F>
91where
92    T: 'static + Debug,
93    F: Fn(T) + 'static,
94{
95    fn id(&self) -> Ustr {
96        self.actor_id
97    }
98
99    fn handle(&mut self, _msg: &dyn Any) {}
100
101    fn as_any(&self) -> &dyn Any {
102        self
103    }
104}
105
106impl<T, F> Debug for Throttler<T, F>
107where
108    T: Debug,
109{
110    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
111        f.debug_struct(stringify!(Throttler))
112            .field("actor_id", &self.actor_id)
113            .field("timer_name", &self.timer_name)
114            .field("limit", &self.limit())
115            .field("interval_ns", &self.interval_ns().as_u64())
116            .field("buffer", &self.buffer)
117            .field("timestamps", &self.timestamps)
118            .field("is_limiting", &self.is_limiting)
119            .field("recv_count", &self.recv_count)
120            .field("sent_count", &self.sent_count)
121            .finish()
122    }
123}
124
125impl<T, F> Throttler<T, F>
126where
127    T: Debug,
128{
129    /// Creates a new [`Throttler`] instance.
130    ///
131    /// The timer is registered under a name namespaced by `actor_id` so multiple
132    /// throttlers can share one clock.
133    #[inline]
134    pub fn new(
135        rate_limit: RateLimit,
136        clock: Rc<RefCell<dyn Clock>>,
137        timer_name: &str,
138        output_send: F,
139        output_drop: Option<F>,
140        actor_id: Ustr,
141    ) -> Self {
142        Self {
143            clock,
144            actor_id,
145            timer_name: Ustr::from(format!("{timer_name}-{actor_id}").as_str()),
146            limit: rate_limit.limit,
147            interval_ns: rate_limit.interval_ns,
148            large_limit: rate_limit.limit.get() > MAX_INITIAL_TIMESTAMPS_CAPACITY,
149            buffer: VecDeque::new(),
150            timestamps: VecDeque::with_capacity(
151                rate_limit.limit.get().min(MAX_INITIAL_TIMESTAMPS_CAPACITY),
152            ),
153            is_limiting: false,
154            recv_count: 0,
155            sent_count: 0,
156            output_send,
157            output_drop,
158        }
159    }
160
161    /// Set timer with a callback to be triggered on next interval.
162    ///
163    /// Typically used to register callbacks:
164    /// - to process buffered messages
165    /// - to stop buffering
166    ///
167    /// `allow_past` is set explicitly so a zero `delta_next` clamps to the
168    /// current time and fires immediately instead of returning an error.
169    ///
170    /// # Panics
171    ///
172    /// Panics if setting the time alert on the internal clock fails.
173    #[inline]
174    pub(crate) fn set_timer(&self, callback: Option<TimeEventCallback>) {
175        let mut clock = self.clock.borrow_mut();
176        if clock.timer_exists(&self.timer_name) {
177            clock.cancel_timer(&self.timer_name);
178        }
179
180        let now = clock.timestamp_ns();
181
182        let Some(alert_ts) = now.checked_add(self.delta_next_at(now)) else {
183            // No future deadline is representable, so leave the throttler limiting without a timer
184            return;
185        };
186
187        clock
188            .set_time_alert_ns(self.timer_name.as_str(), alert_ts, callback, Some(true))
189            .expect(FAILED);
190    }
191
192    /// Time delta when the next message can be sent.
193    ///
194    /// Uses saturating subtraction so a clock regression or a future-dated
195    /// timestamp yields a zero delta instead of panicking.
196    #[inline]
197    pub fn delta_next(&self) -> DurationNanos {
198        match self.timestamps.get(self.limit.get() - 1) {
199            Some(ts) => {
200                let diff = self
201                    .clock
202                    .borrow()
203                    .timestamp_ns()
204                    .saturating_duration_since(*ts);
205                DurationNanos::new(self.interval_ns.get()).saturating_sub(diff)
206            }
207            None => DurationNanos::default(),
208        }
209    }
210
211    #[inline]
212    fn delta_next_at(&self, now: UnixNanos) -> DurationNanos {
213        match self.timestamps.get(self.limit.get() - 1) {
214            Some(ts) => {
215                let diff = now.saturating_duration_since(*ts);
216                DurationNanos::new(self.interval_ns.get()).saturating_sub(diff)
217            }
218            None => DurationNanos::default(),
219        }
220    }
221
222    /// Reset the throttler which clears internal state and cancels any pending
223    /// timer so no drain or resume callback fires after reset.
224    #[inline]
225    pub fn reset(&mut self) {
226        self.cancel_timer_internal();
227        self.buffer.clear();
228        self.recv_count = 0;
229        self.sent_count = 0;
230        self.is_limiting = false;
231        self.timestamps.clear();
232    }
233}
234
235impl<T, F> Throttler<T, F> {
236    /// Cancels the throttler's timer if one is pending. Silently does nothing
237    /// when the clock is borrowed elsewhere or no timer exists (best-effort,
238    /// e.g. from `Drop`).
239    ///
240    /// Lives in a boundless impl block so `Drop` (which has no `T: Debug` bound)
241    /// can call it.
242    fn cancel_timer_internal(&self) {
243        if let Ok(mut clock) = self.clock.try_borrow_mut() {
244            clock.cancel_timer(&self.timer_name);
245        }
246    }
247
248    /// Counts sent messages whose timestamps fall inside the current interval
249    /// window. Shared by [`Throttler::used`] and [`Throttler::try_reserve`].
250    fn count_in_window(&self, now: UnixNanos) -> usize {
251        let Some(interval_start) = now.checked_sub(DurationNanos::new(self.interval_ns.get()))
252        else {
253            return self.timestamps.len();
254        };
255
256        if let Some(oldest) = self.timestamps.back()
257            && *oldest > interval_start
258        {
259            return self.timestamps.len();
260        }
261
262        match self.timestamps.front() {
263            Some(newest) if *newest > interval_start => {}
264            _ => return 0,
265        }
266
267        self.timestamps
268            .iter()
269            .take_while(|&&ts| ts > interval_start)
270            .count()
271    }
272
273    /// Maximum number of messages that can be sent within the interval.
274    #[inline]
275    pub const fn limit(&self) -> usize {
276        self.limit.get()
277    }
278
279    /// Interval between messages in nanoseconds.
280    #[inline]
281    pub const fn interval_ns(&self) -> DurationNanos {
282        DurationNanos::new(self.interval_ns.get())
283    }
284
285    /// Rate limit configured for this throttler.
286    #[inline]
287    pub const fn rate_limit(&self) -> RateLimit {
288        RateLimit {
289            limit: self.limit,
290            interval_ns: self.interval_ns,
291        }
292    }
293
294    /// Number of messages queued in buffer.
295    #[inline]
296    pub fn qsize(&self) -> usize {
297        self.buffer.len()
298    }
299
300    /// Fractional value of rate limit consumed in current interval.
301    #[inline]
302    pub fn used(&self) -> f64 {
303        if self.timestamps.is_empty() {
304            return 0.0;
305        }
306        let messages_in_current_interval = self.count_in_window(self.clock.borrow().timestamp_ns());
307        (messages_in_current_interval as f64) / (self.limit.get() as f64)
308    }
309
310    /// Whether the throttler is currently limiting the message rate.
311    #[inline]
312    pub const fn is_limiting(&self) -> bool {
313        self.is_limiting
314    }
315
316    /// Number of messages received.
317    #[inline]
318    pub const fn recv_count(&self) -> usize {
319        self.recv_count
320    }
321
322    /// Number of messages sent.
323    #[inline]
324    pub const fn sent_count(&self) -> usize {
325        self.sent_count
326    }
327}
328
329impl<T, F> Throttler<T, F>
330where
331    T: 'static + Debug,
332    F: Fn(T) + 'static,
333{
334    /// Registers the throttler's process endpoint and actor state, returning
335    /// the shared handle.
336    pub fn to_actor(self) -> Rc<UnsafeCell<Self>> {
337        // Register process endpoint
338        let process_handler = ThrottlerProcess::<T, F>::new(self.actor_id);
339        msgbus::register_any(
340            process_handler.id().into(),
341            ShareableMessageHandler::from(Rc::new(process_handler) as Rc<dyn Handler<dyn Any>>),
342        );
343
344        // Register actor state and return the wrapped reference
345        register_actor(self)
346    }
347
348    /// Disposes of the throttler by cancelling its timer, deregistering its
349    /// process endpoint from the message bus, and removing it from the actor
350    /// registry.
351    ///
352    /// Call this before dropping a throttler registered via [`Throttler::to_actor`]
353    /// to avoid leaking the process endpoint. For embedded throttlers (not
354    /// registered) this is still safe: the endpoint and registry removals are
355    /// no-ops.
356    pub fn dispose(&mut self) {
357        self.cancel_timer_internal();
358        msgbus::deregister_any(process_endpoint(self.actor_id));
359        with_actor_registry(|registry| {
360            registry.remove(&self.actor_id);
361        });
362    }
363
364    #[inline]
365    pub(crate) fn send_msg(&mut self, msg: T) {
366        let now = self.clock.borrow().timestamp_ns();
367
368        if self.timestamps.len() >= self.limit.get() {
369            self.timestamps.pop_back();
370        }
371        self.timestamps.push_front(now);
372
373        self.sent_count += 1;
374        (self.output_send)(msg);
375    }
376
377    /// Reserves capacity for `count` messages without sending callbacks.
378    ///
379    /// Returns `false` when the current window cannot accept all messages. No partial
380    /// reservation is made in that case. The resume timer is armed only when the
381    /// window is genuinely full (`delta_next > 0`); when the window already slid
382    /// (`delta_next == 0`) the next call re-evaluates without arming a zero-delta
383    /// timer that would fire immediately and log spam.
384    #[inline]
385    pub fn try_reserve(&mut self, count: usize) -> bool {
386        self.recv_count += count;
387
388        if count == 0 {
389            return true;
390        }
391
392        let now = self.clock.borrow().timestamp_ns();
393        let delta = self.delta_next_at(now);
394        if self.is_limiting && delta.is_zero() && self.buffer.is_empty() {
395            self.is_limiting = false;
396        }
397
398        if self.is_limiting {
399            return false;
400        }
401
402        let used = self.count_in_window(now);
403
404        if self.limit.get().saturating_sub(used) < count {
405            self.is_limiting = true;
406
407            if !delta.is_zero() {
408                self.set_timer(Some(throttler_resume::<T, F>(self.actor_id)));
409            }
410            return false;
411        }
412
413        for _ in 0..count {
414            if self.timestamps.len() >= self.limit.get() {
415                self.timestamps.pop_back();
416            }
417            self.timestamps.push_front(now);
418        }
419        self.sent_count += count;
420        true
421    }
422
423    #[inline]
424    pub(crate) fn limit_msg(&mut self, msg: T) {
425        if self.output_drop.is_none() {
426            self.buffer.push_front(msg);
427            log::debug!("Buffering {}", self.buffer.len());
428
429            if !self.is_limiting {
430                log::debug!("Limiting");
431                let cb = Some(ThrottlerProcess::<T, F>::new(self.actor_id).get_timer_callback());
432                self.set_timer(cb);
433                self.is_limiting = true;
434            }
435        } else {
436            log::debug!("Dropping");
437
438            if let Some(drop) = &self.output_drop {
439                drop(msg);
440            }
441
442            if !self.is_limiting {
443                log::debug!("Limiting");
444                self.set_timer(Some(throttler_resume::<T, F>(self.actor_id)));
445                self.is_limiting = true;
446            }
447        }
448    }
449
450    #[inline]
451    pub fn send(&mut self, msg: T)
452    where
453        T: 'static,
454        F: Fn(T) + 'static,
455    {
456        self.recv_count += 1;
457
458        if self.large_limit && self.timestamps.len() < self.limit.get() && !self.is_limiting {
459            self.send_msg(msg);
460            return;
461        }
462
463        let delta = if self.is_limiting && !self.buffer.is_empty() {
464            DurationNanos::default()
465        } else {
466            self.delta_next()
467        };
468
469        // Auto-reset when the rate window has passed but no timer callback
470        // arrived (e.g. for embedded throttlers not registered as actors).
471        // Gated on an empty buffer so buffered throttlers keep draining via
472        // ThrottlerProcess; only drop-mode throttlers have an empty buffer here.
473        if self.is_limiting && delta.is_zero() && self.buffer.is_empty() {
474            self.is_limiting = false;
475        }
476
477        if self.is_limiting || !delta.is_zero() {
478            self.limit_msg(msg);
479        } else {
480            self.send_msg(msg);
481        }
482    }
483}
484
485/// Builds the message-bus endpoint used to drive the buffered drain handler.
486/// Centralized so registration, `dispose`, and `Drop` agree on the name.
487fn process_endpoint(actor_id: Ustr) -> MStr<Endpoint> {
488    MStr::endpoint(format!("{actor_id}_process")).expect(FAILED)
489}
490
491/// Process buffered messages for throttler
492///
493/// When limit is reached, schedules a timer event to call self again. The handler
494/// is registered as a separated endpoint on the message bus as `{actor_id}_process`.
495struct ThrottlerProcess<T, F> {
496    actor_id: Ustr,
497    endpoint: MStr<Endpoint>,
498    phantom_t: PhantomData<T>,
499    phantom_f: PhantomData<F>,
500}
501
502impl<T, F> ThrottlerProcess<T, F>
503where
504    T: Debug,
505{
506    pub(crate) fn new(actor_id: Ustr) -> Self {
507        Self {
508            actor_id,
509            endpoint: process_endpoint(actor_id),
510            phantom_t: PhantomData,
511            phantom_f: PhantomData,
512        }
513    }
514
515    pub(crate) fn get_timer_callback(&self) -> TimeEventCallback {
516        let endpoint = self.endpoint;
517        TimeEventCallback::from(move |event: TimeEvent| {
518            msgbus::send_any(endpoint, &(event));
519        })
520    }
521}
522
523impl<T, F> Handler<dyn Any> for ThrottlerProcess<T, F>
524where
525    T: 'static + Debug,
526    F: Fn(T) + 'static,
527{
528    fn id(&self) -> Ustr {
529        *self.endpoint
530    }
531
532    fn handle(&self, _message: &dyn Any) {
533        // Use the fallible lookup so a late timer fire after teardown is a
534        // no-op rather than a panic.
535        let Some(mut throttler) = try_get_actor_unchecked::<Throttler<T, F>>(&self.actor_id) else {
536            return;
537        };
538
539        while let Some(msg) = throttler.buffer.pop_back() {
540            throttler.send_msg(msg);
541
542            // Set timer to process more buffered messages
543            // if interval limit reached and there are more
544            // buffered messages to process
545            if !throttler.buffer.is_empty() && !throttler.delta_next().is_zero() {
546                throttler.is_limiting = true;
547                throttler.set_timer(Some(self.get_timer_callback()));
548                return;
549            }
550        }
551
552        throttler.is_limiting = false;
553    }
554}
555
556impl<T, F> Drop for Throttler<T, F> {
557    fn drop(&mut self) {
558        // Cancel any pending timer so drain/resume callbacks do not fire after
559        // teardown. Best-effort: skip silently if the shared clock is currently
560        // borrowed (e.g. during a nested drop).
561        self.cancel_timer_internal();
562    }
563}
564
565/// Sets throttler to resume sending messages.
566///
567/// Uses `try_get_actor_unchecked` so that embedded throttlers (not registered
568/// in the actor registry) are handled gracefully. The `send()` auto-reset
569/// ensures such throttlers recover once the rate window passes.
570///
571/// When messages are buffered (possible after a rejected `try_reserve`), the
572/// throttler stays limiting and arms its timer with the drain callback
573/// instead, so buffered messages drain in FIFO order ahead of later sends.
574pub fn throttler_resume<T, F>(actor_id: Ustr) -> TimeEventCallback
575where
576    T: 'static + Debug,
577    F: Fn(T) + 'static,
578{
579    TimeEventCallback::from(move |_event: TimeEvent| {
580        if let Some(mut throttler) = try_get_actor_unchecked::<Throttler<T, F>>(&actor_id) {
581            if throttler.buffer.is_empty() {
582                throttler.is_limiting = false;
583            } else {
584                let cb = Some(ThrottlerProcess::<T, F>::new(actor_id).get_timer_callback());
585                throttler.set_timer(cb);
586            }
587        }
588    })
589}
590
591/// Represents a throttling limit per interval.
592///
593/// Displays as `limit/HH:MM:SS`, with hours unrestricted. Intervals with a subsecond
594/// component append six fractional digits, truncating any precision below microseconds.
595///
596/// The non-zero field types make a degenerate rate limit unrepresentable: a zero `limit`
597/// underflows the throttler's `limit - 1` indexing, and a zero `interval_ns` disables
598/// throttling entirely.
599#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
600#[serde(deny_unknown_fields)]
601pub struct RateLimit {
602    limit: NonZeroUsize,
603    interval_ns: NonZeroU64,
604}
605
606impl RateLimit {
607    /// Creates a new [`RateLimit`] instance with correctness checking.
608    ///
609    /// # Errors
610    ///
611    /// Returns an error if `limit` or `interval_ns` is zero.
612    pub fn new_checked(limit: usize, interval_ns: DurationNanos) -> anyhow::Result<Self> {
613        let limit = NonZeroUsize::new(limit)
614            .ok_or_else(|| anyhow::anyhow!("Invalid limit: {limit} (must be non-zero)"))?;
615
616        let interval_ns = NonZeroU64::new(interval_ns.as_u64()).ok_or_else(|| {
617            anyhow::anyhow!("Invalid interval_ns: {interval_ns} (must be non-zero)")
618        })?;
619
620        Ok(Self { limit, interval_ns })
621    }
622
623    /// Creates a new [`RateLimit`] instance.
624    ///
625    /// # Panics
626    ///
627    /// Panics if `limit` or `interval_ns` is zero.
628    #[must_use]
629    pub fn new(limit: usize, interval_ns: DurationNanos) -> Self {
630        Self::new_checked(limit, interval_ns).expect(FAILED)
631    }
632
633    /// Maximum number of messages that can be sent within the interval.
634    #[must_use]
635    pub const fn limit(&self) -> usize {
636        self.limit.get()
637    }
638
639    /// Interval between messages in nanoseconds.
640    #[must_use]
641    pub const fn interval_ns(&self) -> DurationNanos {
642        DurationNanos::new(self.interval_ns.get())
643    }
644}
645
646impl Display for RateLimit {
647    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
648        let interval = self.interval_ns();
649        let limit = self.limit();
650        let total_secs = interval.as_secs();
651        let remainder_ns = interval.subsec_nanos();
652        let hours = total_secs / 3600;
653        let minutes = (total_secs % 3600) / 60;
654        let seconds = total_secs % 60;
655
656        if remainder_ns == 0 {
657            write!(f, "{limit}/{hours:02}:{minutes:02}:{seconds:02}")
658        } else {
659            let micros = remainder_ns / 1_000;
660            write!(
661                f,
662                "{limit}/{hours:02}:{minutes:02}:{seconds:02}.{micros:06}"
663            )
664        }
665    }
666}
667
668#[cfg(test)]
669mod tests {
670    use std::{
671        cell::{RefCell, UnsafeCell},
672        rc::Rc,
673    };
674
675    use nautilus_core::{DurationNanos, UUID4, UnixNanos};
676    use rstest::{fixture, rstest};
677    use ustr::Ustr;
678
679    use super::{MAX_INITIAL_TIMESTAMPS_CAPACITY, RateLimit, Throttler, ThrottlerProcess};
680    use crate::{
681        clock::{Clock, VirtualClock},
682        msgbus::{self, Handler},
683    };
684    type SharedThrottler = Rc<UnsafeCell<Throttler<u64, Box<dyn Fn(u64)>>>>;
685
686    /// Test throttler with default values for testing
687    ///
688    /// - Rate limit is 5 messages in 10 intervals.
689    /// - Message handling is decided by specific fixture
690    #[derive(Clone)]
691    struct TestThrottler {
692        throttler: SharedThrottler,
693        clock: Rc<RefCell<VirtualClock>>,
694        interval: DurationNanos,
695    }
696
697    #[allow(unsafe_code)]
698    impl TestThrottler {
699        #[expect(clippy::mut_from_ref)]
700        pub(crate) fn get_throttler(&self) -> &mut Throttler<u64, Box<dyn Fn(u64)>> {
701            unsafe { &mut *self.throttler.get() }
702        }
703    }
704
705    // Timer names are namespaced as `{base}-{actor_id}` with a random actor_id,
706    // so tests match on the base prefix and the expected count instead of an
707    // exact name.
708    fn timer_count_with_prefix(
709        throttler: &Throttler<u64, Box<dyn Fn(u64)>>,
710        prefix: &str,
711    ) -> usize {
712        throttler
713            .clock
714            .borrow()
715            .timer_names()
716            .iter()
717            .filter(|name| name.starts_with(prefix))
718            .count()
719    }
720
721    #[allow(unsafe_code)]
722    #[expect(clippy::mut_from_ref)]
723    fn access_shared(t: &SharedThrottler) -> &mut Throttler<u64, Box<dyn Fn(u64)>> {
724        unsafe { &mut *t.get() }
725    }
726
727    #[rstest]
728    #[case(0, 1_000)]
729    #[case(1_000, 0)]
730    fn test_rate_limit_new_checked_rejects_zero(#[case] limit: usize, #[case] interval_ns: u64) {
731        assert!(RateLimit::new_checked(limit, DurationNanos::new(interval_ns)).is_err());
732    }
733
734    #[rstest]
735    #[case(0, 1_000)]
736    #[case(1_000, 0)]
737    #[should_panic]
738    fn test_rate_limit_new_panics_on_zero(#[case] limit: usize, #[case] interval_ns: u64) {
739        let _ = RateLimit::new(limit, DurationNanos::new(interval_ns));
740    }
741
742    #[rstest]
743    fn test_rate_limit_new_checked_accepts_positive() {
744        let rate = RateLimit::new_checked(5, DurationNanos::new(10)).unwrap();
745
746        assert_eq!(rate.limit(), 5);
747        assert_eq!(rate.interval_ns(), DurationNanos::new(10));
748    }
749
750    #[rstest]
751    #[case::whole_seconds(100, 1_000_000_000, "100/00:00:01")]
752    #[case::hours_minutes_seconds(17, 3_723_000_000_000, "17/01:02:03")]
753    #[case::large_hours(23, 360_000_000_000_000, "23/100:00:00")]
754    #[case::fractional_seconds(31, 1_234_567_000, "31/00:00:01.234567")]
755    #[case::truncated_nanoseconds(41, 1_234_567_890, "41/00:00:01.234567")]
756    #[case::below_microsecond(53, 999, "53/00:00:00.000000")]
757    fn test_rate_limit_display(
758        #[case] limit: usize,
759        #[case] interval_ns: u64,
760        #[case] expected: &str,
761    ) {
762        let rate = RateLimit::new(limit, DurationNanos::new(interval_ns));
763
764        assert_eq!(rate.to_string(), expected);
765    }
766
767    #[fixture]
768    pub fn test_throttler_buffered() -> TestThrottler {
769        let output_send: Box<dyn Fn(u64)> = Box::new(|msg: u64| {
770            log::debug!("Sent: {msg}");
771        });
772        let clock = Rc::new(RefCell::new(VirtualClock::new()));
773        let inner_clock = Rc::clone(&clock);
774        let rate_limit = RateLimit::new(5, DurationNanos::new(10));
775        let interval = rate_limit.interval_ns();
776        let actor_id = Ustr::from(UUID4::new().as_str());
777
778        TestThrottler {
779            throttler: Throttler::new(
780                rate_limit,
781                clock,
782                "buffer_timer",
783                output_send,
784                None,
785                actor_id,
786            )
787            .to_actor(),
788            clock: inner_clock,
789            interval,
790        }
791    }
792
793    #[fixture]
794    pub fn test_throttler_unbuffered() -> TestThrottler {
795        let output_send: Box<dyn Fn(u64)> = Box::new(|msg: u64| {
796            log::debug!("Sent: {msg}");
797        });
798        let output_drop: Box<dyn Fn(u64)> = Box::new(|msg: u64| {
799            log::debug!("Dropped: {msg}");
800        });
801        let clock = Rc::new(RefCell::new(VirtualClock::new()));
802        let inner_clock = Rc::clone(&clock);
803        let rate_limit = RateLimit::new(5, DurationNanos::new(10));
804        let interval = rate_limit.interval_ns();
805        let actor_id = Ustr::from(UUID4::new().as_str());
806
807        TestThrottler {
808            throttler: Throttler::new(
809                rate_limit,
810                clock,
811                "dropper_timer",
812                output_send,
813                Some(output_drop),
814                actor_id,
815            )
816            .to_actor(),
817            clock: inner_clock,
818            interval,
819        }
820    }
821
822    #[rstest]
823    fn test_buffering_send_to_limit_becomes_throttled(test_throttler_buffered: TestThrottler) {
824        let throttler = test_throttler_buffered.get_throttler();
825        for _ in 0..6 {
826            throttler.send(42);
827        }
828        assert_eq!(throttler.qsize(), 1);
829
830        assert!(throttler.is_limiting);
831        assert_eq!(throttler.recv_count, 6);
832        assert_eq!(throttler.sent_count, 5);
833        assert_eq!(timer_count_with_prefix(throttler, "buffer_timer"), 1);
834    }
835
836    #[rstest]
837    fn test_buffering_used_when_sent_to_limit_returns_one(test_throttler_buffered: TestThrottler) {
838        let throttler = test_throttler_buffered.get_throttler();
839
840        for _ in 0..5 {
841            throttler.send(42);
842        }
843
844        assert_eq!(throttler.used(), 1.0);
845        assert_eq!(throttler.recv_count, 5);
846        assert_eq!(throttler.sent_count, 5);
847    }
848
849    #[rstest]
850    fn test_buffering_used_when_half_interval_from_limit_returns_one(
851        test_throttler_buffered: TestThrottler,
852    ) {
853        let throttler = test_throttler_buffered.get_throttler();
854
855        for _ in 0..5 {
856            throttler.send(42);
857        }
858
859        let half_interval = test_throttler_buffered.interval / 2;
860        // Advance the clock by half the interval
861        {
862            let mut clock = test_throttler_buffered.clock.borrow_mut();
863            clock.advance_time(UnixNanos::default() + half_interval, true);
864        }
865
866        assert_eq!(throttler.used(), 1.0);
867        assert_eq!(throttler.recv_count, 5);
868        assert_eq!(throttler.sent_count, 5);
869    }
870
871    #[rstest]
872    fn test_buffering_used_before_limit_when_halfway_returns_half(
873        test_throttler_buffered: TestThrottler,
874    ) {
875        let throttler = test_throttler_buffered.get_throttler();
876
877        for _ in 0..3 {
878            throttler.send(42);
879        }
880
881        assert_eq!(throttler.used(), 0.6);
882        assert_eq!(throttler.recv_count, 3);
883        assert_eq!(throttler.sent_count, 3);
884    }
885
886    #[rstest]
887    fn test_try_reserve_counts_messages_without_output(test_throttler_buffered: TestThrottler) {
888        let throttler = test_throttler_buffered.get_throttler();
889
890        assert!(throttler.try_reserve(3));
891
892        assert_eq!(throttler.used(), 0.6);
893        assert_eq!(throttler.recv_count, 3);
894        assert_eq!(throttler.sent_count, 3);
895        assert_eq!(throttler.qsize(), 0);
896    }
897
898    #[rstest]
899    fn test_try_reserve_rejects_when_full_batch_exceeds_limit(
900        test_throttler_buffered: TestThrottler,
901    ) {
902        let throttler = test_throttler_buffered.get_throttler();
903
904        assert!(throttler.try_reserve(3));
905        assert!(!throttler.try_reserve(3));
906
907        assert_eq!(throttler.used(), 0.6);
908        assert_eq!(throttler.recv_count, 6);
909        assert_eq!(throttler.sent_count, 3);
910        assert_eq!(throttler.qsize(), 0);
911        assert!(throttler.is_limiting);
912        // delta_next == 0 here (only 3 of 5 slots used), so the resume timer is
913        // not armed to avoid an immediate-fire zero-delta timer. The next call
914        // re-evaluates via the auto-reset branch.
915        assert_eq!(timer_count_with_prefix(throttler, "buffer_timer"), 0);
916
917        assert!(throttler.try_reserve(2));
918
919        assert_eq!(throttler.used(), 1.0);
920        assert_eq!(throttler.recv_count, 8);
921        assert_eq!(throttler.sent_count, 5);
922        assert_eq!(throttler.qsize(), 0);
923        assert!(!throttler.is_limiting);
924    }
925
926    #[rstest]
927    fn test_try_reserve_rejects_batch_larger_than_limit() {
928        let clock: Rc<RefCell<dyn Clock>> = Rc::new(RefCell::new(VirtualClock::new()));
929        let mut throttler = Throttler::<u64, Box<dyn Fn(u64)>>::new(
930            RateLimit::new(5, DurationNanos::new(10)),
931            clock,
932            "reserve_over_limit",
933            Box::new(|_| ()) as Box<dyn Fn(u64)>,
934            None,
935            Ustr::from("reserve-over-limit-actor"),
936        );
937
938        assert!(!throttler.try_reserve(6));
939
940        assert_eq!(throttler.used(), 0.0);
941        assert_eq!(throttler.recv_count, 6);
942        assert_eq!(throttler.sent_count, 0);
943        assert_eq!(throttler.qsize(), 0);
944        assert!(throttler.is_limiting);
945        assert_eq!(throttler.clock.borrow().timer_count(), 0);
946    }
947
948    #[rstest]
949    fn test_try_reserve_zero_count_is_noop() {
950        let clock: Rc<RefCell<dyn Clock>> = Rc::new(RefCell::new(VirtualClock::new()));
951        let mut throttler = Throttler::<u64, Box<dyn Fn(u64)>>::new(
952            RateLimit::new(5, DurationNanos::new(10)),
953            clock,
954            "reserve_zero",
955            Box::new(|_| ()) as Box<dyn Fn(u64)>,
956            None,
957            Ustr::from("reserve-zero-actor"),
958        );
959
960        assert!(throttler.try_reserve(0));
961
962        assert_eq!(throttler.used(), 0.0);
963        assert_eq!(throttler.recv_count, 0);
964        assert_eq!(throttler.sent_count, 0);
965        assert_eq!(throttler.qsize(), 0);
966        assert!(!throttler.is_limiting);
967        assert_eq!(throttler.clock.borrow().timer_count(), 0);
968    }
969
970    #[rstest]
971    fn test_buffering_refresh_when_at_limit_sends_remaining_items(
972        test_throttler_buffered: TestThrottler,
973    ) {
974        let throttler = test_throttler_buffered.get_throttler();
975
976        for _ in 0..6 {
977            throttler.send(42);
978        }
979
980        // Advance time and process events
981        {
982            let mut clock = test_throttler_buffered.clock.borrow_mut();
983            let time_events = clock.advance_time(
984                UnixNanos::default() + test_throttler_buffered.interval,
985                true,
986            );
987
988            for each_event in clock.match_handlers(time_events) {
989                drop(clock); // Release the mutable borrow
990
991                each_event.callback.call(each_event.event);
992
993                // Re-borrow the clock for the next iteration
994                clock = test_throttler_buffered.clock.borrow_mut();
995            }
996        }
997
998        // Assert final state
999        assert_eq!(throttler.used(), 0.2);
1000        assert_eq!(throttler.recv_count, 6);
1001        assert_eq!(throttler.sent_count, 6);
1002        assert_eq!(throttler.qsize(), 0);
1003    }
1004
1005    #[rstest]
1006    fn test_buffering_send_message_after_buffering_message(test_throttler_buffered: TestThrottler) {
1007        let throttler = test_throttler_buffered.get_throttler();
1008
1009        for _ in 0..6 {
1010            throttler.send(43);
1011        }
1012
1013        // Advance time and process events
1014        {
1015            let mut clock = test_throttler_buffered.clock.borrow_mut();
1016            let time_events = clock.advance_time(
1017                UnixNanos::default() + test_throttler_buffered.interval,
1018                true,
1019            );
1020
1021            for each_event in clock.match_handlers(time_events) {
1022                drop(clock); // Release the mutable borrow
1023
1024                each_event.callback.call(each_event.event);
1025
1026                // Re-borrow the clock for the next iteration
1027                clock = test_throttler_buffered.clock.borrow_mut();
1028            }
1029        }
1030
1031        for _ in 0..6 {
1032            throttler.send(42);
1033        }
1034
1035        // Assert final state
1036        assert_eq!(throttler.used(), 1.0);
1037        assert_eq!(throttler.recv_count, 12);
1038        assert_eq!(throttler.sent_count, 10);
1039        assert_eq!(throttler.qsize(), 2);
1040    }
1041
1042    #[rstest]
1043    fn test_buffering_send_message_after_halfway_after_buffering_message(
1044        test_throttler_buffered: TestThrottler,
1045    ) {
1046        let throttler = test_throttler_buffered.get_throttler();
1047
1048        for _ in 0..6 {
1049            throttler.send(42);
1050        }
1051
1052        // Advance time and process events
1053        {
1054            let mut clock = test_throttler_buffered.clock.borrow_mut();
1055            let time_events = clock.advance_time(
1056                UnixNanos::default() + test_throttler_buffered.interval,
1057                true,
1058            );
1059
1060            for each_event in clock.match_handlers(time_events) {
1061                drop(clock); // Release the mutable borrow
1062
1063                each_event.callback.call(each_event.event);
1064
1065                // Re-borrow the clock for the next iteration
1066                clock = test_throttler_buffered.clock.borrow_mut();
1067            }
1068        }
1069
1070        for _ in 0..3 {
1071            throttler.send(42);
1072        }
1073
1074        // Assert final state
1075        assert_eq!(throttler.used(), 0.8);
1076        assert_eq!(throttler.recv_count, 9);
1077        assert_eq!(throttler.sent_count, 9);
1078        assert_eq!(throttler.qsize(), 0);
1079    }
1080
1081    #[rstest]
1082    fn test_dropping_send_sends_message_to_handler(test_throttler_unbuffered: TestThrottler) {
1083        let throttler = test_throttler_unbuffered.get_throttler();
1084        throttler.send(42);
1085
1086        assert!(!throttler.is_limiting);
1087        assert_eq!(throttler.recv_count, 1);
1088        assert_eq!(throttler.sent_count, 1);
1089    }
1090
1091    #[rstest]
1092    fn test_dropping_send_to_limit_drops_message(test_throttler_unbuffered: TestThrottler) {
1093        let throttler = test_throttler_unbuffered.get_throttler();
1094        for _ in 0..6 {
1095            throttler.send(42);
1096        }
1097        assert_eq!(throttler.qsize(), 0);
1098
1099        assert!(throttler.is_limiting);
1100        assert_eq!(throttler.used(), 1.0);
1101        assert_eq!(throttler.clock.borrow().timer_count(), 1);
1102        assert_eq!(timer_count_with_prefix(throttler, "dropper_timer"), 1);
1103        assert_eq!(throttler.recv_count, 6);
1104        assert_eq!(throttler.sent_count, 5);
1105    }
1106
1107    #[rstest]
1108    fn test_dropping_advance_time_when_at_limit_dropped_message(
1109        test_throttler_unbuffered: TestThrottler,
1110    ) {
1111        let throttler = test_throttler_unbuffered.get_throttler();
1112        for _ in 0..6 {
1113            throttler.send(42);
1114        }
1115
1116        // Advance time and process events
1117        {
1118            let mut clock = test_throttler_unbuffered.clock.borrow_mut();
1119            let time_events = clock.advance_time(
1120                UnixNanos::default() + test_throttler_unbuffered.interval,
1121                true,
1122            );
1123
1124            for each_event in clock.match_handlers(time_events) {
1125                drop(clock); // Release the mutable borrow
1126
1127                each_event.callback.call(each_event.event);
1128
1129                // Re-borrow the clock for the next iteration
1130                clock = test_throttler_unbuffered.clock.borrow_mut();
1131            }
1132        }
1133
1134        assert_eq!(throttler.clock.borrow().timer_count(), 0);
1135        assert!(!throttler.is_limiting);
1136        assert_eq!(throttler.used(), 0.0);
1137        assert_eq!(throttler.recv_count, 6);
1138        assert_eq!(throttler.sent_count, 5);
1139    }
1140
1141    #[rstest]
1142    fn test_dropping_send_message_after_dropping_message(test_throttler_unbuffered: TestThrottler) {
1143        let throttler = test_throttler_unbuffered.get_throttler();
1144        for _ in 0..6 {
1145            throttler.send(42);
1146        }
1147
1148        // Advance time and process events
1149        {
1150            let mut clock = test_throttler_unbuffered.clock.borrow_mut();
1151            let time_events = clock.advance_time(
1152                UnixNanos::default() + test_throttler_unbuffered.interval,
1153                true,
1154            );
1155
1156            for each_event in clock.match_handlers(time_events) {
1157                drop(clock); // Release the mutable borrow
1158
1159                each_event.callback.call(each_event.event);
1160
1161                // Re-borrow the clock for the next iteration
1162                clock = test_throttler_unbuffered.clock.borrow_mut();
1163            }
1164        }
1165
1166        throttler.send(42);
1167
1168        assert_eq!(throttler.used(), 0.2);
1169        assert_eq!(throttler.clock.borrow().timer_count(), 0);
1170        assert!(!throttler.is_limiting);
1171        assert_eq!(throttler.recv_count, 7);
1172        assert_eq!(throttler.sent_count, 6);
1173    }
1174
1175    #[rstest]
1176    fn test_embedded_dropping_auto_resets_after_window_without_actor_callback() {
1177        let clock: Rc<RefCell<VirtualClock>> = Rc::new(RefCell::new(VirtualClock::new()));
1178        let sent = Rc::new(RefCell::new(0));
1179        let dropped = Rc::new(RefCell::new(0));
1180
1181        let sent_cb = {
1182            let sent = Rc::clone(&sent);
1183            Box::new(move |_| *sent.borrow_mut() += 1) as Box<dyn Fn(u64)>
1184        };
1185        let drop_cb = {
1186            let dropped = Rc::clone(&dropped);
1187            Box::new(move |_| *dropped.borrow_mut() += 1) as Box<dyn Fn(u64)>
1188        };
1189
1190        let mut throttler = Throttler::new(
1191            RateLimit::new(5, DurationNanos::new(10)),
1192            Rc::clone(&clock) as Rc<RefCell<dyn Clock>>,
1193            "embedded_drop_timer",
1194            sent_cb,
1195            Some(drop_cb),
1196            Ustr::from("embedded-drop-actor"),
1197        );
1198
1199        for _ in 0..6 {
1200            throttler.send(42);
1201        }
1202        let events = clock.borrow_mut().advance_time(10.into(), true);
1203        throttler.send(42);
1204
1205        assert_eq!(events.len(), 1);
1206        assert_eq!(*sent.borrow(), 6);
1207        assert_eq!(*dropped.borrow(), 1);
1208        assert_eq!(throttler.recv_count, 7);
1209        assert_eq!(throttler.sent_count, 6);
1210        assert!(!throttler.is_limiting);
1211        assert_eq!(throttler.clock.borrow().timer_count(), 0);
1212    }
1213
1214    #[rstest]
1215    fn test_large_limit_fast_path_admits_until_limit_then_limits() {
1216        let clock: Rc<RefCell<dyn Clock>> = Rc::new(RefCell::new(VirtualClock::new()));
1217        let limit = MAX_INITIAL_TIMESTAMPS_CAPACITY + 1;
1218        let mut throttler = Throttler::<u64, Box<dyn Fn(u64)>>::new(
1219            RateLimit::new(limit, DurationNanos::new(10)),
1220            clock,
1221            "large_limit_timer",
1222            Box::new(|_| ()) as Box<dyn Fn(u64)>,
1223            None,
1224            Ustr::from("large-limit-actor"),
1225        );
1226
1227        for _ in 0..limit {
1228            throttler.send(42);
1229        }
1230        throttler.send(42);
1231
1232        assert_eq!(throttler.used(), 1.0);
1233        assert_eq!(throttler.recv_count, limit + 1);
1234        assert_eq!(throttler.sent_count, limit);
1235        assert_eq!(throttler.qsize(), 1);
1236        assert!(throttler.is_limiting);
1237        assert_eq!(throttler.clock.borrow().timer_count(), 1);
1238    }
1239
1240    #[rstest]
1241    fn test_new_preserves_rate_limit() {
1242        let clock: Rc<RefCell<dyn Clock>> = Rc::new(RefCell::new(VirtualClock::new()));
1243        let rate_limit = RateLimit::new(5, DurationNanos::new(10));
1244
1245        let throttler = Throttler::<u64, Box<dyn Fn(u64)>>::new(
1246            rate_limit,
1247            clock,
1248            "rate_limit",
1249            Box::new(|_| ()) as Box<dyn Fn(u64)>,
1250            None,
1251            Ustr::from("rate-limit-actor"),
1252        );
1253
1254        assert_eq!(throttler.rate_limit(), rate_limit);
1255        assert_eq!(throttler.limit(), 5);
1256        assert_eq!(throttler.interval_ns(), DurationNanos::new(10));
1257    }
1258
1259    #[rstest]
1260    fn test_debug_output_includes_identity_and_state() {
1261        let clock: Rc<RefCell<dyn Clock>> = Rc::new(RefCell::new(VirtualClock::new()));
1262        let actor_id = Ustr::from("debug-actor");
1263        let mut throttler = Throttler::<u64, Box<dyn Fn(u64)>>::new(
1264            RateLimit::new(5, DurationNanos::new(10)),
1265            clock,
1266            "debug_timer",
1267            Box::new(|_| ()) as Box<dyn Fn(u64)>,
1268            None,
1269            actor_id,
1270        );
1271
1272        throttler.send(42);
1273
1274        let debug = format!("{throttler:?}");
1275        let timer_name = Ustr::from("debug_timer-debug-actor");
1276
1277        assert!(debug.contains(&format!("actor_id: {actor_id:?}")));
1278        assert!(debug.contains(&format!("timer_name: {timer_name:?}")));
1279        assert!(debug.contains("limit: 5"));
1280        assert!(debug.contains("interval_ns: 10"));
1281        assert!(debug.contains("is_limiting: false"));
1282        assert!(debug.contains("recv_count: 1"));
1283        assert!(debug.contains("sent_count: 1"));
1284    }
1285
1286    #[rstest]
1287    fn test_reset_clears_state_and_cancels_timer(test_throttler_buffered: TestThrottler) {
1288        let throttler = test_throttler_buffered.get_throttler();
1289
1290        for _ in 0..6 {
1291            throttler.send(42);
1292        }
1293        assert_eq!(timer_count_with_prefix(throttler, "buffer_timer"), 1);
1294        assert_eq!(throttler.qsize(), 1);
1295
1296        throttler.reset();
1297
1298        assert_eq!(throttler.qsize(), 0);
1299        assert_eq!(throttler.recv_count, 0);
1300        assert_eq!(throttler.sent_count, 0);
1301        assert!(!throttler.is_limiting);
1302        assert!(throttler.timestamps.is_empty());
1303        assert_eq!(timer_count_with_prefix(throttler, "buffer_timer"), 0);
1304        assert_eq!(throttler.clock.borrow().timer_count(), 0);
1305    }
1306
1307    #[rstest]
1308    fn test_two_throttlers_share_clock_without_timer_collision() {
1309        let clock: Rc<RefCell<VirtualClock>> = Rc::new(RefCell::new(VirtualClock::new()));
1310        let interval = 10u64;
1311
1312        let mk = |base: &str| -> SharedThrottler {
1313            let clock: Rc<RefCell<dyn Clock>> = Rc::clone(&clock) as Rc<RefCell<dyn Clock>>;
1314            Throttler::new(
1315                RateLimit::new(5, DurationNanos::new(interval)),
1316                clock,
1317                base,
1318                Box::new(|_| ()) as Box<dyn Fn(u64)>,
1319                None,
1320                Ustr::from(UUID4::new().as_str()),
1321            )
1322            .to_actor()
1323        };
1324
1325        let t1 = mk("shared_timer");
1326        let t2 = mk("shared_timer");
1327
1328        // Both throttlers use the same base timer name on a shared clock; the
1329        // namespaced names must keep both timers distinct.
1330        {
1331            let t1 = access_shared(&t1);
1332
1333            for _ in 0..6 {
1334                t1.send(42);
1335            }
1336        }
1337        {
1338            let t2 = access_shared(&t2);
1339
1340            for _ in 0..6 {
1341                t2.send(42);
1342            }
1343        }
1344
1345        let clock_ref = clock.borrow();
1346        let names = clock_ref.timer_names();
1347        let shared_count = names
1348            .iter()
1349            .filter(|n| n.starts_with("shared_timer"))
1350            .count();
1351        assert_eq!(
1352            shared_count, 2,
1353            "two distinct timers expected, found {names:?}"
1354        );
1355    }
1356
1357    #[rstest]
1358    fn test_try_reserve_then_send_interleaved(test_throttler_buffered: TestThrottler) {
1359        let throttler = test_throttler_buffered.get_throttler();
1360
1361        // Reserve 3 of 5 slots, then send one more via the send path. Both
1362        // paths share the same window: 4 of 5 slots should be used.
1363        assert!(throttler.try_reserve(3));
1364        throttler.send(42);
1365
1366        assert_eq!(throttler.recv_count, 4);
1367        assert_eq!(throttler.sent_count, 4);
1368        assert_eq!(throttler.used(), 0.8);
1369        assert!(!throttler.is_limiting);
1370    }
1371
1372    #[rstest]
1373    #[case::buffered(false)]
1374    #[case::drop(true)]
1375    fn test_send_at_unrepresentable_deadline_stays_limited(#[case] drop_mode: bool) {
1376        let clock = Rc::new(RefCell::new(VirtualClock::new()));
1377        clock
1378            .borrow_mut()
1379            .advance_time(UnixNanos::new(u64::MAX - 5), true);
1380        let sent = Rc::new(RefCell::new(Vec::new()));
1381        let dropped = Rc::new(RefCell::new(Vec::new()));
1382
1383        let output_send = {
1384            let sent = Rc::clone(&sent);
1385            Box::new(move |msg| sent.borrow_mut().push(msg)) as Box<dyn Fn(u64)>
1386        };
1387
1388        let output_drop = drop_mode.then(|| {
1389            let dropped = Rc::clone(&dropped);
1390            Box::new(move |msg| dropped.borrow_mut().push(msg)) as Box<dyn Fn(u64)>
1391        });
1392
1393        let mut throttler = Throttler::new(
1394            RateLimit::new(1, DurationNanos::new(10)),
1395            Rc::clone(&clock) as Rc<RefCell<dyn Clock>>,
1396            "overflow_send_timer",
1397            output_send,
1398            output_drop,
1399            Ustr::from("overflow-send-actor"),
1400        );
1401
1402        throttler.send(1);
1403        throttler.send(2);
1404        let events = clock.borrow_mut().advance_time(UnixNanos::max(), true);
1405        throttler.send(3);
1406
1407        assert!(events.is_empty());
1408        assert_eq!(*sent.borrow(), vec![1_u64]);
1409        assert_eq!(
1410            *dropped.borrow(),
1411            if drop_mode { vec![2_u64, 3] } else { vec![] }
1412        );
1413        assert_eq!(throttler.qsize(), if drop_mode { 0 } else { 2 });
1414        assert_eq!(throttler.recv_count(), 3);
1415        assert_eq!(throttler.sent_count(), 1);
1416        assert!(throttler.is_limiting());
1417        assert_eq!(clock.borrow().timer_count(), 0);
1418    }
1419
1420    #[rstest]
1421    fn test_try_reserve_at_unrepresentable_deadline_stays_limited() {
1422        let clock = Rc::new(RefCell::new(VirtualClock::new()));
1423        clock
1424            .borrow_mut()
1425            .advance_time(UnixNanos::new(u64::MAX - 5), true);
1426
1427        let mut throttler = Throttler::new(
1428            RateLimit::new(1, DurationNanos::new(10)),
1429            Rc::clone(&clock) as Rc<RefCell<dyn Clock>>,
1430            "overflow_reserve_timer",
1431            Box::new(|_| ()) as Box<dyn Fn(u64)>,
1432            None,
1433            Ustr::from("overflow-reserve-actor"),
1434        );
1435
1436        assert!(throttler.try_reserve(1));
1437        assert!(!throttler.try_reserve(1));
1438        let events = clock.borrow_mut().advance_time(UnixNanos::max(), true);
1439        assert!(!throttler.try_reserve(1));
1440
1441        assert!(events.is_empty());
1442        assert_eq!(throttler.qsize(), 0);
1443        assert_eq!(throttler.recv_count(), 3);
1444        assert_eq!(throttler.sent_count(), 1);
1445        assert!(throttler.is_limiting());
1446        assert_eq!(clock.borrow().timer_count(), 0);
1447    }
1448
1449    #[rstest]
1450    #[case::drains(2, 0, false)]
1451    #[case::rearm_overflow(3, 1, true)]
1452    fn test_buffered_send_at_maximum_representable_deadline(
1453        #[case] received: u64,
1454        #[case] expected_qsize: usize,
1455        #[case] expected_limiting: bool,
1456    ) {
1457        let clock = Rc::new(RefCell::new(VirtualClock::new()));
1458        clock
1459            .borrow_mut()
1460            .advance_time(UnixNanos::new(u64::MAX - 10), true);
1461        let sent = Rc::new(RefCell::new(Vec::new()));
1462
1463        let output_send = {
1464            let sent = Rc::clone(&sent);
1465            Box::new(move |msg| sent.borrow_mut().push(msg)) as Box<dyn Fn(u64)>
1466        };
1467
1468        let throttler = Throttler::new(
1469            RateLimit::new(1, DurationNanos::new(10)),
1470            Rc::clone(&clock) as Rc<RefCell<dyn Clock>>,
1471            "maximum_deadline_timer",
1472            output_send,
1473            None,
1474            Ustr::from("maximum-deadline-actor"),
1475        )
1476        .to_actor();
1477        let throttler = access_shared(&throttler);
1478        for msg in 1..=received {
1479            throttler.send(msg);
1480        }
1481
1482        let early_events = clock
1483            .borrow_mut()
1484            .advance_time(UnixNanos::new(u64::MAX - 1), true);
1485        let due_events = clock.borrow_mut().advance_time(UnixNanos::max(), true);
1486        assert!(early_events.is_empty());
1487        assert_eq!(due_events.len(), 1);
1488        assert_eq!(due_events[0].ts_event, UnixNanos::max());
1489
1490        let handlers = clock.borrow().match_handlers(due_events);
1491        for handler in handlers {
1492            handler.callback.call(handler.event);
1493        }
1494
1495        assert_eq!(*sent.borrow(), vec![1_u64, 2]);
1496        assert_eq!(throttler.qsize(), expected_qsize);
1497        assert_eq!(throttler.recv_count(), received as usize);
1498        assert_eq!(throttler.sent_count(), 2);
1499        assert_eq!(throttler.is_limiting(), expected_limiting);
1500        assert_eq!(clock.borrow().timer_count(), 0);
1501    }
1502
1503    #[rstest]
1504    fn test_dispose_cancels_timer_and_deregisters_endpoint(test_throttler_buffered: TestThrottler) {
1505        let throttler = test_throttler_buffered.get_throttler();
1506
1507        for _ in 0..6 {
1508            throttler.send(42);
1509        }
1510        let actor_id = throttler.actor_id;
1511        let endpoint_name = format!("{actor_id}_process");
1512        assert_eq!(timer_count_with_prefix(throttler, "buffer_timer"), 1);
1513        assert!(msgbus::has_endpoint(&endpoint_name));
1514
1515        throttler.dispose();
1516
1517        assert_eq!(throttler.clock.borrow().timer_count(), 0);
1518        assert!(
1519            !msgbus::has_endpoint(&endpoint_name),
1520            "dispose must deregister the process endpoint"
1521        );
1522    }
1523
1524    #[rstest]
1525    fn test_try_reserve_then_buffered_sends_drain_in_order_after_window() {
1526        let clock: Rc<RefCell<VirtualClock>> = Rc::new(RefCell::new(VirtualClock::new()));
1527        let sent: Rc<RefCell<Vec<u64>>> = Rc::new(RefCell::new(Vec::new()));
1528        let sent_cb = {
1529            let sent = Rc::clone(&sent);
1530            Box::new(move |msg| sent.borrow_mut().push(msg)) as Box<dyn Fn(u64)>
1531        };
1532        let throttler = Throttler::new(
1533            RateLimit::new(5, DurationNanos::new(10)),
1534            Rc::clone(&clock) as Rc<RefCell<dyn Clock>>,
1535            "reserve_drain_timer",
1536            sent_cb,
1537            None,
1538            Ustr::from(UUID4::new().as_str()),
1539        )
1540        .to_actor();
1541        let throttler = access_shared(&throttler);
1542
1543        assert!(throttler.try_reserve(5));
1544        assert!(!throttler.try_reserve(1));
1545        assert!(throttler.is_limiting);
1546
1547        throttler.send(1);
1548        throttler.send(2);
1549        assert_eq!(throttler.qsize(), 2);
1550        assert!(sent.borrow().is_empty());
1551
1552        // The rejected reservation armed only the resume timer. Firing it must
1553        // arm the drain callback and keep limiting, not drain yet or resume.
1554        {
1555            let mut clock_ref = clock.borrow_mut();
1556            let time_events = clock_ref.advance_time(10.into(), true);
1557            for each_event in clock_ref.match_handlers(time_events) {
1558                drop(clock_ref);
1559                each_event.callback.call(each_event.event);
1560                clock_ref = clock.borrow_mut();
1561            }
1562        }
1563        assert!(throttler.is_limiting);
1564        assert_eq!(throttler.qsize(), 2);
1565        assert!(sent.borrow().is_empty());
1566
1567        // A send after the resume fires must queue behind the buffered messages
1568        throttler.send(3);
1569        assert_eq!(throttler.qsize(), 3);
1570        assert!(sent.borrow().is_empty());
1571
1572        for _ in 0..10 {
1573            if throttler.qsize() == 0 && !throttler.is_limiting {
1574                break;
1575            }
1576            let mut clock_ref = clock.borrow_mut();
1577            let current_time = clock_ref.get_time_ns();
1578            let time_events = clock_ref.advance_time(current_time + DurationNanos::new(10), true);
1579            for each_event in clock_ref.match_handlers(time_events) {
1580                drop(clock_ref);
1581                each_event.callback.call(each_event.event);
1582                clock_ref = clock.borrow_mut();
1583            }
1584        }
1585
1586        assert_eq!(*sent.borrow(), vec![1, 2, 3]);
1587        assert_eq!(throttler.qsize(), 0);
1588        assert!(!throttler.is_limiting);
1589        assert_eq!(throttler.sent_count, 8);
1590        assert_eq!(throttler.clock.borrow().timer_count(), 0);
1591    }
1592
1593    ////////////////////////////////////////////////////////////////////////////////
1594    // Property-based testing
1595    ////////////////////////////////////////////////////////////////////////////////
1596
1597    use proptest::prelude::*;
1598
1599    #[derive(Clone, Debug)]
1600    enum ThrottlerInput {
1601        SendMessage(u64),
1602        AdvanceClock(u8),
1603    }
1604
1605    // Custom strategy for ThrottlerInput
1606    fn throttler_input_strategy() -> impl Strategy<Value = ThrottlerInput> {
1607        prop_oneof![
1608            2 => prop::bool::ANY.prop_map(|_| ThrottlerInput::SendMessage(42)),
1609            8 => prop::num::u8::ANY.prop_map(|v| ThrottlerInput::AdvanceClock(v % 5 + 5)),
1610        ]
1611    }
1612
1613    // Custom strategy for ThrottlerTest
1614    fn throttler_test_strategy() -> impl Strategy<Value = Vec<ThrottlerInput>> {
1615        prop::collection::vec(throttler_input_strategy(), 10..=150)
1616    }
1617
1618    fn test_throttler_with_inputs(inputs: Vec<ThrottlerInput>, test_throttler: &TestThrottler) {
1619        let test_clock = test_throttler.clock.clone();
1620        let interval = test_throttler.interval;
1621        let throttler = test_throttler.get_throttler();
1622        let mut sent_count = 0;
1623
1624        for input in inputs {
1625            match input {
1626                ThrottlerInput::SendMessage(msg) => {
1627                    throttler.send(msg);
1628                    sent_count += 1;
1629                }
1630                ThrottlerInput::AdvanceClock(duration) => {
1631                    let mut clock_ref = test_clock.borrow_mut();
1632                    let current_time = clock_ref.get_time_ns();
1633                    let time_events = clock_ref
1634                        .advance_time(current_time + DurationNanos::new(u64::from(duration)), true);
1635
1636                    for each_event in clock_ref.match_handlers(time_events) {
1637                        drop(clock_ref);
1638                        each_event.callback.call(each_event.event);
1639                        clock_ref = test_clock.borrow_mut();
1640                    }
1641                }
1642            }
1643
1644            // Check the throttler rate limits on the appropriate conditions
1645            // * At least one message is buffered
1646            // * Timestamp queue is filled upto limit
1647            // * Least recent timestamp in queue exceeds interval
1648            let buffered_messages = throttler.qsize() > 0;
1649            let now = throttler.clock.borrow().timestamp_ns();
1650            let limit_filled_within_interval = throttler
1651                .timestamps
1652                .get(throttler.limit() - 1)
1653                .is_some_and(|&ts| (now - ts) < interval);
1654            let expected_limiting = buffered_messages && limit_filled_within_interval;
1655            assert_eq!(throttler.is_limiting, expected_limiting);
1656
1657            // Message conservation
1658            assert_eq!(sent_count, throttler.sent_count + throttler.qsize());
1659        }
1660
1661        // Drain all buffered messages by repeatedly advancing the clock.
1662        // Each timer callback may send up to `limit` messages and schedule
1663        // a new timer for the next batch, so we must keep advancing.
1664        for i in 1..=100u64 {
1665            if throttler.qsize() == 0 {
1666                break;
1667            }
1668            let advance_to = UnixNanos::default() + interval * 100 * i;
1669            let time_events = test_clock.borrow_mut().advance_time(advance_to, true);
1670            let mut clock_ref = test_clock.borrow_mut();
1671            for each_event in clock_ref.match_handlers(time_events) {
1672                drop(clock_ref);
1673                each_event.callback.call(each_event.event);
1674                clock_ref = test_clock.borrow_mut();
1675            }
1676        }
1677        assert_eq!(throttler.qsize(), 0);
1678    }
1679
1680    #[rstest]
1681    fn prop_test() {
1682        // Create a fresh throttler for each iteration to ensure clean state,
1683        // even when tests panic (which would skip the reset code)
1684        proptest!(|(inputs in throttler_test_strategy())| {
1685            let test_throttler = test_throttler_buffered();
1686            test_throttler_with_inputs(inputs, &test_throttler);
1687        });
1688    }
1689
1690    #[rstest]
1691    fn prop_test_dropping() {
1692        // Drop-mode coverage: every received message is either sent or dropped,
1693        // and sent_count tracks the send callback exactly. Catches conservation
1694        // violations and panics under random send/advance sequences.
1695        proptest!(|(inputs in throttler_test_strategy())| {
1696            let clock = Rc::new(RefCell::new(VirtualClock::new()));
1697            let sent: Rc<RefCell<usize>> = Rc::new(RefCell::new(0));
1698            let dropped: Rc<RefCell<usize>> = Rc::new(RefCell::new(0));
1699
1700            let sent_cb = {
1701                let sent = Rc::clone(&sent);
1702                Box::new(move |_| *sent.borrow_mut() += 1) as Box<dyn Fn(u64)>
1703            };
1704            let drop_cb = {
1705                let dropped = Rc::clone(&dropped);
1706                Box::new(move |_| *dropped.borrow_mut() += 1) as Box<dyn Fn(u64)>
1707            };
1708
1709            let interval = 10u64;
1710            let throttler = Throttler::new(
1711                RateLimit::new(5, DurationNanos::new(interval)),
1712                Rc::clone(&clock) as Rc<RefCell<dyn Clock>>,
1713                "prop_drop_timer",
1714                sent_cb,
1715                Some(drop_cb),
1716                Ustr::from(UUID4::new().as_str()),
1717            )
1718            .to_actor();
1719            let throttler = access_shared(&throttler);
1720
1721            for input in inputs {
1722                match input {
1723                    ThrottlerInput::SendMessage(msg) => {
1724                        throttler.send(msg);
1725                    }
1726                    ThrottlerInput::AdvanceClock(duration) => {
1727                        let mut clock_ref = clock.borrow_mut();
1728                        let current_time = clock_ref.get_time_ns();
1729                        let time_events = clock_ref.advance_time(
1730                            current_time + DurationNanos::new(u64::from(duration)),
1731                            true,
1732                        );
1733
1734                        for each_event in clock_ref.match_handlers(time_events) {
1735                            drop(clock_ref);
1736                            each_event.callback.call(each_event.event);
1737                            clock_ref = clock.borrow_mut();
1738                        }
1739                    }
1740                }
1741
1742                let sent_now = *sent.borrow();
1743                let dropped_now = *dropped.borrow();
1744                // Conservation: every received message was sent or dropped.
1745                assert_eq!(sent_now + dropped_now, throttler.recv_count);
1746                assert_eq!(throttler.sent_count, sent_now);
1747                assert!(throttler.qsize() == 0, "drop mode must never buffer");
1748            }
1749        });
1750    }
1751
1752    #[derive(Clone, Debug)]
1753    enum ThrottlerReserveInput {
1754        SendMessage(u64),
1755        TryReserve(u8),
1756        AdvanceClock(u8),
1757    }
1758
1759    fn throttler_reserve_input_strategy() -> impl Strategy<Value = ThrottlerReserveInput> {
1760        prop_oneof![
1761            2 => prop::bool::ANY.prop_map(|_| ThrottlerReserveInput::SendMessage(42)),
1762            2 => prop::num::u8::ANY.prop_map(|v| ThrottlerReserveInput::TryReserve(v % 6 + 1)),
1763            6 => prop::num::u8::ANY.prop_map(|v| ThrottlerReserveInput::AdvanceClock(v % 5 + 5)),
1764        ]
1765    }
1766
1767    #[rstest]
1768    fn prop_test_try_reserve_interleaved() {
1769        // Mixing try_reserve with sends: conservation must hold across every
1770        // interleaving, and the buffer must always drain eventually (a
1771        // rejected reservation arms only the resume timer, which must hand off
1772        // to the drain handler when messages are buffered).
1773        proptest!(|(inputs in prop::collection::vec(throttler_reserve_input_strategy(), 10..=150))| {
1774            let test_throttler = test_throttler_buffered();
1775            let test_clock = test_throttler.clock.clone();
1776            let interval = test_throttler.interval;
1777            let throttler = test_throttler.get_throttler();
1778            let mut attempted = 0usize;
1779            let mut reserved = 0usize;
1780
1781            for input in inputs {
1782                match input {
1783                    ThrottlerReserveInput::SendMessage(msg) => {
1784                        throttler.send(msg);
1785                        attempted += 1;
1786                    }
1787                    ThrottlerReserveInput::TryReserve(n) => {
1788                        if throttler.try_reserve(usize::from(n)) {
1789                            reserved += usize::from(n);
1790                        }
1791                    }
1792                    ThrottlerReserveInput::AdvanceClock(duration) => {
1793                        let mut clock_ref = test_clock.borrow_mut();
1794                        let current_time = clock_ref.get_time_ns();
1795                        let time_events = clock_ref.advance_time(
1796                            current_time + DurationNanos::new(u64::from(duration)),
1797                            true,
1798                        );
1799
1800                        for each_event in clock_ref.match_handlers(time_events) {
1801                            drop(clock_ref);
1802                            each_event.callback.call(each_event.event);
1803                            clock_ref = test_clock.borrow_mut();
1804                        }
1805                    }
1806                }
1807
1808                assert_eq!(throttler.sent_count + throttler.qsize(), attempted + reserved);
1809            }
1810
1811            for i in 1..=100u64 {
1812                if throttler.qsize() == 0 {
1813                    break;
1814                }
1815                let advance_to = UnixNanos::default() + interval * 100 * i;
1816                let time_events = test_clock
1817                    .borrow_mut()
1818                    .advance_time(advance_to, true);
1819                let mut clock_ref = test_clock.borrow_mut();
1820                for each_event in clock_ref.match_handlers(time_events) {
1821                    drop(clock_ref);
1822                    each_event.callback.call(each_event.event);
1823                    clock_ref = test_clock.borrow_mut();
1824                }
1825            }
1826            assert_eq!(throttler.qsize(), 0);
1827        });
1828    }
1829
1830    #[rstest]
1831    fn test_throttler_process_id_returns_ustr() {
1832        // This test verifies that ThrottlerProcess::id() correctly returns Ustr
1833        // by dereferencing MStr<Endpoint> (tests *self.endpoint -> Ustr conversion)
1834        let actor_id = Ustr::from("test_throttler");
1835        let process = ThrottlerProcess::<String, fn(String)>::new(actor_id);
1836
1837        // Call id() which does *self.endpoint
1838        let handler_id: Ustr = process.id();
1839
1840        // Verify it's a valid Ustr with expected format
1841        assert!(handler_id.contains("test_throttler_process"));
1842        assert!(!handler_id.is_empty());
1843
1844        // Verify type - this wouldn't compile if id() didn't return Ustr
1845        let _type_check: Ustr = handler_id;
1846    }
1847}