Deep Dive

Auth & Security

Replace hidden middleware with visible, traceable Guard Transition nodes and IAM boundary verification.

Guard Demo Auth JWT Demo Manual Hub

Core Concepts

Guard Nodes (ranvier-std)

CorsGuard: Validates request origin against allowed origins. Reads RequestOrigin from Bus, writes CorsHeaders.

RateLimitGuard: Per-client token-bucket rate limiting. Reads ClientIdentity from Bus.

SecurityHeadersGuard: Injects HSTS, CSP, X-Frame-Options, X-Content-Type-Options into Bus as SecurityHeaders.

IpFilterGuard: Allow-list or deny-list IP filtering. Reads ClientIp from Bus.

All guards implement Transition<T, T> — pass input through on success, return Fault on reject.

IAM Framework (ranvier-core::iam)

IamVerifier trait: Implement verify(token) -> Result<IamIdentity, IamError> for your auth backend.

IamPolicy: None, RequireIdentity, RequireRole(String), RequireClaims(Vec<String>).

Axon::with_iam(policy, verifier): Automatic boundary verification before any Transition runs.

IamIdentity: Subject, roles, claims — inserted into Bus for downstream access.

IamToken: Bus-injectable bearer token read by the Axon IAM boundary.

Session Patterns

Session creation and validation as Transition nodes (not middleware).

Cookie-based or header-based token extraction via Bus injection.

Expiration and cleanup logic as explicit Transition steps.

Capability Snapshot

Can

Define typed decision flows with Axon/Transition/Outcome contracts, explicit Bus wiring, and `Never` error type for infallible pipelines. 61 maintained examples covering all 10 crates.

Run protocol-agnostic core circuits through HTTP ingress adapters with dynamic routing, request extractors, lifecycle controls, middleware composition, and per-path policy overrides.

Apply HTTP security/policy stacks with `ranvier-std` Guard nodes (CorsGuard, RateLimit, SecurityHeaders, IpFilter) — visible in Schematic and Inspector Timeline.

Generate OpenAPI docs and Swagger UI from request/response contracts via `ranvier-openapi`.

Serve static directories and SPA fallback with cache/compression options for fullstack-style delivery.

Handle WebSocket/SSE real-time flows and inject connection/session context into Bus.

Build LLM-as-Transition pipelines for AI classification, content moderation, and policy enforcement.

Write in-process HTTP integration tests with `TestApp/TestRequest/TestResponse` and runtime path assertions with `AxonTestKit`/`Timeline`.

Store and query traces with `ranvier-inspector` TraceStore, secure endpoints with BearerAuth, and route alerts via AlertHook/AlertDispatcher.

Run session/job/persistence patterns and resume faulted workflows from checkpoints with PersistenceStore and compensation hooks.

Validate API compatibility and detect structural drift with cargo-semver-checks and schematic diff/policy CLI commands.

Monitor per-node metrics (throughput, latency percentiles, error rate), inspect in-transit payloads, manage dead letters, set conditional breakpoints, and detect stalled nodes through the built-in Inspector REST + WebSocket server.

Register JSON Schema on circuit nodes via `.with_input_schema::<T>()` builder API or `#[transition(schema)]` macro attribute. Inspector serves schema-enriched route metadata (`GET /api/v1/routes`), relays HTTP requests into running circuits (`POST /api/v1/relay`), and generates empty templates or random sample payloads from schema (`POST /api/v1/routes/schema`, `POST /api/v1/routes/sample`).

Configure production infrastructure with `RanvierConfig` (`ranvier.toml` + env overrides + profile system), structured logging (`init_logging()` with JSON/pretty/compact), and optional TLS via `rustls`.

Return RFC 7807 Problem Details error responses with `ProblemDetail`/`IntoProblemDetail`, and retry faulted transitions with `RetryPolicy` (fixed/exponential backoff) via `Axon::then_with_retry()`.

Provide quantitative performance baselines with criterion micro-benchmarks (Axon latency, Bus operations, Transition chains) and Axum/Actix-web comparison servers.

Demonstrate real-world patterns through three reference applications: Todo API (CRUD + JWT auth), Chat Server (multi-room WebSocket), and E-commerce Order Pipeline (4-stage Saga compensation + audit trail + multi-tenancy).

Automate version migration with `ranvier migrate --from 0.20 --to 0.25` for import path replacement, crate dependency swaps. TOML-based migration rules (text_replace, rename_import, warn) with --dry-run mode.

