Routing config schema

The routing section of project.cfg is the deploy-scoped config tier. It is authored in RON, parsed at sync, and folded into the immutable deployment manifest — so it is atomic with the content and rolls back with it. Every field is optional; an empty routing: () is all defaults.

Validate it without publishing:

boatramp validate

project.cfg: routing OK (2 redirects, 1 handler)

Top-level fields

Pattern fields (from, matches, handler route) use the path matcher syntax and are compiled at validate/sync, so a bad pattern fails at deploy time rather than at request time.

trailing_slash

redirects

Each rule redirects a matching path. First match wins.

redirects: [ (from: "/old/:slug", to: "/new/:slug", status: 301) ],

rewrites

A rewrite serves a different resource without changing the URL. An internal to (a path) rewrites; an absolute-URL to reverse-proxies to that upstream. First match wins.

An SPA fallback is a rewrite of everything to the app shell:

rewrites: [ (from: "/*", to: "/index.html", status: 200) ],

Proxy rewrites are constrained by proxy_allow.

Conditional rules (when)

A redirect or rewrite may carry a when condition — a small server-side expression over the request. The rule fires only when its from pattern matches and its when is true; otherwise the router keeps looking. This is how you do language- or file-aware routing without a WASM handler, and it runs in the routing hot path (compiled once at sync, then a fast in-memory evaluation per request).

routing: (
  redirects: [
    // Send the root to the visitor's preferred locale.
    ( from: "/", to: "/fr/", status: 302, when: "prefers_language(['fr','en']) == 'fr'" ),
    ( from: "/", to: "/en/", status: 302, when: "prefers_language(['en','fr']) == 'en'" ),
    // Fall back to the English page when a localized file is missing in this deploy.
    ( from: "/fr/*", to: "/en/:splat", status: 302, when: "!file_exists(path)" ),
  ],
)

The expression language is a subset of CEL — boolean expressions only, no loops, no timestamps, no regex — so it is bounded and cheap. It is compiled and type-checked at boatramp validate / sync (a bad expression fails the deploy).

Variables (strings): method, host, path (the normalized request path).

Functions:

Operators: == != in && || !, string concatenation with +, and the string/list methods .startsWith(…), .endsWith(…), .contains(…).

when: "method == 'GET' && header('X-Country') == 'IT' && path.startsWith('/shop')"

Computed destinations (${…})

A to destination may embed ${<expr>} — a string-valued expression from the same language — so one rule can route to a computed target. ${…} interpolation runs before the usual :name / :splat capture expansion. The classic use is sending a visitor to their negotiated locale in a single rule:

redirects: [
  ( from: "/",
    to: "/${prefers_language(['fr','en','de'])}/",
    status: 302,
    // Only redirect when a supported locale is actually accepted (else "//").
    when: "prefers_language(['fr','en','de']) != ''" ),
],

Embedded expressions are type-checked at validate/sync (each must be a string), and — like conditions — a ${…} that reads a header/cookie/Accept-Language contributes to the response Vary.

Caching. A condition that reads Accept-Language, a cookie, or a header makes the response depend on that dimension, so boatramp automatically adds the matching Vary header (e.g. Vary: accept-language) to the response — a downstream cache then keys on it and never serves one visitor’s locale redirect to another. Conditions that read only the URL + deploy content (path, file_exists) add no Vary.

headers

Each rule sets or removes response headers on matching paths. All matching rules apply, in order.

headers: [ (matches: "/assets/*", set: { "Cache-Control": "public, max-age=31536000, immutable" }) ],

cache

proxy_allow

Upstream hosts a proxy rewrite may target. An entry is an exact host or a .suffix for a subtree (.internal.example.com). When the list is empty, proxying to any public host is allowed; private, loopback, and link-local addresses are always blocked as an SSRF guard, regardless of this list. To proxy to a private address, declare a gateway upstream instead.

handlers

A WebAssembly handler bound to a route. Matched after redirects, before static lookup. See Deploy a handler.

imports

The capability vocabulary a handler may request. An unrecognized import is rejected at validate.

The site’s allow_imports is the allowlist; a handler requesting an import the site does not permit is denied at activation.

invoke_targets

The deny-by-default allowlist of sibling function names this handler may call through the invoke import. Each entry may use * wildcards (* = any function, img-* = a family, resize = one literal). It is only consulted when imports contains invoke (which the site’s allow_imports must also permit); an empty list means the handler cannot invoke anything even with the import.

handlers: [ (route: "/api", component: "api.wasm", imports: ["invoke"], invoke_targets: ["resize", "img-*"]) ],

limits (HandlerLimits)

Each field may only lower the corresponding site cap, never raise it. A request handler is connection-bearing, so its timeout_ms is additionally capped by the engine’s sync ceiling (handlers.sync_max_timeout_ms, default 10s) — a route that declares more is clamped back down. Genuinely long-running work belongs on the async path (a durable --async invocation or a workflow), not a request handler held open.

consumers

A component invoked once per message on a topic. See Run consumers, crons, and streams.

crons

A scheduled invocation of a declared handler route.

streams

A host-level endpoint that fans out messaging topics to connected clients.

Patterns

Route, redirect, rewrite, and header patterns share one matcher syntax:

Path normalization (dot-segment collapsing, the trailing-slash policy) runs before matching, so patterns always see a canonical path and cannot be bypassed with .. or a double slash. See The request pipeline.