aria2-core 0.3.13

aria2-rust core download engine: multi-protocol segmented downloads, rate limiting, configuration, session persistence, and BitTorrent seeding
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
//! HTTP skip response handler — the main processing logic.
//!
//! Contains `HttpSkipResponseHandler` which consumes and discards HTTP response
//! bodies via NullSinkFilter, then classifies the response as a redirect,
//! authentication challenge, error, or consumed-ok.

use url::Url;

use crate::error::{Aria2Error, RecoverableError};
use crate::http::digest_auth::DigestAuthChallenge;
use crate::http::request::HttpMethod;
use crate::http::stream_filter::{AutoFilterSelector, NullSinkFilter, process_filters};

use super::types::{
    AuthScheme, HttpAuthChallenge, HttpRedirectInfo, RedirectType, SkipResponseResult,
};

// Re-export HttpResponse from aria2-protocol so handler methods can use it
// without callers needing to import two different crates.
pub use aria2_protocol::http::response::HttpResponse;
use aria2_protocol::http::response::is_redirect_status;

/// Handler for HTTP responses that need to be skipped (non-file-data responses).
///
/// This is the Rust equivalent of C++ `HttpSkipResponseCommand`.
/// It consumes the response body (discarding it via NullSinkFilter),
/// then classifies the response as a redirect, auth challenge, error,
/// or consumed-ok.
///
/// # Configuration
///
/// The handler is configured via builder-style methods:
/// - [`with_http_auth_challenge`](Self::with_http_auth_challenge): enable 401 basic auth retry
/// - [`with_max_file_not_found`](Self::with_max_file_not_found): 404 retry count
/// - [`with_retry_wait`](Self::with_retry_wait): 502/503 retry threshold
///
/// # Example
///
/// ```rust,ignore
/// use aria2_core::http::skip_response::{HttpSkipResponseHandler, MAX_REDIRECT_COUNT};
///
/// let handler = HttpSkipResponseHandler::new(MAX_REDIRECT_COUNT)
///     .with_http_auth_challenge(true)
///     .with_max_file_not_found(3)
///     .with_retry_wait(5);
///
/// let result = handler.handle(&response, HttpMethod::Get, &url, 0)?;
/// ```
pub struct HttpSkipResponseHandler {
    /// Maximum number of redirects allowed
    max_redirects: u32,
    /// Whether HTTP auth challenge is enabled (maps to C++ PREF_HTTP_AUTH_CHALLENGE)
    http_auth_challenge_enabled: bool,
    /// Maximum "file not found" (404) retries before aborting;
    /// 0 means abort immediately on 404
    max_file_not_found: u32,
    /// Retry wait in seconds; 0 means do not retry 502/503
    retry_wait_secs: u64,
}

impl HttpSkipResponseHandler {
    /// Create a new handler with the given max-redirect limit.
    pub fn new(max_redirects: u32) -> Self {
        Self {
            max_redirects,
            http_auth_challenge_enabled: false,
            max_file_not_found: 0,
            retry_wait_secs: 0,
        }
    }

    /// Set whether HTTP auth challenge handling is enabled.
    ///
    /// When enabled, a 401 response without a WWW-Authenticate header
    /// will still return `AuthChallenge` (Basic) instead of `FatalError`,
    /// allowing the caller to retry with credentials (matches C++ behavior
    /// where `activateBasicCred` is tried).
    pub fn with_http_auth_challenge(mut self, enabled: bool) -> Self {
        self.http_auth_challenge_enabled = enabled;
        self
    }

    /// Set the maximum number of 404 retries before aborting.
    ///
    /// When > 0, 404 responses produce `RetryableError`; when 0 (default),
    /// 404 responses produce `FatalError` (matches C++ `max-file-not-found` option).
    pub fn with_max_file_not_found(mut self, count: u32) -> Self {
        self.max_file_not_found = count;
        self
    }

