TASK-071 (B): collapse route_entry::handler variant; remove dead lambda_handler arm

route_entry::handler was originally
`std::variant<lambda_handler, shared_ptr<http_resource>>`. The
lambda_handler arm has been dead code since TASK-053: every writer
of route_entry (on_*/route entry points, register_path, register_prefix)
funnels lambdas through a lambda_resource shim and stores the shim as
shared_ptr<http_resource>. No call site stored a lambda directly, and
no v2 task introduced a writer that would. Both readers
(resolve_resource_for_request, prepare_or_create_lambda_shim) already
treated the lambda arm as unreachable.

Collapse handler to a bare shared_ptr<http_resource>:
- route_entry.hpp drops std::variant + the lambda_handler typedef;
- the lambda_handler typedef relocates to detail/lambda_resource.hpp
  where its remaining uses live (the per-method slot signature);
- the dispatch site (webserver_dispatch.cpp::resolve_resource_for_request)
  reads result.entry.handler directly with a defensive null check;
- prepare_or_create_lambda_shim and update_existing_v2_entry shed the
  std::get_if indirection;
- the routing_regression unit pin updates likewise.

Pin the new shape with a static_assert in webserver_on_methods_test:
TASK-071 history is captured in the assertion message so a future
reintroduction of variant storage trips an early-warning canary at
compile time. The webserver::route(...) and on_*(...) public
signatures take std::function (not std::variant) and were unaffected
— no Doxygen update needed on the public surface.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: etr

src/detail/webserver_dispatch.cpp

