Expand description
Error types and exit-code mapping for docsrs-cli.
§Model (Rules Rust — error handling)
- Recoverable failures are
AppError/AppResult(I/O, network, parse, validation). ErrorKindis the stable discriminant for exit codes and JSONerror.kind.std::error::Error::sourcepreserves the lower-level cause when present.- Display messages are technical English: lowercase, no trailing period, no secrets.
- Panic is reserved for static invariants (hardcoded regex / CSS selectors).
- Library API: typed
thiserrorenum, notanyhow/Box<dyn Error>as the publicE.
See docs/decisions/0002-error-model.md.
§Errors
| Kind | Exit | Retryable |
|---|---|---|
| usage | 64 | no |
| invalid_input | 65 | no |
| not_found | 66 | no |
| rate_limited / unavailable | 69 | yes |
| network | 74 | yes |
| budget | 74 | no |
| timeout | 124 | yes |
| parse | 65 | no |
| config | 78 | no |
| internal | 70 | no |
| interrupted (SIGINT) | 130 | no |
| terminated (SIGTERM) | 143 | no |
| broken_pipe (stdout EPIPE) | 141 | no |
Structs§
- Suggestion
- One ranked
--suggestalternative.
Enums§
- Allowlist
Stage - Where an allowlist rejection happened.
- AppError
- Application error with structured kind for agents.
- Content
Kind - Which payload flavour a response was expected to carry.
- Destructive
Effect - What a destructive verb would have done to the target it was refused.
- Error
Detail - Every failure the product can report, as data.
- Error
Kind - Canonical error kinds exposed in JSON envelopes.
- Internal
Op - An internal invariant or infrastructure failure, for
crate::error::ErrorDetail::Internal. - IoCause
- Why an I/O failure is or is not worth another attempt.
- IoOp
- A filesystem or process operation that failed, for
crate::error::ErrorDetail::Io. - Subject
- The thing an error is about, when the failure shape is generic.
- Value
Source - Which layer supplied a value that failed validation.
Constants§
- EXIT_
BROKEN_ PIPE - stdout EPIPE / broken pipe.
- EXIT_
CONFIG - Local configuration error (XDG TOML, origins).
- EXIT_
INTERNAL - Unexpected internal failure.
- EXIT_
INTERRUPTED - SIGINT / Ctrl-C cooperative cancel.
- EXIT_
INVALID_ INPUT - Domain validation failure (invalid crate name, path, pagination).
- EXIT_IO
- Local filesystem failure (sysexits
EX_IOERR, the original meaning of 74). - EXIT_
NETWORK - Transport / network failure or local body budget.
- EXIT_
NOT_ FOUND - Remote resource missing (HTTP 404).
- EXIT_
TERMINATED - SIGTERM / SIGHUP terminate.
- EXIT_
TIMEOUT - Wall-clock deadline exceeded.
- EXIT_
UNAVAILABLE - Rate limit or temporary remote unavailability (HTTP 429/5xx).
- EXIT_
USAGE - Clap / argv usage error (sysexits
EX_USAGE).
Functions§
- io_at
- Map a filesystem failure onto the catalogue, keeping the path that failed.
Type Aliases§
- AppResult
- Result alias for library operations.