#HTTP Ingress & Routing

Version: 0.51.0 Updated: 2026-07-16 Applies to: ranvier-http Category: Deep Dives

Build type-safe, explicit HTTP boundaries with the Router DSL.

#Router DSL

• Grouping: Bundle related routes under a shared prefix (e.g., /api/v1).
• Macros: Use ranvier_router! to define complex routing tables with less boilerplate.
• Composition: Nest groups to reflect nested API structures.

#Type-Safe Routing

• Path Params: Extract variables from URI (e.g., /user/:id) into types.
• Method Guard: Restrict nodes to GET, POST, PUT, DELETE, etc.
• Explicit Flow: No hidden middleware magic; transformations are standard Axon steps.

#Body Handling

#Quickstart

Ranvier::http()
  .bind("0.0.0.0:3000")
  .route("/", hello_axon)
  .route_group("/api/v1", |v1| {
      v1.route("/users", user_axon)
  })
  .run().await?;

#Workflows

1. Define a Schematic for your API logic.
2. Bind the Axon to a URI and HTTP Method.
3. Add Middleware Layers (CORS, Auth) to specific groups.
4. Extract path parameters using the Path<T> extractor.

#Cooperative Shutdown and Deadlines

• run(resources) preserves the 0.51.x compatibility behavior: stop accepting and drain in-flight responses without converting them to cancellation.
• run_managed(resources) maps the operating-system shutdown signal to OperatorShutdown, cancels request Axons, then drains connections plus owned SSE/WebSocket tasks against one deadline budget.
• run_with_cancellation(resources, token) lets an embedding runtime supply the structured shutdown reason. For raw Hyper integration, use into_raw_service_with_cancellation, stop routing, cancel the root, and call RawIngressService::drain_tasks.
• A cooperative deadline returns 408 only after Runtime cancellation cleanup has had a chance to persist and compensate. Shutdown/explicit cancellation maps to 503 while a response is still writable.

CPU-bound or blocking code that never yields is not preempted. The managed deadline eventually aborts remaining connection/child tasks, so compensation that must survive process termination still needs durable RQ8 recovery.

#Key Types