TASK-012: http_response fluent with_* setters

Replace the void-returning v1 with_header/with_footer/with_cookie
methods with ref-qualified overload pairs that return http_response&
(for lvalue chains) and http_response&& (for factory rvalue chains),
and add a matching with_status(int) setter that did not exist before.
This unblocks the AC chain

    auto r = http_response::string("hi")
                 .with_header("X-Foo", "bar")
                 .with_status(201);

end-to-end while preserving SBO inline placement (no intermediate
move-construction). String parameters are taken by value and
forwarded into the underlying header_map via insert_or_assign so an
rvalue caller pays no extra allocation.

Cookie API decision (action item #4): keep the v1 (name, value)
string-pair shape; structured cookie type with first-class
attribute fields is intentionally deferred to a follow-up task and
can be added as a non-breaking overload alongside the existing API.
Documented on the with_cookie Doxygen.

Backward compatibility is preserved: all ~30 existing statement-form
call sites in test/unit/http_response_test.cpp, examples/, and
src/webserver.cpp:1348 keep compiling unchanged because the new
return type is a non-[[nodiscard]] reference.

Tests: 9 new tests in http_response_test.cpp pin the contract
(factory chain, lvalue chain identity, ref-qualifier dispatch via
static_assert, statement-form regression, with_status round-trip
and composition-safety, observable mutation through returned ref,
move-friendly by-value parameters). One additional test in
http_response_factories_test.cpp asserts the SBO-inline invariant
through the http_response_sbo_test_access friend struct. Full
testsuite: 27 entries, 26 PASS + 1 XFAIL (header_hygiene, expected
until M5), under both release and --enable-debug -Werror builds.

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

Author: etr

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

@@ -8,11 +8,11 @@
 Make `with_header` / `with_footer` / `with_cookie` / `with_status` return `http_response&` so factory chains work.
 
 **Action Items:**
-- [ ] `http_response& with_header(std::string key, std::string value) &;`
-- [ ] `http_response&& with_header(std::string key, std::string value) &&;` (rvalue overload to keep `http_response::string("hi").with_header(...)` zero-copy).
-- [ ] Same pattern for `with_footer`, `with_cookie`, `with_status(int code)`.
-- [ ] Cookie API takes a structured cookie type (name, value, attrs) or string-as-Set-Cookie; pick one and document.
-- [ ] Update v1 callers: `r.with_header(...)` chains now compile; previous `void`-returning calls still work (statement form is fine) but enable the fluent style.
+- [x] `http_response& with_header(std::string key, std::string value) &;`
+- [x] `http_response&& with_header(std::string key, std::string value) &&;` (rvalue overload to keep `http_response::string("hi").with_header(...)` zero-copy).
+- [x] Same pattern for `with_footer`, `with_cookie`, `with_status(int code)`.
+- [x] Cookie API takes a structured cookie type (name, value, attrs) or string-as-Set-Cookie; pick one and document. (Decision: keep v1 string-pair `(name, value)`; structured cookie type deferred to a follow-up task. Documented on `with_cookie` Doxygen.)
+- [x] Update v1 callers: `r.with_header(...)` chains now compile; previous `void`-returning calls still work (statement form is fine) but enable the fluent style.
 
 **Dependencies:**
 - Blocked by: TASK-009
@@ -26,4 +26,4 @@ Make `with_header` / `with_footer` / `with_cookie` / `with_status` return `http_
 **Related Requirements:** PRD-RSP-REQ-004
 **Related Decisions:** §4.3
 
-**Status:** Not Started
+**Status:** Done

specs/tasks/_index.md

@@ -94,7 +94,7 @@ Nominally: **13 sequential tasks**, each S–XL. Most other tasks parallelize of
 | 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 | Done | TASK-009 |
-| TASK-012 | `http_response` fluent `with_*` setters | M2 | Not Started | TASK-009 |
+| TASK-012 | `http_response` fluent `with_*` setters | M2 | Done | 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 |
 | TASK-015 | `http_request_impl` skeleton (PIMPL split) | M3 | Not Started | TASK-002, TASK-014 |

src/http_response.cpp

@@ -189,6 +189,59 @@ void http_response::shoutCAST() {
     status_code_ |= http::http_utils::shoutcast_response;
 }
 
+// -----------------------------------------------------------------------
+// Fluent with_* setters (TASK-012, PRD-RSP-REQ-004).
+//
+// Each setter has two ref-qualified overloads. The bodies are a one-line
+// mutation (insert_or_assign for the maps, plain assignment for status),
+// followed by `return *this` (& overload) or `return std::move(*this)`
+// (&& overload). insert_or_assign — rather than `m[k] = v` — is used so
+// the by-value `std::string` parameters can be moved into the map slot
+// directly, avoiding an extra string copy at the insertion site when
+// the caller hands the setter an rvalue.
+// -----------------------------------------------------------------------
+http_response& http_response::with_header(std::string key,
+                                          std::string value) & {
+    headers_.insert_or_assign(std::move(key), std::move(value));
+    return *this;
+}
+http_response&& http_response::with_header(std::string key,
+                                           std::string value) && {
+    headers_.insert_or_assign(std::move(key), std::move(value));
+    return std::move(*this);
+}
+
+http_response& http_response::with_footer(std::string key,
+                                          std::string value) & {
+    footers_.insert_or_assign(std::move(key), std::move(value));
+    return *this;
+}
+http_response&& http_response::with_footer(std::string key,
+                                           std::string value) && {
+    footers_.insert_or_assign(std::move(key), std::move(value));
+    return std::move(*this);
+}
+
+http_response& http_response::with_cookie(std::string key,
+                                          std::string value) & {
+    cookies_.insert_or_assign(std::move(key), std::move(value));
+    return *this;
+}
+http_response&& http_response::with_cookie(std::string key,
+                                           std::string value) && {
+    cookies_.insert_or_assign(std::move(key), std::move(value));
+    return std::move(*this);
+}
+
+http_response& http_response::with_status(int code) & {
+    status_code_ = code;
+    return *this;
+}
+http_response&& http_response::with_status(int code) && {
+    status_code_ = code;
+    return std::move(*this);
+}
+
 // -----------------------------------------------------------------------
 // Const single-key accessors (TASK-011).
 //

src/httpserver/http_response.hpp

@@ -267,17 +267,60 @@ class http_response {
          return status_code_;
      }
 
-     void with_header(const std::string& key, const std::string& value) {
-         headers_[key] = value;
-     }
-
-     void with_footer(const std::string& key, const std::string& value) {
-         footers_[key] = value;
-     }
-
-     void with_cookie(const std::string& key, const std::string& value) {
-         cookies_[key] = value;
-     }
+     // ------------------------------------------------------------------
+     // Fluent setters (TASK-012, PRD-RSP-REQ-004).
+     //
+     // Each setter is overloaded on the value-category of *this so that
+     // both lvalue and rvalue (factory) chains keep the response live
+     // and zero-copy:
+     //
+     //   * The `&` overload returns http_response& so that
+     //         r.with_header(k, v).with_status(s);
+     //     compiles and returns *this when `r` is an lvalue.
+     //   * The `&&` overload returns http_response&& so that
+     //         http_response::string("hi").with_header(...).with_status(...)
+     //     keeps the temporary as an rvalue end-to-end; the chain calls
+     //     successive `&&` overloads on the same SBO-inline body without
+     //     any intermediate move-construction or heap relocation.
+     //
+     // String parameters are taken by value: the body internally moves
+     // them into the underlying header/footer/cookie maps via
+     // insert_or_assign, so callers can either copy or move into the
+     // setter without an extra allocation.
+     //
+     // Backward compatibility (constraint): pre-TASK-012 callers wrote
+     //         r.with_header(k, v);
+     // in statement form, discarding the (then `void`) return. Switching
+     // the return type to a non-`[[nodiscard]]` reference is strictly
+     // source-compatible — the reference is silently ignored.
+     //
+     // Cookie API decision (action item #4 of TASK-012): the v2.0 cookie
+     // surface is the v1 (name, value) string-pair shape. `with_cookie`
+     // overwrites any prior entry for `name` (the cookie map is keyed
+     // case-insensitively). The value is rendered verbatim into the
+     // `Set-Cookie` header by decorate_response, so callers who need
+     // attributes (Path, Secure, HttpOnly, SameSite, ...) pre-format the
+     // value, e.g. with_cookie("sid", "abc; Path=/; Secure; HttpOnly").
+     // A structured cookie type with first-class attribute fields is
+     // intentionally deferred to a follow-up task; it can be added as a
+     // non-breaking overload alongside this string-pair API.
+     //
+     // Note on with_status: status replaces the stored code outright,
+     // including any flag bits set by shoutCAST() (which ORs
+     // MHD_ICY_FLAG into status_code_). Callers wanting both write
+     // with_status(...) first and shoutCAST() second.
+     // ------------------------------------------------------------------
+     http_response& with_header(std::string key, std::string value) &;
+     http_response&& with_header(std::string key, std::string value) &&;
+
+     http_response& with_footer(std::string key, std::string value) &;
+     http_response&& with_footer(std::string key, std::string value) &&;
+
+     http_response& with_cookie(std::string key, std::string value) &;
+     http_response&& with_cookie(std::string key, std::string value) &&;
+
+     http_response& with_status(int code) &;
+     http_response&& with_status(int code) &&;
 
      void shoutCAST();
 

test/unit/http_response_factories_test.cpp

@@ -440,6 +440,24 @@ LT_BEGIN_AUTO_TEST(http_response_factories_suite,
     LT_CHECK_EQ(other.get_response_code(), 200);
 LT_END_AUTO_TEST(factory_move_preserves_kind_and_headers)
 
+// -----------------------------------------------------------------------
+// TASK-012 zero-copy invariant: chained with_* calls on a factory's
+// rvalue must not perturb the SBO placement. http_response::string(...)
+// places a string_body inline in the SBO buffer; the && overloads of
+// with_header / with_status return http_response&& (i.e. propagate the
+// xvalue without an intermediate copy/move-construct), so the body
+// pointer must remain inline through the chain.
+// -----------------------------------------------------------------------
+LT_BEGIN_AUTO_TEST(http_response_factories_suite,
+                   factory_chain_keeps_body_inline_in_sbo)
+    auto r = http_response::string("hi")
+                 .with_header("X-Foo", "bar")
+                 .with_status(201);
+    LT_CHECK_EQ(SBO::body_inline(r), true);
+    LT_CHECK_EQ(static_cast<int>(SBO::kind(r)),
+                static_cast<int>(body_kind::string));
+LT_END_AUTO_TEST(factory_chain_keeps_body_inline_in_sbo)
+
 LT_BEGIN_AUTO_TEST_ENV()
     AUTORUN_TESTS()
 LT_END_AUTO_TEST_ENV()

test/unit/http_response_test.cpp

@@ -22,6 +22,7 @@
 #include <string>
 #include <string_view>
 #include <type_traits>
+#include <utility>
 
 #include "./littletest.hpp"
 #include "./httpserver.hpp"
@@ -468,6 +469,138 @@ LT_BEGIN_AUTO_TEST(http_response_suite, get_header_view_reflects_replacement)
     LT_CHECK_EQ(resp.get_header("K"), std::string_view("v2"));
 LT_END_AUTO_TEST(get_header_view_reflects_replacement)
 
+// -----------------------------------------------------------------------
+// TASK-012: fluent with_* setters return http_response& / http_response&&
+// (PRD-RSP-REQ-004). Tests below pin the new contract:
+//   * the AC chain compiles end-to-end (factory_chain_compiles_and_works);
+//   * lvalue chains return identity (lvalue_chain_returns_lvalue_ref);
+//   * ref-qualifier dispatch is exact at the type level
+//     (with_setters_return_types_are_ref_qualified);
+//   * statement-form pre-TASK-012 callers still compile unchanged
+//     (statement_form_with_setters_still_compile);
+//   * with_status round-trips and is composition-safe
+//     (with_status_changes_status_code, with_status_preserves_body_and_headers);
+//   * mutation is observable through the returned reference
+//     (mutation_observable_through_returned_ref);
+//   * by-value string parameters are move-friendly (with_header_moves_string_args).
+// The SBO-inline / zero-copy invariant for the rvalue chain is verified
+// in test/unit/http_response_factories_test.cpp where the SBO friend
+// struct is already defined.
+// -----------------------------------------------------------------------
+
+LT_BEGIN_AUTO_TEST(http_response_suite, factory_chain_compiles_and_works)
+    auto r = http_response::string("hi")
+                 .with_header("X-Foo", "bar")
+                 .with_status(201);
+    LT_CHECK_EQ(r.get_status(), 201);
+    LT_CHECK_EQ(r.get_header("X-Foo"), std::string_view("bar"));
+    LT_CHECK_EQ(r.get_header("Content-Type"), std::string_view("text/plain"));
+    LT_CHECK_EQ(static_cast<int>(r.kind()),
+                static_cast<int>(httpserver::body_kind::string));
+LT_END_AUTO_TEST(factory_chain_compiles_and_works)
+
+LT_BEGIN_AUTO_TEST(http_response_suite, lvalue_chain_returns_lvalue_ref)
+    http_response r = http_response::empty();
+    auto& ret = r.with_header("A", "1").with_footer("B", "2")
+                  .with_cookie("c", "3").with_status(202);
+    LT_CHECK_EQ(&ret, &r);  // Identity: returned ref must be *this.
+    LT_CHECK_EQ(r.get_header("A"), std::string_view("1"));
+    LT_CHECK_EQ(r.get_footer("B"), std::string_view("2"));
+    LT_CHECK_EQ(r.get_cookie("c"), std::string_view("3"));
+    LT_CHECK_EQ(r.get_status(), 202);
+LT_END_AUTO_TEST(lvalue_chain_returns_lvalue_ref)
+
+LT_BEGIN_AUTO_TEST(http_response_suite, with_setters_return_types_are_ref_qualified)
+    using R = httpserver::http_response;
+    // & overload returns R&
+    static_assert(std::is_same_v<
+        decltype(std::declval<R&>().with_header(std::string{}, std::string{})),
+        R&>, "with_header() & must return http_response&");
+    static_assert(std::is_same_v<
+        decltype(std::declval<R&>().with_footer(std::string{}, std::string{})),
+        R&>, "with_footer() & must return http_response&");
+    static_assert(std::is_same_v<
+        decltype(std::declval<R&>().with_cookie(std::string{}, std::string{})),
+        R&>, "with_cookie() & must return http_response&");
+    static_assert(std::is_same_v<
+        decltype(std::declval<R&>().with_status(0)),
+        R&>, "with_status() & must return http_response&");
+    // && overload returns R&&
+    static_assert(std::is_same_v<
+        decltype(std::declval<R&&>().with_header(std::string{}, std::string{})),
+        R&&>, "with_header() && must return http_response&&");
+    static_assert(std::is_same_v<
+        decltype(std::declval<R&&>().with_footer(std::string{}, std::string{})),
+        R&&>, "with_footer() && must return http_response&&");
+    static_assert(std::is_same_v<
+        decltype(std::declval<R&&>().with_cookie(std::string{}, std::string{})),
+        R&&>, "with_cookie() && must return http_response&&");
+    static_assert(std::is_same_v<
+        decltype(std::declval<R&&>().with_status(0)),
+        R&&>, "with_status() && must return http_response&&");
+    // Smoke runtime check so the suite still has at least one runtime
+    // assertion (a static_assert-only test would still pass if removed).
+    LT_CHECK_EQ(true, true);
+LT_END_AUTO_TEST(with_setters_return_types_are_ref_qualified)
+
+LT_BEGIN_AUTO_TEST(http_response_suite, statement_form_with_setters_still_compile)
+    // Backward-compat: pre-TASK-012 callers wrote `r.with_X(k, v);` in
+    // statement form, discarding the (then void) return. Switching to
+    // a reference return must keep this form compiling unchanged.
+    http_response resp = http_response::string("body");
+    resp.with_header("X-A", "1");
+    resp.with_footer("X-B", "2");
+    resp.with_cookie("c", "3");
+    resp.with_status(202);
+    LT_CHECK_EQ(resp.get_header("X-A"), std::string_view("1"));
+    LT_CHECK_EQ(resp.get_footer("X-B"), std::string_view("2"));
+    LT_CHECK_EQ(resp.get_cookie("c"), std::string_view("3"));
+    LT_CHECK_EQ(resp.get_status(), 202);
+LT_END_AUTO_TEST(statement_form_with_setters_still_compile)
+
+LT_BEGIN_AUTO_TEST(http_response_suite, with_status_changes_status_code)
+    http_response r = http_response::string("body");
+    LT_CHECK_EQ(r.get_status(), 200);  // factory default
+    r.with_status(404);
+    LT_CHECK_EQ(r.get_status(), 404);
+    r.with_status(500);
+    LT_CHECK_EQ(r.get_status(), 500);
+LT_END_AUTO_TEST(with_status_changes_status_code)
+
+LT_BEGIN_AUTO_TEST(http_response_suite, with_status_preserves_body_and_headers)
+    auto r = http_response::string("payload", "application/json")
+                 .with_header("X-K", "v")
+                 .with_status(418);
+    LT_CHECK_EQ(r.get_status(), 418);
+    LT_CHECK_EQ(r.get_header("Content-Type"),
+                std::string_view("application/json"));
+    LT_CHECK_EQ(r.get_header("X-K"), std::string_view("v"));
+    LT_CHECK_EQ(static_cast<int>(r.kind()),
+                static_cast<int>(httpserver::body_kind::string));
+LT_END_AUTO_TEST(with_status_preserves_body_and_headers)
+
+LT_BEGIN_AUTO_TEST(http_response_suite, mutation_observable_through_returned_ref)
+    http_response r = http_response::empty();
+    auto& ret = r.with_header("X-Trace", "a");
+    LT_CHECK_EQ(ret.get_header("X-Trace"), std::string_view("a"));
+    // And the rvalue chain leaves the result in the bound variable.
+    auto r2 = http_response::empty().with_header("X-Trace", "b");
+    LT_CHECK_EQ(r2.get_header("X-Trace"), std::string_view("b"));
+LT_END_AUTO_TEST(mutation_observable_through_returned_ref)
+
+LT_BEGIN_AUTO_TEST(http_response_suite, with_header_moves_string_args)
+    // By-value string parameters must accept rvalue inputs and forward
+    // them into the underlying map. We don't assert on the moved-from
+    // state of the source strings (the standard only guarantees "valid
+    // but unspecified") — only that the value lands in the map intact.
+    http_response r = http_response::empty();
+    std::string key = "X-Long-Header-Name-To-Avoid-SSO";
+    std::string value(64, 'v');  // > SSO threshold on libstdc++/libc++
+    r.with_header(std::move(key), std::move(value));
+    LT_CHECK_EQ(r.get_header("X-Long-Header-Name-To-Avoid-SSO"),
+                std::string_view(std::string(64, 'v')));
+LT_END_AUTO_TEST(with_header_moves_string_args)
+
 LT_BEGIN_AUTO_TEST_ENV()
     AUTORUN_TESTS()
 LT_END_AUTO_TEST_ENV()