TASK-004: Add httpserver::iovec_entry POD with layout-pinning asserts

Introduces a library-defined POD `httpserver::iovec_entry { const void* base;
std::size_t len; }` in a new public header `<httpserver/iovec_entry.hpp>`,
included by `<httpserver/http_response.hpp>` and the umbrella header. The
type replaces POSIX `struct iovec` at the public API surface, keeping
`<sys/uio.h>` out of every public header.

Layout pinning lives in `src/iovec_response.cpp` as six unconditional
static_asserts: three against POSIX `struct iovec` (size + iov_base /
iov_len offsets) per the spec, and three parallel asserts against
libmicrohttpd `MHD_IoVec` because that is the actual cast target on the
dispatch path. The MHD_IoVec asserts are an addition over the spec —
without them the reinterpret_cast bridge is the unsafe one. A TODO
sentinel comment (LIBHTTPSERVER_TODO_TASK004_MEMCPY_FALLBACK) documents
the memcpy fallback strategy that would activate if a divergent-layout
platform ever trips one of the asserts. Today every supported platform
(glibc, musl, macOS, FreeBSD, NetBSD, OpenBSD, illumos) shares the same
layout so the asserts pass and the reinterpret_cast is well-defined.

`iovec_response::get_raw_response()` now builds a contiguous
`std::vector<iovec_entry>` from its owned std::strings and
reinterpret_casts to `const MHD_IoVec*` when calling MHD. This proves
the cast bridge in production code today; TASK-010 will move the same
line into the future `details/body.hpp` factory.

Two new TDD-driven test programs:
- `test/unit/iovec_entry_test.cpp` — verifies POD traits (standard
  layout, trivially copyable), member types, layout equivalence with
  POSIX `struct iovec` from a consumer perspective, and the
  reinterpret_cast bridge round-trip.
- `test/unit/header_hygiene_iovec_test.cpp` — declares a colliding
  `struct iovec` before including `iovec_entry.hpp` directly. The TU
  compiling at all proves the new public header pulls in nothing from
  `<sys/uio.h>`. (The broader umbrella-leak concern — current umbrella
  transitively pulls `<sys/uio.h>` via gnutls and `<sys/socket.h>` —
  is out of scope for TASK-004 and is the remit of TASK-007's
  header-hygiene CI gate.)

Build: 20/20 tests pass under both default and `--enable-debug`
(-Wall -Wextra -Werror -pedantic -O0). `grep -E '#include\s+<sys/uio\.h>'
src/httpserver/*.hpp` returns no results. `make install` ships the new
header at `$prefix/include/httpserver/iovec_entry.hpp`.

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

Author: etr

src/Makefile.am

@@ -24,7 +24,7 @@ libhttpserver_la_SOURCES = string_utilities.cpp webserver.cpp http_utils.cpp fil
 # Detail headers (httpserver/details/*.hpp) live here so they cannot leak to
 # downstream consumers — the public surface comes in through <httpserver.hpp>.
 noinst_HEADERS = httpserver/string_utilities.hpp httpserver/details/modded_request.hpp httpserver/details/http_endpoint.hpp gettext.h
-nobase_include_HEADERS = httpserver.hpp httpserver/create_webserver.hpp httpserver/webserver.hpp httpserver/http_utils.hpp httpserver/file_info.hpp httpserver/http_request.hpp httpserver/http_response.hpp httpserver/http_resource.hpp httpserver/string_response.hpp httpserver/digest_auth_fail_response.hpp httpserver/deferred_response.hpp httpserver/file_response.hpp httpserver/pipe_response.hpp httpserver/empty_response.hpp httpserver/feature_unavailable.hpp httpserver/iovec_response.hpp httpserver/http_arg_value.hpp
+nobase_include_HEADERS = httpserver.hpp httpserver/create_webserver.hpp httpserver/webserver.hpp httpserver/http_utils.hpp httpserver/file_info.hpp httpserver/http_request.hpp httpserver/http_response.hpp httpserver/http_resource.hpp httpserver/string_response.hpp httpserver/digest_auth_fail_response.hpp httpserver/deferred_response.hpp httpserver/file_response.hpp httpserver/pipe_response.hpp httpserver/empty_response.hpp httpserver/feature_unavailable.hpp httpserver/iovec_entry.hpp httpserver/iovec_response.hpp httpserver/http_arg_value.hpp
 
 if HAVE_BAUTH
 libhttpserver_la_SOURCES += basic_auth_fail_response.cpp

