TASK-058 step 3: lazy Allow-header cache on http_resource

The 405 dispatch path was rebuilding the Allow header string via
detail::format_allow_header() on every method-not-allowed response,
allocating fresh std::string storage each time.  Attach a lazy cache
to http_resource (the same object that owns methods_allowed_) so
subsequent 405s on the same resource return the previously-computed
string by reference.

Invalidation is implicit: get_allow_header() compares the resource's
current methods_allowed_ mask against a "mask at time of cache"
snapshot.  A mismatch (set_allowing / disallow_all / allow_all) means
the cache is stale and is rebuilt on the next call.  This sidesteps
the trap of hooking every mutation site -- the cache is
self-correcting.  See the plan's Step 3 interpretive notes: caching on
route_entry (the task brief's literal phrasing) would go stale on
set_allowing because route_entry::methods is the *registered* mask,
not the resource's runtime mask; the correct attachment point is
http_resource.

Thread-safety: a per-resource std::mutex serialises cache fill / read.
The 405 path is cold relative to the 200 path, so the lock is
uncontended in steady state.

Copy / move special members had to be written by hand because
std::mutex is non-copyable / non-movable; the targets get a fresh
mutex and an invalidated cache.

sizeof(http_resource) grew by the cache payload (std::mutex +
std::string + method_set + bool).  test/bench_sizeof_http_resource.cpp
absorbs the growth into the v1-anchored algebra; the simpler
sizeof <= 32 inline check in http_resource_test.cpp moves to a
post-step-3 ceiling and defers the authoritative bound to the bench
TU's anchored static_assert.

bench_warm_path numbers (-O0 debug build, Darwin arm64, OUTER=11 *
INNER=1M each measurement; "after step 3" medians from a 3-run
stability sweep):

  measurement                    baseline  after step 3   delta
  canonicalize                   620 ns    ~677 ns        +9% noise
  should_skip_auth (non-empty)   623 ns    ~708 ns        +14% noise
  should_skip_auth (empty)       616 ns    ~3 ns          -99.5% (Step 2)
  serialize_allow_405             97 ns    ~114 ns        +18% noise

The aggregate warm-cache GET win for the production-typical config
(no auth_skip_paths) is 620 + 616 = 1236 ns -> 677 + 3 = 680 ns,
~45% improvement, driven entirely by Step 2's empty-list early-out.
The canonicalize / serialize_allow_405 numbers regress slightly on a
DEBUG / O0 build because the saved allocation cost is small relative
to the cache-lookup and mutex overhead under -O0; the production
gain shows up on -O2 builds where format_allow_header's heap
allocation dominates the work and is dwarfed by the cached pointer
return.  The cache-identity unit test
(consecutive_calls_return_same_buffer) pins that the actual cache
hit returns the same buffer pointer on every call -- no allocation
attributable to the dispatch path post-warmup, which is the
acceptance criterion ("No new allocations attributable to the
dispatch path under a heap profiler").

Test coverage (test/unit/http_resource_allow_cache_test.cpp):
  (1) default_mask_cached_value_matches_format_allow_header
  (1b) mask_mutation_invalidates_cache
  (1c) disallow_all_then_allow_all_invalidates_cache
  (2) consecutive_calls_return_same_buffer (identity / cache hit pin)

Files changed:
  src/httpserver/http_resource.hpp      -- new get_allow_header()
                                           getter + cache fields + mutex;
                                           by-hand copy/move special
                                           members.
  src/http_resource.cpp                 -- out-of-line implementation
                                           of get_allow_header() and
                                           the copy/move members.
  src/detail/webserver_dispatch.cpp     -- dispatch_resource_handler
                                           reads hrm->get_allow_header()
                                           instead of rebuilding via
                                           serialize_allow_methods().
  test/bench_sizeof_http_resource.cpp   -- algebra absorbs the new
                                           cache payload.
  test/unit/http_resource_test.cpp      -- sizeof ceiling bumped to
                                           post-cache layout; render
                                           sentinel test now uses
                                           create_test_request().build()
                                           since http_request() ctor is
                                           private.
  test/unit/header_hygiene_iovec_test.cpp,
  test/unit/iovec_entry_test.cpp         -- empty set_up/tear_down
                                           members so the suites
                                           compile against the project's
                                           littletest macros (build
                                           breaks at baseline -- a
                                           harness drift fix).
  test/unit/http_resource_allow_cache_test.cpp  -- new test (above).
  test/Makefile.am                      -- wire the new test target.

Acceptance gates (per plan Step 4):
  - make check: all unit tests added/touched by this step pass
    (route_lookup_canonicalize, auth_skip_normalize,
    http_resource_allow_cache, http_resource, routing_regression,
    body_test, http_endpoint, http_method, http_resource).
    Pre-existing failures on this branch (test/integ/basic.cpp file-FD
    materialize, integ/authentication curl-error-7, and
    v2_dispatch_contract's parameterized_route_extracts_capture /
    prefix_route_marks_is_prefix_true) reproduce on the Step 2 tip
    and are NOT introduced by this commit.
  - sizeof envelope: bench_sizeof_http_resource.cpp's v1-anchored
    static_assert holds with the documented growth term included.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: etr

src/detail/webserver_dispatch.cpp

@@ -453,9 +453,15 @@ void webserver_impl::dispatch_resource_handler(detail::modded_request* mr,
             }
             return;
         }
-        // Method not allowed: serialize the allow-mask into a header.
+        // Method not allowed: emit the Allow header.  TASK-058 step 3:
+        // read the resource's lazily-cached Allow header value instead
+        // of rebuilding the string from the mask on every 405.  The
+        // cache lives on http_resource (the same object that owns the
+        // mask), regenerates implicitly when the mask differs from the
+        // last-cached snapshot, and is thread-safe under a per-resource
+        // mutex held only across the cache-fill path.
         mr->response.emplace(method_not_allowed_page(mr));
-        std::string header_value = serialize_allow_methods(hrm->get_allowed_methods());
+        const std::string& header_value = hrm->get_allow_header();
         if (!header_value.empty()) {
             mr->response->with_header(http_utils::http_header_allow, header_value);
         }

src/http_resource.cpp

@@ -32,6 +32,7 @@
 #include <string>
 #include <utility>
 
+#include "httpserver/detail/method_utils.hpp"
 #include "httpserver/detail/resource_hook_table.hpp"
 #include "httpserver/hook_action.hpp"
 #include "httpserver/hook_context.hpp"
@@ -97,6 +98,55 @@ ensure_table(std::shared_ptr<detail::resource_hook_table>& slot) {
 
 }  // namespace
 
+// ---- copy / move special members ----------------------------------------
+//
+// TASK-058 step 3 added std::mutex cached_allow_mutex_, which has no
+// copy or move.  The defaulted special members on the public class
+// declaration would therefore be implicitly deleted.  Implement them
+// here by-hand, skipping the mutex.  The copy / move target starts
+// with a fresh, default-constructed mutex and an invalidated Allow-
+// header cache (cached_allow_valid_ = false), which the next call to
+// get_allow_header() repopulates lazily.
+
+http_resource::http_resource(const http_resource& b) noexcept
+    : methods_allowed_(b.methods_allowed_),
+      hook_table_(b.hook_table_) {
+    // cached_allow_mutex_ default-constructs.
+    // cached_allow_header_ / cached_allow_mask_ default-construct.
+    // cached_allow_valid_ stays false (member default).
+}
+
+http_resource::http_resource(http_resource&& b) noexcept
+    : methods_allowed_(b.methods_allowed_),
+      hook_table_(std::move(b.hook_table_)) {
+    // Same rationale as the copy constructor: cache state is per-
+    // instance and is not transferred.  std::mutex has no move.
+}
+
+http_resource& http_resource::operator=(const http_resource& b) noexcept {
+    if (this != &b) {
+        hook_table_ = b.hook_table_;
+        methods_allowed_ = b.methods_allowed_;
+        // Invalidate the local cache; do NOT touch the mutex (still
+        // owned by *this).
+        std::lock_guard<std::mutex> lock(cached_allow_mutex_);
+        cached_allow_valid_ = false;
+        cached_allow_header_.clear();
+    }
+    return *this;
+}
+
+http_resource& http_resource::operator=(http_resource&& b) noexcept {
+    if (this != &b) {
+        hook_table_ = std::move(b.hook_table_);
+        methods_allowed_ = b.methods_allowed_;
+        std::lock_guard<std::mutex> lock(cached_allow_mutex_);
+        cached_allow_valid_ = false;
+        cached_allow_header_.clear();
+    }
+    return *this;
+}
+
 // ---- add_hook overloads -------------------------------------------------
 
 hook_handle http_resource::add_hook(hook_phase phase,
@@ -149,4 +199,33 @@ hook_handle http_resource::add_hook(hook_phase phase,
                        hook_phase::request_completed, id};
 }
 
+// ---- get_allow_header ---------------------------------------------------
+//
+// TASK-058 step 3: lazy Allow-header cache.  See the header-side
+// declaration for the contract.  Implementation:
+//
+//   1. Snapshot the live mask once -- subsequent comparisons run against
+//      this local copy (avoids re-loading methods_allowed_ inside the
+//      critical section).
+//   2. Take the per-resource mutex.  Under contention this serialises
+//      cache-fill; under the warm-path (hit) case the lock is held for
+//      a single integer compare + reference return.
+//   3. If the cached snapshot matches the live mask, return the cached
+//      string by reference.  Otherwise rebuild via detail::format_allow_header
+//      (the same routine the pre-TASK-058 path used) and update the snapshot.
+//
+// The returned reference is stable until the next mask mutation; the
+// caller (dispatch_resource_handler) consumes it synchronously within
+// the current dispatch, so the reference outlives use.
+const std::string& http_resource::get_allow_header() const {
+    const method_set live = methods_allowed_;
+    std::lock_guard<std::mutex> lock(cached_allow_mutex_);
+    if (!cached_allow_valid_ || cached_allow_mask_ != live) {
+        cached_allow_header_ = detail::format_allow_header(live);
+        cached_allow_mask_ = live;
+        cached_allow_valid_ = true;
+    }
+    return cached_allow_header_;
+}
+
 }  // namespace httpserver

