refactor: extract ws_registry collaborator from webserver_impl

Second step of the webserver_impl decomposition. The URL -> websocket_handler
map and its mutex were another independent state cluster on the god-object.
Move them behind detail::ws_registry (try_register / unregister / find / empty).

webserver_impl holds it as 'ws_registry ws_;' (HAVE_WEBSOCKET-gated).
register/unregister_ws_resource mutate it; complete_websocket_upgrade resolves
a handler via find() — which returns a shared_ptr copy under the read lock,
preserving the keep-alive-across-upgrade guarantee; compose_transport_flags
consults empty() for MHD_ALLOW_UPGRADE. The registry never dereferences
websocket_handler (only stores/erases/copies shared_ptrs), so its TU compiles
feature-independently. ws_upgrade_data/upgrade_handler stay as dispatch glue
for now (they move with the dispatch pipeline). No behavioural change;
build-green, 109/109.

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

Author: etr

src/Makefile.am

@@ -25,11 +25,11 @@ lib_LTLIBRARIES = libhttpserver.la
 # builds. The WS-off branch in websocket_handler.cpp provides stub
 # definitions (every member throws feature_unavailable except is_valid()
 # which returns false).
-libhttpserver_la_SOURCES = string_utilities.cpp webserver.cpp webserver_add_hook.cpp http_utils.cpp file_info.cpp http_request.cpp http_request_auth.cpp http_response.cpp http_response_factories.cpp http_resource.cpp create_webserver.cpp create_test_request.cpp websocket_handler.cpp hook_handle.cpp peer_address.cpp resource_hook_table.cpp cookie.cpp detail/http_endpoint.cpp detail/body.cpp detail/ip_representation.cpp detail/ip_access_control.cpp detail/http_request_impl.cpp detail/http_request_impl_args.cpp detail/http_request_impl_tls.cpp detail/webserver_lifecycle.cpp detail/webserver_register.cpp detail/webserver_routes.cpp detail/webserver_routes_upsert.cpp detail/webserver_callbacks.cpp detail/webserver_callbacks_lifecycle.cpp detail/webserver_websocket.cpp detail/webserver_dispatch.cpp detail/webserver_request.cpp detail/webserver_response_queue.cpp detail/webserver_body_pipeline.cpp detail/webserver_error_pages.cpp detail/webserver_aliases.cpp detail/webserver_hook_firing.cpp detail/hook_phase_dispatch.cpp
+libhttpserver_la_SOURCES = string_utilities.cpp webserver.cpp webserver_add_hook.cpp http_utils.cpp file_info.cpp http_request.cpp http_request_auth.cpp http_response.cpp http_response_factories.cpp http_resource.cpp create_webserver.cpp create_test_request.cpp websocket_handler.cpp hook_handle.cpp peer_address.cpp resource_hook_table.cpp cookie.cpp detail/http_endpoint.cpp detail/body.cpp detail/ip_representation.cpp detail/ip_access_control.cpp detail/ws_registry.cpp detail/http_request_impl.cpp detail/http_request_impl_args.cpp detail/http_request_impl_tls.cpp detail/webserver_lifecycle.cpp detail/webserver_register.cpp detail/webserver_routes.cpp detail/webserver_routes_upsert.cpp detail/webserver_callbacks.cpp detail/webserver_callbacks_lifecycle.cpp detail/webserver_websocket.cpp detail/webserver_dispatch.cpp detail/webserver_request.cpp detail/webserver_response_queue.cpp detail/webserver_body_pipeline.cpp detail/webserver_error_pages.cpp detail/webserver_aliases.cpp detail/webserver_hook_firing.cpp detail/hook_phase_dispatch.cpp
 # 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/webserver_impl_dispatch.hpp httpserver/detail/connection_state.hpp httpserver/detail/ip_access_control.hpp httpserver/detail/secure_zero.hpp httpserver/detail/http_request_impl.hpp httpserver/detail/resource_hook_table.hpp httpserver/detail/route_entry.hpp httpserver/detail/lambda_resource.hpp httpserver/detail/segment_trie.hpp httpserver/detail/route_cache.hpp httpserver/detail/route_tier.hpp httpserver/detail/unescape_helpers.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/webserver_impl_dispatch.hpp httpserver/detail/connection_state.hpp httpserver/detail/ip_access_control.hpp httpserver/detail/ws_registry.hpp httpserver/detail/secure_zero.hpp httpserver/detail/http_request_impl.hpp httpserver/detail/resource_hook_table.hpp httpserver/detail/route_entry.hpp httpserver/detail/lambda_resource.hpp httpserver/detail/segment_trie.hpp httpserver/detail/route_cache.hpp httpserver/detail/route_tier.hpp httpserver/detail/unescape_helpers.hpp gettext.h
 nobase_include_HEADERS = httpserver.hpp httpserver/body_kind.hpp httpserver/cookie.hpp httpserver/constants.hpp httpserver/create_webserver.hpp httpserver/create_webserver_setters.hpp httpserver/create_test_request.hpp httpserver/webserver.hpp httpserver/webserver_routes.hpp httpserver/webserver_runtime.hpp httpserver/webserver_websocket.hpp httpserver/webserver_hooks.hpp httpserver/websocket_handler.hpp httpserver/http_utils.hpp httpserver/http_utils_helpers.hpp httpserver/ip_representation.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 httpserver/hook_phase.hpp httpserver/hook_action.hpp httpserver/hook_handle.hpp httpserver/hook_context.hpp
 
 AM_CXXFLAGS += -fPIC -Wall

