decdn-common 0.1.0

Shared types for deCDN binaries: config schema, identity, CLI args
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138

//! Arguments for `decdn get <URI>` (#2449): one command for a blob, a whole
//! bundle, or one bundle entry, named by a `decdn:` URI
//! (`adr/appendix-bundles.md` § `decdn:` URIs).
//!
//! The URI stays a `String` here: `decdn-common` does not depend on
//! `decdn-client`, which owns the `DecdnUri` parser. The `cli` binary parses it
//! and routes the target to the blob fetch or the bundle pull.

use std::path::PathBuf;

use clap::Args;

use super::fetch::ClientFetchArgs;

/// The default `--jobs` of a bundle pull.
pub const DEFAULT_JOBS: usize = 4;

/// The default `--max-lane-streams` of a bundle pull.
pub const DEFAULT_MAX_LANE_STREAMS: u16 = 4;

/// `decdn get` — pull what a `decdn:` URI names over the paid `cdn/client/v1`
/// path.
///
/// - `decdn:<hash>`: the raw blob. `-o` is the destination file, or `-` for
///   stdout.
/// - `decdn:<hash>/`: every entry of the bundle whose manifest has this hash.
///   `-o` is the output directory.
/// - `decdn:<hash>/<path>`: that one bundle entry. `-o` is the output
///   directory, and the file lands at `<OUT>/<path>`.
///
/// A `?ns=<id>` in the URI is the namespace routing hint (ADR 002) for every
/// request of the run: the manifest blob and each entry. The bundle-only flags
/// are an error on a blob URI, and the entry filters (`--include`,
/// `--exclude`, `--select`) are an error on an entry URI.
#[derive(Args, Debug)]
#[expect(
    clippy::struct_excessive_bools,
    reason = "independent CLI flags (--overwrite/--dry-run/--json/--select), not a state machine"
)]
pub struct GetArgs {
    /// The `decdn:` URI to pull: `decdn:<hash>[/<path>][?ns=<id>]`.
    #[arg(value_name = "URI")]
    pub uri: String,

    /// The destination. For a blob URI, the file to write (atomically: temp
    /// in the same directory, then rename), or `-` to stream verified bytes to
    /// stdout. For a bundle or entry URI, the output directory (created if
    /// absent); each entry's relative path resolves within it, and
    /// `..`/absolute/escaping paths are rejected.
    #[arg(short = 'o', long, value_name = "PATH")]
    pub output: PathBuf,

    /// Bundle only: maximum concurrent entry fetches across the whole run
    /// [default: 4]. Each distinct blob is one unit of work holding one slot:
    /// a plain whole-file entry, or a range-dedup entry across its complement
    /// drive, donor splice, and any re-fetch. A range-dedup entry that only
    /// waits for a sibling to finish the chunks it splices gives its slot to a
    /// queued entry until then. A byte range a sibling entry already holds is
    /// spliced from disk, not fetched, so it never takes a slot of its own.
    #[arg(long, value_name = "N")]
    pub jobs: Option<usize>,

    /// Bundle only: maximum concurrent streams to one `(pool, signer,
    /// provider)` lane [default: 4]. Same-lane streams share one cumulative
    /// voucher watermark, and the serving node credits each stream's delivered
    /// bytes from that shared lane fairly (a slow stream is paid from the
    /// headroom a faster sibling opened), so same-lane concurrency is safe and
    /// this only bounds how many streams touch one provider at once.
    /// Cross-lane parallelism (distinct providers) is bounded by `--jobs`
    /// regardless.
    ///
    /// One connection per node carries every stream of the command, so the
    /// bound (1 to 64) stays below the node's limit of concurrent streams on
    /// one connection.
    #[arg(long, value_name = "N", value_parser = clap::value_parser!(u16).range(1..=64))]
    pub max_lane_streams: Option<u16>,

    /// Whole-bundle only: pull only entries whose POSIX relative path matches
    /// one of these globs (`models/*.bin`), matched against the manifest's
    /// `path` field, never the on-disk absolute path. Repeatable: an entry
    /// passes the include gate if it matches any one. Absent => every entry
    /// passes the gate. gitignore semantics: `*` does not cross `/`, `**`
    /// recurses.
    #[arg(long = "include", value_name = "GLOB", action = clap::ArgAction::Append)]
    pub include: Vec<String>,

    /// Whole-bundle only: skip entries whose POSIX relative path matches one
    /// of these globs, matched against the manifest's `path` field.
    /// Repeatable: every pattern is OR-ed. `--exclude` wins over `--include`:
    /// an entry matching both is skipped. Same gitignore glob semantics as
    /// `--include`.
    #[arg(long = "exclude", value_name = "GLOB", action = clap::ArgAction::Append)]
    pub exclude: Vec<String>,

    /// Whole-bundle only: choose which files to pull interactively. Opens the
    /// (post-`--include`/`--exclude`) file list in `$VISUAL`/`$EDITOR`, one
    /// `path` per line. Comment out (prefix `#`) or delete any line to skip
    /// that file; save and exit to pull the rest. Requires an interactive
    /// terminal; incompatible with `--json` and `--dry-run`.
    #[arg(long)]
    pub select: bool,

    /// Bundle only: re-fetch and overwrite entries whose destination file
    /// already exists. Default is skip-existing (resume-friendly): a path
    /// skips when its saved `.decdn-manifest.json` record still matches the
    /// file's hash, size, and mtime — the fast path, which trusts that gate
    /// without re-hashing — or, failing that, when re-hashing its on-disk
    /// bytes matches the manifest. A file byte-identical to one already
    /// anywhere else in the output root is likewise reused with no download:
    /// it is linked (or copied) from that on-disk file once its hash is
    /// confirmed by a re-hash. Use `--overwrite` to force a full re-fetch of
    /// every entry, for example when the output directory may have been
    /// modified outside `decdn` (an in-place edit that keeps a file's size and
    /// mtime is otherwise trusted by the fast path). It skips consulting
    /// `.decdn-manifest.json` for skip decisions, so it disables both the
    /// skip-existing path and the whole-root reuse above; the file is still
    /// read and rewritten with the run's results. It also fetches the
    /// manifest again instead of reading the output root's cached copy.
    #[arg(long)]
    pub overwrite: bool,

    /// Bundle only: print the entries the run would pull (paths + sizes, after
    /// the entry filters; files already present are still listed) and exit
    /// without any network or chain activity. Entries are listed only when an
    /// earlier pull into the same output directory cached the bundle manifest.
    #[arg(long)]
    pub dry_run: bool,

    /// Bundle only: emit a one-line JSON summary instead of human-readable
    /// output.
    #[arg(long)]
    pub json: bool,

    /// Retrieval flags: peer discovery, chain and payment-pool coordinates,
    /// the source cap and the give-up limit.
    #[command(flatten)]
    pub common: ClientFetchArgs,
}