aria2_rust
中文:README_CN.md
Documentation
Start with the documentation index. The main user paths are:
aria2_rust is an independent Rust download engine. It provides practical compatibility with the aria2 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.
GUI Companion
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,
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 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 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)
- Python SDK (complete client API): An async HTTP/WebSocket JSON-RPC client covering task, status, option, session, system, and event methods; unwrapped methods are available through
call(). It is not a native Rust FFI binding and does not download directly; it controls a running aria2-rust RPC service. Original-client interoperability remains tracked in the compatibility matrix. - Node.js SDK (complete client API): An async TypeScript HTTP/WebSocket JSON-RPC client covering task, status, option, session, system, and event methods; unwrapped methods are available through
call(). It also controls a running aria2-rust RPC service rather than linking to Rust or downloading files itself. - Terminal UI (optional): The
tuifeature provides local and remote-RPC modes with task creation, filtering, paging, details, pause/resume, removal, and translated interface resources; automated feature builds cover compilation, while the interactive cross-platform matrix remains open. See the TUI Guide. - Configuration System: Typed option registry with four-source merging (CLI/file/environment/defaults)
- NetRC Authentication: Automatic FTP/HTTP credential loading from
.netrcfiles - URI List Files: Batch import download tasks via
-iparameter - Public Tracker List: Enabled by default; refreshes
https://cf.trackerslist.com/best.txtevery 24 hours and appends deduplicated trackers to active BT tasks
Quick Start
Install a Release
Prebuilt artifacts are published on the GitHub Releases page. Each platform has minimal, standard, tui, and full variants with matching SHA-256 files. See the release artifact guide before choosing a variant.
One-Line Installation
Linux / macOS:
|
Windows (PowerShell):
irm https://raw.githubusercontent.com/balovess/aria2_rust/main/install.ps1 | iex
Docker (Linux amd64 image):
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:
&&
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:
# Download a file
# Download with multiple connections
# Download a torrent
# Download with custom directory
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:
The generated configuration is intentionally minimal. Session, logging, PID, cookies, DHT state, and server statistics are enabled only by explicit options.
Build from Source
Prerequisites:
- Rust 1.99+ (stable)
- Windows / macOS / Linux
Build Commands:
# Clone the repository
# Build all crates
# Download a file (HTTP)
# Download with custom options
# Show help
# Show version
Usage
Configuration Templates
We provide ready-to-use configuration templates in examples/configs/:
| Template | Description |
|---|---|
| minimal.conf | Minimal configuration for quick setup |
| basic.conf | Basic configuration with common options |
| advanced.conf | Advanced configuration with RPC, proxy, etc. |
| bittorrent.conf | Optimized for BitTorrent downloads |
| windows.conf | Windows manual configuration template |
Usage:
# Copy template to config directory
# Edit as needed
# Run with configuration
For common commands, configuration syntax, RPC/daemon setup, sessions, and configuration check/repair/reset workflows, see the user guide.
Basic HTTP Download
With Options
| 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
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:
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, 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 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. 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
recvafter 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, activity signal, save deadlines, and platform process wait.
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 and
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:
Library Usage
As a library in your Rust project
Add to your Cargo.toml:
[]
= { = "../aria2-core" }
= { = "../aria2-rpc" }
Minimal download example
use ConfigManager;
use RequestGroupMan;
use DownloadOptions;
use OptionValue;
async
RPC server example
use RpcEngine;
use JsonRpcRequest;
async
Building from Source
Requirements
- Rust: 1.99 or later (install)
- OS: Windows 10+, macOS 10.15+, Linux (glibc 2.17+)
Build Commands
# Debug build (fast compilation)
# Release build (optimized)
# Run tests
# Generate documentation
# Run a specific example
Testing
Running Tests
# Run all tests in workspace
# Run tests for specific crate
# Run tests with verbose output
# Run specific test category
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
# Install cargo-tarpaulin (Linux/macOS)
# Generate HTML coverage report
# Generate LCOV format for CI
Running Benchmarks
# Run all benchmarks
# Run specific benchmark
For comprehensive testing guidance, see 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; 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 | 213 canonical public options plus Rust extensions are covered; parsing, boolean semantics, config merging, and help grouping have regression tests; runtime parity is still under comparison |
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 |
Terminal UI (tui feature) |
Implemented path | Local and remote-RPC modes, task creation/filtering/paging/details/pause/remove, and embedded translations; interactive cross-platform acceptance remains open |
| Python and Node.js SDKs | Implemented path | Async HTTP/WebSocket JSON-RPC clients call a running aria2 service; they are not Rust FFI bindings or direct download engines |
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, andsystem.listNotificationsare 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
getPeerswire 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.