aria2-core 0.3.2

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
434
435
436
437
438
439
440
//! FTP feature negotiation and extended commands.
//!
//! Contains the `FtpFeatures` struct (parsed from FEAT response per RFC 2389)
//! and `FtpClient` methods for FEAT, CDUP, MKD, OPTS UTF8 ON, and AUTH TLS.

use tracing::{debug, info, warn};

use crate::error::Result;

use super::types::{FtpClient, FtpResponse};

// =============================================================================
// FtpFeatures - parsed from FEAT multi-line response (RFC 2389)
// =============================================================================

/// Parsed features from FEAT command response (RFC 2389).
///
/// Populated by `FtpClient::send_feat()` from the multi-line 211 response.
/// Each boolean flag indicates whether the server advertised that feature.
/// The `features` field holds raw feature strings for features not covered
/// by the explicit flags.
#[derive(Debug, Clone, Default)]
pub struct FtpFeatures {
    /// Server supports UTF8 path encoding (RFC 2640)
    pub utf8: bool,
    /// Server supports MLSD machine-readable directory listings (RFC 3659)
    pub mlsd: bool,
    /// Server supports MLST machine-readable file metadata (RFC 3659)
    pub mlst: bool,
    /// Server supports PRET (pre-transfer) command (distributed FTP)
    pub pret: bool,
    /// Server supports MFMT modification time command (RFC 3659)
    pub mfmt: bool,
    /// Server supports TVFS trivial virtual file store (RFC 3659)
    pub tvfs: bool,
    /// Server supports AUTH TLS (RFC 4217)
    pub auth_tls: bool,
    /// Server supports AUTH SSL
    pub auth_ssl: bool,
    /// Server supports EPSV extended passive mode (RFC 2428)
    pub epsv: bool,
    /// Server supports EPRT extended active mode (RFC 2428)
    pub eprt: bool,
    /// Server supports SIZE command (RFC 3659)
    pub size: bool,
    /// Server supports REST STREAM (stream-level resume, RFC 3659)
    pub rest_stem: bool,
    /// Raw feature strings not matched by the explicit flags above
    pub features: Vec<String>,
}

impl FtpFeatures {
    /// Parse the body of a 211 FEAT response into `FtpFeatures`.
    ///
    /// Per RFC 2389, each feature line is prefixed with a space.
    /// Lines without a leading space are not feature lines and are skipped.
    /// Feature keywords are case-insensitive.
    pub fn parse(body: &str) -> Self {
        let mut feat = Self::default();

        for line in body.lines() {
            // Feature lines start with a space per RFC 2389
            let feature = if line.starts_with(' ') {
                line.trim()
            } else {
                continue;
            };

            if feature.is_empty() {
                continue;
            }

            // Extract keyword: first token before whitespace or semicolon.
            // E.g. "MLST type*;size*;modify*;" -> keyword is "MLST"
            let keyword = feature
                .split(|c: char| c.is_whitespace() || c == ';')
                .next()
                .unwrap_or(feature)
                .trim();

            feat.apply_keyword(keyword, feature);
        }

        info!(
            "FEAT parsed: utf8={}, mlsd={}, mlst={}, pret={}, mfmt={}, tvfs={}, \
             auth_tls={}, auth_ssl={}, epsv={}, eprt={}, size={}, rest_stem={}",
            feat.utf8,
            feat.mlsd,
            feat.mlst,
            feat.pret,
            feat.mfmt,
            feat.tvfs,
            feat.auth_tls,
            feat.auth_ssl,
            feat.epsv,
            feat.eprt,
            feat.size,
            feat.rest_stem,
        );

        feat
    }

