TASK-010: http_response static factory functions

Adds the seven canonical factories on http_response (string, file, iovec,
pipe, empty, deferred, unauthorized) plus a public kind() accessor.

Each factory placement-news the corresponding detail::body subclass into
the SBO buffer through a single private emplace_body<T> helper, so the
matched ::operator new(sizeof(T)) / ::operator delete pairing the
destructor relies on (TASK-009 OQ-4) lives in exactly one place — a
stray plain `new T(...)` in any factory would mismatch and trip ASan.

Status-code defaults match v1: 200 for content-bearing bodies, 204 for
empty(), 401 for unauthorized(). The unauthorized() factory replaces v1's
basic_auth_fail_response and digest_auth_fail_response with a single
scheme-parameterised entry; the digest path emits a static
WWW-Authenticate challenge and does NOT participate in libmicrohttpd's
nonce/opaque state machine (documented contract gap).

Tests: 17 LT_BEGIN_AUTO_TESTs in test/unit/http_response_factories_test.cpp
exercise kind(), default and overridden Content-Type, file-missing
non-throw semantics, iovec span deep-copy, pipe fd ownership transfer
(destructor closes), deferred capture lifetime, and the AC-mandated
byte-for-byte WWW-Authenticate header. All 27 testsuite entries pass
locally with -j1; cpplint clean on the three changed files.

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

Author: etr

src/http_response.cpp

@@ -21,17 +21,25 @@
 #include "httpserver/http_response.hpp"
 
 #include <microhttpd.h>
+#include <sys/types.h>          // ssize_t (for the deferred() producer)
 
+#include <cassert>
 #include <cstddef>
+#include <cstdint>
+#include <functional>
 #include <iostream>
 #include <map>
 #include <new>
+#include <span>
 #include <string>
+#include <string_view>
 #include <type_traits>
 #include <utility>
+#include <vector>
 
 #include "httpserver/detail/body.hpp"   // complete type for body_->~body()
 #include "httpserver/http_utils.hpp"
+#include "httpserver/iovec_entry.hpp"
 
 namespace httpserver {
 
@@ -200,4 +208,132 @@ std::ostream &operator<< (std::ostream& os, const http_response& r) {
     return os;
 }
 
+// -----------------------------------------------------------------------
+// emplace_body — single placement-new entry point shared by all
+// factories (TASK-010). Centralising the SBO-vs-heap decision here means
+// the matched ::operator new(sizeof(T)) / ::operator delete pairing the
+// destructor relies on (TASK-009 OQ-4) lives in exactly one place; a
+// stray plain `new T(...)` in any factory would mismatch the
+// destructor's ::operator delete and trip ASan immediately.
+//
+// Defined out-of-line in this TU because every factory in this file
+// instantiates it (so no separate-TU instantiation is needed) and the
+// template body needs the complete type detail::body. Per-T size+align
+// guards duplicate the SBO budget asserts in detail/body.hpp so an
+// over-sized future body subclass fails to compile at the factory site
+// rather than silently triggering the heap fallback.
+// -----------------------------------------------------------------------
+template <typename T, typename... Args>
+void http_response::emplace_body(body_kind k, Args&&... args) {
+    static_assert(std::is_base_of_v<detail::body, T>,
+                  "emplace_body: T must derive from detail::body");
+    assert(body_ == nullptr &&
+           "emplace_body: body slot already populated");
+    if constexpr (sizeof(T) <= body_buf_size && alignof(T) <= 16) {
+        // SBO inline path.
+        body_ = ::new (body_storage_) T(std::forward<Args>(args)...);
+        body_inline_ = true;
+    } else {
+        // Heap fallback. ::operator new(sizeof(T)) is paired exactly
+        // with the destructor's ::operator delete(body_); a plain
+        // `new T(...)` here would mismatch.
+        void* mem = ::operator new(sizeof(T));
+        try {
+            body_ = ::new (mem) T(std::forward<Args>(args)...);
+        } catch (...) {
+            ::operator delete(mem);
+            throw;
+        }
+        body_inline_ = false;
+    }
+    kind_ = k;
+}
+
+// -----------------------------------------------------------------------
+// Static factories (TASK-010). Each factory:
+//   1. constructs a default http_response (status_code_ = -1, no body),
+//   2. sets the status code and any per-kind headers,
+//   3. emplaces the appropriate detail::body subclass via emplace_body.
+//
+// The status-code defaults match v1: 200 for content-bearing bodies,
+// 204 for empty(), 401 for unauthorized().
+// -----------------------------------------------------------------------
+
+http_response http_response::empty() {
+    http_response r;
+    r.status_code_ = http::http_utils::http_no_content;  // 204
+    r.emplace_body<detail::empty_body>(body_kind::empty);
+    return r;
+}
+
+http_response http_response::string(std::string body,
+                                    std::string content_type) {
+    http_response r;
+    r.status_code_ = http::http_utils::http_ok;          // 200
+    r.with_header(http::http_utils::http_header_content_type,
+                  std::move(content_type));
+    r.emplace_body<detail::string_body>(body_kind::string,
+                                        std::move(body));
+    return r;
+}
+
+http_response http_response::file(std::string path) {
+    http_response r;
+    r.status_code_ = http::http_utils::http_ok;
+    r.emplace_body<detail::file_body>(body_kind::file, std::move(path));
+    return r;
+}
+
+http_response http_response::iovec(std::span<const iovec_entry> entries) {
+    // Deep-copy into the body's owned vector so the caller's span need
+    // not outlive the response. The buffers each entry's `base` points
+    // at remain BORROWED — see detail::iovec_body's lifetime contract.
+    std::vector<iovec_entry> v(entries.begin(), entries.end());
+    http_response r;
+    r.status_code_ = http::http_utils::http_ok;
+    r.emplace_body<detail::iovec_body>(body_kind::iovec, std::move(v));
+    return r;
+}
+
+http_response http_response::pipe(int fd, std::size_t size_hint) {
+    (void)size_hint;  // reserved for future use
+    http_response r;
+    r.status_code_ = http::http_utils::http_ok;
+    r.emplace_body<detail::pipe_body>(body_kind::pipe, fd);
+    return r;
+}
+
+http_response http_response::deferred(
+        std::function<ssize_t(std::uint64_t, char*, std::size_t)> producer) {
+    http_response r;
+    r.status_code_ = http::http_utils::http_ok;
+    r.emplace_body<detail::deferred_body>(body_kind::deferred,
+                                          std::move(producer));
+    return r;
+}
+
+http_response http_response::unauthorized(std::string_view scheme,
+                                          std::string_view realm,
+                                          std::string body) {
+    http_response r;
+    r.status_code_ = http::http_utils::http_unauthorized;        // 401
+    // Build `<scheme> realm="<realm>"`. AC #3 requires byte-for-byte
+    // `Basic realm="myrealm"` for the canonical case.
+    std::string challenge;
+    challenge.reserve(scheme.size() + realm.size() + 10);
+    challenge.append(scheme.data(), scheme.size());
+    challenge.append(" realm=\"", 8);
+    challenge.append(realm.data(), realm.size());
+    challenge.push_back('"');
+    r.with_header(http::http_utils::http_header_www_authenticate,
+                  challenge);
+    // The body slot literally holds a string_body (possibly empty), so
+    // kind() reports body_kind::string. Switching to body_kind::empty
+    // for the empty-body case would fork the construction path and
+    // break the invariant that kind() reflects the placed-new body.
+    r.emplace_body<detail::string_body>(body_kind::string,
+                                        std::move(body));
+    return r;
+}
+
 }  // namespace httpserver

