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 / DOCSRS_CLI_DISABLE_RETRY. 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 nounsafeblocks. - docs.rs builds enable
doc_cfgvia#. Localcargo +stable docdoes 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
runviaaquamarine(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)).