aria2-rpc 0.3.2

Remote control server for aria2-rust: aria2-compatible JSON-RPC 2.0, XML-RPC, and WebSocket download management
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
//! RPC Handler Utilities - Common helper functions and constants
//!
//! This module provides shared utilities for RPC handler implementations,
//! extracted from rpc_handlers.rs to improve modularity.
//!
//! # Features
//!
//! - Shared option value normalization
//! - Response formatting helpers
//! - Status filtering utilities
//!
//! # Architecture Reference
//!
//! Based on original aria2 C++ structure:
//! - `src/RpcMethodImpl.cc` - Shared utility functions

/// Decode the permissive Base64 stream used by aria2_original's wire
/// adapters. The original decoder skips bytes outside the Base64 alphabet and
/// returns an empty result for malformed padding or incomplete groups.
pub(crate) fn decode_aria2_base64(input: &str) -> Vec<u8> {
    use base64::Engine;

    let filtered: Vec<u8> = input
        .bytes()
        .filter(|byte| {
            matches!(
                byte,
                b'A'..=b'Z'
                    | b'a'..=b'z'
                    | b'0'..=b'9'
                    | b'+'
                    | b'/'
                    | b'='
            )
        })
        .collect();

    if filtered.is_empty() {
        return Vec::new();
    }

    let input = if let Some(eq_pos) = filtered.iter().position(|byte| *byte == b'=') {
        let group_start = eq_pos / 4 * 4;
        let group_end = group_start + 4;
        if group_end > filtered.len()
            || filtered[eq_pos..group_end].iter().any(|byte| *byte != b'=')
        {
            return Vec::new();
        }
        &filtered[..group_end]
    } else if filtered.len() % 4 == 1 {
        // The original decoder ignores one incomplete trailing alphabet byte.
        &filtered[..filtered.len() - 1]
    } else {
        &filtered
    };

    base64::engine::general_purpose::STANDARD
        .decode(input)
        .unwrap_or_default()
}

/// Percent-decode the small legacy GET query grammar without pulling the
/// transport parser into a domain crate.
pub(crate) fn percent_decode(input: &str) -> String {
    let bytes = input.as_bytes();
    let mut output = Vec::with_capacity(bytes.len());
    let mut index = 0;
    while index < bytes.len() {
        if bytes[index] == b'%'
            && index + 2 < bytes.len()
            && let (Some(high), Some(low)) =
                (hex_digit(bytes[index + 1]), hex_digit(bytes[index + 2]))
        {
            output.push((high << 4) | low);
            index += 3;
            continue;
        }
        output.push(bytes[index]);
        index += 1;
    }
    String::from_utf8_lossy(&output).into_owned()
}

fn hex_digit(value: u8) -> Option<u8> {
    match value {
        b'0'..=b'9' => Some(value - b'0'),
        b'a'..=b'f' => Some(value - b'a' + 10),
        b'A'..=b'F' => Some(value - b'A' + 10),
        _ => None,
    }
}

/// Normalize a map of RPC options to the string-valued map returned by aria2.
pub fn normalize_rpc_options(
    options: &std::collections::HashMap<String, serde_json::Value>,
) -> std::collections::HashMap<String, serde_json::Value> {
    options
        .iter()
        .filter_map(|(key, value)| {
            option_value_to_string(value)
                .map(|value| (key.clone(), serde_json::Value::String(value)))
        })
        .collect()
}

fn option_value_to_string(value: &serde_json::Value) -> Option<String> {
    match value {
        serde_json::Value::String(value) => Some(value.clone()),
        serde_json::Value::Number(value) => Some(value.to_string()),
        serde_json::Value::Bool(value) => Some(value.to_string()),
        serde_json::Value::Array(values) => values
            .iter()
            .map(option_value_to_string)
            .collect::<Option<Vec<_>>>()
            .map(|values| values.join("\n")),
        serde_json::Value::Null | serde_json::Value::Object(_) => None,
    }
}

// Preserve the existing helper path while keeping session identity creation
// in the SessionInfo domain type, which is the owner of its wire contract.
pub use crate::types::generate_session_id;

/// Build the same version response used by `aria2.getVersion`.
///
/// This forwarding helper preserves the public Rust utility without creating
/// a second wire shape beside [`crate::types::VersionInfo`].
pub fn build_version_info() -> serde_json::Value {
    crate::types::VersionInfo::from_env().to_json_value()
}

/// Fields that original aria2 keeps as native JSON numbers (not strings).
/// These are exceptions to the general rule that all numbers → strings.
const NATIVE_NUMERIC_FIELDS: &[&str] = &["creationDate"];

