Skip to main content

tor_async_utils/global_rate_limit/
conn.rs

1//! A rate limited async duplex connection.
2//!
3//! An [`AsyncRead`] and [`AsyncWrite`] wrapper that rate limits both directions of a
4//! single bidirectional byte stream such as a TCP or TLS connection, by acquiring
5//! bandwidth from a [`super::BandwidthAcquirer`] given for each diection (read and
6//! write). One byte is one token.
7
8use futures::{AsyncRead, AsyncWrite};
9use pin_project::pin_project;
10use std::borrow::Cow;
11use std::io::Error;
12use std::num::NonZero;
13use std::pin::Pin;
14use std::task::{Context, Poll};
15
16use tor_rtcompat::{CertifiedConn, StreamOps};
17
18use super::DirectionState;
19use crate::bw_pool::BandwidthAcquirer;
20
21/// An [`AsyncRead`] and [`AsyncWrite`] wrapper that rate limits each direction of a single
22/// bidirectional byte stream.
23///
24/// Every byte read or written costs one token per direction pool.
25///
26/// A connection built with [`Self::unlimited`] is not rate limited and forwards
27/// everything to the underlying stream.
28#[derive(Debug)]
29#[pin_project]
30pub struct GlobalRateLimitedConn<S> {
31    /// The underlying stream.
32    #[pin]
33    inner: S,
34    /// Rate-limiting state for the read direction. `None` means unlimited.
35    read_state: Option<DirectionState>,
36    /// Rate-limiting state for the write direction. `None` means unlimited.
37    write_state: Option<DirectionState>,
38}
39
40impl<S> GlobalRateLimitedConn<S> {
41    /// Constructor.
42    ///
43    /// We recommend that the `read_acquirer` and `write_acquirer` comme from different
44    /// bandwidth pools so one direction doesn't starve the other side. In a
45    /// bidirectional setup, this could be equivalent to unidirectionnal.
46    ///
47    /// Each IO requests at most `max_chunk` tokens in either direction.
48    pub fn new(
49        inner: S,
50        read_acquirer: BandwidthAcquirer,
51        write_acquirer: BandwidthAcquirer,
52        max_chunk: NonZero<usize>,
53    ) -> Self {
54        Self {
55            inner,
56            read_state: Some(DirectionState::new(read_acquirer, max_chunk)),
57            write_state: Some(DirectionState::new(write_acquirer, max_chunk)),
58        }
59    }
60
61    /// Constructor of a connection that is not rate limited in either direction.
62    pub fn unlimited(inner: S) -> Self {
63        Self {
64            inner,
65            read_state: None,
66            write_state: None,
67        }
68    }
69}
70
71impl<S> AsyncRead for GlobalRateLimitedConn<S>
72where
73    S: AsyncRead,
74{
75    fn poll_read(
76        self: Pin<&mut Self>,
77        cx: &mut Context<'_>,
78        buf: &mut [u8],
79    ) -> Poll<Result<usize, Error>> {
80        let this = self.project();
81        match this.read_state {
82            Some(state) => super::reader::poll_read_limited(this.inner, state, cx, buf),
83            None => this.inner.poll_read(cx, buf),
84        }
85    }
86}
87
88impl<S> AsyncWrite for GlobalRateLimitedConn<S>
89where
90    S: AsyncWrite,
91{
92    fn poll_write(
93        self: Pin<&mut Self>,
94        cx: &mut Context<'_>,
95        buf: &[u8],
96    ) -> Poll<Result<usize, Error>> {
97        let this = self.project();
98        match this.write_state {
99            Some(state) => super::writer::poll_write_limited(this.inner, state, cx, buf),
100            None => this.inner.poll_write(cx, buf),
101        }
102    }
103
104    fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Error>> {
105        self.project().inner.poll_flush(cx)
106    }
107
108    fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Error>> {
109        self.project().inner.poll_close(cx)
110    }
111}
112
113/// Implement [`StreamOps`] and forward it to the inner stream.
114///
115/// Every operation is untouched, rate-limiting is not applied here.
116impl<S> StreamOps for GlobalRateLimitedConn<S>
117where
118    S: StreamOps,
119{
120    fn set_tcp_notsent_lowat(&self, notsent_lowat: u32) -> std::io::Result<()> {
121        self.inner.set_tcp_notsent_lowat(notsent_lowat)
122    }
123
124    fn new_handle(&self) -> Box<dyn StreamOps + Send + Unpin> {
125        self.inner.new_handle()
126    }
127}
128
129/// Implement [`CertifiedConn`] and forward it to the inner stream.
130///
131/// This allows wrapping a TLS stream.
132impl<S> CertifiedConn for GlobalRateLimitedConn<S>
133where
134    S: CertifiedConn,
135{
136    fn export_keying_material(
137        &self,
138        len: usize,
139        label: &[u8],
140        context: Option<&[u8]>,
141    ) -> std::io::Result<Vec<u8>> {
142        self.inner.export_keying_material(len, label, context)
143    }
144
145    fn peer_certificate(&self) -> std::io::Result<Option<Cow<'_, [u8]>>> {
146        self.inner.peer_certificate()
147    }
148
149    fn own_certificate(&self) -> std::io::Result<Option<Cow<'_, [u8]>>> {
150        self.inner.own_certificate()
151    }
152}
153
154#[cfg(test)]
155mod test {
156    // @@ begin test lint list maintained by maint/add_warning @@
157    #![allow(clippy::bool_assert_comparison)]
158    #![allow(clippy::clone_on_copy)]
159    #![allow(clippy::dbg_macro)]
160    #![allow(clippy::mixed_attributes_style)]
161    #![allow(clippy::print_stderr)]
162    #![allow(clippy::print_stdout)]
163    #![allow(clippy::single_char_pattern)]
164    #![allow(clippy::unwrap_used)]
165    #![allow(clippy::unchecked_time_subtraction)]
166    #![allow(clippy::useless_vec)]
167    #![allow(clippy::needless_pass_by_value)]
168    #![allow(clippy::string_slice)] // See arti#2571
169    //! <!-- @@ end test lint list maintained by maint/add_warning @@ -->
170
171    use super::*;
172
173    use futures::{AsyncReadExt as _, AsyncWriteExt as _, FutureExt as _, io::Cursor};
174
175    use crate::bw_pool::BandwidthPool;
176
177    /// Max chunk used by the tests that don't exercise the cap itself.
178    const MAX_CHUNK: NonZero<usize> = NonZero::new(1024).unwrap();
179
180    /// Minimum partial grant used by the tests.
181    const MIN_GRANT: u64 = 10;
182
183    /// Build a conn over a [`Cursor`] with a 100 bytes length vector.
184    fn new_conn(
185        read_pool: &BandwidthPool,
186        write_pool: &BandwidthPool,
187    ) -> GlobalRateLimitedConn<Cursor<Vec<u8>>> {
188        GlobalRateLimitedConn::new(
189            Cursor::new(vec![1_u8; 100]),
190            read_pool.new_acquirer(),
191            write_pool.new_acquirer(),
192            MAX_CHUNK,
193        )
194    }
195
196    #[test]
197    fn basic_conn() {
198        let (read_pool, _rr) = BandwidthPool::new(NonZero::new(100).unwrap(), MIN_GRANT);
199        let (write_pool, _wr) = BandwidthPool::new(NonZero::new(100).unwrap(), MIN_GRANT);
200        let mut conn = new_conn(&read_pool, &write_pool);
201
202        // A read of 30 only spends from the read pool.
203        let mut buf = [0; 30];
204        assert_eq!(conn.read(&mut buf).now_or_never().unwrap().unwrap(), 30);
205        assert_eq!(read_pool.available(), 70);
206        assert_eq!(write_pool.available(), 100);
207
208        // A write of 40 only spends from the write pool.
209        assert_eq!(conn.write(&[1; 40]).now_or_never().unwrap().unwrap(), 40);
210        assert_eq!(read_pool.available(), 70);
211        assert_eq!(write_pool.available(), 60);
212    }
213
214    #[test]
215    fn write_no_read_block() {
216        let (read_pool, _rr) = BandwidthPool::new(NonZero::new(50).unwrap(), MIN_GRANT);
217        let (write_pool, _wr) = BandwidthPool::new(NonZero::new(50).unwrap(), MIN_GRANT);
218        let mut conn = new_conn(&read_pool, &write_pool);
219
220        // Drain the write pool.
221        assert_eq!(conn.write(&[1; 50]).now_or_never().unwrap().unwrap(), 50);
222
223        // A further write is Pending until a refill...
224        let mut write = conn.write(&[2; 50]);
225        assert!((&mut write).now_or_never().is_none());
226
227        // But a read is not blocked.
228        let mut buf = [0; 30];
229        assert_eq!(conn.read(&mut buf).now_or_never().unwrap().unwrap(), 30);
230        assert_eq!(read_pool.available(), 20);
231    }
232}