TASK-054: migrate auth_handler_ptr to optional<http_response>

Flips the canonical auth handler typedef from
  std::function<std::shared_ptr<http_response>(const http_request&)>
to
  std::function<std::optional<http_response>(const http_request&)>,
completing the DR-009 / PRD-RSP-REQ-007 value-typed response rollout
onto the last remaining heap-allocating slot on the public API.

One-build escape hatch:
- compat::auth_handler_v1_ptr keeps the v1 shared_ptr-returning std::function
  shape (with a [[deprecated]] attribute).
- compat::adapt_legacy_auth(legacy) wraps the v1 callable into the new
  optional shape (nullptr -> nullopt; non-null -> moved-from optional).
- A [[deprecated]] create_webserver::auth_handler(compat::auth_handler_v1_ptr)
  overload accepts the legacy shape and routes through adapt_legacy_auth.
Both deprecation sites cite TASK-054 and point at the new typedef.

Dispatch path: the before_handler auth-alias hook in webserver_aliases.cpp
now consumes std::optional<http_response> directly. Removes one heap
allocation per authenticated request (the shared_ptr control block);
small responses still ride the http_response SBO with zero further allocs.

Tests:
- test/unit/auth_handler_optional_signature_test.cpp NEW: static_assert
  the new typedef shape; end-to-end pin nullopt-allows + engaged-rejects
  via curl; hook-count invariant (+1 on before_handler).
- test/unit/auth_handler_legacy_shim_test.cpp NEW: pin the v1 typedef
  alias shape, the deprecated setter overload, hook-count invariant via
  the shim, and verbatim status/header forwarding through
  compat::adapt_legacy_auth (proves response state is moved, not lost).
  TU-scope #pragma GCC diagnostic ignored "-Wdeprecated-declarations".
- Migrated:
    test/unit/hooks_alias_count_test.cpp (auth lambdas -> optional shape)
    test/unit/webserver_register_path_prefix_test.cpp (reject_auth)
    test/unit/create_webserver_test.cpp (builder_auth_handler)
    test/integ/authentication.cpp (centralized_auth_handler)

Docs:
- README.md: setter blurb + worked example switched to optional shape.
- RELEASE_NOTES.md: added "auth handler" entry under "What changed
  semantically" + rename-pair row in the v1->v2 table.
- specs/architecture/04-components/create-webserver.md: documented the
  new signature, the compat alias, and the one-build deprecation window.
- src/httpserver/create_webserver.hpp: Doxygen on the setter rewritten;
  TODO at lines 92-99 removed.
- examples/centralized_authentication.cpp: drops <memory>/make_shared,
  returns std::optional<http_response> directly.

Verification:
- All TASK-054 new + migrated tests PASS (auth_handler_optional_signature,
  auth_handler_legacy_shim, hooks_alias_count, webserver_register_path_prefix,
  create_webserver, authentication).
- 73 PASS / 0 NEW FAIL in the broader test suite. 3 pre-existing baseline
  segfaults (lookup_pipeline, route_table_concurrency, routing_regression)
  and 6 pre-existing compile failures (basic, http_resource,
  header_hygiene_iovec, iovec_entry, hook_api_shape,
  hooks_per_route_resource_destroyed_first) reproduce on feature/v2.0
  HEAD without these changes.
- scripts/check-examples.sh, check-readme.sh, check-release-notes.sh: OK.
- cpplint clean on new + modified files.

Note on the task action-item line: the spec says "Update the auth
short-circuit path in webserver_dispatch.cpp" -- the actual call site
post-TASK-048 is in webserver_aliases.cpp::install_default_alias_hooks_
(verified by grep -- webserver_dispatch.cpp does not reference
auth_handler). The fix is in webserver_aliases.cpp.

Author: etr

README.md

@@ -618,9 +618,10 @@ build, `webserver(create_webserver{}.use_ssl(true))` throws
   digest auth.
 * **`.auth_handler(auth_handler_ptr cb)`** — install a centralized
   authentication handler that runs before every resource's `render_*`
