ci: complete TASK-058 max_args / cache field-rename feature pieces

Earlier CI fix commits (2e803ed, 096424d, fdee3d7) inadvertently swept
in halves of an in-progress, multi-file refactor that was sitting
uncommitted in the working tree.  HEAD became internally inconsistent:
http_request_impl.cpp referenced cs->max_args_count and the
ensure_args_flat_view_cached / path_pieces_cache_built_ field set, but
the matching declarations on http_request_impl.hpp, connection_state.hpp,
create_webserver.hpp, and webserver.hpp were not in HEAD, breaking
every Verify Build lane that actually builds tests.

Commit the matching pieces so HEAD is self-consistent again:

* src/httpserver/webserver.hpp + src/webserver.cpp: const max_args_count
  / max_args_bytes members on the webserver class + matching ctor
  initializer-list lines reading the values out of create_webserver.

* src/httpserver/detail/connection_state.hpp: per-connection
  max_args_count / max_args_bytes fields plus the comment update
  explaining the compile-time ARENA_INITIAL_BYTES decision.

* src/httpserver/detail/http_request_impl.hpp: rename
  path_pieces / path_pieces_public_ to path_pieces_cached_ +
  args_flat_view_cached_; add args_flat_view_cache_built_ and
  path_pieces_cache_built_ guards.

* src/httpserver/http_request.hpp + src/http_request.cpp: forward the
  new arg / path-piece flat-view accessors through the public class.

* src/httpserver/http_response.hpp, http_method.hpp,
  detail/modded_request.hpp, detail/radix_tree.hpp: smaller in-flight
  refactors that interact with the above renames.

* Makefile.am: extra noinst headers / test entries that came along
  with the renames.