Export Prometheus exposition metrics from Inspector `/metrics` endpoint, auto-initialize OTLP TracerProvider via TelemetryConfig, log HTTP requests with AccessLogGuard path redaction, persist audit events to PostgreSQL with PostgresAuditSink hash-chain integrity, and auto-register OpenAPI SecurityScheme (bearerAuth) with ProblemDetail (RFC 7807) error responses.

Understand framework design philosophy through PHILOSOPHY.md ('Opinionated Core, Flexible Edges' principle) and architecture decision rationale via DESIGN_PRINCIPLES.md (ADR format covering Paradigm Test, Tower Separation, and Opinionated Core enforcement).

Implement authentication using two approaches: Transition-based (examples/auth-transition — Bus context propagation, Schematic visualization, easier testing) or Tower integration (examples/auth-tower-integration — AsyncAuthorizeRequest trait for ecosystem compatibility).

Compare authentication strategies with docs/guides/auth-comparison.md: 7-feature comparison table, performance benchmarks (~1-2μs overhead both), when-to-use decision tree, and migration paths between Transition and Tower approaches.

Cannot yet

Token/claim-to-role mapping for inspector auth headers is not built into core runtime and depends on deployment gateway policy.

Quickstart

// Guard pipeline: 4 security Transitions in one Axon
let pipeline = Axon::new("Guarded API")
    .then(CorsGuard::new(CorsConfig::default()))
    .then(RateLimitGuard::new(100, 60_000))
    .then(SecurityHeadersGuard::new(SecurityPolicy::new()))
    .then(IpFilterGuard::allow_list(["127.0.0.1"]));

// IAM boundary: automatic JWT verification
let admin = Axon::new("admin")
    .with_iam(IamPolicy::RequireRole("admin".into()), JwtVerifier)
    .then(AdminDashboard);

Primary Workflow

Add Guard nodes to your Axon pipeline with .then() for layered HTTP security.

Implement IamVerifier for your JWT/OAuth/API-key backend.

Attach IamPolicy via Axon::with_iam() for automatic boundary verification.

Read IamIdentity from Bus in downstream Transitions for user context.

Inject RequestOrigin, ClientIp, ClientIdentity from your HTTP adapter layer.

Verification Commands

Workspace example build cargo check --workspace

Typed flow example run cargo run -p typed-state-tree

HTTP routing and extractor example run cargo run -p routing-params-demo

HTTP graceful shutdown hooks test cargo test -p ranvier-http

HTTP in-process test harness + health probes cargo test -p ranvier-http --test test_app_health

HTTP request validation feature cargo test -p ranvier-http --features validation

Validation struct-level example run cargo run -p ranvier-http --example validation_struct_level --features validation

Std Guard nodes (CorsGuard/RateLimit/SecurityHeaders/IpFilter) tests cargo test -p ranvier-std guard

OpenAPI generator tests cargo test -p ranvier-openapi

OpenAPI demo compile cargo check -p openapi-demo

Static serving + SPA fallback tests cargo test -p ranvier-http

Static SPA demo compile cargo check -p static-spa-demo

WebSocket ingress upgrade + Event bridge tests cargo test -p ranvier-http

WebSocket ingress demo compile cargo check -p websocket-ingress-demo

Inspector TraceStore + BearerAuth tests cargo test -p ranvier-inspector

Workspace full test sweep cargo test --workspace

Examples smoke baseline (M119) ./scripts/m119_examples_smoke.ps1

Inspector quick-view smoke ./scripts/m131_inspector_quickview_smoke.ps1

Schematic diff/policy smoke ./scripts/m131_schematic_diff_policy_smoke.ps1

Fullstack embedded static smoke ./scripts/m131_fullstack_embedded_smoke.ps1

Runtime timeline integration assertion cargo test -p ranvier-runtime timeline_assertion_works_in_integration_test

M132 SeaORM ecosystem reference run cargo run -p ecosystem-seaorm-demo

M132 Diesel ecosystem reference run cargo run -p ecosystem-diesel-demo

M132 Redis ecosystem reference run cargo run -p ecosystem-redis-demo

M132 NATS ecosystem reference run cargo run -p ecosystem-nats-demo

M132 Meilisearch ecosystem reference run cargo run -p ecosystem-meilisearch-demo

Session pattern example compile cargo check -p session-pattern

Inspector metrics + stall detection tests cargo test -p ranvier-inspector metrics stall

Inspector conditional breakpoint + payload capture tests cargo test -p ranvier-inspector breakpoint payload

Ecosystem: crates.io

Version: 0.30.0

Status: released

For latest capability status and artifact versions, check /status.