aria2-core 0.3.14

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
//! HTTP Cookie implementation per RFC 6265 and RFC 6265bis.
//!
//! Provides cookie parsing, domain/path matching, and serialization.
//! The `from_set_cookie_header()` method validates the cookie's domain
//! against the request host to prevent cross-domain cookie injection.
//! SameSite attribute support follows RFC 6265bis Section 5.4.7.

pub mod netscape;
pub mod parsing;
pub mod storage;

#[cfg(test)]
mod tests;

#[cfg(test)]
mod tests_date;

#[cfg(test)]
mod tests_samesite;

#[cfg(test)]
mod tests_storage;

#[cfg(test)]
mod tests_storage_eviction;

use std::fmt;
use std::time::{SystemTime, UNIX_EPOCH};

use tracing::warn;

use parsing::{domain_matches, is_numeric_host, now_secs, parse_http_date};

pub use storage::{CookieStorage, DOMAIN_EVICTION_RATE, DOMAIN_EVICTION_TRIGGER};

/// Maximum number of cookies per domain (matches C++ aria2 `MAX_COOKIE_PER_DOMAIN`).
pub const MAX_COOKIE_PER_DOMAIN: usize = 50;

/// SameSite attribute per RFC 6265bis Section 5.4.7.
///
/// Controls whether a cookie is sent with cross-site requests.
/// Absent SameSite attribute defaults to `SameSite::None` for compatibility
/// with C++ aria2 behavior (newer browsers treat absent as Lax).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, serde::Serialize, serde::Deserialize)]
pub enum SameSite {
    /// No SameSite attribute specified — cookie is sent in all contexts.
    #[default]
    None,
    /// SameSite=Lax — cookie is sent on top-level navigations.
    Lax,
    /// SameSite=Strict — cookie is only sent in same-site context.
    Strict,
}

impl fmt::Display for SameSite {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            SameSite::None => write!(f, "None"),
            SameSite::Lax => write!(f, "Lax"),
            SameSite::Strict => write!(f, "Strict"),
        }
    }
}

#[derive(Debug, Clone)]
pub struct Cookie {
    pub name: String,
    pub value: String,
    pub domain: String,
    pub path: String,
    pub expiry_time: i64,
    pub creation_time: i64,
    pub last_access_time: i64,
    pub persistent: bool,
    pub host_only: bool,
    pub secure: bool,
    pub http_only: bool,
    pub same_site: SameSite,
}

impl Cookie {
    pub fn new(name: &str, value: &str, domain: &str) -> Self {
        let now = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .unwrap_or_default()
            .as_secs() as i64;
        Self {
            name: name.to_string(),
            value: value.to_string(),
            domain: domain.to_string(),
            path: "/".to_string(),
            expiry_time: 0,
            creation_time: now,
            last_access_time: now,
            persistent: false,
            host_only: true,
            secure: false,
            http_only: false,
            same_site: SameSite::default(),
        }
    }

    /// Check whether this cookie should be sent with a request to `host:path`.
    ///
    /// Per RFC 6265 Section 5.4 and RFC 6265bis Section 5.4.7:
    /// - Secure cookies only over HTTPS
    /// - Domain must match (exact for host-only, subdomain for domain cookies)
    /// - Path must be a prefix match per RFC 6265 Section 5.1.4
    /// - Expired persistent cookies are excluded
    /// - SameSite enforcement per RFC 6265bis Section 5.4.7:
    ///   - `Strict`: only sent in same-site context (`is_cross_site` must be false)
    ///   - `Lax`: sent on top-level navigations (always allowed for download managers)
    ///   - `!None`: sent in all contexts (Secure flag is enforced at parse time)
    ///
    /// # Arguments
    ///
    /// * `host` - The request hostname
    /// * `path` - The request path
    /// * `date` - Current time as Unix epoch seconds
    /// * `secure` - Whether the request uses HTTPS
    /// * `is_cross_site` - Whether the request is cross-site (different registrable domain)
    pub fn match_request(
        &self,
        host: &str,
        path: &str,
        date: i64,
        secure: bool,
        is_cross_site: bool,
    ) -> bool {
        if self.secure && !secure {
            return false;
        }
        if self.persistent && self.is_expired(date) {
            return false;
        }
        if !self.domain_matches(host) {
            return false;
        }
        if !self.path_matches(path) {
            return false;
        }

        // SameSite enforcement per RFC 6265bis Section 5.4.7
        match self.same_site {
            SameSite::Strict => {
                // Strict cookies are only sent in same-site context
                if is_cross_site {
                    return false;
                }
            }
            SameSite::Lax => {
                // Lax cookies are sent on top-level navigations.
                // For a download manager, all requests are considered user-initiated
                // (top-level), so Lax cookies are always allowed regardless of
                // is_cross_site. This matches browser behavior for top-level GETs.
            }
            SameSite::None => {
                // None cookies are sent in all contexts (including cross-site).
                // Per C++ aria2 compatibility, absent SameSite defaults to None.
                // Modern browsers require SameSite=None cookies to have Secure,
                // but we follow C++ behavior for backward compatibility.
            }
        }

        true
    }

