Tutorial

Build your first Ranvier circuit.

This walkthrough uses the facade crate for a minimal HTTP ingress circuit and then points you to canonical examples for deeper workflows.

1. Install Dependencies

cargo add ranvier
cargo add tokio --features full
cargo add anyhow
cargo add async-trait

2. Define a Transition

use async_trait::async_trait;
use ranvier::prelude::*;

#[derive(Clone)]
struct Hello;

#[async_trait]
impl Transition<(), String> for Hello {
    type Error = anyhow::Error;
    type Resources = ();

    async fn run(
        &self,
        _state: (),
        _resources: &Self::Resources,
        _bus: &mut Bus,
    ) -> Outcome<String, Self::Error> {
        Outcome::Next("Hello, Ranvier!".to_string())
    }
}

3. Wire the Ingress Builder

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let hello = Axon::<(), (), anyhow::Error>::new("Hello")
        .then(Hello);

    Ranvier::http()
        .bind("127.0.0.1:3000")
        .route("/", hello)
        .run(())
        .await
        .map_err(|e| anyhow::anyhow("{}", e))?;

    Ok(())
}

Run the server with cargo run, then open http://127.0.0.1:3000.

4. Explore Canonical Examples (Repository)

Hello World (HTTP)

cargo run -p hello-world

Typed State Tree

cargo run -p typed-state-tree

Schematic Baseline

cargo run -p basic-schematic

5. Export a Schematic

ranvier schematic basic-schematic --output schematic.json

6. Generate Trace Projections

ranvier status projection-from-example order-processing-demo \
  --output ./dist/trace-order \
  --service "Ranvier Service" \
  --circuit-id order_processing \
  --circuit-version 0.1.0