#Ranvier Philosophy: Opinionated Core, Flexible Edges

use ranvier::prelude::*;

#[transition]
async fn validate_input(req: Request) -> Outcome<ValidRequest, ValidationError> {
    if req.body.is_empty() {
        return Outcome::err(ValidationError::EmptyBody);
    }
    Outcome::ok(ValidRequest::from(req))
}

#[transition]
async fn process(input: ValidRequest) -> Outcome<Response, ProcessError> {
    // Business logic here
    let result = compute(&input).await?;
    Outcome::ok(Response::new(result))
}

// Compose:
let pipeline = Axon::simple::<AppError>()
    .pipe(validate_input, process)
    .build();

// Transition returns Outcome
#[transition]
async fn fetch_user(id: UserId) -> Outcome<User, DatabaseError> {
    match db.get_user(id).await {
        Ok(user) => Outcome::ok(user),
        Err(e) => Outcome::err(DatabaseError::from(e)),
    }
}

// Outcome values automatically stored in Bus if marked
#[transition]
async fn enrich_user(user: User) -> Outcome<EnrichedUser, EnrichmentError> {
    // 'user' came from Bus (injected automatically)
    let profile = fetch_profile(&user).await?;
    Outcome::ok(EnrichedUser { user, profile })
}

#[transition]
async fn authenticate(req: Request) -> Outcome<AuthContext, AuthError> {
    let token = extract_token(&req)?;
    let auth = validate(token).await?;
    // AuthContext automatically stored in Bus for downstream transitions
    Outcome::ok(auth)
}

#[transition]
async fn authorize(auth: &AuthContext) -> Outcome<(), AuthError> {
    // 'auth' automatically injected from Bus (by type)
    if !auth.has_role("admin") {
        return Outcome::err(AuthError::Unauthorized);
    }
    Outcome::ok(())
}

#[transition]
async fn handle_request(auth: &AuthContext, req: &Request) -> Outcome<Response, AppError> {
    // Both 'auth' and 'req' injected from Bus
    Ok(Response::new(format!("Hello, {}", auth.user_id)))
}

// Build a schematic
let schematic = Axon::simple::<AppError>()
    .pipe(authenticate, authorize, handle_request)
    .build();

// Execute
let outcome = schematic.execute(request).await;

// Export to JSON (for VSCode visualization)
let json = schematic.to_json();
std::fs::write("schematic.json", json)?;

┌─────────────┐    ┌──────────┐    ┌────────────────┐
│ authenticate│───▶│ authorize│───▶│ handle_request │
│             │    │          │    │                │
│ Output:     │    │ Input:   │    │ Input:         │
│ AuthContext │    │ &AuthCtx │    │ &AuthCtx, &Req │
└─────────────┘    └──────────┘    └────────────────┘

// ❌ Confusion in a flexible framework:
// "Do I use middleware? Extractors? Guards? Service layers?"

// ✅ Clarity in Ranvier:
// "Write a Transition. Chain with .pipe(). Done."
#[transition]
async fn my_logic(input: Input) -> Outcome<Output, Error> {
    // Business logic here
}

src/
├── transitions/   # Business logic (Transition functions)
├── outcomes/      # Domain types
├── schematics/    # Pipeline composition
└── main.rs        # Axon setup

use tower::ServiceBuilder;
use tower_http::cors::CorsLayer;
use ranvier::prelude::*;

// Tower handles infrastructure (CORS, tracing, timeouts)
let app = ServiceBuilder::new()
    .layer(CorsLayer::permissive())
    .layer(TraceLayer::new_for_http())
    .layer(TimeoutLayer::new(Duration::from_secs(30)))
    .service(ranvier_handler);

// Ranvier handles business logic (inside ranvier_handler)
#[transition]
async fn business_logic(req: Request) -> Outcome<Response, AppError> {
    // Pure business logic, no infrastructure concerns
}

// Legacy Tower auth layer (keep it, it works)
let auth_layer = RequireAuthorizationLayer::new(...);

// New Ranvier business logic (get visualization)
#[transition]
async fn new_feature(auth: &AuthContext) -> Outcome<Response, Error> {
    // Modern code with Schematic visualization
}

// Combine
let app = ServiceBuilder::new()
    .layer(auth_layer)  // Tower (legacy)
    .service(ranvier_pipeline);  // Ranvier (new)

