aria2-core 0.3.14

aria2-rust core download engine: multi-protocol segmented downloads, rate limiting, configuration, session persistence, and BitTorrent seeding
Documentation
//! HTTP forward proxy for non-HTTPS downloads.
//!
//! Also provides the [forward_get_with_auth] convenience function that
//! combines proxy connection, request sending, and auth handling.

use tokio::net::TcpStream;
use tracing::{debug, info, warn};

use crate::error::{Aria2Error, Result};
use crate::http::header_processor::HttpResponseHead;

use super::auth::build_proxy_auth_header;
use super::config::HttpProxyConfig;
use super::io::{MAX_AUTH_RETRIES, connect_to_proxy, read_proxy_response, write_all_timeout};
use super::response::ProxyResponse;

/// HTTP forward proxy for non-HTTPS downloads.
///
/// In forward mode, the proxy acts as a relay. The client sends requests with
/// the full URL (e.g., GET http://target:port/path HTTP/1.1) instead of just
/// the path. The proxy forwards the request to the target and relays the response.
///
/// For proxy authentication (407), the Proxy-Authorization header is added
/// on retry.
///
/// # Example
///
/// ``rust,ignore
/// use aria2_core::http::proxy::{HttpProxyConfig, HttpProxyForward};
///
/// let config = HttpProxyConfig::new(
///     "proxy.example.com".into(), 3128,
///     "target.example.com".into(), 80,
/// );
/// let forward = HttpProxyForward::new(config);
/// // Send the initial request and handle 407 retry
/// let stream = forward.connect().await?;
/// // Now send the actual HTTP request with full URL through stream
/// ``
pub struct HttpProxyForward {
    config: HttpProxyConfig,
}

impl HttpProxyForward {
    /// Create a new forward proxy handler with the given configuration.
    pub fn new(config: HttpProxyConfig) -> Self {
        Self { config }
    }

    /// Connect to the proxy and verify it is reachable.
    ///
    /// For forward proxy, we simply establish the TCP connection to the proxy.
    /// The actual HTTP request with the full URL is sent by the caller on the
    /// returned stream. This method also performs a lightweight handshake check:
    /// it sends an HTTP HEAD request and handles 407 if needed, then returns
    /// the stream ready for the actual request.
    ///
    /// If skip_handshake is true, only the TCP connection is established
    /// without any probe request. This is useful when the caller will
    /// immediately send their own request.
    pub async fn connect(&self, skip_handshake: bool) -> Result<TcpStream> {
        let target_url = format!(
            "http://{}:{}",
            self.config.target_host, self.config.target_port
        );
        let probe_request = if skip_handshake {
            None
        } else {
            Some(self.try_build_forward_request("HEAD", &target_url, "/", None)?)
        };
        let mut stream = connect_to_proxy(&self.config).await?;

        if skip_handshake {
            return Ok(stream);
        }

        // Send a probe HEAD request to check if proxy auth is needed
        debug!("Sending probe HEAD request to proxy for {}", target_url);
        write_all_timeout(
            &mut stream,
            probe_request
                .as_deref()
                .expect("probe request exists when handshake is enabled")
                .as_bytes(),
            self.config.write_timeout,
        )
        .await?;

        let mut auth_nc = 1u32;

        loop {
            let head = read_proxy_response(&mut stream, self.config.read_timeout).await?;
            let proxy_resp = ProxyResponse::from_head(head);

            match proxy_resp {
                ProxyResponse::Connected(_) => {
                    info!("Forward proxy connection ready for {}", target_url);
                    // For a HEAD probe, a 200 means we're good.
                    // But the stream has consumed the response; we need a fresh
                    // connection for the actual data request.
                    drop(stream);
                    return connect_to_proxy(&self.config).await;
                }
                ProxyResponse::AuthRequired { response } => {
                    let (username, password) = self.get_credentials()?;

                    if auth_nc > MAX_AUTH_RETRIES {
                        return Err(Aria2Error::Network(
                            "Proxy authentication failed after max retries".to_string(),
                        ));
                    }

                    let auth_value = build_proxy_auth_header(
                        &response,
                        &username,
                        &password,
                        "HEAD",
                        &target_url,
                        auth_nc,
                    )
                    .ok_or_else(|| {
                        Aria2Error::Network(
                            "Proxy requires auth but no supported scheme found".to_string(),
                        )
                    })?;

                    let retry_request = self.try_build_forward_request(
                        "HEAD",
                        &target_url,
                        "/",
                        Some(&auth_value),
                    )?;
                    auth_nc += 1;
                    warn!(
                        "Proxy returned 407, retrying with authentication (attempt {})",
                        auth_nc
                    );

                    // Close this connection and open a new one for the retry
                    drop(stream);
                    stream = connect_to_proxy(&self.config).await?;

                    write_all_timeout(
                        &mut stream,
                        retry_request.as_bytes(),
                        self.config.write_timeout,
                    )
                    .await?;
                }
                ProxyResponse::Error {
                    status_code,
                    reason,
                } => {
                    // Some proxies return 403 or other errors for HEAD probes
                    // but work fine for actual GET requests. Log a warning
                    // and return the stream anyway so the caller can try.
                    warn!(
                        "Proxy returned {} {} on probe, returning stream for caller to retry",
                        status_code, reason
                    );
                    drop(stream);
                    return connect_to_proxy(&self.config).await;
                }
            }
        }
    }

