aria2-core 0.3.5

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
use super::*;
use crate::filesystem::disk_adaptor::DirectDiskAdaptor;

#[test]
fn test_allocation_strategy_from_str() {
    assert_eq!(
        AllocationStrategy::from_str("none"),
        AllocationStrategy::None
    );
    assert_eq!(
        AllocationStrategy::from_str("prealloc"),
        AllocationStrategy::Prealloc
    );
    assert_eq!(
        AllocationStrategy::from_str("falloc"),
        AllocationStrategy::Falloc
    );
    assert_eq!(
        AllocationStrategy::from_str("trunc"),
        AllocationStrategy::Trunc
    );
    assert_eq!(
        AllocationStrategy::from_str("mmap"),
        AllocationStrategy::Mmap
    );
    assert_eq!(
        AllocationStrategy::from_str("invalid"),
        AllocationStrategy::None
    );
    assert_eq!(AllocationStrategy::from_str(""), AllocationStrategy::None);
}

#[tokio::test]
async fn test_preallocate_file_none() {
    let dir = tempfile::tempdir().unwrap();
    let path = dir.path().join("test_none.bin");
    preallocate_file(&path, 1024, "none", false).await.unwrap();
    assert!(!path.exists());
}

#[tokio::test]
async fn test_preallocate_file_trunc() {
    let dir = tempfile::tempdir().unwrap();
    let path = dir.path().join("test_trunc.bin");
    preallocate_file(&path, 4096, "trunc", false).await.unwrap();

    let metadata = tokio::fs::metadata(&path).await.unwrap();
    assert_eq!(metadata.len(), 4096);
}

#[tokio::test]
async fn test_preallocate_file_prealloc() {
    let dir = tempfile::tempdir().unwrap();
    let path = dir.path().join("test_prealloc.bin");
    preallocate_file(&path, 1024 * 1024, "prealloc", false)
        .await
        .unwrap();

    let metadata = tokio::fs::metadata(&path).await.unwrap();
    assert_eq!(metadata.len(), 1024 * 1024);
}

#[tokio::test]
async fn test_preallocate_file_prealloc_preserves_existing_prefix() {
    let dir = tempfile::tempdir().unwrap();
    let path = dir.path().join("test_prealloc_resume.bin");
    let prefix = b"resume data must survive native allocation";
    tokio::fs::write(&path, prefix).await.unwrap();

    preallocate_file(&path, 1024 * 1024, "prealloc", false)
        .await
        .unwrap();

    let content = tokio::fs::read(&path).await.unwrap();
    assert_eq!(&content[..prefix.len()], prefix);
    assert_eq!(content.len(), 1024 * 1024);
}

#[tokio::test]
async fn test_preallocate_zero_length() {
    let dir = tempfile::tempdir().unwrap();
    let path = dir.path().join("test_zero.bin");
    preallocate_file(&path, 0, "trunc", false).await.unwrap();
    assert!(!path.exists());
}

#[tokio::test]
async fn test_preallocate_creates_parent_dirs() {
    let dir = tempfile::tempdir().unwrap();
    let path = dir.path().join("sub1").join("sub2").join("test_nested.bin");
    preallocate_file(&path, 100, "trunc", false).await.unwrap();

    assert!(path.exists());
    let metadata = tokio::fs::metadata(&path).await.unwrap();
    assert_eq!(metadata.len(), 100);
}

#[tokio::test]
async fn test_get_available_space_returns_value() {
    let dir = tempfile::tempdir().unwrap();
    let space = get_available_space(dir.path()).await;
    assert!(space.is_ok());
    let val = space.unwrap();
    assert!(val > 0);
}

#[tokio::test]
async fn test_preallocate_overwrite_existing() {
    let dir = tempfile::tempdir().unwrap();
    let path = dir.path().join("test_overwrite.bin");

    tokio::fs::write(&path, b"original data").await.unwrap();
    preallocate_file(&path, 2048, "trunc", false).await.unwrap();

    let metadata = tokio::fs::metadata(&path).await.unwrap();
    assert_eq!(metadata.len(), 2048);
}

/// Test cross-platform file allocation with Prealloc strategy.
/// Verifies that Prealloc works on Windows, macOS, and Linux.
#[tokio::test]
async fn test_allocate_file_cross_platform_prealloc() {
    let dir = tempfile::tempdir().unwrap();
    let path = dir.path().join("test_alloc_prealloc.bin");

    // Create file with initial content
    tokio::fs::write(&path, b"hello").await.unwrap();

    // Allocate 10MB using Prealloc strategy
    preallocate_file(&path, 10 * 1024 * 1024, "prealloc", false)
        .await
        .unwrap();

    // Verify size is correct
    let metadata = tokio::fs::metadata(&path).await.unwrap();
    assert_eq!(metadata.len(), 10 * 1024 * 1024);
}

