refactor: close collaborator duplication seams post-decomposition

Tidy the orchestrator/collaborator boundaries flagged by validation:

- daemon_lifecycle gains handle(), a noexcept acquire-load accessor;
  the nine webserver run/info methods in webserver_lifecycle.cpp call
  it instead of repeating daemon_.daemon.load(memory_order_acquire),
  centralizing the memory-order contract in one place.
- route_table gains erase_exact_and_regex_locked_() and
  remove_param_prefix_locked_(); unregister_impl_ and
  unregister_resource call them instead of poking route_table's raw
  tier containers and open-coding the regex remove_if sweep twice.
  Drops the now-unused <algorithm>/<regex> includes from
  webserver_register.cpp.
- hooks.md: repoint the four fire_*_gated phase-table entries at
  webserver_hook_firing.cpp (renamed from webserver_finalize.cpp in
  commit 2e73dcb).

Behavior-preserving; 113/113 pass. Also records the validation run's
unworked-findings ledger.

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

Author: etr

specs/architecture/04-components/hooks.md

@@ -11,11 +11,11 @@
 | `request_received` | `webserver_body_pipeline.cpp:requests_answer_first_step` — post header-parse, pre body-read | **yes** | no (route not yet known) |
 | `body_chunk` | `webserver_body_pipeline.cpp:requests_answer_second_step` — per chunk | **yes** | no |
 | `route_resolved` | `webserver_request.cpp:fire_route_resolved_gated` — called from `webserver_request.cpp:finalize_answer`, after lookup | no | n/a (boundary phase) |
-| `before_handler` | `webserver_finalize.cpp:fire_before_handler_gated` — called from `webserver_request.cpp:finalize_answer`, before dispatch | **yes** | yes |
+| `before_handler` | `webserver_hook_firing.cpp:fire_before_handler_gated` — called from `webserver_request.cpp:finalize_answer`, before dispatch | **yes** | yes |
 | `handler_exception` | `webserver_dispatch.cpp:dispatch_resource_handler` — each catch arm | **yes** (maps exception to response) | yes |
-| `after_handler` | `webserver_finalize.cpp:fire_after_handler_gated` — called from `webserver_request.cpp:finalize_answer` | **yes** (replaces response) | yes |
-| `response_sent` | `webserver_finalize.cpp:fire_response_sent_gated` — called from `webserver_request.cpp:materialize_and_queue_response`, post `MHD_queue_response` | no | yes |
-| `request_completed` | `webserver_finalize.cpp:fire_request_completed_gated` — called from `webserver_callbacks.cpp:request_completed`, NOTIFY_COMPLETED | no | yes |
+| `after_handler` | `webserver_hook_firing.cpp:fire_after_handler_gated` — called from `webserver_request.cpp:finalize_answer` | **yes** (replaces response) | yes |
+| `response_sent` | `webserver_hook_firing.cpp:fire_response_sent_gated` — called from `webserver_request.cpp:materialize_and_queue_response`, post `MHD_queue_response` | no | yes |
+| `request_completed` | `webserver_hook_firing.cpp:fire_request_completed_gated` — called from `webserver_callbacks.cpp:request_completed`, NOTIFY_COMPLETED | no | yes |
 | `connection_closed` | `detail/webserver_callbacks_lifecycle.cpp:connection_notify` — NOTIFY_CLOSED | no | no |
 
 **Implementation.** Each phase has its own `std::vector<std::function<...>>` in `webserver_impl`, guarded by a single `std::shared_mutex hook_table_mutex_`. A per-phase `std::atomic<bool> any_hooks_[hook_phase::count_]` flag short-circuits the dispatch site to a relaxed atomic load and a compare-with-zero when no subscribers exist — the only hook-related cost on the hot request path for a server with zero hooks registered.

specs/unworked_review_issues/2026-07-17_214922_manual-validation.md

@@ -28,6 +28,7 @@
 
 #include "httpserver/detail/route_table.hpp"
 
+#include <algorithm>
 #include <cassert>
 #include <memory>
 #include <mutex>
@@ -525,5 +526,20 @@ void route_table::register_v2_route(const http_endpoint& idx,
     }
 }
 
+void route_table::erase_exact_and_regex_locked_(const std::string& key) {
+    exact_routes_.erase(key);
+    regex_routes_.erase(
+        std::remove_if(regex_routes_.begin(), regex_routes_.end(),
+                       [&key](const regex_route& rr) {
+                           return rr.url_complete == key;
+                       }),
+        regex_routes_.end());
+}
+
+void route_table::remove_param_prefix_locked_(const std::string& key,
+                                              bool is_prefix) {
+    param_and_prefix_routes_.remove(key, is_prefix);
+}
+
 }  // namespace detail
 }  // namespace httpserver

