refactor: split webserver_impl.hpp (674 → 330)

Step 3 of the FILE_LOC_MAX ratchet. Two extractions:

  connection_state -> httpserver/detail/connection_state.hpp
    The per-MHD_Connection PMR arena anchor (initial_buffer_ +
    monotonic_buffer_resource + reset_arena()). Self-contained,
    no webserver_impl coupling. As a bonus, http_request.cpp can
    eventually narrow its #include from webserver_impl.hpp down
    to just connection_state.hpp, dropping a heavy header (which
    transitively pulls microhttpd / pthread / gnutls / regex) off
    http_request.cpp's compile-time footprint -- not done in this
    commit to keep the diff focused on the LOC ratchet.

  dispatch / start-helper / MHD-trampoline method declarations ->
  httpserver/detail/webserver_impl_dispatch.hpp
    The 280-line tail of method declarations on webserver_impl --
    start-helper overloads (add_*_mhd_options, compose_*_flags),
    dispatch chain (requests_answer_first/second_step, finalize_answer
    + its CCN-10 sub-helpers), route-lookup / route-cache helpers,
    auth short-circuit, post-iterator helpers, MHD trampolines,
    GnuTLS PSK/SNI callbacks. Same in-class-body #include pattern
    introduced in TASK-step-2 for http_request_auth.hpp: the sibling
    header carries declarations only and gates itself behind
    SRC_HTTPSERVER_DETAIL_WEBSERVER_IMPL_HPP_INSIDE_CLASS_, which is
    #define'd/#undef'd around the include inside class webserver_impl
    body. Standalone inclusion produces a #error.

webserver_impl.hpp ends up at 330 LOC (data members + lifecycle
ctors + the in-class-body include for the dispatch surface).
Behaviourally inert -- no ABI change, no public surface change. The
order of declarations inside class webserver_impl is preserved
verbatim because the sibling is included at the original textual
location.

FILE_LOC_MAX stays at 2700 -- webserver.cpp (2673) still pins it.
Offender list down to four files.

Verification:
  make check                          51/51 PASS (includes hygiene,
                                      install-layout, doxygen,
                                      examples, readme, release-notes)
  ./scripts/check-file-size.sh        PASS at FILE_LOC_MAX=2700

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

Author: etr

scripts/check-file-size.sh

@@ -34,7 +34,6 @@
 #   src/http_request.cpp                       1175
 #   src/httpserver/webserver.hpp                845
 #   src/http_utils.cpp                          730
-#   src/httpserver/detail/webserver_impl.hpp    674
 #
 # FILE_LOC_MAX is pinned by the largest unfixed file (webserver.cpp at
 # 2673), so it cannot drop until the top offender is decomposed. The

src/Makefile.am

@@ -29,7 +29,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 httpserver/detail/route_entry.hpp httpserver/detail/lambda_resource.hpp httpserver/detail/radix_tree.hpp httpserver/detail/route_cache.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/http_request_impl.hpp httpserver/detail/route_entry.hpp httpserver/detail/lambda_resource.hpp httpserver/detail/radix_tree.hpp httpserver/detail/route_cache.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/websocket_handler.hpp httpserver/http_utils.hpp httpserver/ip_representation.hpp httpserver/file_info.hpp httpserver/http_request.hpp httpserver/http_request_auth.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/httpserver/detail/connection_state.hpp

