aria2-protocol 0.3.10

Multi-protocol networking stack for aria2-rust: HTTP/HTTPS client, FTP/SFTP, full BitTorrent (DHT/PEX/MSE), and Metalink V3/V4 parser
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
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
//! RFC 6265 helper functions for cookie domain/path matching and date parsing.

/// A syntactically parsed `Set-Cookie` header.
///
/// Attribute meaning and acceptance policy belong to the cookie jar. This
/// type preserves attributes in wire order while normalizing their names.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SetCookieHeader {
    pub name: String,
    pub value: String,
    pub attributes: Vec<SetCookieAttribute>,
}

/// One `Set-Cookie` attribute. Extension attributes are retained as well.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SetCookieAttribute {
    pub name: String,
    pub value: Option<String>,
}

/// A cookie pair parsed from a request `Cookie` field value.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CookiePair {
    pub name: String,
    pub value: String,
}

/// Parse the semicolon-separated cookie pairs in an HTTP `Cookie` field.
pub fn parse_cookie_header(header: &str) -> Vec<CookiePair> {
    header
        .split(';')
        .filter_map(|pair| {
            let (name, value) = pair.trim().split_once('=')?;
            let name = name.trim();
            (!name.is_empty()).then(|| CookiePair {
                name: name.to_owned(),
                value: value.trim().to_owned(),
            })
        })
        .collect()
}

/// Format selected cookie name/value pairs as an HTTP `Cookie` field value.
pub fn format_cookie_header<'a>(cookies: impl IntoIterator<Item = (&'a str, &'a str)>) -> String {
    let mut header = String::new();
    for (name, value) in cookies {
        if !header.is_empty() {
            header.push_str("; ");
        }
        header.push_str(name);
        header.push('=');
        header.push_str(value);
    }
    header
}

/// Format a `Set-Cookie` field value from its name, value, and ordered
/// attributes.
pub fn format_set_cookie_header<'a>(
    name: &str,
    value: &str,
    attributes: &[(&'a str, Option<&'a str>)],
) -> String {
    let mut header = format!("{name}={value}");
    for (attribute_name, attribute_value) in attributes {
        header.push_str("; ");
        header.push_str(attribute_name);
        if let Some(attribute_value) = attribute_value {
            header.push('=');
            header.push_str(attribute_value);
        }
    }
    header
}

/// Parse the wire syntax of a `Set-Cookie` field value.
///
/// This does not validate cookie names, domains, or attribute semantics.
pub fn parse_set_cookie_header(header: &str) -> Option<SetCookieHeader> {
    let header = header.trim();
    if header.is_empty() {
        return None;
    }

    let (name_value, attributes) = match header.split_once(';') {
        Some((name_value, attributes)) => (name_value, Some(attributes)),
        None => (header, None),
    };
    let name_value = name_value.trim();
    let (name, value) = name_value.split_once('=')?;
    let name = name.trim();
    if name.is_empty() {
        return None;
    }
    let mut value = value.trim();
    if value.len() >= 2 && value.starts_with('"') && value.ends_with('"') {
        value = &value[1..value.len() - 1];
    }

    let attributes = attributes
        .into_iter()
        .flat_map(|attributes| attributes.split(';'))
        .filter_map(|attribute| {
            let attribute = attribute.trim();
            if attribute.is_empty() {
                return None;
            }
            let (name, value) = match attribute.split_once('=') {
                Some((name, value)) => (name.trim(), Some(value.trim().to_owned())),
                None => (attribute, None),
            };
            (!name.is_empty()).then(|| SetCookieAttribute {
                name: name.to_ascii_lowercase(),
                value,
            })
        })
        .collect();

    Some(SetCookieHeader {
        name: name.to_owned(),
        value: value.to_owned(),
        attributes,
    })
}

/// Check whether `host` domain-matches `domain` per RFC 6265 Section 5.1.3.
///
/// A string domain-matches a given domain string if at least one of the
/// following conditions holds:
///
/// 1. The host string and the domain string are identical.
/// 2. All of the following conditions hold:
///    - The host string is a host name (not an IP)
///    - The domain string is a suffix of the host string
///    - The last character of the host that is not included in the domain string is a `.` character.
pub fn domain_matches(host: &str, domain: &str) -> bool {
    let h = host.to_lowercase();
    let d = domain.to_lowercase();

    if h == d {
        return true;
    }

    // Numeric hosts cannot receive domain-scoped cookies (per C++ aria2 behavior)
    if is_numeric_host(host) {
        return false;
    }

    // Host must end with "." + domain for subdomain matching
    h.ends_with(&format!(".{}", d))
}