    pub fn is_expired(&self, base_time: i64) -> bool {
        if !self.persistent {
            return false;
        }
        self.expiry_time < base_time
    }

    /// Whether this cookie has immediately expired (Max-Age ≤ 0 or past expiry).
    /// Such cookies should be deleted from storage rather than stored.
    pub fn is_delete_cookie(&self) -> bool {
        self.persistent && self.expiry_time <= now_secs()
    }

    pub fn to_set_cookie_header(&self) -> String {
        let expires = (self.persistent && self.expiry_time > 0)
            .then(|| aria2_protocol::http::cookie::parsing::format_http_date(self.expiry_time));
        let same_site = (self.same_site != SameSite::None).then(|| self.same_site.to_string());
        let mut attributes = Vec::with_capacity(6);
        if let Some(expires) = expires.as_deref() {
            attributes.push(("Expires", Some(expires)));
        }
        if !self.domain.is_empty() {
            attributes.push(("Domain", Some(self.domain.as_str())));
        }
        if self.path != "/" {
            attributes.push(("Path", Some(self.path.as_str())));
        }
        if self.secure {
            attributes.push(("Secure", None));
        }
        if self.http_only {
            attributes.push(("HttpOnly", None));
        }
        // Output SameSite only when it differs from the default (None).
        // This avoids adding SameSite=None to cookies that never specified it.
        if let Some(same_site) = same_site.as_deref() {
            attributes.push(("SameSite", Some(same_site)));
        }
        aria2_protocol::http::cookie::parsing::format_set_cookie_header(
            &self.name,
            &self.value,
            &attributes,
        )
    }

    /// Parse a `Set-Cookie` header value into a `Cookie`.
    ///
    /// Per RFC 6265 Section 5.3, the cookie's domain is validated against
    /// `request_host` to prevent cross-domain cookie injection. If the
    /// domain attribute does not domain-match the request host, the cookie
    /// is rejected (returns `None`).
    ///
    /// # Arguments
    ///
    /// * `header` - The raw Set-Cookie header value
    /// * `request_host` - The hostname of the HTTP request (for domain validation)
    /// * `default_path` - The default path computed from the request URI per RFC 6265 Section 5.1.4
    ///
    /// # Domain Validation Rules
    ///
    /// - If no `Domain` attribute → host-only cookie, domain = request_host
    /// - If `Domain` attribute present → strip leading dot, then check that
    ///   the domain domain-matches the request host (per RFC 6265 Section 5.1.3).
    ///   If not, the cookie is rejected.
    /// - Numeric IP hosts always force host-only mode (no subdomain matching).
    pub fn from_set_cookie_header(
        header: &str,
        request_host: &str,
        default_path: &str,
    ) -> Option<Self> {
        let parsed = aria2_protocol::http::cookie::parsing::parse_set_cookie_header(header)?;
        let mut cookie = Self::new(&parsed.name, &parsed.value, request_host);
        cookie.path = default_path.to_string();

        // Whether the Domain attribute was explicitly provided
        let mut domain_attr_provided = false;

        for attr in parsed.attributes {
            if attr.value.is_none() && !matches!(attr.name.as_str(), "secure" | "httponly") {
                continue;
            }
            match attr.name.as_str() {
                "domain" => {
                    let domain_val = attr.value.as_deref().unwrap_or_default();
                    // Strip leading dot per RFC 6265 Section 5.2.3
                    let domain_val = domain_val.trim_start_matches('.');
                    if domain_val.is_empty() {
                        // Empty domain after stripping → reject
                        warn!("Set-Cookie with empty Domain attribute, rejecting");
                        return None;
                    }
                    cookie.domain = domain_val.to_string();
                    domain_attr_provided = true;
                }
                "path" => {
                    let path_val = attr.value.as_deref().unwrap_or_default();
                    // Path must start with / per RFC 6265 Section 5.2.4
                    if path_val.starts_with('/') {
                        cookie.path = path_val.to_string();
                    } else {
                        // If path doesn't start with /, ignore it and use default
                        warn!(
                            path = path_val,
                            "Set-Cookie Path doesn't start with /, using default"
                        );
                    }
                }
                "max-age" => {
                    let value = attr.value.as_deref().unwrap_or_default();
                    if let Ok(secs) = value.parse::<i64>() {
                        if secs <= 0 {
                            // Max-Age ≤ 0 → cookie should be deleted immediately
                            cookie.expiry_time = 0;
                            cookie.persistent = true;
                        } else {
                            cookie.expiry_time = now_secs() + secs;
                            cookie.persistent = true;
                        }
                    } else {
                        // Non-numeric Max-Age → reject the cookie per C++ behavior
                        warn!(value, "Non-numeric Max-Age, rejecting cookie");
                        return None;
                    }
                }
                "expires" => {
                    let value = attr.value.as_deref().unwrap_or_default();
                    // Max-Age takes precedence over Expires per RFC 6265 Section 5.3
                    if !cookie.persistent
                        && let Some(ep) = parse_http_date(value)
                    {
                        cookie.expiry_time = ep;
                        cookie.persistent = true;
                    }
                    // If Expires is unparseable, C++ rejects the cookie.
                    // We are more lenient: we just ignore the Expires attribute.
                }
                "samesite" => {
                    let value = attr.value.as_deref().unwrap_or_default();
                    // SameSite attribute per RFC 6265bis Section 5.4.7
                    // Value is case-insensitive
                    match value.to_lowercase().as_str() {
                        "strict" => cookie.same_site = SameSite::Strict,
                        "lax" => cookie.same_site = SameSite::Lax,
                        "none" => cookie.same_site = SameSite::None,
                        _ => {
                            // Per RFC 6265bis: unknown SameSite value MUST be ignored
                            // (cookie stays at default SameSite::None)
                            warn!(value, "Unknown SameSite value, ignoring attribute");
                        }
                    }
                }
                "secure" if attr.value.is_none() => cookie.secure = true,
                "httponly" if attr.value.is_none() => cookie.http_only = true,
                _ => {}
            }
        }

        // Domain validation per RFC 6265 Section 5.3 step 6-9
        // Follows C++ aria2 cookie_helper.cc parse() behavior:
        //   if cookieDomain empty    → hostOnly = true, domain = requestHost
        //   if domainMatch(host, dom) → hostOnly = isNumericHost(host)
        //   else                      → reject cookie
        if domain_attr_provided {
            // Validate that the cookie's domain domain-matches the request host
            if !domain_matches(request_host, &cookie.domain) {
                warn!(
                    cookie_domain = %cookie.domain,
                    request_host = %request_host,
                    "Cookie domain does not match request host, rejecting"
                );
                return None;
            }
            // Per C++ behavior: numeric hosts always force host-only mode
            // even when the domain matches exactly
            cookie.host_only = is_numeric_host(request_host);
        } else {
            // No Domain attribute → host-only cookie
            cookie.host_only = true;
            cookie.domain = request_host.to_string();
        }

        Some(cookie)
    }

