-type bindings() :: #{binary() => binary() | [binary()]}.

Captured route parameters, populated by match/3.

:param segments produce a single binary value (#{~"id" => ~"42"}). *wildcard segments produce the list of remaining path segments (#{~"rest" => [~"a", ~"b"]}). Empty for routes with no captures.

Captured values are percent-decoded (/users/caf%C3%A9 binds <<"café"/utf8>>), consistent with query params; a segment whose percent-escapes are malformed (a % not followed by two hex digits) is kept raw. Decoding does not validate UTF-8, so %FF binds the raw 0xFF byte. There is no + -> space translation -- that is a query-string convention, so a literal + in a path stays a +.

Because decoding happens after the path is split on raw /, a decoded value can contain a / (%2F), a .., or a leading / — it is not a single clean path component. A handler that builds a filesystem path or an outbound URL from a captured value must reject .. and absolute segments itself; see roadrunner_static for the reference check.

-opaque compiled()

The compiled-routes representation match/3 consumes. Treat as opaque: the shape is an implementation detail and may change.

-type methods() :: [binary()] | undefined.

An HTTP-method allowlist for a route: a list of uppercase method binaries ([~"GET", ~"POST"]), or undefined to answer every method. compile/2 turns the list into a #{Method => true} set-map so match time is an O(1) is_map_key/2 rather than a list scan; methods are matched byte-exact against roadrunner_req:method/1 (already uppercase on the wire), so callers must pass uppercase.

Matching is literal: a [~"GET"] route does not implicitly answer HEAD (or any other verb) -- list every method the route accepts. A present methods must be a non-empty list of binaries; compile/2 raises {invalid_route_methods, _} on an empty list or non-binary entries (both would otherwise silently reject every request).

-type route() ::
          {Path :: binary(), Handler :: module()} |
          {Path :: binary(), Handler :: module(), State :: term()} |
          #{path := binary(),
            handler := module(),
            state => term(),
            middlewares => roadrunner_middleware:middleware_list(),
            methods => methods()}.

A single route entry. Three shapes are accepted:

• {Path, Handler} — shorthand: no state, no middlewares.
• {Path, Handler, State} — shorthand with state only.
• #{path := Path, handler := Handler, state => State, middlewares => Mws, methods => [~"GET", ...]} — map form; use this to attach per-route middlewares, an HTTP-method allowlist, or future per-route framework knobs.

Path is a binary pattern (literal segments, :param captures, or *wildcard catch-all). Handler is the module implementing roadrunner_handler. State is opaque per-route data threaded back to the handler via roadrunner_req:state/1; unset → undefined. methods is a list of uppercase method binaries the route answers; unset → every method.

-type routes() :: [route()].

An ordered list of routes; matched first-to-last.

-type validation_error() ::
          {invalid_route, route()} |
          {invalid_route_methods, term()} |
          {invalid_route_path, binary(), wildcard_not_last} |
          {unreachable_route, pos_integer(), binary(), [{pos_integer(), binary()}]}.

Why a route table was rejected, as returned by validate/1 and raised by compile/2.

• {invalid_route, Route} — the entry is not one of the accepted shapes, or its path is not a binary / its handler is not a module atom.
• {invalid_route_methods, Methods} — a methods key that is not a non-empty list of binaries.
• {invalid_route_path, Path, wildcard_not_last} — a segment after the pattern's *wildcard, which no request could ever reach.
• {unreachable_route, Position, Path, ShadowedBy} — the entries above this one already answer its path for every method it declares. Position is the 1-based index in the table and ShadowedBy lists the {Position, Path} of every earlier route taking work away from it.