#Authentication Approaches: Transition vs Tower

This guide compares two authentication approaches in Ranvier:

1. Transition-based auth (examples/auth-transition/) — Pure Ranvier approach (recommended)
2. Tower integration (examples/auth-tower-integration/) — Ecosystem compatibility approach

#Executive Summary

TL;DR: If you're starting fresh, use Transition-based auth. If you have an existing Tower app or need specific Tower middleware, use Tower integration.

#Feature Comparison

Legend:

• ✅ Strong advantage
• ⚠️ Usable but with caveats
• ❌ Not supported / significant limitation

#Detailed Analysis

#Transition-based Auth (Ranvier Way)

Philosophy: Authentication is a business concern and should be represented as Transitions in the Schematic.

#Code Pattern

#[transition]
async fn authenticate(req: Request, res: &(), bus: &mut Bus) -> Outcome<AuthContext, AppError> {
    let token = extract_token(&req)?;
    let auth_ctx = validate_jwt(token, &secret)?;
    bus.insert(auth_ctx.clone()); // Store in Bus
    Outcome::Next(auth_ctx)
}

#[transition]
async fn authorize(auth: AuthContext, res: &(), bus: &mut Bus) -> Outcome<(), AppError> {
    if !auth.roles.contains(&"admin".into()) {
        return Outcome::Fault(AppError::Unauthorized);
    }
    Outcome::Next(())
}

let pipeline = Axon::simple::<AppError>("auth-pipeline")
    .then(authenticate)
    .then(authorize)
    .then(protected_handler);

#Advantages

1. Schematic Visualization

   • The entire auth flow is represented in schematic.json
   • VSCode Circuit view shows: authenticate → authorize → handler
   • Easy to see data flow: Request → AuthContext → () → Response
   • Non-technical stakeholders can understand the flow

2. Bus-based Context Propagation

   • AuthContext is stored in the Bus automatically after authenticate returns
   • All downstream transitions can read it with bus.read::<AuthContext>()
   • Type-safe: the compiler ensures AuthContext exists before authorize runs
   • Explicit: no hidden global state or magic request extensions

3. Easier Unit Testing

   Copy

   #[tokio::test]
   async fn test_authorize_missing_role() {
       let mut bus = Bus::new();
       bus.insert(AuthContext {
           user_id: "alice".into(),
           roles: vec!["user".into()], // Missing "admin"
       });
   
       let result = authorize(auth_ctx, &(), &mut bus).await;
       assert!(matches!(result, Outcome::Fault(_)));
   }

   • No HTTP server needed
   • Test individual transitions in isolation
   • Easy to test edge cases (expired tokens, missing roles, etc.)

4. Composability

   • Add steps without breaking existing code:
   Copy

   let pipeline = Axon::simple::<AppError>("auth-pipeline")
       .then(authenticate)
       .then(audit_log)         // ← Add audit logging
       .then(check_subscription) // ← Add subscription check
       .then(authorize)
       .then(protected_handler);

   • Parallel checks are explicit:
   Copy

   let pipeline = Axon::simple()
       .then(authenticate)
       .parallel(authorize, check_subscription) // Both run in parallel
       .then(protected_handler);

#Disadvantages

1. Cannot Reuse Tower Middleware

   • If you need tower-http::cors::CorsLayer, you must reimplement in Ranvier
   • If your team has custom Tower layers, they won't work directly
   • Ecosystem tools (e.g., tower-otel, tower-governor) require adapters

2. Learning Curve

   • Team must learn Transition/Outcome/Bus paradigm
   • Different from traditional middleware patterns
   • Requires understanding Schematic model

#Tower Integration (Ecosystem Way)

Philosophy: Ranvier is for business logic. Use Tower for HTTP concerns (auth, CORS, tracing).

#Code Pattern

use tower::ServiceBuilder;
use tower_http::auth::AsyncRequireAuthorizationLayer;

#[derive(Clone)]
struct JwtAuthorizer { secret: String }

impl<B> AsyncAuthorizeRequest<B> for JwtAuthorizer {
    type RequestBody = B;
    type ResponseBody = String;
    type Future = Ready<Result<Request<B>, Response<String>>>;

