TASK-045: Hook bus skeleton (hook_phase, hook_action, hook_handle, add_hook)

Lands the public types and per-phase storage for the lifecycle hook bus
per §4.10 / DR-012 / PRD-HOOK-REQ-001..002. No phase fires yet; phases
start firing in TASK-046..051. After this task the API surface compiles
and a hook can be registered + removed.

Public surface (four new MHD-clean headers):
  src/httpserver/hook_phase.hpp    -- enum class hook_phase + count_ (11)
  src/httpserver/hook_action.hpp   -- pass / respond_with / take_response &&
  src/httpserver/hook_handle.hpp   -- move-only RAII receipt
  src/httpserver/hook_context.hpp  -- 11 per-phase ctx structs + peer_address
                                      + route_descriptor

webserver::add_hook -- 11 overloads, one per phase, distinguished by the
std::function signature; each validates the runtime phase tag, allocates
a fresh slot_id (monotonic uint64), takes hook_table_mutex_ unique_lock,
pushes into the matching per-phase vector, flips any_hooks_[phase] true.
hook_handle::remove() / dtor re-takes the lock, linear-scans for slot_id,
erases, and clears the gate if the vector is now empty.

Storage lives on webserver_impl: shared_mutex hook_table_mutex_, atomic
uint64 next_slot_id_, std::array<atomic<bool>, count_> any_hooks_, and
11 individually-typed std::vector<phase_entry<Sig>> members (signatures
differ per phase). hook_handle is ABI-pinned <= 32 B via static_assert.

Tests (3 new entries, total now 51):
  test/unit/header_hygiene_hooks_test.cpp -- per-header preprocessor
    sentinel that the four new hook headers don't transitively pull
    <microhttpd.h>/<gnutls/gnutls.h>/<sys/socket.h>/<sys/uio.h>.
  test/unit/hook_api_shape_test.cpp -- compile-time SFINAE gates
    (move-only, signature mismatch rejected) + runtime add/remove,
    double-remove no-op, RAII destruction, detach() disarm, any_hooks_
    gate flip semantics.
  test/integ/hooks_no_firing.cpp -- registers one hook on every phase,
    drives one full HTTP round-trip, asserts all 11 counters stay zero.

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

Author: etr

src/Makefile.am

@@ -25,12 +25,12 @@ lib_LTLIBRARIES = libhttpserver.la
 # builds. The WS-off branch in websocket_handler.cpp provides stub
 # definitions (every member throws feature_unavailable except is_valid()
 # which returns false).
-libhttpserver_la_SOURCES = string_utilities.cpp webserver.cpp http_utils.cpp file_info.cpp http_request.cpp http_response.cpp create_webserver.cpp create_test_request.cpp websocket_handler.cpp detail/http_endpoint.cpp detail/body.cpp
+libhttpserver_la_SOURCES = string_utilities.cpp webserver.cpp http_utils.cpp file_info.cpp http_request.cpp http_response.cpp create_webserver.cpp create_test_request.cpp websocket_handler.cpp hook_handle.cpp detail/http_endpoint.cpp detail/body.cpp
 # noinst_HEADERS: shipped in the tarball but NEVER installed under $prefix/include.
 # Detail headers (httpserver/detail/*.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/detail/modded_request.hpp httpserver/detail/http_endpoint.hpp httpserver/detail/body.hpp httpserver/detail/webserver_impl.hpp httpserver/detail/http_request_impl.hpp httpserver/detail/route_entry.hpp httpserver/detail/lambda_resource.hpp httpserver/detail/radix_tree.hpp httpserver/detail/route_cache.hpp gettext.h
-nobase_include_HEADERS = httpserver.hpp httpserver/body_kind.hpp httpserver/constants.hpp httpserver/create_webserver.hpp httpserver/create_test_request.hpp httpserver/webserver.hpp httpserver/websocket_handler.hpp httpserver/http_utils.hpp httpserver/file_info.hpp httpserver/http_request.hpp httpserver/http_response.hpp httpserver/http_resource.hpp httpserver/feature_unavailable.hpp httpserver/iovec_entry.hpp httpserver/http_arg_value.hpp httpserver/http_method.hpp
+nobase_include_HEADERS = httpserver.hpp httpserver/body_kind.hpp httpserver/constants.hpp httpserver/create_webserver.hpp httpserver/create_test_request.hpp httpserver/webserver.hpp httpserver/websocket_handler.hpp httpserver/http_utils.hpp httpserver/file_info.hpp httpserver/http_request.hpp httpserver/http_response.hpp httpserver/http_resource.hpp httpserver/feature_unavailable.hpp httpserver/iovec_entry.hpp httpserver/http_arg_value.hpp httpserver/http_method.hpp httpserver/hook_phase.hpp httpserver/hook_action.hpp httpserver/hook_handle.hpp httpserver/hook_context.hpp
 
 AM_CXXFLAGS += -fPIC -Wall
 

