Merge TASK-054: auth_handler_ptr → optional<http_response>

Migrates auth_handler_ptr from shared_ptr<http_response> to
optional<http_response>, removing the last shared_ptr<http_response>
on the public API (PRD-RSP-REQ-007, DR-009).

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

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.
 
 ---

specs/tasks/v2-deferred-backlog-plan.md

@@ -107,22 +107,22 @@ TODO comment marking this migration already lives at
 `src/httpserver/create_webserver.hpp:92-99`.
 
 **Action Items:**
-- [ ] Define `auth_handler_ptr` as
+- [x] Define `auth_handler_ptr` as
   `std::function<std::optional<http_response>(const http_request&)>` in
   `create_webserver.hpp`. Keep the old typedef alias for one transitional
   build with a `[[deprecated]]` attribute pointing at the new shape.
-- [ ] Update the auth short-circuit path in `webserver_dispatch.cpp` to
+- [x] Update the auth short-circuit path in `webserver_dispatch.cpp` to
   consume `optional<http_response>` instead of dereferencing a
   `shared_ptr`.
-- [ ] Update the documented v1 alias surface (`auth_handler` setter) to
+- [x] Update the documented v1 alias surface (`auth_handler` setter) to
   internally adapt v1 callers that still produce a `shared_ptr` (free
   function `compat::adapt_legacy_auth(...)`), with a `[[deprecated]]`
   warning.
-- [ ] Update `examples/centralized_authentication.cpp` to return
+- [x] Update `examples/centralized_authentication.cpp` to return
   `std::optional<http_response>` directly (drop `std::make_shared`).
-- [ ] Update Doxygen, README "Centralized authentication" section, and
+- [x] Update Doxygen, README "Centralized authentication" section, and
   RELEASE_NOTES.md "Migration notes" with the new signature.
-- [ ] Remove the TODO comment at `create_webserver.hpp:92-99`.
+- [x] Remove the TODO comment at `create_webserver.hpp:92-99`.
 
 **Dependencies:**
 - Blocked by: TASK-046 (by-value response cutover, Done)
@@ -141,6 +141,8 @@ TODO comment marking this migration already lives at
 **Related Findings:** task-036 #38, task-030 #18
 **Related Decisions:** DR-009, PRD-RSP-REQ-007
 
+**Status:** Done
+
 ---
 
 ## TASK-055 — DR-009 revision: default error body must not surface `e.what()`