Ranvier
KR

#Getting Started with Ranvier

Version: 0.51.0 Updated: 2026-07-16 Category: Getting Started

This page is the navigation contract after the canonical quickstart. It does not introduce a second dependency recipe.

#1. Start here

Complete the canonical quickstart. It is the only first-user installation path and uses the public ranvier facade with Rust 1.93.0 or newer.

#2. Learn the candidate spine through three workflows

  1. Typed state progression — Transition, typed Axon handoff, Outcome.
  2. Typed JSON native HTTP — supported native ingress and typed request/response boundaries.
  3. Bus capability policy — explicit resource and request-context access.

All three are Canonical or Supported and compile in recurring gates without external runtime services.

#3. Choose the HTTP edge deliberately

  • New decision-oriented service: stay on native Ranvier::http().
  • Existing Axum service: use the Axum + Ranvier hybrid guide and bridge only the state the Axon needs.
  • Simple CRUD or proxy with no decision pipeline: prefer Axum alone; Ranvier is not a mandatory wrapper around every endpoint.

#4. Deepen the stable path

  • Hello World tutorial
  • API stability contract
  • Testing patterns
  • Production readiness checklist

The former long-form onboarding material is retained here as a bounded map rather than as another setup recipe:

#Transition composition and testing

  • .then() requires the previous Next output to match the next transition's input at compile time.
  • Test a transition as a plain async unit, then test the complete Axon with execute() and an explicit Bus.
  • Runnable references: `typed-state-tree` and `testing-patterns`.

#Errors and outcome boundaries

  • Use a domain error enum, commonly derived with thiserror, for Fault.
  • Next and Fault retain Rust types. Schema-described Branch, Jump, and Emit payloads cross a runtime validation boundary.
  • Runnable reference: `custom-error-types`.

#Bus, resources, and authoritative state

  1. Use Bus for execution-scoped capabilities that move through one decision path. Capability presence and access policy are runtime checks.
  2. Use Resources: ResourceRequirement for process-local infrastructure handles such as DB pools, configuration, HTTP clients, or cache clients.
  3. Use an external authoritative system for mutable state that must remain consistent across multiple service instances.

Ranvier does not turn Resources into a hidden dependency-injection container and does not provide a framework-owned ORM or mocking DSL. Keep ecosystem clients behind explicit resources and replace those handles in tests.

#Resilience and persistence

  • Add retry/DLQ policy only after the transition boundary and idempotency model are explicit; inspect Timeline events for retry and DLQ activity.
  • Use checkpoint/resume for long-running workflows and choose trace lifecycle and authoritative persistence deliberately.
  • Runnable references: `retry-dlq-demo` and `state-persistence-demo`.
  • Operations references: persistence runbook and production evidence pack.

#5. Explore Lab and experimental material last

Only after the stable path works should you browse Lab or experimental entries in the Examples Explorer. They are not part of routine Developer or Release support.