src/hook_handle.cpp

@@ -0,0 +1,218 @@
+/*
+     This file is part of libhttpserver
+     Copyright (C) 2011-2026 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
+*/
+
+// TASK-045 -- Out-of-line bodies for hook_handle and peer_address.
+//
+// hook_handle's destructor + remove() + move ops need the complete
+// type of detail::webserver_impl (the per-phase vectors live there),
+// so the bodies live here, not in the public header. Same pattern as
+// http_response's move/dtor.
+
+#include "httpserver/hook_handle.hpp"
+
+#include <cstdio>
+#include <mutex>
+#include <shared_mutex>
+#include <string>
+#include <utility>
+
+#include "httpserver/hook_context.hpp"
+#include "httpserver/detail/webserver_impl.hpp"
+
+namespace httpserver {
+
+// ---- hook_handle ---------------------------------------------------------
+
+hook_handle::hook_handle(hook_handle&& other) noexcept
+    : impl_(other.impl_),
+      slot_id_(other.slot_id_),
+      phase_(other.phase_),
+      armed_(other.armed_) {
+    // Disarm the source so its destructor is a no-op.
+    other.armed_ = false;
+    other.impl_ = nullptr;
+}
+
+hook_handle& hook_handle::operator=(hook_handle&& other) noexcept {
+    if (this != &other) {
+        // Remove any registration this object currently owns before
+        // taking over the source's. remove() is idempotent and
+        // noexcept, so this is safe even if `armed_` is already false.
+        remove();
+        impl_ = other.impl_;
+        slot_id_ = other.slot_id_;
+        phase_ = other.phase_;
+        armed_ = other.armed_;
+        other.armed_ = false;
+        other.impl_ = nullptr;
+    }
+    return *this;
+}
+
+hook_handle::~hook_handle() {
+    if (armed_) {
+        remove();
+    }
+}
+
+void hook_handle::remove() noexcept {
+    if (!armed_ || impl_ == nullptr) {
+        return;
+    }
+    // Snapshot the source state and disarm BEFORE doing the erase, so
+    // any exception from the lambda's destructor (very unlikely, but
+    // remove() is declared noexcept and std::terminate is the
+    // observable outcome anyway) does not leave the handle in a
+    // half-removed state.
+    auto* impl = impl_;
+    const auto phase = phase_;
+    const auto id = slot_id_;
+    armed_ = false;
+    impl_ = nullptr;
+
+    std::unique_lock lock(impl->hook_table_mutex_);
+
+    // Linear scan for the matching slot. Phase vectors are tiny in
+    // practice (single-digit hook counts). A not-found result is the
+    // idempotent no-op case: the slot was already erased by an earlier
+    // remove() or never inserted (defensive). Either way we still
+    // re-evaluate the any_hooks_ gate against the current vector
+    // emptiness.
+    auto erase_if_found = [id](auto& vec) -> bool {
+        for (auto it = vec.begin(); it != vec.end(); ++it) {
+            if (it->slot_id == id) {
+                vec.erase(it);
+                return true;
+            }
+        }
+        return false;
+    };
+    auto reset_gate_if_empty = [impl, phase](const auto& vec) {
+        if (vec.empty()) {
+            impl->any_hooks_[static_cast<std::size_t>(phase)].store(
+                false, std::memory_order_release);
+        }
+    };
+
+    switch (phase) {
+    case hook_phase::connection_opened:
+        erase_if_found(impl->hooks_connection_opened_);
+        reset_gate_if_empty(impl->hooks_connection_opened_);
+        break;
+    case hook_phase::accept_decision:
+        erase_if_found(impl->hooks_accept_decision_);
+        reset_gate_if_empty(impl->hooks_accept_decision_);
+        break;
+    case hook_phase::request_received:
+        erase_if_found(impl->hooks_request_received_);
+        reset_gate_if_empty(impl->hooks_request_received_);
+        break;
+    case hook_phase::body_chunk:
+        erase_if_found(impl->hooks_body_chunk_);
+        reset_gate_if_empty(impl->hooks_body_chunk_);
+        break;
+    case hook_phase::route_resolved:
+        erase_if_found(impl->hooks_route_resolved_);
+        reset_gate_if_empty(impl->hooks_route_resolved_);
+        break;
+    case hook_phase::before_handler:
+        erase_if_found(impl->hooks_before_handler_);
+        reset_gate_if_empty(impl->hooks_before_handler_);
+        break;
+    case hook_phase::handler_exception:
+        erase_if_found(impl->hooks_handler_exception_);
+        reset_gate_if_empty(impl->hooks_handler_exception_);
+        break;
+    case hook_phase::after_handler:
+        erase_if_found(impl->hooks_after_handler_);
+        reset_gate_if_empty(impl->hooks_after_handler_);
+        break;
+    case hook_phase::response_sent:
+        erase_if_found(impl->hooks_response_sent_);
+        reset_gate_if_empty(impl->hooks_response_sent_);
+        break;
+    case hook_phase::request_completed:
+        erase_if_found(impl->hooks_request_completed_);
+        reset_gate_if_empty(impl->hooks_request_completed_);
+        break;
+    case hook_phase::connection_closed:
+        erase_if_found(impl->hooks_connection_closed_);
+        reset_gate_if_empty(impl->hooks_connection_closed_);
+        break;
+    case hook_phase::count_:
+        // Unreachable: an armed handle always carries a valid phase.
+        break;
+    }
+}
+
+hook_handle hook_handle::detach() && noexcept {
+    // Construct a disarmed handle from the same data; do NOT call the
+    // private armed-ctor because the spec says detach() leaves the
+    // underlying registration in place (no impl interaction).
+    hook_handle out;
+    out.impl_ = impl_;
+    out.slot_id_ = slot_id_;
+    out.phase_ = phase_;
+    out.armed_ = false;     // detach() = "destructor will not touch impl"
+    // Disarm the source so its destructor is also a no-op.
+    armed_ = false;
+    impl_ = nullptr;
+    return out;
+}
+
+// ---- peer_address::to_string ---------------------------------------------
+
+std::string peer_address::to_string() const {
+    // No <netinet/in.h> / inet_ntop here so we keep this TU free of
+    // backend-platform headers. The format is canonical-enough for
+    // log lines without dragging in the full POSIX socket surface.
+    // 46 is POSIX INET6_ADDRSTRLEN; we round up for snprintf's NUL.
+    char buf[64];
+    switch (fam) {
+    case family::ipv4:
+        std::snprintf(buf, sizeof(buf), "%u.%u.%u.%u",
+                      static_cast<unsigned>(bytes[0]),
+                      static_cast<unsigned>(bytes[1]),
+                      static_cast<unsigned>(bytes[2]),
+                      static_cast<unsigned>(bytes[3]));
+        return std::string{buf};
+    case family::ipv6: {
+        // Group as eight uint16_t big-endian words, colon-separated.
+        // Skip zero-compression for simplicity at TASK-045; TASK-046
+        // can refine when telemetry/log requirements firm up.
+        std::snprintf(buf, sizeof(buf),
+                      "%x:%x:%x:%x:%x:%x:%x:%x",
+                      (bytes[0] << 8)  | bytes[1],
+                      (bytes[2] << 8)  | bytes[3],
+                      (bytes[4] << 8)  | bytes[5],
+                      (bytes[6] << 8)  | bytes[7],
+                      (bytes[8] << 8)  | bytes[9],
+                      (bytes[10] << 8) | bytes[11],
+                      (bytes[12] << 8) | bytes[13],
+                      (bytes[14] << 8) | bytes[15]);
+        return std::string{buf};
+    }
+    case family::unspec:
+    default:
+        return std::string{};
+    }
+}
+
+}  // namespace httpserver

