TASK-053 step 3: remove v1 fallback + rename route_cache_v2

finalize_answer now unconditionally routes through the v2 resolver
(no flag). The v1 resolver body and its four helpers
(lookup_route_cache, scan_regex_routes, store_route_cache,
apply_extracted_params) are deleted together with the v1 LRU cache
(route_cache_list / route_cache_map / route_cache_mutex_) and the
regex_route_lookup / regex_route_scan_hit carrier structs. The v2
resolver is renamed in place from resolve_resource_for_request_v2 to
resolve_resource_for_request — there is now a single dispatch resolver.

invalidate_route_cache() collapses to a single route_lru_cache.clear()
since the v1 cache is gone. The lock-order comments in
webserver_register.cpp / webserver_routes.cpp are refreshed: the
order is now registration mutex (registered_resources_mutex) ->
route_table_mutex_ -> route_lru_cache's internal mutex.

The route_cache_v2 field is renamed to route_lru_cache, dropping
the TODO(Cycle K) marker — this was the rename the v2.0 plan
deferred to the dispatch cutover, and the cutover landed here. The
class itself stays named `route_cache` (only the field rename is in
scope per the plan).

The five v1-side registration-time maps
(registered_resources / _str / _regex + registered_resources_mutex)
are intentionally retained: prepare_or_create_lambda_shim reads
registered_resources for lambda+class conflict detection and the
WebSocket dispatch path uses registered_resources_mutex. Both are
non-dispatch concerns; their removal is its own follow-up task
(see TASK-053 §11). The header block comment is updated to make the
"registration-only after TASK-053" status explicit.

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

