nova_routing_trie (nova v0.18.1)

View Source

Host-aware routing trie. This is Nova's dispatch table: a map from host to a tree of path segments, where each terminal node holds one payload per comparator (HTTP method).

Paths are declared with three kinds of segment:

  • "/users" - a literal segment.
  • "/users/:id" - a binding. Matches one segment and binds it under <<"id">> in the returned bindings map.
  • "/assets/[...]" - a catch-all. Matches zero or more trailing segments, which are returned as PathInfo. Only valid as the last segment of a path.

A path may also be an integer, in which case it denotes an HTTP status code rather than a URL. Nova uses this to register error pages.

Matching is deterministic: at each depth a literal segment is tried first, then each binding in name order, then the catch-all. Matching backtracks, so "/a/:x/c" still matches "/a/b/c" even when a "/a/b/d" route exists.

Summary

Types

bindings()
child_key()
comparator()
comparator_in()
conflict()
host_in()
path()
payload()
route()
trie()
trie_node()

Functions

find(HostIn, Path, ComparatorIn, Trie)

Look up a route.

foldl/2

Rebuild the trie from a transformation of its routes. Fun is handed every route in the table and returns the routes the new table should contain, which makes it the way to filter or rewrite the dispatch table wholesale.

from_list(Routes)
from_list(Routes, RootOpts)
insert(Path, Comparator, Payload, Trie)

Insert a route. Path is a URL or an HTTP status code, Comparator is an HTTP method or `_'' to match any method.

insert(HostIn, Path, Comparator, Payload, Trie)
insert/6
member(HostIn, Path, Trie)
member(HostIn, Path, Comparator, Trie)
new()
new(Opts)

Create an empty trie. Recognised options are strict (also accepted as use_strict for compatibility) and on_duplicate, which is either keep_first (the default) or overwrite.

routes/1

Every route in the trie, as {Host, Path, Comparator, Payload}. This is the supported way to introspect a dispatch table; the trie itself is opaque. The result can be fed straight back into from_list/1.

to_list(Trie)

A flat, human-readable listing of the routing table, one entry per method and path. Payloads are not included - use routes/1 when you need them.

Types

bindings()

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

child_key()

-type child_key() :: binary() | {binding, binary()} | '...' | integer().

comparator()

-type comparator() :: '_' | binary().

comparator_in()

-type comparator_in() :: comparator() | atom() | list().

conflict()

-type conflict() ::
          #{reason := atom(),
            at := [child_key()],
            existing := child_key() | undefined,
            incoming := child_key() | undefined,
            conflicts_with := path(),
            incoming_path := path(),
            comparator := comparator(),
            existing_methods := [comparator()]}.

host_in()

-type host_in() :: '_' | binary() | list() | atom().

path()

-type path() :: binary() | list() | integer().

payload()

-type payload() :: term().

route()

-type route() ::
          {path(), comparator_in(), payload()} |
          {host_in(), path(), comparator_in(), payload()} |
          {host_in(), path(), comparator_in(), payload(), map()}.

trie()

-opaque trie()

trie_node()

-opaque trie_node()

Functions

find(HostIn, Path, ComparatorIn, Trie)

-spec find(host_in(), path(), comparator_in(), trie()) ->
              {ok, bindings(), payload()} |
              {ok, bindings(), payload(), PathInfo :: [binary()]} |
              {error, not_found} |
              {error, comparator_not_found, [comparator()]}.

Look up a route.

A host-specific tree is consulted when one exists for Host, and the `_'' tree otherwise. PathInfo is only returned when the match was made by a [...] catch-all and there were trailing segments to report.

{error, comparator_not_found, AllowedMethods} means the path matched but the method did not, which is what Nova turns into a 405.

foldl/2

-spec foldl(trie(), fun(([route()]) -> [route()])) -> {ok, trie()} | {error, conflict, conflict()}.

Rebuild the trie from a transformation of its routes. Fun is handed every route in the table and returns the routes the new table should contain, which makes it the way to filter or rewrite the dispatch table wholesale.

from_list(Routes)

-spec from_list([route()]) -> {ok, trie()} | {error, conflict, conflict()}.

from_list(Routes, RootOpts)

-spec from_list([route()], map()) -> {ok, trie()} | {error, conflict, conflict()}.

insert(Path, Comparator, Payload, Trie)

-spec insert(path(), comparator_in(), payload(), trie()) -> {ok, trie()} | {error, conflict, conflict()}.

Insert a route. Path is a URL or an HTTP status code, Comparator is an HTTP method or `_'' to match any method.

Returns {error, conflict, Conflict} when the trie is in strict mode and the route clashes with an existing one. In non-strict mode a clash is logged and resolved according to the on_duplicate option.

insert(HostIn, Path, Comparator, Payload, Trie)

-spec insert(host_in(), path(), comparator_in(), payload(), trie()) ->
                {ok, trie()} | {error, conflict, conflict()}.

insert/6

-spec insert(host_in(), path(), comparator_in(), payload(), trie(), map()) ->
                {ok, trie()} | {error, conflict, conflict()}.

member(HostIn, Path, Trie)

-spec member(host_in(), path(), trie()) -> boolean().

member(HostIn, Path, Comparator, Trie)

-spec member(host_in(), path(), comparator_in(), trie()) -> boolean().

new()

-spec new() -> trie().

new(Opts)

-spec new(map()) -> trie().

Create an empty trie. Recognised options are strict (also accepted as use_strict for compatibility) and on_duplicate, which is either keep_first (the default) or overwrite.

routes/1

-spec routes(trie()) -> [route()].

Every route in the trie, as {Host, Path, Comparator, Payload}. This is the supported way to introspect a dispatch table; the trie itself is opaque. The result can be fed straight back into from_list/1.

to_list(Trie)

-spec to_list(trie()) -> [binary()].

A flat, human-readable listing of the routing table, one entry per method and path. Payloads are not included - use routes/1 when you need them.