    /// Apply a single feature keyword to the capability set.
    fn apply_keyword(&mut self, keyword: &str, full_line: &str) {
        // Feature keywords are case-insensitive per RFC 2389
        match keyword.to_uppercase().as_str() {
            "UTF8" => {
                self.utf8 = true;
                debug!("FEAT: UTF8 support detected");
            }
            "MLSD" => {
                self.mlsd = true;
                debug!("FEAT: MLSD support detected");
            }
            "MLST" => {
                self.mlst = true;
                debug!("FEAT: MLST support detected");
            }
            "PRET" => {
                self.pret = true;
                debug!("FEAT: PRET support detected");
            }
            "MFMT" => {
                self.mfmt = true;
                debug!("FEAT: MFMT support detected");
            }
            "TVFS" => {
                self.tvfs = true;
                debug!("FEAT: TVFS support detected");
            }
            "AUTH" => {
                // AUTH TLS vs AUTH SSL: check the full line
                let upper = full_line.to_uppercase();
                if upper.contains("TLS") {
                    self.auth_tls = true;
                    debug!("FEAT: AUTH TLS support detected");
                }
                if upper.contains("SSL") {
                    self.auth_ssl = true;
                    debug!("FEAT: AUTH SSL support detected");
                }
                // If neither TLS nor SSL is mentioned, record as generic AUTH
                if !upper.contains("TLS") && !upper.contains("SSL") {
                    debug!(
                        "FEAT: AUTH support detected (type unspecified): {}",
                        full_line
                    );
                }
            }
            "EPSV" => {
                self.epsv = true;
                debug!("FEAT: EPSV support detected");
            }
            "EPRT" => {
                self.eprt = true;
                debug!("FEAT: EPRT support detected");
            }
            "SIZE" => {
                self.size = true;
                debug!("FEAT: SIZE support detected");
            }
            "REST" => {
                // REST STREAM, REST PIPE, etc.
                let upper = full_line.to_uppercase();
                if upper.contains("STREAM") {
                    self.rest_stem = true;
                    debug!("FEAT: REST STREAM support detected");
                } else {
                    debug!("FEAT: REST support detected (variant: {})", full_line);
                }
            }
            _ => {
                debug!("FEAT: unknown feature '{}'", keyword);
                self.features.push(full_line.to_string());
            }
        }
    }
}

// =============================================================================
// FtpClient command implementations
// =============================================================================

impl FtpClient {
    /// Send FEAT command and parse server feature list (RFC 2389).
    ///
    /// The server responds with a multi-line 211 reply listing supported
    /// features. If the server does not support FEAT (returns a non-211
    /// response), returns `Ok(FtpFeatures::default())`.
    ///
    /// The parsed features are also stored in `self.features` for later access.
    pub async fn send_feat(&mut self) -> Result<FtpFeatures> {
        debug!("Sending FEAT command");
        self.send_command("FEAT").await?;
        let resp = self.read_response().await?;

        if resp.code != 211 {
            info!(
                "FEAT not supported (response: {} {}), using defaults",
                resp.code, resp.message
            );
            let feat = FtpFeatures::default();
            self.features = Some(feat.clone());
            return Ok(feat);
        }

        let feat = FtpFeatures::parse(&resp.message);
        self.features = Some(feat.clone());
        Ok(feat)
    }

    /// Send CDUP command to change to the parent directory.
    ///
    /// Returns `Ok(FtpResponse)` on 200/250 success, or an error on failure.
    /// Non-fatal failures (e.g. already at root) may return a 5xx response
    /// which is still returned as `Ok` for the caller to decide.
    pub async fn send_cdup(&mut self) -> Result<FtpResponse> {
        debug!("Sending CDUP command");
        self.send_command("CDUP").await?;
        let resp = self.read_response().await?;

        if resp.is_positive_completion() {
            debug!("CDUP successful");
        } else {
            warn!("CDUP failed: {} {}", resp.code, resp.message);
        }

        Ok(resp)
    }

    /// Send MKD command to create a directory on the server.
    ///
    /// Returns the 257 response on success (directory created).
    /// Returns `RecoverableError::ServerError { code: 550 }` if the
    /// directory already exists or the path is unavailable.
    pub async fn send_mkd(&mut self, path: &str) -> Result<FtpResponse> {
        debug!("Sending MKD command for: {}", path);
        self.send_command(&format!("MKD {}", path)).await?;
        let resp = self.read_response().await?;

        if resp.code == 257 {
            debug!("MKD successful: {}", path);
        } else if resp.code == 550 {
            debug!("MKD returned 550 (directory may already exist): {}", path);
        } else {
            warn!("MKD failed for {}: {} {}", path, resp.code, resp.message);
        }

        Ok(resp)
    }

    /// Send OPTS UTF8 ON to enable UTF-8 path encoding (RFC 2640).
    ///
    /// Should be called after `send_feat()` indicates UTF8 support.
    /// A 200 response means the server accepted the option. A non-200
    /// response is not fatal; the method still returns `Ok(FtpResponse)`.
    pub async fn send_opts_utf8(&mut self) -> Result<FtpResponse> {
        debug!("Sending OPTS UTF8 ON");
        self.send_command("OPTS UTF8 ON").await?;
        let resp = self.read_response().await?;

        if resp.is_positive_completion() {
            info!("UTF-8 path encoding enabled (OPTS UTF8 ON accepted)");
        } else {
            warn!(
                "OPTS UTF8 ON rejected ({} {}), continuing with default encoding",
                resp.code, resp.message
            );
        }

        Ok(resp)
    }

