router

README

router

A path router for SSPUR's HTTP server, for the cases a svc doesn't cover. A svc already binds {name} segments, routes by method and answers 404 and 405 with Allow; use it when that is enough. Reach for router when you need:

• typed and constrained parameters: {id:int}, {id:uuid}, {name:alpha}, {slug:[a-z-]+};
• catch-all wildcards: /assets/{path...};
• the most specific route winning whatever the order (/users/me over /users/{id:int} over /users/{name}), with conflicting routes reported when the table is compiled;
• automatic OPTIONS and HEAD, 405 with a correct Allow, and OPTIONS *;
• cleaned paths (//, ., ..) and trailing-slash redirects (301 for GET and HEAD, 308 otherwise, keeping the query);
• route groups with prefixes and tags, for per-group middleware such as an admin check;
• host constraints (api.example.com, *.tenant.example.com);
• mounting a svc or any handler under a prefix;
• building URLs back from routes, with every parameter checked and percent-encoded.

Routes are data. Each route names an id of your own type, usually a sum type, and the router says which one matched and with which decoded parameters; your handler dispatches with a match. Server handlers can't keep function values built outside them, so a table of handler functions would have to be rebuilt on every request, while a compiled table of data is built once and shared by every handler thread.

Install

$ sspur add router

Example

use router.{Match, Table, Route, get, post, delete, group, compile, default_options, route_request, param_int, has_tag, url_for, describe}

type Page = Home | ShowUser | DeleteUser | NewUser | Me | Assets | AdminStats

fn routes() -> List[Route[Page]]
= [get("/", Home), get("/users/me", Me), get("/users/\{id:int}", ShowUser), delete("/users/\{id:int}", DeleteUser), post("/users", NewUser), get("/assets/\{path...}", Assets)] + group("/admin", ["admin"], [get("/stats", AdminStats)])

fn page(m: Match[Page]) -> Response
= match m.id
  | ShowUser => http.text(200, "user {param_int(m, "id").or(0)}")
  | Me => http.text(200, "me")
  | other => http.text(200, "{other} {m.params}")

fn dispatch(t: Table[Page], req: Request) -> Response
= match route_request(t, req)
  | ok(m) => if has_tag(m, "admin") and req.header("authorization").is_none then http.text(401, "sign in") else page(m)
  | err(answer) => answer

fn rq(m: Str, url: Str) -> Request
= Request{method: m, url, headers: [], body: "", timeout_ms: 0, retries: 0, redirects: 0}

fn main() -> Unit ! log
= match compile(routes(), default_options())
  | err(problems) => log.error(problems.join("; "))
  | ok(t) => do
    for line in describe(t)
      log(line)
    for (m, url) in [("GET", "/users/me"), ("GET", "/users/42"), ("PUT", "/users/42"), ("GET", "/users/42/"), ("GET", "/assets/css/site.css"), ("GET", "/admin/stats"), ("GET", "/nope")]
      r = dispatch(t, rq(m, url))
      log("{m} {url} -> {r.status} {r.header("allow").or(r.header("location").or(r.body))}")
    log("url: {url_for(t, ShowUser, [("id", "7")], [("tab", "posts")])}")
    // Serving it: http.serve_with(http.server(8080), req => dispatch(t, req))

$ sspur run main.ssp
GET / -> Home
GET /users/me -> Me
GET /users/{id:int} -> ShowUser
DELETE /users/{id:int} -> DeleteUser
POST /users -> NewUser
GET /assets/{path...} -> Assets
GET /admin/stats -> AdminStats
GET /users/me -> 200 me
GET /users/42 -> 200 user 42
PUT /users/42 -> 405 GET, HEAD, DELETE, OPTIONS
GET /users/42/ -> 301 /users/42
GET /assets/css/site.css -> 200 Assets [("path", "css/site.css")]
GET /admin/stats -> 401 sign in
GET /nope -> 404 {"type":"about:blank","title":"Not Found","status":404}
url: some("/users/7?tab=posts")

Note the \{ in patterns: in an SSPUR string literal {id} is interpolation, so write "/users/\{id}". ({id:int} happens to stay literal, but escaping every { is the safe habit.)

Mounting a svc under a prefix: route any_method("/api/\{rest...}", Api) and answer it with api(router.strip_prefix("/api", req).or(req)); the svc then sees /items/7 for /api/items/7 and keeps its own typed binding, 404 and 405.

Matching rules

• A path is split on / and each segment is percent-decoded (a %2F stays inside its segment); a bad escape or invalid UTF-8 is 400.
• Literal segments compare exactly, or case-insensitively with case_insensitive.
• {name} takes any non-empty segment, {name:int} decimal digits (up to 18, so it fits an Int), {name:uuid} the 8-4-4-4-12 hex form, {name:alpha} letters, and anything else after the colon is a regular expression that must match the whole segment. {name...} takes the rest of the path, slashes included, and may be empty only after a trailing slash (/assets/ gives ""; /assets redirects to /assets/).
• Among the routes whose path, host and method match, the most specific wins, segment by segment from the left: literal, then constrained parameter, then plain parameter, then rest; then a route with methods over one for any method. Equal routes are compile errors.
• No route serves the method but some have the path: 405 with every method those routes serve in Allow (with HEAD and OPTIONS when automatic), or 204 with Allow for OPTIONS.
• No route has the path but one has it with the trailing slash toggled: redirect (default), 404 (SlashStrict) or route it (SlashIgnore).
• An unclean path is redirected to clean_path of it first, unless clean_paths is off.

API

Types

• Route[T]: methods, pattern, host, tags and id. Entry[T] and Table[T]: a compiled table.
• Segment (Lit, Param, Rest) and Kind (AnyText, Digits, UuidText, Letters, Matching): parsed patterns.
• Options, Slash (SlashStrict, SlashRedirect, SlashIgnore), default_options().
• Match[T]: the id, pattern, tags and decoded parameters of the route that matched.
• Resolution[T]: Matched, Redirected, NoRoute, WrongMethod, OptionsAnswer, BadPath.

Building routes

• route(methods, pattern, id), get, post, put, patch, delete, any_method.
• on_host(r, host), tagged(r, tag), group(prefix, tags, routes) (groups nest).
• parse_pattern(pattern): the segments, or what is wrong with the pattern.
• compile(routes, options): the table, or every problem (bad patterns, bad methods, routes that can never match).

Routing

• resolve(t, req): the full Resolution.
• route_request(t, req): ok(match) or err(response), the usual way to dispatch.
• answer(resolution): the response for everything but a match: problem details for 400 and 404, 405 and 204 with Allow, redirects.
• param(m, name), param_int(m, name), has_tag(m, tag).
• allowed_methods(t, path), describe(t): what a path serves, and one line per route.

Paths and URLs

• clean_path(path): remove empty, . and .. segments, never above the root.
• decode_segment(s), encode_segment(s): percent-encoding for one path segment.
• kind_accepts(kind, s): whether a decoded segment fits a parameter kind.
• strip_prefix(prefix, req): the request as a handler mounted at prefix sees it.
• url_for(t, id, params, query): the URL of a route with its parameters filled in.

Out of scope

• Storing handler functions in the table (the language doesn't allow effect-generic records, and handlers can't share function values); dispatch on the id instead.
• Middleware: see the middleware package, and apply it per group with has_tag.
• Query-string and body binding: a svc does that with types; mount one under a prefix.
• Parameters inside a segment (/files/{name}.{ext}): a segment is either text or one parameter; use a regex kind such as {file:[^/]+\.json}.

License

MIT, see LICENSE.