src/detail/route_table.cpp

@@ -193,44 +193,44 @@ bool webserver::stop() {
 }
 
 int webserver::quiesce() {
-    struct MHD_Daemon* d = impl_->daemon_.daemon.load(std::memory_order_acquire);
+    struct MHD_Daemon* d = impl_->daemon_.handle();
     if (d == nullptr) return -1;
     MHD_socket fd = MHD_quiesce_daemon(d);
     return static_cast<int>(fd);
 }
 
 int webserver::get_listen_fd() const {
-    struct MHD_Daemon* d = impl_->daemon_.daemon.load(std::memory_order_acquire);
+    struct MHD_Daemon* d = impl_->daemon_.handle();
     if (d == nullptr) return -1;
     const union MHD_DaemonInfo* info = MHD_get_daemon_info(d, MHD_DAEMON_INFO_LISTEN_FD);
     if (info == nullptr) return -1;
     return static_cast<int>(info->listen_fd);
 }
 
 unsigned int webserver::get_active_connections() const {
-    struct MHD_Daemon* d = impl_->daemon_.daemon.load(std::memory_order_acquire);
+    struct MHD_Daemon* d = impl_->daemon_.handle();
     if (d == nullptr) return 0;
     const union MHD_DaemonInfo* info = MHD_get_daemon_info(d, MHD_DAEMON_INFO_CURRENT_CONNECTIONS);
     if (info == nullptr) return 0;
     return info->num_connections;
 }
 
 uint16_t webserver::get_bound_port() const {
-    struct MHD_Daemon* d = impl_->daemon_.daemon.load(std::memory_order_acquire);
+    struct MHD_Daemon* d = impl_->daemon_.handle();
     if (d == nullptr) return 0;
     const union MHD_DaemonInfo* info = MHD_get_daemon_info(d, MHD_DAEMON_INFO_BIND_PORT);
     if (info == nullptr) return 0;
     return info->port;
 }
 
 bool webserver::run() {
-    struct MHD_Daemon* d = impl_->daemon_.daemon.load(std::memory_order_acquire);
+    struct MHD_Daemon* d = impl_->daemon_.handle();
     if (d == nullptr) return false;
     return MHD_run(d) == MHD_YES;
 }
 
 bool webserver::run_wait(int32_t millisec) {
-    struct MHD_Daemon* d = impl_->daemon_.daemon.load(std::memory_order_acquire);
+    struct MHD_Daemon* d = impl_->daemon_.handle();
     if (d == nullptr) return false;
     return MHD_run_wait(d, millisec) == MHD_YES;
 }
