dream/router

Route configuration and request matching

The router matches incoming requests to controllers based on HTTP method and path patterns. It uses a radix trie for O(path depth) lookup performance, making it efficient even with hundreds of routes. The router supports path parameters, wildcards, middleware chains, and custom context/services types.

Basic Routing

import dream/router.{route, router}
import dream/http/request.{Get, Post}

pub fn create_router() {
  router()
  |> route(method: Get, path: "/", controller: controllers.index, middleware: [])
  |> route(method: Get, path: "/users/:id", controller: controllers.show_user, middleware: [])
  |> route(method: Post, path: "/users", controller: controllers.create_user, middleware: [])
}

Path Parameters

Use :name to capture path segments as parameters:

• /users/:id matches /users/123 and extracts id = "123"
• /posts/:post_id/comments/:id extracts both parameters

Access parameters in your controller with request.get_param(request, "id").

Parameter Name Remapping

Routes with different parameter names at the same position are supported. Each route extracts parameters using its own declared parameter names:

router()
|> route(method: Get, path: "/users/:id", controller: show_user, middleware: [])
|> route(method: Get, path: "/users/:user_id/posts", controller: show_posts, middleware: [])

• /users/123 extracts id = "123" (first route’s param name)
• /users/123/posts extracts user_id = "123" (second route’s param name)

The router automatically remaps parameters to match each route’s declared names, even when routes share parameter positions in the trie structure.

Wildcards

Wildcards match one or more path segments:

• * or *name - Matches exactly one segment
• ** or **path - Matches zero or more segments (greedy)
• *.jpg - Matches any path ending in .jpg
• *.{jpg,png,gif} - Matches multiple extensions

Middleware

Middleware run before (and optionally after) your controller:

router()
|> route(
  method: Get,
  path: "/admin/users",
  controller: controllers.admin_users,
  middleware: [auth_middleware, logging_middleware]
)

Middleware are executed in order: auth → logging → controller → logging → auth. Each middleware can modify the request on the way in or the response on the way out.

Route Matching Priority

When multiple routes could match, the most specific wins:

1. Literal segments (exact match) - highest priority
2. Parameters (:id)
3. Single wildcards (*)
4. Extension patterns (*.jpg)
5. Multi-segment wildcards (**) - lowest priority

This means /users/new will match before /users/:id even if defined in reverse order.

Important: Parameter Validation Trade-off

Dream validates path parameters at runtime, not compile-time. This means:

• ✅ Ergonomic API: Simple, clean route definitions
• ✅ Flexible: Easy to add/change routes dynamically
• ❌ No compile-time safety: Typos in parameter names cause runtime errors

Example of what the compiler WON’T catch:

// Route definition
router()
|> route(method: Get, path: "/users/:user_id", controller: show_user, middleware: [])

// Controller (WRONG - will fail at runtime)
fn show_user(request: Request, context: Context, services: Services) -> Response {
  case get_param(request, "id") {  // Should be "user_id"
    Ok(param) -> // This will never execute
    Error(_) -> // Always hits this branch
  }
}

This is an intentional design decision favoring ergonomics over compile-time guarantees. We’re exploring more type-safe alternatives that maintain clean APIs in GitHub Discussion #15.

Mitigation: Write integration tests that exercise your routes. The runtime validators (get_param, get_int_param, etc.) will catch mismatches immediately.

pub type EmptyServices {
  EmptyServices
}

pub type Middleware(context, services) {
  Middleware(
    fn(
      request.Request,
      context,
      services,
      fn(request.Request, context, services) -> response.Response,
    ) -> response.Response,
  )
}

pub type Route(context, services) {
  Route(
    method: request.Method,
    path: String,
    controller: fn(request.Request, context, services) -> response.Response,
    middleware: List(Middleware(context, services)),
    streaming: Bool,
  )
}

pub opaque type Router(context, services)

pub fn build_controller_chain(
  middleware: List(Middleware(context, services)),
  final_controller: fn(request.Request, context, services) -> response.Response,
) -> fn(request.Request, context, services) -> response.Response

pub fn find_route(
  router_value: Router(context, services),
  request: request.Request,
) -> option.Option(
  #(Route(context, services), List(#(String, String))),
)

let app_router = router
  |> route(method: Get, path: "/users/:id", controller: show_user, middleware: [])

case find_route(app_router, request) {
  Some(#(route, params)) -> {
    // route.controller is show_user
    // params is [#("id", "123")] if path was "/users/123"
  }
  None -> // No route matched
}

pub fn route(
  router_value: Router(context, services),
  method method_value: request.Method,
  path path_pattern: String,
  controller controller_fn: fn(request.Request, context, services) -> response.Response,
  middleware middleware_list: List(
    fn(
      request.Request,
      context,
      services,
      fn(request.Request, context, services) -> response.Response,
    ) -> response.Response,
  ),
) -> Router(context, services)

// Simple route
route(router, method: Get, path: "/", controller: home_controller, middleware: [])

// Route with path parameter
route(router, method: Get, path: "/users/:id", controller: show_user, middleware: [])

// Route with middleware
route(router, method: Post, path: "/admin/users", controller: create_user, middleware: [auth, logging])

// Wildcard route for static files
route(router, method: Get, path: "/assets/**path", controller: serve_static, middleware: [])

pub fn router() -> Router(context, services)

router()
|> route(method: Get, path: "/", controller: home, middleware: [])
|> route(method: Get, path: "/users/:id", controller: show_user, middleware: [])

pub fn stream_route(
  router_value: Router(context, services),
  method method_value: request.Method,
  path path_pattern: String,
  controller controller_fn: fn(request.Request, context, services) -> response.Response,
  middleware middleware_list: List(
    fn(
      request.Request,
      context,
      services,
      fn(request.Request, context, services) -> response.Response,
    ) -> response.Response,
  ),
) -> Router(context, services)

router
|> stream_route(method: Post, path: "/upload", controller: handle_upload, middleware: [auth])
|> stream_route(method: Put, path: "/files/:id", controller: replace_file, middleware: [])