Crate cruxi 

Cruxi

A minimal, transport-agnostic hexagonal architecture framework for Rust.

Cruxi implements the Ports & Adapters pattern with a 4-layer architecture:

┌──────────────────────────────────────┐
│ 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)

Structs

CancellationHandle

Shared cancellation handle for a context runtime.

CodedError

A structured error with a machine-readable code.

Context

Request-scoped context carrying cancellation, deadline, and extension data.

ContextBuilder

Builder for constructing Context instances.

ErrorMappingContext

Transport-agnostic mapping context derived from a CodedError.

Extensions

Type-safe storage for arbitrary values in a context.

FailValidator

A validator that always fails with the given error.

HandlerFn

Adapts a function to the Handler trait.

NoTransaction

A no-op transaction that just executes the function directly.

PassValidator

A validator that always passes.

Principal

Typed principal metadata value.

ProviderFn

Adapts a function to the Provider trait.

RepositoryFn

Adapts a function to the Repository trait.

RequestId

Typed request-id metadata value.

Scopes

Typed scopes metadata value.

ServiceFn

Adapts a function to the Service trait.

Tenant

Typed tenant metadata value.

TraceId

Typed trace-id metadata value.

Urn

A Unified Resource Name for stable resource references.

ValidatingHandler

A handler that validates requests before delegating to a service.

ValidatingRepository

A repository that validates input and wraps provider calls in a transaction collaborator.

ValidationError

A field-level validation error.

ValidatorFn

Adapts a function to the Validator trait.

Enums

CruxiError

Sentinel errors for common framework conditions.

DoneReason

Completion reason for context lifecycle.

ErrorClass

Transport-agnostic error classification for adapter mapping.

MessageExposure

Whether an adapter can safely expose the user-facing error message.

RetryabilityHint

Retryability hint for policy engines and adapters.

TxError

Error combining transaction failures with inner operation failures.

UrnError

Errors that can occur when parsing or constructing URNs.

ValidatingHandlerError

Error type for ValidatingHandler.

ValidatingRepositoryError

Error type for ValidatingRepository.

Traits

ErrorClassMapper

Contract for adapter-facing error mapping.

Handler

Receives inbound requests and delegates to a service.

Provider

Performs infrastructure I/O operations.

Repository

Validates data and enforces transactional integrity.

Service

Orchestrates business logic and coordinates repositories.

Transaction

Wraps operations in a unit of work.

TransportAs

Helper trait for type-safe transport payload extraction.

Validator

Validates input and returns its configured error type on failure.

Functions

map_coded_error

Maps a CodedError to an adapter decision via an ErrorClassMapper.