/// Post-process a JSON value to match original aria2 wire format.
///
/// Converts all numbers to strings and booleans to "true"/"false" strings,
/// except for fields listed in [`NATIVE_NUMERIC_FIELDS`].
pub fn to_aria2_wire_format(value: serde_json::Value) -> serde_json::Value {
    match value {
        serde_json::Value::Object(map) => {
            let mut new_map = serde_json::Map::with_capacity(map.len());
            for (k, v) in map {
                if NATIVE_NUMERIC_FIELDS.contains(&k.as_str()) {
                    new_map.insert(k, v);
                } else {
                    new_map.insert(k, to_aria2_wire_format(v));
                }
            }
            serde_json::Value::Object(new_map)
        }
        serde_json::Value::Array(arr) => {
            let new_arr: Vec<serde_json::Value> =
                arr.into_iter().map(to_aria2_wire_format).collect();
            serde_json::Value::Array(new_arr)
        }
        serde_json::Value::Number(n) => serde_json::Value::String(n.to_string()),
        serde_json::Value::Bool(b) => serde_json::Value::String(if b {
            "true".to_string()
        } else {
            "false".to_string()
        }),
        serde_json::Value::String(_) | serde_json::Value::Null => value,
    }
}

/// Split the aria2 RPC authorization token off a JSON-RPC parameter list.
///
/// Mirrors C++ aria2's `rpc::RpcMethod::authorize()` (`src/RpcMethod.cc`):
/// the first *positional* parameter is always treated as the secret token
/// when it is a string starting with `"token:"`, and it is popped from the
/// list so method handlers never see it and their positional argument
/// indices stay correct.
///
/// Object-style params (`{"token": "..."}`) are also recognised for
/// backward compatibility. Nothing is stripped in that case because
/// named-parameter handlers look their arguments up by name, so a stray
/// `token` key cannot shift any index.
///
/// # Returns
/// `(token, stripped_params)` where
/// * `token` — the secret with the `"token:"` prefix removed, if one was found.
/// * `stripped_params` — `Some(params)` only when the input actually had to be
///   rewritten. `None` means the caller can keep using the original params
///   without cloning them.
///
/// # Examples
/// ```
/// use aria2_rpc::rpc_helpers::split_auth_token;
///
/// let (token, stripped) = split_auth_token(&serde_json::json!(["token:s3cr3t", "gid1"]));
/// assert_eq!(token.as_deref(), Some("s3cr3t"));
/// assert_eq!(stripped, Some(serde_json::json!(["gid1"])));
///
/// // No token → nothing to rewrite.
/// let (token, stripped) = split_auth_token(&serde_json::json!(["gid1"]));
/// assert_eq!(token, None);
/// assert_eq!(stripped, None);
/// ```
pub fn split_auth_token(params: &serde_json::Value) -> (Option<String>, Option<serde_json::Value>) {
    match params {
        serde_json::Value::Array(arr) => {
            let token = arr
                .first()
                .and_then(|v| v.as_str())
                .and_then(|s| s.strip_prefix("token:"))
                .map(str::to_string);
            match token {
                Some(t) => {
                    let mut rest = arr.clone();
                    rest.remove(0);
                    (Some(t), Some(serde_json::Value::Array(rest)))
                }
                None => (None, None),
            }
        }
        other => (
            other
                .get("token")
                .and_then(|v| v.as_str())
                .map(str::to_string),
            None,
        ),
    }
}

/// Consume a parameter value while removing a leading `token:` entry.
///
/// Server-side parsers already own their request DOM. This variant preserves
/// the borrowed helper's wire semantics without cloning the whole positional
/// parameter array before dispatch.
pub(crate) fn split_auth_token_owned(
    params: serde_json::Value,
) -> (Option<String>, serde_json::Value) {
    match params {
        serde_json::Value::Array(mut arr) => {
            let token = arr
                .first()
                .and_then(|value| value.as_str())
                .and_then(|value| value.strip_prefix("token:"))
                .map(str::to_owned);
            if token.is_some() {
                arr.remove(0);
            }
            (token, serde_json::Value::Array(arr))
        }
        params => {
            let token = params
                .get("token")
                .and_then(|value| value.as_str())
                .map(str::to_owned);
            (token, params)
        }
    }
}

