1#![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
123fn 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
146pub 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
183pub 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 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 if !e.use_stderr() {
211 let _ = e.print();
212 flush_stdio();
213 return ExitCode::SUCCESS;
214 }
215 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 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 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 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 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 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 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 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 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