    /// Set the retry wait in seconds. When > 0, 502/503 errors are retryable.
    ///
    /// Matches C++ `retry-wait` option: hammering a busy server is not ideal,
    /// so 502/503 are only retryable when there is a non-zero wait between attempts.
    pub fn with_retry_wait(mut self, secs: u64) -> Self {
        self.retry_wait_secs = secs;
        self
    }

    /// Consume and discard the response body, then classify the response.
    ///
    /// This mirrors the C++ `executeInternal()` + `processResponse()` flow:
    /// 1. Consume the body through stream filters (handling chunked/content-encoding)
    ///    using NullSinkFilter to discard data.
    /// 2. Classify the status code and return the appropriate `SkipResponseResult`.
    ///
    /// # Arguments
    /// * `response` - The parsed HTTP response (body may already be populated)
    /// * `request_method` - The HTTP method of the original request
    /// * `current_url` - The URL of the current request (for resolving relative redirects)
    /// * `redirect_count` - Number of redirects already followed
    ///
    /// # Returns
    /// A `SkipResponseResult` indicating what action the caller should take.
    pub fn handle(
        &self,
        response: &HttpResponse,
        request_method: HttpMethod,
        current_url: &Url,
        redirect_count: u32,
    ) -> Result<SkipResponseResult, Aria2Error> {
        // Consume the body through stream filters (discard output)
        self.consume_body(response)?;

        // Process the response status
        self.process_response(response, request_method, current_url, redirect_count)
    }

    /// Consume the response body using NullSinkFilter + encoding filters.
    ///
    /// Equivalent to the C++ body-consumption loop in `executeInternal()`.
    /// The body data is read, decoded (if chunked/content-encoded), and
    /// discarded via NullSinkFilter.
    fn consume_body(&self, response: &HttpResponse) -> Result<(), Aria2Error> {
        let content_encoding = response.header("Content-Encoding").map(|s| s.as_str());
        let transfer_encoding = response.header("Transfer-Encoding").map(|s| s.as_str());

        // Validate transfer framing before the empty-body fast path. An
        // unsupported declared transfer encoding is invalid even when the
        // peer sends no payload bytes.
        let mut filters = AutoFilterSelector::select_filters(content_encoding, transfer_encoding)?;

        // Framing has been validated, but there is no body to consume.
        if response.body.is_empty() {
            tracing::trace!("Empty response body, nothing to consume");
            return Ok(());
        }

        // Build decoding pipeline: encoding filters -> null sink
        filters.push(Box::new(NullSinkFilter::new()));

        // Process the entire body through the filter chain (data is discarded)
        let _ = process_filters(&mut filters, &response.body)?;

        tracing::debug!(
            "Consumed {} bytes of response body (discarded)",
            response.body.len()
        );
        Ok(())
    }

    /// Classify the HTTP response and determine the appropriate action.
    ///
    /// Mirrors C++ `HttpSkipResponseCommand::processResponse()`.
    fn process_response(
        &self,
        response: &HttpResponse,
        request_method: HttpMethod,
        current_url: &Url,
        redirect_count: u32,
    ) -> Result<SkipResponseResult, Aria2Error> {
        let status = response.status_code;

        // 3xx redirect handling
        if is_redirect_status(status) {
            return self.handle_redirect(response, request_method, current_url, redirect_count);
        }

        // 4xx/5xx error handling
        if status >= 400 {
            return Ok(self.handle_error_status(response, status));
        }

        // 1xx informational or 2xx success that ended up here — just consumed
        tracing::debug!("Response status {} consumed, no special action", status);
        Ok(SkipResponseResult::Consumed)
    }

