Skip to main content

hopr_transport_session/balancer/
rate_limiting.rs

1use std::{
2    future::Future,
3    pin::Pin,
4    sync::{
5        Arc,
6        atomic::{AtomicU64, Ordering},
7    },
8    task::{Context, Poll},
9    time::{Duration, Instant},
10};
11
12use futures_time::task::Sleep;
13use pin_project::pin_project;
14
15/// Controller for [`RateLimitedStream`] to allow dynamic controlling of the stream's rate.
16#[derive(Clone, Debug)]
17pub struct RateController(Arc<AtomicU64>);
18
19impl Default for RateController {
20    fn default() -> Self {
21        Self(Arc::new(AtomicU64::new(0)))
22    }
23}
24
25fn rate_from_delay(delay_micros: u64) -> f64 {
26    if delay_micros > 0 {
27        1.0 / Duration::from_micros(delay_micros).as_secs_f64()
28    } else {
29        0.0
30    }
31}
32
33#[allow(unused)]
34impl RateController {
35    const MIN_DELAY: Duration = Duration::from_micros(100);
36
37    pub fn new(elements_per_unit: usize, unit: Duration) -> Self {
38        let rc = RateController::default();
39        rc.set_rate_per_unit(elements_per_unit, unit);
40        rc
41    }
42
43    /// Update the rate limit (elements per unit).
44    pub fn set_rate_per_unit(&self, elements_per_unit: usize, unit: Duration) {
45        assert!(unit > Duration::ZERO, "unit must be greater than zero");
46
47        if elements_per_unit > 0 {
48            // Calculate the next allowable time based on the rate
49            let rate_per_sec = (elements_per_unit as f64 / unit.as_secs_f64());
50
51            // Convert to duration (seconds per element)
52            let new_rate = Duration::from_secs_f64(1.0 / rate_per_sec)
53                .max(Self::MIN_DELAY)
54                .as_micros()
55                .min(u64::MAX as u128) as u64; // Clamp to u64 to avoid overflow
56
57            self.0.store(new_rate, Ordering::Relaxed);
58        } else {
59            self.0.store(0, Ordering::Relaxed);
60        }
61    }
62
63    /// Checks whether the rate is set to 0 at this controller.
64    pub fn has_zero_rate(&self) -> bool {
65        self.0.load(Ordering::Relaxed) == 0
66    }
67
68    /// Gets the delay per element (inverse rate).
69    pub fn get_delay_per_element(&self) -> Duration {
70        Duration::from_micros(self.0.load(Ordering::Relaxed))
71    }
72
73    /// Get the current rate limit per time unit.
74    pub fn get_rate_per_sec(&self) -> f64 {
75        rate_from_delay(self.0.load(Ordering::Relaxed))
76    }
77}
78
79enum StreamState {
80    Read,
81    NoRate,
82    Wait,
83}
84
85/// Longest a [`RateLimitedStream`] sleeps before re-reading its controller.
86///
87/// The wait for one item used to be computed once, when the item was read, and then slept out whole.
88/// That is invisible at the rates this adapter was written for and wrong at the rates the PIX filler
89/// uses it at: a stream idling at one packet a minute that is raised to ten a second would apply the
90/// new rate up to a minute later, which is a minute of a funded cycle's deadline spent honouring a
91/// decision that has been superseded.
92///
93/// Chunking the sleep bounds that lag by this value instead of by the period. Half a second is chosen
94/// against what the lag costs rather than against precision: it is short enough that a rate change is
95/// acted on within one sampling interval of the planner that made it, and long enough that a stream
96/// parked at the heartbeat wakes twice a second rather than continuously. The emitted *rate* is
97/// unaffected either way — the target instant is recomputed from when the item was read, so chunking
98/// changes when the controller is consulted, not when the item goes out.
99///
100/// `pub(crate)` because it is also the slack the Exit's keep-alive control classifies a SURB-level
101/// notification by: the stream releases a packet up to one chunk late, and a notification that has
102/// merely been rescheduled is still the notification. Exported rather than duplicated so the two
103/// cannot drift apart.
104pub(crate) const MAX_WAIT_CHUNK: Duration = Duration::from_millis(500);
105
106/// A stream adapter that yields elements at a controlled rate, with dynamic rate adjustment.
107///
108/// See [`RateLimitStreamExt::rate_limit_per_unit`].
109#[must_use = "streams do nothing unless polled"]
110#[pin_project]
111pub struct RateLimitedStream<S: futures::Stream> {
112    #[pin]
113    inner: S,
114    item: Option<S::Item>,
115    /// When the pending item was read, and therefore the instant the wait is measured from.
116    ///
117    /// Held separately from the sleep because the sleep is now a *chunk* of the wait rather than all
118    /// of it: each wake re-reads the controller and re-derives how much of the period is left from
119    /// this instant, so a rate raised mid-wait shortens the remaining wait instead of being applied
120    /// to the item after.
121    item_at: Option<Instant>,
122    #[pin]
123    delay: Option<Sleep>,
124    state: StreamState,
125    delay_time: Arc<AtomicU64>,
126}
127
128impl<S: futures::Stream> RateLimitedStream<S> {
129    /// Creates a stream with rate limit controllable using the given controller.
130    pub fn new_with_controller(stream: S, controller: &RateController) -> Self {
131        Self {
132            inner: stream,
133            item: None,
134            item_at: None,
135            delay: None,
136            state: if controller.0.load(Ordering::Relaxed) > 0 {
137                StreamState::Read
138            } else {
139                StreamState::NoRate
140            },
141            delay_time: controller.0.clone(),
142        }
143    }
144
145    /// Creates a stream with some initial rate limit of elements per a time unit.
146    pub fn new_with_rate_per_unit(stream: S, initial_rate_per_unit: usize, unit: Duration) -> (Self, RateController) {
147        let rc = RateController::new(initial_rate_per_unit, unit);
148        (Self::new_with_controller(stream, &rc), rc)
149    }
150}
151
152impl<S, T> futures::Stream for RateLimitedStream<S>
153where
154    S: futures::Stream<Item = T> + Unpin,
155{
156    type Item = T;
157
158    fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
159        let mut this = self.project();
160
161        loop {
162            match this.state {
163                StreamState::Read => {
164                    let yield_start = Instant::now();
165                    if let Some(item) = futures::ready!(this.inner.as_mut().poll_next(cx)) {
166                        *this.item = Some(item);
167                        *this.item_at = Some(yield_start);
168                        let delay_time = this.delay_time.load(Ordering::Relaxed);
169                        if delay_time > 0 {
170                            // The `max` keeps the original guarantee that two items are never
171                            // emitted closer together than `MIN_DELAY`; the `min` is what bounds how
172                            // stale the rate this was computed from may become.
173                            let wait = Duration::from_micros(delay_time)
174                                .saturating_sub(yield_start.elapsed())
175                                .max(RateController::MIN_DELAY)
176                                .min(MAX_WAIT_CHUNK);
177                            *this.delay = Some(futures_time::task::sleep(wait.into()));
178                            *this.state = StreamState::Wait;
179                        } else {
180                            *this.delay = Some(futures_time::task::sleep(Duration::from_millis(100).into()));
181                            *this.state = StreamState::NoRate;
182                        }
183                    } else {
184                        return Poll::Ready(None);
185                    }
186                }
187                StreamState::NoRate => {
188                    if let Some(mut delay) = this.delay.as_mut().as_pin_mut() {
189                        let _ = futures::ready!(delay.as_mut().poll(cx));
190                    }
191                    let delay_time = this.delay_time.load(Ordering::Relaxed);
192                    if delay_time > 0 {
193                        if this.item.is_some() {
194                            // The item was read while the stream was suspended, so the period it now
195                            // owes starts here rather than at whenever it happened to be read — an
196                            // item held through an hour of zero rate must not be released the instant
197                            // a rate appears.
198                            *this.item_at = Some(Instant::now());
199                            *this.delay = Some(futures_time::task::sleep(
200                                Duration::from_micros(delay_time).min(MAX_WAIT_CHUNK).into(),
201                            ));
202                            *this.state = StreamState::Wait;
203                        } else {
204                            *this.delay = Some(futures_time::task::sleep(Duration::from_micros(delay_time).into()));
205                            *this.state = StreamState::Read;
206                        }
207                    } else {
208                        *this.delay = Some(futures_time::task::sleep(Duration::from_millis(100).into()));
209                        *this.state = StreamState::NoRate;
210                    }
211                }
212                StreamState::Wait => {
213                    if let Some(mut delay) = this.delay.as_mut().as_pin_mut() {
214                        let _ = futures::ready!(delay.as_mut().poll(cx));
215                    }
216
217                    let delay_time = this.delay_time.load(Ordering::Relaxed);
218                    if delay_time == 0 {
219                        // The rate was withdrawn while this item waited. Park it rather than emitting
220                        // it: a zero rate means "emit nothing until told otherwise", and an item
221                        // already in hand is not an exception to that.
222                        *this.delay = Some(futures_time::task::sleep(Duration::from_millis(100).into()));
223                        *this.state = StreamState::NoRate;
224                        continue;
225                    }
226
227                    // Re-derived from the read instant against the *current* rate, so a rate raised
228                    // during the wait shortens what is left of it and a rate lowered extends it.
229                    let elapsed = this.item_at.map(|at| at.elapsed()).unwrap_or_default();
230                    let remaining = Duration::from_micros(delay_time).saturating_sub(elapsed);
231                    if remaining.is_zero() {
232                        *this.item_at = None;
233                        *this.state = StreamState::Read;
234                        return Poll::Ready(this.item.take());
235                    }
236
237                    *this.delay = Some(futures_time::task::sleep(remaining.min(MAX_WAIT_CHUNK).into()));
238                }
239            }
240        }
241    }
242}
243
244/// Extension trait to add rate limiting to any stream
245pub trait RateLimitStreamExt: futures::Stream + Sized {
246    /// Creates a rate-limited stream that yields elements at the given rate.
247    ///
248    /// The rate can be controlled dynamically during the lifetime of the stream by using
249    /// the returned [`RateController`].
250    ///
251    /// If `elements_per_unit` is 0, the stream will not yield until the limit is changed
252    /// using the [`RateController`] to a non-zero value.
253    fn rate_limit_per_unit(
254        self,
255        elements_per_unit: usize,
256        unit: Duration,
257    ) -> (RateLimitedStream<Self>, RateController) {
258        RateLimitedStream::new_with_rate_per_unit(self, elements_per_unit, unit)
259    }
260
261    /// Creates a rate-limited stream that yields elements at the given rate.
262    ///
263    /// The rate can be controlled dynamically during the lifetime of the stream by using
264    /// the given [`RateController`].
265    ///
266    /// If the `controller` has [zero rate](RateController::has_zero_rate),
267    /// the stream will not yield until the limit is
268    /// changed using the [`RateController`] to a non-zero value.
269    fn rate_limit_with_controller(self, controller: &RateController) -> RateLimitedStream<Self> {
270        RateLimitedStream::new_with_controller(self, controller)
271    }
272}
273
274impl<S: futures::Stream + Sized> RateLimitStreamExt for S {}
275
276/// A sink adapter that allows ingesting items at a controlled rate, with dynamic rate adjustment.
277///
278/// If the underlying Sink is cloneable, this object will be cloneable too, each clone having
279/// the same rate-limit. Therefore, the total rate-limit is multiple of the number of clones
280/// of this sink.
281///
282/// See [`RateLimitSinkExt::rate_limit_per_unit`].
283#[must_use = "sinks do nothing unless polled"]
284#[pin_project]
285pub struct RateLimitedSink<S> {
286    #[pin]
287    inner: S,
288    delay_micros: Arc<AtomicU64>,
289    tokens: u64,
290    last_check: Option<Instant>,
291    #[pin]
292    sleep: Option<Sleep>,
293    state: SinkState,
294}
295
296enum SinkState {
297    Ready,
298    Waiting,
299}
300
301impl<S> RateLimitedSink<S> {
302    /// Creates a sink with ingestion rate controllable using the given controller.
303    pub fn new_with_controller(inner: S, controller: &RateController) -> Self {
304        Self {
305            inner,
306            delay_micros: controller.0.clone(),
307            tokens: 0,
308            last_check: None,
309            sleep: None,
310            state: SinkState::Ready,
311        }
312    }
313
314    /// Creates a sink with some initial rate limit of elements per a time unit.
315    pub fn new_with_rate_per_unit(inner: S, initial_rate_per_unit: usize, unit: Duration) -> (Self, RateController) {
316        let rc = RateController::new(initial_rate_per_unit, unit);
317        (Self::new_with_controller(inner, &rc), rc)
318    }
319}
320
321impl<S, Item> futures::Sink<Item> for RateLimitedSink<S>
322where
323    S: futures::Sink<Item> + Unpin,
324{
325    type Error = S::Error;
326
327    fn poll_ready(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), S::Error>> {
328        let mut this = self.project();
329
330        loop {
331            let current_delay = this.delay_micros.load(Ordering::Relaxed);
332            let current_rate_limit = rate_from_delay(current_delay);
333
334            if let Some(last_check) = this.last_check.as_mut() {
335                *this.tokens += (current_rate_limit * last_check.elapsed().as_secs_f64()).round() as u64;
336                *last_check = Instant::now();
337            } else {
338                // This happens only on the first poll_ready
339                *this.last_check = Some(Instant::now());
340            }
341
342            match this.state {
343                SinkState::Ready => {
344                    if *this.tokens > 0 {
345                        futures::ready!(this.inner.as_mut().poll_ready(cx))?;
346
347                        tracing::trace!(tokens = *this.tokens, "tokens left");
348                        return Poll::Ready(Ok(()));
349                    } else {
350                        tracing::trace!("no tokens left");
351                        *this.state = SinkState::Waiting;
352                    }
353                }
354                SinkState::Waiting => {
355                    if let Some(sleep) = this.sleep.as_mut().as_pin_mut() {
356                        futures::ready!(sleep.poll(cx));
357                        this.sleep.set(None);
358
359                        tracing::trace!("waiting done");
360                        *this.state = SinkState::Ready;
361                    } else if current_delay > 0 {
362                        // Sleep the minimum amount of time to replenish at least one token
363                        *this.sleep = Some(futures_time::task::sleep(futures_time::time::Duration::from_micros(
364                            current_delay,
365                        )));
366                    } else {
367                        // Sleep for some fixed duration if the rate is 0
368                        *this.sleep = Some(futures_time::task::sleep(futures_time::time::Duration::from_millis(50)));
369                    }
370                }
371            }
372        }
373    }
374
375    fn start_send(self: Pin<&mut Self>, item: Item) -> Result<(), S::Error> {
376        let this = self.project();
377        if *this.tokens > 0 {
378            *this.tokens -= 1;
379            tracing::trace!("token consumed");
380            this.inner.start_send(item)
381        } else {
382            panic!("start_send called without poll_ready");
383        }
384    }
385
386    fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), S::Error>> {
387        self.project().inner.poll_flush(cx)
388    }
389
390    fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), S::Error>> {
391        self.project().inner.poll_close(cx)
392    }
393}
394
395impl<S: Clone> Clone for RateLimitedSink<S> {
396    fn clone(&self) -> Self {
397        Self {
398            inner: self.inner.clone(),
399            delay_micros: self.delay_micros.clone(),
400            tokens: 0,
401            last_check: None,
402            sleep: None,
403            state: SinkState::Ready,
404        }
405    }
406}
407
408/// Extension trait to add rate limiting to any sink.
409pub trait RateLimitSinkExt<T>: futures::Sink<T> + Sized {
410    /// Creates a rate-limited sink that allows ingesting items at the given rate.
411    ///
412    /// The rate can be controlled dynamically during the lifetime of the sink by using
413    /// the returned [`RateController`].
414    ///
415    /// If `elements_per_unit` is 0, the sink will not ingest items until the limit is changed
416    /// using the [`RateController`] to a non-zero value.
417    fn rate_limit_per_unit(self, elements_per_unit: usize, unit: Duration) -> (RateLimitedSink<Self>, RateController) {
418        RateLimitedSink::new_with_rate_per_unit(self, elements_per_unit, unit)
419    }
420
421    /// Creates a rate-limited sink that allows ingesting items at the given rate.
422    ///
423    /// The rate can be controlled dynamically during the lifetime of the sink by using
424    /// the given [`RateController`].
425    ///
426    /// If the `controller` has [zero rate](RateController::has_zero_rate),
427    /// the sink will not ingest items until the limit is
428    /// changed using the [`RateController`] to a non-zero value.
429    fn rate_limit_with_controller(self, controller: &RateController) -> RateLimitedSink<Self> {
430        RateLimitedSink::new_with_controller(self, controller)
431    }
432}
433
434impl<T, S: futures::Sink<T> + Sized> RateLimitSinkExt<T> for S {}
435
436#[cfg(test)]
437mod tests {
438    use std::time::{Duration, Instant};
439
440    use futures::{
441        SinkExt, pin_mut,
442        stream::{self, StreamExt},
443    };
444    use futures_time::future::FutureExt;
445
446    use super::*;
447
448    #[test]
449    fn test_rate_controller_set_rate_per_unit() {
450        let rc = RateController(Arc::new(AtomicU64::new(0)));
451        rc.set_rate_per_unit(2500, 2 * Duration::from_secs(1));
452        assert_eq!(rc.get_rate_per_sec(), 1250.0);
453    }
454
455    #[tokio::test]
456    async fn test_rate_limited_stream_respects_rate() {
457        // Create a stream with 5 elements
458        let stream = stream::iter(1..=5);
459
460        // Set a rate of 10 elements per second (100ms per element)
461        let (rate_limited, controller) = stream.rate_limit_per_unit(10, Duration::from_secs(1));
462
463        assert_eq!(controller.get_rate_per_sec(), 10.0);
464
465        let start = Instant::now();
466
467        // Collect all elements from the stream
468        let items: Vec<i32> = rate_limited.collect().await;
469
470        let elapsed = start.elapsed();
471
472        // Verify all elements were yielded
473        assert_eq!(items, vec![1, 2, 3, 4, 5]);
474
475        // Verify the rate limiting worked
476        // With 5 elements at 10 per second; we expect ~400ms (4 delays of 100ms)
477        // We use 300ms as a lower bound to account for processing time
478        assert!(
479            elapsed >= Duration::from_millis(300),
480            "Stream completed too quickly: {elapsed:?}"
481        );
482
483        // We use 600ms as an upper bound to allow for some overhead
484        assert!(
485            elapsed <= Duration::from_millis(600),
486            "Stream completed too slowly: {elapsed:?}"
487        );
488    }
489
490    #[tokio::test]
491    async fn test_rate_limited_first_item_should_be_delayed() {
492        // Create a stream with 3 elements
493        let stream = stream::iter(1..=1);
494
495        // Set a rate of 1 element per 100ms
496        let (rate_limited, _) = stream.rate_limit_per_unit(1, Duration::from_millis(100));
497
498        pin_mut!(rate_limited);
499
500        let start = Instant::now();
501        assert_eq!(Some(1), rate_limited.next().await);
502        assert!(start.elapsed() >= Duration::from_millis(100));
503    }
504
505    #[tokio::test]
506    async fn test_rate_limited_stream_empty() {
507        // Create an empty stream
508        let stream = stream::iter::<Vec<i32>>(vec![]);
509
510        // Apply rate limiting
511        let (mut rate_limited, _) = stream.rate_limit_per_unit(10, Duration::from_secs(1));
512
513        // Verify we get None right away
514        assert_eq!(rate_limited.next().await, None);
515    }
516
517    #[tokio::test]
518    async fn test_rate_limited_stream_zero_rate() -> anyhow::Result<()> {
519        // Create a stream with 3 elements
520        let stream = stream::iter(1..=3);
521
522        // Set a rate of 0 elements per second (= will not yield)
523        let (mut rate_limited, _) = stream.rate_limit_per_unit(0, Duration::from_millis(50));
524
525        assert!(
526            rate_limited
527                .next()
528                .timeout(futures_time::time::Duration::from_millis(100))
529                .await
530                .is_err(),
531            "zero rate should not yield anything"
532        );
533
534        Ok(())
535    }
536
537    #[tokio::test]
538    async fn test_rate_limited_stream_should_pause_on_zero_rate() -> anyhow::Result<()> {
539        // Create a stream with 3 elements
540        let stream = stream::iter(1..=3);
541
542        // Set a rate of 1 element per 100ms
543        let (mut rate_limited, controller) = stream.rate_limit_per_unit(1, Duration::from_millis(100));
544
545        let start = Instant::now();
546        assert_eq!(Some(1), rate_limited.next().await);
547        let elapsed = start.elapsed();
548        assert!(
549            elapsed >= Duration::from_millis(100),
550            "first element too fast {elapsed:?}"
551        );
552
553        let start = Instant::now();
554        assert_eq!(Some(2), rate_limited.next().await);
555        let elapsed = start.elapsed();
556        assert!(
557            elapsed >= Duration::from_millis(100),
558            "first element too fast {elapsed:?}"
559        );
560
561        controller.set_rate_per_unit(0, Duration::from_millis(100));
562
563        assert!(
564            rate_limited
565                .next()
566                .timeout(futures_time::time::Duration::from_millis(200))
567                .await
568                .is_err(),
569            "zero rate should not yield anything"
570        );
571
572        Ok(())
573    }
574
575    #[tokio::test]
576    async fn test_rate_limited_stream_zero_rate_should_restart_when_increased() -> anyhow::Result<()> {
577        // Create a stream with 3 elements
578        let stream = stream::iter(1..=3);
579
580        // Set a rate of 0 elements per second (= will not yield)
581        let (mut rate_limited, controller) = stream.rate_limit_per_unit(0, Duration::from_secs(1));
582
583        assert!(
584            rate_limited
585                .next()
586                .timeout(futures_time::time::Duration::from_millis(100))
587                .await
588                .is_err(),
589            "zero rate should not yield anything"
590        );
591
592        controller.set_rate_per_unit(1, Duration::from_millis(100));
593
594        let start = Instant::now();
595        let all_items = rate_limited.collect::<Vec<_>>().await;
596        let all_items_elapsed = start.elapsed();
597
598        assert_eq!(all_items, vec![1, 2, 3]);
599        assert!(
600            all_items_elapsed >= Duration::from_millis(300),
601            "all items should have been yielded in at least 300ms instead {all_items_elapsed:?}"
602        );
603
604        Ok(())
605    }
606
607    #[tokio::test]
608    async fn test_rate_changing_during_stream() {
609        // Create a stream with 6 elements
610        let stream = stream::iter(1..=6);
611
612        // Start with 5 elements per second (200ms per element)
613        let (mut rate_limited, controller) = stream.rate_limit_per_unit(5, Duration::from_secs(1));
614
615        // Consume first 3 elements
616        let start = Instant::now();
617        for i in 1..=3 {
618            assert_eq!(Some(i), rate_limited.next().await);
619        }
620
621        // Measure time for the first 3 elements
622        let first_half_elapsed = start.elapsed();
623
624        // Change rate to 2 elements per second (500ms per element)
625        controller.set_rate_per_unit(2, Duration::from_secs(1));
626
627        // Consume last 3 elements
628        for i in 4..=6 {
629            assert_eq!(Some(i), rate_limited.next().await);
630        }
631
632        // Measure total time
633        let total_elapsed = start.elapsed();
634        let second_half_elapsed = total_elapsed - first_half_elapsed;
635
636        // The first 3 elements at 5 per second should take ~600ms (200 ms each)
637        assert!(
638            first_half_elapsed >= Duration::from_millis(600),
639            "First half too fast: {first_half_elapsed:?}"
640        );
641        assert!(
642            first_half_elapsed <= Duration::from_millis(700),
643            "First half too slow: {first_half_elapsed:?}"
644        );
645
646        // The last 3 elements at 2 per second should take ~1500ms (500 ms each)
647        assert!(
648            second_half_elapsed >= Duration::from_millis(1500),
649            "Second half too fast: {second_half_elapsed:?}"
650        );
651        assert!(
652            second_half_elapsed <= Duration::from_millis(1600),
653            "Second half too slow: {second_half_elapsed:?}"
654        );
655    }
656
657    #[tokio::test]
658    async fn test_very_high_rate() {
659        // Create a stream with 100 elements
660        let stream = stream::iter(1..=100);
661
662        // Set a very high rate (1000 per second)
663        let (rate_limited, _) = stream.rate_limit_per_unit(1000, Duration::from_secs(1));
664
665        let start = Instant::now();
666
667        // Collect all elements
668        let items: Vec<i32> = rate_limited.collect().await;
669
670        let elapsed = start.elapsed();
671
672        // Verify all elements were yielded
673        assert_eq!(items.len(), 100);
674        assert_eq!(items.first(), Some(&1));
675        assert_eq!(items.last(), Some(&100));
676
677        // Even at a high rate, processing 100 elements should take some time
678        // but less than 500 ms (theoretical time would be ~99ms, but CI/nightly
679        // runners can have significant scheduling jitter).
680        assert!(
681            elapsed >= Duration::from_millis(90),
682            "Very high rate stream finished too quickly: {elapsed:?}"
683        );
684
685        assert!(
686            elapsed < Duration::from_millis(500),
687            "Very high rate stream took too long: {elapsed:?}"
688        );
689    }
690
691    #[tokio::test]
692    async fn test_concurrent_rate_change() {
693        use futures::future::join;
694
695        // Create a stream with 10 elements
696        let stream = stream::iter(1..=10);
697
698        // Start with 2 elements per second
699        let (mut rate_limited, controller) = stream.rate_limit_per_unit(2, Duration::from_secs(1));
700
701        // Set up a task to process the stream
702        let stream_task = async {
703            let mut count = 0;
704            let mut items = Vec::new();
705
706            while let Some(item) = rate_limited.next().await {
707                items.push(item);
708                count += 1;
709
710                // After 3 elements, wait briefly to allow rate change to take effect
711                if count == 3 {
712                    futures_time::task::sleep(Duration::from_millis(50).into()).await;
713                }
714            }
715
716            items
717        };
718
719        // Set up a task to change the rate after a delay
720        let rate_change_task = async move {
721            // Wait a bit for the stream to start processing
722            futures_time::task::sleep(Duration::from_millis(100).into()).await;
723
724            // Change the rate to 20 per second
725            controller.set_rate_per_unit(20, Duration::from_secs(1));
726
727            // Return the new rate
728            20
729        };
730
731        // Run both tasks concurrently
732        let (items, new_rate) = join(stream_task, rate_change_task).await;
733
734        // Verify results
735        assert_eq!(items.len(), 10, "Should have received all 10 items");
736        assert_eq!(new_rate, 20, "Rate should have been changed to 20");
737    }
738
739    #[test_log::test(tokio::test)]
740    async fn rate_limited_sink_should_respect_rate() -> anyhow::Result<()> {
741        let (tx, rx) = futures::channel::mpsc::unbounded::<i32>();
742        let (tx, _) = tx.rate_limit_per_unit(5, Duration::from_millis(100));
743
744        let input = (0..10).collect::<Vec<_>>();
745
746        let start = Instant::now();
747        pin_mut!(tx);
748        tx.send_all(&mut futures::stream::iter(input.clone()).map(Ok))
749            .timeout(futures_time::time::Duration::from_millis(500))
750            .await??;
751
752        let elapsed = start.elapsed();
753        assert!(
754            elapsed >= Duration::from_millis(200),
755            "sending took too little {elapsed:?}"
756        );
757
758        tx.close().await?;
759
760        let collected = rx.collect::<Vec<_>>().await;
761        assert_eq!(input, collected);
762
763        Ok(())
764    }
765
766    #[test_log::test(tokio::test)]
767    async fn rate_limited_sink_should_replenish_when_idle() -> anyhow::Result<()> {
768        let (tx, rx) = futures::channel::mpsc::unbounded::<i32>();
769        let (tx, _) = tx.rate_limit_per_unit(5, Duration::from_millis(100));
770
771        pin_mut!(tx);
772
773        let input = (0..5).collect::<Vec<_>>();
774
775        let start = Instant::now();
776        tx.send_all(&mut futures::stream::iter(input.clone()).map(Ok))
777            .timeout(futures_time::time::Duration::from_millis(500))
778            .await??;
779
780        let elapsed = start.elapsed();
781        assert!(
782            elapsed < Duration::from_millis(120),
783            "sending took too much {elapsed:?}"
784        );
785
786        tokio::time::sleep(Duration::from_millis(100)).await;
787
788        let start = Instant::now();
789        tx.send_all(&mut futures::stream::iter(input.clone()).map(Ok))
790            .timeout(futures_time::time::Duration::from_millis(500))
791            .await??;
792
793        let elapsed = start.elapsed();
794        assert!(
795            elapsed < Duration::from_millis(120),
796            "sending took too much {elapsed:?}"
797        );
798
799        tx.close().await?;
800
801        let collected = rx.collect::<Vec<_>>().await;
802        assert_eq!(input.into_iter().cycle().take(10).collect::<Vec<_>>(), collected);
803
804        Ok(())
805    }
806
807    #[test_log::test(tokio::test)]
808    async fn rate_limited_sink_should_not_send_when_zero_rate() -> anyhow::Result<()> {
809        let (tx, _) = futures::channel::mpsc::unbounded::<i32>();
810        let (tx, _) = tx.rate_limit_per_unit(0, Duration::from_millis(100));
811
812        pin_mut!(tx);
813
814        assert!(
815            tx.send(1i32)
816                .timeout(futures_time::time::Duration::from_millis(100))
817                .await
818                .is_err()
819        );
820        Ok(())
821    }
822
823    #[test_log::test(tokio::test)]
824    async fn rate_limited_sink_should_recover_after_rate_is_increased() -> anyhow::Result<()> {
825        let (tx, rx) = futures::channel::mpsc::unbounded::<i32>();
826        let (tx, ctl) = tx.rate_limit_per_unit(0, Duration::from_millis(100));
827
828        pin_mut!(tx);
829
830        assert!(
831            tx.send(1i32)
832                .timeout(futures_time::time::Duration::from_millis(100))
833                .await
834                .is_err()
835        );
836
837        ctl.set_rate_per_unit(10, Duration::from_millis(10));
838
839        tx.send(2i32)
840            .timeout(futures_time::time::Duration::from_millis(100))
841            .await??;
842
843        pin_mut!(rx);
844        assert_eq!(
845            Some(2),
846            rx.next()
847                .timeout(futures_time::time::Duration::from_millis(100))
848                .await?
849        );
850
851        Ok(())
852    }
853
854    /// A rate raised mid-wait must take effect within a wait chunk, not at the end of the old period.
855    ///
856    /// This is what the PIX filler needs and what the adapter did not do: it computed the wait once,
857    /// when the item was read, and slept it out whole. A stream parked at one packet a minute — the
858    /// fill heartbeat — that is raised to ten a second would therefore have applied the new rate up
859    /// to a minute later, which on a funded cycle is a minute of its deadline spent honouring a
860    /// decision that had already been superseded.
861    ///
862    /// The bound asserted is [`MAX_WAIT_CHUNK`] plus scheduling slack, and deliberately far below the
863    /// 60 s period it replaces: a regression that restores the old behaviour cannot pass it by being
864    /// unlucky, only by being wrong.
865    #[tokio::test]
866    async fn a_rate_raised_during_a_long_wait_is_applied_within_one_chunk() {
867        let stream = stream::iter(1..=2);
868        let (mut rate_limited, controller) = stream.rate_limit_per_unit(1, Duration::from_secs(60));
869
870        // One poll is enough to have the item read and the minute-long wait armed. Dropping the
871        // timed-out future leaves that state on the stream, which is exactly the situation the
872        // planner raises a rate into.
873        assert!(
874            tokio::time::timeout(Duration::from_millis(200), rate_limited.next())
875                .await
876                .is_err(),
877            "the fixture needs an item parked on a long wait"
878        );
879
880        let raised_at = Instant::now();
881        controller.set_rate_per_unit(10, Duration::from_secs(1));
882
883        let first = tokio::time::timeout(Duration::from_secs(5), rate_limited.next())
884            .await
885            .expect("the stream must re-arm rather than sleeping out the minute it started with");
886        assert_eq!(Some(1), first);
887        assert!(
888            raised_at.elapsed() < MAX_WAIT_CHUNK + Duration::from_millis(500),
889            "the raised rate took {:?} to apply, against a chunk of {MAX_WAIT_CHUNK:?}",
890            raised_at.elapsed()
891        );
892    }
893
894    /// The converse: a rate withdrawn mid-wait parks the item instead of releasing it.
895    ///
896    /// Zero means "emit nothing until told otherwise", and an item already read is not an exception
897    /// — it is precisely the packet a Session that has just been closed must not send.
898    #[tokio::test]
899    async fn a_rate_withdrawn_during_a_wait_parks_the_item() {
900        let stream = stream::iter(1..=2);
901        let (mut rate_limited, controller) = stream.rate_limit_per_unit(2, Duration::from_secs(1));
902
903        assert_eq!(Some(1), rate_limited.next().await);
904        controller.set_rate_per_unit(0, Duration::from_secs(1));
905
906        assert!(
907            tokio::time::timeout(Duration::from_millis(1500), rate_limited.next())
908                .await
909                .is_err(),
910            "an item waiting when the rate was withdrawn must not be emitted"
911        );
912
913        controller.set_rate_per_unit(100, Duration::from_secs(1));
914        assert_eq!(
915            Some(2),
916            tokio::time::timeout(Duration::from_secs(2), rate_limited.next())
917                .await
918                .expect("the parked item must be released once a rate returns")
919        );
920    }
921
922    /// The same rule, reached from inside a wait rather than from a fresh read.
923    ///
924    /// Its sibling above withdraws the rate while the stream is in `Read`, so the item it parks is
925    /// one that had not been read yet and the zero is noticed on the way *out* of `Read`. The branch
926    /// this crate added is the other one: an item already in hand, its wait already armed, when the
927    /// rate goes to zero. That is exactly the shape of a Session closed mid-period — the supervisor's
928    /// zero arrives while the filler is sleeping out an interval — and releasing that packet sends it
929    /// return-routed to a pseudonym whose SURBs are being torn down.
930    ///
931    /// The minute-long period is what forces the stream through `Wait`: one poll arms it, and nothing
932    /// but the chunked re-read can then observe the withdrawal.
933    #[tokio::test]
934    async fn a_rate_withdrawn_inside_a_long_wait_parks_the_item() {
935        let stream = stream::iter(1..=2);
936        let (mut rate_limited, controller) = stream.rate_limit_per_unit(1, Duration::from_secs(60));
937
938        // As in `a_rate_raised_during_a_long_wait_is_applied_within_one_chunk`: one poll reads the
939        // item and arms the wait, and dropping the timed-out future leaves that state on the stream.
940        assert!(
941            tokio::time::timeout(Duration::from_millis(200), rate_limited.next())
942                .await
943                .is_err(),
944            "the fixture needs an item parked inside a long wait"
945        );
946
947        controller.set_rate_per_unit(0, Duration::from_secs(1));
948        assert!(
949            tokio::time::timeout(Duration::from_millis(1500), rate_limited.next())
950                .await
951                .is_err(),
952            "an item waiting when the rate was withdrawn must not be emitted"
953        );
954
955        controller.set_rate_per_unit(100, Duration::from_secs(1));
956        assert_eq!(
957            Some(1),
958            tokio::time::timeout(Duration::from_secs(2), rate_limited.next())
959                .await
960                .expect("the parked item must be released once a rate returns")
961        );
962    }
963}