Merge TASK-011: http_response const-correct accessors

Author: etr

specs/tasks/M2-response/TASK-011.md

@@ -8,13 +8,13 @@
 Make read accessors callable on `const http_response&`, returning views without inserting on miss.
 
 **Action Items:**
-- [ ] `std::string_view get_header(std::string_view key) const;` returns empty view on miss; does NOT insert.
-- [ ] Same for `get_footer(std::string_view) const;` and `get_cookie(std::string_view) const;`.
-- [ ] `const header_map& get_headers() const noexcept;` (and `get_footers`, `get_cookies`).
-- [ ] `int get_status() const noexcept;`
-- [ ] `body_kind kind() const noexcept;`
-- [ ] Remove any v1 accessor that inserted on miss (e.g., `headers[key]` patterns).
-- [ ] Audit `string_view` returns: the storage must outlive the view. Document lifetime contract on each accessor (views invalidated by mutation of the response, e.g., `with_header` may rehash the map).
+- [x] `std::string_view get_header(std::string_view key) const;` returns empty view on miss; does NOT insert.
+- [x] Same for `get_footer(std::string_view) const;` and `get_cookie(std::string_view) const;`.
+- [x] `const header_map& get_headers() const noexcept;` (and `get_footers`, `get_cookies`).
+- [x] `int get_status() const noexcept;`
+- [x] `body_kind kind() const noexcept;`
+- [x] Remove any v1 accessor that inserted on miss (e.g., `headers[key]` patterns).
+- [x] Audit `string_view` returns: the storage must outlive the view. Document lifetime contract on each accessor (views invalidated by mutation of the response, e.g., `with_header` may rehash the map).
 
 **Dependencies:**
 - Blocked by: TASK-009
@@ -30,4 +30,4 @@ Make read accessors callable on `const http_response&`, returning views without
 **Related Requirements:** PRD-RSP-REQ-002, PRD-RSP-REQ-003
 **Related Decisions:** §2.2 (const correctness), §4.3
 
-**Status:** Not Started
+**Status:** Done

specs/tasks/_index.md

@@ -93,7 +93,7 @@ Nominally: **13 sequential tasks**, each S–XL. Most other tasks parallelize of
 | TASK-008 | Internal `detail::body` hierarchy | M2 | Done | TASK-002 |
 | TASK-009 | `http_response` value type with SBO buffer | M2 | Done | TASK-008 |
 | TASK-010 | `http_response` factory functions | M2 | Done | TASK-008, TASK-009, TASK-004 |
-| TASK-011 | `http_response` const-correct accessors | M2 | Not Started | TASK-009 |
+| TASK-011 | `http_response` const-correct accessors | M2 | Done | TASK-009 |
 | TASK-012 | `http_response` fluent `with_*` setters | M2 | Not Started | TASK-009 |
 | TASK-013 | Remove `*_response` subclasses and dispatch virtuals | M2 | Not Started | TASK-009, TASK-010, TASK-011, TASK-012 |
 | TASK-014 | `webserver_impl` skeleton (PIMPL prep) | M3 | Not Started | TASK-002 |

specs/unworked_review_issues/2026-05-03_211000_task-011.md

@@ -0,0 +1,7 @@
+# Unworked Review Issues
+
+**Run:** 2026-05-03 21:10:00
+**Task:** TASK-011
+**Total:** 0 (0 critical, 0 major, 0 minor)
+
+No unworked findings. All critical and major findings (task status Not Started → Done, seven action-item checkboxes) were resolved in the housekeeping pass.

specs/unworked_review_issues/2026-05-03_213725_task-011.md

@@ -189,6 +189,39 @@ void http_response::shoutCAST() {
     status_code_ |= http::http_utils::shoutcast_response;
 }
 