    /// Handle 3xx redirect responses.
    ///
    /// Extracts the Location header, resolves it against the current URL,
    /// determines method change rules per RFC 7231, and checks redirect limits.
    ///
    /// # 300 Multiple Choices
    ///
    /// Per C++ aria2 and aria2-next, 300 is treated as a redirect when a
    /// Location header is present. If no Location header exists, it is
    /// treated as a fatal error (the server is offering a choice but not
    /// telling us which one to pick).
    fn handle_redirect(
        &self,
        response: &HttpResponse,
        request_method: HttpMethod,
        current_url: &Url,
        redirect_count: u32,
    ) -> Result<SkipResponseResult, Aria2Error> {
        // Check redirect count limit
        if redirect_count >= self.max_redirects {
            return Err(Aria2Error::Recoverable(
                RecoverableError::HttpTooManyRedirects {
                    count: redirect_count,
                },
            ));
        }

        // Extract Location header
        // For 300 Multiple Choices, Location may be absent → treat as error
        let location = response.location();
        let location = match location {
            Some(loc) => loc,
            None => {
                if response.status_code == 300 {
                    // 300 without Location: server is offering choices but
                    // not telling us which one. Treat as a fatal error.
                    tracing::warn!("300 Multiple Choices without Location header");
                    return Ok(SkipResponseResult::FatalError {
                        status_code: 300,
                        message: "Multiple choices without Location header".to_string(),
                    });
                }
                return Err(Aria2Error::Parse(
                    "Redirect response missing Location header".to_string(),
                ));
            }
        };

        // Resolve relative URLs against the current URL
        let target_url = current_url.join(location).map_err(|e| {
            Aria2Error::Parse(format!(
                "Failed to resolve redirect URL '{}': {}",
                location, e
            ))
        })?;

        // Determine redirect type and method change rules per RFC 7231
        let redirect_type = match response.status_code {
            300 | 301 => RedirectType::Permanent,
            303 => RedirectType::SeeOther,
            307 | 308 => RedirectType::PreserveMethod,
            _ => RedirectType::Temporary, // 302 and other 3xx
        };

        let change_method = redirect_type.should_change_method(request_method);
        let new_count = redirect_count + 1;

        tracing::info!(
            "HTTP redirect: {} -> {} (type={:?}, change_method={}, count={}/{})",
            current_url,
            target_url,
            redirect_type,
            change_method,
            new_count,
            self.max_redirects
        );

        Ok(SkipResponseResult::Redirect(HttpRedirectInfo {
            target_url,
            change_method,
            redirect_type,
            redirect_count: new_count,
        }))
    }

    /// Handle 4xx/5xx error status codes.
    ///
    /// Mirrors the C++ switch statement in `processResponse()` plus
    /// aria2-next enhancements:
    /// - 401: auth challenge (if enabled) or fatal
    /// - 407: proxy auth challenge
    /// - 404: retryable or fatal depending on max_file_not_found
    /// - 413: retryable when Retry-After header is present (aria2-next)
    /// - 502/503: retryable if retry_wait > 0, else fatal
    /// - 504: always retryable (gateway timeout)
    /// - other 4xx/5xx: fatal
    fn handle_error_status(&self, response: &HttpResponse, status: u16) -> SkipResponseResult {
        match status {
            401 => self.handle_auth_challenge(response, false),
            407 => self.handle_auth_challenge(response, true),
            404 => {
                if self.max_file_not_found == 0 {
                    SkipResponseResult::FatalError {
                        status_code: status,
                        message: "Resource not found".to_string(),
                    }
                } else {
                    SkipResponseResult::RetryableError {
                        status_code: status,
                        message: "Resource not found".to_string(),
                    }
                }
            }
            413 => {
                // Request Entity Too Large — retryable if server specifies
                // Retry-After, matching aria2-next behavior for "Payload Too
                // Large" with backoff. Without Retry-After, this is fatal.
                if response.header("Retry-After").is_some() {
                    tracing::info!("413 Request Entity Too Large with Retry-After, will retry");
                    SkipResponseResult::RetryableError {
                        status_code: status,
                        message: "Request entity too large, retrying after backoff".to_string(),
                    }
                } else {
                    SkipResponseResult::FatalError {
                        status_code: status,
                        message: "Request entity too large".to_string(),
                    }
                }
            }
            502 | 503 => {
                // Only retry if retry_wait > 0; hammering a busy server is not ideal
                if self.retry_wait_secs > 0 {
                    SkipResponseResult::RetryableError {
                        status_code: status,
                        message: format!("Server returned error: {}", status),
                    }
                } else {
                    SkipResponseResult::FatalError {
                        status_code: status,
                        message: format!("Server returned error: {}", status),
                    }
                }
            }
            504 => {
                // Gateway Timeout — always retryable
                SkipResponseResult::RetryableError {
                    status_code: status,
                    message: format!("Gateway timeout: {}", status),
                }
            }
            _ => SkipResponseResult::FatalError {
                status_code: status,
                message: format!("HTTP error: {}", status),
            },
        }
    }