/// Check whether `cookie_path` path-matches `request_path` per RFC 6265 Section 5.1.4.
///
/// A request-path path-matches a given cookie-path if:
/// 1. The cookie-path is identical to the request-path, OR
/// 2. The cookie-path is a prefix of the request-path, AND
///    the last character of the cookie-path is `/`, OR
///    the first character of the request-path that is not included in the
///    cookie-path is a `/` character.
pub fn path_matches(cookie_path: &str, request_path: &str) -> bool {
    // Identical paths always match
    if cookie_path == request_path {
        return true;
    }

    // Cookie path must be a prefix of request path
    if !request_path.starts_with(cookie_path) {
        return false;
    }

    // Cookie path ends with / -> match
    if cookie_path.ends_with('/') {
        return true;
    }

    // The first character of request_path not included in cookie_path must be /
    let remaining = &request_path[cookie_path.len()..];
    remaining.starts_with('/')
}

/// Compute the default cookie path for a request URI path per RFC 6265
/// Section 5.1.4.
pub fn default_path(request_uri_path: &str) -> String {
    if request_uri_path.is_empty() || !request_uri_path.starts_with('/') {
        return "/".to_owned();
    }
    let Some(last_slash) = request_uri_path.rfind('/') else {
        return "/".to_owned();
    };
    if last_slash == 0 {
        "/".to_owned()
    } else {
        request_uri_path[..last_slash].to_owned()
    }
}

/// Check whether a host string is a numeric IP address (IPv4 or IPv6).
///
/// Per C++ aria2 behavior, numeric hosts cannot receive domain-scoped cookies.
pub fn is_numeric_host(host: &str) -> bool {
    // IPv4: all characters are digits or dots
    let is_ipv4 = host.chars().all(|c| c.is_ascii_digit() || c == '.');
    if is_ipv4 && host.contains('.') {
        return true;
    }
    // IPv6: contains colons
    if host.contains(':') {
        return true;
    }
    false
}

/// Format a Unix epoch timestamp as an HTTP-date per RFC 7231 Section 7.1.1.1.
///
/// Example output: `"Wed, 09 Jun 2021 10:18:14 GMT"`
pub fn format_http_date(epoch: i64) -> String {
    const DAYS: [&str; 7] = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
    const MONTHS: [&str; 12] = [
        "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec",
    ];
    let days_since_epoch = epoch.div_euclid(86_400);
    let seconds = epoch.rem_euclid(86_400);
    let (y, m, day) = civil_from_days(days_since_epoch);
    let hour = seconds / 3_600;
    let min = (seconds % 3_600) / 60;
    let sec = seconds % 60;
    // 1970-01-01 was a Thursday; convert to the Sunday=0 convention.
    let dow = (days_since_epoch + 4).rem_euclid(7) as usize;
    format!(
        "{}, {:02} {} {:04} {:02}:{:02}:{:02} GMT",
        DAYS[dow],
        day,
        MONTHS[(m - 1) as usize],
        y,
        hour,
        min,
        sec
    )
}

