Deep Dive

Operations Guide

Production-ready configuration, health probes, structured logging, and telemetry for Ranvier applications.

Production Ops Demo Telemetry Demo Manual Hub

Core Concepts

Configuration System

RanvierConfig: 4-layer loading — defaults, ranvier.toml, profile overrides, environment variables.

Profile Overrides: RANVIER_PROFILE=prod activates [profile.prod] section in ranvier.toml.

HttpIngress::config(): Applies server settings and initializes telemetry from config.

Health & Readiness

health_endpoint(): JSON health status with registered check results.

readiness_liveness_default(): Kubernetes-style /ready and /live probes.

health_check(): Register async health checks (DB connectivity, external service pings).

Request Pipeline

request_id_layer(): Ensures x-request-id propagation on every request/response.

AccessLogGuard: Structured HTTP request/response logging as a Transition node.

Path Redaction: AccessLogGuard.redact_paths() for sensitive endpoints like /auth/login.

Structured Logging

config.init_logging(): Initializes tracing subscriber from config.

Three formats: json (production, machine-readable), pretty (development), compact.

Per-module level overrides via logging.module_levels in ranvier.toml.

Telemetry & OTLP

TelemetryConfig: OTLP endpoint, protocol (gRPC/HTTP), service name, sample ratio.

init_telemetry(): No-op when otlp_endpoint is None; auto-initializes TracerProvider when set.

Inspector /metrics: Prometheus exposition format for Grafana/AlertManager integration.

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

let config = RanvierConfig::load()?;
config.init_logging();

Ranvier::http()
    .config(&config)
    .health_endpoint("/health")
    .readiness_liveness_default()
    .request_id_layer()
    .route("/api", api_axon)
    .run(()).await?;

Primary Workflow

Create ranvier.toml with server, logging, telemetry, and inspector sections.

Load config with RanvierConfig::load() and initialize logging with config.init_logging().

Pass config to HttpIngress::config() to apply server settings and start telemetry.

Add health_endpoint() and readiness_liveness_default() for Kubernetes probes.

Enable request_id_layer() for request tracing correlation.

Add AccessLogGuard to Axon pipelines for structured request logging.

Configure OTLP endpoint via environment variable for production tracing.

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.