    fn authorize(&mut self, mut request: Request<B>) -> Self::Future {
        let token = extract_token(&request)?;
        let auth_ctx = validate_jwt(token, &self.secret)?;
        request.extensions_mut().insert(auth_ctx); // Store in extensions
        ready(Ok(request))
    }
}

let service = ServiceBuilder::new()
    .layer(CorsLayer::permissive())
    .layer(AsyncRequireAuthorizationLayer::new(JwtAuthorizer { secret }))
    .service(ranvier_adapter);

#[transition]
async fn handler(_input: (), _res: &(), bus: &mut Bus) -> Outcome<Response, AppError> {
    // Adapter must extract AuthContext from request.extensions() → Bus
    let auth = bus.read::<AuthContext>().expect("AuthContext in Bus");
    // Business logic...
}

#Advantages

1. Full Tower Ecosystem Access

   Copy

   let service = ServiceBuilder::new()
       .layer(CorsLayer::permissive())
       .layer(TraceLayer::new_for_http())
       .layer(TimeoutLayer::new(Duration::from_secs(30)))
       .layer(RateLimitLayer::new(100, Duration::from_secs(60)))
       .layer(jwt_auth_layer(secret))
       .service(ranvier_adapter);

   • Reuse existing Tower middleware without modification
   • Access to tower-http (CORS, Trace, Timeout, Compression)
   • Access to community layers (tower-governor, tower-sessions, etc.)

2. Team Knowledge Transfer

   • If your team knows Tower, they can apply that knowledge directly
   • Minimal learning curve for Tower-based auth
   • Familiar patterns from other Rust web frameworks (Axum, Tonic)

3. Gradual Migration Path

   • Stage 1: Keep existing Tower app, add one Ranvier endpoint
   • Stage 2: Move more endpoints to Ranvier over time
   • Stage 3: Eventually migrate auth to Ranvier if desired
   • No need for "big bang" rewrite

4. Battle-tested Middleware

   • Tower middleware has been used in production for years
   • Well-documented, stable APIs
   • Community support and examples

#Disadvantages

1. Not Visible in Schematic

   • Tower layers are opaque in schematic.json
   • VSCode Circuit view shows: protected_handler (no auth flow)
   • Debugging requires understanding Tower middleware chain
   • Harder to explain to non-technical stakeholders

2. AuthContext Not in Bus (by default)

   • Tower stores AuthContext in request.extensions()
   • Requires adapter to extract from extensions → put in Bus
   • Manual wiring:
   Copy

   // In Tower-to-Ranvier adapter
   let auth_ctx = req.extensions().get::<AuthContext>().cloned();
   if let Some(ctx) = auth_ctx {
       bus.insert(ctx);
   }

   • Less type-safe: Runtime extraction, not compile-time guaranteed

3. More Boilerplate

   • AuthorizeRequest trait: ~50 lines
   • Manual Layer + Service: ~150 lines
   • Compare with Ranvier transition: ~20 lines
   • More code to maintain and test

#When to Use Which

#Choose **Transition-based Auth** if:

• ✅ You're starting a new project and want full Ranvier benefits
• ✅ You want Schematic visualization of auth flow in VSCode
• ✅ You prefer Bus-based context propagation (type-safe, explicit)
• ✅ You want easier unit testing (no HTTP mocks needed)
• ✅ You value composability (easy to add/remove auth steps)
• ✅ Your team is willing to learn Ranvier paradigm

#Choose **Tower Integration** if:

• ✅ You have an existing Tower app and want to add Ranvier gradually
• ✅ Your team already knows Tower and wants to leverage that
• ✅ You need specific Tower middleware (CORS, RateLimit, Trace)
• ✅ You're migrating from another framework (Axum, Tonic) that uses Tower
• ✅ You want battle-tested middleware without reimplementation

#Hybrid Approach

You can use both in the same application:

// Tower handles cross-cutting HTTP concerns
let service = ServiceBuilder::new()
    .layer(CorsLayer::permissive())          // Tower: CORS
    .layer(TraceLayer::new_for_http())       // Tower: Tracing
    .layer(TimeoutLayer::new(...))           // Tower: Timeout
    .service(ranvier_adapter);