/// Test cross-platform file allocation with Falloc strategy.
/// Verifies that Falloc works on Windows (using set_len fallback) and Unix (using posix_fallocate).
#[tokio::test]
async fn test_allocate_file_cross_platform_falloc() {
    let dir = tempfile::tempdir().unwrap();
    let path = dir.path().join("test_alloc_falloc.bin");

    // Create file first
    tokio::fs::write(&path, b"initial data").await.unwrap();

    // Allocate 5MB using Falloc strategy
    preallocate_file(&path, 5 * 1024 * 1024, "falloc", false)
        .await
        .unwrap();

    // Verify size
    let metadata = tokio::fs::metadata(&path).await.unwrap();
    assert_eq!(metadata.len(), 5 * 1024 * 1024);
}

/// Test that the Falloc strategy produces a file of the correct logical size.
///
/// On Windows the file is sparse unless `SetFileValidData` succeeds (which
/// requires `SE_MANAGE_VOLUME_PRIVILEGE`, typically absent in test runs).
/// On Unix, `posix_fallocate`/`F_PREALLOCATE` allocate real blocks when
/// supported. This test only asserts the logical size, keeping it
/// cross-platform and independent of privilege state.
#[tokio::test]
async fn test_fallocate_creates_sparse_file_of_correct_size() {
    let dir = tempfile::tempdir().unwrap();
    let path = dir.path().join("test_falloc_sparse.bin");

    preallocate_file(&path, 1024 * 1024, "falloc", false)
        .await
        .unwrap();

    let metadata = tokio::fs::metadata(&path).await.unwrap();
    assert_eq!(metadata.len(), 1024 * 1024);
}

/// Test cross-platform file allocation with Trunc strategy.
/// Verifies that Trunc works identically on all platforms via set_len.
#[tokio::test]
async fn test_allocate_file_cross_platform_trunc() {
    let dir = tempfile::tempdir().unwrap();
    let path = dir.path().join("test_alloc_trunc.bin");

    // Create file with some data
    tokio::fs::write(&path, b"some initial content here")
        .await
        .unwrap();

    // Truncate to 1MB using Trunc strategy
    preallocate_file(&path, 1024 * 1024, "trunc", false)
        .await
        .unwrap();

    // Verify size
    let metadata = tokio::fs::metadata(&path).await.unwrap();
    assert_eq!(metadata.len(), 1024 * 1024);
}

/// Test None strategy does not create files.
#[tokio::test]
async fn test_allocate_file_cross_platform_none() {
    let dir = tempfile::tempdir().unwrap();
    let path = dir.path().join("test_alloc_none.bin");

    // Try to allocate with None strategy - should not create file
    preallocate_file(&path, 1024 * 1024, "none", false)
        .await
        .unwrap();

    // File should not exist
    assert!(!path.exists());
}

/// Test allocating a large file (50MB) to verify performance across platforms.
#[tokio::test]
async fn test_allocate_large_file() {
    let dir = tempfile::tempdir().unwrap();
    let path = dir.path().join("test_large_alloc.bin");

    // Allocate 50MB using falloc strategy
    preallocate_file(&path, 50 * 1024 * 1024, "falloc", false)
        .await
        .unwrap();

    // Verify size
    let metadata = tokio::fs::metadata(&path).await.unwrap();
    assert_eq!(metadata.len(), 50 * 1024 * 1024);

    // Verify we can write to the allocated space
    use tokio::io::{AsyncSeekExt, AsyncWriteExt};
    let mut file = tokio::fs::OpenOptions::new()
        .write(true)
        .open(&path)
        .await
        .unwrap();

    // Write at an offset near the end of the file
    file.seek(std::io::SeekFrom::Start(49 * 1024 * 1024))
        .await
        .unwrap();
    file.write_all(b"end marker").await.unwrap();
    file.flush().await.unwrap();
    drop(file);

    // Verify final size unchanged
    let metadata = tokio::fs::metadata(&path).await.unwrap();
    assert_eq!(metadata.len(), 50 * 1024 * 1024);
}

/// Test that all three allocation strategies produce same result.
#[tokio::test]
async fn test_all_strategies_same_result() {
    let dir = tempfile::tempdir().unwrap();
    let test_size: u64 = 1024 * 100; // 100KB

    let strategies = ["prealloc", "falloc", "trunc"];

    for (i, strategy) in strategies.iter().enumerate() {
        let path = dir.path().join(format!("test_strategy_{}.bin", i));

        preallocate_file(&path, test_size, strategy, false)
            .await
            .unwrap();

        let metadata = tokio::fs::metadata(&path).await.unwrap();
        assert_eq!(
            metadata.len(),
            test_size,
            "Strategy {} produced wrong size",
            strategy
        );
    }
}

