TASK-053 step 2: cut dispatch over to lookup_v2 behind flag

Adds resolve_resource_for_request_v2 alongside the v1 resolver and
routes finalize_answer through it by default (use_lookup_v2_ flag,
true by default; transitional — removed in step 3).

The new resolver:
  * Preserves the parent->single_resource fast path verbatim (it reads
    registered_resources, which v1 also did — that data store is
    orthogonal to the route-table tier choice).
  * Otherwise delegates to lookup_v2 (cache -> exact -> radix -> regex),
    extracts the shared_ptr<http_resource> arm of route_entry::handler,
    replays captured_params into mr->dhr via set_arg, and populates
    matched_path_template / matched_is_prefix for the hook ctx (gated
    on need_path_template like the v1 resolver).

Two correctness fixes wired in alongside the cutover:

  1. lookup_v2 was moving result.entry into the cache_value before
     returning result to the caller. Pre-TASK-053 no caller read
     result.entry.handler (lookup_pipeline_test only checks
     .found / .tier), so the bug was latent. Once the resolver started
     calling std::get_if<shared_ptr<...>> on the returned entry, every
     dispatch saw a moved-from variant and 404'd. Copy on insert
     instead — one shared_ptr ref-count bump and one captures-vector
     copy on the cache-miss path, no effect on cache hits.

  2. route_cache::find_by_view crashed on a fresh cache (bucket_count()
     == 0 on libc++; cbegin(0)/cend(0) dereferences a null bucket-list
     pointer). Pre-TASK-053 this path was test-only, so the UB was
     dormant; the dispatch cutover puts find_by_view on the request
     hot path, so the first request against a fresh server reliably
     reproduced the crash. Early-out when bucket_count() == 0.

All v2_dispatch_contract, routing_regression, lookup_pipeline,
route_table_concurrency, hooks_route_resolved_miss_and_hit,
webserver_register_path_prefix, webserver_on_methods, webserver_route
suites pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: etr

src/detail/webserver_dispatch.cpp

@@ -203,14 +203,17 @@ webserver_impl::lookup_v2(http_method method, const std::string& path) {
         }
     }  // table_lock released.
 
-    // Step 3: install into cache (cache mutex only). Move result.entry and
-    // result.captured_params into the cache_value to avoid a second copy
-    // of the shared_ptr ref-count bump and captured vector on the miss path.
-    // result is not used after this point.
+    // Step 3: install into cache (cache mutex only). Copy result.entry and
+    // result.captured_params into the cache_value — the caller (the v2
+    // resolver) consumes `result` after this returns, so a move-out of
+    // `result.entry` here would leave the caller's `std::get_if` reading a
+    // moved-from variant (the shared_ptr arm is null after a move, causing
+    // a false-negative 404). The copy is one shared_ptr ref-count bump and
+    // one std::vector copy on the miss path — cache hits are unaffected.
     if (result.found) {
         cache_value v;
-        v.entry = std::move(result.entry);
-        v.captured_params = std::move(result.captured_params);
+        v.entry = result.entry;
+        v.captured_params = result.captured_params;
         route_cache_v2.insert(key, std::move(v));
     }
 
@@ -293,6 +296,97 @@ void webserver_impl::apply_extracted_params(detail::modded_request* mr,
     }
 }
 
