Merge TASK-063: drop accepted-but-ignored size_hint from http_response::pipe

Author: etr

RELEASE_NOTES.md

@@ -222,6 +222,15 @@ and see the v2 replacement.
   verbose form for local development, call `.expose_credentials_in_logs(true)`
   on the `create_webserver` builder — this flag is intended for development
   only and must not be set in production deployments.
+- **`http_response::pipe` no longer accepts a `size_hint`.** Earlier v2
+  work-in-progress builds exposed `pipe(int fd, std::size_t size_hint = 0)`
+  with `size_hint` reserved for future use; the parameter was never
+  consulted on the dispatch path. v2.0 ships the minimal `pipe(int fd)`
+  signature (TASK-063, PRD §3.5 / `PRD-RSP-REQ-001`). Source callers
+  passing a second argument must drop it; no behavioural change. There
+  is no honoring path planned — `Content-Length` synthesis would lie
+  when the pipe yields a different byte count, and libmicrohttpd's
+  `MHD_create_response_from_pipe` takes no size.
 
 ## Threading
 

specs/tasks/M7-v2-cleanup/TASK-063.md

@@ -8,10 +8,10 @@
 `pipe(int fd, std::size_t size_hint = 0)` exposes `size_hint` in the public API but the dispatch path ignores it; a test (`test/unit/http_response_factories_test.cpp:253-266`) pins "accepted-but-ignored" as the contract. Decide whether to honor the hint (sizing the streaming buffer, `Content-Length` synthesis, or kernel hint via `posix_fadvise`) or remove it from the signature.
 
 **Action Items:**
-- [ ] Decide one of: (a) honor `size_hint` as the streaming chunk size and/or `Content-Length`, or (b) remove the parameter and the pinning test.
+- [x] Decide one of: (a) honor `size_hint` as the streaming chunk size and/or `Content-Length`, or (b) remove the parameter and the pinning test. — chose (b); rationale recorded in `.groundwork-plans/TASK-063-plan.md` (no `PRD-RSP-REQ` for streaming-size; MHD's `MHD_create_response_from_pipe` takes no size; `Content-Length` synthesis would lie).
 - [ ] If (a): wire `size_hint` into `detail::body_pipe` (or wherever the pipe body is materialised) and add a `Content-Length` header when the hint is nonzero and finite. Add a real integration test that pins the byte-count emitted on the wire matches the hint when the underlying fd produces exactly that many bytes.
-- [ ] If (b): drop `size_hint` from the public `pipe(int fd)` signature in `src/httpserver/http_response.hpp:159-161`, drop the corresponding default-arg in `src/http_response.cpp:409`, and convert the "accepted-but-ignored" test in `test/unit/http_response_factories_test.cpp:253-266` into a compile-fail or call-site update.
-- [ ] Update RELEASE_NOTES.md "Migration notes" if the signature changed (binary/source incompatibility).
+- [x] If (b): drop `size_hint` from the public `pipe(int fd)` signature in `src/httpserver/http_response.hpp:159-161`, drop the corresponding default-arg in `src/http_response.cpp:409`, and convert the "accepted-but-ignored" test in `test/unit/http_response_factories_test.cpp:253-266` into a compile-fail or call-site update.
+- [x] Update RELEASE_NOTES.md "Migration notes" if the signature changed (binary/source incompatibility).
 
 **Dependencies:**
 - Blocked by: None
@@ -26,4 +26,4 @@
 **Related Requirements:** PRD-RSP-REQ-001 (factory by value), PRD §2 API minimalism
 **Related Decisions:** None new
 
-**Status:** Backlog
+**Status:** Done

specs/tasks/M7-v2-cleanup/_index.md

@@ -27,7 +27,7 @@ TASK-093).
 | TASK-060 | Scope or remove file-scoped `-Warray-bounds` suppressions | HIGH | S | Done |
 | TASK-061 | Mechanical cleanup sweep — unfinished prose, orphan comments, stale doc refs | HIGH | S | Done |
 | TASK-062 | RFC-7616-compliant Digest auth response factory | HIGH | L | Done |
-| TASK-063 | Honor or remove `http_response::pipe` `size_hint` parameter | HIGH | S | Backlog |
+| TASK-063 | Honor or remove `http_response::pipe` `size_hint` parameter | HIGH | S | Done |
 | TASK-064 | Structured cookie type | HIGH | M | Backlog |
 | TASK-065 | RFC 5952 IPv6 zero-compression in `peer_address` | HIGH | S | Backlog |
 | TASK-066 | Runtime setter for hook alias slots | MED | M | Backlog |

src/http_response.cpp

@@ -405,8 +405,7 @@ http_response http_response::iovec(std::span<const iovec_entry> entries) {
     return r;
 }
 
-http_response http_response::pipe(int fd, std::size_t size_hint) {
-    (void)size_hint;  // reserved for future use
+http_response http_response::pipe(int fd) {
     http_response r;
     r.status_code_ = http::http_utils::http_ok;
     r.emplace_body<detail::pipe_body>(body_kind::pipe, fd);

src/httpserver/http_response.hpp

@@ -192,11 +192,7 @@ class http_response final {
      // 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);
+     [[nodiscard]] static http_response pipe(int fd);
 
      // Construct an empty (no-payload) response. Defaults to 204
      // No Content, matching v1 empty_response. The optional `mhd_flags`

test/unit/http_response_factories_test.cpp

@@ -250,20 +250,20 @@ LT_BEGIN_AUTO_TEST(http_response_factories_suite, pipe_factory_kind)
     ::close(fds[1]);
 LT_END_AUTO_TEST(pipe_factory_kind)
 
+// Pin: pipe() must accept exactly one argument (the fd). Any future
+// reintroduction of a size_hint / chunk_size / Content-Length parameter
+// is a deliberate API change and must update this assertion. See
+// TASK-063 — rationale: an accepted-but-ignored parameter teaches
+// callers a lie; honoring it would require synthesising Content-Length
+// without ground truth from the pipe fd.
 LT_BEGIN_AUTO_TEST(http_response_factories_suite,
-                   pipe_factory_size_hint_is_accepted_but_ignored)
-    // size_hint is reserved for future use; callers may pass it without
-    // observable effect today.
-    int fds[2];
-    int rc = ::pipe(fds);
-    LT_ASSERT_EQ(rc, 0);
-    {
-        auto r = http_response::pipe(fds[0], /*size_hint=*/4096);
-        LT_CHECK_EQ(static_cast<int>(r.kind()),
-                    static_cast<int>(body_kind::pipe));
-    }
-    ::close(fds[1]);
-LT_END_AUTO_TEST(pipe_factory_size_hint_is_accepted_but_ignored)
+                   pipe_factory_signature_is_single_arg)
+    using pipe_fn_t = http_response (*)(int);
+    static_assert(std::is_same_v<decltype(&http_response::pipe), pipe_fn_t>,
+                  "http_response::pipe must take exactly one parameter "
+                  "(int fd); see TASK-063");
+    LT_CHECK_EQ(true, true);  // littletest needs at least one runtime check
+LT_END_AUTO_TEST(pipe_factory_signature_is_single_arg)
 #endif  // !_WIN32
 
 // -----------------------------------------------------------------------