-  call. The callback returns `nullptr` to allow the request to proceed,
-  or an `http_response` (typically `http_response::unauthorized(realm)`)
-  to reject it. Single source of truth for auth — see [Centralized
+  call. The callback returns `std::nullopt` to allow the request to
+  proceed, or an `http_response` (typically
+  `http_response::unauthorized(realm)`) to reject it. Single source of
+  truth for auth — see [Centralized
   authentication](#using-centralized-authentication).
 * **`.auth_skip_paths(const std::vector<std::string>& paths)`** — paths
   to bypass `auth_handler`. Exact match (`"/health"`) and wildcard
@@ -1226,14 +1227,13 @@ resource. Centralized authentication lets you define the policy once and
 have it applied automatically to every request:
 
 ```cpp
-// auth runs once per request before any render_*; return nullptr to allow
+// auth runs once per request before any render_*; return std::nullopt to allow
 auto auth = [](const httpserver::http_request& req)
-    -> std::shared_ptr<httpserver::http_response> {
+    -> std::optional<httpserver::http_response> {
     if (req.get_user() != "admin" || req.get_pass() != "secret") {
-        return std::make_shared<httpserver::http_response>(
-            httpserver::http_response::unauthorized("MyRealm"));
+        return httpserver::http_response::unauthorized("MyRealm");
     }
-    return nullptr;
+    return std::nullopt;
 };
 
 httpserver::webserver ws{httpserver::create_webserver(8080)
@@ -1248,9 +1248,10 @@ ws.start(true);
 The `auth_handler` callback runs for every request before the resource's
 render method. It receives the `http_request` and can:
 
-* Return `nullptr` to allow the request to proceed normally.
+* Return `std::nullopt` to allow the request to proceed normally.
 * Return an `http_response` (typically `http_response::unauthorized`) to
-  reject the request.
+  reject the request. The response is moved onto the wire by the
+  dispatcher; no heap allocation is required.
 
 `auth_skip_paths` accepts a vector of paths that should bypass the
 handler:

RELEASE_NOTES.md

@@ -159,6 +159,7 @@ and see the v2 replacement.
 | `deferred_response` | `http_response::deferred` |
 | `basic_auth_fail_response` | `http_response::unauthorized` |
 | `digest_auth_fail_response` | `http_response::unauthorized` |
+| `auth_handler_ptr` returning `std::shared_ptr<http_response>` | `auth_handler_ptr` returning `std::optional<http_response>` |
 
 > **Note:** `shoutCAST()` is the sole camelCase survivor in the v2 public API.
 > The name maps to the SHOUTcast streaming protocol and is intentionally
@@ -171,6 +172,16 @@ and see the v2 replacement.
   v2 returns a value. The framework moves it into the dispatch path. No
   heap allocation is required for small responses (small-buffer optimisation
   inside `http_response`).
+- **Centralized auth handler returns `std::optional<http_response>`.**
+  The `auth_handler` callback signature is now
+  `std::function<std::optional<http_response>(const http_request&)>`
+  (earlier v2 work-in-progress shipped
+  `std::function<std::shared_ptr<http_response>(const http_request&)>`).
+  Return `std::nullopt` to allow the request; return an `http_response`
+  to reject. The v1 `shared_ptr` shape still compiles for one
+  transitional build via `httpserver::compat::auth_handler_v1_ptr` and a
+  `[[deprecated]]` setter overload; both emit a deprecation warning.
+  Removes one heap allocation per authenticated request.
 - **`http_request` getters return `const&` / `string_view`.** v1's
   `get_header(name)` (and `get_arg`, `get_cookie`, `get_footer`) returned
   by value and inserted an empty entry into the request map on miss; v2's

examples/centralized_authentication.cpp

@@ -19,7 +19,7 @@
 */
 
 // centralized_authentication.cpp - install a server-wide auth_handler
-// that runs before every request. The handler returns nullptr to
+// that runs before every request. The handler returns std::nullopt to
 // accept, or an http_response to reject. auth_skip_paths lists routes
 // that bypass auth entirely.
 //
@@ -42,29 +42,30 @@
 
 #include <cstdlib>
 #include <iostream>
-#include <memory>
+#include <optional>
 #include <string>
 
 #include <httpserver.hpp>
 
-// Returns nullptr to allow the request, or an http_response to reject it.
-std::shared_ptr<httpserver::http_response> auth_handler(
+// Returns std::nullopt to allow the request, or an engaged optional
+// carrying an http_response to reject it (TASK-054).
+std::optional<httpserver::http_response> auth_handler(
         const httpserver::http_request& req) {
     const char* expected_user = std::getenv("AUTH_USER");
     const char* expected_pass = std::getenv("AUTH_PASS");
     if (!expected_user || !expected_pass) {
         std::cerr << "centralized_authentication: AUTH_USER and AUTH_PASS "
                      "environment variables must be set.\n";
-        return std::make_shared<httpserver::http_response>(
+        return std::optional<httpserver::http_response>(
             httpserver::http_response::string("Server configuration error")
                 .with_status(500));
     }
     if (req.get_user() != expected_user || req.get_pass() != expected_pass) {
-        return std::make_shared<httpserver::http_response>(
+        return std::optional<httpserver::http_response>(
             httpserver::http_response::unauthorized(
                 "Basic", "MyRealm", "Unauthorized"));
     }
-    return nullptr;
+    return std::nullopt;
 }
 
 int main() {

specs/architecture/04-components/create-webserver.md

@@ -6,6 +6,22 @@
 
 The builder remains non-PIMPL (it's a pure value carrier; PIMPL would buy nothing).
 
-**Related requirements:** PRD-CFG-REQ-001..004.
+**`auth_handler_ptr` shape (TASK-054).** The centralised authentication
+callback is `std::function<std::optional<http_response>(const http_request&)>`.
+Returning `std::nullopt` allows the request through; returning an
+engaged optional short-circuits the before_handler chain with that
+response (the dispatcher moves it into `mr->response`). The earlier v2
+work-in-progress shape returned `std::shared_ptr<http_response>`; that
+shape remains available for one transitional build via the
+`httpserver::compat::auth_handler_v1_ptr` typedef alias and a
+`[[deprecated]]` setter overload (`auth_handler(compat::auth_handler_v1_ptr)`),
+both of which wrap the legacy callable via `compat::adapt_legacy_auth`
+into the canonical `auth_handler_ptr` shape and emit a deprecation
+diagnostic at the call site. The compat alias and overload will be
+removed after the next release. Rationale: completes the
+PRD-RSP-REQ-007 value-typed response cutover (DR-009) onto the auth
+path, removing the per-authenticated-request control-block allocation.
+
+**Related requirements:** PRD-CFG-REQ-001..004, PRD-RSP-REQ-007.
 
 ---

src/detail/webserver_aliases.cpp

@@ -58,6 +58,7 @@
 #include <cassert>
 #include <functional>
 #include <memory>
+#include <optional>
 #include <string>
 #include <string_view>
 #include <utility>
@@ -211,15 +212,18 @@ void webserver::install_default_alias_hooks_() {
                     if (impl_ptr->should_skip_auth(path)) {
                         return hook_action::pass();
                     }
-                    // Call the user-supplied auth_handler. Returns nullptr
-                    // to mean "allow" (pass-through); non-null means
-                    // "reject with this response". The shared_ptr<> is the
-                    // v1 nullable-optional pattern; see the TODO on
-                    // auth_handler_ptr in create_webserver.hpp for the
-                    // deferred migration plan.
-                    std::shared_ptr<http_response> auth_rejection_response =
+                    // Call the user-supplied auth_handler. TASK-054: the
+                    // return type is std::optional<http_response>. nullopt
+                    // means "allow"; an engaged optional carries the
+                    // rejection response. Compared to the v1
+                    // shared_ptr<http_response> shape this saves the
+                    // per-authenticated-request control-block allocation
+                    // (one heap alloc removed per request that runs through
+                    // this hook), and small responses ride the http_response
+                    // SBO with zero further allocs.
+                    std::optional<http_response> auth_rejection_response =
                         ws_ptr->auth_handler(*ctx.request);
-                    if (auth_rejection_response == nullptr) {
+                    if (!auth_rejection_response.has_value()) {
                         return hook_action::pass();
                     }
                     // Auth failed: short-circuit with the rejection response.

src/httpserver/create_webserver.hpp

@@ -30,6 +30,7 @@
 #include <memory>
 #include <functional>
 #include <limits>
+#include <optional>
 #include <stdexcept>
 #include <string>
 #include <string_view>
@@ -89,15 +90,71 @@ namespace http { class file_info; }
 
 typedef std::function<bool(const std::string&, const std::string&, const http::file_info&)> file_cleanup_callback_ptr;
 
-// TODO(follow-up): migrate auth_handler_ptr to
-//   std::function<std::optional<http_response>(const http_request&)>
-// to complete the DR-004 value-return rollout to the auth hook (removing
-// the per-authenticated-request heap allocation for the shared_ptr control
-// block). This requires updating the call site in webserver_finalize.cpp,
-// the example in examples/centralized_authentication.cpp, and the
-// integration test in test/integ/authentication.cpp. Deferred from TASK-036
-// to avoid a cascading public-API break mid-milestone.
-typedef std::function<std::shared_ptr<http_response>(const http_request&)> auth_handler_ptr;
+/**
+ * Centralised authentication callback signature.
+ *
+ * Returning `std::nullopt` allows the request to proceed to dispatch.
+ * Returning an engaged `std::optional<http_response>` short-circuits the
+ * before_handler chain and sends that response on the wire (typically a
+ * 401 produced by `http_response::unauthorized(realm)`).
+ *
+ * Migrated from `std::function<std::shared_ptr<http_response>(...)>` to
+ * remove the per-authenticated-request control-block allocation; the
+ * by-value `http_response` carries small bodies via SBO without any heap
+ * traffic. See TASK-054, DR-009, PRD-RSP-REQ-007.
+ */
+typedef std::function<std::optional<http_response>(const http_request&)> auth_handler_ptr;
+
+namespace compat {
+
+/**
+ * One-transitional-build alias preserving the v1 auth callable shape
+ * (`std::function<std::shared_ptr<http_response>(const http_request&)>`).
+ *
+ * A v1 caller can migrate without an in-place call-site change by
+ * spelling the type as `httpserver::compat::auth_handler_v1_ptr`; the
+ * deprecated @ref create_webserver::auth_handler(compat::auth_handler_v1_ptr)
+ * overload wraps the callable via @ref compat::adapt_legacy_auth into the
+ * new @ref auth_handler_ptr shape. Both this alias and the overload emit
+ * a deprecation diagnostic; they will be removed in the next release.
+ *
+ * @deprecated Migrate to @ref auth_handler_ptr returning
+ *             `std::optional<http_response>`.
+ */
+using auth_handler_v1_ptr
+[[deprecated(
+"use auth_handler_ptr returning std::optional<http_response>; "
+"see RELEASE_NOTES.md 'auth handler migration' (TASK-054)")]]
+= std::function<std::shared_ptr<http_response>(const http_request&)>;
+
+/**
+ * Adapts a v1 auth callable (`std::shared_ptr<http_response>` return)
+ * into the v2 @ref auth_handler_ptr shape.
+ *
+ * The returned wrapper invokes @p legacy; a null `shared_ptr` maps to
+ * `std::nullopt` (allow); a non-null `shared_ptr` is dereferenced and
+ * its pointed-to @ref http_response is MOVED into the engaged optional
+ * (so response state — status, body, headers — is forwarded verbatim).
+ *
+ * @deprecated Provided for one transitional build. Migrate the callable's
+ *             return type to `std::optional<http_response>` and pass it
+ *             directly to @ref create_webserver::auth_handler.
+ */
+[[deprecated(
+    "v1 shared_ptr<http_response> auth signature is deprecated; "
+    "migrate to std::optional<http_response> (TASK-054)")]]
+inline auth_handler_ptr adapt_legacy_auth(
+        std::function<std::shared_ptr<http_response>(
+            const http_request&)> legacy) {
+    return [legacy = std::move(legacy)](const http_request& req)
+            -> std::optional<http_response> {
+        std::shared_ptr<http_response> ptr = legacy(req);
+        if (ptr == nullptr) return std::nullopt;
+        return std::optional<http_response>(std::move(*ptr));
+    };
+}
+
+}  // namespace compat
 
 /**
  * Fluent builder for @ref webserver instances (PRD-NAM-REQ-004,
@@ -363,9 +420,9 @@ class create_webserver {
      /**
       * Install the centralised auth handler invoked before every
       * dispatched request whose path is not on the @ref auth_skip_paths
-      * list. Returning a non-null `shared_ptr<http_response>` short-
-      * circuits dispatch and sends that response on the wire
-      * (typically a 401 or 403).
+      * list. Returning an engaged `std::optional<http_response>` short-
+      * circuits dispatch and sends that response on the wire (typically a
+      * 401 or 403). Returning `std::nullopt` allows the request to proceed.
       *
       * @note This is an alias. Calling it (with a non-null callable)
       *       installs a hook at @ref httpserver::hook_phase::before_handler.
@@ -385,10 +442,30 @@ class create_webserver {
       *       use a wildcard resource registered at "/" or implement the
       *       check inside the `not_found_handler`.
       *
-      * @param v auth_handler_ptr callback; pass `nullptr` to clear.
+      * @param v @ref auth_handler_ptr callback; pass `nullptr` to clear.
       * @return reference to this builder for chaining.
       */
      create_webserver& auth_handler(auth_handler_ptr v) { _auth_handler = std::move(v); return *this; }
+
+     /**
+      * Deprecated v1 overload: accepts a callable returning
+      * `std::shared_ptr<http_response>`, wraps it via
+      * @ref compat::adapt_legacy_auth, and stores it in the canonical
+      * @ref auth_handler_ptr shape. Provided for one transitional build
+      * so existing v1 call sites get a deprecation warning rather than
+      * a hard build break.
+      *
+      * @deprecated Migrate callables to return
+      *             `std::optional<http_response>` and use the canonical
+      *             @ref auth_handler(auth_handler_ptr) overload.
+      */
+     [[deprecated(
+         "v1 shared_ptr<http_response> auth signature is deprecated; "
+         "return std::optional<http_response> instead (TASK-054)")]]
+     create_webserver& auth_handler(compat::auth_handler_v1_ptr v) {
+         _auth_handler = compat::adapt_legacy_auth(std::move(v));
+         return *this;
+     }
      create_webserver& auth_skip_paths(std::vector<std::string> v) { _auth_skip_paths = std::move(v); return *this; }
      create_webserver& sni_callback(sni_callback_t v) { _sni_callback = std::move(v); return *this; }