    /// Build a forward proxy request with the full URL.
    ///
    /// In forward proxy mode, the request line uses the absolute URL:
    /// METHOD http://host:port/path HTTP/1.1
    ///
    /// # Arguments
    /// * method - HTTP method (GET, HEAD, etc.)
    /// * full_url - The full URL including scheme and host (e.g., http://target:80/path)
    /// * path - Retained for compatibility; `full_url` determines the request
    ///   target and the caller supplies any computed authentication header.
    /// * proxy_auth - Optional Proxy-Authorization header value
    ///
    /// This is a raw compatibility serializer. Use
    /// [`Self::try_build_forward_request`] for data sent over a network.
    pub fn build_forward_request(
        &self,
        method: &str,
        full_url: &str,
        path: &str,
        proxy_auth: Option<&str>,
    ) -> String {
        let host = self.config.target_host_port();
        let mut headers = vec![("Host", host.as_str())];
        if let Some(auth) = proxy_auth {
            headers.push(("Proxy-Authorization", auth));
        }
        headers.extend([
            ("User-Agent", crate::constants::USER_AGENT),
            ("Accept", "*/*"),
            ("Connection", "close"),
        ]);
        let _ = path;
        String::from_utf8(aria2_protocol::http::request::serialize_http_request(
            method, full_url, &headers, None,
        ))
        .expect("HTTP request fields are UTF-8")
    }

    /// Build and validate a forward-proxy request before it is sent.
    pub fn try_build_forward_request(
        &self,
        method: &str,
        full_url: &str,
        path: &str,
        proxy_auth: Option<&str>,
    ) -> Result<String> {
        let host = self.config.target_host_port();
        let mut headers = vec![("Host", host.as_str())];
        if let Some(auth) = proxy_auth {
            headers.push(("Proxy-Authorization", auth));
        }
        headers.extend([
            ("User-Agent", crate::constants::USER_AGENT),
            ("Accept", "*/*"),
            ("Connection", "close"),
        ]);
        let _ = path;
        serialize_forward_request(method, full_url, &headers)
    }

    /// Extract credentials or return an error.
    pub(crate) fn get_credentials(&self) -> Result<(String, String)> {
        match (&self.config.proxy_username, &self.config.proxy_password) {
            (Some(u), Some(p)) => Ok((u.clone(), p.clone())),
            (Some(u), None) => Ok((u.clone(), String::new())),
            _ => Err(Aria2Error::Network(
                "Proxy requires authentication but no credentials provided".to_string(),
            )),
        }
    }
}

