Skip to main content

Crate docsrs_cli

Crate docsrs_cli 

Source
Expand description

One-shot library and CLI for crates.io search and docs.rs documentation.

docsrs-cli is agent-first: structured data on stdout, diagnostics on stderr, deterministic exit codes, and a BORN → EXECUTE → FINALIZE → DIE lifecycle with no daemon or sticky session state.

This crate consumes published documentation from crates.io and docs.rs (and stdlib pages on doc.rust-lang.org). It does not replace docs.rs or re-implement cargo doc as a proprietary host.

§Concurrency model (Rules Rust — parallelism)

Workload is mixed I/O + CPU (see binary main, concurrency, http::HttpClient): multi-thread Tokio for HTTPS, spawn_blocking under concurrency::ConcurrencyBudget for HTML parse, and rayon for large all.html hit scans. Bound via --max-concurrency / auto CPU+RAM formula. Fixed auxiliary tasks (double-interrupt, shutdown::ProgressGuard) still abort-on-drop. Shared cancel uses Arc<AtomicU8>, not Mutex across .await.

§HTTP retry (Rules Rust — retry/backoff)

Product GETs use retry::RetryConfig: exponential full-jitter backoff, Retry-After delta-seconds on 429/503, no retry on permanent 4xx/parse. Kill switch: --disable-retry / TOML disable_retry / max_retries=0. Policy is single-layer inside http::HttpClient only.

§Features

This package has no Cargo feature flags. All product capabilities ship in the default build. Optional network live tests are gated by environment variables (DOCSRS_CLI_NETWORK_TESTS, DOCSRS_CLI_STDLIB_NETWORK_TESTS), not features.

§Safety

  • Product code in src/ contains no unsafe blocks.
  • docs.rs builds enable doc_cfg via #![cfg_attr(docsrs, feature(doc_cfg))] (post-2025 merge of doc_auto_cfg into doc_cfg). Local cargo +stable doc does not require the nightly feature gate.
  • TLS is rustls-only; HTTP product methods are GET-only against an allowlist.
  • Mermaid diagrams for the agent lifecycle live on run via aquamarine (attribute macros apply to items, not the crate root).

§Examples

Parse a crate name at the domain boundary:

use docsrs_cli::domain::CrateName;

let name = CrateName::parse("serde").expect("valid crate name");
assert_eq!(name.as_str(), "serde");

Map error kinds to process exit codes:

use docsrs_cli::error::ErrorKind;

assert_eq!(ErrorKind::NotFound.exit_code(), 66);
assert!(ErrorKind::Timeout.retryable());

Modules§

cache
XDG disk cache for successful HTTP GET bodies between process invocations.
cli
Clap surface for docsrs-cli.
concurrency
Bounded concurrency budget for the multi-thread one-shot runtime.
config
Configuration: defaults, XDG TOML, env allowlist, CLI override.
crates_io
crates.io search-crates operation.
docs_rs
docs.rs operations: readme, get-item, search-in-crate.
domain
Domain newtypes: parse at the boundary, carry validity in the type.
error
Error types and exit-code mapping for docsrs-cli.
http
HTTP client: rustls, retry, rate limit, body cap, host allowlist, cancel-aware.
i18n
Human-facing messages for stderr prose (en / pt-BR).
item_kind
ItemKind normalization for rustdoc URLs and all.html filters.
platform
Cross-platform filesystem and console helpers.
render
Markdown and JSON rendering with output truncation.
retry
Explicit HTTP retry policy for crates.io / docs.rs (Rules Rust — retry/backoff).
shutdown
Wall-clock timeout, signal awareness, and cancel racing for one-shot runs.
telemetry
Process-local diagnostic subscriber for the CLI entry path.

Functions§

run
Parse argv and execute one command. Returns process exit code.
run_with_io
Injectable IO entrypoint for tests (run(args, stdin, stdout, stderr, stdout_is_terminal)).