cruxi 0.2.0

Minimal, transport-agnostic hexagonal architecture framework
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107

//! # Cruxi
//!
//! A minimal, transport-agnostic hexagonal architecture framework for Rust.
//!
//! Cruxi implements the Ports & Adapters pattern with a 4-layer architecture:
//!
//! ```text
//! ┌──────────────────────────────────────┐
//! │ INBOUND TRANSPORTS                   │
//! │ (HTTP, gRPC, MQTT, TCP)              │
//! └──────────────────────────────────────┘
//!               ↓
//! ┌──────────────────────────────────────┐
//! │ HANDLER (Inbound Adapter)            │
//! │ • Receives requests                  │
//! │ • Validates transport format         │
//! │ • Delegates to Service               │
//! └──────────────────────────────────────┘
//!               ↓
//! ┌──────────────────────────────────────┐
//! │ SERVICE (Application Layer)          │
//! │ • Business logic orchestration       │
//! │ • Authorization checks               │
//! │ • Coordinates Repositories           │
//! └──────────────────────────────────────┘
//!               ↓
//! ┌──────────────────────────────────────┐
//! │ REPOSITORY (Domain Layer)            │
//! │ • Domain validation                  │
//! │ • Transactional integrity            │
//! │ • Calls Providers                    │
//! └──────────────────────────────────────┘
//!               ↓
//! ┌──────────────────────────────────────┐
//! │ PROVIDER (Infrastructure)            │
//! │ • Database I/O                       │
//! │ • HTTP API calls                     │
//! │ • Message queues                     │
//! └──────────────────────────────────────┘
//! ```
//!
//! ## Design Principles
//!
//! - **Zero external dependencies** in the core (only std + thiserror)
//! - **Generic type safety** via trait generics on Req/Resp
//! - **Pattern matching** for all control flow and error handling
//! - **No `.unwrap()`** - explicit error handling throughout
//!
//! ## Collaborators
//!
//! A collaborator is a required dependency that a composite delegates to, provided at
//! construction time.
//!
//! - `ValidatingHandler` collaborators: validator and service
//! - `ValidatingRepository` collaborators: validator, provider, and transaction
//!
//! Intentional no-op behavior is still explicit composition:
//! - use `PassValidator` for no-op validation
//! - use `NoTransaction` for no-op transaction wrapping
//!
//! ## Features
//!
//! - `async` - Enables async trait variants (requires `async-trait`)

#![forbid(unsafe_code)]
#![deny(missing_docs)]
#![deny(clippy::unwrap_used)]
#![deny(clippy::expect_used)]
#![warn(clippy::pedantic)]

mod context;
mod error;
mod handler;
mod provider;
mod repository;
mod service;
mod urn;
mod validator;

pub use context::{
    CancellationHandle, Context, ContextBuilder, DoneReason, Extensions, Principal, RequestId,
    Scopes, Tenant, TraceId, TransportAs,
};
pub use error::{
    CodedError, CruxiError, ErrorClass, ErrorClassMapper, ErrorMappingContext, MessageExposure,
    RetryabilityHint, ValidationError, map_coded_error,
};
pub use handler::{Handler, HandlerFn, ValidatingHandler, ValidatingHandlerError};
pub use provider::{Provider, ProviderFn};
pub use repository::{
    NoTransaction, Repository, RepositoryFn, Transaction, TxError, ValidatingRepository,
    ValidatingRepositoryError,
};
pub use service::{Service, ServiceFn};
pub use urn::{Urn, UrnError};
pub use validator::{FailValidator, PassValidator, Validator, ValidatorFn};

#[cfg(feature = "async")]
pub use handler::AsyncHandler;
#[cfg(feature = "async")]
pub use provider::AsyncProvider;
#[cfg(feature = "async")]
pub use repository::AsyncRepository;
#[cfg(feature = "async")]
pub use service::AsyncService;
#[cfg(feature = "async")]
pub use validator::AsyncValidator;