+// -----------------------------------------------------------------------
+// Const single-key accessors (TASK-011).
+//
+// All three share the same shape: heterogeneous lookup into the
+// corresponding header_map (transparent header_comparator), returning an
+// empty std::string_view on miss. NEVER inserts (PRD-RSP-REQ-003); the
+// previous v1 accessors used `headers_[key]`, which silently inserted
+// an empty entry on miss and consequently could not be const.
+//
+// View lifetime is documented in the class-level contract block in
+// http_response.hpp.
+// -----------------------------------------------------------------------
+namespace {
+inline std::string_view header_map_find_view(const http::header_map& m,
+                                             std::string_view key) {
+    auto it = m.find(key);
+    if (it == m.end()) return {};
+    return std::string_view(it->second);
+}
+}  // namespace
+
+std::string_view http_response::get_header(std::string_view key) const {
+    return header_map_find_view(headers_, key);
+}
+
+std::string_view http_response::get_footer(std::string_view key) const {
+    return header_map_find_view(footers_, key);
+}
+
+std::string_view http_response::get_cookie(std::string_view key) const {
+    return header_map_find_view(cookies_, key);
+}
+
 namespace {
 static inline http::header_view_map to_view_map(const http::header_map& hdr_map) {
     http::header_view_map view_map;

src/http_response.cpp

@@ -183,53 +183,87 @@ class http_response {
          std::string_view realm,
          std::string body = {});
 
-     /**
-      * Method used to get a specified header defined for the response
-      * @param key The header identification
-      * @return a string representing the value assumed by the header
-     **/
-     const std::string& get_header(const std::string& key) {
-         return headers_[key];
-     }
+     // -----------------------------------------------------------------
+     // Read accessors (TASK-011, PRD-RSP-REQ-002 / PRD-RSP-REQ-003).
+     //
+     // Lifetime contract for the string_view-returning accessors:
+     //
+     // The returned view points into storage owned by *this. The view is
+     // valid until ANY of the following happen:
+     //   1. *this is destroyed.
+     //   2. *this is moved-from (move ctor / move-assign target).
+     //   3. The corresponding map is mutated for the SAME key
+     //      (with_header(key, ...) replacing an existing value
+     //      invalidates a view obtained from a prior get_header(key)).
+     //
+     // std::map's node-stability guarantee means that adding or removing
+     // OTHER keys does NOT invalidate views of unrelated keys; only
+     // same-key re-assignment, erase, or whole-response destruction
+     // does. Multi-value headers are not modelled in v2.0 — header_map
+     // is single-valued per key.
+     //
+     // Callers MUST NOT keep the view past the next non-const operation
+     // on the response, and MUST NOT keep it past the response's
+     // destruction. If a longer lifetime is required, copy into a
+     // std::string.
+     //
+     // No noexcept on the single-key accessors: std::map::find can in
+     // principle propagate a comparator exception. The map-returning
+     // accessors and the trivial scalar accessors (get_status, kind) are
+     // noexcept (they only return a reference / scalar member).
+     // -----------------------------------------------------------------
 
-     /**
-      * Method used to get a specified footer defined for the response
-      * @param key The footer identification
-      * @return a string representing the value assumed by the footer
-     **/
-     const std::string& get_footer(const std::string& key) {
-         return footers_[key];
-     }
+     /// Returns the value of header `key`, or an empty view if absent.
+     /// Does NOT insert on miss (PRD-RSP-REQ-003).
+     /// View lifetime: see lifetime contract above.
+     [[nodiscard]] std::string_view get_header(std::string_view key) const;
 
-     const std::string& get_cookie(const std::string& key) {
-         return cookies_[key];
-     }
+     /// Returns the value of footer `key`, or an empty view if absent.
+     /// Does NOT insert on miss. View lifetime: see lifetime contract.
+     [[nodiscard]] std::string_view get_footer(std::string_view key) const;
+
+     /// Returns the value of cookie `key`, or an empty view if absent.
+     /// Does NOT insert on miss. View lifetime: see lifetime contract.
+     [[nodiscard]] std::string_view get_cookie(std::string_view key) const;
 
      /**
       * Method used to get all headers passed with the request.
       * @return a map<string,string> containing all headers.
      **/
-     const std::map<std::string, std::string, http::header_comparator>& get_headers() const {
+     [[nodiscard]] const http::header_map& get_headers() const noexcept {
          return headers_;
      }
 
      /**
       * Method used to get all footers passed with the request.
       * @return a map<string,string> containing all footers.
      **/
-     const std::map<std::string, std::string, http::header_comparator>& get_footers() const {
+     [[nodiscard]] const http::header_map& get_footers() const noexcept {
          return footers_;
      }
 
-     const std::map<std::string, std::string, http::header_comparator>& get_cookies() const {
+     [[nodiscard]] const http::header_map& get_cookies() const noexcept {
          return cookies_;
      }
 
      /**
-      * Method used to get the response code from the response
+      * Method used to get the response status code.
+      * Spelled `get_status` to match the v2 vocabulary (TASK-011);
+      * `get_response_code` survives as a compatibility alias while the
+      * v1 subclass hierarchy still inherits from http_response
+      * (TASK-013 removes both the subclasses and the alias together
+      * with the dispatch path in webserver.cpp:1336).
       * @return The response code
      **/
-     int get_response_code() const {
+     [[nodiscard]] int get_status() const noexcept {
+         return status_code_;
+     }
+
+     // Compatibility shim retained while v1 subclasses still inherit
+     // (TASK-013 removes them). Internal dispatch (webserver.cpp:1336)
+     // reaches through a base pointer; that call site flips to
+     // get_status() when TASK-013 lands.
+     [[nodiscard]] int get_response_code() const noexcept {
          return status_code_;
      }
 

src/httpserver/http_response.hpp

@@ -312,6 +312,12 @@ class http_utils {
 
 class header_comparator {
  public:
+     // is_transparent enables heterogeneous lookup against header_map
+     // (std::map<std::string, std::string, header_comparator>): callers
+     // can pass std::string_view directly to find()/count() without
+     // constructing a std::string. Required by TASK-011's
+     // string_view-returning const accessors on http_response.
+     using is_transparent = std::true_type;
      /**
       * Operator used to compare strings.
       * @param first string

src/httpserver/http_utils.hpp

@@ -2472,9 +2472,14 @@ class response_footer_resource : public http_resource {
         response->with_footer("X-Checksum", "abc123");
         response->with_footer("X-Processing-Time", "42ms");
 
-        // Test get_footer and get_footers on response
+        // Test get_footer and get_footers on response. The returned
+        // string_view points into the response's storage; we only
+        // read it before returning so the response (and thus the
+        // backing string) outlives any read.
         auto checksum = response->get_footer("X-Checksum");
         auto all_footers = response->get_footers();
+        (void)checksum;
+        (void)all_footers;
 
         return response;
     }