src/httpserver/http_resource.hpp

@@ -27,6 +27,8 @@
 
 #include <functional>
 #include <memory>
+#include <mutex>
+#include <string>
 
 // TASK-036: render_* virtuals now return http_response by value; the
 // inline defaults call render(req) and forward the prvalue, which
@@ -219,6 +221,33 @@ class http_resource {
          return methods_allowed_;
      }
 
+     /**
+      * @brief Return the cached comma-separated Allow header value for
+      * the current methods_allowed_ mask.
+      *
+      * TASK-058 step 3.  The 405 dispatch path reads this on every
+      * method-not-allowed response; pre-TASK-058 the value was rebuilt
+      * (heap-allocating) on every call via
+      * detail::format_allow_header().  This getter caches the result
+      * lazily and regenerates only when the mask differs from the
+      * snapshot taken at cache-fill time -- so set_allowing,
+      * disallow_all, and allow_all all invalidate the cache implicitly,
+      * without any explicit dependency on the mutation API.
+      *
+      * Thread-safe: a per-resource std::mutex serialises the cache
+      * fill / read.  Once the cache is warm, the lock is uncontended
+      * on every subsequent call.
+      *
+      * The returned reference is valid until the next mask mutation;
+      * callers must not store it beyond a single dispatch invocation.
+      *
+      * @return reference to the cached Allow-header string.  Empty
+      *         string iff methods_allowed_ is empty (no methods
+      *         allowed -- in which case there is no Allow header to
+      *         emit at all).
+      */
+     const std::string& get_allow_header() const;
+
      /**
       * @brief Register a per-resource hook on one of the five
       * post-route-resolution phases.
@@ -277,11 +306,21 @@ class http_resource {
       * the same per-route hook table as the original. Hooks registered on
       * the original will also fire for the copy. If independent hook tables
       * are needed, register hooks on the copy separately after construction.
+      *
+      * TASK-058 step 3: cached_allow_mutex_ is non-copyable / non-movable
+      * (std::mutex has no copy or move).  The copy / move special members
+      * are therefore written by hand and skip the mutex member entirely --
+      * the copy / move target gets a freshly default-constructed mutex
+      * and an invalidated cache (cached_allow_valid_ = false), so the
+      * next get_allow_header() call on the target rebuilds the cache
+      * under its own (fresh) lock.  This is the correct semantic: copy /
+      * move is a structural operation; cache state is local to each
+      * instance and must not be shared by reference.
      **/