// ✅ Core: Business logic as Transition
#[transition]
async fn validate_order(order: Order) -> Outcome<ValidOrder, ValidationError> {
    if order.items.is_empty() {
        return Outcome::err(ValidationError::EmptyOrder);
    }
    Outcome::ok(ValidOrder::from(order))
}

// ✅ Core: State in Bus
#[transition]
async fn calculate_tax(order: &ValidOrder, tax_rate: &TaxRate) -> Outcome<Tax, TaxError> {
    // tax_rate injected from Bus
}

// ✅ Core: Composition with Axon
let pipeline = Axon::simple()
    .pipe(validate_order, calculate_tax, apply_discount)
    .build();

// ❌ Don't: Regular function instead of Transition
async fn my_logic(input: Input) -> Result<Output, Error> {
    // Won't appear in Schematic, can't compose with .pipe()
}

// ❌ Don't: Global state instead of Bus
static AUTH: Mutex<Option<AuthContext>> = Mutex::new(None);
// Implicit dependencies, not testable, not visualized

// ✅ Edge: Tower middleware
use tower::ServiceBuilder;
use tower_http::cors::CorsLayer;

let app = ServiceBuilder::new()
    .layer(CorsLayer::permissive())
    .service(ranvier_handler);

// ✅ Edge: sqlx for database
#[transition]
async fn fetch_user(pool: &PgPool, id: UserId) -> Outcome<User, DbError> {
    let user = sqlx::query_as("SELECT * FROM users WHERE id = $1")
        .bind(id)
        .fetch_one(pool)
        .await?;
    Outcome::ok(user)
}

// ✅ Edge: redis for caching
#[transition]
async fn get_cached(cache: &RedisPool, key: &str) -> Outcome<String, CacheError> {
    let value = cache.get(key).await?;
    Outcome::ok(value)
}

// Option A: Transition (Ranvier way, visualized)
#[transition]
async fn authenticate(req: Request) -> Outcome<AuthContext, AuthError> {
    // Appears in Schematic graph
}

// Option B: Tower (ecosystem way, not visualized)
let app = ServiceBuilder::new()
    .layer(RequireAuthorizationLayer::new(...))
    .service(ranvier_handler);

// Helper function (outside Transition) — Result OK
fn parse_config(path: &Path) -> Result<Config, ConfigError> {
    // ...
}

// Transition (core) — Outcome required
#[transition]
async fn load_config(path: &Path) -> Outcome<Config, AppError> {
    let config = parse_config(path)
        .map_err(AppError::from)?;  // Convert Result → Outcome
    Outcome::ok(config)
}

// Request-scoped: Bus (changes per request)
#[transition]
async fn handler(auth: &AuthContext, tenant: &TenantId) -> Outcome<...> {
    // auth, tenant from Bus
}

// Global shared: Axum State (same for all requests)
async fn axum_route(
    State(pool): State<PgPool>,
    State(schematic): State<Schematic>,
) -> Response {
    // pool, schematic shared across requests
}

// Simple case: Tower middleware (not visualized)
let app = ServiceBuilder::new()
    .layer(ValidateRequestHeaderLayer::bearer("secret"))
    .service(ranvier_handler);

// Complex case: Transition (visualized)
#[transition]
async fn authenticate(req: Request) -> Outcome<AuthContext, AuthError> { /*...*/ }

#[transition]
async fn check_subscription(auth: &AuthContext) -> Outcome<(), AuthError> { /*...*/ }

#[transition]
async fn authorize(auth: &AuthContext, required_role: &str) -> Outcome<(), AuthError> { /*...*/ }

let pipeline = Axon::simple()
    .pipe(authenticate, check_subscription, authorize, handle_request)
    .build();

use tower::ServiceBuilder;
use tower_http::cors::{CorsLayer, Any};

let app = ServiceBuilder::new()
    .layer(
        CorsLayer::new()
            .allow_origin(Any)
            .allow_methods(Any)
    )
    .service(ranvier_handler);

// Use any DB library inside a Transition
#[transition]
async fn fetch_user(pool: &PgPool, id: UserId) -> Outcome<User, DbError> {
    let user = sqlx::query_as!(User, "SELECT * FROM users WHERE id = $1", id)
        .fetch_one(pool)
        .await
        .map_err(DbError::from)?;
    Outcome::ok(user)
}

#[transition]
async fn update_balance(user: &User, amount: i64) -> Outcome<(), DbError> {
    // Appears in Schematic: fetch_user → update_balance
    sqlx::query!("UPDATE users SET balance = balance + $1 WHERE id = $2", amount, user.id)
        .execute(pool)
        .await?;
    Outcome::ok(())
}