@@ -0,0 +1,112 @@
+/*
+     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
+*/
+
+// Internal detail header. Strict gate: reachable only from libhttpserver
+// translation units, never from the public umbrella.
+// cppcheck-suppress-file unusedStructMember
+#if !defined(HTTPSERVER_COMPILATION)
+#error "connection_state.hpp is internal; only reachable when compiling libhttpserver."
+#endif
+
+#ifndef SRC_HTTPSERVER_DETAIL_CONNECTION_STATE_HPP_
+#define SRC_HTTPSERVER_DETAIL_CONNECTION_STATE_HPP_
+
+#include <cstddef>
+#include <cstring>
+
+#include <array>
+#include <memory_resource>
+
+namespace httpserver {
+namespace detail {
+
+// connection_state: per-MHD_Connection arena anchor.
+//
+// Owns a std::pmr::monotonic_buffer_resource over an embedded initial
+// buffer. The arena is allocated once per MHD connection (in
+// webserver_impl::connection_notify on MHD_CONNECTION_NOTIFY_STARTED)
+// and torn down on MHD_CONNECTION_NOTIFY_CLOSED. Between requests on a
+// keep-alive connection, request_completed calls arena_.release() to
+// rewind the bump pointer, so a second request reuses the same memory.
+//
+// Lifetime contract for views returned by http_request getters: they
+// remain valid until the request-completion callback fires for the
+// request they were derived from. Capturing them past the user
+// handler's return is undefined behavior. (See architecture doc
+// 04-components/http-request.md.)
+//
+// Initial-buffer sizing math (8 KiB):
+//   - sizeof(http_request_impl) ~= 600-700 B with libstdc++/libc++
+//     map/string layouts.
+//   - A typical small GET populates ~1.5 KiB across header_view_map,
+//     querystring, requestor_ip; a small POST with a few args ~2.5 KiB.
+//   - Each std::pmr::map node (unescaped_args) is ~64-96 B on
+//     libstdc++/libc++, so 5 headers/args already consume ~400-500 B
+//     in tree nodes alone. 4 KiB was undersized for realistic requests
+//     with moderate arg counts; 8 KiB matches the test's own generous
+//     buffer and covers the common case without overflow to the upstream
+//     heap. (performance-reviewer-iter1-1.)
+//   - Overflow spills to the upstream resource (default = heap) silently
+//     -- it is a correctness fall-through, not a hard limit.
+//   - TODO(M5): expose ARENA_INITIAL_BYTES via create_webserver if/when
+//     profiling shows tuning value.
+struct connection_state {
+    static constexpr std::size_t ARENA_INITIAL_BYTES = 8192;
+
+    // The buffer aliases storage for any PMR-aware object the arena
+    // hands out, so it must satisfy the strictest fundamental alignment.
+    alignas(std::max_align_t) std::array<std::byte, ARENA_INITIAL_BYTES> initial_buffer_{};
+
+    // upstream defaults to new_delete_resource (= get_default_resource).
+    // We pass it explicitly to make the contract obvious in source.
+    std::pmr::monotonic_buffer_resource arena_{
+        initial_buffer_.data(), initial_buffer_.size(),
+        std::pmr::new_delete_resource()};
+
+    connection_state() = default;
+    connection_state(const connection_state&) = delete;
+    connection_state& operator=(const connection_state&) = delete;
+    connection_state(connection_state&&) = delete;
+    connection_state& operator=(connection_state&&) = delete;
+
+    // reset_arena(): release the bump pointer AND zero the initial buffer.
+    //
+    // The plain arena_.release() rewinds the bump pointer so the next
+    // request reuses the same memory, but it does NOT clear the reclaimed
+    // bytes. Credentials (username, password, digested_user) written into
+    // the arena by a previous request would therefore linger in the buffer
+    // until overwritten by the next request's lazy-cache population.
+    // Explicit zeroing after release() closes that residual-credential
+    // window. (security-reviewer-iter1-3, CWE-226.)
+    //
+    // Using std::memset here (rather than explicit_bzero / SecureZeroMemory)
+    // is acceptable because the buffer is accessed again immediately by the
+    // next request's arena allocation, preventing the compiler from
+    // optimising the clear away as a dead store.
+    void reset_arena() noexcept {
+        arena_.release();
+        std::memset(initial_buffer_.data(), 0, ARENA_INITIAL_BYTES);
+    }
+};
+
+}  // namespace detail
+}  // namespace httpserver
+
+#endif  // SRC_HTTPSERVER_DETAIL_CONNECTION_STATE_HPP_