src/httpserver.hpp

@@ -30,6 +30,10 @@
 #include "httpserver/body_kind.hpp"
 #include "httpserver/constants.hpp"
 #include "httpserver/feature_unavailable.hpp"
+#include "httpserver/hook_action.hpp"
+#include "httpserver/hook_context.hpp"
+#include "httpserver/hook_handle.hpp"
+#include "httpserver/hook_phase.hpp"
 #include "httpserver/http_arg_value.hpp"
 #include "httpserver/http_method.hpp"
 #include "httpserver/http_request.hpp"

src/httpserver/detail/webserver_impl.hpp

@@ -65,7 +65,11 @@
 #include <gnutls/gnutls.h>
 #endif  // HAVE_GNUTLS
 
+#include "httpserver/file_info.hpp"
 #include "httpserver/http_utils.hpp"
+#include "httpserver/hook_action.hpp"
+#include "httpserver/hook_context.hpp"
+#include "httpserver/hook_phase.hpp"
 #include "httpserver/detail/http_endpoint.hpp"
 #include "httpserver/detail/radix_tree.hpp"
 #include "httpserver/detail/route_cache.hpp"
@@ -282,6 +286,65 @@ class webserver_impl {
     // miss (tier_hit::none) so callers can branch deterministically.
     lookup_result lookup_v2(http_method method, const std::string& path);
 
+    // TASK-045 -- Lifecycle hook bus (skeleton, no firing yet).
+    //
+    // Per-phase callable storage. Each phase has its own
+    // std::vector<phase_entry<Sig>> because phase signatures differ
+    // (some return void, some return hook_action; ctx types differ).
+    // Concurrency:
+    //   - `hook_table_mutex_` is a shared_mutex covering ALL eleven
+    //     phase vectors. Writers (add_hook, hook_handle::remove) take
+    //     a unique_lock; future firing sites (TASK-046+) will take
+    //     a shared_lock to snapshot a phase vector before iterating.
+    //   - `any_hooks_[i]` is a short-circuit gate read with relaxed/
+    //     acquire semantics on the dispatch hot path so a phase with
+    //     no registrations costs one atomic load. Set on first
+    //     registration of a phase and cleared when the phase's vector
+    //     drops to empty (memory_order_release on both edges).
+    //   - `next_slot_id_` is a monotonic 64-bit counter. It is never
+    //     reused, so a hook_handle whose slot has already been erased
+    //     simply finds no match in remove() -- the idempotent no-op
+    //     path. 64 bits is unboundedly large in practice (centuries
+    //     at any realistic registration rate).
+    template <class Sig>
+    struct phase_entry {
+        std::uint64_t slot_id;
+        std::function<Sig> fn;
+    };
+
+    std::shared_mutex hook_table_mutex_;
+    std::atomic<std::uint64_t> next_slot_id_{1};
+    std::array<std::atomic<bool>,
+               static_cast<std::size_t>(hook_phase::count_)> any_hooks_{};
+
+    std::vector<phase_entry<void(const ::httpserver::connection_open_ctx&)>>
+        hooks_connection_opened_;
+    std::vector<phase_entry<void(const ::httpserver::accept_ctx&)>>
+        hooks_accept_decision_;
+    std::vector<phase_entry<::httpserver::hook_action(
+            ::httpserver::request_received_ctx&)>>
+        hooks_request_received_;
+    std::vector<phase_entry<::httpserver::hook_action(
+            ::httpserver::body_chunk_ctx&)>>
+        hooks_body_chunk_;
+    std::vector<phase_entry<void(const ::httpserver::route_resolved_ctx&)>>
+        hooks_route_resolved_;
+    std::vector<phase_entry<::httpserver::hook_action(
+            ::httpserver::before_handler_ctx&)>>
+        hooks_before_handler_;
+    std::vector<phase_entry<::httpserver::hook_action(
+            const ::httpserver::handler_exception_ctx&)>>
+        hooks_handler_exception_;
+    std::vector<phase_entry<::httpserver::hook_action(
+            ::httpserver::after_handler_ctx&)>>
+        hooks_after_handler_;
+    std::vector<phase_entry<void(const ::httpserver::response_sent_ctx&)>>
+        hooks_response_sent_;
+    std::vector<phase_entry<void(const ::httpserver::request_completed_ctx&)>>
+        hooks_request_completed_;
+    std::vector<phase_entry<void(const ::httpserver::connection_close_ctx&)>>
+        hooks_connection_closed_;
+
     std::shared_mutex bans_mutex;
     std::set<http::ip_representation> bans;