src/detail/webserver_lifecycle.cpp

@@ -271,7 +271,7 @@ int webserver_impl::compose_runtime_flags() const {
     if (parent->config.turbo) flags |= MHD_USE_TURBO;
     if (parent->config.suppress_date_header) flags |= MHD_USE_SUPPRESS_DATE_NO_CLOCK;
 #ifdef HAVE_WEBSOCKET
-    if (!registered_ws_handlers.empty()) flags |= MHD_ALLOW_UPGRADE;
+    if (!ws_.empty()) flags |= MHD_ALLOW_UPGRADE;
 #endif  // HAVE_WEBSOCKET
     return flags;
 }

src/detail/webserver_routes.cpp

@@ -248,10 +248,7 @@ void webserver::register_ws_resource(const std::string& resource,
         throw std::invalid_argument("The websocket_handler pointer cannot be null");
     }
     std::string url_key = http_utils::standardize_url(resource);
-    std::unique_lock lock(impl_->registered_ws_handlers_mutex_);
-    auto result = impl_->registered_ws_handlers.emplace(std::move(url_key),
-                                                        std::move(handler));
-    if (!result.second) {
+    if (!impl_->ws_.try_register(std::move(url_key), std::move(handler))) {
         // v1's operator[]-based insert silently overwrote; v2.0
         // surfaces the collision by throwing.
         throw std::invalid_argument(
@@ -268,8 +265,7 @@ void webserver::register_ws_resource(const std::string& resource,
 
 void webserver::unregister_ws_resource(const std::string& resource) {
 #ifdef HAVE_WEBSOCKET
-    std::unique_lock lock(impl_->registered_ws_handlers_mutex_);
-    impl_->registered_ws_handlers.erase(http_utils::standardize_url(resource));
+    impl_->ws_.unregister(http_utils::standardize_url(resource));
 #else
     (void)resource;
     throw feature_unavailable("websocket", "HAVE_WEBSOCKET");

src/detail/webserver_websocket.cpp

@@ -209,16 +209,13 @@ std::optional<MHD_Result>
 webserver_impl::complete_websocket_upgrade(MHD_Connection* connection,
                                            detail::modded_request* mr,
                                            const char* ws_key) {
-    std::shared_lock lock(registered_ws_handlers_mutex_);
-    auto ws_it = registered_ws_handlers.find(mr->standardized_url);
-    if (ws_it == registered_ws_handlers.end()) {
+    // find() returns a shared_ptr copy taken under the registry's read lock,
+    // so the handler is kept alive across the MHD upgrade callback even if
+    // unregister_ws_resource erases the slot mid-upgrade.
+    std::shared_ptr<websocket_handler> handler_sp = ws_.find(mr->standardized_url);
+    if (!handler_sp) {
         return std::nullopt;
     }
-    // Take a shared_ptr copy under the shared lock so the
-    // handler is kept alive across the MHD upgrade callback even if
-    // unregister_ws_resource erases the slot mid-upgrade.
-    std::shared_ptr<websocket_handler> handler_sp = ws_it->second;
-    lock.unlock();
 
     // CWE-401: RAII guard so data is freed if MHD_create_response_for_upgrade
     // returns null. Ownership is transferred to MHD (via release()) only after

src/detail/ws_registry.cpp

@@ -0,0 +1,57 @@
+/*
+     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
+*/
+
+#include "httpserver/detail/ws_registry.hpp"
+
+#include <map>
+#include <memory>
+#include <mutex>
+#include <shared_mutex>
+#include <string>
+#include <utility>
+
+namespace httpserver {
+namespace detail {
+
+bool ws_registry::try_register(std::string url_key,
+                               std::shared_ptr<websocket_handler> handler) {
+    std::unique_lock lock(mutex_);
+    return handlers_.emplace(std::move(url_key), std::move(handler)).second;
+}
+
+void ws_registry::unregister(const std::string& url_key) {
+    std::unique_lock lock(mutex_);
+    handlers_.erase(url_key);
+}
+
+std::shared_ptr<websocket_handler> ws_registry::find(
+        const std::string& url) const {
+    std::shared_lock lock(mutex_);
+    auto it = handlers_.find(url);
+    return it == handlers_.end() ? nullptr : it->second;
+}
+
+bool ws_registry::empty() const {
+    std::shared_lock lock(mutex_);
+    return handlers_.empty();
+}
+
+}  // namespace detail
+}  // namespace httpserver

src/httpserver/detail/webserver_impl.hpp

@@ -76,6 +76,7 @@
 #include "httpserver/detail/segment_trie.hpp"
 #include "httpserver/detail/route_cache.hpp"
 #include "httpserver/detail/route_entry.hpp"
+#include "httpserver/detail/ws_registry.hpp"
 
 #if MHD_VERSION < 0x00097002
 typedef int MHD_Result;
@@ -261,7 +262,7 @@ class webserver_impl {
     // resolve_resource_for_request() calls it exclusively, and the
     // 3-tier table is the single routing surface. Lambda/class conflict
     // detection probes the same tiers (find_v2_entry_by_path_);
-    // WebSocket dispatch uses a dedicated registered_ws_handlers_mutex_.
+    // WebSocket dispatch resolves handlers through the separate ws_ registry.
     lookup_result lookup_v2(http_method method, const std::string& path);
 
     // Lifecycle hook bus.
@@ -380,19 +381,14 @@ class webserver_impl {
     ip_access_control acl_;
 
 #ifdef HAVE_WEBSOCKET
-    // shared_ptr storage. The dispatch path
-    // (complete_websocket_upgrade) takes a shared_ptr copy under the
-    // shared lock that keeps the handler alive across an MHD upgrade
-    // callback, even if unregister_ws_resource races to drop the
-    // registration mid-upgrade. The webserver always holds one reference
-    // until the slot is erased.
-    //
-    // Lock: registered_ws_handlers_mutex_ guards this map exclusively,
-    // independent of the HTTP route_table_mutex_; no call site ever
-    // holds both mutexes simultaneously.
-    std::shared_mutex registered_ws_handlers_mutex_;
-    std::map<std::string, std::shared_ptr<::httpserver::websocket_handler>>
-        registered_ws_handlers;
+    // WebSocket handler registry (URL -> handler map + its mutex) lives
+    // behind this collaborator. register/unregister_ws_resource mutate it;
+    // complete_websocket_upgrade resolves a handler via find() (taking a
+    // shared_ptr copy that keeps the handler alive across the MHD upgrade
+    // callback even if unregister races mid-upgrade); start() consults
+    // empty() for MHD_ALLOW_UPGRADE. Its mutex is independent of every
+    // other cluster's; no call site holds two of them at once.
+    ws_registry ws_;
 
     struct ws_upgrade_data {
         webserver_impl* impl;

src/httpserver/detail/ws_registry.hpp

@@ -0,0 +1,78 @@
+/*
+     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
+*/
+
+// WebSocket handler registry collaborator. Internal header; only reachable
+// when compiling libhttpserver translation units. NOT part of the installed
+// surface.
+#if !defined(HTTPSERVER_COMPILATION)
+#error "ws_registry.hpp is internal; only reachable when compiling libhttpserver."
+#endif
+
+#ifndef SRC_HTTPSERVER_DETAIL_WS_REGISTRY_HPP_
+#define SRC_HTTPSERVER_DETAIL_WS_REGISTRY_HPP_
+
+#include <map>
+#include <memory>
+#include <shared_mutex>
+#include <string>
+
+namespace httpserver {
+
+class websocket_handler;
+
+namespace detail {
+
+// Owns the URL -> websocket_handler map and its mutex — the whole of the
+// webserver's websocket-registration state, extracted from webserver_impl.
+// webserver::{register,unregister}_ws_resource mutate it; the dispatch-side
+// upgrade path resolves a handler via find(); start() consults empty() to
+// decide MHD_ALLOW_UPGRADE. This type never dereferences websocket_handler
+// (it only stores/erases/copies shared_ptrs), so it is feature-independent
+// and compiles even on HAVE_WEBSOCKET-off builds.
+class ws_registry {
+ public:
+    // Register @p handler at @p url_key. Returns false if a handler is
+    // already present at that key (the caller surfaces the collision), true
+    // on insert. Takes the write lock.
+    bool try_register(std::string url_key,
+                      std::shared_ptr<websocket_handler> handler);
+
+    // Erase any handler registered at @p url_key. Takes the write lock.
+    void unregister(const std::string& url_key);
+
+    // Return a shared_ptr copy of the handler registered at @p url, or
+    // nullptr if none. The copy keeps the handler alive across an MHD
+    // upgrade even if a concurrent unregister races to drop the slot.
+    // Takes the read lock.
+    [[nodiscard]] std::shared_ptr<websocket_handler> find(
+        const std::string& url) const;
+
+    // True iff no handler is registered. Takes the read lock.
+    [[nodiscard]] bool empty() const;
+
+ private:
+    mutable std::shared_mutex mutex_;
+    std::map<std::string, std::shared_ptr<websocket_handler>> handlers_;
+};
+
+}  // namespace detail
+}  // namespace httpserver
+
+#endif  // SRC_HTTPSERVER_DETAIL_WS_REGISTRY_HPP_