/// Parse an HTTP-date string into a Unix epoch timestamp.
///
/// Implements the full RFC 6265 Section 5.1.1 date parsing algorithm,
/// matching the C++ `cookie_helper.cc::parseDate()` behavior:
/// 1. Split the date string into tokens by delimiter characters
///    (tab, space, and most punctuation)
/// 2. Identify the time token (HH:MM:SS), day-of-month token, month token,
///    and year token regardless of their position in the string
/// 3. Normalize 2-digit years per RFC 6265 (70-99 -> 1970-1999, 0-69 -> 2000-2069)
/// 4. Validate the date (day-of-month ranges, leap year, etc.)
/// 5. Convert to Unix epoch using UTC (equivalent to C++ timegm())
///
/// Returns `None` if the date string cannot be parsed.
pub fn parse_http_date(s: &str) -> Option<i64> {
    const MONTH_NAMES: [&str; 12] = [
        "jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec",
    ];

    // Step 1: Tokenize by delimiter characters per RFC 6265 Section 5.1.1.
    // Delimiters: 0x09, 0x20-0x2F, 0x3B-0x40, 0x5B-0x60, 0x7B-0x7E
    fn is_delimiter(c: u8) -> bool {
        c == 0x09
            || (0x20..=0x2F).contains(&c)
            || (0x3B..=0x40).contains(&c)
            || (0x5B..=0x60).contains(&c)
            || (0x7B..=0x7E).contains(&c)
    }

    let bytes = s.trim().as_bytes();
    let mut tokens: Vec<&str> = Vec::new();
    let mut i = 0;
    while i < bytes.len() {
        if is_delimiter(bytes[i]) {
            i += 1;
            continue;
        }
        let start = i;
        while i < bytes.len() && !is_delimiter(bytes[i]) {
            i += 1;
        }
        tokens.push(std::str::from_utf8(&bytes[start..i]).ok()?);
    }

    // Step 2: Identify time, day-of-month, month, and year tokens.
    let mut found_time = false;
    let mut hour: u32 = 0;
    let mut minute: u32 = 0;
    let mut second: u32 = 0;

    let mut found_day = false;
    let mut day_of_month: u32 = 0;

    let mut found_month = false;
    let mut month: u32 = 0; // 1-based

    let mut found_year = false;
    let mut year: u32 = 0;

    for token in &tokens {
        // Try to parse as time (HH:MM:SS)
        if !found_time && let Some((h, m, s)) = parse_time_token(token) {
            hour = h;
            minute = m;
            second = s;
            found_time = true;
            continue;
        }

        // Try to parse as day-of-month (1-2 digit number)
        if !found_day {
            let digits = leading_digits(token);
            if (1..=2).contains(&digits)
                && digits == token.len()
                && let Ok(d) = token.parse::<u32>()
            {
                day_of_month = d;
                found_day = true;
                continue;
            }
        }

        // Try to parse as month name (case-insensitive, at least 3 chars)
        if !found_month && token.len() >= 3 {
            let lower = token.to_lowercase();
            for (idx, &name) in MONTH_NAMES.iter().enumerate() {
                if lower.starts_with(name) {
                    month = (idx + 1) as u32;
                    found_month = true;
                    break;
                }
            }
            if found_month {
                continue;
            }
        }

        // Try to parse as year (1-4 digit number)
        if !found_year {
            let digits = leading_digits(token);
            if (1..=4).contains(&digits)
                && digits == token.len()
                && let Ok(y) = token.parse::<u32>()
            {
                year = y;
                found_year = true;
                continue;
            }
        }
    }

    // Step 3: Normalize 2-digit years per RFC 6265 Section 5.1.1
    if (70..=99).contains(&year) {
        year += 1900;
    } else if year <= 69 {
        year += 2000;
    }

    // Step 4: Validate the date
    if !found_time || !found_day || !found_month || !found_year {
        return None;
    }
    if !(1..=31).contains(&day_of_month) || year < 1601 || hour > 23 || minute > 59 || second > 59 {
        return None;
    }
    // Validate day-of-month against month
    let max_day = match month {
        4 | 6 | 9 | 11 => 30,
        2 => {
            let is_leap =
                (year.is_multiple_of(4) && !year.is_multiple_of(100)) || year.is_multiple_of(400);
            if is_leap { 29 } else { 28 }
        }
        1 | 3 | 5 | 7 | 8 | 10 | 12 => 31,
        _ => return None,
    };
    if day_of_month > max_day {
        return None;
    }

    // Step 5: Convert to Unix epoch timestamp (equivalent to C++ timegm())
    let total_days = days_since_epoch(year, month, day_of_month);
    Some(total_days * 86400 + hour as i64 * 3600 + minute as i64 * 60 + second as i64)
}

/// Parse a time token in HH:MM:SS format.
/// Returns (hour, minute, second) if valid, None otherwise.
fn parse_time_token(token: &str) -> Option<(u32, u32, u32)> {
    let parts: Vec<&str> = token.split(':').collect();
    if parts.len() != 3 {
        return None;
    }
    // Each component must be 1-2 digits
    for p in &parts {
        let digits = leading_digits(p);
        if digits == 0 || digits > 2 || digits != p.len() {
            return None;
        }
    }
    let h: u32 = parts[0].parse().ok()?;
    let m: u32 = parts[1].parse().ok()?;
    let s: u32 = parts[2].parse().ok()?;
    Some((h, m, s))
}

/// Count leading ASCII digits in a string.
fn leading_digits(s: &str) -> usize {
    s.bytes().take_while(|c| c.is_ascii_digit()).count()
}

/// Calculate the number of days since Unix epoch (1970-01-01 UTC) for a given date.
/// Equivalent to C++ timegm() for date conversion.
fn days_since_epoch(year: u32, month: u32, day: u32) -> i64 {
    let y = year as i64 - if month <= 2 { 1 } else { 0 };
    let era = if y >= 0 { y / 400 } else { (y - 399) / 400 };
    let year_of_era = y - era * 400;
    let month_from_march = month as i64 + if month > 2 { -3 } else { 9 };
    let day_of_year = (153 * month_from_march + 2) / 5 + day as i64 - 1;
    let day_of_era = year_of_era * 365 + year_of_era / 4 - year_of_era / 100 + day_of_year;
    era * 146_097 + day_of_era - 719_468
}

