aria2-protocol 0.3.8

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
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
# aria2_rust

中文:[`README_CN.md`](README_CN.md)

> **Version Notice:** aria2-rust is currently in a period of rapid iteration.
> It is far from production-ready. Features may be incomplete, unstable, or
> unusable, and functionality is not guaranteed. Do not rely on it for
> production workloads or important data.

<p align="center">
  <img src="https://img.shields.io/badge/STATUS-IN%20DEVELOPMENT-red?style=for-the-badge" alt="In development — not production ready" />
</p>

## Documentation

Start with the [documentation index](docs/README-en.md). The main user paths are:

- [Quick Start]docs/quickstart-en.md
- [Configuration Guide]docs/configuration-guide-en.md
- [RPC Guide]docs/rpc-guide-en.md
- [TUI Guide]docs/tui-guide-en.md
- [Release Artifacts]docs/release-artifacts-en.md
- [Troubleshooting]docs/troubleshooting-en.md

<p align="center">
  <strong>The ultra-fast download utility — rewritten in Rust</strong>
</p>

<p align="center">
  <a href="#features">Features</a> •
  <a href="#quick-start">Quick Start</a> •
  <a href="#usage">Usage</a> •
  <a href="#architecture">Architecture</a> •
  <a href="#performance">Performance</a> •
  <a href="#building">Building</a> •
  <a href="#license">License</a>
</p>

---