use tower_http::trace::TraceLayer;

let app = ServiceBuilder::new()
    .layer(TraceLayer::new_for_http())  // Automatic tracing
    .service(ranvier_handler);

// Or manual instrumentation inside Transition:
#[transition]
async fn process(input: Input) -> Outcome<Output, Error> {
    tracing::info!("Processing input: {:?}", input);
    // ...
}

// Tower upgrades HTTP → WebSocket
let ws_layer = WebSocketUpgrade::new(|socket| async {
    // Inside WebSocket handler:
    while let Some(msg) = socket.recv().await {
        // Ranvier Transition processes each message
        let outcome = message_pipeline.execute(msg).await;
        socket.send(outcome.into()).await;
    }
});

START
  │
  ├─ Core business logic? ───Yes──> Ranvier way (Transition)
  │
  ├─ Need visualization? ────Yes──> Ranvier way
  │
  ├─ Pure infrastructure? ───Yes──> Ecosystem way (Tower/library)
  │
  ├─ Migrating existing? ────Yes──> Hybrid (Tower + Ranvier)
  │
  └─ Default ────────────────────> Ranvier way (when in doubt)

                    START: "Should I use Ranvier, Tower, or both?"
                                      │
                                      ▼
        ┌─────────────────────────────────────────────────────┐
        │  Q1: Are you starting a NEW project from scratch?   │
        └─────────────────────────────────────────────────────┘
                 │                                │
                YES                              NO
                 │                                │
                 ▼                                ▼
        ┌───────────────────┐         ┌─────────────────────────┐
        │ Ranvier Way       │         │ Q2: Existing codebase?  │
        │ (Transition)      │         └─────────────────────────┘
        │                   │                     │
        │ ✅ Recommended:   │         ┌───────────┴──────────────┐
        │ - Full visibility │        YES                        NO
        │ - Clean slate     │         │                          │
        │ - Best practices  │         ▼                          ▼
        └───────────────────┘  ┌──────────────┐      ┌──────────────────┐
                               │ Tower app?   │      │ Other framework? │
                               └──────────────┘      └──────────────────┘
                                      │                       │
                              ┌───────┴────────┐             │
                             YES               NO             │
                              │                 │             │
                              ▼                 ▼             ▼
                     ┌────────────────┐  ┌─────────────┐  ┌────────────┐
                     │ Hybrid         │  │ actix/Axum? │  │ Standalone │
                     │ (Tower +       │  └─────────────┘  │ service?   │
                     │  Ranvier)      │         │         └────────────┘
                     │                │    ┌────┴─────┐        │
                     │ ✅ Start:      │   YES        NO         │
                     │ - Keep Tower   │    │          │         ▼
                     │   layers       │    ▼          ▼    ┌──────────┐
                     │ - Add Ranvier  │ ┌─────┐  ┌──────┐ │ Ranvier  │
                     │   for new      │ │Embed│  │Custom│ │ with     │
                     │   features     │ │in   │  │      │ │ ecosystem│
                     └────────────────┘ │actix│  │wrap  │ │ tools    │
                                        └─────┘  └──────┘ └──────────┘

# Create new project
cargo new my-app
cd my-app

# Add Ranvier
cargo add ranvier --features http

# Write first transition
cat > src/main.rs <<'EOF'
use ranvier::prelude::*;

#[transition]
async fn hello() -> Outcome<String, Never> {
    Outcome::ok("Hello from Ranvier!".into())
}

#[tokio::main]
async fn main() {
    let app = Axon::simple().pipe(hello).build();
    // Setup HTTP server...
}
EOF

// Week 1: Keep ALL Tower layers, add Ranvier for ONE new endpoint
let existing_tower_app = ServiceBuilder::new()
    .layer(CorsLayer::permissive())
    .layer(AuthLayer::new(...))
    .layer(TraceLayer::new())
    .service(tower_router);  // Keep existing

// Add Ranvier handler for new feature
#[transition]
async fn new_feature() -> Outcome<Response, Error> {
    // New code uses Ranvier
}

// Week 2-4: Convert more endpoints to Ranvier
// Week 5+: Optionally convert Tower auth to Ranvier Transition

use actix_web::{web, App, HttpServer, HttpResponse};
use ranvier::prelude::*;

// Ranvier transition
#[transition]
async fn process(input: String) -> Outcome<String, Error> {
    // Business logic
    Outcome::ok(input.to_uppercase())
}

