TASK-051: per-route hooks via http_resource::add_hook

Add a per-resource scope to the hook bus, restricted to the five
post-route-resolution phases (before_handler, handler_exception,
after_handler, response_sent, request_completed). Other phases throw
std::invalid_argument naming the constraint.

Storage uses a PIMPL (detail::resource_hook_table) reached through a
single std::shared_ptr<> on http_resource (lazily allocated on first
add_hook), so resources that never register a hook pay only the 16-byte
pointer plus a null-check on the dispatch hot path. The sizeof cap on
http_resource is bumped accordingly (vptr + shared_ptr + method_set +
padding); bench_sizeof_http_resource and the in-header static_assert
reflect the new cap.

The per-route chain fires at each of the five applicable phases AFTER
the server-wide chain and BEFORE checking for a server-wide short-circuit
result -- if server-wide short-circuited, the per-route chain is skipped
(response is already fixed). modded_request carries a
weak_ptr<http_resource> populated in finalize_answer once the route
resolves; fire_response_sent_gated and fire_request_completed_gated
lock() it to fire the per-route chain after the server-wide one. If the
resource was unregistered between dispatch and completion, lock()
returns null and the per-route chain is naturally skipped.

hook_handle gains a weak_ptr<detail::resource_hook_table> so per-route
handles drain through the table's writer lock; if the resource is
destroyed before the handle, remove() is a no-op. The handle size cap
is bumped from 32 to 48 in the unit shape test.

Lock order documented in §5.6:
route_table_mutex_ -> resource hook_table_mutex_ -> server-wide
hook_table_mutex_. Exercised by hooks_per_route_concurrent_registration
under TSan.

Carved out of webserver_request.cpp:
- fire_before_handler_gated as a member on webserver_impl (definition
  in webserver_finalize.cpp alongside the other gated-fire helpers) so
  finalize_answer stays under CCN_MAX after the per-route branch
  doubles the local branch count.

Carved out of hook_handle.cpp:
- remove_per_route static helper for the per-route remove() branch so
  the host function stays at its pre-task CCN.

Five new integ tests + the unit hook_api_shape pin extension cover:
- invalid-phase rejection
- server-wide-before-per-route ordering on response_sent
- different early-413 size policies on two endpoints
- resource-destroyed-before-handle no-op + no UAF (ASan)
- concurrent registration on resource R from inside a handler on
  resource Q (TSan)

Closes TASK-051.

Author: etr

src/Makefile.am

@@ -25,11 +25,11 @@ 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_request_auth.cpp http_response.cpp create_webserver.cpp create_test_request.cpp websocket_handler.cpp hook_handle.cpp detail/http_endpoint.cpp detail/body.cpp detail/ip_representation.cpp detail/http_request_impl.cpp detail/http_request_impl_tls.cpp detail/webserver_setup.cpp detail/webserver_register.cpp detail/webserver_routes.cpp detail/webserver_callbacks.cpp detail/webserver_callbacks_lifecycle.cpp detail/webserver_websocket.cpp detail/webserver_dispatch.cpp detail/webserver_request.cpp detail/webserver_body_pipeline.cpp detail/webserver_error_pages.cpp detail/webserver_aliases.cpp detail/webserver_finalize.cpp
+libhttpserver_la_SOURCES = string_utilities.cpp webserver.cpp http_utils.cpp file_info.cpp http_request.cpp http_request_auth.cpp http_response.cpp http_resource.cpp create_webserver.cpp create_test_request.cpp websocket_handler.cpp hook_handle.cpp peer_address.cpp resource_hook_table.cpp detail/http_endpoint.cpp detail/body.cpp detail/ip_representation.cpp detail/http_request_impl.cpp detail/http_request_impl_tls.cpp detail/webserver_setup.cpp detail/webserver_register.cpp detail/webserver_routes.cpp detail/webserver_callbacks.cpp detail/webserver_callbacks_lifecycle.cpp detail/webserver_websocket.cpp detail/webserver_dispatch.cpp detail/webserver_request.cpp detail/webserver_body_pipeline.cpp detail/webserver_error_pages.cpp detail/webserver_aliases.cpp detail/webserver_finalize.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/webserver_impl_dispatch.hpp httpserver/detail/connection_state.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 httpserver/detail/route_tier.hpp gettext.h
+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/webserver_impl_dispatch.hpp httpserver/detail/connection_state.hpp httpserver/detail/http_request_impl.hpp httpserver/detail/resource_hook_table.hpp httpserver/detail/route_entry.hpp httpserver/detail/lambda_resource.hpp httpserver/detail/radix_tree.hpp httpserver/detail/route_cache.hpp httpserver/detail/route_tier.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/webserver_routes.hpp httpserver/webserver_websocket.hpp httpserver/webserver_hooks.hpp httpserver/websocket_handler.hpp httpserver/http_utils.hpp httpserver/ip_representation.hpp httpserver/file_info.hpp httpserver/http_request.hpp httpserver/http_request_auth.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/detail/webserver_dispatch.cpp