@@ -95,15 +95,10 @@ namespace detail {
 // route_resolved and before_handler firing sites landed.
 
 void webserver_impl::invalidate_route_cache() {
-    // Clear both the v1 and v2 caches. v1's cache is keyed on
-    // standardized_url only; v2's is keyed on (method, path). A
-    // registration may invalidate both, so clear both atomically.
-    {
-        std::lock_guard<std::mutex> lock(route_cache_mutex_);
-        route_cache_list.clear();
-        route_cache_map.clear();
-    }
-    route_cache_v2.clear();
+    // Clear the v2 LRU cache. (The v1 dispatch cache — route_cache_list
+    // / route_cache_map / route_cache_mutex_ — was removed in TASK-053
+    // step 3 along with the v1 resolver.)
+    route_lru_cache.clear();
 }
 
 // TASK-027: 3-tier route lookup. Pipeline:
@@ -153,7 +148,7 @@ webserver_impl::lookup_v2(http_method method, const std::string& path) {
     // into a cache_key on every call, including warm-cache hits.
     // cache_key is only constructed when an insert is needed (miss path).
     cache_value cached;
-    if (route_cache_v2.find_by_view(method, lookup_path, cached)) {
+    if (route_lru_cache.find_by_view(method, lookup_path, cached)) {
         result.found = true;
         result.tier = tier_hit::cache;
         result.entry = std::move(cached.entry);
@@ -214,7 +209,7 @@ webserver_impl::lookup_v2(http_method method, const std::string& path) {
         cache_value v;
         v.entry = result.entry;
         v.captured_params = result.captured_params;
-        route_cache_v2.insert(key, std::move(v));
+        route_lru_cache.insert(key, std::move(v));
     }
 
     return result;
@@ -224,88 +219,15 @@ webserver_impl::lookup_v2(http_method method, const std::string& path) {
 
 namespace detail {
 
-std::optional<webserver_impl::regex_route_lookup>
-webserver_impl::lookup_route_cache(const std::string& key) {
-    std::lock_guard<std::mutex> cache_lock(route_cache_mutex_);
-    auto cache_it = route_cache_map.find(key);
-    if (cache_it == route_cache_map.end()) {
-        return std::nullopt;
-    }
-    // Cache hit — promote to LRU front and copy the match data while
-    // still under the cache lock, so a concurrent invalidation can't
-    // free the cached endpoint out from under us.
-    // The shared_ptr copy (cached.resource) performs an atomic refcount bump
-    // while holding route_cache_mutex_ exclusively. This is the hottest
-    // point in the dispatch path; the atomic op is unavoidable as long as
-    // callers need the resource to survive a concurrent unregister_resource.
-    route_cache_list.splice(route_cache_list.begin(), route_cache_list, cache_it->second);
-    const route_cache_entry& cached = cache_it->second->second;
-    return regex_route_lookup{
-        cached.resource,
-        cached.matched_endpoint.get_url_pars(),
-        cached.matched_endpoint.get_chunk_positions(),
-    };
-}
-
-std::optional<webserver_impl::regex_route_scan_hit>
-webserver_impl::scan_regex_routes(const detail::http_endpoint& target) {
-    // Longest-match-wins tie-breaking: prefer the endpoint with more
-    // url-pieces; among equals, prefer the longer url_complete string.
-    bool found = false;
-    size_t len = 0;
-    size_t tot_len = 0;
-    map<detail::http_endpoint, std::shared_ptr<http_resource>>::iterator found_endpoint;
-    for (auto it = registered_resources_regex.begin();
-            it != registered_resources_regex.end(); ++it) {
-        size_t endpoint_pieces_len = it->first.get_url_pieces().size();
-        size_t endpoint_tot_len = it->first.get_url_complete().size();
-        if (found && endpoint_pieces_len <= len
-                && !(endpoint_pieces_len == len && endpoint_tot_len > tot_len)) {
-            continue;
-        }
-        if (!it->first.match(target)) continue;
-        found = true;
-        len = endpoint_pieces_len;
-        tot_len = endpoint_tot_len;
-        found_endpoint = it;
-    }
-    if (!found) return std::nullopt;
-    return regex_route_scan_hit{found_endpoint->first, found_endpoint->second};
-}
-
-void webserver_impl::store_route_cache(const std::string& key,
-                                       const detail::http_endpoint& matched,
-                                       std::shared_ptr<http_resource> hrm) {
-    std::lock_guard<std::mutex> cache_lock(route_cache_mutex_);
-    route_cache_list.emplace_front(key, route_cache_entry{matched, std::move(hrm)});
-    route_cache_map[key] = route_cache_list.begin();
-    if (route_cache_map.size() > ROUTE_CACHE_MAX_SIZE) {
-        route_cache_map.erase(route_cache_list.back().first);
-        route_cache_list.pop_back();
-    }
-}
-
-void webserver_impl::apply_extracted_params(detail::modded_request* mr,
-        const detail::http_endpoint& target,
-        const std::vector<std::string>& url_pars,
-        const std::vector<int>& chunks) {
-    const auto& url_pieces = target.get_url_pieces();
-    for (unsigned int i = 0; i < url_pars.size(); i++) {
-        if (chunks[i] < 0 || static_cast<size_t>(chunks[i]) >= url_pieces.size()) continue;
-        mr->dhr->set_arg(url_pars[i], url_pieces[chunks[i]]);
-    }
-}
-
-// 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.
+// TASK-053: v2 lookup-backed resolver. Routes finalize_answer through
+// lookup_v2 (the 3-tier v2 table fronted by route_lru_cache) — the v1
+// resolver and its helpers (lookup_route_cache, scan_regex_routes,
+// store_route_cache, apply_extracted_params) were deleted in TASK-053
+// step 3. 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_ ->
+// The dispatch path now does:
+//   lookup_v2() walks route_lru_cache -> 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
@@ -317,22 +239,22 @@ void webserver_impl::apply_extracted_params(detail::modded_request* mr,
 // 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,
+bool webserver_impl::resolve_resource_for_request(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.
+    // hook in either phase is registered.
     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
+    // every URL. Read it directly from registered_resources.
+    // 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);
@@ -366,9 +288,9 @@ bool webserver_impl::resolve_resource_for_request_v2(detail::modded_request* mr,
     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.
+    // equivalent of the v1-era apply_extracted_params (removed in
+    // TASK-053 step 3). Per-name set_arg matches 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);
@@ -378,90 +300,14 @@ bool webserver_impl::resolve_resource_for_request_v2(detail::modded_request* mr,
     // 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).
+    // (matches the v1 cache-hit path the legacy resolver used).
     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
-    // fire_route_resolved_gated and the before_handler firing site, both
-    // of which are gated by their respective any_hooks_ entries. Skip the
-    // heap allocation on every matched request when no hooks are registered.
-    const bool need_path_template =
-        has_hooks_for(hook_phase::route_resolved) ||
-        has_hooks_for(hook_phase::before_handler);
-
-    std::shared_lock registered_resources_lock(registered_resources_mutex);
-
-    if (parent->single_resource) {
-        hrm = registered_resources.begin()->second;
-        // single_resource: the one registered endpoint serves every URL.
-        // Capture its key for the route_resolved/before_handler hook ctx.
-        if (need_path_template) {
-            const auto& only = *registered_resources.begin();
-            mr->matched_path_template = only.first.get_url_complete();
-            mr->matched_is_prefix = only.first.is_family_url();
-        }
-        return true;
-    }
-
-    auto exact_it = registered_resources_str.find(mr->standardized_url.c_str());
-    if (exact_it != registered_resources_str.end()) {
-        // Copy the shared_ptr (atomic refcount bump) while the shared_lock
-        // on registered_resources_mutex is still held. The copy extends the
-        // resource's lifetime past a concurrent unregister_path that might
-        // erase this slot — without the copy, dispatch_resource_handler
-        // could hold a dangling pointer. The single atomic op is the
-        // unavoidable cost of the use-after-unregister safety guarantee.
-        hrm = exact_it->second;
-        // Exact-match: the registration key equals the standardized URL.
-        // Copy into modded_request so the hook context's string_view is
-        // safe across hook calls even if a concurrent unregister_path
-        // erases the slot.
-        if (need_path_template) {
-            mr->matched_path_template = exact_it->first;
-            mr->matched_is_prefix = false;
-        }
-        return true;
-    }
-
-    if (!parent->regex_checking) return false;
-
-    detail::http_endpoint endpoint(mr->standardized_url.c_str(), false, false, false);
-
-    if (auto cached = lookup_route_cache(mr->standardized_url)) {
-        hrm = cached->hrm;
-        apply_extracted_params(mr, endpoint, cached->url_pars, cached->chunks);
-        if (need_path_template) {
-            // Cache layer dropped the matched endpoint at its API boundary;
-            // fall back to the requested URL as a stable approximation of
-            // the path_template (used by the route_resolved hook ctx only).
-            mr->matched_path_template = mr->standardized_url;
-            mr->matched_is_prefix = false;
-        }
-        return true;
-    }
-
-    auto scan_hit = scan_regex_routes(endpoint);
-    if (!scan_hit) return false;
-
-    hrm = scan_hit->hrm;
-    store_route_cache(mr->standardized_url, scan_hit->endpoint, hrm);
-    apply_extracted_params(mr, endpoint, scan_hit->endpoint.get_url_pars(),
-                           scan_hit->endpoint.get_chunk_positions());
-    if (need_path_template) {
-        mr->matched_path_template = scan_hit->endpoint.get_url_complete();
-        mr->matched_is_prefix = scan_hit->endpoint.is_family_url();
-    }
-    return true;
-}
-
 std::string webserver_impl::serialize_allow_methods(method_set allowed) const {
     // TASK-048 review cleanup (findings 3 & 4): delegate to the shared free
     // function format_allow_header in detail/method_utils.hpp.  The member

src/detail/webserver_register.cpp

@@ -142,18 +142,17 @@ void webserver::register_impl_(const std::string& resource,
         // shared_ptr copies are cheaper than the regex scan they help avoid.
         impl_->registered_resources_regex.insert({idx, res});
     }
-    // Release the write lock before invalidating the cache.
-    // invalidate_route_cache() acquires route_cache_mutex_ independently;
-    // holding registered_resources_mutex across that call would invert the
-    // lock order documented in webserver_impl.hpp (cache mutex is always
-    // acquired AFTER table mutex, never while table mutex is held).
+    // Release the registration mutex before clearing the LRU cache.
+    // route_lru_cache.clear() takes the cache's internal mutex; the
+    // lock order documented in webserver_impl.hpp acquires the table
+    // mutex BEFORE the cache mutex and never both at once, so the
+    // registration mutex (which gates the registration-side maps,
+    // distinct from the v2 table mutex) is also released first as a
+    // matter of discipline.
     registered_resources_lock.unlock();
-    // Unlocking before invalidate_route_cache() is intentional: it preserves
-    // lock-order discipline (registered_resources_mutex released before
-    // route_cache_mutex_ is acquired inside invalidate_route_cache).
-    // A reader can transiently see the new entry without a warm cache, causing
-    // one extra regex scan on the first hit. This is a harmless read-stale
-    // effect — the resource is already visible to readers under the shared lock.
+    // A reader can transiently see the new entry without a warm cache,
+    // causing one extra tier walk on the first hit — harmless read-stale
+    // effect: the resource is already visible under the shared lock.
 
     impl_->register_v2_route(idx, std::move(res), family);
     impl_->invalidate_route_cache();
@@ -236,11 +235,9 @@ void webserver::unregister_impl_(const string& resource, bool family) {
 
     // TASK-027: mirror the erasure into the v2 3-tier table.
     // Lock ordering: registered_resources_mutex (released above) ->
-    // route_table_mutex_ -> route_cache_mutex_ (inside invalidate_route_cache).
-    // Do not acquire route_cache_mutex_ without holding route_table_mutex_ or
-    // registered_resources_mutex first.
-    // This matches the pattern used in register_impl_ / on_methods_:
-    // table lock released before cache is cleared.
+    // route_table_mutex_ -> route_lru_cache's internal mutex
+    // (inside invalidate_route_cache). Table lock released before the
+    // LRU cache is cleared, matching register_impl_ / on_methods_.
     {
         std::unique_lock table_lock(impl_->route_table_mutex_);
         const std::string& key = he.get_url_complete();

src/detail/webserver_request.cpp

@@ -350,12 +350,7 @@ 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;
-    // 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);
+    bool found = 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/detail/webserver_routes.cpp

@@ -334,10 +334,11 @@ void webserver::on_methods_(method_set methods,
     std::shared_ptr<detail::lambda_resource> shim;
     {
         // Scoped block: registered_resources_mutex is released at the
-        // closing brace, before upsert_v2_table_entry (which takes its own
-        // route_table_mutex_) and before invalidate_route_cache (which takes
-        // route_cache_mutex_). This lock-ordering — v1 mutex released before
-        // v2/cache mutexes are acquired — prevents deadlock.
+        // closing brace, before upsert_v2_table_entry (which takes its
+        // own route_table_mutex_) and before invalidate_route_cache
+        // (which takes the route_lru_cache internal mutex). This
+        // lock-ordering — registration mutex released before
+        // table/cache mutexes are acquired — prevents deadlock.
         std::unique_lock registered_resources_lock(impl_->registered_resources_mutex);
         shim = impl_->prepare_or_create_lambda_shim(idx, methods, is_new_entry);
         impl_->commit_handlers_to_shim(*shim, methods, std::move(handler));

src/httpserver/detail/route_cache.hpp

@@ -26,11 +26,12 @@
 // the key so a path served by both on_get and on_post warms two distinct
 // cache entries.
 //
-// Concurrency: the cache uses its own plain std::mutex (route_cache_mutex_
-// in webserver_impl) — *not* a shared_mutex — because every cache touch,
+// Concurrency: the cache uses its own plain std::mutex (an internal
+// member of route_cache itself, owned by `route_lru_cache` on
+// webserver_impl) — *not* a shared_mutex — because every cache touch,
 // including the LRU promotion on a hit, is a write (std::list::splice).
 // Lock-order discipline: route_table_mutex_ is always acquired before
-// route_cache_mutex_ when both are held.
+// the cache's internal mutex when both are held.
 //
 // Internal header — only reachable when compiling libhttpserver.
 #if !defined(HTTPSERVER_COMPILATION)