Shared path tree with interceptor accumulation during lookup

[SeanTAllen]

Supersedes #56, which identified the 404 interceptor gap but proposed fixing it within the existing per-method tree structure. Design exploration revealed that per-method trees are fundamentally wrong for path-scoped interceptors — the fix requires a structural change to the router.

Problem

Interceptors are path-scoped, but the router stores them only at leaf nodes in per-method trees. When a route lookup fails (404), no interceptors run except app-level response interceptors passed through a side channel (_Listener → _Connection._app_response_interceptors).

This has two consequences:

1. Group interceptors don't run on 404s. An auth request interceptor on /api should reject unauthenticated requests to /api/nonexistent. A CORS response interceptor on /api should add headers to 404 responses under /api. Neither happens today.

2. Per-method trees duplicate (or fail to duplicate) interceptors. Interceptors registered via a group with only GET routes exist only in the GET tree. A HEAD request to a non-existent path under that group accumulates no interceptors from the HEAD tree (which may not even have the group's nodes), producing different 404 behavior depending on which HTTP methods happen to have routes.

Design

Single shared path tree

Replace the per-method tree map (Map[String, _BuildNode ref]) with a single shared path tree. Handlers are keyed by HTTP method at the leaf nodes. Interceptors live on the shared path nodes and are method-independent.

Tree node structure changes:

• _factory: (HandlerFactory | None) → method-keyed map at the leaf (e.g., Map[String, _MethodEntry] where _MethodEntry carries the factory and per-route interceptors)
• _wildcard_factory → same method-keyed map treatment
• _interceptors and _response_interceptors move from leaf-only to every node (intermediate nodes carry group-level interceptors)
• Per-route interceptors stay method-specific (stored in the method entry, not on the path node)

HEAD→GET fallback simplifies: One traversal, then check HEAD key → GET key at the leaf. No second tree walk. Interceptors are identical for both methods (same path nodes traversed).

Interceptor accumulation during lookup

During _lookup, each node the traversal visits contributes its interceptors. On a successful match, the handler gets the full accumulated set. On a failed match (404), the partial traversal produces interceptors accumulated to the deepest point.

Pre-computation at freeze time: To avoid per-request allocation, freeze() pre-computes the accumulated-from-root interceptor arrays at each node. Each _TreeNode val stores the cumulative interceptors from root to itself. On a hit, the leaf returns its pre-computed array. On a miss, the deepest reached node returns its pre-computed array. Zero allocation at request time for both paths.

Lookup return type

lookup() returns (_RouteMatch | _RouteMiss) instead of (_RouteMatch | None).

_RouteMatch is unchanged — factory (guaranteed), interceptors, response interceptors, params.

_RouteMiss is new — carries accumulated request and response interceptors from the partial traversal. No factory, no params.

_Connection._process_request matches exhaustively on the union. On _RouteMiss: runs request interceptors (may short-circuit with 401/403), then sends 404 with response interceptors applied. On _RouteMatch: dispatches as today.

Group info preserved to tree-building time

The current RouteGroup._flatten_into() pre-concatenates group interceptors onto each route and discards the group identity. The tree builder never learns which prefix carried which interceptors.

The new design separates group metadata from route flattening:

• Application and RouteGroup track _GroupInfo entries (prefix + interceptors) alongside flattened routes
• _flatten_into() no longer concatenates interceptors — it only joins paths and passes through per-route interceptors
• Application.serve() registers group infos with the builder via add_interceptors(path, req, resp), which tags intermediate nodes
• For nested groups, inner group prefixes are joined with outer group prefixes when collecting upward

The builder gets a method to register path-node interceptors separately from route handlers:

fun ref add_interceptors(path, req_interceptors, resp_interceptors)
fun ref add(method, path, factory, per_route_req_interceptors, per_route_resp_interceptors)

What gets removed

• _app_response_interceptors field on _Connection and _Listener — the tree root carries app-level interceptors; traversal accumulates them into every result
• Pre-concatenation loop in Application.serve() — app interceptors go on the root node via add_interceptors
• Pre-concatenation in RouteGroup._flatten_into() — group interceptors go on group prefix nodes
• Per-method tree map on _RouterBuilder and _Router — single root node

_ConcatInterceptors and _ConcatResponseInterceptors remain — used during freeze() to pre-compute accumulated arrays.

Behavioral changes

Request interceptors run on 404

This is a breaking change from current behavior. Currently zero request interceptors run on any 404. Under the new design, traversal-accumulated request interceptors run on 404 for paths that traverse through group nodes. App-level request interceptors (on the root node) run on all 404s.

This is the intended behavior — the auth use case requires it. An auth interceptor that returns InterceptRespond will produce a 401/403 instead of 404, preventing information leakage about API structure to unauthenticated users.

The _RouteMiss path in _Connection: run request interceptors → if any short-circuit, respond with the intercept response (with response interceptors applied); if all pass, respond 404 (with response interceptors applied).

Per-method group interceptors no longer possible

In the shared tree, a path node has one interceptor array — interceptors are path-scoped, not method-scoped.

Today, a user could create two groups with the same prefix and different interceptors for different methods:

let get_api = RouteGroup("/api"
  where interceptors = recover val [as RequestInterceptor val: CacheInterceptor] end)
get_api.>get("/users", users_factory)

let post_api = RouteGroup("/api"
  where interceptors = recover val [as RequestInterceptor val: CsrfInterceptor] end)
post_api.>post("/users", create_user_factory)

app.>group(consume get_api)
app.>group(consume post_api)

GET /api/users gets [CacheInterceptor], POST /api/users gets [CsrfInterceptor]. This works today as an accident of per-method trees — each method has its own tree, so the two groups' interceptors never conflict. It was never a designed capability.

In the shared tree, /api is one node. It can't carry both [CacheInterceptor] and [CsrfInterceptor] separately. The user's intent — different interceptors for different methods on the same path — is better expressed as per-route interceptors, which remain method-specific in the new design:

let api = RouteGroup("/api")
api.>get("/users", users_factory
  where interceptors = recover val [as RequestInterceptor val: CacheInterceptor] end)
api.>post("/users", create_user_factory
  where interceptors = recover val [as RequestInterceptor val: CsrfInterceptor] end)

Registering two groups with the same prefix should be treated as an error at add_interceptors time — it catches mistakes rather than silently picking a winner.

What doesn't change

The user-facing API is identical. add_request_interceptor(), add_response_interceptor(), group-level interceptors, per-route interceptors — all the same registration calls and signatures.

[SeanTAllen]

Design constraint: overlapping route group prefixes must be rejected at startup, not silently resolved at runtime.

_RouterBuilder.add_interceptors() should fail when it encounters a node that already has interceptors — that means two groups claimed the same prefix. This is a configuration error: two sibling groups under the same parent is fine (/api/users and /api/items), but two groups both claiming /api with different interceptors is ambiguous and should be caught before the server starts serving traffic.

The failure should happen during Application.serve(), before the listener is created — not when handling a request.

[SeanTAllen]

Implementation Plan

1. New types: _RouteMiss, _MethodEntry, _GroupInfo

hobby/_route_match.pony — add _RouteMiss alongside _RouteMatch (same file, paired concepts):

class val _RouteMiss
  let response_interceptors: (Array[ResponseInterceptor val] val | None)
  let interceptors: (Array[RequestInterceptor val] val | None)

hobby/_method_entry.pony (new file) — per-method handler + per-route interceptors at a leaf:

class val _MethodEntry
  let factory: HandlerFactory
  let interceptors: (Array[RequestInterceptor val] val | None)
  let response_interceptors: (Array[ResponseInterceptor val] val | None)

hobby/_group_info.pony (new file) — group metadata preserved for tree building:

class val _GroupInfo
  let prefix: String
  let interceptors: (Array[RequestInterceptor val] val | None)
  let response_interceptors: (Array[ResponseInterceptor val] val | None)

2. Router: single tree with method-keyed leaves

hobby/_router.pony — this is the largest change.

_BuildNode changes:

• Remove: _factory, _wildcard_factory, _wildcard_response_interceptors, _wildcard_interceptors
• Add: embed _method_entries: Map[String, _MethodEntry] — handlers keyed by method string
• Add: embed _wildcard_entries: Map[String, _MethodEntry] — wildcards also method-keyed
• Keep: _interceptors, _response_interceptors — now used at every node, not just leaves
• insert() takes method key and stores factory + per-route interceptors in the method map

_BuildNode.freeze() changes:

• Accept parent accumulated interceptors as parameters
• Compute this_accumulated = _ConcatInterceptors(parent, own) for both req and resp
• Store pre-computed accumulated arrays on the frozen _TreeNode
• Pre-compute leaf entries: for each method entry at this node, concatenate accumulated path interceptors with per-route interceptors into the entry's final arrays
• Overlapping group detection happens in add_interceptors, not in freeze()

_TreeNode changes:

• Remove: _factory, _wildcard_factory, per-leaf interceptor fields
• Add: _method_entries: (Map[String, _MethodEntry] val | None) — None when empty
• Add: _wildcard_entries: (Map[String, _MethodEntry] val | None)
• Add: _accumulated_interceptors: (Array[RequestInterceptor val] val | None) — pre-computed root-to-here
• Add: _accumulated_response_interceptors: (Array[ResponseInterceptor val] val | None)

_TreeNode._lookup() changes:

• Return type: (_RouteMatch | _RouteMiss) instead of the current tuple-or-None
• No per-request accumulation — read pre-computed arrays from nodes
• On match: resolve method from _method_entries, build _RouteMatch with pre-computed interceptors (accumulated + per-route, already concatenated at freeze time)
• On miss: build _RouteMiss from deepest reached node's _accumulated_* fields
• HEAD→GET fallback: check HEAD key then GET key in _method_entries at the leaf — one traversal
• Wildcard: same method-keyed lookup in _wildcard_entries

_RouterBuilder changes:

• Remove: Map[String, _BuildNode ref] (per-method trees)
• Add: single _BuildNode ref root
• Change add() signature: takes method, path, factory, per-route interceptors (not pre-concatenated)
• Add add_interceptors(path, req, resp): traverses the tree to find (or create) the node at path using the same prefix-matching logic as insert (handles post-split node structure correctly), then tags it with interceptors. Panics if node already has interceptors (overlapping groups is a programmer error). Note: add_interceptors may be called before or after routes are registered — the tree traversal must work in either case

_Router changes:

• Remove: Map[String, _TreeNode val]
• Add: single _TreeNode val root
• lookup(method, path) delegates to root's _lookup, passes method for leaf resolution

3. Group info preservation

hobby/route_group.pony — RouteGroup changes:

• Add: embed _group_infos: Array[_GroupInfo] — tracks nested group metadata
• _flatten_into() → rename/split into _flatten_routes_into() and _collect_group_infos()
• _flatten_routes_into(): joins paths only, passes through per-route interceptors unchanged (no concatenation)
• _collect_group_infos(target, outer_prefix): emits this group's _GroupInfo(_JoinPath(outer_prefix, _prefix), interceptors, response_interceptors) plus any nested group infos (with prefixes joined through all nesting levels)
• group(): captures inner group's infos into _group_infos (with prefix joining) before consuming it and flattening its routes. Both RouteGroup.group() and Application.group() must call _collect_group_infos before _flatten_routes_into

hobby/_route_definition.pony — no more pre-concatenated interceptors. Fields stay the same but now carry only per-route interceptors. Update docstring to reflect the semantic change.

4. Application.serve() changes

hobby/application.pony:

• Add: embed _group_infos: Array[_GroupInfo]
• group(): calls g_ref._collect_group_infos(_group_infos) before g_ref._flatten_routes_into(_routes)
• serve():
  • Register app-level interceptors on root node directly (root _BuildNode has prefix "")
  • Register each group's interceptors: builder.add_interceptors(gi.prefix, gi.interceptors, gi.response_interceptors)
  • Register routes with per-route interceptors only: builder.add(r.method, r.path, r.factory, r.interceptors, r.response_interceptors)
  • Remove pre-concatenation loop (_ConcatInterceptors calls)
  • Remove app_response_interceptors from _Listener constructor call

5. Listener and Connection changes

hobby/_listener.pony:

• Remove: _response_interceptors field and constructor parameter
• _on_accept(): stop passing response interceptors to _Connection

hobby/_connection.pony:

• Remove: _app_response_interceptors field and constructor parameter
• _process_request():
  • _router.lookup() now returns (_RouteMatch | _RouteMiss)
  • HEAD→GET fallback handled inside the router (single traversal), no second _router.lookup() call
  • Match on _RouteMatch: call _dispatch() as today
  • Match on _RouteMiss: run request interceptors (may short-circuit with intercept response + response interceptors), then send 404 with response interceptors

6. Update _flatten.pony

• _ConcatInterceptors and _ConcatResponseInterceptors stay — used by freeze() for pre-computation
• _JoinPath and _TrimTrailingSlash stay unchanged

7. Update tests

hobby/_test_router.pony:

• Update lookup() return matching — (_RouteMatch | _RouteMiss) instead of (_RouteMatch | None)
• Specific tests that match None and must change to _RouteMiss:
  • _PropertyUnregisteredReturnsNone → rename to _PropertyUnregisteredReturnsMiss, match _RouteMiss explicitly
  • _PropertyMethodIsolation → second match (non-registered method) must match _RouteMiss not None
  • _PropertyInsertionOrderInvariance → update (None, None) arm to (_RouteMiss, _RouteMiss)
• New tests:
  • Interceptor accumulation: register interceptors at /api node, verify they appear on matched routes under /api
  • 404 accumulation: lookup /api/nonexistent, verify _RouteMiss carries /api node interceptors
  • Root-level 404: lookup /nonexistent, verify _RouteMiss carries root interceptors
  • HEAD→GET fallback: single traversal, verify correct factory returned
  • HEAD 404 interceptors: verify HEAD 404 under a GET-only group gets the group's interceptors
  • Overlapping group prefix rejection: add_interceptors called twice for same prefix should panic
  • Per-route interceptors method-specific: GET and POST at same leaf with different per-route interceptors

hobby/_test_route_group.pony:

• Update to match new _flatten_routes_into / _collect_group_infos API
• _TestEmptyGroup and _TestMultipleGroupsOnApplication: update direct _flatten_into calls to new names
• Add test: nested group infos collected with joined prefixes
• _PropertyGroupFlattenEquivalence: currently uses router.lookup(...) isnt None which becomes vacuously true. Must rewrite to match on _RouteMatch vs _RouteMiss explicitly

hobby/_test_request_interceptor.pony:

• Integration tests: update to verify interceptors fire on 404s under groups

hobby/_test_response_interceptor.pony:

• _TestResponseInterceptorOn404: update — now gets group-level interceptors, not just app-level
• Add test: group response interceptor runs on 404 under that group's prefix

hobby/_test_integration.pony:

• Existing HEAD tests: verify behavior unchanged
• Add integration test: 404 under a group with auth interceptor returns 401/403
• Add integration test: 404 under a group with CORS response interceptor gets CORS headers

8. Release notes and CLAUDE.md

VERSION is 0.4.1 (not 0.0.0), so release notes required. This is a "changed" entry:

• Request interceptors now run on 404 responses when the request path traverses through a group with interceptors
• Response interceptors from groups now run on 404 responses under that group's prefix (previously only app-level response interceptors ran on 404)

CLAUDE.md updates: router architecture (single tree, method-keyed leaves), interceptor model, file layout.

Files to modify

• hobby/_router.pony — largest change (single tree, method-keyed leaves, freeze-time pre-computation)
• hobby/_route_match.pony — add _RouteMiss alongside _RouteMatch
• hobby/_method_entry.pony — new file
• hobby/_group_info.pony — new file
• hobby/_route_definition.pony — docstring update (per-route only)
• hobby/_flatten.pony — remove concat calls from flattening (keep primitives)
• hobby/application.pony — group info tracking, serve() changes
• hobby/route_group.pony — split flatten, collect group infos
• hobby/_listener.pony — remove response_interceptors field/param
• hobby/_connection.pony — remove _app_response_interceptors, new match on lookup result
• hobby/_test_router.pony — update all tests, add new tests
• hobby/_test_route_group.pony — update for new API
• hobby/_test_request_interceptor.pony — add 404 interceptor tests
• hobby/_test_response_interceptor.pony — add 404 interceptor tests
• hobby/_test_integration.pony — add 404 interceptor integration tests
• hobby/CLAUDE.md — update architecture documentation

[SeanTAllen]

Implemented in #59.

[SeanTAllen]

Implemented.