/// Format session summary for logging/display
///
/// Creates a human-readable summary of the current session state.
///
/// # Arguments
/// * `active_count` - Number of active downloads
/// * `waiting_count` - Number of waiting downloads
/// * `stopped_count` - Number of stopped downloads
///
/// # Returns
/// * Formatted summary string
pub fn format_session_summary(
    active_count: usize,
    waiting_count: usize,
    stopped_count: usize,
) -> String {
    format!(
        "Session Summary: {} active, {} waiting, {} stopped",
        active_count, waiting_count, stopped_count
    )
}

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

    #[test]
    fn test_build_version_info_structure() {
        let info = build_version_info();
        assert_eq!(info, crate::types::VersionInfo::from_env().to_json_value());
        assert!(info.get("version").is_some());
        assert!(info.get("enabledFeatures").is_some());
        assert!(info.get("session").is_none());
    }

    #[test]
    fn test_format_session_summary() {
        let summary = format_session_summary(5, 3, 2);
        assert!(summary.contains("5 active"));
        assert!(summary.contains("3 waiting"));
        assert!(summary.contains("2 stopped"));
    }

    #[test]
    fn test_to_aria2_wire_format_numbers() {
        let input = serde_json::json!({"a": 123, "b": 456});
        let output = to_aria2_wire_format(input);
        assert_eq!(output["a"].as_str(), Some("123"));
        assert_eq!(output["b"].as_str(), Some("456"));
    }

    #[test]
    fn test_to_aria2_wire_format_bools() {
        let input = serde_json::json!({"x": true, "y": false});
        let output = to_aria2_wire_format(input);
        assert_eq!(output["x"].as_str(), Some("true"));
        assert_eq!(output["y"].as_str(), Some("false"));
    }

    #[test]
    fn test_to_aria2_wire_format_native_numeric() {
        let input = serde_json::json!({"creationDate": 1700000000, "other": 42});
        let output = to_aria2_wire_format(input);
        assert!(
            output["creationDate"].is_number(),
            "creationDate should remain a number"
        );
        assert_eq!(output["other"].as_str(), Some("42"));
    }

    #[test]
    fn test_to_aria2_wire_format_bitfield() {
        let input = serde_json::json!({"bitfield": "ff00ff00"});
        let output = to_aria2_wire_format(input);
        assert_eq!(output["bitfield"].as_str(), Some("ff00ff00"));
    }

    #[test]
    fn test_to_aria2_wire_format_piece_fields() {
        let input = serde_json::json!({"pieceLength": 262144, "numPieces": 128});
        let output = to_aria2_wire_format(input);
        assert_eq!(output["pieceLength"].as_str(), Some("262144"));
        assert_eq!(output["numPieces"].as_str(), Some("128"));
    }

    #[test]
    fn test_to_aria2_wire_format_followed_by() {
        let input = serde_json::json!({"followedBy": ["gid-abc", "gid-def"]});
        let output = to_aria2_wire_format(input);
        assert_eq!(output["followedBy"][0].as_str(), Some("gid-abc"));
        assert_eq!(output["followedBy"][1].as_str(), Some("gid-def"));
    }

    #[test]
    fn test_to_aria2_wire_format_complete_status() {
        let input = serde_json::json!({
            "gid": "abc123",
            "totalLength": 1048576,
            "completedLength": 524288,
            "downloadSpeed": 1024000,
            "uploadSpeed": 512000,
            "uploadLength": 0,
            "connections": 4,
            "pieceLength": 16384,
            "numPieces": 64,
            "numSeeders": 2,
            "verifiedLength": 0,
            "verifyIntegrityPending": "false",
            "seeder": "false",
            "infoHash": "abcdef0123456789",
            "belongsTo": "parent-gid",
            "followedBy": ["child1", "child2"],
            "bitfield": "ffff0000",
            "dir": "/downloads",
            "files": [{"index": 1, "path": "/downloads/file.iso", "length": 1048576, "completedLength": 524288, "selected": "true", "uris": [{"uri": "http://example.com/file.iso", "status": "used"}]}]
        });
        let output = to_aria2_wire_format(input);

        // Numeric fields should be strings
        assert_eq!(output["totalLength"].as_str(), Some("1048576"));
        assert_eq!(output["completedLength"].as_str(), Some("524288"));
        assert_eq!(output["downloadSpeed"].as_str(), Some("1024000"));
        assert_eq!(output["uploadSpeed"].as_str(), Some("512000"));
        assert_eq!(output["pieceLength"].as_str(), Some("16384"));
        assert_eq!(output["numPieces"].as_str(), Some("64"));
        assert_eq!(output["numSeeders"].as_str(), Some("2"));

        // String fields should pass through
        assert_eq!(output["gid"].as_str(), Some("abc123"));
        assert_eq!(output["bitfield"].as_str(), Some("ffff0000"));
        assert_eq!(output["infoHash"].as_str(), Some("abcdef0123456789"));
        assert_eq!(output["belongsTo"].as_str(), Some("parent-gid"));
        assert_eq!(output["verifyIntegrityPending"].as_str(), Some("false"));
        assert_eq!(output["seeder"].as_str(), Some("false"));

        // Array passthrough
        assert_eq!(output["followedBy"][0].as_str(), Some("child1"));
        assert_eq!(output["followedBy"][1].as_str(), Some("child2"));

        // Nested objects
        let file = &output["files"][0];
        assert_eq!(file["path"].as_str(), Some("/downloads/file.iso"));
        let uri = &file["uris"][0];
        assert_eq!(uri["uri"].as_str(), Some("http://example.com/file.iso"));
        assert_eq!(uri["status"].as_str(), Some("used"));
    }
}