    /// Send AUTH TLS to request TLS protection on the control connection.
    ///
    /// Per RFC 4217, a 234 response means the server is ready for TLS
    /// handshake. The caller is responsible for upgrading the connection
    /// to a TLS stream after receiving a 234 response.
    ///
    /// Returns `Ok(FtpResponse)` regardless of whether TLS was accepted;
    /// the caller should inspect `resp.code` to decide next steps.
    pub async fn send_auth_tls(&mut self) -> Result<FtpResponse> {
        debug!("Sending AUTH TLS command");
        self.send_command("AUTH TLS").await?;
        let resp = self.read_response().await?;

        match resp.code {
            234 => {
                info!("AUTH TLS accepted (234), connection ready for TLS upgrade");
            }
            _ => {
                info!(
                    "AUTH TLS not supported by server ({} {})",
                    resp.code, resp.message
                );
            }
        }

        Ok(resp)
    }

    /// Get the server features, if they have been queried via `send_feat()`.
    pub fn features(&self) -> Option<&FtpFeatures> {
        self.features.as_ref()
    }
}

// =============================================================================
// Unit tests
// =============================================================================

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_parse_feat_full() {
        let response = "\
211-Features:
 UTF8
 MLST type*;size*;modify*;
 MLSD
 SIZE
 MDTM
 EPSV
 EPRT
 TVFS
 PRET
 MFMT
 REST STREAM
 AUTH TLS
211 End";

        let feat = FtpFeatures::parse(response);

        assert!(feat.utf8);
        assert!(feat.mlst);
        assert!(feat.mlsd);
        assert!(feat.size);
        assert!(feat.epsv);
        assert!(feat.eprt);
        assert!(feat.tvfs);
        assert!(feat.pret);
        assert!(feat.mfmt);
        assert!(feat.rest_stem);
        assert!(feat.auth_tls);
        assert!(!feat.auth_ssl);
    }

    #[test]
    fn test_parse_feat_minimal() {
        let response = "\
211-Features:
 UTF8
211 End";

        let feat = FtpFeatures::parse(response);
        assert!(feat.utf8);
        assert!(!feat.mlsd);
        assert!(!feat.size);
    }

    #[test]
    fn test_parse_feat_empty() {
        let response = "211 End";
        let feat = FtpFeatures::parse(response);
        assert!(!feat.utf8);
        assert!(!feat.mlst);
    }

    #[test]
    fn test_parse_feat_case_insensitive() {
        let response = "\
211-Features:
 utf8
 Mlst type*;size*;
211 End";

        let feat = FtpFeatures::parse(response);
        assert!(feat.utf8);
        assert!(feat.mlst);
    }

    #[test]
    fn test_parse_feat_auth_ssl() {
        let response = "\
211-Features:
 AUTH SSL
211 End";

        let feat = FtpFeatures::parse(response);
        assert!(feat.auth_ssl);
        assert!(!feat.auth_tls);
    }

    #[test]
    fn test_parse_feat_rest_stream() {
        let response = "\
211-Features:
 REST STREAM
211 End";

        let feat = FtpFeatures::parse(response);
        assert!(feat.rest_stem);
    }

    #[test]
    fn test_parse_feat_unknown_features_collected() {
        let response = "\
211-Features:
 UTF8
 XCURSOR
 SOME_UNKNOWN_FEATURE
211 End";

        let feat = FtpFeatures::parse(response);
        assert!(feat.utf8);
        // Unknown features should be collected in the features vec
        assert_eq!(feat.features.len(), 2);
    }

    #[test]
    fn test_feat_default() {
        let feat = FtpFeatures::default();
        assert!(!feat.utf8);
        assert!(!feat.mlsd);
        assert!(!feat.mlst);
        assert!(!feat.pret);
        assert!(!feat.mfmt);
        assert!(!feat.tvfs);
        assert!(!feat.auth_tls);
        assert!(!feat.auth_ssl);
        assert!(!feat.epsv);
        assert!(!feat.eprt);
        assert!(!feat.size);
        assert!(!feat.rest_stem);
        assert!(feat.features.is_empty());
    }
}