feat(TASK-025): GREEN seven on_* lambda registration entry points

Adds the public on_get / on_post / on_put / on_delete / on_patch /
on_options / on_head member functions on webserver, each accepting a
std::function<http_response(const http_request&)>. All seven forward
to a private webserver::on_method_ helper that:

- Builds (or merges into) a hidden detail::lambda_resource shim at the
  given path. The shim is a final subclass of http_resource holding
  one callable slot per http_method enumerator. It starts with every
  method disallowed (disallow_all()), so 405 dispatch falls through
  the existing finalize_answer mask path with no edit to the dispatch
  glue; on_* enables the matching bit per slot via set_allowing.
- Throws std::invalid_argument on conflict (slot already populated for
  the requested method, class-resource already registered at the path)
  and on bad input (empty handler, single_resource path violation).
- Inserts into the same three storage maps register_impl_ uses, so
  exact and parameterized lambda routes both land in the right tier
  (str fast-path map for exact non-parameterized; regex map for
  parameterized).

Adds detail::route_entry (architecture spec §4.7) holding method_set +
std::variant<lambda_handler, shared_ptr<http_resource>> + bool
is_prefix; pinned at compile time via static_assert in the test TU.
TASK-027 will plumb route_entry into a real 3-tier route table; until
then the lambda_resource shim is the dispatch carrier.

Both new headers live in src/httpserver/detail/ and are gated on
HTTPSERVER_COMPILATION; added to noinst_HEADERS so they're tarred but
never installed under $prefix/include.

35 tests pass (was 34); webserver_on_methods's eight runtime cases
plus its compile-time signature contract covers PRD §3.4 hello-world,
per-method 405 + Allow header, multi-method composition, all seven
overloads dispatch their method, duplicate (method, path) throws,
merge-then-conflict still throws, parameterized path binds {id}, and
class-resource registration on a lambda-owned path throws.

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

Author: etr

src/Makefile.am

@@ -23,7 +23,7 @@ libhttpserver_la_SOURCES = string_utilities.cpp webserver.cpp http_utils.cpp fil
 # noinst_HEADERS: shipped in the tarball but NEVER installed under $prefix/include.
 # Detail headers (httpserver/detail/*.hpp) live here so they cannot leak to
 # downstream consumers — the public surface comes in through <httpserver.hpp>.
-noinst_HEADERS = httpserver/string_utilities.hpp httpserver/detail/modded_request.hpp httpserver/detail/http_endpoint.hpp httpserver/detail/body.hpp httpserver/detail/webserver_impl.hpp httpserver/detail/http_request_impl.hpp gettext.h
+noinst_HEADERS = httpserver/string_utilities.hpp httpserver/detail/modded_request.hpp httpserver/detail/http_endpoint.hpp httpserver/detail/body.hpp httpserver/detail/webserver_impl.hpp httpserver/detail/http_request_impl.hpp httpserver/detail/route_entry.hpp httpserver/detail/lambda_resource.hpp gettext.h
 nobase_include_HEADERS = httpserver.hpp httpserver/body_kind.hpp httpserver/constants.hpp httpserver/create_webserver.hpp httpserver/create_test_request.hpp httpserver/webserver.hpp httpserver/http_utils.hpp httpserver/file_info.hpp httpserver/http_request.hpp httpserver/http_response.hpp httpserver/http_resource.hpp httpserver/feature_unavailable.hpp httpserver/iovec_entry.hpp httpserver/http_arg_value.hpp httpserver/http_method.hpp
 
 if HAVE_WEBSOCKET

src/httpserver/detail/lambda_resource.hpp