// Ranvier handles business logic (including auth)
let auth_pipeline = Axon::simple::<AppError>("auth")
    .then(authenticate)  // Ranvier: JWT validation
    .then(authorize)     // Ranvier: Role check
    .then(handler);      // Ranvier: Business logic

Guideline: Use Tower for protocol-level HTTP concerns (CORS, tracing, timeout). Use Ranvier for business logic (auth, authorization, domain operations).

#Migration Paths

#From Tower to Ranvier (Gradual)

If you have an existing Tower app and want to migrate to Ranvier auth:

Stage 1: Add Ranvier adapter, keep Tower auth

let service = ServiceBuilder::new()
    .layer(jwt_auth_layer(secret))  // Tower: Auth (keep)
    .service(ranvier_adapter);      // Ranvier: Business logic only

Stage 2: Move auth to Ranvier, keep Tower for HTTP concerns

let service = ServiceBuilder::new()
    .layer(CorsLayer::permissive()) // Tower: CORS (keep)
    .service(ranvier_adapter);      // Ranvier: Auth + business logic

let auth_pipeline = Axon::simple()
    .then(authenticate)             // Ranvier: Auth (new)
    .then(handler);

Stage 3: Full Ranvier (optional, if you want full visualization)

// Pure Ranvier (no Tower)
let http_ingress = HttpIngress::new(...);
let auth_pipeline = Axon::simple()
    .then(authenticate)
    .then(authorize)
    .then(handler);

Time estimate: 1-2 weeks per stage for a medium-sized app.

#From Ranvier to Tower (Interop)

If you want to add Tower middleware to a Ranvier app:

Stage 1: Add Tower layer for HTTP concerns

// Add Tower for CORS/Trace, keep Ranvier for auth
let service = ServiceBuilder::new()
    .layer(CorsLayer::permissive())
    .layer(TraceLayer::new_for_http())
    .service(ranvier_adapter);

let auth_pipeline = Axon::simple()
    .then(authenticate)  // Ranvier: Auth
    .then(handler);

Stage 2: Move auth to Tower (if needed for ecosystem integration)

let service = ServiceBuilder::new()
    .layer(CorsLayer::permissive())
    .layer(jwt_auth_layer(secret))  // Tower: Auth
    .service(ranvier_adapter);

// Adapter extracts AuthContext from extensions → Bus
let auth_pipeline = Axon::simple()
    .then(handler);  // Ranvier: Business logic only

Time estimate: 1-3 days for adding Tower layers.

#Performance Comparison

TL;DR: Both approaches have identical performance in production. The overhead of Tower layers and Ranvier transitions is negligible (less than 1 µs per layer/transition).

#Benchmark Results (Intel i7, Release Build)

Explanation:

• Both compile to async functions with similar machine code
• Tower layers and Ranvier transitions are zero-cost abstractions
• Bus and request extensions have identical memory layout (both use TypeMap)

Caveat: If you use many Tower layers (10+), there may be slight overhead from middleware chain traversal. In practice, this is negligible (less than 0.1 ms).

#Testing Strategies

#Transition-based: Unit Tests

#[tokio::test]
async fn test_authenticate_valid_token() {
    let mut bus = Bus::new();
    bus.insert("Bearer valid-token".to_string());

    let result = authenticate((), &(), &mut bus).await;
    assert!(matches!(result, Outcome::Next(_)));

    let auth = bus.read::<AuthContext>().unwrap();
    assert_eq!(auth.user_id, "alice");
}

#[tokio::test]
async fn test_authorize_missing_role() {
    let mut bus = Bus::new();
    bus.insert(AuthContext {
        user_id: "bob".into(),
        roles: vec!["user".into()], // Missing "admin"
    });

    let result = authorize(AuthContext { ... }, &(), &mut bus).await;
    assert!(matches!(result, Outcome::Fault(_)));
}

Advantages:

• Fast (no HTTP server)
• Easy to test edge cases (missing token, expired token, invalid role)
• No mocking needed (just inject test data into Bus)

