aria2_core/lib.rs
1//! # aria2-core
2//!
3//! Core library for the aria2-rust download utility — a high-performance,
4//! multi-protocol download manager rewritten in Rust.
5//!
6//! ## Supported Protocols & Features
7//!
8//! | Protocol / Feature | Status | Notes |
9//! |---|---|---|
10//! | HTTP / HTTPS | ✅ Full | Range requests, redirects, cookies, gzip/bzip2/chunked decoding |
11//! | FTP / SFTP | ✅ Full | Passive/active mode, REST resume, LIST/MLSD parsing |
12//! | BitTorrent | ✅ Full | Piece picker, choke algorithm, DHT, tracker (HTTP/UDP), seeding |
13//! | Metalink | ✅ Full | v3/v4 parsing, multi-source, checksum verification, signature |
14//! | Auth: Basic (RFC 7617) | ✅ | Base64 credential encoding, HTTPS-only enforcement |
15//! | Auth: Digest (RFC 7616) | ✅ | MD5/SHA256/SHA512 HA1→HA2→Response chain, nonce/qop/stale |
16//! | LPD (BEP 14) | ✅ | UDP multicast peer discovery on 239.192.152.143:6771 |
17//! | MSE (BEP 10) | ✅ | X25519 DH key exchange, RC4 encryption, plaintext fallback |
18//! | Stream Filters | ✅ | Composable GZip/BZip2/Chunked decoder pipeline |
19//! | Post-Download Hooks | ✅ | Move/Rename/Touch/Exec hook chain with env injection |
20//! | BT Progress Persistence | ✅ | Atomic .aria2 file save/load, C++ format compatible |
21//!
22//! ## Module Overview
23//!
24//! - **[`config`]** — Configuration system with ~95 core options, multi-source
25//! merging (defaults → env → file → CLI), `ConfigManager` runtime manager,
26//! NetRC authentication parser, and URI list file parser.
27//!
28//! - **[`engine`]** — Download engine with event-loop architecture (`DownloadEngine`),
29//! command queue, timer system, tick-based scheduling. Includes `BtDownloadCommand`
30//! with pluggable progress/LPD/hook managers.
31//!
32//! - **[`request`]** — Request management layer: `RequestGroupMan` (global task manager),
33//! `RequestGroup` (per-task lifecycle: Waiting → Active → Paused → Complete/Error/Removed),
34//! segment tracking, and bitfield management.
35//!
36//! - **[`auth`]** — HTTP authentication: [`BasicAuthProvider`](auth::basic_auth::BasicAuthProvider),
37//! [`DigestAuthProvider`](auth::digest_auth::DigestAuthProvider), thread-safe
38//! [`CredentialStore`](auth::credential_store::CredentialStore) with automatic secret zeroing.
39//!
40//! - **[`http`]** — HTTP client with connection pooling, redirect following (iterative with loop detection),
41//! stream filters ([`GzDecoder`](http::stream_filter::GzDecoder), [`ChunkedDecoder`](http::stream_filter::ChunkedDecoder)),
42//! cookie jar, and auth header builders.
43//!
44//! - **[`ftp`]** — FTP/SFTP protocol handler with passive/active modes, fast-path LIST parser,
45//! REST resume support, and control file management.
46//!
47//! - **[`filesystem`]** — Disk I/O abstraction: `DiskAdaptor`, `DiskWriter`,
48//! file pre-allocation strategies, write cache (LRU eviction), and checksum verification.
49//!
50//! - **[`ui`]** — Console UI components: `ProgressBar`, `MultiProgress` (multi-task summary),
51//! `StatusPanel`, and formatting utilities (`format_size`, `format_speed`, `format_duration`).
52//!
53//! ## Quick Start
54//!
55//! ```rust,no_run
56//! use aria2_core::config::ConfigManager;
57//! use aria2_core::request::request_group_man::RequestGroupMan;
58//! use aria2_core::request::request_group::DownloadOptions;
59//! use aria2_core::config::OptionValue;
60//!
61//! #[tokio::main]
62//! async fn main() {
63//! let mut config = ConfigManager::new();
64//! config.set_global_option("dir", OptionValue::Str("./downloads".into())).await.unwrap();
65//! config.set_global_option("split", OptionValue::Int(4)).await.unwrap();
66//!
67//! let man = RequestGroupMan::new();
68//! let opts = DownloadOptions {
69//! split: Some(4),
70//! ..Default::default()
71//! };
72//!
73//! match man.add_group(vec!["http://example.com/file.zip".into()], opts).await {
74//! Ok(gid) => println!("Started: #{}", gid.value()),
75//! Err(e) => eprintln!("Error: {}", e),
76//! }
77//! }
78//! ```
79
80pub mod auth;
81pub mod checksum;
82pub mod colorized_stream;
83pub mod config;
84pub mod constants;
85pub mod dns;
86pub mod engine;
87pub mod error;
88pub mod filesystem;
89pub mod ftp;
90pub mod http;
91pub mod log;
92pub mod option;
93pub mod rate_limiter;
94pub mod request;
95pub mod retry;
96pub mod segment;
97pub mod selector;
98pub mod session;
99pub mod ui;
100pub mod util;
101pub mod validation;
102
103// Re-export commonly used types for downstream crates.
104// This avoids forcing consumers to depend on internal module paths.
105pub use engine::multi_file_layout::TorrentFileEntry;
106pub use request::request_group::{DownloadStatus, RUNTIME_CHANGEABLE_OPTIONS};
107
108#[cfg(test)]
109mod integration_tests_j2_j5;
110
111/// Initialize the logging subsystem with optional file output.
112///
113/// Sets up `tracing-subscriber` with console output (colorized) and optionally
114/// writes to a log file. The log level controls verbosity (DEBUG/INFO/WARN/ERROR).
115pub fn init_logging(
116 log_level: &str,
117 console_log_level: &str,
118 log_file: Option<&str>,
119 log_backup_count: usize,
120) {
121 log::init_logging(log_level, console_log_level, log_file, log_backup_count);
122}