Skip to main content

aria2_protocol/http/
client.rs

1use std::sync::Once;
2use std::time::Duration;
3
4use bytes::Bytes;
5use futures::{StreamExt, stream::BoxStream};
6use reqwest::{Certificate, Client, ClientBuilder, redirect};
7use tracing::{debug, info};
8
9use crate::http::request::HttpRequest;
10use crate::http::response::{HttpResponse, is_redirect_status};
11
12#[derive(Debug, Clone)]
13pub struct HttpClientOptions {
14    pub connect_timeout: Duration,
15    pub timeout: Duration,
16    pub max_redirects: usize,
17    pub user_agent: String,
18    pub accept_gzip: bool,
19    pub verify_tls: bool,
20    pub ca_cert_path: Option<String>,
21}
22
23/// A response body stream returned by [`HttpClient::execute_stream`].
24///
25/// Response metadata is available immediately after headers arrive. Body
26/// bytes are read on demand, so dropping this value cancels the in-flight
27/// response instead of buffering the remaining payload.
28pub struct HttpResponseStream {
29    status_code: u16,
30    status_text: String,
31    headers: Vec<(String, String)>,
32    body: HttpBodyStream,
33}
34
35/// The body stream type exposed by [`HttpResponseStream::into_stream`].
36pub type HttpBodyStream = BoxStream<'static, Result<Bytes, String>>;
37
38impl HttpResponseStream {
39    /// Return the HTTP status code received from the server.
40    pub fn status_code(&self) -> u16 {
41        self.status_code
42    }
43
44    /// Return the canonical status text received from the server.
45    pub fn status_text(&self) -> &str {
46        &self.status_text
47    }
48
49    /// Return the response headers captured before body streaming began.
50    pub fn headers(&self) -> &[(String, String)] {
51        &self.headers
52    }
53
54    /// Look up a response header without regard to ASCII case.
55    pub fn header(&self, name: &str) -> Option<&String> {
56        self.headers
57            .iter()
58            .find(|(key, _)| key.eq_ignore_ascii_case(name))
59            .map(|(_, value)| value)
60    }
61
62    /// Read the next body chunk.
63    ///
64    /// `None` means end-of-stream. Transport failures are returned as
65    /// `Err(String)` and do not get silently converted into an empty body.
66    pub async fn next_chunk(&mut self) -> Option<Result<Bytes, String>> {
67        self.body.next().await
68    }
69
70    /// Take ownership of the underlying body stream.
71    pub fn into_stream(self) -> HttpBodyStream {
72        self.body
73    }
74
75    /// Collect the streamed body into the existing buffered response type.
76    pub async fn collect(mut self) -> Result<HttpResponse, String> {
77        let mut body = Vec::new();
78        while let Some(chunk) = self.next_chunk().await {
79            body.extend_from_slice(&chunk?);
80        }
81
82        Ok(HttpResponse {
83            status_code: self.status_code,
84            status_text: self.status_text,
85            headers: self.headers,
86            body,
87        })
88    }
89}
90
91impl Default for HttpClientOptions {
92    fn default() -> Self {
93        Self {
94            connect_timeout: Duration::from_secs(30),
95            timeout: Duration::from_secs(300),
96            max_redirects: 5,
97            user_agent: crate::identity::DEFAULT_USER_AGENT.to_string(),
98            // aria2_original advertises compressed HTTP responses only when
99            // --http-accept-gzip is enabled. Keep the protocol client safe
100            // by default; callers can opt in explicitly.
101            accept_gzip: false,
102            verify_tls: true,
103            ca_cert_path: None,
104        }
105    }
106}
107
108pub struct HttpClient {
109    inner: Client,
110    options: HttpClientOptions,
111}
112
113/// Validation failures returned by the fallible request-builder header API.
114#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
115pub enum HttpRequestBuilderError {
116    #[error("invalid header name: {0}")]
117    InvalidName(String),
118    #[error("invalid header value: {0}")]
119    InvalidValue(String),
120}
121
122/// Lazily install the `ring` crypto provider for rustls on first call.
123///
124/// Required when reqwest is built with the `rustls-no-provider` feature;
125/// without a provider, `ClientBuilder::build()` will panic.
126///
127/// Note: `install_default()` returns Err if a provider is already installed
128/// (e.g., by test helpers' `ensure_crypto_provider()`). That is fine — we
129/// only need to ensure a provider is present, not that we installed it.
130pub(crate) fn ensure_ring_provider() {
131    static INIT: Once = Once::new();
132    INIT.call_once(|| {
133        let _ = rustls::crypto::ring::default_provider().install_default();
134    });
135}
136
137impl HttpClient {
138    pub fn new(options: HttpClientOptions) -> Result<Self, String> {
139        // Ensure the TLS crypto provider is installed before constructing
140        // the reqwest Client (required for rustls-no-provider builds).
141        ensure_ring_provider();
142        let mut builder = ClientBuilder::new()
143            .connect_timeout(options.connect_timeout)
144            .timeout(options.timeout)
145            .user_agent(&options.user_agent)
146            .redirect(redirect::Policy::limited(options.max_redirects));
147
148        builder = builder.gzip(options.accept_gzip);
149
150        if !options.verify_tls {
151            builder = builder.danger_accept_invalid_certs(true);
152        }
153
154        if let Some(ref ca_path) = options.ca_cert_path {
155            match std::fs::read(ca_path) {
156                Ok(cert_bytes) => {
157                    let cert = Certificate::from_pem(&cert_bytes)
158                        .map_err(|e| format!("Failed to load CA certificate: {}", e))?;
159                    builder = builder.add_root_certificate(cert);
160                }
161                Err(e) => return Err(format!("Failed to read CA certificate file: {}", e)),
162            }
163        }
164
165        let inner = builder
166            .build()
167            .map_err(|e| format!("Failed to create HTTP client: {}", e))?;
168
169        info!(
170            "HttpClient initialized (timeout={:?}, max_redirects={}, verify_tls={})",
171            options.timeout, options.max_redirects, options.verify_tls
172        );
173
174        Ok(Self { inner, options })
175    }
176
177    pub fn default_client() -> Result<Self, String> {
178        Self::new(HttpClientOptions::default())
179    }
180
181    fn build_request(&self, request: HttpRequest) -> Result<reqwest::RequestBuilder, String> {
182        debug!("Sending HTTP request: {} {}", request.method, request.url);
183
184        let mut reqwest_request = match request.method.to_uppercase().as_str() {
185            "GET" => self.inner.get(&request.url),
186            "POST" => self.inner.post(&request.url),
187            "HEAD" => self.inner.head(&request.url),
188            "PUT" => self.inner.put(&request.url),
189            _ => return Err(format!("Unsupported HTTP method: {}", request.method)),
190        };
191
192        if let Some(ref headers) = request.headers {
193            for (key, value) in headers.iter() {
194                reqwest_request = reqwest_request.header(
195                    key.as_str()
196                        .parse::<reqwest::header::HeaderName>()
197                        .map_err(|e| format!("Invalid header name: {}", e))?,
198                    value.as_str(),
199                );
200            }
201        }
202
203        if let Some(body) = request.body {
204            reqwest_request = reqwest_request.body(body);
205        }
206
207        Ok(reqwest_request)
208    }
209
210    pub async fn execute(&self, request: HttpRequest) -> Result<HttpResponse, String> {
211        let response = self
212            .build_request(request)?
213            .send()
214            .await
215            .map_err(|e| format!("HTTP request failed: {}", e))?;
216
217        let (status_code, status_text, headers_map) = response_metadata(&response);
218        debug!("Received HTTP response: status_code={}", status_code);
219
220        let body_bytes = response
221            .bytes()
222            .await
223            .map_err(|e| format!("Failed to read response body: {}", e))?
224            .to_vec();
225
226        Ok(HttpResponse {
227            status_code,
228            status_text,
229            headers: headers_map,
230            body: body_bytes,
231        })
232    }
233
234    /// Execute a request without buffering its response body.
235    ///
236    /// The returned metadata is available after response headers arrive. Use
237    /// [`HttpResponseStream::next_chunk`] for incremental reads, or drop the
238    /// stream to cancel the remaining transfer.
239    pub async fn execute_stream(&self, request: HttpRequest) -> Result<HttpResponseStream, String> {
240        let response = self
241            .build_request(request)?
242            .send()
243            .await
244            .map_err(|e| format!("HTTP request failed: {}", e))?;
245
246        let (status_code, status_text, headers) = response_metadata(&response);
247        debug!(
248            "Received HTTP response headers: status_code={}",
249            status_code
250        );
251        let body = response
252            .bytes_stream()
253            .map(|chunk| chunk.map_err(|e| format!("Failed to read response body: {}", e)))
254            .boxed();
255
256        Ok(HttpResponseStream {
257            status_code,
258            status_text,
259            headers,
260            body,
261        })
262    }
263
264    pub fn get<U: Into<String>>(&self, url: U) -> HttpRequestBuilder<'_> {
265        HttpRequestBuilder::new(self, "GET", url.into())
266    }
267
268    pub fn post<U: Into<String>>(&self, url: U) -> HttpRequestBuilder<'_> {
269        HttpRequestBuilder::new(self, "POST", url.into())
270    }
271
272    pub fn head<U: Into<String>>(&self, url: U) -> HttpRequestBuilder<'_> {
273        HttpRequestBuilder::new(self, "HEAD", url.into())
274    }
275
276    pub fn options_ref(&self) -> &HttpClientOptions {
277        &self.options
278    }
279}
280
281fn response_metadata(response: &reqwest::Response) -> (u16, String, Vec<(String, String)>) {
282    let status = response.status();
283    let headers = response
284        .headers()
285        .iter()
286        .map(|(key, value)| {
287            (
288                key.as_str().to_string(),
289                value.to_str().unwrap_or("").to_string(),
290            )
291        })
292        .collect();
293    (
294        status.as_u16(),
295        status.canonical_reason().unwrap_or("Unknown").to_string(),
296        headers,
297    )
298}
299
300pub struct HttpRequestBuilder<'a> {
301    client: &'a HttpClient,
302    method: String,
303    url: String,
304    headers: Option<reqwest::header::HeaderMap>,
305    body: Option<Vec<u8>>,
306    error: Option<HttpRequestBuilderError>,
307}
308
309impl<'a> HttpRequestBuilder<'a> {
310    fn new(client: &'a HttpClient, method: &str, url: String) -> Self {
311        Self {
312            client,
313            method: method.to_string(),
314            url,
315            headers: None,
316            body: None,
317            error: None,
318        }
319    }
320
321    /// Add a header using the existing chainable API.
322    ///
323    /// Invalid input is reported by [`Self::send`] or
324    /// [`Self::send_stream`]. Use [`Self::try_header`] when validation should
325    /// happen immediately.
326    pub fn header(mut self, name: &str, value: &str) -> Self {
327        if let Err(error) = self.insert_header(name, value) {
328            self.error = Some(error);
329        }
330        self
331    }
332
333    /// Add a header and return validation errors instead of panicking.
334    ///
335    /// `header` remains available for trusted, compile-time-known headers and
336    /// preserves the existing chainable API. Use this method for values that
337    /// originate outside the application, such as user configuration or an
338    /// RPC request.
339    pub fn try_header(mut self, name: &str, value: &str) -> Result<Self, HttpRequestBuilderError> {
340        self.insert_header(name, value)?;
341        Ok(self)
342    }
343
344    fn insert_header(&mut self, name: &str, value: &str) -> Result<(), HttpRequestBuilderError> {
345        let mut headers = self.headers.take().unwrap_or_default();
346        let name = name
347            .parse::<reqwest::header::HeaderName>()
348            .map_err(|error| HttpRequestBuilderError::InvalidName(error.to_string()))?;
349        let value = value
350            .parse::<reqwest::header::HeaderValue>()
351            .map_err(|error| HttpRequestBuilderError::InvalidValue(error.to_string()))?;
352        headers.insert(name, value);
353        self.headers = Some(headers);
354        Ok(())
355    }
356
357    /// Add a typed header using the existing chainable API.
358    ///
359    /// Conversion failures are reported by [`Self::send`] or
360    /// [`Self::send_stream`]. Use [`Self::try_header_raw`] for immediate
361    /// validation.
362    pub fn header_raw<K, V>(mut self, key: K, value: V) -> Self
363    where
364        K: TryInto<reqwest::header::HeaderName>,
365        V: TryInto<reqwest::header::HeaderValue>,
366    {
367        let mut headers = self.headers.take().unwrap_or_default();
368        match (key.try_into(), value.try_into()) {
369            (Ok(k), Ok(v)) => {
370                headers.insert(k, v);
371                self.headers = Some(headers);
372            }
373            (Err(_), _) => {
374                self.error = Some(HttpRequestBuilderError::InvalidName(
375                    "header name conversion failed".to_string(),
376                ));
377            }
378            (_, Err(_)) => {
379                self.error = Some(HttpRequestBuilderError::InvalidValue(
380                    "header value conversion failed".to_string(),
381                ));
382            }
383        }
384        self
385    }
386
387    /// Add a typed header and preserve conversion errors for the caller.
388    pub fn try_header_raw<K, V>(mut self, key: K, value: V) -> Result<Self, HttpRequestBuilderError>
389    where
390        K: TryInto<reqwest::header::HeaderName>,
391        K::Error: std::fmt::Display,
392        V: TryInto<reqwest::header::HeaderValue>,
393        V::Error: std::fmt::Display,
394    {
395        let key = key
396            .try_into()
397            .map_err(|error| HttpRequestBuilderError::InvalidName(error.to_string()))?;
398        let value = value
399            .try_into()
400            .map_err(|error| HttpRequestBuilderError::InvalidValue(error.to_string()))?;
401        let mut headers = self.headers.take().unwrap_or_default();
402        headers.insert(key, value);
403        self.headers = Some(headers);
404        Ok(self)
405    }
406
407    pub fn range(self, start: u64, end: Option<u64>) -> Self {
408        let range_value = match end {
409            Some(e) => format!("bytes={}-{}", start, e),
410            None => format!("bytes={}-", start),
411        };
412        self.header("Range", &range_value)
413    }
414
415    pub fn body<B: Into<Vec<u8>>>(mut self, body: B) -> Self {
416        self.body = Some(body.into());
417        self
418    }
419
420    pub fn user_agent(self, ua: &str) -> Self {
421        self.header("User-Agent", ua)
422    }
423
424    pub fn referer(self, referer: &str) -> Self {
425        self.header("Referer", referer)
426    }
427
428    fn into_request(self) -> Result<(&'a HttpClient, HttpRequest), HttpRequestBuilderError> {
429        let Self {
430            client,
431            method,
432            url,
433            headers,
434            body,
435            error,
436        } = self;
437        if let Some(error) = error {
438            return Err(error);
439        }
440        let headers_map = headers.map(|h| {
441            h.iter()
442                .map(|(k, v)| (k.as_str().to_string(), v.to_str().unwrap_or("").to_string()))
443                .collect::<Vec<_>>()
444        });
445
446        Ok((
447            client,
448            HttpRequest {
449                method,
450                url,
451                headers: headers_map,
452                body,
453            },
454        ))
455    }
456
457    pub async fn send(self) -> Result<HttpResponse, String> {
458        let (client, request) = self.into_request().map_err(|error| error.to_string())?;
459        client.execute(request).await
460    }
461
462    /// Send this request while keeping the response body incremental.
463    pub async fn send_stream(self) -> Result<HttpResponseStream, String> {
464        let (client, request) = self.into_request().map_err(|error| error.to_string())?;
465        client.execute_stream(request).await
466    }
467}
468
469#[derive(Debug, Clone, PartialEq)]
470pub enum RedirectPolicy {
471    Follow,
472    Limit(usize),
473    None,
474}
475
476impl Default for RedirectPolicy {
477    fn default() -> Self {
478        Self::Limit(5)
479    }
480}
481
482pub struct RedirectHandler;
483
484impl RedirectHandler {
485    pub fn should_follow_redirect(
486        status_code: u16,
487        _method: &str,
488        current_redirects: usize,
489        max_redirects: usize,
490    ) -> Option<RedirectAction> {
491        if current_redirects >= max_redirects {
492            debug!("Maximum redirect limit reached: {}", max_redirects);
493            return None;
494        }
495
496        if !is_redirect_status(status_code) {
497            return None;
498        }
499
500        match status_code {
501            300 | 301 => Some(RedirectAction::FollowKeepMethod),
502            302 | 303 => Some(RedirectAction::FollowChangeToGet),
503            307 | 308 => Some(RedirectAction::FollowKeepMethod),
504            _ => None,
505        }
506    }
507
508    pub fn resolve_redirect_url(current_url: &str, location: &str) -> Result<String, String> {
509        let location = location.trim();
510        if location.is_empty() {
511            return Err("Location header is empty".to_string());
512        }
513
514        if location.starts_with("http://") || location.starts_with("https://") {
515            return Ok(location.to_string());
516        }
517
518        if location.starts_with("/") {
519            if let Some(base_end) = current_url[8..].find('/') {
520                Ok(format!("{}{}", &current_url[..8 + base_end], location))
521            } else {
522                Ok(format!("{}{}", current_url, location))
523            }
524        } else {
525            let last_slash = current_url.rfind('/').unwrap_or(current_url.len());
526            if last_slash < 8 {
527                Ok(format!("{}/{}", current_url, location))
528            } else {
529                Ok(format!("{}{}", &current_url[..last_slash + 1], location))
530            }
531        }
532    }
533
534    pub fn sanitize_redirect_url(url: &str) -> Result<String, String> {
535        if !url.starts_with("http://") && !url.starts_with("https://") {
536            return Err(format!("Unsafe redirect URL protocol: {}", url));
537        }
538        Ok(url.to_string())
539    }
540}
541
542pub enum RedirectAction {
543    FollowKeepMethod,
544    FollowChangeToGet,
545}
546
547#[cfg(test)]
548mod tests {
549    use super::*;
550    use tokio::io::{AsyncReadExt, AsyncWriteExt};
551    use tokio::net::TcpListener;
552
553    #[test]
554    fn default_options_do_not_advertise_gzip() {
555        assert!(!HttpClientOptions::default().accept_gzip);
556    }
557
558    #[test]
559    fn fallible_header_builder_reports_invalid_input() {
560        let client = HttpClient::default_client().unwrap();
561
562        let name_error = client
563            .get("http://example.test")
564            .try_header("invalid header name", "value");
565        assert!(matches!(
566            name_error,
567            Err(HttpRequestBuilderError::InvalidName(_))
568        ));
569
570        let value_error = client
571            .get("http://example.test")
572            .try_header("X-Test", "invalid\nvalue");
573        assert!(matches!(
574            value_error,
575            Err(HttpRequestBuilderError::InvalidValue(_))
576        ));
577    }
578
579    #[tokio::test]
580    async fn chainable_header_reports_invalid_input_without_panicking() {
581        let client = HttpClient::default_client().unwrap();
582        let result = client
583            .get("http://example.test")
584            .header("invalid header name", "value")
585            .send()
586            .await;
587
588        assert!(matches!(
589            result,
590            Err(error) if error.contains("invalid header name")
591        ));
592    }
593
594    #[test]
595    fn test_should_follow_301() {
596        let action = RedirectHandler::should_follow_redirect(301, "GET", 0, 5);
597        assert!(action.is_some());
598
599        let no_action = RedirectHandler::should_follow_redirect(301, "GET", 5, 5);
600        assert!(no_action.is_none());
601    }
602
603    #[test]
604    fn test_should_follow_300() {
605        let action = RedirectHandler::should_follow_redirect(300, "GET", 0, 5);
606        assert!(matches!(action, Some(RedirectAction::FollowKeepMethod)));
607    }
608
609    #[test]
610    fn test_should_not_follow_200() {
611        let action = RedirectHandler::should_follow_redirect(200, "GET", 0, 5);
612        assert!(action.is_none());
613    }
614
615    #[test]
616    fn test_resolve_absolute_redirect() {
617        let url = RedirectHandler::resolve_redirect_url(
618            "http://example.com/page",
619            "http://other.example.com/new",
620        )
621        .unwrap();
622        assert_eq!(url, "http://other.example.com/new");
623    }
624
625    #[test]
626    fn test_resolve_relative_redirect() {
627        let url = RedirectHandler::resolve_redirect_url("http://example.com/old/path", "/new/path")
628            .unwrap();
629        assert_eq!(url, "http://example.com/new/path");
630    }
631
632    #[test]
633    fn test_resolve_relative_path_redirect() {
634        let url = RedirectHandler::resolve_redirect_url(
635            "http://example.com/old/page.html",
636            "new-page.html",
637        )
638        .unwrap();
639        assert_eq!(url, "http://example.com/old/new-page.html");
640    }
641
642    #[test]
643    fn test_302_changes_to_get() {
644        let action = RedirectHandler::should_follow_redirect(302, "POST", 0, 5);
645        assert!(action.is_some());
646        if let Some(action) = action {
647            assert!(matches!(action, RedirectAction::FollowChangeToGet));
648        }
649    }
650
651    #[test]
652    fn test_307_keeps_method() {
653        let action = RedirectHandler::should_follow_redirect(307, "POST", 0, 5);
654        assert!(action.is_some());
655        if let Some(action) = action {
656            assert!(matches!(action, RedirectAction::FollowKeepMethod));
657        }
658    }
659
660    #[tokio::test]
661    async fn execute_stream_exposes_metadata_and_incremental_body() {
662        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
663        let address = listener.local_addr().unwrap();
664        let server = tokio::spawn(async move {
665            let (mut connection, _) = listener.accept().await.unwrap();
666            let mut request = [0_u8; 1024];
667            let _ = connection.read(&mut request).await.unwrap();
668            connection
669                .write_all(
670                    b"HTTP/1.1 200 OK\r\nContent-Length: 11\r\nX-Test: stream\r\nConnection: close\r\n\r\nhello world",
671                )
672                .await
673                .unwrap();
674            connection.shutdown().await.unwrap();
675        });
676
677        let client = HttpClient::default_client().unwrap();
678        let mut response = client
679            .get(format!("http://{address}/payload"))
680            .send_stream()
681            .await
682            .unwrap();
683        assert_eq!(response.status_code(), 200);
684        assert_eq!(response.status_text(), "OK");
685        assert_eq!(response.header("x-test"), Some(&"stream".to_string()));
686
687        let mut body = Vec::new();
688        let mut chunks = 0;
689        while let Some(chunk) = response.next_chunk().await {
690            chunks += 1;
691            body.extend_from_slice(&chunk.unwrap());
692        }
693        assert!(chunks > 0);
694        assert_eq!(body, b"hello world");
695        server.await.unwrap();
696    }
697
698    #[tokio::test]
699    async fn execute_stream_propagates_truncated_body_errors() {
700        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
701        let address = listener.local_addr().unwrap();
702        let server = tokio::spawn(async move {
703            let (mut connection, _) = listener.accept().await.unwrap();
704            let mut request = [0_u8; 1024];
705            let _ = connection.read(&mut request).await.unwrap();
706            connection
707                .write_all(
708                    b"HTTP/1.1 200 OK\r\nContent-Length: 10\r\nConnection: close\r\n\r\nshort",
709                )
710                .await
711                .unwrap();
712            connection.shutdown().await.unwrap();
713        });
714
715        let client = HttpClient::default_client().unwrap();
716        let mut response = client
717            .execute_stream(HttpRequest::get(format!("http://{address}/truncated")))
718            .await
719            .unwrap();
720        let mut saw_error = false;
721        while let Some(chunk) = response.next_chunk().await {
722            if chunk.is_err() {
723                saw_error = true;
724                break;
725            }
726        }
727        assert!(
728            saw_error,
729            "premature EOF must not look like a successful body"
730        );
731        server.await.unwrap();
732    }
733}