src/httpserver/http_response.hpp

@@ -25,13 +25,20 @@
 #ifndef SRC_HTTPSERVER_HTTP_RESPONSE_HPP_
 #define SRC_HTTPSERVER_HTTP_RESPONSE_HPP_
 
+#include <sys/types.h>          // ssize_t — for the deferred() producer
+
 #include <cstddef>
+#include <cstdint>
+#include <functional>
 #include <iosfwd>
 #include <map>
+#include <span>
 #include <string>
+#include <string_view>
 #include "httpserver/body_kind.hpp"
 #include "httpserver/http_arg_value.hpp"
 #include "httpserver/http_utils.hpp"
+#include "httpserver/iovec_entry.hpp"
 
 struct MHD_Connection;
 struct MHD_Response;
@@ -94,6 +101,88 @@ class http_response {
      // the complete type.
      virtual ~http_response();
 
+     // Body-kind discriminator (TASK-010 AC). Mirrors the kind reported
+     // by the underlying detail::body, but answered without a virtual
+     // call: the kind is recorded into kind_ at factory time and
+     // preserved across moves. TASK-011's dispatch path will consume
+     // this for its kind-specific fast paths.
+     [[nodiscard]] body_kind kind() const noexcept { return kind_; }
+
+     // -----------------------------------------------------------------
+     // Static factories (TASK-010, DR-005).
+     //
+     // Each factory placement-news the corresponding detail::body
+     // subclass into the response's SBO buffer (or, if the body ever
+     // exceeds 64 bytes, onto the heap via ::operator new(sizeof(T))
+     // so the destructor's matched ::operator delete pairs cleanly).
+     // Replaces the v1 polymorphic *_response subclasses.
+     //
+     // Status-code defaults match v1: 200 for content-bearing bodies,
+     // 204 for empty(), 401 for unauthorized().
+     // -----------------------------------------------------------------
+
+     // Construct a response carrying a string body. The Content-Type
+     // header defaults to "text/plain"; pass a different value (for
+     // example "application/json") to override. The body string is
+     // stored by move so callers retain no aliasing.
+     [[nodiscard]] static http_response string(
+         std::string body,
+         std::string content_type = "text/plain");
+
+     // Construct a response that streams a file from disk. Does NOT
+     // throw on a missing or unreadable path — failure is observable at
+     // dispatch time (the materialized MHD_Response is null and the
+     // dispatch path renders a 500). Mirrors v1 file_response semantics.
+     [[nodiscard]] static http_response file(std::string path);
+
+     // Construct a response from a span of scatter/gather buffers. The
+     // entries array is deep-copied into the body so the span need not
+     // outlive the response, but the buffers each entry's `base` points
+     // at remain BORROWED — they must outlive the response (and the
+     // MHD_Response that response materializes).
+     [[nodiscard]] static http_response iovec(
+         std::span<const iovec_entry> entries);
+
+     // Construct a response that streams from a pipe read-end. The
+     // factory takes ownership of `fd` immediately. The fd is closed
+     // when the materialized MHD_Response is destroyed; if the response
+     // is never materialized, the http_response's destructor closes
+     // it. Callers MUST NOT close `fd` after handing it off.
+     // `size_hint` is reserved for forward compatibility — currently
+     // ignored, may be used to advise libmicrohttpd of payload size in
+     // a future revision.
+     [[nodiscard]] static http_response pipe(int fd,
+                                             std::size_t size_hint = 0);
+
+     // Construct an empty (no-payload) response. Defaults to 204
+     // No Content, matching v1 empty_response.
+     [[nodiscard]] static http_response empty();
+
+     // Construct a response that streams from a producer callback.
+     // libmicrohttpd invokes `producer(pos, buf, max)` whenever it
+     // needs more bytes; the producer should return the number of
+     // bytes written, MHD_CONTENT_READER_END_OF_STREAM, or
+     // MHD_CONTENT_READER_END_WITH_ERROR. The producer is stored by
+     // move; large captures may force std::function to heap-allocate
+     // internally (independent of http_response's own SBO).
+     [[nodiscard]] static http_response deferred(
+         std::function<ssize_t(std::uint64_t, char*, std::size_t)> producer);
+
+     // Construct a 401 Unauthorized response with a WWW-Authenticate
+     // header of the form `<scheme> realm="<realm>"`. Replaces v1's
+     // basic_auth_fail_response and digest_auth_fail_response.
+     //
+     // Note: for "Digest" the response carries a static
+     // WWW-Authenticate challenge but does NOT participate in
+     // libmicrohttpd's nonce/opaque digest-auth state machine — that
+     // was v1's MHD_queue_auth_required_response3-driven path which
+     // requires connection-time state. Callers needing full digest
+     // auth should reach for the dedicated MHD APIs directly.
+     [[nodiscard]] static http_response unauthorized(
+         std::string_view scheme,
+         std::string_view realm,
+         std::string body = {});
+
      /**
       * Method used to get a specified header defined for the response
       * @param key The header identification
@@ -187,6 +276,19 @@ class http_response {
      void destroy_body() noexcept;
      void adopt_body_from(http_response& o) noexcept;
 
+     // Placement-new a concrete detail::body subclass into the SBO
+     // buffer (or, if T does not fit, onto the heap via the matched
+     // ::operator new(sizeof(T))/::operator delete pairing the
+     // destructor relies on). Defined out-of-line in http_response.cpp
+     // because it requires the complete type detail::body — it is only
+     // instantiated from the factory bodies in that TU.
+     //
+     // Pre-condition: the response's body slot is empty
+     // (default-constructed). Factories construct on a fresh
+     // http_response, so this always holds; an assertion guards it.
+     template <typename T, typename... Args>
+     void emplace_body(body_kind k, Args&&... args);
+
  protected:
      friend std::ostream &operator<< (std::ostream &os, const http_response &r);
 

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 new_response_types daemon_info uri_log feature_unavailable header_hygiene_iovec header_hygiene iovec_entry iovec_response http_method constants body http_response_sbo
+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 new_response_types daemon_info uri_log feature_unavailable header_hygiene_iovec header_hygiene iovec_entry iovec_response http_method constants body http_response_sbo http_response_factories
 
 MOSTLYCLEANFILES = *.gcda *.gcno *.gcov
 
@@ -85,6 +85,16 @@ body_LDADD = $(LDADD) -lmicrohttpd
 http_response_sbo_SOURCES = unit/http_response_sbo_test.cpp
 http_response_sbo_LDADD = $(LDADD) -lmicrohttpd
 
+# http_response_factories: TASK-010 unit test for the static factory
+# functions on http_response (string/file/iovec/pipe/empty/deferred/
+# unauthorized). Each factory placement-news the corresponding
+# detail::body subclass into the SBO buffer, so this TU includes the
+# private detail/body.hpp via the build-tree -DHTTPSERVER_COMPILATION
+# path. Needs -lmicrohttpd for the same transitive reasons as
+# http_response_sbo.
+http_response_factories_SOURCES = unit/http_response_factories_test.cpp
+http_response_factories_LDADD = $(LDADD) -lmicrohttpd
+
 noinst_HEADERS = littletest.hpp
 AM_CXXFLAGS += -Wall -fPIC -Wno-overloaded-virtual