orion_error/lib.rs
1//! # orion-error — structured error governance for large Rust codebases
2//!
3//! ## Decision flow
4//!
5//! When you have an error, the question is: **what do you need to do with it?**
6//!
7//! ```text
8//! ┌─ I have an error ──────────────────────────────────────────┐
9//! │ │
10//! │ Need to print it for a human? │
11//! │ → err.report().render() │
12//! │ │
13//! │ Need to return it to an HTTP/RPC/CLI boundary? │
14//! │ → err.exposure_snapshot(&policy).to_http_error_json() │
15//! │ → err.exposure_snapshot(&policy).to_rpc_error_json() │
16//! │ → err.exposure_snapshot(&policy).to_cli_error_json() │
17//! │ │
18//! │ Need a stable machine-readable snapshot? │
19//! │ → err.snapshot().stable_export() │
20//! │ │
21//! │ Need to bridge to std::error::Error? │
22//! │ → err.as_std() / err.into_std() / err.into_dyn_std() │
23//! │ │
24//! │ Just need to log and move on? │
25//! │ → err.display_chain() │
26//! │ → report::print_error(&err) │
27//! └─────────────────────────────────────────────────────────────┘
28//! ```
29//!
30//! The key boundary:
31//!
32//! - [`StructError::report()`] gives you a [`DiagnosticReport`] — human diagnostics,
33//! redaction, text rendering. Only requires [`DomainReason`].
34//! - [`StructError::exposure_snapshot()`] gives you an [`ErrorProtocolSnapshot`] —
35//! identity + exposure decision + report, the unified protocol input.
36//! Requires [`DomainReason`] + [`ErrorIdentityProvider`].
37//!
38//! If you only have [`DomainReason`], you can always `report()`. If you
39//! also implement [`ErrorIdentityProvider`] (via `#[derive(OrionError)]`),
40//! you can use `exposure_snapshot()` and the full protocol projection stack.
41mod core;
42pub mod testcase;
43mod traits;
44
45extern crate self as orion_error;
46
47#[cfg(feature = "derive")]
48pub use orion_error_derive::{ErrorCode, ErrorIdentityProvider, OrionError};
49
50pub use core::{DefaultExposurePolicy, DomainReason, OperationContext, StructError, UvsReason};
51pub use traits::{ErrorWith, ErrorWrapAs, IntoAs};
52
53#[doc(hidden)]
54pub use core::{
55 ErrorCategory, ErrorCode, ErrorIdentityProvider, UvsFrom, Visibility,
56};
57#[doc(hidden)]
58pub use traits::ErrorConv;
59
60/// Primary-path traits and types for convenient wildcard imports.
61///
62/// # Example
63/// ```rust,ignore
64/// use orion_error::prelude::*;
65/// ```
66pub mod prelude {
67 pub use crate::core::{DefaultExposurePolicy, StructError};
68 pub use crate::traits::{ErrorWith, ErrorWrapAs, IntoAs};
69 #[cfg(feature = "derive")]
70 pub use crate::OrionError;
71}
72
73/// Wildcard imports for protocol/schema checks and migration-oriented tests.
74///
75/// Prefer [`prelude`] for new application code. Use this module when a test or
76/// verification task intentionally needs broad access to projection, snapshot,
77/// bridge, and conversion surfaces in one place.
78pub mod advanced_prelude {
79 pub use crate::core::{
80 DefaultExposurePolicy, DiagnosticReport, ErrorCategory, ErrorCode,
81 ErrorIdentity, ErrorIdentityProvider, ErrorMetadata,
82 ErrorProtocolSnapshot, ErrorSnapshot, ExposureDecision,
83 ExposurePolicy, IntoSourcePayload, OwnedDynStdStructError,
84 OwnedStdStructError, RedactPolicy, SnapshotContextFrame, SnapshotSourceFrame,
85 SourceFrame, SourcePayload, SourcePayloadKind, SourcePayloadRef, StableErrorSnapshot,
86 StableSnapshotContextFrame, StableSnapshotSourceFrame, StdStructRef, StructError,
87 UvsFrom, UvsReason, Visibility, STABLE_SNAPSHOT_SCHEMA_VERSION,
88 };
89 pub use crate::traits::{
90 raw_source, ConvStructError, ErrorConv, ErrorWith, ErrorWrapAs, IntoAs, RawSource,
91 RawStdError, ToStructError, WrapStructErrorAs,
92 };
93 #[cfg(feature = "derive")]
94 pub use crate::OrionError;
95}
96
97/// Compatibility wildcard imports for legacy conversion APIs.
98///
99/// Use this only when maintaining older `owe(...)` call paths.
100pub mod compat_prelude {
101 #![allow(deprecated)]
102 pub use crate::traits::{
103 ErrorOwe, ErrorOweBase, ErrorOweSource, ErrorOweSourceBase,
104 };
105}
106
107/// Shared data carriers and enums that are still convenient outside the
108/// layered namespaces.
109pub mod types {
110 pub use crate::core::{
111 ConfErrReason, DiagnosticReport, ErrStrategy, ErrorCategory, ErrorIdentity,
112 ErrorIdentityProvider, ErrorMetadata, ErrorProtocolSnapshot, ExposureDecision,
113 MetadataValue, OperationContext, OperationScope, StructError, StructErrorBuilder,
114 UvsReason, Visibility, WithContext,
115 };
116}
117
118/// Runtime-layer types.
119///
120/// These are the primary carriers used while an error is still moving through
121/// application code.
122pub mod runtime {
123 pub use crate::core::{
124 ContextRecord, ErrorMetadata, MetadataValue, OperationContext, OperationScope, SourceFrame,
125 SourcePayload, SourcePayloadKind, SourcePayloadRef, StructError, StructErrorBuilder,
126 WithContext,
127 };
128}
129
130/// Explicit bridge types for entering the standard error ecosystem.
131pub mod bridge {
132 pub use crate::core::{
133 IntoSourcePayload, OwnedDynStdStructError, OwnedStdStructError, SourcePayload,
134 SourcePayloadKind, SourcePayloadRef, StdStructRef,
135 };
136 pub use crate::traits::{raw_source, RawSource, RawStdError};
137}
138
139/// Snapshot-layer types and stable snapshot schema exports.
140pub mod snapshot {
141 pub use crate::core::{
142 ErrorIdentity, ErrorSnapshot, SnapshotContextFrame, SnapshotSourceFrame,
143 StableErrorSnapshot, StableSnapshotContextFrame, StableSnapshotSourceFrame,
144 STABLE_SNAPSHOT_SCHEMA_VERSION,
145 };
146}
147
148/// Report-layer types for rendering and redaction.
149pub mod report {
150 pub use crate::core::{
151 DefaultExposurePolicy, DiagnosticReport, ErrorProtocolSnapshot, ExposureDecision,
152 ExposurePolicy, RedactPolicy, Visibility,
153 };
154 pub use crate::core::cli::print_error;
155}
156
157/// Reason-layer enums and traits.
158pub mod reason {
159 pub use crate::core::{
160 ConfErrReason, DomainReason, ErrorCategory, ErrorCode, ErrorIdentityProvider, UvsFrom,
161 UvsReason,
162 };
163}
164
165/// Conversion traits for the current primary paths.
166pub mod conversion {
167 pub use crate::traits::{
168 ErrorConv, ErrorWith, ErrorWrapAs, IntoAs, ToStructError, WrapStructErrorAs,
169 };
170}
171
172/// Advanced conversion helpers that are not part of the default import path.
173pub mod conversion_ext {
174 pub use crate::traits::ConvStructError;
175}
176
177/// Grouped conversion and context extension traits.
178pub mod traits_ext {
179 pub use crate::runtime::ContextRecord;
180 pub use crate::traits::{
181 ConvStructError, ErrorConv, ErrorWith, ErrorWrapAs, IntoAs, ToStructError,
182 WrapStructErrorAs,
183 };
184 pub use crate::{ErrorCode, UvsFrom};
185}
186
187/// Compatibility trait exports for legacy conversion helpers.
188pub mod compat_traits {
189 #![allow(deprecated)]
190 pub use crate::traits::{
191 ErrorOwe, ErrorOweBase, ErrorOweSource, ErrorOweSourceBase,
192 };
193}