Merge TASK-026: Generic webserver::route(method, path, handler)

Author: etr

specs/tasks/M4-handlers/TASK-026.md

@@ -8,10 +8,10 @@
 Provide the table-driven escape hatch for registering handlers when the HTTP method is a runtime value.
 
 **Action Items:**
-- [ ] Add `webserver::route(http_method m, const std::string& path, std::function<http_response(const http_request&)> handler);`.
-- [ ] Implementation dispatches to the same internal registration path used by `on_*`.
-- [ ] Document the call-site convention: `route()` is the escape hatch; `on_*` is preferred when the method is known statically.
-- [ ] Add `webserver::route(method_set methods, const std::string& path, handler)` if a single handler should serve multiple methods (e.g., GET and HEAD).
+- [x] Add `webserver::route(http_method m, const std::string& path, std::function<http_response(const http_request&)> handler);`.
+- [x] Implementation dispatches to the same internal registration path used by `on_*`.
+- [x] Document the call-site convention: `route()` is the escape hatch; `on_*` is preferred when the method is known statically.
+- [x] Add `webserver::route(method_set methods, const std::string& path, handler)` if a single handler should serve multiple methods (e.g., GET and HEAD).
 
 **Dependencies:**
 - Blocked by: TASK-005, TASK-025
@@ -26,4 +26,4 @@ Provide the table-driven escape hatch for registering handlers when the HTTP met
 **Related Requirements:** PRD-HDL-REQ-006
 **Related Decisions:** §4.7, OQ-003 resolution
 
-**Status:** Not Started
+**Status:** Done

specs/tasks/_index.md

@@ -108,7 +108,7 @@ Nominally: **13 sequential tasks**, each S–XL. Most other tasks parallelize of
 | TASK-023 | Smart-pointer `register_resource` overloads | M4 | Done | TASK-014 |
 | TASK-024 | `register_path` and `register_prefix` (replace `bool family`) | M4 | Done | TASK-023 |
 | TASK-025 | Lambda handler entry points `on_*` | M4 | Done | TASK-005, TASK-009, TASK-014 |
-| TASK-026 | Generic `webserver::route(method, path, handler)` | M4 | Not Started | TASK-005, TASK-025 |
+| TASK-026 | Generic `webserver::route(method, path, handler)` | M4 | Done | TASK-005, TASK-025 |
 | TASK-027 | 3-tier route table with LRU cache | M5 | Not Started | TASK-005, TASK-014, TASK-021, TASK-024, TASK-025, TASK-026 |
 | TASK-028 | Routing-semantics regression gate | M5 | Not Started | TASK-027 |
 | TASK-029 | Naming consistency — `stop_and_wait`, `block_ip`/`unblock_ip` | M5 | Not Started | TASK-014 |

specs/unworked_review_issues/2026-05-10_195020_task-026.md

@@ -18,19 +18,19 @@
      USA
 */
 
-// TASK-025: dispatch shim used by webserver::on_method_ to slot lambda
-// handlers into the existing v1-shaped route table.
+// TASK-025/TASK-026: dispatch shim used by webserver::on_methods_ to
+// slot lambda handlers into the existing v1-shaped route table.
 //
 // The shim is a sub-class of http_resource that holds one slot per
 // http_method enumerator. Its render_* virtuals look up the slot for
 // the dispatched method and invoke it. The shim starts with EVERY
-// method disallowed (`disallow_all()`); each on_* call enables exactly
-// the matching bit via `set_allowing(method, true)`. The existing
-// finalize_answer dispatch glue therefore returns 405 for unregistered
-// methods automatically — no edit to webserver.cpp's dispatch path is
-// needed.
+// method disallowed (`disallow_all()`); each on_*/route call enables
+// exactly the matching bits via `set_allowing(method, true)`. The
+// existing finalize_answer dispatch glue therefore returns 405 for
+// unregistered methods automatically — no edit to webserver.cpp's
+// dispatch path is needed.
 //
-// `final` is intentional: the conflict check in webserver::on_method_
+// `final` is intentional: the conflict check in webserver::on_methods_
 // uses dynamic_pointer_cast<lambda_resource>(...) to distinguish
 // lambda-owned routes from class-owned routes. A subclass would hide
 // in that test and break the invariant.