/// Test progress callback is invoked for large file allocation (>=100MB).
#[tokio::test]
async fn test_preallocate_with_progress_callback() {
    use std::sync::{Arc, Mutex};

    let dir = tempfile::tempdir().unwrap();
    let path = dir.path().join("test_progress.bin");

    let progress_calls: Arc<Mutex<Vec<(u64, u64)>>> = Arc::new(Mutex::new(Vec::new()));
    let pc = progress_calls.clone();

    preallocate_file_with_progress(
        &path,
        150 * 1024 * 1024, // 150MB — exceeds 100MB threshold
        "prealloc",
        Some(&|allocated, total| {
            pc.lock().unwrap().push((allocated, total));
        }),
        false,
    )
    .await
    .unwrap();

    {
        // Lock scope - must be dropped before await below
        let calls = progress_calls.lock().unwrap();
        // Should have at least start(0) and end(total) calls
        assert!(
            calls.len() >= 2,
            "expected at least 2 progress calls, got {}",
            calls.len()
        );
        assert_eq!(calls.first().unwrap().0, 0); // Start: 0 bytes
        assert_eq!(
            calls.last().unwrap().0,
            150 * 1024 * 1024 // End: full size
        );
        assert_eq!(calls.last().unwrap().1, 150 * 1024 * 1024);
    } // lock dropped here

    // Verify file was actually created correctly
    let metadata = tokio::fs::metadata(&path).await.unwrap();
    assert_eq!(metadata.len(), 150 * 1024 * 1024);
}

/// Test small file does NOT trigger progress callback (<100MB).
#[tokio::test]
async fn test_preallocate_small_file_no_progress_callback() {
    use std::sync::{Arc, Mutex};

    let dir = tempfile::tempdir().unwrap();
    let path = dir.path().join("test_small_progress.bin");

    let progress_calls: Arc<Mutex<Vec<(u64, u64)>>> = Arc::new(Mutex::new(Vec::new()));
    let pc = progress_calls.clone();

    preallocate_file_with_progress(
        &path,
        1024, // 1KB — well under 100MB threshold
        "trunc",
        Some(&|allocated, total| {
            pc.lock().unwrap().push((allocated, total));
        }),
        false,
    )
    .await
    .unwrap();

    let calls = progress_calls.lock().unwrap();
    // Small files should NOT trigger callback
    assert!(
        calls.is_empty(),
        "small file should not trigger progress, got {} calls",
        calls.len()
    );
}

/// Verify the workspace default file allocation strategy matches aria2.
#[test]
fn test_default_allocation_is_prealloc() {
    use crate::constants;
    assert_eq!(constants::DEFAULT_FILE_ALLOCATION, "prealloc");
    assert_eq!(
        AllocationStrategy::from_str(constants::DEFAULT_FILE_ALLOCATION),
        AllocationStrategy::Prealloc
    );
}

/// Test that async_zero_fill produces a file of the correct size filled
/// with zeros.
#[tokio::test]
async fn test_async_zero_fill() {
    let dir = tempfile::tempdir().unwrap();
    let path = dir.path().join("test_zero_fill.bin");

    let mut adaptor = DirectDiskAdaptor::new();
    adaptor.open(&path).await.unwrap();
    adaptor.truncate(5 * 1024 * 1024).await.unwrap(); // 5 MiB
    strategies::async_zero_fill(&mut adaptor, 5 * 1024 * 1024)
        .await
        .unwrap();
    adaptor.close().await.unwrap();

    // Verify size
    let metadata = tokio::fs::metadata(&path).await.unwrap();
    assert_eq!(metadata.len(), 5 * 1024 * 1024);

    // Verify content is all zeros
    let content = tokio::fs::read(&path).await.unwrap();
    assert!(content.iter().all(|&b| b == 0), "File should be all zeros");
}

/// A resumed allocation clears only the newly extended region.
#[tokio::test]
async fn test_async_zero_fill_from_preserves_existing_prefix() {
    let dir = tempfile::tempdir().unwrap();
    let path = dir.path().join("test_zero_fill_resume.bin");

    let prefix = vec![0x5Au8; 4096];
    tokio::fs::write(&path, &prefix).await.unwrap();

    let mut adaptor = DirectDiskAdaptor::new();
    adaptor.open(&path).await.unwrap();
    adaptor.truncate(8192).await.unwrap();
    strategies::async_zero_fill_from(&mut adaptor, 4096, 8192)
        .await
        .unwrap();
    adaptor.close().await.unwrap();

    let content = tokio::fs::read(&path).await.unwrap();
    assert_eq!(&content[..prefix.len()], prefix.as_slice());
    assert!(content[4096..].iter().all(|&b| b == 0));
}

/// Test that secure_falloc option defaults to false in DownloadOptions.
#[test]
fn test_secure_falloc_default() {
    use crate::request::request_group::DownloadOptions;
    let opts = DownloadOptions::default();
    assert!(!opts.secure_falloc, "secure_falloc should default to false");
}