// actix handler calls Ranvier
async fn actix_handler(body: String) -> HttpResponse {
    let schematic = Axon::simple().pipe(process).build();
    match schematic.execute(body).await {
        Ok(result) => HttpResponse::Ok().body(result),
        Err(e) => HttpResponse::InternalServerError().body(e.to_string()),
    }
}

#[actix_web::main]
async fn main() {
    HttpServer::new(|| {
        App::new().route("/", web::post().to(actix_handler))
    }).bind("127.0.0.1:8080")?.run().await
}

use axum::{Router, routing::post, extract::State};

// Ranvier schematic as shared state
#[tokio::main]
async fn main() {
    let schematic = Axon::simple().pipe(process).build();

    let app = Router::new()
        .route("/", post(axum_handler))
        .with_state(schematic);

    axum::Server::bind(&"0.0.0.0:3000".parse().unwrap())
        .serve(app.into_make_service())
        .await
}

async fn axum_handler(State(schematic): State<Schematic>, body: String) -> String {
    schematic.execute(body).await.unwrap_or_else(|e| e.to_string())
}

// Complex business logic in Ranvier
let order_pipeline = Axon::simple()
    .pipe(validate_order, check_inventory)
    .parallel(calculate_tax, apply_discount, check_fraud)
    .pipe(charge_payment, create_shipment, send_confirmation)
    .build();

// Serve with any HTTP framework
// - Hyper: ranvier-http
// - Axum: State(order_pipeline)
// - actix: web::Data<Schematic>
// - Tower: ServiceBuilder::service(ranvier_adapter)

// Just use Tower
let app = ServiceBuilder::new()
    .layer(CorsLayer::permissive())
    .layer(AuthLayer::bearer("secret"))
    .service(simple_handler);

// Ranvier: Simple
#[transition]
async fn my_logic(input: Input) -> Outcome<Output, Error> { ... }

// Tower: Complex
impl<S> Service<Request> for MyService<S> {
    type Response = Response;
    type Error = Error;
    type Future = Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>>>>;
    fn call(&mut self, req: Request) -> Self::Future { ... }
}

┌─────────────────────────────┐
│ API Gateway (Tower/Axum)    │  ← Simple routing
└──────────┬──────────────────┘
           │
           ▼
┌─────────────────────────────┐
│ Orchestrator (Ranvier)      │  ← Complex workflows, visualized
│  - Multi-service calls      │
│  - Saga pattern             │
│  - Compensation logic       │
└──────┬─────┬────────┬───────┘
       │     │        │
       ▼     ▼        ▼
   ┌────┐ ┌────┐  ┌────┐
   │User│ │Pay │  │Ship│       ← Simple CRUD (any framework)
   └────┘ └────┘  └────┘

use ranvier::prelude::*;
use jsonwebtoken::{decode, DecodingKey, Validation};
use serde::{Deserialize, Serialize};

// Domain types
#[derive(Debug, Clone, Serialize, Deserialize)]
struct AuthContext {
    user_id: String,
    roles: Vec<String>,
}

#[derive(Debug, thiserror::Error)]
enum AuthError {
    #[error("Missing authorization header")]
    MissingHeader,
    #[error("Invalid token: {0}")]
    InvalidToken(String),
    #[error("Unauthorized: requires role {0}")]
    Unauthorized(String),
}

// Transition 1: Extract and validate JWT
#[transition]
async fn authenticate(req: Request) -> Outcome<AuthContext, AuthError> {
    // Extract Authorization header
    let header = req.headers()
        .get("Authorization")
        .ok_or(AuthError::MissingHeader)?;

    let token = header
        .to_str()
        .ok()?
        .strip_prefix("Bearer ")
        .ok_or(AuthError::InvalidToken("Invalid format".into()))?;

    // Validate JWT
    let secret = std::env::var("JWT_SECRET").expect("JWT_SECRET not set");
    let key = DecodingKey::from_secret(secret.as_bytes());
    let claims = decode::<AuthContext>(token, &key, &Validation::default())
        .map_err(|e| AuthError::InvalidToken(e.to_string()))?
        .claims;

    // AuthContext automatically stored in Bus
    Outcome::ok(claims)
}

// Transition 2: Check role-based authorization
#[transition]
async fn authorize(auth: &AuthContext, required_role: &str) -> Outcome<(), AuthError> {
    // AuthContext automatically injected from Bus
    if !auth.roles.contains(&required_role.to_string()) {
        return Outcome::err(AuthError::Unauthorized(required_role.into()));
    }
    Outcome::ok(())
}