@@ -0,0 +1,139 @@
+/*
+     This file is part of libhttpserver
+     Copyright (C) 2011-2026 Sebastiano Merlino
+
+     This library is free software; you can redistribute it and/or
+     modify it under the terms of the GNU Lesser General Public
+     License as published by the Free Software Foundation; either
+     version 2.1 of the License, or (at your option) any later version.
+
+     This library is distributed in the hope that it will be useful,
+     but WITHOUT ANY WARRANTY; without even the implied warranty of
+     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+     Lesser General Public License for more details.
+
+     You should have received a copy of the GNU Lesser General Public
+     License along with this library; if not, write to the Free Software
+     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301
+     USA
+*/
+
+// TASK-025: dispatch shim used by webserver::on_method_ 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.
+//
+// `final` is intentional: the conflict check in webserver::on_method_
+// 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.
+//
+// Internal header — only reachable when compiling libhttpserver. NOT
+// included from the public umbrella <httpserver.hpp>.
+#if !defined(HTTPSERVER_COMPILATION)
+#error "lambda_resource.hpp is internal; only reachable when compiling libhttpserver."
+#endif
+
+#ifndef SRC_HTTPSERVER_DETAIL_LAMBDA_RESOURCE_HPP_
+#define SRC_HTTPSERVER_DETAIL_LAMBDA_RESOURCE_HPP_
+
+#include <array>
+#include <cstddef>
+#include <cstdint>
+#include <memory>
+#include <utility>
+
+#include "httpserver/http_method.hpp"
+#include "httpserver/http_resource.hpp"
+#include "httpserver/detail/route_entry.hpp"
+
+namespace httpserver {
+class http_request;
+class http_response;
+}  // namespace httpserver
+
+namespace httpserver {
+namespace detail {
+
+// 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.
+class lambda_resource final : public ::httpserver::http_resource {
+ public:
+    lambda_resource() {
+        // Lambda routes are opt-in per method (the default
+        // http_resource constructor enables every method via
+        // set_all()). on_* sets the matching bit when populating a slot.
+        disallow_all();
+    }
+
+    // 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).
+    void set_slot(http_method method, lambda_handler h) {
+        slots_[static_cast<std::size_t>(method)] = std::move(h);
+        set_allowing(method, true);
+    }
+
+    bool has_slot(http_method method) const noexcept {
+        return is_allowed(method);
+    }
+
+    std::shared_ptr<::httpserver::http_response>
+    render_get(const ::httpserver::http_request& r) override {
+        return invoke_(http_method::get, r);
+    }
+    std::shared_ptr<::httpserver::http_response>
+    render_post(const ::httpserver::http_request& r) override {
+        return invoke_(http_method::post, r);
+    }
+    std::shared_ptr<::httpserver::http_response>
+    render_put(const ::httpserver::http_request& r) override {
+        return invoke_(http_method::put, r);
+    }
+    std::shared_ptr<::httpserver::http_response>
+    render_delete(const ::httpserver::http_request& r) override {
+        return invoke_(http_method::del, r);
+    }
+    std::shared_ptr<::httpserver::http_response>
+    render_patch(const ::httpserver::http_request& r) override {
+        return invoke_(http_method::patch, r);
+    }
+    std::shared_ptr<::httpserver::http_response>
+    render_options(const ::httpserver::http_request& r) override {
+        return invoke_(http_method::options, r);
+    }
+    std::shared_ptr<::httpserver::http_response>
+    render_head(const ::httpserver::http_request& r) override {
+        return invoke_(http_method::head, r);
+    }
+
+ private:
+    std::shared_ptr<::httpserver::http_response>
+    invoke_(http_method m, const ::httpserver::http_request& r) {
+        auto& slot = slots_[static_cast<std::size_t>(m)];
+        if (!slot) {
+            // Reachable only if dispatch arrives for a method whose
+            // bit was set but whose slot was somehow cleared. The
+            // existing finalize_answer 405 path normally fires before
+            // we get here.
+            return ::httpserver::detail::empty_render(r);
+        }
+        return std::make_shared<::httpserver::http_response>(slot(r));
+    }
+
+    std::array<lambda_handler,
+               static_cast<std::size_t>(http_method::count_)> slots_{};
+};
+
+}  // namespace detail
+}  // namespace httpserver
+
+#endif  // SRC_HTTPSERVER_DETAIL_LAMBDA_RESOURCE_HPP_

src/httpserver/detail/route_entry.hpp