// ---------------------------------------------------------------------------
// Free helper: send a request through a forward proxy and handle 407
// ---------------------------------------------------------------------------

/// Send an HTTP GET request through a forward proxy, handling 407 auth retry.
///
/// This is a convenience function that combines proxy connection, request
/// sending, and auth handling into a single call. On success, returns the
/// TcpStream positioned after the response headers (ready to read body),
/// along with the parsed [HttpResponseHead].
///
/// # Arguments
/// * config - Proxy configuration
/// * path - The request path on the target (e.g., /download/file.zip)
///
/// # Returns
/// A tuple of (TcpStream, HttpResponseHead) where the stream is ready
/// for reading the response body.
pub async fn forward_get_with_auth(
    config: &HttpProxyConfig,
    path: &str,
) -> Result<(TcpStream, HttpResponseHead)> {
    let full_url = format!(
        "http://{}:{}{}",
        config.target_host, config.target_port, path
    );
    let host = config.target_host_port();
    let mut headers = vec![("Host", host.as_str())];
    headers.extend([
        ("User-Agent", crate::constants::USER_AGENT),
        ("Accept", "*/*"),
        ("Connection", "close"),
    ]);
    let mut request = serialize_forward_request("GET", &full_url, &headers)?;

    let mut stream = connect_to_proxy(config).await?;
    let mut auth_nc = 1u32;

    loop {
        write_all_timeout(&mut stream, request.as_bytes(), config.write_timeout).await?;
        let head = read_proxy_response(&mut stream, config.read_timeout).await?;
        let proxy_resp = ProxyResponse::from_head(head);

        match proxy_resp {
            ProxyResponse::Connected(head) => {
                return Ok((stream, head));
            }
            ProxyResponse::AuthRequired { response } => {
                let username = config.proxy_username.as_deref().unwrap_or("");
                let password = config.proxy_password.as_deref().unwrap_or("");

                if username.is_empty() && config.proxy_username.is_none() {
                    return Err(Aria2Error::Network(
                        "Proxy requires authentication but no credentials provided".to_string(),
                    ));
                }

                if auth_nc > MAX_AUTH_RETRIES {
                    return Err(Aria2Error::Network(
                        "Proxy authentication failed after max retries".to_string(),
                    ));
                }

                let auth_value = build_proxy_auth_header(
                    &response, username, password, "GET", &full_url, auth_nc,
                )
                .ok_or_else(|| {
                    Aria2Error::Network(
                        "Proxy requires auth but no supported scheme found".to_string(),
                    )
                })?;

                let mut authenticated_headers = vec![("Host", host.as_str())];
                authenticated_headers.push(("Proxy-Authorization", auth_value.as_str()));
                authenticated_headers.extend([
                    ("User-Agent", crate::constants::USER_AGENT),
                    ("Accept", "*/*"),
                    ("Connection", "close"),
                ]);
                request = serialize_forward_request("GET", &full_url, &authenticated_headers)?;

                auth_nc += 1;

                warn!(
                    "Proxy returned 407, retrying GET with auth (attempt {})",
                    auth_nc
                );

                // Open a new connection for the retry
                drop(stream);
                stream = connect_to_proxy(config).await?;
            }
            ProxyResponse::Error {
                status_code,
                reason,
            } => {
                return Err(Aria2Error::Network(format!(
                    "Proxy returned error {} {} for GET {}",
                    status_code, reason, full_url
                )));
            }
        }
    }
}

fn serialize_forward_request(
    method: &str,
    full_url: &str,
    headers: &[(&str, &str)],
) -> Result<String> {
    let bytes =
        aria2_protocol::http::request::try_serialize_http_request(method, full_url, headers, None)
            .map_err(|_| {
                Aria2Error::InvalidArgument("invalid HTTP forward-proxy request fields".into())
            })?;
    String::from_utf8(bytes)
        .map_err(|_| Aria2Error::InvalidArgument("HTTP request fields are not UTF-8".into()))
}