odl/
lib.rs

1//! ODL — Open-source Download Library and CLI
2//!
3//! This crate provides a flexible, resumable, and configurable download manager
4//! with a small CLI and library API. Intended for use as both a library and a
5//! standalone binary. Public types and modules expose the high-level API used
6//! by applications:
7//!
8//! - `Download` — primary download instruction type (create via `from_response_info` or
9//!   `from_metadata`).
10//! - `download_manager` — higher-level operations to evaluate and run downloads.
11//! - `config` — persistent configuration for the manager.
12//!
13//! Example (library usage):
14//!
15//! ```no_run
16//! use odl::{Download, download_manager::DownloadManager, config::Config};
17//! // create a `DownloadManager` with default `Config` and call `evaluate`/`download`.
18//! ```
19//!
20//! # Feature flags and process spawning
21//!
22//! The default feature set targets the `odl` binary: it pulls in the CLI and
23//! the `ytdlp` engine, which delegates known media hosts to an externally
24//! installed `yt-dlp`. That makes [`download_manager::DownloadManager::evaluate`]
25//! able to **fork and exec a helper process**, which matters if you embed odl
26//! somewhere that cannot or should not do that — a sandboxed desktop app
27//! (macOS App Sandbox, Flatpak), a hardened server, or anywhere `evaluate`
28//! is expected to cost one HTTP round-trip rather than a full extraction.
29//!
30//! Library consumers should therefore opt in deliberately:
31//!
32//! ```toml
33//! # Pure library: no CLI dependencies, no engine that spawns anything.
34//! odl = { version = "3", default-features = false }
35//!
36//! # Library plus media-site support.
37//! odl = { version = "3", default-features = false, features = ["ytdlp"] }
38//! ```
39//!
40//! # Public dependencies
41//!
42//! Types from other crates appear in odl's API, which means a consumer has to
43//! resolve a compatible version of those crates to pass them: [`url::Url`],
44//! `http::HeaderMap`, `chrono::DateTime`, `prost`'s generated types in
45//! [`proto`], and `tokio`'s `AcquireError`. Every one of them is a declared
46//! dependency, so the version to match is visible in odl's manifest.
47//!
48//! Which HTTP client odl downloads with is deliberately **not** on that list.
49//!
50//! Two runtime switches exist as well, for builds that do include the feature:
51//! set `enabled = false` on [`config::YtdlpOptions`], or pass
52//! [`engine::EnginePreference::Engine`] with the HTTP engine on an individual
53//! request. Read the security notes on [`config::YtdlpOptions`] before
54//! accepting a `Config` from anywhere but your own code.
55
56pub mod config;
57pub mod conflict;
58pub mod credentials;
59mod download;
60pub mod download_manager;
61pub mod engine;
62pub mod error;
63pub mod format;
64mod fs_utils;
65pub mod hash;
66#[cfg(any(feature = "ytdlp", feature = "self-update"))]
67mod http;
68pub mod progress;
69mod response_info;
70mod retry_policies;
71#[cfg(feature = "self-update")]
72pub mod self_update;
73pub mod user_agents;
74#[cfg(feature = "ytdlp")]
75pub mod ytdlp;
76
77pub mod proto {
78    // prost names a `oneof`'s module after the message that holds it, which
79    // for `DownloadMetadata` repeats this module's own name.
80    #[allow(clippy::module_inception)]
81    pub mod download_metadata {
82        include!(concat!(env!("OUT_DIR"), "/odl.download_metadata.rs"));
83
84        // prost nests a `oneof`'s enum in a module named after its message,
85        // giving `download_metadata::download_metadata::EngineDetails`.
86        // Re-exported so the doubled path stays an implementation detail.
87        pub use self::download_metadata::EngineDetails;
88    }
89    mod download_metadata_ext;
90}
91
92pub use download::{Download, YtdlpSpec};
93pub use proto::download_metadata;
odl/lib.rs

odl/
lib.rs