@@ -77,7 +77,7 @@ class lambda_resource final : public ::httpserver::http_resource {
 
     // Install (or replace) the slot for `method`. Caller must have
     // already verified that no slot is currently set for `method`
-    // (webserver::on_method_ enforces this and throws on conflict).
+    // (webserver::on_methods_ enforces this and throws on conflict).
     void set_slot(http_method method, lambda_handler h) {
         slots_[static_cast<std::size_t>(method)] = std::move(h);
         set_allowing(method, true);

src/httpserver/detail/lambda_resource.hpp

@@ -227,6 +227,59 @@ class webserver {
      void on_head(const std::string& path,
                   std::function<http_response(const http_request&)> handler);
 
+     /**
+      * Generic table-driven lambda registration.
+      *
+      * `on_get`, `on_post`, ... are the preferred call-site form when
+      * the HTTP method is known statically; `route()` is the escape
+      * hatch for cases where the method is a runtime value
+      * (config-driven route tables, programmatic registration loops).
+      *
+      * Both forms share the same internal registration path: a single
+      * `route(http_method, path, h)` is exactly equivalent to the
+      * matching `on_*(path, h)`, and `route(method_set, path, h)` is
+      * exactly equivalent to one `on_*` call per set bit, applied
+      * atomically -- if any one of the bits would conflict with an
+      * existing registration, no slot is mutated and the call throws.
+      *
+      * Throws std::invalid_argument if @p handler is empty, if @p m
+      * is `http_method::count_` (sentinel), if the path conflicts
+      * with single_resource mode, if a class-based resource is
+      * already registered at the path, or if a lambda is already
+      * registered for any of the requested methods on this path.
+      *
+      * @param m       HTTP method to register the handler under.
+      * @param path    URL path; may be parameterized as /foo/{id}.
+      * @param handler invoked per request; returns http_response by value.
+     **/
+     void route(http_method m,
+                const std::string& path,
+                std::function<http_response(const http_request&)> handler);
+
+     /**
+      * Multi-method form of route(): register the same handler for
+      * every method bit set in @p methods, atomically (all-or-nothing).
+      *
+      * Useful when one handler should serve more than one method
+      * (e.g., GET and HEAD on the same path). Equivalent to one
+      * `on_*` call per set bit, but if any one of those would conflict
+      * with an existing registration, no slot is mutated and the call
+      * throws std::invalid_argument.
+      *
+      * Throws std::invalid_argument if @p methods is empty, if
+      * @p handler is empty, if the path conflicts with single_resource
+      * mode, if a class-based resource is already registered at the
+      * path, or if a lambda is already registered for any of the
+      * requested methods on this path.
+      *
+      * @param methods bitmask of methods to register the handler for.
+      * @param path    URL path; may be parameterized as /foo/{id}.
+      * @param handler invoked per request; returns http_response by value.
+     **/
+     void route(method_set methods,
+                const std::string& path,
+                std::function<http_response(const http_request&)> handler);
+
      /**
       * Unregister an exact-match (register_path) registration.
       * No-op if no exact registration exists at @p path.
@@ -433,18 +486,23 @@ class webserver {
      // registration of the requested kind.
      void unregister_impl_(const std::string& path, bool family);
 
-     // TASK-025: shared lambda-registration helper. Builds-or-merges a
-     // hidden detail::lambda_resource shim at @p path, sets the @p method
-     // bit on it, and stores @p handler into that method's slot. All
-     // seven public on_* overloads forward to this single entry point so
-     // the merge-and-conflict logic lives in one place. Throws
-     // std::invalid_argument if @p handler is empty, if the path
-     // conflicts with single_resource mode, if a class-based resource
-     // is already registered at the path, or if a lambda is already
-     // registered for (method, path).
-     void on_method_(http_method method,
-                     const std::string& path,
-                     std::function<http_response(const http_request&)> handler);
+     // TASK-025/TASK-026: shared lambda-registration helper. Builds-or-
+     // merges a hidden detail::lambda_resource shim at @p path, sets every
+     // bit in @p methods on it, and stores @p handler into each of those
+     // method slots. All seven public on_* overloads and both public
+     // route() overloads forward to this single entry point so the
+     // merge-and-conflict logic lives in one place. Validation is
+     // atomic: if any requested method already has a slot on the path,
+     // no slot is mutated and the call throws -- callers therefore see
+     // either a fully-installed registration or no change at all.
+     // Throws std::invalid_argument if @p methods is empty, if @p
+     // handler is empty, if the path conflicts with single_resource
+     // mode, if a class-based resource is already registered at the
+     // path, or if a lambda is already registered for any requested
+     // (method, path).
+     void on_methods_(method_set methods,
+                      const std::string& path,
+                      std::function<http_response(const http_request&)> handler);
 
      // PIMPL: backend-coupled state (MHD daemon, pthread mutexes, route
      // table, ban set, route cache, websocket registry, GnuTLS SNI cache,

src/httpserver/webserver.hpp

@@ -306,40 +306,48 @@ void webserver::register_resource(const std::string& resource,
     register_path(resource, std::move(res));
 }
 
-// TASK-025: lambda registration plumbing.
+// TASK-025/TASK-026: lambda registration plumbing.
 //
-// All seven public on_* overloads forward to on_method_, which:
-//   1. Validates the handler and the path (single_resource constraints).
+// All seven public on_* overloads and both public route() overloads
+// forward to on_methods_, which:
+//   1. Validates the handler, the method set (non-empty, no count_
+//      sentinel bit), and the path (single_resource constraints).
 //   2. Looks up any existing entry at the path. If it's a class-based
 //      http_resource, throw -- lambda and class registrations cannot
-//      share a path. If it's an existing lambda_resource shim, merge by
-//      checking the per-method slot is empty (else throw) and writing
-//      the new handler into that slot.
+//      share a path. If it's an existing lambda_resource shim, check
+//      that EVERY requested method slot is empty before mutating any
+//      of them (atomic all-or-nothing); otherwise throw.
 //   3. If no entry exists, build a fresh lambda_resource shim and
 //      insert it into the same three storage maps used by
 //      register_impl_ (master ordered map; the str fast-path map iff
 //      exact non-parameterized; the regex map iff parameterized).
-//   4. Invalidate the LRU route cache.
+//   4. Write @p handler into each requested method slot.
+//   5. Invalidate the LRU route cache.
 //
 // The dispatch path in finalize_answer is not modified: it already
 // looks up via shared_ptr<http_resource>, calls is_allowed(method)
 // gating the 405 path, then dispatches via the per-method member-
 // function pointer set in answer_to_connection. The lambda_resource
 // shim's render_* overrides invoke the stored slot.
-void webserver::on_method_(http_method method,
-                           const std::string& path,
-                           std::function<http_response(const http_request&)> handler) {
+void webserver::on_methods_(method_set methods,
+                            const std::string& path,
+                            std::function<http_response(const http_request&)> handler) {
+    if (methods.bits == 0u) {
+        throw std::invalid_argument(
+            "route(method_set, ...) requires at least one method bit set");
+    }
     if (!handler) {
         throw std::invalid_argument(
-            "The handler function passed to on_* must be non-empty");
+            "The handler function passed to on_*/route must be non-empty");
     }
 
     // Same single-resource constraint as register_path: only "" or "/"
-    // is acceptable, and the matching mode must be exact (which on_* is).
+    // is acceptable, and the matching mode must be exact (which on_*/
+    // route are).
     if (single_resource && path != "" && path != "/") {
         throw std::invalid_argument(
-            "When using a single_resource server, on_* requires the "
-            "path to be '' or '/'");
+            "When using a single_resource server, on_*/route requires "
+            "the path to be '' or '/'");
     }
 
     detail::http_endpoint idx(path, /*family=*/false,
@@ -360,20 +368,38 @@ void webserver::on_method_(http_method method,
         if (!shim) {
             throw std::invalid_argument(
                 "A non-lambda http_resource is already registered at "
-                "this path; on_* cannot share a path with "
+                "this path; on_*/route cannot share a path with "
                 "register_path/register_prefix");
         }
-        if (shim->has_slot(method)) {
-            throw std::invalid_argument(
-                "A handler is already registered for this method on "
-                "this path");
+        // Atomicity pre-check: every requested slot must be empty
+        // BEFORE we mutate any of them. Iterates in enum order (get,
+        // head, post, ...) matching the `Allow:` header serialization.
+        for (std::uint8_t i = 0;
+             i < static_cast<std::uint8_t>(http_method::count_);
+             ++i) {
+            auto m = static_cast<http_method>(i);
+            if (!methods.contains(m)) continue;
+            if (shim->has_slot(m)) {
+                throw std::invalid_argument(
+                    "A handler is already registered for one of the "
+                    "requested methods on this path");
+            }
         }
     } else {
         shim = std::make_shared<detail::lambda_resource>();
         fresh = true;
     }
 
-    shim->set_slot(method, std::move(handler));
+    // Commit phase: install the handler into every requested slot.
+    // The shared std::function copies cheaply (type-erased callable),
+    // so each slot owns its own copy.
+    for (std::uint8_t i = 0;
+         i < static_cast<std::uint8_t>(http_method::count_);
+         ++i) {
+        auto m = static_cast<http_method>(i);
+        if (!methods.contains(m)) continue;
+        shim->set_slot(m, handler);
+    }
 
     if (fresh) {
         impl_->registered_resources.insert({idx, shim});
@@ -392,42 +418,64 @@ void webserver::on_method_(http_method method,
 
 // The seven named forwarders below are the only place that maps the
 // method name to its http_method enum constant. Each is a thin alias
-// for on_method_; all validation and insertion logic lives there.
+// for on_methods_; all validation and insertion logic lives there.
 // on_delete uses http_method::del because `delete` is a C++ keyword;
 // the wire token is "DELETE" (see http_method::to_string).
 void webserver::on_get(const std::string& path,
                        std::function<http_response(const http_request&)> handler) {
-    on_method_(http_method::get, path, std::move(handler));
+    on_methods_(method_set{}.set(http_method::get), path, std::move(handler));
 }
 
 void webserver::on_post(const std::string& path,
                         std::function<http_response(const http_request&)> handler) {
-    on_method_(http_method::post, path, std::move(handler));
+    on_methods_(method_set{}.set(http_method::post), path, std::move(handler));
 }
 
 void webserver::on_put(const std::string& path,
                        std::function<http_response(const http_request&)> handler) {
-    on_method_(http_method::put, path, std::move(handler));
+    on_methods_(method_set{}.set(http_method::put), path, std::move(handler));
 }
 
 void webserver::on_delete(const std::string& path,
                           std::function<http_response(const http_request&)> handler) {
-    on_method_(http_method::del, path, std::move(handler));
+    on_methods_(method_set{}.set(http_method::del), path, std::move(handler));
 }
 
 void webserver::on_patch(const std::string& path,
                          std::function<http_response(const http_request&)> handler) {
-    on_method_(http_method::patch, path, std::move(handler));
+    on_methods_(method_set{}.set(http_method::patch), path, std::move(handler));
 }
 
 void webserver::on_options(const std::string& path,
                            std::function<http_response(const http_request&)> handler) {
-    on_method_(http_method::options, path, std::move(handler));
+    on_methods_(method_set{}.set(http_method::options), path, std::move(handler));
 }
 
 void webserver::on_head(const std::string& path,
                         std::function<http_response(const http_request&)> handler) {
-    on_method_(http_method::head, path, std::move(handler));
+    on_methods_(method_set{}.set(http_method::head), path, std::move(handler));
+}
+
+// TASK-026: generic table-driven entry points. The single-method form
+// rejects http_method::count_ explicitly because the public route()
+// overload accepts a runtime value (and so the sentinel is reachable);
+// the on_* forwarders never pass count_, so the on_methods_ helper
+// itself does not guard against it.
+void webserver::route(http_method m,
+                      const std::string& path,
+                      std::function<http_response(const http_request&)> handler) {
+    if (m == http_method::count_) {
+        throw std::invalid_argument(
+            "http_method::count_ is a sentinel and may not be "
+            "registered as a route");
+    }
+    on_methods_(method_set{}.set(m), path, std::move(handler));
+}
+
+void webserver::route(method_set methods,
+                      const std::string& path,
+                      std::function<http_response(const http_request&)> handler) {
+    on_methods_(methods, path, std::move(handler));
 }
 
 #ifdef HAVE_WEBSOCKET