Route Reference

Route matching and dispatch configuration for ServerBlock.routes.

Routes are evaluated in declaration order; the first route whose match conditions are all satisfied dispatches the request to its handler. Requests that match no route fall through to the block-level ServerBlock.handler.

Route-level middleware wraps the handler for that route only and runs after block-level middleware. See Handler for available handler types and Middleware for available middleware.

> This page is auto-generated from the PKL schema. See the guide for usage examples.

Types

HttpMethod

Standard HTTP request methods, used by RouteMatch.methods to restrict which methods a route will match.

typealias HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS" | "TRACE"

---

RouteMatch

Match conditions for a route. All non-null fields must match simultaneously (logical AND) for the route to be selected. Omitting a field (leaving it null) means "match any value" for that dimension.

Path matching semantics:

path

Path pattern to match against the request URI path. null matches all paths. See the class-level doc comment for pattern syntax.

path = "/api/**"
path = "/re:^/users/[0-9]+"

host

Hostname / virtual-host pattern. Supports glob patterns for wildcard subdomains. null matches all hosts.

host = "api.example.com"
host = "*.example.com"

methods

Restrict this route to the listed HTTP methods. null matches all methods. Requests with a non-matching method continue to the next route (they do not receive a 405).

methods { "GET"; "HEAD" }

headers

Required request headers. Every entry must be present with a matching value for the route to match. Values support * as a wildcard.

headers { ["Accept"] = "application/json" }
headers { ["X-Feature-Flag"] = "*" }

queryParams

Required query-string parameters. Every entry must be present with the given value for the route to match.

queryParams { ["format"] = "json" }

---

Route

A route pairs match conditions with a handler and optional route-scoped middleware. Routes are evaluated in the order they appear in ServerBlock.routes; the first match wins.

new Route {
  match = "/api/**"
  handler = new ReverseProxy { upstreams { "backend:9000" } }
  middleware { new RateLimit { requests = 100; window = 60.s } }
}

match

Conditions that select this route. Accepts a path string shorthand or a full RouteMatch object for multi-dimensional matching.

match = "/api/**"
match { path = "/api/**"; methods { "GET"; "POST" } }

An empty RouteMatch (the default) matches every request — useful as a catch-all route at the end of a listing.

handler

Handler invoked when this route matches. See Handler for available types (StaticFiles, ReverseProxy, Redirect, Cgi, Respond).

middleware

Middleware applied only to requests matched by this route. Runs after block-level ServerBlock.middleware and wraps this route's handler. Applied in declaration order (first = outermost layer).

---