src/httpserver.hpp

@@ -42,6 +42,7 @@
 #include "httpserver/http_resource.hpp"
 #include "httpserver/http_response.hpp"
 #include "httpserver/http_utils.hpp"
+#include "httpserver/iovec_entry.hpp"
 #include "httpserver/iovec_response.hpp"
 #include "httpserver/file_info.hpp"
 #include "httpserver/pipe_response.hpp"

src/httpserver/http_response.hpp

@@ -30,6 +30,7 @@
 #include <string>
 #include "httpserver/http_arg_value.hpp"
 #include "httpserver/http_utils.hpp"
+#include "httpserver/iovec_entry.hpp"
 
 struct MHD_Connection;
 struct MHD_Response;

src/httpserver/iovec_entry.hpp

@@ -0,0 +1,50 @@
+/*
+     This file is part of libhttpserver
+     Copyright (C) 2011-2019 Sebastiano Merlino
+
+     This library is free software; you can redistribute it and/or
+     modify it under the terms of the GNU Lesser General Public
+     License as published by the Free Software Foundation; either
+     version 2.1 of the License, or (at your option) any later version.
+
+     This library is distributed in the hope that it will be useful,
+     but WITHOUT ANY WARRANTY; without even the implied warranty of
+     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+     Lesser General Public License for more details.
+
+     You should have received a copy of the GNU Lesser General Public
+     License along with this library; if not, write to the Free Software
+     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301
+     USA
+*/
+
+#if !defined (_HTTPSERVER_HPP_INSIDE_) && !defined (HTTPSERVER_COMPILATION)
+#error "Only <httpserver.hpp> or <httpserverpp> can be included directly."
+#endif
+
+#ifndef SRC_HTTPSERVER_IOVEC_ENTRY_HPP_
+#define SRC_HTTPSERVER_IOVEC_ENTRY_HPP_
+
+#include <cstddef>
+
+namespace httpserver {
+
+// Library-defined POD describing a single scatter/gather buffer at the
+// public API surface. Replaces `struct iovec` from <sys/uio.h>, keeping
+// the public-header surface free of POSIX-only system headers.
+//
+// Layout is pinned to match POSIX `struct iovec` and libmicrohttpd's
+// `MHD_IoVec` so the dispatch path can `reinterpret_cast` a contiguous
+// array of iovec_entry into either C type at zero copy. The pinning
+// asserts live next to the cast site (currently `iovec_response.cpp`,
+// moving to `details/body.hpp` once TASK-009 lands).
+//
+// `base` is `const void*` because libhttpserver never writes through
+// these buffers on the response path.
+struct iovec_entry {
+    const void* base;
+    std::size_t len;
+};
+
+}  // namespace httpserver
+#endif  // SRC_HTTPSERVER_IOVEC_ENTRY_HPP_

src/iovec_response.cpp

@@ -19,26 +19,72 @@
 */
 
 #include "httpserver/iovec_response.hpp"
+#include "httpserver/iovec_entry.hpp"
+
+#include <cstddef>
 #include <microhttpd.h>
