Skip to main content

docsrs_cli/cli/
overrides.rs

1//! Apply parsed CLI flags onto the loaded [`Config`].
2//!
3//! Precedence is defaults → XDG `config.toml` → CLI flags, so this runs last and
4//! wins. Explicit budgets are **fail-closed**: a value above a hard ceiling is an
5//! error (exit 65), never a silent clamp, because silently shrinking a cap the
6//! caller asked for makes the resulting truncation look like upstream behaviour.
7
8use super::Cli;
9use crate::config::{Config, HARD_MAX_BODY_BYTES, HARD_MAX_OUTPUT_BYTES, validate_user_agent};
10use crate::error::{AppError, AppResult, ErrorDetail, Subject, ValueSource};
11
12/// Overlay `cli` flags onto `cfg`, then re-apply the hard resource ceilings.
13///
14/// # Errors
15///
16/// Returns [`crate::error::ErrorKind::InvalidInput`] for a zero timeout or a budget above its
17/// hard maximum, and [`crate::error::ErrorKind::Config`] when `--user-agent` fails validation.
18pub fn apply_cli_overrides(cli: &Cli, cfg: &mut Config) -> AppResult<()> {
19    if let Some(t) = cli.timeout {
20        if t == 0 {
21            return Err(AppError::of(ErrorDetail::MustBeAtLeastOneSecond {
22                subject: Subject::Timeout,
23                source: ValueSource::CommandLine,
24            }));
25        }
26        cfg.timeout_secs = t;
27    }
28    if let Some(t) = cli.connect_timeout {
29        if t == 0 {
30            return Err(AppError::of(ErrorDetail::MustBeAtLeastOneSecond {
31                subject: Subject::ConnectTimeout,
32                source: ValueSource::CommandLine,
33            }));
34        }
35        cfg.connect_timeout_secs = t;
36    }
37    if let Some(ref ua) = cli.user_agent {
38        validate_user_agent(ua)?;
39        cfg.user_agent.clone_from(ua);
40    }
41    if let Some(b) = cli.max_body_bytes {
42        // Fail-closed: never silently clamp explicit CLI budgets (GAP-X-005).
43        if b > HARD_MAX_BODY_BYTES {
44            return Err(AppError::of(ErrorDetail::AboveHardMaximum {
45                subject: Subject::MaxBodyBytes,
46                hard_max: HARD_MAX_BODY_BYTES,
47                source: ValueSource::CommandLine,
48            }));
49        }
50        cfg.max_body_bytes = b;
51    }
52    if let Some(b) = cli.agent.max_output_bytes {
53        if b > HARD_MAX_OUTPUT_BYTES {
54            return Err(AppError::of(ErrorDetail::AboveHardMaximum {
55                subject: Subject::MaxOutputBytes,
56                hard_max: HARD_MAX_OUTPUT_BYTES,
57                source: ValueSource::CommandLine,
58            }));
59        }
60        cfg.max_output_bytes = b;
61    }
62    if let Some(d) = cli.rate_limit_delay_ms {
63        cfg.rate_limit_delay_ms = d;
64    }
65    if let Some(n) = cli.max_concurrency {
66        cfg.max_concurrency = n;
67    }
68    if let Some(r) = cli.max_retries {
69        cfg.max_retries = r;
70    }
71    if let Some(ms) = cli.retry_base_ms {
72        cfg.retry_base_ms = ms;
73    }
74    if let Some(ms) = cli.retry_max_delay_ms {
75        cfg.retry_max_delay_ms = ms;
76    }
77    if let Some(ms) = cli.retry_max_elapsed_ms {
78        cfg.retry_max_elapsed_ms = ms;
79    }
80    if cli.disable_retry {
81        cfg.disable_retry = true;
82    }
83    if let Some(ref l) = cli.lang {
84        match &mut cfg.lang {
85            Some(dst) => dst.clone_from(l),
86            None => cfg.lang = Some(l.clone()),
87        }
88    }
89    if cli.no_cache {
90        cfg.no_cache = true;
91    }
92    if cli.allow_loopback {
93        cfg.allow_loopback = true;
94    }
95    if let Some(ttl) = cli.cache_ttl_secs {
96        cfg.cache_ttl_secs = ttl;
97    }
98    if let Some(max) = cli.max_cache_bytes {
99        cfg.max_cache_bytes = max;
100    }
101    if let Some(ref dir) = cli.cache_dir {
102        cfg.cache_dir = Some(dir.clone());
103    }
104    // After all CLI mutations: hard ceiling (cannot elevate above HARD_MAX_*).
105    cfg.clamp_resource_limits();
106    Ok(())
107}
108
109#[cfg(test)]
110mod tests {
111    use super::*;
112    use crate::error::ErrorKind;
113    use clap::Parser;
114
115    fn cfg_from(args: &[&str]) -> AppResult<Config> {
116        let cli = Cli::try_parse_from(args).expect("parse argv");
117        let mut cfg = Config::default();
118        apply_cli_overrides(&cli, &mut cfg)?;
119        Ok(cfg)
120    }
121
122    #[test]
123    fn zero_timeouts_are_rejected() {
124        for args in [
125            ["docsrs-cli", "version", "--timeout", "0"],
126            ["docsrs-cli", "version", "--connect-timeout", "0"],
127        ] {
128            let e = cfg_from(&args).expect_err("must reject zero");
129            assert_eq!(e.kind(), ErrorKind::InvalidInput);
130            assert_eq!(e.kind().exit_code(), 65);
131        }
132    }
133
134    #[test]
135    fn budgets_above_hard_max_fail_closed() {
136        let over_body = (HARD_MAX_BODY_BYTES + 1).to_string();
137        let e = cfg_from(&["docsrs-cli", "version", "--max-body-bytes", &over_body])
138            .expect_err("must reject");
139        assert_eq!(e.kind(), ErrorKind::InvalidInput);
140        let over_out = (HARD_MAX_OUTPUT_BYTES + 1).to_string();
141        let e = cfg_from(&["docsrs-cli", "version", "--max-output-bytes", &over_out])
142            .expect_err("must reject");
143        assert_eq!(e.kind(), ErrorKind::InvalidInput);
144    }
145
146    #[test]
147    fn scalar_flags_land_on_config() {
148        let cfg = cfg_from(&[
149            "docsrs-cli",
150            "version",
151            "--timeout",
152            "42",
153            "--max-retries",
154            "7",
155            "--rate-limit-delay-ms",
156            "250",
157            "--no-cache",
158            "--disable-retry",
159        ])
160        .expect("valid overrides");
161        assert_eq!(cfg.timeout_secs, 42);
162        assert_eq!(cfg.max_retries, 7);
163        assert_eq!(cfg.rate_limit_delay_ms, 250);
164        assert!(cfg.no_cache);
165        assert!(cfg.disable_retry);
166    }
167
168    #[test]
169    fn lang_overwrites_existing_config_value() {
170        let cli = Cli::try_parse_from(["docsrs-cli", "version", "--lang", "pt-BR"]).expect("parse");
171        let mut cfg = Config {
172            lang: Some("en".into()),
173            ..Config::default()
174        };
175        apply_cli_overrides(&cli, &mut cfg).expect("valid");
176        assert_eq!(cfg.lang.as_deref(), Some("pt-BR"));
177    }
178
179    #[test]
180    fn absent_flags_leave_defaults_untouched() {
181        let base = Config::default();
182        let cfg = cfg_from(&["docsrs-cli", "version"]).expect("valid");
183        assert_eq!(cfg.timeout_secs, base.timeout_secs);
184        assert_eq!(cfg.max_retries, base.max_retries);
185        assert_eq!(cfg.user_agent, base.user_agent);
186    }
187}