// Transition 3: Audit log (optional)
#[transition]
async fn audit_log(auth: &AuthContext, req: &Request) -> Outcome<(), Never> {
    tracing::info!(
        user_id = %auth.user_id,
        path = %req.uri().path(),
        "Authenticated request"
    );
    Outcome::ok(())
}

// Transition 4: Business logic
#[transition]
async fn protected_handler(auth: &AuthContext) -> Outcome<Response, AppError> {
    let body = format!("Hello, {}! Roles: {:?}", auth.user_id, auth.roles);
    Ok(Response::new(body.into()))
}

// Compose pipeline
fn main() {
    let admin_pipeline = Axon::simple::<AppError>()
        .pipe(authenticate, |auth| authorize(auth, "admin"), audit_log, protected_handler)
        .build();

    // Visualize in VSCode:
    // authenticate → authorize → audit_log → protected_handler
    //                  ↓ (if unauthorized)
    //                401 Unauthorized
}

use tower::ServiceBuilder;
use tower_http::auth::RequireAuthorizationLayer;
use hyper::{Request, Response, Body};

// Tower authorization validator
async fn validate_api_key(request: &Request<Body>) -> Result<(), &'static str> {
    let header = request.headers()
        .get("X-API-Key")
        .ok_or("Missing API key")?;

    let key = header.to_str().map_err(|_| "Invalid API key format")?;

    if key != "secret-key-123" {
        return Err("Invalid API key");
    }

    Ok(())
}

// Ranvier handler (business logic)
#[transition]
async fn business_logic(req: Request) -> Outcome<Response, AppError> {
    // Tower already validated API key
    Ok(Response::new("Authenticated!".into()))
}

fn main() {
    // Tower handles auth (not in Schematic)
    let app = ServiceBuilder::new()
        .layer(RequireAuthorizationLayer::custom(validate_api_key))
        .service(ranvier_handler);

    // Ranvier handles business logic (in Schematic)
}

use tower::ServiceBuilder;
use tower_http::{cors::CorsLayer, limit::RateLimitLayer};
use std::time::Duration;

// Tower handles infrastructure
let app = ServiceBuilder::new()
    .layer(CorsLayer::permissive())  // Infrastructure: CORS
    .layer(RateLimitLayer::new(100, Duration::from_secs(60)))  // Infrastructure: Rate limit
    .service(ranvier_handler);

// Ranvier handles business logic (visualized)
let ranvier_handler = Axon::simple::<AppError>()
    .pipe(authenticate, authorize, audit_log, protected_handler)
    .build();

Tower Layers (hidden):
  ├─ CORS
  └─ Rate Limit
      ↓
Ranvier Pipeline (visualized):
  authenticate → authorize → audit_log → protected_handler

#[transition]
async fn authenticate(req: Request) -> Outcome<AuthContext, AuthError> { /*...*/ }

#[transition]
async fn parse_order(req: &Request) -> Outcome<Order, ValidationError> { /*...*/ }

#[transition]
async fn check_inventory(order: &Order) -> Outcome<(), InventoryError> { /*...*/ }

#[transition]
async fn calculate_tax(order: &Order, auth: &AuthContext) -> Outcome<Tax, TaxError> {
    // Tax rate depends on user's location (from auth)
    /*...*/
}

#[transition]
async fn apply_discount(order: &Order, auth: &AuthContext) -> Outcome<Discount, ()> {
    // VIP users get 10% off
    if auth.roles.contains(&"vip".into()) {
        Outcome::ok(Discount::percent(10))
    } else {
        Outcome::ok(Discount::none())
    }
}

#[transition]
async fn charge_payment(order: &Order, tax: &Tax, discount: &Discount) -> Outcome<PaymentId, PaymentError> { /*...*/ }

#[transition]
async fn create_shipment(order: &Order, payment: &PaymentId) -> Outcome<ShipmentId, ShipmentError> { /*...*/ }

let pipeline = Axon::simple::<AppError>()
    .pipe(authenticate, parse_order)
    .parallel(check_inventory, calculate_tax, apply_discount)  // Run in parallel
    .pipe(charge_payment, create_shipment)
    .build();

authenticate → parse_order → ┬─ check_inventory ─┐
                              ├─ calculate_tax ────┤→ charge_payment → create_shipment
                              └─ apply_discount ───┘