@@ -255,9 +255,10 @@ webserver_impl::lookup_v2(http_method method, const std::string& path) {
 // 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>
+//       route_entry whose handler is a 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).
+//       before storing — see prepare_or_create_lambda_shim in
+//       webserver_routes.cpp).
 //
 // TASK-067: single_resource mode used to short-circuit to a direct read
 // of the v1 registered_resources map. With the v1 maps deleted, single
@@ -267,6 +268,13 @@ webserver_impl::lookup_v2(http_method method, const std::string& path) {
 // is no separate fast path because the v2 walk for a single registered
 // prefix is one shared_lock + one empty-map probe + one trivial radix
 // descent: cheap enough that the extra branch was net-negative.
+//
+// TASK-071: route_entry::handler was previously a
+// `std::variant<lambda_handler, shared_ptr<http_resource>>`. The
+// lambda_handler arm was dead code (every writer wrapped lambdas in
+// lambda_resource) and has been removed. The dispatch path reads the
+// shared_ptr directly with a defensive null check that degrades to a
+// 404 miss.
 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
@@ -280,20 +288,15 @@ bool webserver_impl::resolve_resource_for_request(detail::modded_request* mr,
     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.
+    // Read the resource pointer directly. Every writer of route_entry
+    // populates a non-null shared_ptr (a class-derived http_resource
+    // for register_path / register_prefix, or a lambda_resource shim
+    // for on_* / route); a null pointer here would indicate a future
+    // bug, so degrade to a not-found miss defensively.
+    if (result.entry.handler == nullptr) {
         return false;
     }
-    hrm = *hp;
+    hrm = result.entry.handler;
 
     // Replay captured URL parameters into the request. This is the v2
     // equivalent of the v1-era apply_extracted_params (removed in

src/detail/webserver_routes.cpp

@@ -188,16 +188,12 @@ webserver_impl::prepare_or_create_lambda_shim(const detail::http_endpoint& idx,
         fresh_out = true;
         return std::make_shared<detail::lambda_resource>();
     }
-    // Existing entry. The v2 storage uses a variant whose handler arm is
-    // always shared_ptr<http_resource> in the current code (the
-    // lambda_handler arm is unused; see resolve_resource_for_request).
-    // Pull the shared_ptr and dynamic_pointer_cast to lambda_resource:
-    // if the cast misses, a class-based register_path/register_prefix
-    // owns this path and we must throw.
-    const auto* sp = std::get_if<std::shared_ptr<http_resource>>(&existing->handler);
-    auto shim = (sp != nullptr)
-        ? std::dynamic_pointer_cast<detail::lambda_resource>(*sp)
-        : nullptr;
+    // Existing entry. route_entry::handler is a shared_ptr<http_resource>
+    // (TASK-071 collapsed the prior variant). Dynamic-cast to
+    // lambda_resource: if the cast misses, a class-based
+    // register_path/register_prefix owns this path and we must throw.
+    auto shim = std::dynamic_pointer_cast<detail::lambda_resource>(
+        existing->handler);
     if (!shim) {
         throw std::invalid_argument(
             "A non-lambda http_resource is already registered at "
@@ -355,8 +351,7 @@ void webserver_impl::update_existing_v2_entry(const std::string& key,
         return;
     }
     for (auto& rr : regex_routes_) {
-        auto* sp = std::get_if<std::shared_ptr<http_resource>>(&rr.entry.handler);
-        if (sp && *sp == shim) {
+        if (rr.entry.handler == shim) {
             merge_into(rr.entry);
             return;
         }

src/httpserver/detail/lambda_resource.hpp

@@ -48,6 +48,7 @@
 #include <cassert>
 #include <cstddef>
 #include <cstdint>
+#include <functional>
 #include <utility>
 
 #include "httpserver/http_method.hpp"
@@ -62,12 +63,26 @@ class http_request;
 namespace httpserver {
 namespace detail {
 
+// The per-method slot signature for lambda_resource. Returns
+// http_response by value (DR-004) and takes the request by const
+// reference. std::function is the chosen storage so users can pass any
+// callable (lambda, function pointer, std::bind result, member-function
+// adaptor) without leaking the concrete callable type into the slot
+// array.
+//
+// TASK-071 history: this typedef formerly lived in route_entry.hpp as
+// the lambda arm of `std::variant<lambda_handler, shared_ptr<...>>`. The
+// variant arm was dead code (no writer stored a lambda directly — every
+// on_*/route path funnels through lambda_resource), so it was removed.
+// The typedef relocates here, where its remaining uses are.
+using lambda_handler = std::function<::httpserver::http_response(const ::httpserver::http_request&)>;  // NOLINT(whitespace/line_length)
+
 // Tiny adapter that wraps a single lambda_handler as an http_resource
 // virtual override. We keep one slot per method enum and dispatch in
 // each render_* override. Each slot holds a
 //   std::function<http_response(const http_request&)>
-// (see route_entry.hpp::lambda_handler). Slots are installed via
-// set_slot() and invoked by the render_* overrides below.
+// (the `lambda_handler` typedef defined above). Slots are installed
+// via set_slot() and invoked by the render_* overrides below.
 class lambda_resource final : public ::httpserver::http_resource {
  public:
     lambda_resource() {

src/httpserver/detail/route_entry.hpp

@@ -40,44 +40,38 @@
 #ifndef SRC_HTTPSERVER_DETAIL_ROUTE_ENTRY_HPP_
 #define SRC_HTTPSERVER_DETAIL_ROUTE_ENTRY_HPP_
 
-#include <functional>
 #include <memory>
-#include <variant>
 
 #include "httpserver/http_method.hpp"
 
 namespace httpserver {
-class http_request;
-class http_response;
 class http_resource;
 }  // namespace httpserver
 
 namespace httpserver {
 namespace detail {
 
-// The lambda arm of the route_entry payload variant. Returns
-// http_response by value (DR-004) and takes the request by const
-// reference. std::function is the chosen storage so users can pass any
-// callable (lambda, function pointer, std::bind result, member-function
-// adaptor) without leaking the concrete callable type into the route
-// table.
-//
-// PRD-RSP-REQ-007 dispatch note: when the lookup_v2 path invokes this
-// variant arm, the returned http_response prvalue is moved directly into
-// modded_request::response via emplace(), matching the pointer-to-member
-// dispatch path used by the v1 finalize_answer (see DR-004 §5.3).
-using lambda_handler = std::function<::httpserver::http_response(const ::httpserver::http_request&)>;  // NOLINT(whitespace/line_length)
-
 // route_entry: §4.7-shape value type stored per route in the route
 // table. The `methods` mask holds every HTTP method this entry serves;
-// the variant payload holds either a lambda (for on_* registrations)
-// or a shared_ptr<http_resource> (for register_path / register_prefix
-// registrations). `is_prefix` distinguishes prefix matching from exact
-// matching at lookup time.
+// the `handler` payload is a shared_ptr to the http_resource serving
+// the route — either a class-derived resource (for register_path /
+// register_prefix registrations) or a lambda_resource shim
+// (for on_* / route registrations, which wrap the user lambda in a
+// lambda_resource owning one slot per HTTP method). `is_prefix`
+// distinguishes prefix matching from exact matching at lookup time.
+//
+// TASK-071 history: this field was originally a
+// `std::variant<lambda_handler, shared_ptr<http_resource>>`. The
+// lambda_handler arm was never populated — every writer wrapped user
+// lambdas in lambda_resource (see webserver_routes.cpp's
+// prepare_or_create_lambda_shim and the lambda_resource header doc-
+// comment for why the shim composes cleanly with register_path's
+// resource storage). The variant arm has been removed; the
+// lambda_handler typedef now lives in detail/lambda_resource.hpp
+// where its remaining uses are (the per-method slot signature).
 struct route_entry {
     method_set methods{};
-    std::variant<lambda_handler,
-                 std::shared_ptr<::httpserver::http_resource>> handler;
+    std::shared_ptr<::httpserver::http_resource> handler;
     bool is_prefix = false;
 };
 

test/Makefile.am

@@ -252,8 +252,8 @@ webserver_register_path_prefix_SOURCES = unit/webserver_register_path_prefix_tes
 # webserver_on_methods: TASK-025. Compile-time signature contract for
 # the seven on_* lambda registration overloads (on_get / on_post / on_put
 # / on_delete / on_patch / on_options / on_head) plus static_asserts on
-# the §4.7 detail::route_entry shape (method_set + variant<lambda_handler,
-# shared_ptr<http_resource>> + bool is_prefix). Runtime tests over real
+# the §4.7 detail::route_entry shape (method_set + shared_ptr<http_resource>
+# + bool is_prefix; TASK-071 collapsed the original variant arm). Runtime tests over real
 # curl round-trips: PRD §3.4 hello-world; per-method 405 + Allow header;
 # composition (on_get + on_post on the same path serve both); all seven
 # methods dispatch correctly; duplicate (method, path) registration

test/unit/route_table_test.cpp

@@ -39,11 +39,13 @@ namespace ht = httpserver;
 namespace htd = httpserver::detail;
 
 // Sentinel makers to avoid crafting a real http_resource just to populate
-// the variant; we leave the lambda_handler default-constructed (empty
-// std::function) and ride on the sentinel id field in the test below.
-// The variant arm itself is irrelevant — the radix_tree / route_cache
-// tests only care about the entry payload identity through pointer
-// equality and the methods/is_prefix fields.
+// the handler field; we leave it null (a default-constructed shared_ptr)
+// and ride on the sentinel id field in the test below. The handler field
+// is irrelevant — the radix_tree / route_cache tests only care about the
+// entry payload identity through pointer equality and the methods/is_prefix
+// fields. (TASK-071: route_entry::handler was originally a
+// std::variant<lambda_handler, shared_ptr<http_resource>>; the variant arm
+// was collapsed to a bare shared_ptr<http_resource>.)
 struct test_entry {
     int sentinel = 0;
     ht::method_set methods{};
@@ -57,7 +59,7 @@ static htd::route_entry make_entry(
     htd::route_entry e;
     e.methods = ms;
     e.is_prefix = is_prefix;
-    // Leave variant alternative #0 (lambda_handler) default-constructed.
+    // Leave handler default-constructed (null shared_ptr).
     return e;
 }
 

test/unit/routing_regression_test.cpp

@@ -565,10 +565,10 @@ LT_BEGIN_AUTO_TEST(routing_regression_suite,
     // literal "foo" (exact child), so the tree descends there first and
     // never tries the wildcard root branch required by the second
     // pattern. Structural precedence → first-registered wins here.
-    auto* hp = std::get_if<std::shared_ptr<ht::http_resource>>(
-        &r.entry.handler);
-    LT_CHECK(hp != nullptr);
-    LT_CHECK(*hp == first);
+    // TASK-071: route_entry::handler is now a bare shared_ptr<http_resource>
+    // (the variant arm was collapsed); read it directly.
+    LT_CHECK(r.entry.handler != nullptr);
+    LT_CHECK(r.entry.handler == first);
 LT_END_AUTO_TEST(overlapping_two_regex_routes_deterministic_first_wins)
 
 LT_BEGIN_AUTO_TEST(routing_regression_suite,
@@ -588,10 +588,8 @@ LT_BEGIN_AUTO_TEST(routing_regression_suite,
                                    std::string("/foo/bar/"));
     LT_CHECK(r.found);
     LT_CHECK(r.tier == ht::detail::webserver_impl::tier_hit::exact);
-    auto* hp = std::get_if<std::shared_ptr<ht::http_resource>>(
-        &r.entry.handler);
-    LT_CHECK(hp != nullptr);
-    LT_CHECK(*hp == exact);
+    LT_CHECK(r.entry.handler != nullptr);
+    LT_CHECK(r.entry.handler == exact);
 LT_END_AUTO_TEST(later_exact_registration_shadows_earlier_regex)
 
 // ---------------------------------------------------------------------
@@ -615,10 +613,8 @@ LT_BEGIN_AUTO_TEST(routing_regression_suite,
     auto deep = impl_of(ws).lookup_v2(
         ht::http_method::get, std::string("/anything/at/all"));
     LT_CHECK(deep.found);
-    auto* hp = std::get_if<std::shared_ptr<ht::http_resource>>(
-        &deep.entry.handler);
-    LT_CHECK(hp != nullptr);
-    LT_CHECK(*hp == only);
+    LT_CHECK(deep.entry.handler != nullptr);
+    LT_CHECK(deep.entry.handler == only);
 LT_END_AUTO_TEST(single_resource_mode_serves_any_subpath)
 
 // ---------------------------------------------------------------------

test/unit/webserver_on_methods_test.cpp

@@ -172,19 +172,23 @@ static_assert(std::is_same_v<
                   void>,
               "on_head must exist and return void");
 
-// (2) The route_entry detail type pins the §4.7 shape: method_set + a
-//     two-arm variant + a bool is_prefix flag.
+// (2) The route_entry detail type pins the §4.7 shape: method_set +
+//     a single-arm shared_ptr<http_resource> handler + a bool is_prefix
+//     flag. TASK-071 collapsed the variant: the lambda_handler arm was
+//     dead code (every writer wrapped user lambdas in a lambda_resource
+//     shim and stored the shim as shared_ptr<http_resource>; no path
+//     stored a lambda directly).
 static_assert(std::is_same_v<
                   decltype(httpserver::detail::route_entry::methods),
                   method_set>,
               "route_entry::methods must be method_set");
 
 static_assert(std::is_same_v<
                   decltype(httpserver::detail::route_entry::handler),
-                  std::variant<httpserver::detail::lambda_handler,
-                               std::shared_ptr<http_resource>>>,
-              "route_entry::handler must be variant<lambda_handler, "
-              "shared_ptr<http_resource>>");
+                  std::shared_ptr<http_resource>>,
+              "route_entry::handler must be shared_ptr<http_resource> "
+              "(TASK-071: lambda_handler variant arm removed; "
+              "on_*/route shim through lambda_resource).");
 
 static_assert(std::is_same_v<
                   decltype(httpserver::detail::route_entry::is_prefix),