route

Route Builder

Core routing types and functions for defining HTTP routes with type-safe parameter extraction, middleware support, and route grouping capabilities.

Types

Middleware Type

A function that intercepts requests before they reach the handler. Can modify the request, execute logic, and modify the response. Uses the ‘next’ callback to continue the chain.

pub type Middleware(context) =
  fn(
    request.Request(wisp.Connection),
    context,
    fn(request.Request(wisp.Connection)) -> response.Response(
      wisp.Body,
    ),
  ) -> response.Response(wisp.Body)

Route Type

Represents a single route with its HTTP method, the path pattern, handler function, middleware stack, and optional name for URL generation. Paths also can include wildcard parameters like /users/{id}.

pub type Route(context) {
  Route(
    method: http.Method,
    path: String,
    handler: fn(RouteRequest, context) -> response.Response(
      wisp.Body,
    ),
    middleware: List(
      fn(
        request.Request(wisp.Connection),
        context,
        fn(request.Request(wisp.Connection)) -> response.Response(
          wisp.Body,
        ),
      ) -> response.Response(wisp.Body),
    ),
    name: String,
  )
}

Constructors

Route(
  method: http.Method,
  path: String,
  handler: fn(RouteRequest, context) -> response.Response(
    wisp.Body,
  ),
  middleware: List(
    fn(
      request.Request(wisp.Connection),
      context,
      fn(request.Request(wisp.Connection)) -> response.Response(
        wisp.Body,
      ),
    ) -> response.Response(wisp.Body),
  ),
  name: String,
)

RouteGroup

</>

RouteGroup Type

Groups routes together with a shared middleware group which determines which global middlewares are applied to all routes in the group.

pub type RouteGroup(context) {
  RouteGroup(
    middleware_group: kernel.MiddlewareGroup,
    routes: List(Route(context)),
  )
}

Constructors

RouteGroup(
  middleware_group: kernel.MiddlewareGroup,
  routes: List(Route(context)),
)

RouteHandler

</>

RouteHandler Type

A function that handles a route request and returns a wisp response. This would typically be a controller modules function but it can be an anonymous function as well.

pub type RouteHandler(context) =
  fn(RouteRequest, context) -> response.Response(wisp.Body)

RouteRequest

</>

RouteRequest Type

Wraps a Wisp request with extracted route parameters from the URL path. Parameters are stored as a dictionary mapping parameter names to their string values.

pub type RouteRequest {
  RouteRequest(
    request: request.Request(wisp.Connection),
    params: dict.Dict(String, String),
  )
}

Constructors

RouteRequest(
  request: request.Request(wisp.Connection),
  params: dict.Dict(String, String),
)

Values

delete

</>

pub fn delete(
  path: String,
  handler: fn(RouteRequest, context) -> response.Response(
    wisp.Body,
  ),
) -> Route(context)

DELETE Route Builder

Creates a DELETE route with the specified path and handler. Path is normalized (adds leading slash, removes trailing slash). Supports parameters like /users/{id}.

Example:

route.delete("/users/{user_id}", user_controller.delete)

get

</>

pub fn get(
  path: String,
  handler: fn(RouteRequest, context) -> response.Response(
    wisp.Body,
  ),
) -> Route(context)

GET Route Builder

Creates a GET route with the specified path and handler. Path is normalized (adds leading slash, removes trailing slash). Supports parameters like /users/{id}.

Example:

route.get("/users", user_controller.index)

get_param

</>

pub fn get_param(
  req: RouteRequest,
  key: String,
) -> Result(String, Nil)

Get Route Parameter

Extracts a parameter value from the route request by key. Returns Ok(value) if the parameter exists, or Error(Nil) if not found. Use for required parameters that must exist.

get_param_or

</>

pub fn get_param_or(
  req: RouteRequest,
  key: String,
  default: String,
) -> String

Get Route Parameter with Default

Extracts a parameter value from the route request by key, returning the provided default value if not found. Use for optional parameters with fallback values.

group_middleware

</>

pub fn group_middleware(
  middleware: List(
    fn(
      request.Request(wisp.Connection),
      context,
      fn(request.Request(wisp.Connection)) -> response.Response(
        wisp.Body,
      ),
    ) -> response.Response(wisp.Body),
  ),
  routes: List(List(Route(context))),
) -> List(Route(context))

Group Routes with Middleware

Applies middleware to multiple routes at once. Middleware is prepended to any existing route-level middleware, so group middleware executes first (outermost wrapper).

Example:

route.group_middleware([logger.handle], [
  [
    router.get(...),
    router.get(...),
    router.post(...),
  ]
])

group_name_prefix

</>

pub fn group_name_prefix(
  name: String,
  routes: List(List(Route(context))),
) -> List(Route(context))

Group Routes with Name Prefix

Adds a name prefix to multiple routes. This is Useful for namespacing route names like “admin.” or “api.v1.”. The prefix is prepended to each route’s existing name.

Example:

route.group_name_prefix("users.", [
  [
    router.get(...),
    router.get(...),
    router.post(...),
  ]
])

group_path_prefix

</>

pub fn group_path_prefix(
  prefix: String,
  routes: List(List(Route(context))),
) -> List(Route(context))

Group Routes with Path Prefix

Adds a path prefix to multiple routes. Useful for versioning (/v1/users) or organizing by section (/admin/users). The prefix is automatically normalized.

Example:

route.group_path_prefix("/users", [
  [
    router.get(...),
    router.get(...),
    router.post(...),
  ]
])

middleware

</>

pub fn middleware(
  route: Route(context),
  middleware: List(
    fn(
      request.Request(wisp.Connection),
      context,
      fn(request.Request(wisp.Connection)) -> response.Response(
        wisp.Body,
      ),
    ) -> response.Response(wisp.Body),
  ),
) -> Route(context)

Apply Middleware to Route

Attaches middleware to a route. Middleware executes before the handler and can modify the request or response. Use the pipe operator to chain.

Example:

route.get(...)
  |> router.middleware([logger.handle])

name

</>

pub fn name(
  route: Route(context),
  name: String,
) -> Route(context)

Name a Route

Assigns a name to a route for URL generation and reference. Names should be unique and descriptive, like “users.show” or “admin.dashboard”. Use the pipe operator to chain.

Example:

route.get(...)
  |> router.name("users.get")

post

</>

pub fn post(
  path: String,
  handler: fn(RouteRequest, context) -> response.Response(
    wisp.Body,
  ),
) -> Route(context)

POST Route Builder

Creates a POST route with the specified path and handler. Path is normalized (adds leading slash, removes trailing slash). Supports parameters like /users/{id}.

Example:

route.post("/users", user_controller.store)

put

</>

pub fn put(
  path: String,
  handler: fn(RouteRequest, context) -> response.Response(
    wisp.Body,
  ),
) -> Route(context)

PUT Route Builder

Creates a PUT route with the specified path and handler. Path is normalized (adds leading slash, removes trailing slash). Supports parameters like /users/{id}.

Example:

route.put("/users/{user_id}", user_controller.update)