#Tower Integration: Integration Tests

#[tokio::test]
async fn test_auth_middleware() {
    let app = ServiceBuilder::new()
        .layer(jwt_auth_layer(secret))
        .service(test_handler);

    let req = Request::builder()
        .header("Authorization", "Bearer valid-token")
        .body(Body::empty())
        .unwrap();

    let resp = app.oneshot(req).await.unwrap();
    assert_eq!(resp.status(), StatusCode::OK);
}

Advantages:

• Tests the full Tower middleware chain
• Closer to production behavior

Disadvantages:

• Slower (HTTP overhead)
• Harder to test edge cases (need to craft HTTP requests)

#Code Complexity Comparison

#Transition-based Auth

Lines of code: ~60 lines total

• auth.rs: 30 lines (AuthContext, AuthError, validate_jwt)
• main.rs: 30 lines (authenticate, authorize, handler)

#Tower Integration

Lines of code: ~120 lines total (Option B: high-level API)

• auth.rs: 30 lines (same as Transition-based)
• tower_auth.rs: 60 lines (JwtAuthorizer impl)
• main.rs: 30 lines (Tower setup + adapter)

Lines of code: ~200 lines total (Option A: low-level)

• auth.rs: 30 lines
• tower_auth.rs: 140 lines (AuthLayer + AuthService impl)
• main.rs: 30 lines

Verdict: The transition-based approach has 50% less code than Tower (high-level) and 70% less than Tower (low-level).

#Decision Framework

Use this decision tree to choose the right approach:

graph TD
    START{Are you starting a new project?} -->|Yes| Q1{Need specific Tower middleware?<br/>CORS, RateLimit}
    Q1 -->|No| T1["Use Transition-based ✅"]
    Q1 -->|Yes| T2["Hybrid: Tower for HTTP,<br/>Ranvier for auth ⚠️"]
    START -->|No| Q2{"Existing Tower app —<br/>Team willing to learn Ranvier?"}
    Q2 -->|Yes| T3["Gradual migration to<br/>Transition-based ⚠️"]
    Q2 -->|No| T4["Keep Tower Integration ✅"]

#Real-world Examples

#E-commerce Platform (Transition-based)

Scenario: Startup building a new e-commerce platform.

Requirements:

• JWT authentication
• Role-based authorization (admin, seller, buyer)
• Subscription check (premium features)
• Rate limiting (per-user basis)

Approach: Transition-based auth

let checkout_pipeline = Axon::simple()
    .then(authenticate)          // JWT validation
    .then(check_subscription)    // Premium features check
    .then(authorize_buyer)       // Must have "buyer" role
    .then(rate_limit_user)       // Per-user rate limit
    .then(process_order);        // Business logic

Why: New project, want full Schematic visualization for debugging, easy to add/remove auth steps as requirements change.

#SaaS Migration (Tower Integration)

Scenario: Existing Tower-based SaaS product migrating to Ranvier.

Requirements:

• Keep existing Tower auth (OIDC + session)
• Add Ranvier for new workflow engine
• Team knows Tower, limited time to learn Ranvier

Approach: Tower integration

let service = ServiceBuilder::new()
    .layer(CorsLayer::permissive())
    .layer(oidc_auth_layer())       // Existing Tower auth
    .layer(session_layer())          // Existing Tower session
    .service(ranvier_adapter);

let workflow_pipeline = Axon::simple()
    .then(workflow_handler);  // New Ranvier logic (no auth, Tower handles it)

Why: Gradual migration, leverage existing Tower knowledge, minimize risk.

#Summary

Final Recommendation:

• Default choice: Transition-based (pure Ranvier)
• If you need Tower: Tower integration (ecosystem compatibility)
• Best of both: Hybrid (Tower for HTTP, Ranvier for auth + business logic)

#Further Reading

• examples/auth-transition/ — Full Transition-based example
• examples/auth-tower-integration/ — Full Tower integration example
• PHILOSOPHY.md — "Opinionated Core, Flexible Edges" principle
• DESIGN_PRINCIPLES.md — Why we separated from Tower (DP-2)