+// TASK-053 step 2: v2 lookup-backed resolver. Routes finalize_answer
+// through lookup_v2 (the 3-tier v2 table fronted by route_cache_v2)
+// instead of the v1 registered_resources* maps. See header comment in
+// webserver_impl_dispatch.hpp for the full contract.
+//
+// The dispatch path used to do:
+//   v1: hash registered_resources_str -> walk registered_resources_regex
+//       (with LRU front-end route_cache_list / route_cache_map).
+// This path now does:
+//   v2: lookup_v2() walks route_cache_v2 -> exact_routes_ ->
+//       param_and_prefix_routes_ -> regex_routes_, returning a
+//       route_entry whose handler arm is always shared_ptr<http_resource>
+//       (the on_*/route entry points wrap user lambdas in lambda_resource
+//       before storing; the variant's lambda_handler arm is dead code).
+//
+// The parent->single_resource fast path is intentionally preserved
+// here: it reads the single registered endpoint directly from
+// registered_resources rather than falling through to lookup_v2 (which
+// would also work because single_resource installs a radix prefix at
+// "/"). Reading registered_resources avoids the captured-params /
+// route_entry plumbing for a configuration that has no parameters.
+bool webserver_impl::resolve_resource_for_request_v2(detail::modded_request* mr,
+        std::shared_ptr<http_resource>& hrm) {
+    // matched_path_template + matched_is_prefix feed the route_resolved
+    // and before_handler hook ctxs. Skip the heap allocation when no
+    // hook in either phase is registered. Mirrors the v1 resolver.
+    const bool need_path_template =
+        has_hooks_for(hook_phase::route_resolved) ||
+        has_hooks_for(hook_phase::before_handler);
+
+    // single_resource fast path: the one registered endpoint serves
+    // every URL. Read it directly from registered_resources to mirror
+    // the v1 resolver's behaviour. registered_resources_mutex protects
+    // a registration-time data store; under dispatch we still need a
+    // shared lock to make the read-then-copy atomic with respect to a
+    // concurrent unregister_path. (NOTE: single_resource webservers do
+    // not support runtime register/unregister in practice, but the lock
+    // is cheap when uncontended and the safety guarantee is worth it.)
+    if (parent->single_resource) {
+        std::shared_lock registered_resources_lock(registered_resources_mutex);
+        if (registered_resources.empty()) return false;
+        const auto& only = *registered_resources.begin();
+        hrm = only.second;
+        if (need_path_template) {
+            mr->matched_path_template = only.first.get_url_complete();
+            mr->matched_is_prefix = only.first.is_family_url();
+        }
+        return true;
+    }
+
+    // v2 lookup pipeline: cache -> exact -> radix -> regex.
+    lookup_result result = lookup_v2(mr->method_enum, mr->standardized_url);
+    if (!result.found) return false;
+
+    // Extract the shared_ptr<http_resource> arm of the route_entry's
+    // variant. The on_* / route entry points wrap user lambdas in a
+    // lambda_resource shim and store the shim as shared_ptr<http_resource>,
+    // so this arm is the only one populated in practice; treat the
+    // lambda_handler arm as unreachable (defensive nullptr check below).
+    auto* hp = std::get_if<std::shared_ptr<http_resource>>(&result.entry.handler);
+    if (hp == nullptr || *hp == nullptr) {
+        // Unreachable today: lookup_v2 only returns entries whose
+        // handler is a shared_ptr<http_resource>. If a future task
+        // stores a lambda_handler directly we will need to grow this
+        // path; until then, treat as a not-found miss.
+        return false;
+    }
+    hrm = *hp;
+
+    // Replay captured URL parameters into the request. This is the v2
+    // equivalent of apply_extracted_params (which the v1 resolver calls
+    // on regex-tier hits). Per-name set_arg matches the v1 behaviour
+    // exactly — duplicates with later wins, etc.
+    if (mr->dhr != nullptr) {
+        for (const auto& [name, value] : result.captured_params) {
+            mr->dhr->set_arg(name, value);
+        }
+    }
+
+    // Populate the hook ctx scratch slots when at least one hook is
+    // registered for the phases that read them. v2 cache_value does
+    // not store the matched URL template; fall back to standardized_url
+    // (matches the v1 cache-hit path; see resolve_resource_for_request
+    // ll. 348-353).
+    if (need_path_template) {
+        mr->matched_path_template = mr->standardized_url;
+        mr->matched_is_prefix = result.entry.is_prefix;
+    }
+    return true;
+}
+
 bool webserver_impl::resolve_resource_for_request(detail::modded_request* mr,
         std::shared_ptr<http_resource>& hrm) {
     // TASK-048 perf: matched_path_template is only consumed by

src/detail/webserver_request.cpp

@@ -350,7 +350,12 @@ MHD_Result webserver_impl::finalize_answer(MHD_Connection* connection,
     // alive until our local shared_ptr drops at the end of
     // finalize_answer.
     std::shared_ptr<http_resource> hrm;
-    bool found = resolve_resource_for_request(mr, hrm);
+    // TASK-053 step 2: route through the v2 3-tier table (default) or
+    // the legacy v1 maps (use_lookup_v2_=false). Step 3 deletes the
+    // branch and the v1 resolver body together.
+    bool found = use_lookup_v2_
+        ? resolve_resource_for_request_v2(mr, hrm)
+        : resolve_resource_for_request(mr, hrm);
 
     // TASK-051: capture the resolved resource on the request so the
     // tail-end firing helpers (fire_response_sent_gated /

src/httpserver/detail/route_cache.hpp

@@ -138,7 +138,16 @@ class route_cache {
         // Walk the bucket manually via equal_range on the raw bucket index.
         // unordered_map::bucket() + bucket_begin()/bucket_end() lets us
         // scan the correct bucket without constructing a full cache_key.
-        std::size_t b = map_.bucket_count() ? bucket_hash % map_.bucket_count() : 0;
+        // TASK-053: empty-cache early-out. On libc++ a default-constructed
+        // unordered_map has bucket_count() == 0 and calling cbegin(0) /
+        // cend(0) dereferences a null bucket-list pointer (UB). Before
+        // TASK-053 this path was only hit by tests; the TASK-053 dispatch
+        // cutover puts find_by_view on the request hot path, so the first
+        // request against a fresh server reliably reproduced the crash.
+        if (map_.bucket_count() == 0) {
+            return false;
+        }
+        std::size_t b = bucket_hash % map_.bucket_count();
         for (auto it = map_.cbegin(b), end = map_.cend(b); it != end; ++it) {
             if (it->first.method == method && it->first.path == path) {
                 // Promote: splice requires a mutable iterator from the main map.

src/httpserver/detail/webserver_impl.hpp

@@ -229,6 +229,16 @@ class webserver_impl {
     // TASK-027 LRU front-end. 256 entries per architecture spec.
     route_cache route_cache_v2{ROUTE_CACHE_MAX_SIZE};
 
+    // TASK-053 step 2: transitional flag controlling whether
+    // finalize_answer routes its lookup through the v2 3-tier table
+    // (resolve_resource_for_request_v2 -> lookup_v2) or the legacy v1
+    // maps (resolve_resource_for_request). Default: v2.
+    //
+    // Step 3 of TASK-053 deletes this flag and the v1 resolver body in
+    // a separate commit so the diff stays reviewable in isolation. The
+    // flag exists only across step 2 / step 3.
+    bool use_lookup_v2_ = true;
+
     // tier_hit identifies which tier of the v2 route table answered a
     // lookup. Returned alongside the route_entry copy from lookup_v2()
     // so the dispatch site (and tests) can pin the lookup pipeline.

src/httpserver/detail/webserver_impl_dispatch.hpp

@@ -299,6 +299,24 @@ struct regex_route_lookup {
 bool resolve_resource_for_request(modded_request* mr,
         std::shared_ptr<::httpserver::http_resource>& hrm);
 
+// TASK-053 step 2: v2 lookup-backed resolver. Same observable
+// contract as resolve_resource_for_request (returns true + sets
+// @p hrm on hit, sets @p mr->matched_path_template + matched_is_prefix
+// when the hook ctx needs them; sets URL captures via mr->dhr->set_arg
+// for parameterized routes), but consults lookup_v2() and the v2 3-tier
+// route table (exact_routes_ / param_and_prefix_routes_ / regex_routes_)
+// fronted by route_cache_v2 instead of the v1 maps (registered_resources*
+// + route_cache_list). Selected over the v1 path at finalize_answer
+// per the use_lookup_v2_ flag on webserver_impl (default: true).
+//
+// Note: the parent->single_resource fast path is preserved here exactly
+// as in the v1 resolver — it reads registered_resources directly because
+// the configuration shape (one registered endpoint serves every URL) is
+// orthogonal to the route-table tier choice. (Folding it into lookup_v2
+// itself is cleaner long-term but would balloon the diff; deferred.)
+bool resolve_resource_for_request_v2(modded_request* mr,
+        std::shared_ptr<::httpserver::http_resource>& hrm);
+
 // LRU cache hit path: returns the cached match (hrm + url_pars +
 // chunks) and promotes the entry to the front of the list. Caller
 // must hold registered_resources_mutex (shared).