Skip to main content

matier_core/
body.rs

1//! Request body.
2
3use std::fmt;
4use std::pin::Pin;
5use std::sync::{Arc, Mutex};
6use std::task::{Context, Poll};
7
8use bytesbuf::BytesView;
9use http_body::{Frame, SizeHint};
10use tokio::sync::mpsc;
11
12use crate::error::{Error, ErrorKind, Recovery, Result};
13
14/// Request body.
15#[derive(Default)]
16#[allow(
17    clippy::large_enum_variant,
18    reason = "BytesView is ~272 bytes (8 inline spans); boxing would cost an allocation per request"
19)]
20pub enum Body {
21    #[default]
22    Empty,
23    /// Fast path: cloneable (for retries), sent as iovecs, zero-copy.
24    Full(BytesView),
25    /// From [`Body::channel`].
26    Stream(BodyStream),
27}
28
29impl fmt::Debug for Body {
30    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
31        match self {
32            Self::Empty => f.write_str("Body::Empty"),
33            Self::Full(v) => write!(f, "Body::Full({} bytes)", v.len()),
34            Self::Stream(_) => f.write_str("Body::Stream"),
35        }
36    }
37}
38
39impl Body {
40    #[must_use]
41    pub const fn empty() -> Self {
42        Self::Empty
43    }
44
45    pub fn full(data: impl Into<BytesView>) -> Self {
46        let v = data.into();
47        if v.is_empty() {
48            Self::Empty
49        } else {
50            Self::Full(v)
51        }
52    }
53
54    #[must_use]
55    pub fn from_static(data: &'static [u8]) -> Self {
56        Self::full(crate::buf::from_static(data))
57    }
58
59    /// Bounded single-producer single-consumer body. `buffer` is the number of chunks that may be queued
60    /// before `BodySender::send` waits (backpressure). Clamped to at least 1.
61    // v0: tokio's mpsc. A purpose-built SPSC (no multi-producer machinery, byte-credit accounting) comes later.
62    #[must_use]
63    pub fn channel(buffer: usize) -> (BodySender, Self) {
64        let (tx, rx) = mpsc::channel(buffer.max(1));
65        let abort = Arc::new(Mutex::new(None));
66        (
67            BodySender {
68                tx,
69                abort: Arc::clone(&abort),
70                finished: false,
71            },
72            Self::Stream(BodyStream {
73                rx,
74                abort,
75                done: false,
76            }),
77        )
78    }
79
80    /// Exact length when known (`Some` for Empty/Full, `None` for streams).
81    #[must_use]
82    pub fn size_hint(&self) -> Option<u64> {
83        match self {
84            Self::Empty => Some(0),
85            Self::Full(v) => Some(v.len() as u64),
86            Self::Stream(_) => None,
87        }
88    }
89
90    /// `Some` for Empty/Full (cheap: refcount bumps), `None` for streams.
91    #[must_use]
92    pub fn try_clone(&self) -> Option<Self> {
93        match self {
94            Self::Empty => Some(Self::Empty),
95            Self::Full(v) => Some(Self::Full(v.clone())),
96            Self::Stream(_) => None,
97        }
98    }
99
100    #[must_use]
101    pub fn is_empty_hint(&self) -> bool {
102        self.size_hint() == Some(0)
103    }
104}
105
106impl From<BytesView> for Body {
107    fn from(v: BytesView) -> Self {
108        Self::full(v)
109    }
110}
111impl From<bytes::Bytes> for Body {
112    fn from(b: bytes::Bytes) -> Self {
113        Self::full(crate::buf::from_bytes(b))
114    }
115}
116impl From<Vec<u8>> for Body {
117    fn from(b: Vec<u8>) -> Self {
118        Self::full(bytes::Bytes::from(b))
119    }
120}
121impl From<&'static str> for Body {
122    fn from(s: &'static str) -> Self {
123        Self::from_static(s.as_bytes())
124    }
125}
126impl From<String> for Body {
127    fn from(s: String) -> Self {
128        Self::from(s.into_bytes())
129    }
130}
131
132/// Receiving half of [`Body::channel`].
133pub struct BodyStream {
134    rx: mpsc::Receiver<Result<BytesView>>,
135    abort: Arc<Mutex<Option<Error>>>,
136    done: bool,
137}
138
139impl fmt::Debug for BodyStream {
140    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
141        f.debug_struct("BodyStream").finish_non_exhaustive()
142    }
143}
144
145impl BodyStream {
146    fn poll_chunk(&mut self, cx: &mut Context<'_>) -> Poll<Option<Result<BytesView>>> {
147        if self.done {
148            return Poll::Ready(None);
149        }
150        match self.rx.poll_recv(cx) {
151            Poll::Ready(Some(item)) => Poll::Ready(Some(item)),
152            Poll::Ready(None) => {
153                self.done = true;
154                // Sender gone: clean finish, or an abort/drop-without-finish recorded an error.
155                let err = self
156                    .abort
157                    .lock()
158                    .unwrap_or_else(std::sync::PoisonError::into_inner)
159                    .take();
160                Poll::Ready(err.map(Err))
161            }
162            Poll::Pending => Poll::Pending,
163        }
164    }
165}
166
167/// Producer half of [`Body::channel`].
168///
169/// Dropping the sender without calling [`finish`](Self::finish) aborts the body with
170/// `Canceled`, so a producer that dies mid-upload can never look like a complete body.
171pub struct BodySender {
172    tx: mpsc::Sender<Result<BytesView>>,
173    abort: Arc<Mutex<Option<Error>>>,
174    finished: bool,
175}
176
177impl fmt::Debug for BodySender {
178    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
179        f.debug_struct("BodySender").finish_non_exhaustive()
180    }
181}
182
183impl BodySender {
184    /// Queues a chunk, waiting while the buffer is full. Empty chunks are skipped.
185    ///
186    /// # Errors
187    /// `Canceled` if the receiving side (the request) is gone.
188    pub async fn send(&mut self, chunk: BytesView) -> Result<()> {
189        if chunk.is_empty() {
190            return Ok(());
191        }
192        self.tx.send(Ok(chunk)).await.map_err(|_| {
193            Error::with_source(
194                ErrorKind::Canceled,
195                Recovery::Never,
196                "body receiver dropped",
197            )
198        })
199    }
200
201    /// Whether the receiving side is gone.
202    #[must_use]
203    pub fn is_closed(&self) -> bool {
204        self.tx.is_closed()
205    }
206
207    /// Ends the stream cleanly.
208    pub fn finish(mut self) {
209        self.finished = true;
210    }
211
212    /// Fails the stream. Chunks already queued are delivered first, then `err`.
213    pub fn abort(mut self, err: Error) {
214        self.finished = true;
215        self.record(err);
216    }
217
218    fn record(&self, err: Error) {
219        *self
220            .abort
221            .lock()
222            .unwrap_or_else(std::sync::PoisonError::into_inner) = Some(err);
223    }
224}
225
226impl Drop for BodySender {
227    fn drop(&mut self) {
228        if !self.finished {
229            self.record(Error::with_source(
230                ErrorKind::Canceled,
231                Recovery::Never,
232                "body sender dropped before finish",
233            ));
234        }
235        // `tx` drops after this, closing the channel; the receiver then observes the recorded error.
236    }
237}
238
239impl http_body::Body for Body {
240    type Data = BytesView;
241    type Error = Error;
242
243    fn poll_frame(
244        self: Pin<&mut Self>,
245        cx: &mut Context<'_>,
246    ) -> Poll<Option<Result<Frame<BytesView>>>> {
247        let this = self.get_mut();
248        match this {
249            Self::Empty => Poll::Ready(None),
250            Self::Full(_) => {
251                let Self::Full(v) = std::mem::replace(this, Self::Empty) else {
252                    unreachable!()
253                };
254                Poll::Ready(Some(Ok(Frame::data(v))))
255            }
256            Self::Stream(s) => s.poll_chunk(cx).map(|o| o.map(|r| r.map(Frame::data))),
257        }
258    }
259
260    fn is_end_stream(&self) -> bool {
261        match self {
262            Self::Empty => true,
263            Self::Full(v) => v.is_empty(),
264            Self::Stream(s) => s.done,
265        }
266    }
267
268    fn size_hint(&self) -> SizeHint {
269        match self {
270            Self::Empty => SizeHint::with_exact(0),
271            Self::Full(v) => SizeHint::with_exact(v.len() as u64),
272            Self::Stream(_) => SizeHint::default(),
273        }
274    }
275}
276
277#[cfg(test)]
278mod tests {
279    use std::future::poll_fn;
280
281    use http_body::Body as _;
282
283    use super::*;
284    use crate::buf;
285
286    async fn next(b: &mut Body) -> Option<Result<BytesView>> {
287        poll_fn(|cx| Pin::new(&mut *b).poll_frame(cx))
288            .await
289            .map(|r| r.map(|f| f.into_data().ok().unwrap()))
290    }
291
292    #[tokio::test]
293    async fn empty_and_full() {
294        let mut e = Body::empty();
295        assert_eq!(e.size_hint(), Some(0));
296        assert!(e.is_end_stream());
297        assert!(next(&mut e).await.is_none());
298
299        let mut f = Body::from_static(b"hello");
300        assert_eq!(f.size_hint(), Some(5));
301        assert_eq!(http_body::Body::size_hint(&f).exact(), Some(5));
302        assert!(!f.is_end_stream());
303        let c = f.try_clone().unwrap();
304        assert_eq!(next(&mut f).await.unwrap().unwrap().to_vec(), b"hello");
305        assert!(f.is_end_stream());
306        assert_eq!(f.size_hint(), Some(0));
307        assert!(next(&mut f).await.is_none());
308        assert_eq!(c.size_hint(), Some(5));
309        assert!(Body::full(buf::copy_from_slice(b"")).is_empty_hint());
310        assert!(matches!(Body::from(String::new()), Body::Empty));
311    }
312
313    #[tokio::test]
314    async fn channel_flow() {
315        let (mut tx, mut body) = Body::channel(2);
316        assert!(body.try_clone().is_none());
317        assert_eq!(body.size_hint(), None);
318        let prod = tokio::spawn(async move {
319            for i in 0..5u8 {
320                tx.send(buf::copy_from_slice(&[i; 3])).await.unwrap();
321            }
322            tx.finish();
323        });
324        let mut got = Vec::new();
325        while let Some(c) = next(&mut body).await {
326            got.extend(c.unwrap().to_vec());
327        }
328        prod.await.unwrap();
329        assert_eq!(got.len(), 15);
330        assert!(body.is_end_stream());
331    }
332
333    #[tokio::test]
334    async fn channel_abort_after_queued() {
335        let (mut tx, mut body) = Body::channel(4);
336        tx.send(buf::copy_from_slice(b"ab")).await.unwrap();
337        tx.abort(Error::io("boom"));
338        assert_eq!(next(&mut body).await.unwrap().unwrap().to_vec(), b"ab");
339        assert_eq!(
340            next(&mut body).await.unwrap().unwrap_err().kind(),
341            ErrorKind::Io
342        );
343        assert!(next(&mut body).await.is_none());
344    }
345
346    #[tokio::test]
347    async fn dropped_sender_is_not_clean_eof() {
348        let (tx, mut body) = Body::channel(1);
349        drop(tx);
350        assert_eq!(
351            next(&mut body).await.unwrap().unwrap_err().kind(),
352            ErrorKind::Canceled
353        );
354    }
355
356    #[tokio::test]
357    async fn dropped_receiver_fails_send() {
358        let (mut tx, body) = Body::channel(1);
359        drop(body);
360        assert!(tx.is_closed());
361        assert_eq!(
362            tx.send(buf::copy_from_slice(b"x"))
363                .await
364                .unwrap_err()
365                .kind(),
366            ErrorKind::Canceled
367        );
368        tx.finish();
369    }
370
371    #[tokio::test]
372    async fn backpressure() {
373        let (mut tx, mut body) = Body::channel(1);
374        tx.send(buf::copy_from_slice(b"1")).await.unwrap();
375        let second = tokio::time::timeout(
376            std::time::Duration::from_millis(50),
377            tx.send(buf::copy_from_slice(b"2")),
378        )
379        .await;
380        assert!(second.is_err(), "send must wait while buffer is full");
381        next(&mut body).await.unwrap().unwrap();
382        tx.send(buf::copy_from_slice(b"3")).await.unwrap();
383    }
384
385    #[test]
386    fn multi_span_io_slices() {
387        let v = BytesView::from_views([buf::copy_from_slice(b"ab"), buf::from_static(b"cd")]);
388        let mut slices = [std::io::IoSlice::new(&[]); 4];
389        assert_eq!(buf::io_slices(&v, &mut slices), 2);
390        assert_eq!(&*slices[1], b"cd");
391    }
392}