**aria2_rust** is an independent Rust download engine. It provides practical
compatibility with the [aria2](https://aria2.github.io/) ecosystem so existing
users and tools can migrate easily, while its architecture, safety,
performance, and product direction are its own. The default build supports
HTTP/HTTPS, FTP, BitTorrent, and JSON-RPC/XML-RPC/WebSocket paths;
Metalink and SFTP require their Cargo features;
compatibility status and verification evidence are tracked in
[docs/compatibility-status.md](docs/compatibility-status.md).

## GUI Companion

[Phosona Manager](https://github.com/balovess/Phosona_Manager) is a
cross-platform GUI download tool highly based on `aria2_rust`. Its desktop
application, installers, and GUI releases will be published in the
[Phosona_Manager repository](https://github.com/balovess/Phosona_Manager),
while this repository remains the home for the Rust engine, protocol crates,
and RPC services.

Phosona Manager will also ship a new P2P network model focused on sharing and
incentive mechanisms, inspired by BitTorrent, eMule, and similar systems.

Binary releases are available in four feature tiers; see the
[release artifact guide](docs/release-artifacts-en.md) to choose between
`minimal`, `standard`, `tui`, and `full`.

## Implemented Capabilities

The capability inventory below describes code paths, not a claim that every
feature has passed the complete cross-platform E2E matrix. See the
[compatibility status](docs/compatibility-status.md) for the current gate.

- **Multi-Protocol Download**: HTTP/HTTPS, FTP, and BitTorrent by default; SFTP and Metalink are feature-gated
- **Multi-Source Mirrors**: Automatic segmented parallel downloads from multiple URIs for maximum bandwidth utilization
- **Resume Support**: Checkpoint-based resume for the main download paths; protocol-specific compatibility is tracked in the matrix
- **BitTorrent**:
  - ✅ DHT network (KRPC + routing table + bootstrap)
  - ✅ Tracker communication (UDP/HTTP), with a periodically refreshed public tracker catalog
  - ✅ Peer Exchange (PEX, per-peer BEP 10 extension-ID negotiation)
  - ✅ MSE/PE encryption (BEP14 handshake)
  - ✅ Choking algorithms + seed-time/ratio support
  - ✅ RarestFirst piece selection
  - ✅ uTP protocol (BEP 29) - Not in original aria2 C++
  - ✅ Web Seeds (BEP 19)
  - ✅ LPD (Local Peer Discovery)
  - ✅ Complete seeding mode with upload support
- **Rate Limiting**: Token bucket algorithm with per-task/global limits
- **Cookie Management**: Netscape format persistence + auto-loading from files
- **Session Management**: Auto-save + manual save/load with .aria2 control files
- **RPC Remote Control**: JSON-RPC 2.0, XML-RPC, and WebSocket; the method and notification sets depend on enabled features (up to 42 methods and 6 notifications)
- **Configuration System**: Typed option registry with four-source merging (CLI/file/environment/defaults)
- **NetRC Authentication**: Automatic FTP/HTTP credential loading from `.netrc` files
- **URI List Files**: Batch import download tasks via `-i` parameter
- **Public Tracker List**: Enabled by default; refreshes `https://cf.trackerslist.com/best.txt` every 24 hours and appends deduplicated trackers to active BT tasks

## Quick Start

### Install a Release

Prebuilt artifacts are published on the [GitHub Releases](https://github.com/balovess/aria2_rust/releases) page. Each platform has `minimal`, `standard`, `tui`, and `full` variants with matching SHA-256 files. See the [release artifact guide](docs/release-artifacts-en.md) before choosing a variant.

### One-Line Installation

**Linux / macOS:**
```bash
curl -fsSL https://raw.githubusercontent.com/balovess/aria2_rust/main/install.sh | bash
```

**Windows (PowerShell):**
```powershell
irm https://raw.githubusercontent.com/balovess/aria2_rust/main/install.ps1 | iex
```

**Docker (Linux amd64 image):**
```bash
docker run -d --name aria2 -p 127.0.0.1:6800:6800 -v ~/downloads:/downloads ghcr.io/balovess/aria2-rust:latest
```

The RPC endpoint is unauthenticated unless `rpc-secret` is configured. This
example publishes it only on the host's loopback interface; configure
authentication and firewall rules before publishing it on other interfaces.

**Package Managers:**

| Platform | Command |
|----------|---------|
| Homebrew (macOS/Linux) | `brew tap balovess/aria2_rust https://github.com/balovess/aria2_rust.git && brew install balovess/aria2_rust/aria2-rust` |
| Scoop (Windows x64) | `scoop bucket add aria2 https://github.com/balovess/aria2_rust.git && scoop install aria2/aria2-rust` |
| Cargo (from source) | `cargo install --path aria2` |

The Homebrew formula builds the full feature set from the tagged source archive
and works on supported macOS and Linux Intel/ARM hosts. The Scoop manifest
installs the verified Windows x64 full release package and exposes it as
`aria2c`. After the one-time tap/bucket setup, standard update commands work:

```bash
brew update && brew upgrade aria2-rust
```

```powershell
scoop update
scoop update aria2-rust
```

Chocolatey is not a supported installation channel. Use the GitHub Release ZIP,
the PowerShell installer, or Scoop on Windows.

### First Download

After installation, start downloading immediately:

```bash
# Download a file
aria2c http://example.com/file.zip

# Download with multiple connections
aria2c -x 16 -s 16 http://example.com/large.iso

# Download a torrent
aria2c file.torrent

# Download with custom directory
aria2c -d ~/downloads http://example.com/file.zip
```

### Initialize Persistent Paths

Run `aria2c --init` to choose system, current-directory, executable-directory,
portable, or custom storage. Existing configuration is backed up before reset.
Use `--non-interactive` with an explicit profile in automation:

```bash
aria2c --init
aria2c --init --profile=system --non-interactive
aria2c --init --profile=custom --state-dir="$HOME/.aria2" --download-dir="$HOME/Downloads" --non-interactive
aria2c --show-paths --profile=system
```

The generated configuration is intentionally minimal. Session, logging, PID,
cookies, DHT state, and server statistics are enabled only by explicit options.

### Build from Source

<details>
<summary>Click to expand build instructions</summary>

**Prerequisites:**
- [Rust]https://www.rust-lang.org/tools/install 1.99+ (stable)
- Windows / macOS / Linux

**Build Commands:**
```bash
# Clone the repository
git clone https://github.com/balovess/aria2_rust.git
cd aria2_rust

# Build all crates
cargo build --release

# Download a file (HTTP)
cargo run --release -- http://example.com/file.zip

# Download with custom options
cargo run --release -- -d ./downloads -s 4 http://example.com/large.iso

# Show help
cargo run --release -- --help

# Show version
cargo run --release -- --version
```

</details>

## Usage

### Configuration Templates

We provide ready-to-use configuration templates in `examples/configs/`:

| Template | Description |
|----------|-------------|
| [minimal.conf]examples/configs/minimal.conf | Minimal configuration for quick setup |
| [basic.conf]examples/configs/basic.conf | Basic configuration with common options |
| [advanced.conf]examples/configs/advanced.conf | Advanced configuration with RPC, proxy, etc. |
| [bittorrent.conf]examples/configs/bittorrent.conf | Optimized for BitTorrent downloads |
| [windows.conf]examples/configs/windows.conf | Windows manual configuration template |

**Usage:**
```bash
# Copy template to config directory
mkdir -p ~/.aria2
cp examples/configs/basic.conf ~/.aria2/aria2.conf

# Edit as needed
nano ~/.aria2/aria2.conf

# Run with configuration
aria2c --conf-path=~/.aria2/aria2.conf http://example.com/file.zip
```

For common commands, configuration syntax, RPC/daemon setup, sessions, and
configuration check/repair/reset workflows, see the
[user guide](docs/user-guide.md).

### Basic HTTP Download

```bash
aria2c http://example.com/file.zip
```

### With Options

```bash
aria2c -o output.dat -d /downloads -s 4 -x 8 http://example.com/large.bin
```

| Option | Description | Default |
|--------|-------------|---------|
| `-d, --dir` | Save directory | `.` |
| `-o, --out` | Output filename | auto |
| `-s, --split` | Concurrent segment requests per download | `16` |
| `-x, --max-connection-per-server` | Per-authority HTTP segment request cap; adaptive download may lower it | `16` |
| `--max-download-limit` | Max download speed | unlimited |
| `--timeout` | Timeout in seconds | `60` |
| `-q, --quiet` | Quiet mode | false |

For segmented HTTP downloads, `split` is the total concurrent request budget
for one file. `max-connection-per-server` is the independent cap for each
`scheme://host:port` authority. With multiple mirrors, different authorities
may run concurrently within the `split` budget; mirrors sharing one authority
share that authority's cap. HTTP adaptive concurrency starts at the configured
cap and lowers only the authority that returns `429` or `503`.
### BitTorrent Download

```bash
aria2c file.torrent
```

### URI List File

Create a text file with URIs (one entry per block, Tab-separated mirrors):

```
  dir=/downloads
  split=16
http://mirror1.example.com/file.iso	http://mirror2.example.com/file.iso
http://mirror3.example.com/file.iso
```

Then:

```bash
aria2c -i uris.txt
```

## Architecture

The workspace contains four Rust crates plus Python and Node.js bindings.
Test status is reported from reproducible commands in
[docs/compatibility-status.md](docs/compatibility-status.md), rather than as
a fixed historical test count.

Migration status (2026-09-14): the Rust implementation migration is
substantially complete and is now in the final compatibility and acceptance
phase. The latest reproducible verification covers the CLI, RPC, protocol,
BitTorrent, Metalink, FTP/SFTP, Node.js, and Python paths; see the
[compatibility status](docs/compatibility-status.md) for commands and evidence.
The latest focused snapshot includes 3,733 passing `aria2-core` library tests
(1 ignored), 866 passing `aria2-protocol` tests (1 ignored), 319 passing
`aria2-rpc` tests, and 379 passing `aria2` tests (3 ignored), plus 123 Node.js
and 137 Python binding tests.

Remaining work is primarily compatibility evidence and release hardening:
complete original-client and browser-extension interoperability, public C ABI
parity, live cross-platform protocol/binding coverage, a few Metalink and
pause/remove lifecycle edges, and a comparable aria2 C++ performance baseline.
These do not represent a missing core protocol implementation; they remain
explicit acceptance boundaries in the compatibility matrix.

The project is organized as a Cargo workspace with 4 crates:

```
aria2-rust/
├── aria2/                  # Binary crate (CLI entry point, ~550 lines)
│   ├── src/main.rs        #   Entry point
│   ├── src/app.rs         #   App runtime (ConfigManager + Engine)
│   └── examples/          #   Usage examples
├── aria2-core/             # Download engine and shared application policies
│   ├── src/engine/
│   │   ├── http/          # HTTP/HTTPS command, probing, and transfer pipeline
│   │   ├── ftp/           # FTP/FTPS task command and transfer lifecycle
│   │   ├── sftp/          # SFTP task command and transfer lifecycle
│   │   ├── bittorrent/    # Torrent, peer, and magnet commands
│   │   ├── metalink/      # Metadata expansion into payload requests
│   │   ├── task_spawner.rs # Selects a protocol command for each request
│   │   ├── command.rs     # Shared command interface
│   │   └── engine_loop/   # Command scheduling and completion lifecycle
│   ├── src/config/        #   Typed configuration registry and parser
│   │   ├── option.rs     #     OptionType/Value/Def/Registry
│   │   ├── parser.rs     #     Multi-source parser (CLI/file/env/defaults)
│   │   ├── netrc.rs      #     NetRC authentication parser
│   │   ├── uri_list.rs  #     URI list file (-i option) parser
│   │   └── mod.rs        #     ConfigManager unified runtime manager
│   ├── src/request/       #   Request management
│   │   ├── request_group_man.rs # Global task manager
│   │   └── request_group/      # Per-task state machine and activity signals
│   │       └── activity.rs     # Notify + generation wake-up signal
│   ├── src/filesystem/     #   Disk I/O
│   │   ├── disk_writer.rs # Disk writer trait
│   │   ├── disk_cache.rs # Cached writer (256KB direct write)
│   │   ├── control_file.rs # .aria2 control file format
│   │   ├── file_allocation.rs # Pre-allocation strategies
│   │   └── checksum.rs # Checksum verification
│   ├── src/http/          #   Cookie management
│   │   ├── cookie.rs # Cookie structure
│   │   ├── cookie_storage.rs # Persistent storage
│   │   └── ns_cookie_parser.rs # Netscape format parser
│   ├── src/session/       #   Session persistence
│   │   ├── session_serializer.rs # Serialization
│   │   ├── auto_save_coordinator.rs # Unified persistence deadlines
│   │   ├── auto_save_session.rs # Auto-save
│   │   └── save_session_command.rs # Save on exit
│   ├── src/rate_limiter.rs # Token bucket rate limiting
│   └── src/ui.rs           #   Progress bar & status panel
├── aria2-protocol/         # Reusable protocol implementations
│   └── src/
│       ├── http/          # HTTP/HTTPS client primitives
│       ├── ftp/           # FTP/FTPS control, data, and TLS primitives
│       ├── sftp/          # SSH/SFTP connection, packets, sessions, and files
│       ├── bittorrent/    # Bencode, torrent, peer, DHT, and tracker protocols
│       ├── metalink/      # Metalink V3/V4 parsing
│       └── identity.rs    # Shared TLS identity setup
├── aria2-rpc/              # RPC server (~1,000 lines)
│   ├── src/json_rpc.rs     #   JSON-RPC 2.0 codec
│   ├── src/xml_rpc.rs      #   XML-RPC codec
│   ├── src/websocket.rs    #   WebSocket event publisher
│   ├── src/server.rs       #   HTTP server (auth/CORS/status)
│   └── src/engine.rs       #   RpcEngine bridge (feature-gated RPC methods)
└── bindings/               # Language bindings (~1,200 lines)
    ├── python/            #   Python SDK (~600 lines)
    └── nodejs/            #   Node.js SDK (~627 lines TS)
└── Cargo.toml              # Workspace configuration
```

## Performance

The implementation-oriented comparison with `aria2_original` is maintained in
[Performance Differentiators](docs/performance-differentiators.md). The current
Rust-specific differences are:

| Area | Current implementation |
| --- | --- |
| Disk I/O | Slow disk operations run in the background so synchronous reads and writes do not stall network tasks. Storage speed can still limit overall download speed. |
| Data path | `bytes::Bytes` is transferred through the cache, Piece writer, and multi-file slices to reduce copies and temporary allocations. This is a reduced-copy path, not an end-to-end zero-copy guarantee. |
| Hash verification | File and piece checks run in the background to reduce their impact on download tasks. |
| BitTorrent/DHT | Hash-based peer lifecycle, incremental piece-frequency tracking, shared HAVE frame encoding with bounded concurrent sends, bucket-tree/top-K routing, and bounded UDP workers. |
| File allocation | Platform-aware Linux `fallocate`, Windows `SetFileValidData`, macOS `F_PREALLOCATE`, and cooperative fallbacks that keep long allocation work off the reactor. |
| RPC control plane | Owned wire parsing, up to 64 concurrent read-only calls in HTTP/WebSocket batches, mutation barriers, and blocking workers for heavy payload conversion. `system.multicall` keeps original sequential semantics. |

### Current Version Compared with Original

The following data comes from a Release build and idle-RPC process measurement on the same Windows 11 x64 machine:

| Metric | Original aria2 1.37.0 | Current aria2-rust reference |
| --- | ---: | ---: |
| `aria2c.exe` file size | about 5.39 MiB | about 13.6 MiB |
| Idle RPC Working Set | about 12.5 MiB | about 16.1 MiB |
| Idle RPC Private Bytes | about 3.25 MiB | about 3.6 MiB |

These values vary with compiler features, Windows version, allocator, and measurement timing. They are not a substitute for a same-load download benchmark. Private Bytes are already close to the original, while the current binary size and Working Set remain higher.

The same document records compatibility impact, source entry points, focused test
evidence, and known boundaries. DHT network maintenance and active peer
lookups now use the unified task queue, with duplicate periodic network ticks
coalesced while a lane is busy. Token rotation and local cleanup remain in the
deadline coordinator, while routing-table saves use a blocking worker. Linux
and macOS runtime evidence and a comparable full-download workload benchmark
against `aria2_original` are still pending.

Existing event-driven hot paths include:

- uTP receive waits on Tokio UDP readiness and retains fragmented frames in a
  persistent buffer instead of retrying `recv` after a fixed sleep.
- BitTorrent piece downloads use a bounded event-driven block pipeline;
  endgame peers are consumed concurrently and TCP/MSE readers preserve partial
  frames across cancellation.
- Dynamic rate-limit changes wake blocked token acquisitions immediately.
- Piece-stat and missing-piece queries scan bitfields bytewise; unrestricted
  rarest-first selection advances a sorted cursor instead of rescanning pieces.
- The engine idle path waits on commands, task completions, the earliest
  maintenance deadline, and shutdown instead of scanning on a fixed idle tick.

Implementation seams: [engine idle wait](aria2-core/src/engine/engine_loop.rs),
[activity signal](aria2-core/src/request/request_group/activity.rs),
[save deadlines](aria2-core/src/session/auto_save_coordinator.rs), and
[platform process wait](aria2-core/src/engine/process_wait.rs).

Rust-only Criterion measurements on Windows release builds (`50,000` pieces,
same-worktree before/after medians) show the following algorithm-level changes:

| Benchmark | Before | After |
| --- | ---: | ---: |
| Bitfield all-missing query | 63.4 us | 4.3 us |
| Bitfield sparse selection | 194.9 us | 75.0 us |
| Rarest selection | 54.96 us | 2.13 us |

These are microbenchmark results, not a whole-download throughput claim or a
comparison with `aria2_original`. Details and validation commands are recorded
in [docs/MIGRATION.md](docs/MIGRATION.md) and
[docs/engine-loop-performance.md](docs/engine-loop-performance.md).

### Download Responsiveness

Disk writes and integrity checks run in the background so synchronous I/O or
hashing does not stall network tasks. The worker queue is bounded; if storage
falls behind, download tasks still wait and overall speed remains limited by
the device. The current write benchmark does not include a real network
download, so it does not establish higher download throughput.

To reproduce the focused benchmarks:

```bash
cargo bench -p aria2-core --features bittorrent --bench segment_scan_bench -- --noplot
cargo bench -p aria2-core --features bittorrent --bench sequential_picker_bench -- rarest_selection --noplot
```

## Library Usage

### As a library in your Rust project

Add to your `Cargo.toml`:

```toml
[dependencies]
aria2-core = { path = "../aria2-core" }
aria2-rpc = { path = "../aria2-rpc" }
```

#### Minimal download example

```rust
use aria2_core::config::ConfigManager;
use aria2_core::request::request_group_man::RequestGroupMan;
use aria2_core::request::request_group::DownloadOptions;
use aria2_core::config::OptionValue;

#[tokio::main]
async fn main() {
    let mut config = ConfigManager::new();
    config.set_global_option("dir", OptionValue::Str("./downloads".into())).await.unwrap();
    config.set_global_option("split", OptionValue::Int(4)).await.unwrap();

    let man = RequestGroupMan::new();
    let opts = DownloadOptions {
        split: Some(4),
        ..Default::default()
    };

    match man.add_group(vec!["http://example.com/file.zip".into()], opts).await {
        Ok(gid) => println!("Download started: #{}", gid.value()),
        Err(e) => eprintln!("Error: {}", e),
    }
}
```

#### RPC server example

```rust
use aria2_rpc::engine::RpcEngine;
use aria2_rpc::json_rpc::JsonRpcRequest;

#[tokio::main]
async fn main() {
    let engine = RpcEngine::new();

    let req = JsonRpcRequest {
        version: Some("2.0".into()),
        method: "aria2.addUri".into(),
        params: serde_json::json!([["http://example.com/file.zip"]]),
        id: Some(serde_json::Value::String("req-1".into())),
    };

    let resp = engine.handle_request(&req).await;
    println!("{}", serde_json::to_string_pretty(&resp).unwrap());
}
```

## Building from Source

### Requirements

- **Rust**: 1.99 or later ([install]https://rustup.rs/)
- **OS**: Windows 10+, macOS 10.15+, Linux (glibc 2.17+)

### Build Commands

```bash
# Debug build (fast compilation)
cargo build

# Release build (optimized)
cargo build --release

# Run tests
cargo test --workspace

# Generate documentation
cargo doc --workspace --no-deps

# Run a specific example
cargo run -p aria2 --example simple_download -- http://example.com/test.bin
```

## Testing

### Running Tests

```bash
# Run all tests in workspace
cargo test --workspace

# Run tests for specific crate
cargo test -p aria2-core

# Run tests with verbose output
cargo test --workspace -- --nocapture

# Run specific test category
cargo test "test_e2e"      # E2E tests
cargo test "test_stress"   # Stress tests
cargo test "test_edge"     # Edge case tests
cargo test "test_error"    # Error path tests
```

### Test Categories

| Category | Prefix | Description |
|----------|--------|-------------|
| Unit Tests | `test_` | Inline tests for individual functions |
| Integration Tests | `test_` | Module interaction tests |
| E2E Tests | `test_e2e_` | Complete workflow tests |
| Stress Tests | `test_stress_` | High-load stability tests |
| Edge Case Tests | `test_edge_` | Boundary condition tests |
| Error Path Tests | `test_error_` | Error handling tests |

### Coverage Report

```bash
# Install cargo-tarpaulin (Linux/macOS)
cargo install cargo-tarpaulin

# Generate HTML coverage report
cargo tarpaulin --workspace --out Html --output-dir coverage/

# Generate LCOV format for CI
cargo tarpaulin --workspace --out Lcov --output-dir coverage/
```

### Running Benchmarks

```bash
# Run all benchmarks
cargo bench --workspace

# Run specific benchmark
cargo bench -p aria2-core --bench config_bench
```

For comprehensive testing guidance, see [docs/testing-guide.md](docs/testing-guide.md).

## Compatibility with Original aria2

The table below records implemented code paths and their remaining acceptance
boundaries. The authoritative status is the module matrix in
[docs/compatibility-status.md](docs/compatibility-status.md); an implemented
path can still be `PARTIAL` or `UNVERIFIED` when external interoperability or
cross-platform evidence is incomplete.

| Feature | Path state | Notes |
|---------|--------|-------|
| CLI arguments | Implemented path | ~50 most-used options; full option parity is still open |
| Configuration file (`aria2.conf`) | Implemented path | Same syntax path; defaults and changeability still need comparison |
| Environment variables | Implemented path | `ARIA2_*` prefix mapping; full parity is still open |
| JSON-RPC API | Implemented path | Feature-dependent method set (up to 42 methods) returned by `system.listMethods`; BT metadata, tracker runtime state, DHT runtime counters, and manual DHT maintenance are available |
| XML-RPC API | Implemented path | MethodCall/response/fault paths exist; original-client matrix remains open |
| WebSocket events | Implemented path | 6 notifications returned by `system.listNotifications` |
| URI list file (`-i`) | Implemented path | Mirror + inline options |
| NetRC auth | Implemented path | machine/default/macdef parsing |
| Session save/load | Implemented path | Round-trip tests exist; complete control-file parity remains open |
| Metalink V3/V4 | Implemented path | Parsing and downloads exist; torrent metaurl lifecycle is partial |
| BitTorrent DHT | Implemented path | KRPC + routing table + bootstrap; live interoperability remains open |
| FTP/SFTP | Implemented path | Passive mode + auth; live-server evidence remains open |
| Rate limiting | Implemented path | Shared token bucket and runtime updates are tested |
| Cookie management | Implemented path | Netscape and SQLite parsing paths exist |
| MSE/PE encryption | Implemented path | BEP14 handshake |
| Magnet link support | Implemented path | ut_metadata fetching |
| RarestFirst piece | Implemented path | Piece selection implementation and tests |
| Endgame mode | Implemented path | Last-piece optimization |
| DHT persistence | Implemented path | `dht.dat` serialization |
| uTP Protocol | Extension path | Not in original aria2 C++ |
| Web Seeds | Implemented path | BEP 19 |
| LPD | Implemented path | Local Peer Discovery |
| Seeding Mode | Implemented path | Upload support |

**Known gaps and verification status:**
- This table is a capability inventory, not a release compatibility claim.
- The implementation migration is substantially complete; optional-feature
  evidence, ignored network tests, platform-specific binding runs,
  original-client interoperability, and public C ABI parity remain tracked.
- `aria2.forceShutdown`, `system.listMethods`, and `system.listNotifications` are implemented and covered by handler/integration tests.
- HTTPS RPC has TLS configuration, server implementation, and dedicated test coverage; broader client/server interoperability testing remains tracked.
- IPv6 DHT has CLI and protocol support; full network interoperability coverage remains tracked.
- BitTorrent RPC exposes torrent metadata, tracker tiers/runtime state, files, URIs, servers, peers, piece progress, and aggregated DHT counters. Tracker and DHT values are published from the active BT command and are removed when that command exits; peer discovery attribution is retained internally and is not added to the upstream `getPeers` wire response.
- Additional CLI/runtime option behavior still requires systematic comparison against `aria2_original`.

## License

This project is licensed under **GPL-3.0-or-later**.

Copyright (C) 2024 aria2-rust contributors.

## Acknowledgments

- [aria2]https://aria2.github.io/ — The original C++ download utility that inspired this project
- [Tokio]https://tokio.rs/ — Async runtime for Rust
- [Reqwest]https://docs.rs/reqwest/ — HTTP client foundation
- [Axum]https://docs.rs/axum/ — Web framework for RPC server