Expand description
§aria2-core
Core library for the aria2-rust download utility — a high-performance, multi-protocol download manager rewritten in Rust.
§Supported Protocols & Features
| Protocol / Feature | Status | Notes |
|---|---|---|
| HTTP / HTTPS | ✅ Full | Range requests, redirects, cookies, gzip/bzip2/chunked decoding |
| FTP / SFTP | ✅ Full | Passive/active mode, REST resume, LIST/MLSD parsing |
| BitTorrent | ✅ Full | Piece picker, choke algorithm, DHT, tracker (HTTP/UDP), seeding |
| Metalink | ✅ Full | v3/v4 parsing, multi-source, checksum verification |
| Auth: Basic (RFC 7617) | ✅ | Base64 credential encoding, HTTPS-only enforcement |
| Auth: Digest (RFC 7616) | ✅ | MD5/SHA256/SHA512 HA1→HA2→Response chain, nonce/qop/stale |
| LPD (BEP 14) | ✅ | UDP multicast peer discovery on 239.192.152.143:6771 |
| BitTorrent MSE | ✅ | 768-bit finite-field DH, RC4 encryption, plaintext fallback |
| Stream Filters | ✅ | Composable GZip/BZip2/Chunked decoder pipeline |
| Post-Download Hooks | ✅ | Move/Rename/Touch/Exec hook chain with env injection |
| BT Progress Persistence | ✅ | Atomic .aria2 file save/load, C++ format compatible |
§Module Overview
-
config— Typed configuration and option registry, multi-source merging (defaults → env → file → CLI),ConfigManagerruntime manager, NetRC authentication parser, and URI list file parser. -
engine— Shared event loop, task lifecycle, scheduling, and protocol command assembly. Protocol-specific execution lives underengine::http,engine::ftp,engine::sftp,engine::bittorrent, andengine::metalink. -
request— Request management layer:RequestGroupMan(global task manager),RequestGroup(per-task lifecycle: Waiting → Active → Paused → Complete/Error/Removed), segment tracking, and bitfield management. -
auth— HTTP authentication:BasicAuthProvider,DigestAuthProvider, thread-safeCredentialStorewith automatic secret zeroing. -
http— HTTP request policy and reusable helpers for authentication, redirects, cookies, response processing, TLS identity, and stream filters (GzDecoder,ChunkedDecoder). -
ftp— FTP control/data connection support, passive/active negotiation, listing parsing, proxy handling, and connection pooling. SFTP lives in its own protocol module. -
filesystem— Disk I/O abstraction:DiskAdaptor,DiskWriter, file pre-allocation strategies, write cache (LRU eviction), and checksum verification. -
ui— Console UI components:ProgressBar,MultiProgress(multi-task summary),StatusPanel, and formatting utilities (format_size,format_speed,format_duration).
§BitTorrent Library API
BitTorrent task state and scheduling are exposed from this crate’s root so
downstream users do not need to depend on the internal engine layout.
Use [PiecePicker] for task-level piece selection, [PieceManager] for
completion and hash accounting, [PeerBitfieldTracker] for peer
availability, and [BtMessageValidator] for validation against torrent
metadata.
fn bittorrent_library_example() {
#[cfg(feature = "bittorrent")]
{
use aria2_core::{
BtMessageValidator, PeerBitfieldTracker, PieceManager, PiecePicker,
PieceSelectionStrategy,
};
let mut picker = PiecePicker::new(128);
picker.set_strategy(PieceSelectionStrategy::RarestFirst);
let mut peers = PeerBitfieldTracker::new(128);
peers.update_peer_bitfield("peer-1", &[0xff; 16]);
let hashes = vec![[0u8; 20]; 128];
let manager = PieceManager::new(128, 262_144, 128 * 262_144, &hashes);
let validator = BtMessageValidator::new(manager.num_pieces(), manager.piece_length());
assert!(validator.validate_index(0).is_ok());
let _ = (picker, peers);
}
}For custom seeding integrations, aria2-core also exposes
BtSeedManager,
PieceDataProvider,
and BtSeedingConfig.
The built-in task lifecycle remains the recommended entry point when the
application needs RPC-visible progress, tracker/DHT discovery, persistence,
and download-to-seed handoff.
The companion aria2-protocol crate owns reusable protocol wire formats,
parsers, and clients, such as Bencode, BitTorrent messages, Handshake, and
Bitfield. aria2-core::engine assembles them with download policy,
request state, and storage.
Applications should import the task-facing types from aria2_core rather
than from aria2_protocol.
§Quick Start
use std::sync::Arc;
use aria2_core::request::request_group::DownloadOptions;
use aria2_core::request::request_group_man::RequestGroupMan;
use aria2_core::DownloadEngine;
#[tokio::main]
async fn main() {
let groups = Arc::new(RequestGroupMan::new());
let mut engine = DownloadEngine::new();
engine.set_request_group_man(Arc::clone(&groups));
let engine = engine.start().unwrap();
let download = engine.downloads().add_uri(
vec!["http://example.com/file.zip".into()],
DownloadOptions::default(),
).unwrap();
let result = download.wait().await.unwrap();
println!("{}: {}", download.gid_hex(), result.status);
engine.shutdown_and_wait().await.unwrap();
}Magnet downloads use the same handle and event stream. Metadata is a
notification rather than a DownloadStatus variant, so callers do not
need to parse messages or poll getFiles:
use std::sync::Arc;
use aria2_core::request::request_group::DownloadOptions;
use aria2_core::request::request_group_man::RequestGroupMan;
use aria2_core::{DownloadEngine, DownloadNotification};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let groups = Arc::new(RequestGroupMan::new());
let mut engine = DownloadEngine::new();
engine.set_request_group_man(Arc::clone(&groups));
let engine = engine.start()?;
let mut events = engine.downloads().subscribe();
let mut options = DownloadOptions::default();
options.dir = Some("./downloads".into());
options.out = None;
options.enable_dht = true;
let download = engine.downloads().add_uri(
vec!["magnet:?xt=urn:btih:YOUR_INFO_HASH".into()],
options,
)?;
let _metadata = events.recv_metadata_for(download.gid()).await?;
for file in download.get_files().unwrap_or_default() {
println!("{}: {} bytes", file.path, file.length);
}
let _result = download.wait().await?;
engine.shutdown_and_wait().await?;
Ok(())
}Re-exports§
pub use engine::download_engine::DownloadEngine;pub use engine::download_event_hooks::DownloadEvent;pub use engine::download_event_hooks::DownloadEventHooks;pub use engine::download_event_hooks::DownloadEventListener;pub use engine::download_event_hooks::DownloadEventListenerId;pub use engine::download_event_hooks::DownloadEventStream;pub use engine::download_event_hooks::DownloadNotification;pub use engine::download_event_hooks::MetadataResolvedEvent;pub use engine::download_manager::DownloadEngineHandle;pub use engine::download_manager::DownloadHandle;pub use engine::download_manager::DownloadManager;pub use engine::download_manager::DownloadManagerError;pub use request::request_group::ChangeableKind;pub use request::request_group::DownloadOptions;pub use request::request_group::DownloadResult;pub use request::request_group::DownloadStatus;pub use request::request_group::DownloadStatusSnapshot;pub use request::request_group::FileEntry;pub use request::request_group::GroupId;pub use request::request_group::RUNTIME_CHANGEABLE_FOR_RESERVED_OPTIONS;pub use request::request_group::RUNTIME_CHANGEABLE_OPTIONS;pub use request::request_group::UriEntry;pub use request::request_group::is_option_changeable;pub use request::request_group_man::PositionMode;pub use request::request_group_man::RequestGroupMan;
Modules§
- auth
- HTTP Authentication module
- c_api
- Stable C ABI for embedding the Rust download engine.
- checksum
- colorized_
stream - config
- constants
- dns
- download
- Download domain objects: per-file tracking, download context, and per-connection request state.
- engine
- Download task lifecycle, dispatch, and protocol-specific command assembly.
- error
- filesystem
- ftp
- FTP protocol client module.
- http
- log
- network
- rate_
limiter - request
- retry
- segment
- selector
- session
- ui
- util
- validation
Macros§
- scoped_
perf_ timer - Helper macro for creating a scoped timer
Functions§
- init_
logging - Initialize the logging subsystem with optional file output.