tur_rs/lib.rs
1//! tur-rs: A relentless, high-concurrency download manager.
2//!
3//! `tur-rs` is a reusable download core with adaptive work-stealing,
4//! protocol-aware scheduling, and platform-optimized storage backends.
5//!
6//! # Quick start (library embedding)
7//!
8//! ```rust,no_run
9//! use tokio::task::LocalSet;
10//! use tur_rs::{TurService, ServiceConfig, DownloadRequest, DownloadUpdate};
11//!
12//! # async fn example() -> anyhow::Result<()> {
13//! let local = LocalSet::new();
14//! local.run_until(async {
15//! let mut service = TurService::new(ServiceConfig::default()).await?;
16//!
17//! let mut handle = service
18//! .add_download(DownloadRequest::new("https://example.com/file.zip"))
19//! .await?;
20//!
21//! while let Some(update) = handle.recv().await {
22//! match update {
23//! DownloadUpdate::Progress { downloaded_bytes, speed_bps } => {
24//! println!("{downloaded_bytes} bytes at {speed_bps:.0} bps");
25//! }
26//! DownloadUpdate::TotalSize(size) => {
27//! println!("Total: {size} bytes");
28//! }
29//! DownloadUpdate::Workers(workers) => {
30//! println!("{} worker snapshots", workers.len());
31//! }
32//! DownloadUpdate::Protocol(protocol) => {
33//! println!("Protocol: {protocol:?}");
34//! }
35//! DownloadUpdate::StatusChanged(status) => {
36//! println!("Status: {status:?}");
37//! if matches!(status, tur_rs::DownloadStatus::Completed) {
38//! break;
39//! }
40//! }
41//! }
42//! }
43//!
44//! service.shutdown().await;
45//! Ok::<_, anyhow::Error>(())
46//! }).await
47//! # }
48//! ```
49//!
50//! See `examples/embed.rs` for a complete runnable example.
51//!
52//! # Features
53//!
54//! | Feature | Description |
55//! |-------------------------------|--------------------------------------------------------------|
56//! | `tui` (default) | Terminal UI via ratatui/crossterm |
57//! | `http3` | Experimental HTTP/3 via QUIC (quinn, h3, rustls) |
58//! | `linux-io-uring-experimental` | Experimental Linux io_uring storage backend |
59//!
60//! # Stability
61//!
62//! The types re-exported from this crate root (`TurService`, `ServiceConfig`,
63//! `DownloadRequest`, `DownloadHandle`, `DownloadUpdate`, `DownloadStatus`,
64//! `HttpMode`, `ScheduleMode`, `StorageConfig`) are the **stable public API**
65//! and follow semantic versioning.
66//!
67//! Internal modules (`engine`, `connector`, `quic`, `storage`, `cli`) are
68//! exposed for advanced use but may change between minor releases. Prefer
69//! the re-exported types where possible.
70
71// ---------------------------------------------------------------------------
72// Public modules (exposed for the binary frontends and advanced embedding)
73// ---------------------------------------------------------------------------
74
75pub mod cli;
76pub mod connector;
77pub mod engine;
78pub mod quic;
79pub mod storage;
80
81/// Stable service facade for frontend integration.
82pub mod service;
83
84#[cfg(feature = "tui")]
85pub mod tui;
86
87// ---------------------------------------------------------------------------
88// Re-exports — stable public API surface
89//
90// These are the types that downstream consumers should rely on.
91// Everything behind `engine::`, `connector::`, `quic::`, `storage::` is
92// internal and subject to change.
93// ---------------------------------------------------------------------------
94
95pub use service::{
96 CookieEntry, CookieJar, DownloadHandle, DownloadRequest, DownloadUpdate, RequestContext,
97 ServiceConfig, SessionContext, TurService,
98};
99pub use storage::StorageConfig;
100
101pub use engine::{
102 DownloadStatus, HttpMode, ProtocolFamily, ProtocolInfo, ScheduleMode, WorkerSnapshot,
103 WorkerState,
104};