Skip to main content

Crate aria2_core

Crate aria2_core 

Source
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 / FeatureStatusNotes
HTTP / HTTPS✅ FullRange requests, redirects, cookies, gzip/bzip2/chunked decoding
FTP / SFTP✅ FullPassive/active mode, REST resume, LIST/MLSD parsing
BitTorrent✅ FullPiece picker, choke algorithm, DHT, tracker (HTTP/UDP), seeding
Metalink✅ Fullv3/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), ConfigManager runtime manager, NetRC authentication parser, and URI list file parser.

  • engine — Shared event loop, task lifecycle, scheduling, and protocol command assembly. Protocol-specific execution lives under engine::http, engine::ftp, engine::sftp, engine::bittorrent, and engine::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-safe CredentialStore with 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.