@@ -0,0 +1,82 @@
+/*
+     This file is part of libhttpserver
+     Copyright (C) 2011-2026 Sebastiano Merlino
+
+     This library is free software; you can redistribute it and/or
+     modify it under the terms of the GNU Lesser General Public
+     License as published by the Free Software Foundation; either
+     version 2.1 of the License, or (at your option) any later version.
+
+     This library is distributed in the hope that it will be useful,
+     but WITHOUT ANY WARRANTY; without even the implied warranty of
+     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+     Lesser General Public License for more details.
+
+     You should have received a copy of the GNU Lesser General Public
+     License along with this library; if not, write to the Free Software
+     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301
+     USA
+*/
+
+// TASK-025: route table value type as pinned by architecture spec §4.7.
+//
+// `route_entry` carries the method-set the entry covers, the actual
+// handler (either a stateless lambda or a shared_ptr to a class-derived
+// http_resource), and a `is_prefix` flag that lets the route table
+// distinguish exact-match registrations (register_path / on_*) from
+// prefix-match registrations (register_prefix). TASK-027 will plug this
+// type into the real 3-tier route table; TASK-025 only ships the type
+// and the on_* entry points that build it.
+//
+// The header is internal — only reachable when compiling libhttpserver
+// itself (HTTPSERVER_COMPILATION is supplied via src/Makefile.am
+// AM_CPPFLAGS, and via test/Makefile.am for the test TUs that need to
+// pin the variant shape with static_assert). It must NOT be included
+// from the public umbrella <httpserver.hpp>.
+#if !defined(HTTPSERVER_COMPILATION)
+#error "route_entry.hpp is internal; only reachable when compiling libhttpserver."
+#endif
+
+#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.
+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.
+struct route_entry {
+    method_set methods{};
+    std::variant<lambda_handler,
+                 std::shared_ptr<::httpserver::http_resource>> handler;
+    bool is_prefix = false;
+};
+
+}  // namespace detail
+}  // namespace httpserver
+
+#endif  // SRC_HTTPSERVER_DETAIL_ROUTE_ENTRY_HPP_

src/httpserver/webserver.hpp

@@ -29,13 +29,15 @@
 #include <stdint.h>
 #include <stdlib.h>
 
+#include <functional>
 #include <memory>
 #include <string>
 #include <type_traits>
 #include <utility>
 #include <vector>
 
 #include "httpserver/constants.hpp"
+#include "httpserver/http_method.hpp"
 #include "httpserver/http_utils.hpp"
 #include "httpserver/create_webserver.hpp"
 
@@ -186,6 +188,45 @@ class webserver {
      void register_resource(const std::string& path,
                             std::shared_ptr<http_resource> res);
 
+     /**
+      * Register a lambda handler for HTTP GET on @p path.
+      *
+      * The seven on_* entry points (on_get, on_post, on_put, on_delete,
+      * on_patch, on_options, on_head) let stateless endpoints be
+      * registered without subclassing http_resource. Each accepts a
+      * std::function<http_response(const http_request&)>.
+      *
+      * Multiple on_* calls on the SAME path COMPOSE: each call adds the
+      * matching method bit to a single route entry. A second on_get on
+      * the same path -- or on_get after another on_* already covers GET
+      * on this path -- throws std::invalid_argument. Mixing class-based
+      * registration (register_path / register_prefix) and lambda
+      * registration on the same path also throws.
+      *
+      * @param path    URL path; may be parameterized as /foo/{id}.
+      * @param handler invoked per request; returns http_response by value.
+     **/
+     void on_get(const std::string& path,
+                 std::function<http_response(const http_request&)> handler);
+     /// @copydoc on_get(const std::string&, std::function<http_response(const http_request&)>)
+     void on_post(const std::string& path,
+                  std::function<http_response(const http_request&)> handler);
+     /// @copydoc on_get(const std::string&, std::function<http_response(const http_request&)>)
+     void on_put(const std::string& path,
+                 std::function<http_response(const http_request&)> handler);
+     /// @copydoc on_get(const std::string&, std::function<http_response(const http_request&)>)
+     void on_delete(const std::string& path,
+                    std::function<http_response(const http_request&)> handler);
+     /// @copydoc on_get(const std::string&, std::function<http_response(const http_request&)>)
+     void on_patch(const std::string& path,
+                   std::function<http_response(const http_request&)> handler);
+     /// @copydoc on_get(const std::string&, std::function<http_response(const http_request&)>)
+     void on_options(const std::string& path,
+                     std::function<http_response(const http_request&)> handler);
+     /// @copydoc on_get(const std::string&, std::function<http_response(const http_request&)>)
+     void on_head(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.
@@ -392,6 +433,19 @@ 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);
+
      // PIMPL: backend-coupled state (MHD daemon, pthread mutexes, route
      // table, ban set, route cache, websocket registry, GnuTLS SNI cache,
      // and the dispatch helpers / MHD trampolines that operate on those)