feat: replace routing_tree with an in-tree routing trie and support multiple listeners

[Taure]

Finishes @burbas' work in #350, rebased onto current master. His commits are preserved in the history; #350 can be closed in favour of this.

Two goals, both from the 1.0 list: drop the external routing_tree dependency, and make Nova able to bind more than one port.

What was left to do

#350 compiles, but that is the only green light. It cannot boot: nova_router:routes/1 registers integer status-code routes for 404 and 500 on every startup, and the new trie had no clause for an integer path, so application:ensure_all_started(nova) died with a function_clause. It could not have served a request either: execute/2 and render_status_page/5 both call nova_routing_trie:find/4, which did not exist.

Behind that were the parity gaps: no [...] catch-all or pathinfo (so every static-file route was dead, including the one the rebar3_nova scaffold generates), no '_' any-method comparator (it normalised to <<"_">> while the sentinel was <<"ALL">>, making every websocket, static and methods => ['_'] route unmatchable), and no way to express 405 at all. insert/5 returned {ok, Trie} where the caller expected the tree, so any application with two routes failed to compile. compile/1 double-wrapped the options map, so use_strict_routing never reached the trie. And rebar.lock still pinned routing_tree 1.0.11, so the dependency was not actually gone.

Routing

nova_routing_trie now stands in for routing_tree. find/4 returns its shapes, including {error, comparator_not_found, AllowedMethods} for the 405 path. Integer status codes, the [...] catch-all and its pathinfo, and the '_' comparator all work. routes/1 is the supported way to introspect the table, since the trie itself is opaque.

Two matching improvements over routing_tree, both of which change which controller runs and are called out in guides/deprecations.md:

• Matching backtracks. /a/:x/c now matches /a/b/c even when a /a/b/d route exists. Previously matching committed to the first sibling it found and returned a 404.
• Every binding at a depth is reachable. /p/:id/picture and /p/:user_id/name both work. Previously only whichever one maps:fold visited first was, and which one that was depended on hash order.

Duplicate routes keep the first registration, as routing_tree did. add_routes/2 overwrites, which is what the routing guide has always promised.

Ambiguity detection only runs under use_strict_routing. As written it fired on /users/new alongside /users/:id, which would have warned on startup for most applications.

Router

Both find/4 call sites now call a function that exists, insert handles the real return shape, and lookup_url/4 passes arguments in the order the callee declares.

Two fixes worth singling out because they fail silently:

• plugin_strategy deduped with lists:ukeysort(1, ...) on {Type, Module, Opts} tuples, which keys on the phase. At most one pre_request and one post_request plugin survived per route, including on the default path where the route declares no local plugins. A stock configuration silently lost JSON body decoding, CORS and correlation IDs. Dedupe is now on {Type, Module} and preserves order, and the default strategy reproduces existing behaviour.
• remove_application/1 filtered on a 3-tuple while the trie emits 4-tuples, so it matched nothing and wiped the routing table for every application.

override_secure also accepted only a fun, so override_secure => true crashed compilation with a case_clause.

Multiple listeners

Each listener now owns its routing table, carried in its Cowboy env. Without that, all listeners shared one global nova_dispatch keyed only on host, path and method, so a second application on a second port made each listener answer for the other's routes: a second socket and nothing else.

The registry was created without a keypos, so every #nova_server{} row keyed on the record tag and it could hold exactly one entry — remove_application/1 answered {error, not_found} for every real application. add_application/2 on an already-bound port, the case guides/multi-app.md advertises, returned a bare ok into a case with no matching clause. Both are fixed, and removal now stops the listener and forgets its table only once nothing is left on it.