    /// Check whether this cookie's domain matches the given host.
    ///
    /// For host-only cookies, the domain must exactly match the host (case-insensitive).
    /// For domain cookies, the host must either equal the domain or be
    /// a subdomain of it (per RFC 6265 Section 5.1.3).
    fn domain_matches(&self, host: &str) -> bool {
        if self.host_only {
            // Host-only cookies require exact domain match (case-insensitive)
            self.domain.eq_ignore_ascii_case(host)
        } else {
            // Domain cookies allow subdomain matching
            domain_matches(host, &self.domain)
        }
    }

    /// Check whether this cookie's path matches the given request path.
    ///
    /// Per RFC 6265 Section 5.1.4:
    /// - The cookie path is a prefix of the request path, AND
    /// - Either the cookie path ends with `/`, OR the character in the
    ///   request path immediately after the cookie path is `/`.
    fn path_matches(&self, request_path: &str) -> bool {
        parsing::path_matches(&self.path, request_path)
    }

    /// Compute the default path from a request URI per RFC 6265 Section 5.1.4.
    ///
    /// Algorithm:
    /// 1. If the URI path is empty or does not start with `/`, return `/`
    /// 2. If the URI path contains no more than one `/`, return `/`
    /// 3. Otherwise, return the characters up to (but not including) the right-most `/`
    pub fn default_path(request_uri_path: &str) -> String {
        aria2_protocol::http::cookie::parsing::default_path(request_uri_path)
    }

    /// Returns the maximum number of cookies allowed per domain.
    /// Matches C++ aria2's `MAX_COOKIE_PER_DOMAIN = 50`.
    pub fn max_cookie_per_domain() -> usize {
        MAX_COOKIE_PER_DOMAIN
    }
}

impl PartialEq for Cookie {
    fn eq(&self, other: &Self) -> bool {
        self.name == other.name && self.domain == other.domain && self.path == other.path
    }
}

impl fmt::Display for Cookie {
    /// Format as `name=value`, matching C++ `Cookie::toString()`.
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}={}", self.name, self.value)
    }
}