@@ -65,6 +65,7 @@
 #include "httpserver/detail/http_endpoint.hpp"
 #include "httpserver/detail/lambda_resource.hpp"
 #include "httpserver/detail/modded_request.hpp"
+#include "httpserver/detail/resource_hook_table.hpp"
 #include "httpserver/http_request.hpp"
 #include "httpserver/http_resource.hpp"
 #include "httpserver/http_response.hpp"
@@ -379,31 +380,45 @@ void handle_dispatch_exception(
         webserver_impl* impl,
         detail::modded_request* mr,
         std::string_view message) {
-    if (impl->any_hooks_[static_cast<std::size_t>(
+    // TASK-051: per-route handler_exception. weak_ptr was set on mr in
+    // finalize_answer before dispatch_resource_handler was called.
+    auto res = mr->resource_weak_.lock();
+    auto* rtable = res ? res->hook_table_raw_() : nullptr;
+    const bool per_route = rtable != nullptr &&
+        rtable->any_hooks(hook_phase::handler_exception);
+    const bool server_chain =
+        impl->any_hooks_[static_cast<std::size_t>(
                 hook_phase::handler_exception)]
             .load(std::memory_order_relaxed) ||
-        impl->handler_exception_alias_) {
-        handler_exception_ctx ctx{
-            /*request=*/mr->dhr.get(),
-            /*exception=*/std::current_exception(),
-            /*message=*/message};
-        if (auto sc = impl->fire_handler_exception(ctx)) {
-            mr->response_.emplace(std::move(*sc));
-            return;
+        impl->handler_exception_alias_;
+
+    if (server_chain || per_route) {
+        handler_exception_ctx ctx{mr->dhr.get(),
+            std::current_exception(), message};
+        if (server_chain) {
+            if (auto sc = impl->fire_handler_exception(ctx)) {
+                mr->response_.emplace(std::move(*sc));
+                return;
+            }
+        }
+        if (per_route) {
+            // Per-route chain runs AFTER server-wide. Same DR-009 §5.2
+            // semantics: respond_with() short-circuits the chain.
+            if (auto sc = rtable->fire_handler_exception(ctx,
+                    [impl](std::string_view m) {
+                        impl->log_dispatch_error(std::string(m));
+                    })) {
+                mr->response_.emplace(std::move(*sc));
+                return;
+            }
         }
-        // DR-009 §5.2 point 4 extended: every hook (and the alias) ran
-        // without producing a response -- emit the hardcoded empty-body
-        // 500 directly. Do NOT re-enter run_internal_error_handler_safely
-        // here; the alias slot has already invoked the user callable on
-        // this request.
+        // §5.2 point 4: every hook (and the alias) ran without a
+        // response -- emit the hardcoded empty-body 500 directly.
         mr->response_.emplace(
             impl->internal_error_page(mr, "", /*force_our=*/true));
         return;
     }
-    // Backwards-compat fast path: no handler_exception hooks AND no
-    // alias wired (the v1 builder did not call internal_error_handler).
-    // Use the existing safe-call site so the unset-alias default body
-    // (which surfaces the message) still applies.
+    // Backwards-compat fast path: no hook chain at all.
     mr->response_.emplace(
         impl->run_internal_error_handler_safely(mr, message));
 }

src/detail/webserver_finalize.cpp

@@ -45,19 +45,89 @@
 
 #include <chrono>
 #include <cstddef>
+#include <memory>
+#include <optional>
+#include <string>
+#include <string_view>
 #include <utility>
 
 #include "httpserver/detail/body.hpp"
 #include "httpserver/detail/modded_request.hpp"
+#include "httpserver/detail/resource_hook_table.hpp"
 #include "httpserver/hook_action.hpp"
 #include "httpserver/hook_context.hpp"
 #include "httpserver/hook_phase.hpp"
 #include "httpserver/http_request.hpp"
+#include "httpserver/http_resource.hpp"
 #include "httpserver/http_response.hpp"
 
 namespace httpserver {
 namespace detail {
 
+namespace {
+
+// TASK-051: helper to fetch the per-route hook table (if any) from
+// the request's resource_weak_ slot. Holds the shared_ptr<http_resource>
+// alive in `res_out` so the caller can keep the table pointer valid.
+// Returns nullptr when no per-route table exists for this request.
+resource_hook_table* per_route_table(detail::modded_request* mr,
+                                     std::shared_ptr<http_resource>& res_out) {
+    if (mr->resource_weak_.expired()) return nullptr;
+    res_out = mr->resource_weak_.lock();
+    if (!res_out) return nullptr;
+    return res_out->hook_table_raw_();
+}
+
+}  // namespace
+
+// TASK-051: gated fire of before_handler, server-wide AND per-route,
+// with short-circuit detection. Carved out of finalize_answer to keep
+// the host function under CCN_MAX after TASK-051's per-route extension
+// roughly doubled the local branch count. Returns true iff either chain
+// short-circuited (mr->response_ has already been emplaced; caller must
+// route straight to materialize_and_queue_response). False means both
+// chains passed (or both gates were closed) and dispatch should proceed.
+bool webserver_impl::fire_before_handler_gated(
+        detail::modded_request* mr,
+        const std::shared_ptr<http_resource>& hrm) {
+    const bool server_gate =
+        any_hooks_[static_cast<std::size_t>(hook_phase::before_handler)]
+            .load(std::memory_order_relaxed);
+    auto* per_route_table = hrm->hook_table_raw_();
+    const bool per_route_gate = per_route_table != nullptr &&
+        per_route_table->any_hooks(hook_phase::before_handler);
+    if (!server_gate && !per_route_gate) return false;
+
+    std::optional<route_descriptor> desc;
+    if (!mr->matched_path_template.empty()) {
+        desc = route_descriptor{
+            /*path_template=*/std::string_view{mr->matched_path_template},
+            /*methods=*/hrm->get_allowed_methods(),
+            /*is_prefix=*/mr->matched_is_prefix};
+    }
+    before_handler_ctx ctx{
+        /*request=*/mr->dhr.get(),
+        /*matched=*/std::move(desc),
+        /*method=*/mr->method_enum,
+        /*resource=*/hrm.get()};
+    if (server_gate) {
+        if (auto sc = fire_before_handler(ctx)) {
+            mr->response_.emplace(std::move(*sc));
+            return true;
+        }
+    }
+    if (per_route_gate) {
+        if (auto sc = per_route_table->fire_before_handler(ctx,
+                [this](std::string_view m) {
+                    log_dispatch_error(std::string(m));
+                })) {
+            mr->response_.emplace(std::move(*sc));
+            return true;
+        }
+    }
+    return false;
+}
+
 // TASK-050: gated fire of after_handler. Fires between
 // dispatch_resource_handler (which populates mr->response_) and
 // materialize_and_queue_response. A hook returning respond_with(...)
@@ -70,21 +140,37 @@ namespace detail {
 // The pre-handler short-circuit branch (mr->skip_handler) is handled
 // upstream in finalize_answer and never reaches this site.
 void webserver_impl::fire_after_handler_gated(detail::modded_request* mr) {
-    if (!any_hooks_[static_cast<std::size_t>(hook_phase::after_handler)]
-            .load(std::memory_order_relaxed)) {
-        return;
-    }
+    const bool server_gate =
+        any_hooks_[static_cast<std::size_t>(hook_phase::after_handler)]
+            .load(std::memory_order_relaxed);
+    std::shared_ptr<http_resource> res;
+    auto* rtable = per_route_table(mr, res);
+    const bool route_gate = rtable != nullptr &&
+        rtable->any_hooks(hook_phase::after_handler);
+
+    if (!server_gate && !route_gate) return;
     if (!mr->response_) return;  // defensive: never fire without a response
-    after_handler_ctx ctx{
-        /*request=*/mr->dhr.get(),
-        /*response=*/&*mr->response_,
-    };
-    if (auto sc = fire_after_handler(ctx)) {
-        // Short-circuit: REPLACE mr->response_ with the hook's response.
-        // emplace() destroys the old http_response in mr->response_
-        // first (DR-010), tearing down any deferred-producer captures
-        // here rather than later in ~modded_request.
-        mr->response_.emplace(std::move(*sc));
+
+    after_handler_ctx ctx{mr->dhr.get(), &*mr->response_};
+    if (server_gate) {
+        if (auto sc = fire_after_handler(ctx)) {
+            // Short-circuit: REPLACE mr->response_ (DR-010 -- emplace
+            // destroys the old response, releasing any deferred captures
+            // here rather than later in ~modded_request). Per-route
+            // chain ALSO sees the replaced response, so refresh ctx.
+            mr->response_.emplace(std::move(*sc));
+            ctx.response = &*mr->response_;
+        }
+    }
+    // TASK-051: per-route chain AFTER the server-wide chain. Same
+    // short-circuit semantics (respond_with replaces the response).
+    if (route_gate) {
+        if (auto sc = rtable->fire_after_handler(ctx,
+                [this](std::string_view m) {
+                    log_dispatch_error(std::string(m));
+                })) {
+            mr->response_.emplace(std::move(*sc));
+        }
     }
 }
 
@@ -96,34 +182,35 @@ void webserver_impl::fire_after_handler_gated(detail::modded_request* mr) {
 // size from http_response::body_->size(); for deferred/pipe bodies this
 // is 0 and consumers should fall back to the Content-Length header.
 void webserver_impl::fire_response_sent_gated(detail::modded_request* mr) {
-    const bool user_hooks_present =
+    const bool server_gate =
         any_hooks_[static_cast<std::size_t>(hook_phase::response_sent)]
             .load(std::memory_order_relaxed);
-    if (!user_hooks_present && !log_access_alias_) return;
-    if (!mr->response_) return;  // defensive
+    std::shared_ptr<http_resource> res;
+    auto* rtable = per_route_table(mr, res);
+    const bool route_gate = rtable != nullptr &&
+        rtable->any_hooks(hook_phase::response_sent);
 
-    std::size_t bytes = 0;
-    if (mr->response_->body_ != nullptr) {
-        bytes = mr->response_->body_->size();
-    }
-    // Only compute elapsed when user-registered response_sent hooks are
-    // present and will read the field. If only the log_access alias slot
-    // fires, elapsed is unused by the alias lambda (which reads only path
-    // and method), so we skip the steady_clock::now() call (typically
-    // 20-50 ns on Linux/macOS via VDSO) to avoid per-request overhead
-    // when the server is configured with log_access but no add_hook hooks.
-    const auto elapsed = user_hooks_present
+    if (!server_gate && !route_gate && !log_access_alias_) return;
+    if (!mr->response_) return;
+
+    const std::size_t bytes = (mr->response_->body_ != nullptr)
+        ? mr->response_->body_->size() : 0;
+    // elapsed is consumed by user hooks (server-wide + per-route), not
+    // by the log_access alias. Skip the steady_clock::now() call when
+    // only the alias slot is going to fire.
+    const auto elapsed = (server_gate || route_gate)
         ? std::chrono::duration_cast<std::chrono::nanoseconds>(
               std::chrono::steady_clock::now() - mr->start_time)
         : std::chrono::nanoseconds::zero();
-    response_sent_ctx ctx{
-        /*request=*/mr->dhr.get(),
-        /*response=*/&*mr->response_,
-        /*status=*/mr->response_->get_status(),
-        /*bytes_queued=*/bytes,
-        /*elapsed=*/elapsed,
-    };
+    response_sent_ctx ctx{mr->dhr.get(), &*mr->response_,
+        mr->response_->get_status(), bytes, elapsed};
     fire_response_sent(ctx);
+    // TASK-051: per-route chain AFTER server-wide + its alias slot.
+    // response_sent is observation-only; no short-circuit logic.
+    if (route_gate) {
+        rtable->fire_response_sent(ctx,
+            [this](std::string_view m) { log_dispatch_error(std::string(m)); });
+    }
 }
 
 // TASK-050: gated fire of request_completed. Fires from
@@ -139,8 +226,25 @@ void webserver_impl::fire_response_sent_gated(detail::modded_request* mr) {
 void webserver_impl::fire_request_completed_gated(
         detail::modded_request* mr,
         enum MHD_RequestTerminationCode toe) {
-    if (!any_hooks_[static_cast<std::size_t>(hook_phase::request_completed)]
-            .load(std::memory_order_relaxed)) {
+    const bool server_gate =
+        any_hooks_[static_cast<std::size_t>(hook_phase::request_completed)]
+            .load(std::memory_order_relaxed);
+
+    // TASK-051: per-route gate. lock() may return null if the resource
+    // was unregistered between dispatch and completion (per the action
+    // item contract: skip the per-route chain in that case).
+    std::shared_ptr<http_resource> res;
+    detail::resource_hook_table* rtable = nullptr;
+    if (!mr->resource_weak_.expired()) {
+        res = mr->resource_weak_.lock();
+        if (res) {
+            rtable = res->hook_table_raw_();
+        }
+    }
+    const bool per_route_present = rtable != nullptr &&
+        rtable->any_hooks(hook_phase::request_completed);
+
+    if (!server_gate && !per_route_present) {
         return;
     }
     const http_response* resp_ptr =
@@ -157,7 +261,14 @@ void webserver_impl::fire_request_completed_gated(
         /*succeeded=*/(toe == MHD_REQUEST_TERMINATED_COMPLETED_OK),
         /*duration=*/std::chrono::steady_clock::now() - mr->start_time,
     };
-    fire_request_completed(ctx);
+    if (server_gate) {
+        fire_request_completed(ctx);
+    }
+    // TASK-051: per-route chain fires AFTER the server-wide chain.
+    if (per_route_present) {
+        rtable->fire_request_completed(ctx,
+            [this](std::string_view m) { log_dispatch_error(std::string(m)); });
+    }
 }
 
 }  // namespace detail

src/detail/webserver_request.cpp

@@ -67,6 +67,7 @@
 #include "httpserver/detail/http_endpoint.hpp"
 #include "httpserver/detail/lambda_resource.hpp"
 #include "httpserver/detail/modded_request.hpp"
+#include "httpserver/detail/resource_hook_table.hpp"
 #include "httpserver/http_request.hpp"
 #include "httpserver/http_resource.hpp"
 #include "httpserver/http_response.hpp"
@@ -303,32 +304,29 @@ MHD_Result webserver_impl::finalize_answer(MHD_Connection* connection,
     std::shared_ptr<http_resource> hrm;
     bool found = resolve_resource_for_request(mr, hrm);
 
+    // TASK-051: capture the resolved resource on the request so the
+    // tail-end firing helpers (fire_response_sent_gated /
+    // fire_request_completed_gated) can fire the per-route hook chain
+    // after the server-wide one. weak_ptr does not keep the resource
+    // alive; the local `hrm` shared_ptr does that for the duration of
+    // finalize_answer, after which mr->response_ no longer references
+    // the resource directly.
+    if (found) {
+        mr->resource_weak_ = hrm;
+    }
+
     fire_route_resolved_gated(this, mr, found, hrm);
 
-    // TASK-048: fire before_handler from finalize_answer (not from inside
-    // dispatch_resource_handler). This ensures auth and method-not-allowed
-    // alias hooks run as part of the unified before_handler chain, with
-    // the auth alias as the first hook (registered in
-    // install_default_alias_hooks_). The gate preserves zero-cost-when-unused.
-    if (found &&
-        any_hooks_[static_cast<std::size_t>(hook_phase::before_handler)]
-            .load(std::memory_order_relaxed)) {
-        std::optional<route_descriptor> desc;
-        if (!mr->matched_path_template.empty()) {
-            desc = route_descriptor{
-                /*path_template=*/std::string_view{mr->matched_path_template},
-                /*methods=*/hrm->get_allowed_methods(),
-                /*is_prefix=*/mr->matched_is_prefix};
-        }
-        before_handler_ctx ctx{
-            /*request=*/mr->dhr.get(),
-            /*matched=*/std::move(desc),
-            /*method=*/mr->method_enum,
-            /*resource=*/hrm.get()};
-        if (auto sc = fire_before_handler(ctx)) {
-            mr->response_.emplace(std::move(*sc));
-            return materialize_and_queue_response(connection, mr);
-        }
+    // TASK-048 / TASK-051: fire before_handler from finalize_answer (not
+    // from inside dispatch_resource_handler). This ensures auth and
+    // method-not-allowed alias hooks run as part of the unified
+    // before_handler chain, with the auth alias as the first hook
+    // (registered in install_default_alias_hooks_). Per-route firing is
+    // included by the helper (see fire_before_handler_gated). If either
+    // chain short-circuited, mr->response_ is already populated and we
+    // route straight to materialize.
+    if (found && fire_before_handler_gated(mr, hrm)) {
+        return materialize_and_queue_response(connection, mr);
     }
 
     if (found) {