Crate orion_error 

orion-error — structured error governance for large Rust codebases

Decision flow

When you have an error, the question is: what do you need to do with it?

┌─ I have an error ──────────────────────────────────────────┐
│                                                             │
│  Need to print it for a human?                              │
│    → err.report().render()                                  │
│                                                             │
│  Need to return it to an HTTP/RPC/CLI boundary?             │
│    → err.exposure(&policy).to_http_error_json()    │
│    → err.exposure(&policy).to_rpc_error_json()     │
│    → err.exposure(&policy).to_cli_error_json()     │
│                                                             │
│  Need to bridge to std::error::Error?                       │
│    → err.as_std() / err.into_std() / err.into_dyn_std()    │
│                                                             │
│  Just need to log and move on?                              │
│    → err.display_chain()                                    │
│    → cli::print_error(&err)                                 │
└─────────────────────────────────────────────────────────────┘

The key boundary:

• StructError::report() gives you a [DiagnosticReport] — human diagnostics, redaction, text rendering. Only requires reason::DomainReason.
• StructError::exposure() gives you an [ErrorProtocolSnapshot] — identity + exposure decision + report, the unified protocol input. Requires reason::DomainReason + reason::ErrorIdentityProvider.

If you only have reason::DomainReason, you can always report(). If you also implement reason::ErrorIdentityProvider (via #[derive(OrionError)]), you can use exposure() and the full protocol projection stack.

Module split:

• report is the human-facing diagnostics layer
• protocol is the protocol/exposure projection layer

Root-surface guardrails:

• derive macros stay importable from the crate root
• runtime identity traits live under reason
• removed root trait/type re-exports and old extension modules must not drift back

use orion_error::DomainReason;

use orion_error::ErrorCode;

trait NeedsRootTrait: ErrorCode {}

use orion_error::ErrorIdentityProvider;

fn accepts_root_trait<T: ErrorIdentityProvider>(_value: &T) {}

use orion_error::bridge::*;

use orion_error::testing::*;

use orion_error::test_prelude::*;

use orion_error::ErrorWith;

use orion_error::ErrorWrapAs;

use orion_error::IntoAs;

use orion_error::{StructError, UnifiedReason};

let _ = StructError::from(UnifiedReason::system_error())
    .attach_source(std::io::Error::other("disk offline"));

use orion_error::types::ErrorIdentity;

use orion_error::DefaultExposurePolicy;

use orion_error::traits_ext::*;

use orion_error::{StructError, UnifiedReason};

let report = StructError::from(UnifiedReason::system_error()).report();
let _ = report.projection;

use orion_error::report::print_error;

use orion_error::{StructError, UnifiedReason};

let report = StructError::from(UnifiedReason::system_error()).report();
let _ = report.path();

use orion_error::{StructError, UnifiedReason};

let report = StructError::from(UnifiedReason::system_error()).report();
let _ = report.root_metadata();

use orion_error::{StructError, UnifiedReason};

let report = StructError::from(UnifiedReason::system_error()).report();
let _ = report.source_frames();

use orion_error::{OperationContext, StructError, UnifiedReason};

let _ = OperationContext::doing("load config").target();
let _ = StructError::from(UnifiedReason::system_error()).target_main();

use orion_error::protocol::DefaultExposurePolicy;
use orion_error::{StructError, UnifiedReason};

let proto = StructError::from(UnifiedReason::system_error())
    .exposure(&DefaultExposurePolicy);
let _ = proto.report();

// This example requires the `derive` feature (enabled by default).
use orion_error::OrionError;
use orion_error::reason::{ErrorCategory, ErrorCode, ErrorIdentityProvider};

#[derive(Debug, Clone, PartialEq, OrionError)]
enum DemoReason {
    #[orion_error(identity = "logic.demo_reason")]
    Demo,
}

let reason = DemoReason::Demo;
assert_eq!(reason.error_code(), 500);
assert_eq!(reason.stable_code(), "logic.demo_reason");
assert_eq!(reason.error_category(), ErrorCategory::Logic);

Modules

cli

CLI-side output helpers.

conversion

Conversion traits for the current primary paths.

dev

Development and validation-only helpers.

interop

Standard-error ecosystem interop: bridge types for entering the standard std::error::Error ecosystem.

prelude

Primary-path traits and types for convenient wildcard imports.

protocol

Protocol/exposure-layer types for boundary projections.

reason

Reason-layer enums and traits.

report

Report-layer types for rendering and redaction.

runtime

Runtime-layer types.

Macros

location

op_context

Expands module_path!() at the call site so log output automatically reflects the correct module path.

Structs

ErrorIdentity

Identity-first snapshot view of a StructError.

OperationContext

StructError

Enums

UnifiedReason

Universal error reason classification with clear hierarchical structure 统一错误原因分类 - 采用清晰的分层结构

Functions

convert_error

Derive Macros

ErrorCode

ErrorIdentityProvider

OrionError