+#include <sys/uio.h>
 #include <vector>
 
 struct MHD_Response;
 
 namespace httpserver {
 
+// ---------------------------------------------------------------------------
+// TASK-004: layout-pinning static_asserts.
+//
+// httpserver::iovec_entry is the public scatter/gather POD; libmicrohttpd's
+// MHD_IoVec is the actual cast target on the dispatch path. POSIX struct
+// iovec is asserted in parallel because the spec mandates it and because
+// every platform we ship to defines all three with identical layout
+// (glibc, musl, macOS, FreeBSD, NetBSD, OpenBSD, illumos).
+//
+// LIBHTTPSERVER_TODO_TASK004_MEMCPY_FALLBACK: if any of the asserts below
+// ever fires on a divergent-layout platform, the fix is to replace the
+// reinterpret_cast in the dispatch path with an element-by-element copy
+// into a stack/heap MHD_IoVec[]. Until such a platform appears the
+// asserts are the gate — a build failure on the divergent platform is
+// the desired outcome (loud, immediate, with the assert string naming
+// what diverged).
+// ---------------------------------------------------------------------------
+static_assert(sizeof(::httpserver::iovec_entry) == sizeof(struct iovec),
+    "iovec_entry size must match POSIX struct iovec — divergent platform; "
+    "implement memcpy fallback (see TASK-004)");
+static_assert(offsetof(::httpserver::iovec_entry, base) ==
+                  offsetof(struct iovec, iov_base),
+    "iovec_entry::base offset must match struct iovec::iov_base");
+static_assert(offsetof(::httpserver::iovec_entry, len) ==
+                  offsetof(struct iovec, iov_len),
+    "iovec_entry::len offset must match struct iovec::iov_len");
+
+static_assert(sizeof(::httpserver::iovec_entry) == sizeof(MHD_IoVec),
+    "iovec_entry size must match libmicrohttpd MHD_IoVec — MHD layout drift");
+static_assert(offsetof(::httpserver::iovec_entry, base) ==
+                  offsetof(MHD_IoVec, iov_base),
+    "iovec_entry::base offset must match MHD_IoVec::iov_base");
+static_assert(offsetof(::httpserver::iovec_entry, len) ==
+                  offsetof(MHD_IoVec, iov_len),
+    "iovec_entry::len offset must match MHD_IoVec::iov_len");
+
 MHD_Response* iovec_response::get_raw_response() {
     // MHD_create_response_from_iovec makes an internal copy of the iov array,
     // so the local vector is safe. The buffer data pointed to by iov_base must
     // remain valid until the response is destroyed — this is guaranteed because
     // the buffers are owned by this iovec_response object.
-    std::vector<MHD_IoVec> iov(buffers.size());
+    //
+    // The dispatch path builds a contiguous std::vector<iovec_entry> from the
+    // owned std::strings, then reinterpret_casts it to const MHD_IoVec* when
+    // calling MHD. The cast is well-defined because the layout-pinning
+    // static_asserts above guarantee identical size and field offsets. This
+    // same cast bridge will move into details/body.hpp when TASK-009 lands.
+    std::vector<iovec_entry> entries(buffers.size());
     for (size_t i = 0; i < buffers.size(); ++i) {
-        iov[i].iov_base = buffers[i].data();
-        iov[i].iov_len = buffers[i].size();
+        entries[i].base = buffers[i].data();
+        entries[i].len = buffers[i].size();
     }
     return MHD_create_response_from_iovec(
-        iov.data(),
-        static_cast<unsigned int>(iov.size()),
+        reinterpret_cast<const MHD_IoVec*>(entries.data()),
+        static_cast<unsigned int>(entries.size()),
         nullptr,
         nullptr);
 }

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
+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 iovec_entry
 
 MOSTLYCLEANFILES = *.gcda *.gcno *.gcov
 
@@ -52,6 +52,8 @@ uri_log_SOURCES = unit/uri_log_test.cpp
 # LDADD (modern ld enforces --no-copy-dt-needed-entries).
 uri_log_LDADD = $(LDADD) -lmicrohttpd
 feature_unavailable_SOURCES = unit/feature_unavailable_test.cpp
+header_hygiene_iovec_SOURCES = unit/header_hygiene_iovec_test.cpp
+iovec_entry_SOURCES = unit/iovec_entry_test.cpp
 
 noinst_HEADERS = littletest.hpp
 AM_CXXFLAGS += -Wall -fPIC -Wno-overloaded-virtual

test/unit/header_hygiene_iovec_test.cpp

@@ -0,0 +1,60 @@
+/*
+     This file is part of libhttpserver
+     Copyright (C) 2011-2019 Sebastiano Merlino
+
+     This library is free software; you can redistribute it and/or
+     modify it under the terms of the GNU Lesser General Public
+     License as published by the Free Software Foundation; either
+     version 2.1 of the License, or (at your option) any later version.
+
+     This library is distributed in the hope that it will be useful,
+     but WITHOUT ANY WARRANTY; without even the implied warranty of
+     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+     Lesser General Public License for more details.
+
+     You should have received a copy of the GNU Lesser General Public
+     License along with this library; if not, write to the Free Software
+     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301
+     USA
+*/
+
+// Header-hygiene sentinel for TASK-004:
+//
+// AC #4 of TASK-004 ("public header must not include <sys/uio.h>") is
+// scoped to the new iovec_entry header itself; the broader umbrella-leak
+// concern (current umbrella transitively pulls <sys/uio.h> via gnutls/
+// <sys/socket.h>) is the remit of TASK-007's header-hygiene CI gate.
+//
+// To enforce the local guarantee, this TU declares a colliding
+// `struct iovec` BEFORE including iovec_entry.hpp directly. If the
+// header (or anything it pulls in) pulls <sys/uio.h>, the system
+// definition collides with this sentinel and the build fails with a
+// redefinition error. The TU compiling at all is the assertion.
+struct iovec {
+    int libhttpserver_hygiene_sentinel;
+};
+
+// Include the new POD header in isolation to verify it pulls no
+// surprise dependencies. HTTPSERVER_COMPILATION is already defined by
+// AM_CPPFLAGS in test/Makefile.am, so the gate is satisfied.
+#include "httpserver/iovec_entry.hpp"
+
+#include "./littletest.hpp"
+
+LT_BEGIN_SUITE(header_hygiene_iovec_suite)
+    void set_up() {
+    }
+
+    void tear_down() {
+    }
+LT_END_SUITE(header_hygiene_iovec_suite)
+
+LT_BEGIN_AUTO_TEST(header_hygiene_iovec_suite, iovec_entry_visible_without_sys_uio)
+    httpserver::iovec_entry e{nullptr, 0};
+    LT_CHECK_EQ(e.base, nullptr);
+    LT_CHECK_EQ(e.len, 0u);
+LT_END_AUTO_TEST(iovec_entry_visible_without_sys_uio)
+
+LT_BEGIN_AUTO_TEST_ENV()
+    AUTORUN_TESTS()
+LT_END_AUTO_TEST_ENV()

test/unit/iovec_entry_test.cpp

@@ -0,0 +1,102 @@
+/*
+     This file is part of libhttpserver
+     Copyright (C) 2011-2019 Sebastiano Merlino
+
+     This library is free software; you can redistribute it and/or
+     modify it under the terms of the GNU Lesser General Public
+     License as published by the Free Software Foundation; either
+     version 2.1 of the License, or (at your option) any later version.
+
+     This library is distributed in the hope that it will be useful,
+     but WITHOUT ANY WARRANTY; without even the implied warranty of
+     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+     Lesser General Public License for more details.
+
+     You should have received a copy of the GNU Lesser General Public
+     License along with this library; if not, write to the Free Software
+     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301
+     USA
+*/
+
+// Layout / POD-trait verification for `httpserver::iovec_entry`.
+// This TU is allowed to include <sys/uio.h> directly — it is an internal
+// test, not a header-hygiene sentinel. The library-side guarantee that
+// downstream code does NOT see <sys/uio.h> via the umbrella is asserted
+// separately by `header_hygiene_iovec_test.cpp`.
+
+#include <cstddef>
+#include <sys/uio.h>
+#include <type_traits>
+
+#include "./httpserver.hpp"
+#include "./littletest.hpp"
+
+// AC: trivially copyable + standard layout — required for the
+// reinterpret_cast bridge to libmicrohttpd's MHD_IoVec / POSIX struct iovec.
+static_assert(std::is_standard_layout_v<httpserver::iovec_entry>,
+              "iovec_entry must be standard layout");
+static_assert(std::is_trivially_copyable_v<httpserver::iovec_entry>,
+              "iovec_entry must be trivially copyable");
+
+// Member types as declared by the spec.
+static_assert(std::is_same_v<decltype(httpserver::iovec_entry::base),
+                             const void*>,
+              "iovec_entry::base must be const void*");
+static_assert(std::is_same_v<decltype(httpserver::iovec_entry::len),
+                             std::size_t>,
+              "iovec_entry::len must be std::size_t");
+
+// Layout pinning duplicated from the consumer perspective: defense in depth
+// against a future change to <sys/uio.h> on a divergent platform.
+static_assert(sizeof(httpserver::iovec_entry) == sizeof(struct iovec),
+              "iovec_entry size must match POSIX struct iovec");
+static_assert(offsetof(httpserver::iovec_entry, base) ==
+                  offsetof(struct iovec, iov_base),
+              "iovec_entry::base offset must match struct iovec::iov_base");
+static_assert(offsetof(httpserver::iovec_entry, len) ==
+                  offsetof(struct iovec, iov_len),
+              "iovec_entry::len offset must match struct iovec::iov_len");
+
+LT_BEGIN_SUITE(iovec_entry_suite)
+    void set_up() {
+    }
+
+    void tear_down() {
+    }
+LT_END_SUITE(iovec_entry_suite)
+
+LT_BEGIN_AUTO_TEST(iovec_entry_suite, default_constructed_pod_holds_values)
+    httpserver::iovec_entry e{};
+    LT_CHECK_EQ(e.base, nullptr);
+    LT_CHECK_EQ(e.len, 0u);
+LT_END_AUTO_TEST(default_constructed_pod_holds_values)
+
+LT_BEGIN_AUTO_TEST(iovec_entry_suite, brace_init_assigns_members)
+    const char* payload = "hello";
+    httpserver::iovec_entry e{payload, 5};
+    LT_CHECK_EQ(e.base, static_cast<const void*>(payload));
+    LT_CHECK_EQ(e.len, 5u);
+LT_END_AUTO_TEST(brace_init_assigns_members)
+
+// Reinterpret-cast bridge from a contiguous range of iovec_entry to
+// POSIX struct iovec. This is the cast the library performs when feeding
+// libmicrohttpd, and what TASK-010 will rely on when it lands the
+// std::span<const iovec_entry> factory.
+LT_BEGIN_AUTO_TEST(iovec_entry_suite, reinterpret_cast_to_struct_iovec_preserves_data)
+    const char* a = "abc";
+    const char* b = "wxyz";
+    httpserver::iovec_entry entries[2] = {
+        {a, 3},
+        {b, 4},
+    };
+    const struct iovec* posix =
+        reinterpret_cast<const struct iovec*>(&entries[0]);
+    LT_CHECK_EQ(posix[0].iov_base, const_cast<void*>(static_cast<const void*>(a)));
+    LT_CHECK_EQ(posix[0].iov_len, 3u);
+    LT_CHECK_EQ(posix[1].iov_base, const_cast<void*>(static_cast<const void*>(b)));
+    LT_CHECK_EQ(posix[1].iov_len, 4u);
+LT_END_AUTO_TEST(reinterpret_cast_to_struct_iovec_preserves_data)
+
+LT_BEGIN_AUTO_TEST_ENV()
+    AUTORUN_TESTS()
+LT_END_AUTO_TEST_ENV()