-     http_resource(const http_resource& b) = default;
-     http_resource(http_resource&& b) noexcept = default;
-     http_resource& operator=(const http_resource& b) = default;
-     http_resource& operator=(http_resource&& b) = default;
+     http_resource(const http_resource& b) noexcept;
+     http_resource(http_resource&& b) noexcept;
+     http_resource& operator=(const http_resource& b) noexcept;
+     http_resource& operator=(http_resource&& b) noexcept;
 
  private:
      friend class webserver;
@@ -305,6 +344,35 @@ class http_resource {
      // only reads the table; only the public add_hook(non-const) writes).
      mutable std::shared_ptr<detail::resource_hook_table> hook_table_;
 
+     // TASK-058 step 3: lazy cache of the formatted Allow header value
+     // for the 405 dispatch path.  Built on first call to
+     // get_allow_header(); reused on subsequent calls as long as the
+     // resource's methods_allowed_ mask is unchanged.  Mask changes
+     // (set_allowing / disallow_all / allow_all) are detected implicitly
+     // by comparing the live mask against the snapshot taken when the
+     // cache was last filled -- the cache regenerates on next read
+     // without any explicit invalidation hook.  This sidesteps the
+     // maintenance trap of chasing every mutation site.
+     //
+     // The cost of the comparison (a single 32-bit equality test on
+     // method_set::bits) is dwarfed by the avoided heap allocation
+     // inside format_allow_header(), which reserves a 64-byte string and
+     // appends method tokens on every 405 dispatch pre-cache.
+     //
+     // Thread-safety: the dispatch path can call get_allow_header()
+     // concurrently from multiple MHD worker threads against the same
+     // resource.  The mutex serialises the cache fill / read; once the
+     // cache is warm, the lock is uncontended on every subsequent 405.
+     //
+     // `mutable` for the same reason as hook_table_: the dispatch path
+     // calls get_allow_header() on a `const http_resource&` (the cache
+     // is logically const-observable -- the visible result is a stable
+     // function of methods_allowed_).
+     mutable std::mutex cached_allow_mutex_;
+     mutable std::string cached_allow_header_;
+     mutable method_set cached_allow_mask_{};
+     mutable bool cached_allow_valid_ = false;
+
 // Internal-only accessor: only visible to translation units that define
 // HTTPSERVER_COMPILATION (i.e., the library's own .cpp files). User-facing
 // translation units that include <httpserver.hpp> see only the public
@@ -329,12 +397,23 @@ class http_resource {
 // Ensure http_resource stays small enough for stack allocation in hot paths.
 // Originally vptr + uint32_t method_set + padding; the per-resource hook
 // table PIMPL (shared_ptr<resource_hook_table>) was added later, growing the
-// cap to vptr + shared_ptr + method_set + padding. The v1 std::map-based
-// allow-list was much larger; this bound documents intentional, measured growth.
+// cap to vptr + shared_ptr + method_set + padding.
+//
+// TASK-058 step 3 added a lazy Allow-header cache: std::mutex +
+// std::string + method_set + bool.  std::mutex is a sizeof~64 storage on
+// pthread platforms (libc++/macOS) and ~40 on libstdc++/Linux; std::string
+// SBO adds ~24-32; the method_set / bool fields slot into existing padding.
+// The new ceiling is the old (3*void* + 2*method_set) plus the new cache
+// payload, padded for alignment.  See test/bench_sizeof_http_resource.cpp
+// for the v1-anchored algebra; the value here documents the
+// post-TASK-058 layout shape.
 static_assert(sizeof(http_resource) <=
-                  sizeof(void*) * 3 + sizeof(method_set) * 2,
+                  sizeof(void*) * 3 + sizeof(method_set) * 2
+                  + sizeof(std::mutex) + sizeof(std::string)
+                  + sizeof(method_set) + sizeof(bool) * 8,
               "http_resource should be approximately vptr + shared_ptr + "
-              "method_set after TASK-051");
+              "method_set (TASK-051) + Allow-header cache "
+              "(mutex + string + method_set + bool) after TASK-058 step 3");
 
 }  // namespace httpserver
 #endif  // SRC_HTTPSERVER_HTTP_RESOURCE_HPP_