    /// Parse authentication challenge from 401/407 response.
    fn handle_auth_challenge(&self, response: &HttpResponse, is_proxy: bool) -> SkipResponseResult {
        let header_name = if is_proxy {
            "Proxy-Authenticate"
        } else {
            "WWW-Authenticate"
        };

        let auth_header = response.header(header_name);

        match auth_header {
            Some(value) => {
                let scheme = AuthScheme::from_header(value);
                match scheme {
                    Some(AuthScheme::Digest) => {
                        let digest = DigestAuthChallenge::parse(value).ok();
                        let realm = digest.as_ref().map(|d| d.realm.clone()).unwrap_or_default();
                        SkipResponseResult::AuthChallenge(HttpAuthChallenge {
                            scheme: AuthScheme::Digest,
                            realm,
                            is_proxy,
                            digest_challenge: digest,
                        })
                    }
                    Some(scheme) => {
                        // Basic / Negotiate / NTLM — extract realm from header
                        let realm = Self::extract_realm(value);
                        SkipResponseResult::AuthChallenge(HttpAuthChallenge {
                            scheme,
                            realm,
                            is_proxy,
                            digest_challenge: None,
                        })
                    }
                    None => {
                        tracing::warn!("Unknown auth scheme in {} header: {}", header_name, value);
                        SkipResponseResult::FatalError {
                            status_code: if is_proxy { 407 } else { 401 },
                            message: "Authentication failed: unknown scheme".to_string(),
                        }
                    }
                }
            }
            None => {
                // No auth header — if auth challenge is enabled, this is retryable
                // (basic cred activation); otherwise fatal (matches C++ behavior)
                if self.http_auth_challenge_enabled && !is_proxy {
                    SkipResponseResult::AuthChallenge(HttpAuthChallenge {
                        scheme: AuthScheme::Basic,
                        realm: String::new(),
                        is_proxy: false,
                        digest_challenge: None,
                    })
                } else {
                    SkipResponseResult::FatalError {
                        status_code: if is_proxy { 407 } else { 401 },
                        message: "Authentication failed".to_string(),
                    }
                }
            }
        }
    }

    /// Extract the realm parameter from a WWW-Authenticate / Proxy-Authenticate header.
    pub(crate) fn extract_realm(header_value: &str) -> String {
        // Case-insensitive search for realm= while preserving original case for value
        let lower = header_value.to_lowercase();
        if let Some(idx) = lower.find("realm=") {
            let rest = &header_value[idx + 6..];
            let rest = rest.trim();
            if let Some(stripped) = rest.strip_prefix('"') {
                // Quoted value: find closing quote
                if let Some(end) = stripped.find('"') {
                    return stripped[..end].to_string();
                }
            } else {
                // Unquoted value — ends at whitespace or comma
                let end = rest
                    .find(|c: char| c.is_whitespace() || c == ',')
                    .unwrap_or(rest.len());
                return rest[..end].to_string();
            }
        }
        String::new()
    }
}