decdn_client/
config.rs

1//! Zero-config tunables for the consumption faces over the paid pull engine
2//! (`Downloader`, `Streamer`, #1848).
3//!
4//! [`PullConfig`] holds only tunables, each with a sensible default. The REQUIRED
5//! per-fetch inputs — identity, the connection, the spend budget, the provider
6//! set — are not here; they flow through the engine's existing params
7//! ([`crate::PoolContext`], the [`iroh::Endpoint`], discovered candidates). That
8//! split is what lets a `PullConfig` construct with no network or chain access.
9//!
10//! The payment interval is deliberately NOT a tunable: it is the fixed protocol
11//! constant [`decdn_protocol::client::CHUNK_BYTES`] (1 MiB, #1676).
12
13/// Default [`PullConfig::read_ahead_bytes`]: 16 MiB — sixteen 1 MiB payment
14/// intervals of buffering. Enough to keep a consumer's buffer full without
15/// fetching (and paying for) far past where it might stop reading.
16pub(crate) const DEFAULT_READ_AHEAD_BYTES: u64 = 16 * 1024 * 1024;
17
18/// Default [`PullConfig::streamer_lane_cap`]: two. A `Streamer` keeps a small,
19/// bounded set of provider lanes on the front — enough for same-region fan-out,
20/// without the wide fan-out a full download wants. The `Downloader` runs one
21/// lane per holder instead.
22pub(crate) const DEFAULT_STREAMER_LANE_CAP: usize = 2;
23
24/// Zero-config tunables shared by the consumption faces.
25///
26/// Overrides are opt-in: [`PullConfig::default`] is the whole configuration a
27/// caller needs. Override a field with struct-update syntax:
28///
29/// ```
30/// use decdn_client::PullConfig;
31///
32/// // Let a stream run 64 MiB ahead of its reader instead of the default.
33/// let config = PullConfig {
34///     read_ahead_bytes: 64 * 1024 * 1024,
35///     ..PullConfig::new()
36/// };
37/// assert_eq!(config.streamer_lane_cap, PullConfig::new().streamer_lane_cap);
38/// ```
39#[derive(Clone, Copy, Debug, PartialEq, Eq)]
40pub struct PullConfig {
41    /// The `Streamer`'s bounded read-ahead: the maximum number of bytes fetched
42    /// AHEAD of the consumer's read cursor. Because every fetched byte is paid,
43    /// this read-ahead bound is also the outstanding-spend bound for a stream the
44    /// consumer abandons early — fetch a two-hour movie's first `read_ahead_bytes`
45    /// only, not the whole thing, for a viewer who stops after five minutes. A
46    /// value below [`crate::pacer::PULL_WINDOW_FLOOR`] is raised to it: a smaller
47    /// window cannot keep a paid leg moving. The `Downloader` ignores it and
48    /// fetches the whole blob at full throughput.
49    pub read_ahead_bytes: u64,
50    /// The `Streamer`'s provider-lane cap: how many discovered holders it fetches
51    /// the front across at once (the acquire loop's `max_lanes`). Small by design
52    /// — a paced stream wants a little same-region parallelism on the front, not
53    /// the wide striping a full download does. The `Downloader` runs one lane
54    /// per holder instead.
55    pub streamer_lane_cap: usize,
56}
57
58impl PullConfig {
59    /// The default configuration: every tunable at its documented default. `const`
60    /// so it is provably free of any network or chain access.
61    #[must_use]
62    pub const fn new() -> Self {
63        Self {
64            read_ahead_bytes: DEFAULT_READ_AHEAD_BYTES,
65            streamer_lane_cap: DEFAULT_STREAMER_LANE_CAP,
66        }
67    }
68}
69
70impl Default for PullConfig {
71    fn default() -> Self {
72        Self::new()
73    }
74}
75
76#[cfg(test)]
77mod tests;
decdn_client/config.rs

decdn_client/
config.rs