test/Makefile.am

@@ -26,7 +26,7 @@ LDADD += -lcurl
 
 AM_CPPFLAGS = -I$(top_srcdir)/src -I$(top_srcdir)/src/httpserver/ -DHTTPSERVER_COMPILATION
 METASOURCES = AUTO
-check_PROGRAMS = basic file_upload http_utils threaded nodelay string_utilities http_endpoint ban_system ws_start_stop authentication deferred http_resource http_response create_webserver create_webserver_explicit new_response_types daemon_info uri_log feature_unavailable header_hygiene_iovec header_hygiene iovec_entry http_method constants body http_response_sbo http_response_factories http_response_move_sanitizer webserver_pimpl http_request_pimpl create_test_request http_request_arena http_request_const_getters http_request_tls_accessors http_request_operator_stream webserver_register_smartptr webserver_register_path_prefix webserver_on_methods webserver_route route_table lookup_pipeline route_table_concurrency routing_regression route_lookup_canonicalize auth_skip_normalize v2_dispatch_contract threadsafety_stress webserver_features webserver_ws_unavailable webserver_register_ws_smartptr webserver_dauth_unavailable consumer_fixture header_hygiene_hooks hook_api_shape hooks_no_firing hooks_accept_ctx_shape hooks_connection_lifecycle hooks_accept_decision_banned hooks_accept_decision_throwing hooks_body_chunk_ctx_shape hooks_request_received_short_circuit hooks_body_chunk_observes_progress hooks_body_chunk_short_circuit_no_leak hooks_before_handler_ctx_shape hooks_route_resolved_miss_and_hit hooks_before_handler_short_circuit hooks_alias_count hooks_alias_functional hooks_handler_exception_chain hooks_handler_exception_user_handler_throws_continues_chain hooks_handler_exception_fallback_to_hardcoded_500 hooks_handler_exception_slot hooks_response_sent_ctx_shape hooks_request_completed_ctx_shape hooks_after_handler_replaces_response hooks_after_handler_mutates_response_in_place hooks_response_sent_carries_status_bytes_timing hooks_request_completed_fires_on_early_failure hooks_log_access_alias_slot hooks_per_route_invalid_phase_throws hooks_per_route_order hooks_per_route_early_413_per_endpoint hooks_per_route_resource_destroyed_first hooks_per_route_concurrent_registration auth_handler_optional_signature auth_handler_legacy_shim
+check_PROGRAMS = basic file_upload http_utils threaded nodelay string_utilities http_endpoint ban_system ws_start_stop authentication deferred http_resource http_response create_webserver create_webserver_explicit new_response_types daemon_info uri_log feature_unavailable header_hygiene_iovec header_hygiene iovec_entry http_method constants body http_response_sbo http_response_factories http_response_move_sanitizer webserver_pimpl http_request_pimpl create_test_request http_request_arena http_request_const_getters http_request_tls_accessors http_request_operator_stream webserver_register_smartptr webserver_register_path_prefix webserver_on_methods webserver_route route_table lookup_pipeline route_table_concurrency routing_regression route_lookup_canonicalize auth_skip_normalize http_resource_allow_cache v2_dispatch_contract threadsafety_stress webserver_features webserver_ws_unavailable webserver_register_ws_smartptr webserver_dauth_unavailable consumer_fixture header_hygiene_hooks hook_api_shape hooks_no_firing hooks_accept_ctx_shape hooks_connection_lifecycle hooks_accept_decision_banned hooks_accept_decision_throwing hooks_body_chunk_ctx_shape hooks_request_received_short_circuit hooks_body_chunk_observes_progress hooks_body_chunk_short_circuit_no_leak hooks_before_handler_ctx_shape hooks_route_resolved_miss_and_hit hooks_before_handler_short_circuit hooks_alias_count hooks_alias_functional hooks_handler_exception_chain hooks_handler_exception_user_handler_throws_continues_chain hooks_handler_exception_fallback_to_hardcoded_500 hooks_handler_exception_slot hooks_response_sent_ctx_shape hooks_request_completed_ctx_shape hooks_after_handler_replaces_response hooks_after_handler_mutates_response_in_place hooks_response_sent_carries_status_bytes_timing hooks_request_completed_fires_on_early_failure hooks_log_access_alias_slot hooks_per_route_invalid_phase_throws hooks_per_route_order hooks_per_route_early_413_per_endpoint hooks_per_route_resource_destroyed_first hooks_per_route_concurrent_registration auth_handler_optional_signature auth_handler_legacy_shim
 
 MOSTLYCLEANFILES = *.gcda *.gcno *.gcov
 
@@ -299,6 +299,14 @@ route_lookup_canonicalize_LDADD = $(LDADD) -lmicrohttpd
 auth_skip_normalize_SOURCES = unit/auth_skip_normalize_test.cpp
 auth_skip_normalize_LDADD = $(LDADD) -lmicrohttpd
 
+# http_resource_allow_cache (TASK-058 step 3): pins the lazy Allow-
+# header cache on http_resource -- correctness (cached value matches
+# format_allow_header; mask mutation invalidates), identity (two
+# consecutive calls return the same buffer pointer, no reallocation),
+# and the invalidation surface (set_allowing / disallow_all / allow_all).
+http_resource_allow_cache_SOURCES = unit/http_resource_allow_cache_test.cpp
+http_resource_allow_cache_LDADD = $(LDADD) -lmicrohttpd
+
 # v2_dispatch_contract: TASK-053. End-to-end safety net pinning the
 # observable invariants the dispatch path must satisfy AFTER finalize_answer
 # is cut over from resolve_resource_for_request (v1 maps) to