* test/REGRESSION.md, test/headers/*, test/integ/{authentication,basic}.cpp,
  test/unit/{http_response_sbo,routing_regression}_test.cpp:
  test-side adjustments to match the new field / accessor names.

No behavioural change beyond what those files already document; the
feature work itself was authored on this branch before the CI sweep
started.

Author: etr

Makefile.am

@@ -76,7 +76,15 @@ EXTRA_DIST = libhttpserver.pc.in $(DX_CONFIG) scripts/extract-release-notes.sh s
 # that -DHTTPSERVER_COMPILATION (set in src/ and test/ AM_CPPFLAGS) cannot
 # leak into the consumer-style compile. A true consumer never has that macro.
 CHECK_HEADERS_CXX = $(CXX) -std=c++20 -I$(top_builddir) -I$(top_srcdir)/src -I$(top_srcdir)/src/httpserver $(CPPFLAGS)
-CHECK_HEADERS_GATE_MSG = Only <httpserver.hpp> or <httpserverpp> can be included directly.
+# Public-header gate (consumer_direct, consumer_post_umbrella): triggered when
+# a public httpserver/* header is included without the umbrella having defined
+# _HTTPSERVER_HPP_INSIDE_.
+CHECK_HEADERS_PUBLIC_GATE_MSG = Only <httpserver.hpp> or <httpserverpp> can be included directly.
+# Detail-header gate (consumer_detail, consumer_detail_modded): post-TASK-014
+# the detail-header gate is HTTPSERVER_COMPILATION-only and emits a message of
+# the form "httpserver/detail/<file>.hpp is internal; only include it when
+# compiling libhttpserver (HTTPSERVER_COMPILATION must be defined)."
+CHECK_HEADERS_DETAIL_GATE_MSG = is internal; only include it when compiling libhttpserver
 
 check-headers:
 	@echo "=== check-headers A.1: direct public-header include must fail ==="
@@ -86,7 +94,7 @@ check-headers:
 	    rm -f check-headers-A1.log; \
 	    exit 1; \
 	fi
-	@if ! grep -q "$(CHECK_HEADERS_GATE_MSG)" check-headers-A1.log; then \
+	@if ! grep -q "$(CHECK_HEADERS_PUBLIC_GATE_MSG)" check-headers-A1.log; then \
 	    echo "FAIL: consumer_direct.cpp failed but not for the gate reason"; \
 	    cat check-headers-A1.log; \
 	    rm -f check-headers-A1.log; \
@@ -95,18 +103,18 @@ check-headers:
 	@rm -f check-headers-A1.log
 	@echo "  PASS: A.1 gate fired as expected"
 	@echo "=== check-headers A.2: direct detail-header include must fail ==="
-	@# NOTE: A.2 currently fires for the same reason as A.1 (neither macro defined).
-	@# After TASK-014 tightens the detail gate to HTTPSERVER_COMPILATION-only,
-	@# consumer_detail.cpp will add '#define _HTTPSERVER_HPP_INSIDE_' to exercise
-	@# the stricter path. Do not collapse A.2 into A.1 — the include path distinction
-	@# (detail/ vs public) is valuable and A.2 becomes a discriminating test post-TASK-014.
+	@# Post-TASK-014: the detail-header gate is HTTPSERVER_COMPILATION-only.
+	@# consumer_detail.cpp defines _HTTPSERVER_HPP_INSIDE_ explicitly so this
+	@# check validates the stricter scenario (the macro alone must not satisfy
+	@# the gate). A.2 is distinct from A.1 because of the include-path
+	@# (detail/ vs public) and the different gate message.
 	@if $(CHECK_HEADERS_CXX) -c $(top_srcdir)/test/headers/consumer_detail.cpp -o /dev/null 2>check-headers-A2.log; then \
 	    echo "FAIL: consumer_detail.cpp compiled but should have errored"; \
 	    cat check-headers-A2.log; \
 	    rm -f check-headers-A2.log; \
 	    exit 1; \
 	fi
-	@if ! grep -q "$(CHECK_HEADERS_GATE_MSG)" check-headers-A2.log; then \
+	@if ! grep -q "$(CHECK_HEADERS_DETAIL_GATE_MSG)" check-headers-A2.log; then \
 	    echo "FAIL: consumer_detail.cpp failed but not for the gate reason"; \
 	    cat check-headers-A2.log; \
 	    rm -f check-headers-A2.log; \
@@ -122,7 +130,7 @@ check-headers:
 	    rm -f check-headers-A2b.log; \
 	    exit 1; \
 	fi
-	@if ! grep -q "$(CHECK_HEADERS_GATE_MSG)" check-headers-A2b.log; then \
+	@if ! grep -q "$(CHECK_HEADERS_DETAIL_GATE_MSG)" check-headers-A2b.log; then \
 	    echo "FAIL: consumer_detail_modded.cpp failed but not for the gate reason"; \
 	    cat check-headers-A2b.log; \
 	    rm -f check-headers-A2b.log; \
@@ -146,7 +154,7 @@ check-headers:
 	    rm -f check-headers-A4.log; \
 	    exit 1; \
 	fi
-	@if ! grep -q "$(CHECK_HEADERS_GATE_MSG)" check-headers-A4.log; then \
+	@if ! grep -q "$(CHECK_HEADERS_PUBLIC_GATE_MSG)" check-headers-A4.log; then \
 	    echo "FAIL: consumer_post_umbrella.cpp failed but not for the gate reason"; \
 	    cat check-headers-A4.log; \
 	    rm -f check-headers-A4.log; \

src/http_request.cpp

@@ -185,19 +185,17 @@ void http_request::set_method(const std::string& method) {
 }
 
 const std::vector<std::string>& http_request::get_path_pieces() const {
-    // TASK-017: lazily populate both caches and return the public-typed
-    // mirror by const&. All cache-maintenance logic lives inside the impl
-    // class (code-quality-reviewer-iter1-4 / code-simplifier-iter1-8).
+    // TASK-017: lazily populate the cache and return it by const&. All
+    // cache-maintenance logic lives inside the impl class.
+    // (code-quality-reviewer-iter1-4 / code-simplifier-iter1-8)
     impl_->ensure_path_pieces_cached(path);
-    impl_->ensure_path_pieces_public_cached();
-    return impl_->path_pieces_public_;
+    return impl_->path_pieces_cached_;
 }
 
 const std::string http_request::get_path_piece(int index) const {
     impl_->ensure_path_pieces_cached(path);
-    if (static_cast<int>(impl_->path_pieces.size()) > index) {
-        const auto& p = impl_->path_pieces[index];
-        return std::string(p.data(), p.size());
+    if (static_cast<int>(impl_->path_pieces_cached_.size()) > index) {
+        return impl_->path_pieces_cached_[index];
     }
     return EMPTY;
 }
@@ -268,13 +266,11 @@ const http::arg_view_map& http_request::get_args() const {
     return impl_->args_view_cached_;
 }
 
-const std::map<std::string_view, std::string_view, http::arg_comparator> http_request::get_args_flat() const {
+const std::map<std::string_view, std::string_view, http::arg_comparator>&
+http_request::get_args_flat() const {
     impl_->populate_args();
-    std::map<std::string_view, std::string_view, http::arg_comparator> ret;
-    for (const auto& [key, val] : impl_->unescaped_args) {
-        ret[key] = val[0];
-    }
-    return ret;
+    impl_->ensure_args_flat_view_cached();
+    return impl_->args_flat_view_cached_;
 }
 
 http::file_info& http_request::get_or_create_file_info(const std::string& key, const std::string& upload_file_name) {

src/httpserver/detail/connection_state.hpp

@@ -66,8 +66,14 @@ namespace detail {
 //     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.
+//   - ARENA_INITIAL_BYTES stays compile-time intentionally: the buffer is
+//     an embedded std::array, so making it runtime-sized would require an
+//     extra heap allocation per connection. The compile-time default is
+//     sized to cover typical small-GET / small-POST shapes without
+//     overflow; profiling has not shown a deployed workload where the
+//     per-connection extra allocation pays for itself. If a future
+//     deployment needs tuning, replace initial_buffer_ with a
+//     unique_ptr<std::byte[]> + runtime size carried here.
 struct connection_state {
     static constexpr std::size_t ARENA_INITIAL_BYTES = 8192;
 
@@ -81,6 +87,15 @@ struct connection_state {
         initial_buffer_.data(), initial_buffer_.size(),
         std::pmr::new_delete_resource()};
 
+    // Per-connection args DoS limits, copied from webserver::max_args_count
+    // / max_args_bytes by webserver_impl::connection_notify at
+    // MHD_CONNECTION_NOTIFY_STARTED. populate_args() reads these from the
+    // socket_context to set up the per-request arguments_accumulator. A
+    // value of 0 means "use the arguments_accumulator compile-time
+    // default", matching create_webserver's sentinel convention.
+    std::size_t max_args_count = 0;
+    std::size_t max_args_bytes = 0;
+
     connection_state() = default;
     connection_state(const connection_state&) = delete;
     connection_state& operator=(const connection_state&) = delete;

src/httpserver/detail/http_request_impl.hpp

@@ -118,8 +118,7 @@ class http_request_impl {
 #ifdef HAVE_DAUTH
           digested_user(alloc),
 #endif  // HAVE_DAUTH
-          unescaped_args(alloc),
-          path_pieces(alloc)
+          unescaped_args(alloc)
 #ifdef HAVE_GNUTLS
           , client_cert_dn(alloc),
           client_cert_issuer_dn(alloc),
@@ -183,24 +182,22 @@ class http_request_impl {
 #endif  // HAVE_DAUTH
     mutable std::pmr::map<std::pmr::string, std::pmr::vector<std::pmr::string>,
                           http::arg_comparator> unescaped_args;
-    mutable std::pmr::vector<std::pmr::string> path_pieces;
     mutable bool args_populated = false;
-    mutable bool path_pieces_cached = false;
 #ifdef HAVE_BAUTH
     // Guard for fetch_user_pass(): once the MHD round-trip has been made
     // (whether or not the request carries a Basic-Auth header), further
     // calls to get_user()/get_pass() skip the MHD call entirely.
     // Using a dedicated boolean (rather than checking username.empty())
-    // matches the args_populated / path_pieces_cached pattern and avoids
-    // a redundant MHD call on requests with no auth credentials where the
-    // credential strings remain empty after the first fetch.
+    // matches the args_populated pattern and avoids a redundant MHD call
+    // on requests with no auth credentials where the credential strings
+    // remain empty after the first fetch.
     // (code-simplifier finding #6 / major review item)
     mutable bool user_pass_fetched = false;
 #endif  // HAVE_BAUTH
     // Cache guard for get_requestor(). Using a dedicated boolean (rather
     // than checking requestor_ip.empty()) is consistent with the boolean-
-    // flag pattern used by args_populated and path_pieces_cached, and is
-    // robust if the connection layer ever returns an empty IP string.
+    // flag pattern used by args_populated, and is robust if the connection
+    // layer ever returns an empty IP string.
     // (code-simplifier finding #7 / minor review item)
     mutable bool requestor_ip_cached = false;
 
@@ -211,7 +208,7 @@ class http_request_impl {
     // and reused on subsequent calls.
     //
     // Allocator note: the public container types embed std::string_view
-    // (header_view_map / arg_view_map) or std::string (path_pieces_public_)
+    // (header_view_map / arg_view_map) or std::string (path_pieces_cached_)
     // and use the default allocator. They cannot be made PMR without
     // changing the public surface (TASK-017 plan, "Storage strategy").
     // The first call therefore allocates on the global heap; subsequent
@@ -231,24 +228,27 @@ class http_request_impl {
     mutable http::arg_view_map args_view_cached_;
     mutable bool args_view_cache_built_ = false;
 
-    // Public-typed mirror of `path_pieces` (the pmr::vector<pmr::string>
-    // already kept above). Two caches in lockstep: the pmr version stays
-    // arena-friendly for any future internal consumer (e.g. radix-tree
-    // route matching that must allocate on the per-connection arena);
-    // the public version is what get_path_pieces() returns by const&.
+    // PRD-REQ-REQ-001 / Item 19 / Item 24: cached "first value per key"
+    // view used by get_args_flat(). Aliases the pmr-backed unescaped_args
+    // storage via string_view, so it shares the request's lifetime.
+    // Avoids the O(n log n) reconstruction the by-value form paid on
+    // every call.
+    mutable std::map<std::string_view, std::string_view, http::arg_comparator>
+        args_flat_view_cached_;
+    mutable bool args_flat_view_cache_built_ = false;
+
+    // Tokenised path pieces. Single cache populated lazily on the first
+    // get_path_pieces() / get_path_piece(int) call. Stored as
+    // std::vector<std::string> so get_path_pieces() can return it by
+    // const& without an ABI break.
     //
-    // Deliberate dual-cache design (architecture-alignment-checker-iter1-1 /
-    // code-quality-reviewer-iter1-5 / performance-reviewer-iter1-13):
-    //   - The pmr::vector<pmr::string> cannot be returned as const
-    //     vector<string>& without an ABI change, so the public mirror
-    //     exists as a forward-compatible layer.
-    //   - No current internal consumer uses path_pieces post-PIMPL;
-    //     if none materialises before TASK-018 lands the two caches can
-    //     be collapsed to a single std::vector<std::string>.
-    //   - TODO(post-018): evaluate collapsing to a single cache if no
-    //     internal arena consumer has emerged.
-    mutable std::vector<std::string> path_pieces_public_;
-    mutable bool path_pieces_public_built_ = false;
+    // The post-PIMPL audit (TASK-018) found no internal arena consumer of
+    // a pmr-backed path-pieces vector, so the earlier dual-cache design
+    // (pmr arena copy + public mirror) was collapsed to this single
+    // heap-allocated cache. If a future radix/route-matching path needs
+    // arena-allocated pieces, reintroduce the pmr cache alongside.
+    mutable std::vector<std::string> path_pieces_cached_;
+    mutable bool path_pieces_cache_built_ = false;
 
     // TASK-057: when true, http_request::operator<< streams credential
     // material verbatim (v1 verbose form). Default false: the four
@@ -290,22 +290,20 @@ class http_request_impl {
     // the same reference in O(1).
     const http::header_view_map& ensure_headerlike_cache(MHD_ValueKind kind) const;
     void populate_args() const;
+    // Populates path_pieces_cached_ from the tokenised request path on
+    // first call. Subsequent calls are O(1) and zero-allocating.
     void ensure_path_pieces_cached(std::string_view path) const;
 
-    // TASK-017: populates the public-typed mirror of path_pieces and marks
-    // path_pieces_public_built_. Called from get_path_pieces() after
-    // ensure_path_pieces_cached() so all cache-maintenance logic for the
-    // public mirror lives inside the impl class (analogous to
-    // ensure_headerlike_cache / ensure_path_pieces_cached).
-    // (code-quality-reviewer-iter1-4 / code-simplifier-iter1-8)
-    void ensure_path_pieces_public_cached() const;
-
     // TASK-017: populates the arg view-map cache from unescaped_args.
     // Called from get_args() so the build loop lives inside the impl
     // class, keeping all cache-maintenance code in one place.
     // (code-simplifier-iter1-9)
     void ensure_args_view_cached() const;
 
+    // Populates args_flat_view_cached_ from unescaped_args, picking the
+    // first value for each key. Called from get_args_flat().
+    void ensure_args_flat_view_cached() const;
+
     void set_arg(const std::string& key, const std::string& value, std::size_t content_size_limit);
     void set_arg(const char* key, const char* value, std::size_t size, std::size_t content_size_limit);
     void set_arg_flat(const std::string& key, const std::string& value, std::size_t content_size_limit);
@@ -347,9 +345,10 @@ class http_request_impl {
 //
 // Defaults are deliberately generous (64 unique keys / 64 KiB total bytes)
 // so existing callers that construct the accumulator without setting these
-// fields remain compatible. The webserver hot path sets these from
-// connection_state or a compile-time constant once the create_webserver
-// API exposes them (TODO(M5)).
+// fields remain compatible. Operators can override via
+// create_webserver::max_args_count() / max_args_bytes(); populate_args()
+// reads the per-connection override from connection_state when present
+// and falls back to these compile-time defaults otherwise.
 //
 // NOTE: POST argument limits are handled upstream by MHD_OPTION_CONNECTION_
 // MEMORY_LIMIT; the guards here apply only to GET arguments processed via

src/httpserver/detail/modded_request.hpp

@@ -18,12 +18,12 @@
      USA
 */
 
-// TASK-014: this detail header uses a dual-mode gate (_HTTPSERVER_HPP_INSIDE_ OR
-// HTTPSERVER_COMPILATION) because webserver.hpp (a public header) still
-// transitively includes it. Once TASK-014 lands the PIMPL split removing that
-// transitive include, tighten this gate to HTTPSERVER_COMPILATION-only.
-#if !defined (_HTTPSERVER_HPP_INSIDE_) && !defined (HTTPSERVER_COMPILATION)
-#error "Only <httpserver.hpp> or <httpserverpp> can be included directly."
+// ADR-002 / TASK-014: PIMPL split removed the transitive include of
+// modded_request.hpp from public headers (webserver.hpp now only forward-
+// declares detail::modded_request). The gate is tightened to
+// HTTPSERVER_COMPILATION-only, matching http_endpoint.hpp.
+#if !defined(HTTPSERVER_COMPILATION)
+#error "httpserver/detail/modded_request.hpp is internal; only include it when compiling libhttpserver (HTTPSERVER_COMPILATION must be defined)."
 #endif
 
 #ifndef SRC_HTTPSERVER_DETAIL_MODDED_REQUEST_HPP_