Skip to main content

docsrs_cli/
lib.rs

1//! One-shot library and CLI for crates.io search and docs.rs documentation.
2//!
3//! `docsrs-cli` is agent-first: structured data on stdout, diagnostics on stderr,
4//! deterministic exit codes, and a BORN → EXECUTE → FINALIZE → DIE lifecycle with
5//! no daemon or sticky session state.
6//!
7//! This crate **consumes** published documentation from crates.io and docs.rs
8//! (and stdlib pages on `doc.rust-lang.org`). It does **not** replace docs.rs
9//! or re-implement `cargo doc` as a proprietary host.
10//!
11//! # Concurrency model (Rules Rust — parallelism)
12//!
13//! Workload is **mixed I/O + CPU** (see binary `main`, [`concurrency`], [`http::HttpClient`]):
14//! multi-thread Tokio for HTTPS, `spawn_blocking` under
15//! [`concurrency::ConcurrencyBudget`] for HTML parse, and `rayon` for large
16//! `all.html` hit scans. Bound via `--max-concurrency` / auto CPU+RAM formula.
17//! Fixed auxiliary tasks (double-interrupt, [`shutdown::ProgressGuard`]) still
18//! abort-on-drop. Shared cancel uses `Arc<AtomicU8>`, not `Mutex` across `.await`.
19//!
20//! # HTTP retry (Rules Rust — retry/backoff)
21//!
22//! Product GETs use [`retry::RetryConfig`]: exponential full-jitter backoff,
23//! `Retry-After` delta-seconds **or** HTTP-date on 429/503, dual budget
24//! (`max_attempts` + `max_elapsed_ms`), no retry on permanent 4xx/parse/budget.
25//! Kill switch: `--disable-retry` / TOML `disable_retry` / `max_retries=0`. Policy is
26//! single-layer inside [`http::HttpClient`] only.
27//!
28//! # Features
29//!
30//! This package has no Cargo feature flags. All product capabilities ship in the
31//! default build. Optional network live tests are gated by environment variables
32//! (`DOCSRS_CLI_NETWORK_TESTS`, `DOCSRS_CLI_STDLIB_NETWORK_TESTS`), not features.
33//!
34//! # Safety
35//!
36//! - Product code in `src/` contains no `unsafe` blocks (`#![forbid(unsafe_code)]`).
37//! - External input is validated at boundaries (domain newtypes, origin allowlist, body caps).
38//! - Threat model (STRIDE / accepted risks): `docs/decisions/0004-threat-model.md`.
39//! - Regexes compile with bounded `size_limit` / `dfa_size_limit` (ReDoS posture).
40//! - docs.rs builds enable `doc_cfg` via `#![cfg_attr(docsrs, feature(doc_cfg))]`
41//!   (post-2025 merge of `doc_auto_cfg` into `doc_cfg`). Local `cargo +stable doc`
42//!   does not require the nightly feature gate.
43//! - TLS is rustls-only; HTTP product methods are GET-only against an allowlist.
44//! - Agent lifecycle is documented as a Mermaid sequence fence on [`run`]
45//!   (plain rustdoc code block — no proc-macro renderer).
46//!
47//! # Examples
48//!
49//! Parse a crate name at the domain boundary:
50//!
51//! ```
52//! use docsrs_cli::domain::CrateName;
53//!
54//! let name = CrateName::parse("serde").expect("valid crate name");
55//! assert_eq!(name.as_str(), "serde");
56//! ```
57//!
58//! Map error kinds to process exit codes:
59//!
60//! ```
61//! use docsrs_cli::error::ErrorKind;
62//!
63//! assert_eq!(ErrorKind::NotFound.exit_code(), 66);
64//! assert!(ErrorKind::Timeout.retryable());
65//! ```
66
67// Defensive security (Rules Rust / ADR 0009): product has no FFI; forbid all `unsafe`.
68// Integration tests may use `unsafe` only for the Unix signal harness (`libc::kill`).
69// Loopback mocks use CLI/XDG `allow_loopback` — never `env::set_var`.
70#![forbid(unsafe_code)]
71#![warn(missing_docs)]
72#![warn(rustdoc::missing_crate_level_docs)]
73#![warn(rustdoc::broken_intra_doc_links)]
74#![warn(rustdoc::private_intra_doc_links)]
75#![deny(rustdoc::invalid_html_tags)]
76#![deny(rustdoc::invalid_rust_codeblocks)]
77#![deny(rustdoc::bare_urls)]
78#![warn(rustdoc::redundant_explicit_links)]
79#![cfg_attr(docsrs, feature(doc_cfg))]
80
81pub mod cache;
82pub mod cli;
83pub mod concurrency;
84pub mod config;
85pub mod crates_io;
86pub mod diagnostics;
87pub mod docs_rs;
88mod doctor;
89mod meta_cmds;
90mod ops;
91pub mod domain;
92pub mod error;
93pub mod http;
94pub mod i18n;
95pub mod item_kind;
96mod output;
97pub mod platform;
98pub mod render;
99pub mod retry;
100pub mod shutdown;
101mod suggest;
102
103use std::io::{self, IsTerminal, Write};
104use std::process::ExitCode;
105use std::time::Duration;
106
107use clap::Parser;
108use tokio::time::Instant;
109
110use crate::cli::{Cli, Commands};
111use crate::config::{APP_NAME, APP_VERSION, Config, MSRV, validate_user_agent};
112use crate::diagnostics::init_tracing;
113use crate::error::{
114    AppError, AppResult, EXIT_BROKEN_PIPE, EXIT_USAGE, ErrorKind,
115};
116use crate::i18n::Locale;
117use crate::render::{error_envelope, success_envelope};
118use crate::shutdown::{
119    CancelFlag, duration_ms, flush_stdio, race_op_with_cancel_and_deadline,
120    spawn_double_interrupt_force_exit,
121};
122
123/// True when argv requests JSON or stdout is non-TTY (agent mode) — used before full parse.
124fn argv_wants_json_mode(args: &[std::ffi::OsString], stdout_is_terminal: bool) -> bool {
125    let has_json = args.iter().any(|a| a == "--json");
126    let has_human_format = args.windows(2).any(|w| {
127        w[0] == "--format"
128            && w[1]
129                .to_str()
130                .is_some_and(|v| v == "text" || v == "markdown" || v == "md")
131    }) || args.iter().any(|a| {
132        a.to_str().is_some_and(|s| {
133            s.starts_with("--format=")
134                && (s.contains("text") || s.contains("markdown") || s.contains("md"))
135        })
136    });
137    if has_json {
138        return true;
139    }
140    if has_human_format {
141        return false;
142    }
143    !stdout_is_terminal
144}
145
146/// Parse argv and execute one command. Returns process exit code.
147///
148/// This is the binary entrypoint wrapper (stdin/stdout/stderr are process defaults).
149/// Agent-first: when stdout is not a TTY, JSON is auto-selected unless `--format` forces human.
150///
151/// # Lifecycle
152///
153/// Lifecycle (BORN → EXECUTE → FINALIZE → DIE), Mermaid form for agent readers:
154///
155/// ```text
156/// sequenceDiagram
157///   participant A as Agent
158///   participant C as docsrs-cli
159///   participant N as crates.io / docs.rs
160///   A->>C: BORN spawn
161///   C->>N: EXECUTE GET
162///   N-->>C: body
163///   C-->>A: stdout envelope
164///   C->>C: FINALIZE flush
165///   C->>C: DIE exit code
166/// ```
167pub async fn run<I, T>(args: I) -> ExitCode
168where
169    I: IntoIterator<Item = T>,
170    T: Into<std::ffi::OsString> + Clone,
171{
172    let stdout_is_terminal = io::stdout().is_terminal();
173    run_with_io(
174        args,
175        io::stdin(),
176        io::stdout(),
177        io::stderr(),
178        stdout_is_terminal,
179    )
180    .await
181}
182
183/// Injectable IO entrypoint for tests (`run(args, stdin, stdout, stderr, stdout_is_terminal)`).
184///
185/// `stdin` is reserved for future payload flows and is unused by current ops.
186/// Pass `stdout_is_terminal = true` to keep human markdown default in unit tests;
187/// the binary path passes the real `IsTerminal` of process stdout.
188pub async fn run_with_io<I, T, In, Out, ErrW>(
189    args: I,
190    _stdin: In,
191    mut stdout: Out,
192    mut stderr: ErrW,
193    stdout_is_terminal: bool,
194) -> ExitCode
195where
196    I: IntoIterator<Item = T>,
197    T: Into<std::ffi::OsString> + Clone,
198    In: io::Read,
199    Out: Write,
200    ErrW: Write,
201{
202    // Collect args once so we can detect --json / agent mode before parse fails.
203    let args: Vec<std::ffi::OsString> = args.into_iter().map(Into::into).collect();
204    let agent_json = argv_wants_json_mode(&args, stdout_is_terminal);
205
206    let cli = match Cli::try_parse_from(&args) {
207        Ok(c) => c,
208        Err(e) => {
209            // Help / version display: human text, success.
210            if !e.use_stderr() {
211                let _ = e.print();
212                flush_stdio();
213                return ExitCode::SUCCESS;
214            }
215            // Contract: usage failures are exit EXIT_USAGE with JSON envelope in agent/JSON mode.
216            let msg = e.to_string();
217            if agent_json {
218                let err = AppError::new(ErrorKind::Usage, msg);
219                let _ = output::write_json(&mut stdout, &error_envelope(&err, "usage", 0));
220                flush_stdio();
221                return ExitCode::from(EXIT_USAGE);
222            }
223            // Human TTY: print clap rendering to stderr, still EXIT_USAGE (unified contract).
224            let _ = e.print();
225            flush_stdio();
226            return ExitCode::from(EXIT_USAGE);
227        }
228    };
229
230    let code = match run_cli(cli, &mut stdout, &mut stderr, stdout_is_terminal).await {
231        Ok(code) => code,
232        Err(err) if err.kind() == ErrorKind::BrokenPipe => ExitCode::from(EXIT_BROKEN_PIPE),
233        Err(err) => {
234            // Domain errors should already have been turned into ExitCode via
235            // `emit_error` inside `run_cli`. This path is a last-resort safety net
236            // (preserves kind exit code; never hardcodes 70).
237            tracing::error!(
238                target: "docsrs_cli::diagnostics",
239                error = %err,
240                kind = ?err.kind(),
241                "error escaped structured emit path"
242            );
243            let _ = writeln!(stderr, "error: {}", err.message());
244            err.exit_code()
245        }
246    };
247    flush_stdio();
248    let _ = stdout.flush();
249    let _ = stderr.flush();
250    code
251}
252
253async fn run_cli<Out: Write, ErrW: Write>(
254    cli: Cli,
255    stdout: &mut Out,
256    stderr: &mut ErrW,
257    stdout_is_terminal: bool,
258) -> Result<ExitCode, AppError> {
259    let wire = cli.wire_command();
260    if let Err(e) = cli.validate_format_conflict() {
261        return Ok(meta_cmds::emit_error(
262            &cli,
263            &e,
264            Locale::En,
265            stdout,
266            stderr,
267            stdout_is_terminal,
268            wire,
269            0,
270        ));
271    }
272
273    init_tracing(&cli);
274
275    // Config load must go through `emit_error` so exit 78 / JSON envelope are correct.
276    // A bare `?` would bubble to `run_with_io` and historically forced exit 70.
277    let mut cfg = match Config::load_with_options(
278        cli.config_dir.clone(),
279        cli.cache_dir.clone(),
280        cli.allow_loopback,
281    ) {
282        Ok(c) => c,
283        Err(e) => {
284            return Ok(meta_cmds::emit_error(
285                &cli,
286                &e,
287                Locale::En,
288                stdout,
289                stderr,
290                stdout_is_terminal,
291                wire,
292                0,
293            ));
294        }
295    };
296    if let Err(e) = apply_cli_overrides(&cli, &mut cfg) {
297        return Ok(meta_cmds::emit_error(
298            &cli,
299            &e,
300            Locale::En,
301            stdout,
302            stderr,
303            stdout_is_terminal,
304            wire,
305            0,
306        ));
307    }
308
309    // Fail-closed on explicit/config lang before any network work (no product env).
310    let locale = match Locale::resolve(cli.lang.as_deref().or(cfg.lang.as_deref())) {
311        Ok(l) => l,
312        Err(e) => {
313            return Ok(meta_cmds::emit_error(
314                &cli,
315                &e,
316                Locale::En,
317                stdout,
318                stderr,
319                stdout_is_terminal,
320                wire,
321                0,
322            ));
323        }
324    };
325    let start = Instant::now();
326    let wants_json = cli.wants_json(stdout_is_terminal);
327    let dry_run = cli.dry_run;
328    let wall = Duration::from_secs(cfg.timeout_secs.max(1));
329    let cancel = CancelFlag::new();
330    // Rules Rust: first Ctrl-C is cooperative; second within 5s force-exits 130.
331    let force_on_second = spawn_double_interrupt_force_exit();
332
333    let cli_ref = &cli;
334    let cfg_ref = &cfg;
335    let result = race_op_with_cancel_and_deadline(wall, cancel.clone(), async {
336        dispatch(
337            cli_ref, cfg_ref, locale, dry_run, wants_json, start, cancel, stdout, stderr,
338        )
339        .await
340    })
341    .await;
342
343    force_on_second.abort();
344
345    match result {
346        Ok(code) => Ok(code),
347        Err(e) if e.kind() == ErrorKind::BrokenPipe => Ok(ExitCode::from(EXIT_BROKEN_PIPE)),
348        Err(e) => Ok(meta_cmds::emit_error(
349            &cli,
350            &e,
351            locale,
352            stdout,
353            stderr,
354            stdout_is_terminal,
355            wire,
356            duration_ms(start),
357        )),
358    }
359}
360
361fn apply_cli_overrides(cli: &Cli, cfg: &mut Config) -> AppResult<()> {
362    if let Some(t) = cli.timeout {
363        if t == 0 {
364            return Err(AppError::new(
365                ErrorKind::InvalidInput,
366                "timeout must be >= 1 second (got 0)",
367            ));
368        }
369        cfg.timeout_secs = t;
370    }
371    if let Some(t) = cli.connect_timeout {
372        if t == 0 {
373            return Err(AppError::new(
374                ErrorKind::InvalidInput,
375                "connect_timeout must be >= 1 second (got 0)",
376            ));
377        }
378        cfg.connect_timeout_secs = t;
379    }
380    if let Some(ref ua) = cli.user_agent {
381        validate_user_agent(ua)?;
382        cfg.user_agent.clone_from(ua);
383    }
384    if let Some(b) = cli.max_body_bytes {
385        // Fail-closed: never silently clamp explicit CLI budgets (GAP-X-005).
386        if b > crate::config::HARD_MAX_BODY_BYTES {
387            return Err(AppError::new(
388                ErrorKind::InvalidInput,
389                format!(
390                    "max_body_bytes exceeds hard maximum ({})",
391                    crate::config::HARD_MAX_BODY_BYTES
392                ),
393            ));
394        }
395        cfg.max_body_bytes = b;
396    }
397    if let Some(b) = cli.max_output_bytes {
398        if b > crate::config::HARD_MAX_OUTPUT_BYTES {
399            return Err(AppError::new(
400                ErrorKind::InvalidInput,
401                format!(
402                    "max_output_bytes exceeds hard maximum ({})",
403                    crate::config::HARD_MAX_OUTPUT_BYTES
404                ),
405            ));
406        }
407        cfg.max_output_bytes = b;
408    }
409    if let Some(d) = cli.rate_limit_delay_ms {
410        cfg.rate_limit_delay_ms = d;
411    }
412    if let Some(n) = cli.max_concurrency {
413        cfg.max_concurrency = n;
414    }
415    if let Some(r) = cli.max_retries {
416        cfg.max_retries = r;
417    }
418    if let Some(ms) = cli.retry_base_ms {
419        cfg.retry_base_ms = ms;
420    }
421    if let Some(ms) = cli.retry_max_delay_ms {
422        cfg.retry_max_delay_ms = ms;
423    }
424    if let Some(ms) = cli.retry_max_elapsed_ms {
425        cfg.retry_max_elapsed_ms = ms;
426    }
427    if cli.disable_retry {
428        cfg.disable_retry = true;
429    }
430    if let Some(ref l) = cli.lang {
431        match &mut cfg.lang {
432            Some(dst) => dst.clone_from(l),
433            None => cfg.lang = Some(l.clone()),
434        }
435    }
436    if cli.no_cache {
437        cfg.no_cache = true;
438    }
439    if cli.allow_loopback {
440        cfg.allow_loopback = true;
441    }
442    if let Some(ttl) = cli.cache_ttl_secs {
443        cfg.cache_ttl_secs = ttl;
444    }
445    if let Some(max) = cli.max_cache_bytes {
446        cfg.max_cache_bytes = max;
447    }
448    if let Some(ref dir) = cli.cache_dir {
449        cfg.cache_dir = Some(dir.clone());
450    }
451    // After all CLI mutations: hard ceiling (cannot elevate above HARD_MAX_*).
452    cfg.clamp_resource_limits();
453    Ok(())
454}
455
456
457#[allow(clippy::too_many_arguments)]
458async fn dispatch<Out: Write, ErrW: Write>(
459    cli: &Cli,
460    cfg: &Config,
461    locale: Locale,
462    dry_run: bool,
463    wants_json: bool,
464    start: Instant,
465    cancel: CancelFlag,
466    stdout: &mut Out,
467    _stderr: &mut ErrW,
468) -> AppResult<ExitCode> {
469    match &cli.command {
470        Commands::Version => {
471            if wants_json {
472                let data = meta_cmds::VersionData {
473                    name: APP_NAME,
474                    version: APP_VERSION,
475                    msrv: MSRV,
476                    os: std::env::consts::OS,
477                    arch: std::env::consts::ARCH,
478                };
479                output::write_json(
480                    stdout,
481                    &success_envelope("version", &data, duration_ms(start), None),
482                )?;
483            } else {
484                writeln!(stdout, "{APP_NAME} {APP_VERSION}").map_err(output::map_stdout_err)?;
485            }
486            Ok(ExitCode::SUCCESS)
487        }
488        Commands::Doctor { online } => doctor::doctor(cfg, *online, wants_json, start, locale, stdout),
489        Commands::Commands => meta_cmds::commands_cmd(wants_json, start, stdout),
490        Commands::Schema { cmd } => meta_cmds::schema_cmd(cmd, wants_json, cli.format, start, stdout),
491        Commands::Completions { shell } => {
492            // Completions emit shell script by default (even on non-TTY). JSON only if --json/--format json.
493            let explicit_json =
494                cli.json || matches!(cli.format, Some(crate::cli::OutputFormat::Json));
495            meta_cmds::completions_cmd(*shell, explicit_json, start, stdout)
496        }
497        Commands::Cache { action } => meta_cmds::cache_cmd(cfg, action, wants_json, start, stdout),
498        Commands::Config { action } => meta_cmds::config_cmd(cli, cfg, action, wants_json, start, stdout),
499        Commands::SearchCrates {
500            query,
501            per_page,
502            sort,
503            page,
504            page_token,
505        } => {
506            let ctx = ops::OpCtx {
507                cli,
508                cfg,
509                locale,
510                dry_run,
511                wants_json,
512                start,
513                cancel,
514            };
515            ops::search_crates(&ctx, stdout, query, *per_page, *sort, *page, page_token).await
516        }
517        Commands::Readme {
518            crate_name,
519            crate_version,
520        } => {
521            let ctx = ops::OpCtx {
522                cli,
523                cfg,
524                locale,
525                dry_run,
526                wants_json,
527                start,
528                cancel,
529            };
530            ops::readme(&ctx, stdout, crate_name, crate_version).await
531        }
532        Commands::GetItem {
533            crate_name,
534            item_type,
535            item_path,
536            crate_version,
537            suggest,
538        } => {
539            let ctx = ops::OpCtx {
540                cli,
541                cfg,
542                locale,
543                dry_run,
544                wants_json,
545                start,
546                cancel,
547            };
548            ops::get_item(
549                &ctx,
550                stdout,
551                crate_name,
552                item_type,
553                item_path,
554                crate_version,
555                *suggest,
556            )
557            .await
558        }
559        Commands::SearchInCrate {
560            crate_name,
561            query,
562            crate_version,
563            item_type,
564            limit,
565            r#match,
566        } => {
567            let ctx = ops::OpCtx {
568                cli,
569                cfg,
570                locale,
571                dry_run,
572                wants_json,
573                start,
574                cancel,
575            };
576            ops::search_in_crate(
577                &ctx,
578                stdout,
579                crate_name,
580                query,
581                crate_version,
582                item_type,
583                *limit,
584                r#match,
585            )
586            .await
587        }
588    }
589}
590