/// Convert days since 1970-01-01 to a proleptic Gregorian civil date.
fn civil_from_days(days: i64) -> (i64, u32, u32) {
    let z = days + 719_468;
    let era = if z >= 0 {
        z / 146_097
    } else {
        (z - 146_096) / 146_097
    };
    let day_of_era = z - era * 146_097;
    let year_of_era =
        (day_of_era - day_of_era / 1_460 + day_of_era / 36_524 - day_of_era / 146_096) / 365;
    let year = year_of_era + era * 400;
    let day_of_year = day_of_era - (365 * year_of_era + year_of_era / 4 - year_of_era / 100);
    let month_from_march = (5 * day_of_year + 2) / 153;
    let day = day_of_year - (153 * month_from_march + 2) / 5 + 1;
    let month = month_from_march + if month_from_march < 10 { 3 } else { -9 };
    let year = year + if month <= 2 { 1 } else { 0 };
    (year, month as u32, day as u32)
}

#[cfg(test)]
mod tests {
    use super::{
        default_path, domain_matches, format_cookie_header, format_http_date,
        format_set_cookie_header, parse_cookie_header, parse_http_date, parse_set_cookie_header,
        path_matches,
    };

    #[test]
    fn parses_set_cookie_wire_fields_and_preserves_attribute_order() {
        let cookie = parse_set_cookie_header(
            " SID = \"abc=123\" ; Domain=.Example.test; Secure; SameSite=Lax; Extension=one=two ",
        )
        .unwrap();
        assert_eq!(cookie.name, "SID");
        assert_eq!(cookie.value, "abc=123");
        assert_eq!(
            cookie.attributes,
            vec![
                super::SetCookieAttribute {
                    name: "domain".to_owned(),
                    value: Some(".Example.test".to_owned()),
                },
                super::SetCookieAttribute {
                    name: "secure".to_owned(),
                    value: None,
                },
                super::SetCookieAttribute {
                    name: "samesite".to_owned(),
                    value: Some("Lax".to_owned()),
                },
                super::SetCookieAttribute {
                    name: "extension".to_owned(),
                    value: Some("one=two".to_owned()),
                },
            ]
        );
    }

    #[test]
    fn parses_bare_set_cookie_and_rejects_missing_name_or_value_separator() {
        assert_eq!(
            parse_set_cookie_header("SID=abc"),
            Some(super::SetCookieHeader {
                name: "SID".to_owned(),
                value: "abc".to_owned(),
                attributes: vec![],
            })
        );
        assert!(parse_set_cookie_header("").is_none());
        assert!(parse_set_cookie_header("missing-separator").is_none());
        assert!(parse_set_cookie_header("=value").is_none());
    }

    #[test]
    fn parses_request_cookie_pairs_and_skips_malformed_entries() {
        assert_eq!(
            parse_cookie_header(" a=1; malformed; token = value=tail; =empty; b=2 "),
            vec![
                super::CookiePair {
                    name: "a".to_owned(),
                    value: "1".to_owned(),
                },
                super::CookiePair {
                    name: "token".to_owned(),
                    value: "value=tail".to_owned(),
                },
                super::CookiePair {
                    name: "b".to_owned(),
                    value: "2".to_owned(),
                },
            ]
        );
    }

    #[test]
    fn formats_request_cookie_pairs() {
        assert_eq!(format_cookie_header([]), "");
        assert_eq!(
            format_cookie_header([("sid", "abc"), ("theme", "dark")]),
            "sid=abc; theme=dark"
        );
    }

    #[test]
    fn formats_set_cookie_attributes_in_order() {
        assert_eq!(
            format_set_cookie_header(
                "sid",
                "abc",
                &[("Path", Some("/")), ("Secure", None), ("HttpOnly", None)],
            ),
            "sid=abc; Path=/; Secure; HttpOnly"
        );
    }

    #[test]
    fn parses_cookie_and_http_date_forms() {
        assert_eq!(
            parse_http_date("Wed, 09 Jun 2021 10:18:14 GMT"),
            Some(1_623_233_894)
        );
        assert_eq!(parse_http_date("06-Nov-94 08:49:37 GMT"), Some(784_111_777));
        assert_eq!(parse_http_date("not a date"), None);
    }

    #[test]
    fn formats_http_date_and_matches_cookie_scopes() {
        assert_eq!(
            format_http_date(1_623_233_894),
            "Wed, 09 Jun 2021 10:18:14 GMT"
        );
        assert!(domain_matches("download.example.test", "example.test"));
        assert!(path_matches("/files", "/files/item.bin"));
        assert!(!path_matches("/files", "/files-other/item.bin"));
    }

    #[test]
    fn computes_default_cookie_paths() {
        assert_eq!(default_path(""), "/");
        assert_eq!(default_path("relative/path"), "/");
        assert_eq!(default_path("/"), "/");
        assert_eq!(default_path("/file.bin"), "/");
        assert_eq!(default_path("/a/b"), "/a");
        assert_eq!(default_path("/a/b/"), "/a/b");
    }
}