Skip to main content

nautilus_network/http/
stream.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//! Streaming HTTP responses with the request's original deadline and connection ownership.
17
18use bytes::Bytes;
19use http::{HeaderMap, StatusCode};
20use http_body_util::BodyExt;
21use hyper::body::Incoming;
22
23use super::{HttpClientError, client::REQUEST_TIMEOUT_MESSAGE, error::transport_error};
24use crate::dst::time::Instant;
25
26/// An HTTP response whose body is consumed incrementally.
27///
28/// One absolute deadline covers response headers and the whole body, including time between
29/// chunk reads. Dropping an unfinished response releases its body and, under simulation,
30/// aborts its owned connection task. No total body limit applies.
31#[derive(Debug)]
32pub struct HttpResponseStream {
33    pub(super) response: http::Response<Incoming>,
34    pub(super) deadline: Option<Instant>,
35    pub(super) origin: Option<String>,
36    #[cfg(all(feature = "simulation", madsim))]
37    pub(super) _connection: super::simulation::Connection,
38}
39
40impl HttpResponseStream {
41    /// Returns the HTTP response status.
42    #[must_use]
43    pub fn status(&self) -> StatusCode {
44        self.response.status()
45    }
46
47    /// Returns the response headers without consuming the body.
48    #[must_use]
49    pub fn headers(&self) -> &HeaderMap {
50        self.response.headers()
51    }
52
53    /// Reads the next body chunk, or returns `None` at the end of the body.
54    ///
55    /// # Errors
56    ///
57    /// Returns an error if the transport fails or the original request deadline expires.
58    pub async fn chunk(&mut self) -> Result<Option<Bytes>, HttpClientError> {
59        read_chunk(self.response.body_mut(), self.deadline)
60            .await
61            .map_err(|e| response_error(e, self.origin.as_deref()))
62    }
63}
64
65pub(super) async fn read_chunk<B>(
66    body: &mut B,
67    deadline: Option<Instant>,
68) -> Result<Option<Bytes>, HttpClientError>
69where
70    B: http_body::Body<Data = Bytes> + Unpin,
71    B::Error: std::error::Error + 'static,
72{
73    loop {
74        check_deadline(deadline)?;
75
76        let frame = match deadline {
77            Some(deadline) => {
78                tokio::select! {
79                    biased;
80                    () = crate::dst::time::sleep_until(deadline) => return Err(HttpClientError::TimeoutError(REQUEST_TIMEOUT_MESSAGE.into())),
81                    frame = body.frame() => frame,
82                }
83            }
84            None => body.frame().await,
85        };
86
87        let Some(frame) = frame else {
88            return Ok(None);
89        };
90
91        if let Ok(chunk) = frame.map_err(|e| transport_error(&e))?.into_data() {
92            return Ok(Some(chunk));
93        }
94    }
95}
96
97pub(super) fn check_deadline(deadline: Option<Instant>) -> Result<(), HttpClientError> {
98    if deadline.is_some_and(|deadline| Instant::now() >= deadline) {
99        return Err(HttpClientError::TimeoutError(
100            REQUEST_TIMEOUT_MESSAGE.into(),
101        ));
102    }
103
104    Ok(())
105}
106
107pub(super) fn response_error(error: HttpClientError, origin: Option<&str>) -> HttpClientError {
108    match (error, origin) {
109        (HttpClientError::TransportError(message), Some(origin)) => {
110            HttpClientError::TransportError(format!("{message} for origin ({origin})"))
111        }
112        (error, _) => error,
113    }
114}
115
116#[cfg(test)]
117mod tests {
118    use std::io;
119
120    use http::{HeaderMap, HeaderValue, header::HeaderName};
121    use http_body::Frame;
122    use http_body_util::StreamBody;
123    use rstest::rstest;
124
125    use super::*;
126
127    #[tokio::test]
128    async fn read_chunk_skips_trailers_and_preserves_data() {
129        let trailers = HeaderMap::from_iter([(
130            HeaderName::from_static("x-checksum"),
131            HeaderValue::from_static("receipt-83"),
132        )]);
133        let frames: Vec<Result<_, io::Error>> = vec![
134            Ok(Frame::data(Bytes::from_static(b"first"))),
135            Ok(Frame::data(Bytes::from_static(b"second"))),
136            Ok(Frame::trailers(trailers)),
137        ];
138        let mut body = StreamBody::new(futures_util::stream::iter(frames));
139
140        let first = read_chunk(&mut body, None).await.unwrap();
141        let second = read_chunk(&mut body, None).await.unwrap();
142        let end = read_chunk(&mut body, None).await.unwrap();
143
144        assert_eq!(first, Some(Bytes::from_static(b"first")));
145        assert_eq!(second, Some(Bytes::from_static(b"second")));
146        assert_eq!(end, None);
147    }
148
149    #[rstest]
150    #[case::transport(io::ErrorKind::UnexpectedEof, false)]
151    #[case::timeout(io::ErrorKind::TimedOut, true)]
152    #[tokio::test]
153    async fn read_chunk_propagates_body_error(#[case] kind: io::ErrorKind, #[case] timeout: bool) {
154        let frames = vec![Err::<Frame<Bytes>, _>(io::Error::new(kind, "body failure"))];
155        let mut body = StreamBody::new(futures_util::stream::iter(frames));
156
157        let error = read_chunk(&mut body, None).await.unwrap_err();
158
159        match (error, timeout) {
160            (HttpClientError::TimeoutError(message), true)
161            | (HttpClientError::TransportError(message), false) => {
162                assert_eq!(message, "body failure");
163            }
164            (error, _) => panic!("unexpected classification: {error:?}"),
165        }
166    }
167}