Graceful shutdown (#365) drains every listener. It suspended and stopped the single nova_listener atom, so any additional listener kept accepting connections through the drain and was killed outright at exit.

Testing

Nothing in this repo started Nova end to end, which is why a branch where the framework cannot boot survived for months. The only integration gate was nova_request_app, a separate repository that has to be updated by hand whenever Nova changes.

test/nova_test_app is a real Nova application — router, controllers, websocket controller, plugin, security callback, priv assets — with test/nova_test_sub_app mounted under a prefix. nova_full_app_SUITE drives it over a real Cowboy listener and nova_multi_listener_SUITE covers the lifecycle. Between them: bindings, precedence, every method, 405, redirects, status codes, host scoping, static directories, security and auth data, both plugin phases, custom error pages, crashes, websockets, sub-applications, runtime add and remove, and two listeners not serving each other's routes. Both run in CI on every OTP version.

Master's 25 test modules are ported off routing_tree, and nova_routing_trie_tests ports routing_tree's own suite as the parity checklist.

Two defects the new suites caught immediately

• An application's own status-code route was unreachable. Nova compiles first and routes are first-wins, so a {404, fun my_controller:not_found/1, #{}} entry in a router was silently ignored. Nova is now compiled last, making its error pages the defaults they were meant to be.
• resolve_nova_apps/2 (feat: support nested nova_apps #380) called lists:reverse/1 on an accumulator it was still accumulating, so as soon as any nova_app declared nova_apps of its own the resolution order came out scrambled. It also looked up nested apps with the whole {App, Options} tuple as the application name, so a sub-application in tuple form never had its own nova_apps resolved.

Not included

The #nova_handler_value.extra_state → extra rename is reverted for now — I asked on #350 whether it was deliberate. It is worth checking before it lands: nova_file_controller still reads extra_state in six places behind {status, 404} catch-alls, so the rename silently 404s every static route, and it also breaks the Req key that nova_json_schemas, egql_nova and nova_request_app read. Re-applying it is a one-line change plus lockstep updates downstream.

src/nova_request.erl, an unreferenced empty gen_server skeleton, is dropped. .github/labeler.yml is dropped too — the workflow that consumed it was deleted in #353.

Companion PR

rebar3_nova's routes, audit, openapi and doctor tasks all included routing_tree.hrl and destructured its records. novaframework/rebar3_nova#71 ports them to nova_routing_trie:routes/1 and needs to land with the Nova release.

Checks

rebar3 eunit 412/412, rebar3 ct 32/32, xref, dialyzer and ex_doc clean, elp lint clean. elp eqwalize-all is at 179 errors against master's 181 — nova_routing_trie is clean and nova_router is below where it started.

[Taure]

Both of the master-side defects this PR fixes are now split out into #406, so they can be reviewed and backported without the routing rewrite: resolve_nova_apps/2 returning applications in the wrong order, and an application's own status-code routes being unreachable.

This PR still contains both, as part of the nova_sup rewrite. If #406 lands first, this branch needs a git merge origin/master with its own nova_sup kept - it is a strict superset. Either merge order works.

[Taure]

Two things found while checking this branch against #408.

This closes #408

Verified against nova_routing_trie on this branch, using the declaration order from the nova-book my_first_nova example:

GET  /notes/new -> {ok,#{},new_form}
POST /notes/42  -> {ok,#{<<"id">> => <<"42">>},update}

On master the first of those returns {error,comparator_not_found,[<<"POST">>]}, which is the 405 the reporter sees. The cause is routing_tree:lookup_segment/4: it returns on the first sibling that matches, and a binding node matches any segment. Wildcards are carried as a deferred fallback, bindings never were, so there was no literal-beats-binding precedence at all. Since insert/4 prepends, sibling order is declaration order reversed, which is why the route declared first is the one that loses.

The trie here gets it right in both declaration orders, when both routes share a method, and for the backtracking and sibling-binding cases the description claims. Worth linking so #408 closes on merge.

use_strict_routing was not a no-op

guides/deprecations.md says:

use_strict_routing now takes effect. It never reached the routing table before, so it has been a no-op.

It did reach it. nova_router:compile/1 on master passes #{use_strict => UseStrict} into routing_tree:new/1, and routing_tree honours it. Against the released 1.0.11:

same method: /notes/new GET + /notes/:id GET   -> throws non_deterministic_paths
reverse:     /notes/:id GET + /notes/new GET   -> throws non_deterministic_paths
true dup:    /notes/new GET twice              -> throws duplicated_paths
diff method: /notes/new GET + /notes/:id POST  -> no throw
deeper:      /a/b/c GET + /a/:x/c GET          -> no throw

So it works, with holes: it only checks terminal segments and only when the comparators match. nova_request_app runs with it enabled in its prod config, and it is used the same way in private downstream applications, so this is live behaviour rather than a dormant flag. The entry should say it was inconsistent, not dead.

The overshadowing_route conflict is now a false positive

Under strict the trie rejects this:

insert /notes/:id -> {error,conflict,#{reason => overshadowing_route,
                                       conflicts_with => <<"/notes/new">>,
                                       incoming => {binding,<<"id">>}, ...}}

That is the pair guides/routing.md tells people to write two paragraphs earlier:

/users/new and /users/:id can therefore both be declared: /users/new serves the literal path and /users/:id serves everything else.

Both statements are in this PR. Before the rewrite the overlap was genuinely undecidable, so flagging it was reasonable. Now precedence is specified, matching backtracks, and the overlap resolves deterministically, so there is nothing left to warn about. Anyone who turns strict routing on is unable to follow the tutorial.

The other half of the check is still worth keeping. A duplicate path and method is silently first-wins, which is exactly the silent route drop the flag was turned on to catch, and that reason survives the rewrite intact.

Suggest narrowing strict to duplicates and genuine ambiguity (binding vs wildcard at the same depth), and dropping overshadowing_route. That resolves the contradiction with the routing guide without giving up the guard.