@@ -241,7 +241,7 @@ bool webserver::get_fdset(fd_set* read_fd_set, fd_set* write_fd_set,
     // restoring compile-time type safety. The public header pulls in
     // <sys/select.h> / <winsock2.h> directly because fd_set is a typedef
     // and cannot be portably forward-declared.
-    struct MHD_Daemon* d = impl_->daemon_.daemon.load(std::memory_order_acquire);
+    struct MHD_Daemon* d = impl_->daemon_.handle();
     if (d == nullptr) return false;
     MHD_socket mhd_max_fd = 0;
     if (MHD_get_fdset(d,
@@ -256,7 +256,7 @@ bool webserver::get_fdset(fd_set* read_fd_set, fd_set* write_fd_set,
 }
 
 bool webserver::get_timeout(uint64_t* timeout) {
-    struct MHD_Daemon* d = impl_->daemon_.daemon.load(std::memory_order_acquire);
+    struct MHD_Daemon* d = impl_->daemon_.handle();
     if (d == nullptr) return false;
     MHD_UNSIGNED_LONG_LONG mhd_timeout = 0;
     if (MHD_get_timeout(d, &mhd_timeout) != MHD_YES) {
@@ -272,7 +272,7 @@ bool webserver::add_connection(int client_socket, const struct sockaddr* addr, u
     // POSIX guarantees `socklen_t` is an unsigned integer of at least 32
     // bits; `unsigned int` matches on every supported platform.
     // (The sizeof static_assert is at file scope above.)
-    struct MHD_Daemon* d = impl_->daemon_.daemon.load(std::memory_order_acquire);
+    struct MHD_Daemon* d = impl_->daemon_.handle();
     if (d == nullptr) return false;
     return MHD_add_connection(d, client_socket, addr,
                               static_cast<socklen_t>(addrlen)) == MHD_YES;

src/detail/webserver_lifecycle.cpp

@@ -43,13 +43,11 @@
 #include <stdio.h>
 #include <stdlib.h>
 #include <strings.h>
-#include <algorithm>
 #include <cstring>
 #include <iosfwd>
 #include <iostream>
 #include <memory>
 #include <mutex>
-#include <regex>
 #include <set>
 #include <shared_mutex>
 #include <stdexcept>
@@ -170,19 +168,12 @@ void webserver::unregister_impl_(const string& resource, bool family) {
         auto table_lock = impl_->routes_.lock_for_write();
         const std::string& key = he.get_url_complete();
         if (family) {
-            impl_->routes_.param_and_prefix_routes_.remove(key, /*is_prefix=*/true);
+            impl_->routes_.remove_param_prefix_locked_(key, /*is_prefix=*/true);
         } else if (!he.get_url_pars().empty()) {
-            impl_->routes_.param_and_prefix_routes_.remove(key, /*is_prefix=*/false);
+            impl_->routes_.remove_param_prefix_locked_(key, /*is_prefix=*/false);
         } else {
             // Erase from exact tier; also sweep regex tier (url_complete key).
-            impl_->routes_.exact_routes_.erase(key);
-            impl_->routes_.regex_routes_.erase(
-                std::remove_if(impl_->routes_.regex_routes_.begin(),
-                               impl_->routes_.regex_routes_.end(),
-                               [&key](const detail::route_table::regex_route& rr) {
-                                   return rr.url_complete == key;
-                               }),
-                impl_->routes_.regex_routes_.end());
+            impl_->routes_.erase_exact_and_regex_locked_(key);
         }
     }
     impl_->routes_.invalidate_route_cache();
@@ -209,17 +200,11 @@ void webserver::unregister_resource(const string& resource) {
     {
         auto table_lock = impl_->routes_.lock_for_write();
         const std::string& key = he_exact.get_url_complete();
-        impl_->routes_.exact_routes_.erase(key);
-        impl_->routes_.param_and_prefix_routes_.remove(key, /*is_prefix=*/false);
-        impl_->routes_.param_and_prefix_routes_.remove(key, /*is_prefix=*/true);
-        // Also sweep the regex tier by url_complete.
-        impl_->routes_.regex_routes_.erase(
-            std::remove_if(impl_->routes_.regex_routes_.begin(),
-                           impl_->routes_.regex_routes_.end(),
-                           [&key](const detail::route_table::regex_route& rr) {
-                               return rr.url_complete == key;
-                           }),
-            impl_->routes_.regex_routes_.end());
+        // Sweep every tier the key could occupy so a prior register_path AND
+        // register_prefix on the same path are both cleared atomically.
+        impl_->routes_.erase_exact_and_regex_locked_(key);
+        impl_->routes_.remove_param_prefix_locked_(key, /*is_prefix=*/false);
+        impl_->routes_.remove_param_prefix_locked_(key, /*is_prefix=*/true);
     }
     // Delegate cache clearing to invalidate_route_cache() matching the
     // pattern used by register_impl_ and on_methods_ (table lock released

src/detail/webserver_register.cpp

@@ -103,6 +103,15 @@ class daemon_lifecycle {
     // a TSan-flagged data race in the ws_start_stop integ test.
     std::atomic<struct MHD_Daemon*> daemon{nullptr};
 
+    // Acquire-load the published daemon handle, or nullptr when the daemon
+    // is not currently started. Single home for the acquire-semantics
+    // contract documented on `daemon` above, so webserver's run/info
+    // accessors (webserver_lifecycle.cpp) don't each repeat the load + the
+    // memory_order argument.
+    struct MHD_Daemon* handle() const noexcept {
+        return daemon.load(std::memory_order_acquire);
+    }
+
     // MHD_socket (int on POSIX, SOCKET on Windows) for a caller-supplied
     // pre-bound socket passed via create_webserver().bind_socket().
     // MHD_INVALID_SOCKET is the sentinel meaning "no pre-bound socket".

src/httpserver/detail/daemon_lifecycle.hpp

@@ -181,6 +181,19 @@ class route_table {
                            std::shared_ptr<http_resource> res,
                            bool family);
 
+    // Erase @p key from the exact tier and sweep it from the regex tier
+    // (every regex_route whose url_complete == key). These two tiers are
+    // always cleared together on an exact-shaped unregister, so the sweep
+    // lives here in one place rather than being open-coded at each call
+    // site. Caller must hold route_table_mutex_ (unique_lock).
+    void erase_exact_and_regex_locked_(const std::string& key);
+
+    // Remove @p key from the param/prefix trie tier. @p is_prefix selects
+    // the prefix terminus (register_prefix) vs the parameterized terminus
+    // (register_path with :params). Caller must hold route_table_mutex_
+    // (unique_lock).
+    void remove_param_prefix_locked_(const std::string& key, bool is_prefix);
+
     // --- Route-table state -----------------------------------------------
     // One shared_mutex covering the three tiers. Writes (registration)
     // are rare; reads (dispatch lookups) take shared ownership briefly.