TASK-049: fire handler_exception + wire internal_error_handler alias

Convert the DR-009 §5.2 dispatch-exception path into a hookable chain.
User-added handler_exception hooks run first in registration order; the
v1 internal_error_handler becomes a last-position alias slot. The first
hook to return respond_with() wins; a throwing hook is caught and the
chain continues (DR-012 §4.10 - the one phase where exception-in-hook
does NOT abort, because the chain itself IS exception recovery). When
every hook and the alias either throw or pass(), the dispatcher emits
the hardcoded empty-body 500 directly without re-invoking the alias.

Implementation:
- webserver_impl gains handler_exception_alias_, a dedicated single-slot
  std::function written once at construction (never in the user vector,
  so its last-position ordering is structural).
- fire_handler_exception in hook_handle.cpp snapshots the user vector
  under shared_lock, iterates with per-hook try/catch, then invokes the
  alias slot.
- dispatch_resource_handler's two catch arms now route through
  handle_dispatch_exception() which takes the chain path when any user
  hook is registered OR the alias is wired, and falls back to the v1
  run_internal_error_handler_safely path otherwise.
- install_default_alias_hooks_ writes the alias slot via the extracted
  install_internal_error_alias_ helper (keeps host CCN at baseline).
- Doxygen on create_webserver::internal_error_handler and the class-
  level error-propagation contract on webserver document the alias and
  reference DR-012.

Tests (all 68 pass sequentially):
- hooks_handler_exception_chain: A=pass, B=respond_with(418), alias C
  never invoked.
- hooks_handler_exception_user_handler_throws_continues_chain: A
  throws; chain continues to B; "alpha" surfaced in log_error.
- hooks_handler_exception_fallback_to_hardcoded_500: A=pass, B throws,
  alias C throws -> empty-body 500; alias C called exactly once (pins
  no-re-entry contract).
- hooks_handler_exception_slot: unit pin that internal_error_handler
  populates the dedicated last-position slot and leaves the user
  vector at size 0.
- hooks_no_firing: handler_exception added to the not_yet_wired exclude
  list with explanatory comment.

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

Author: etr

src/detail/webserver_aliases.cpp

@@ -76,6 +76,37 @@ namespace httpserver {
 
 namespace {
 
+// TASK-049: build the std::function stored in
+// webserver_impl::handler_exception_alias_ from a (non-null) user-supplied
+// internal_error_handler callable. Extracted from
+// install_default_alias_hooks_ to keep that function under the CCN bar.
+std::function<hook_action(const handler_exception_ctx&)>
+make_internal_error_alias_(internal_error_handler_t user_handler) {
+    return [user_handler = std::move(user_handler)](
+                   const handler_exception_ctx& ctx) -> hook_action {
+        if (ctx.request == nullptr) {
+            // Defensive: caller always passes a non-null request, but
+            // stay benign if a future call site changes that contract.
+            return hook_action::pass();
+        }
+        return hook_action::respond_with(
+            user_handler(*ctx.request, ctx.message));
+    };
+}
+
+// TASK-049: install the internal_error_handler alias into the dedicated
+// last-position slot on webserver_impl. Extracted from
+// install_default_alias_hooks_ so the added `if` does not push the host
+// function over the CCN bar. See webserver_impl::handler_exception_alias_
+// for the lifetime contract (write-once-at-construction).
+void install_internal_error_alias_(
+        detail::webserver_impl* impl,
+        internal_error_handler_t user_handler) {
+    if (user_handler == nullptr) return;
+    impl->handler_exception_alias_ =
+        make_internal_error_alias_(std::move(user_handler));
+}
+
 // Serialize an allowed-method set into the comma-separated value
 // expected by the HTTP `Allow:` header. Enum-declaration order:
 // GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, TRACE, PATCH.
@@ -204,6 +235,35 @@ void webserver::install_default_alias_hooks_() {
                 })))
             .detach();
     }
+
+    // ----------------------------------------------------------------
+    // internal_error_handler -> handler_exception alias slot (LAST position).
+    // [TASK-049]
+    //
+    // This is an alias. Calling internal_error_handler(fn) on the builder
+    // makes the user callable the LAST-position fallback in the
+    // handler_exception chain (DR-012 §4.10, PRD-HOOK-REQ-009).
+    //
+    // Unlike auth_handler / method_not_allowed_handler / not_found_handler
+    // (which install at the FIRST position via add_hook so they short-
+    // circuit before user hooks), the internal_error_handler alias must
+    // fire LAST so user-added handler_exception hooks have a chance to
+    // recover first. We achieve this by storing the alias in the
+    // dedicated webserver_impl::handler_exception_alias_ slot rather than
+    // push_back-ing into the hooks_handler_exception_ vector. The fire
+    // site (fire_handler_exception in src/hook_handle.cpp) iterates the
+    // user vector first and only then invokes the alias slot.
+    //
+    // The alias body invokes the user-supplied callable with the
+    // originating exception's message and returns
+    // hook_action::respond_with(response). If the user callable itself
+    // throws, fire_handler_exception's catch arm absorbs it and returns
+    // nullopt; the caller in dispatch_resource_handler then emits the
+    // hardcoded empty-body 500 DIRECTLY without re-invoking the user
+    // callable (it has already been seen to throw on this request --
+    // calling it a second time would observably invoke the user code
+    // twice for one logical exception). See webserver_dispatch.cpp.
+    install_internal_error_alias_(impl_.get(), internal_error_handler);
 }
 
 }  // namespace httpserver

src/detail/webserver_dispatch.cpp

@@ -367,6 +367,49 @@ std::string webserver_impl::serialize_allow_methods(method_set allowed) const {
     return header_value;
 }
 
+namespace {
+
+// TASK-049: shared body of the two dispatch_resource_handler catch arms.
+// Either routes the dispatch-thrown exception through the
+// handler_exception hook chain (when any user hooks are registered or
+// the internal_error_handler alias slot is wired) or falls back to the
+// v1 run_internal_error_handler_safely path. Extracted to keep
+// dispatch_resource_handler under the per-function CCN bar.
+void handle_dispatch_exception(
+        webserver_impl* impl,
+        detail::modded_request* mr,
+        std::string_view message) {
+    if (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;
+        }
+        // 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.
+        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.
+    mr->response_.emplace(
+        impl->run_internal_error_handler_safely(mr, message));
+}
+
+}  // namespace
+
 void webserver_impl::dispatch_resource_handler(detail::modded_request* mr,
         const std::shared_ptr<http_resource>& hrm) {
     try {
@@ -412,17 +455,18 @@ void webserver_impl::dispatch_resource_handler(detail::modded_request* mr,
         }
     } catch (const std::exception& e) {
         // TASK-031 / DR-009 §5.2 point 2: handler threw std::exception.
-        // Log via error_logger, forward e.what() to internal_error_handler.
-        // run_internal_error_handler_safely contains a possible re-throw
-        // from the user handler (point 4).
+        // TASK-049 routes the exception through the handler_exception
+        // hook chain (with the internal_error_handler alias as the
+        // last-position fallback) inside handle_dispatch_exception.
         log_dispatch_error(std::string("dispatch: handler threw "
                                        "std::exception: ") + e.what());
-        mr->response_.emplace(run_internal_error_handler_safely(mr, e.what()));
+        handle_dispatch_exception(this, mr, std::string_view{e.what()});
     } catch (...) {
         // §5.2 point 3: handler threw non-std::exception. Same flow as
         // the std::exception arm but with the sentinel message.
         log_dispatch_error("dispatch: handler threw unknown exception");
-        mr->response_.emplace(run_internal_error_handler_safely(mr, "unknown exception"));
+        handle_dispatch_exception(this, mr,
+                                  std::string_view{"unknown exception"});
     }
 }
 

src/hook_handle.cpp

@@ -231,11 +231,11 @@ std::string peer_address::to_string() const {
 // ws.add_hook() / handle.remove() because we no longer hold the table
 // lock by the time the user code runs.
 
-namespace {
-
-constexpr std::size_t kHookSnapshotReserve = 8;
-
-}  // namespace
+// (Previously an unused kHookSnapshotReserve constant lived here.
+// The thread_local snapshot buffers below are now sized lazily on
+// first use; the constant was dead code as of TASK-048's perf rework.
+// Removed in TASK-049 to silence -Wunused-const-variable under
+// --enable-debug.)
 
 // fire_hooks_for_phase: shared dispatch template for all void-returning
 // lifecycle hook phases. Snapshots the caller-supplied vector under a
@@ -383,4 +383,72 @@ detail::webserver_impl::fire_before_handler(
         this, hooks_before_handler_, ctx, "before_handler");
 }
 
+// ---- fire_* (TASK-049) ---------------------------------------------------
+//
+// handler_exception is the only short-circuit-capable phase whose ctx is
+// passed as `const&` (the user cannot mutate the in-flight exception or
+// request). It also layers a dedicated single-slot alias on top of the
+// user vector (handler_exception_alias_ -- the v1 internal_error_handler
+// re-described as a last-position hook). Both of those make the body
+// awkward to express via fire_short_circuit_hooks_for_phase<Ctx&>; the
+// firing logic is inlined here. The body mirrors the template's
+// structure -- snapshot under shared_lock, release, iterate with per-hook
+// try/catch -- with an extra tail that invokes the alias slot after the
+// user vector is exhausted.
+std::optional<::httpserver::http_response>
+detail::webserver_impl::fire_handler_exception(
+    const ::httpserver::handler_exception_ctx& ctx) noexcept {
+    using EntryVec = std::vector<phase_entry<
+        ::httpserver::hook_action(
+            const ::httpserver::handler_exception_ctx&)>>;
+    try {
+        thread_local EntryVec snapshot;
+        snapshot.clear();
+        {
+            std::shared_lock lock(hook_table_mutex_);
+            snapshot = hooks_handler_exception_;
+        }
+        for (auto& entry : snapshot) {
+            try {
+                auto action = entry.fn(ctx);
+                if (!action.is_pass()) {
+                    return std::move(action).take_response();
+                }
+            } catch (const std::exception& e) {
+                log_dispatch_error(
+                    std::string("hook[handler_exception] threw: ") + e.what());
+            } catch (...) {
+                log_dispatch_error(
+                    "hook[handler_exception] threw unknown exception");
+            }
+        }
+    } catch (...) {
+        log_dispatch_error(
+            "fire_handler_exception: snapshot copy failed");
+    }
+    // Tail: invoke the alias slot, if any. Read without synchronisation;
+    // the slot is single-writer-at-construction (see webserver_impl.hpp).
+    //
+    // Throw containment: a throwing alias is logged with the legacy
+    // "internal_error_handler threw" prefix so the DR-009 §5.2 point 4
+    // log contract (and its tests in basic.cpp) is preserved verbatim
+    // even though the call site has moved from
+    // run_internal_error_handler_safely into the hook chain.
+    if (handler_exception_alias_) {
+        try {
+            auto action = handler_exception_alias_(ctx);
+            if (!action.is_pass()) {
+                return std::move(action).take_response();
+            }
+        } catch (const std::exception& e) {
+            log_dispatch_error(
+                std::string("internal_error_handler threw: ") + e.what());
+        } catch (...) {
+            log_dispatch_error(
+                "internal_error_handler threw unknown exception");
+        }
+    }
+    return std::nullopt;
+}
+
 }  // namespace httpserver

src/httpserver/create_webserver.hpp

@@ -268,6 +268,24 @@ class create_webserver {
       * If @p h is null, the default response is a 500 with the message
       * in the body (see DR-009).
       *
+      * @note This is an alias. Calling it with a non-null callable
+      *       installs the callable as a LAST-position hook at
+      *       @ref httpserver::hook_phase::handler_exception. Equivalent
+      *       to `ws.add_hook(hook_phase::handler_exception, ...)`
+      *       at webserver construction, except that the alias slot
+      *       ALWAYS fires last in the chain -- user-added
+      *       handler_exception hooks added via `add_hook` run first and
+      *       may short-circuit before the alias is reached. See DR-012
+      *       / §4.10 / PRD-HOOK-REQ-009.
+      *
+      *       Throwing-hook semantics (per DR-012): a throwing
+      *       handler_exception hook -- user-added or this alias -- is
+      *       caught and the chain CONTINUES to the next hook. If every
+      *       hook (including this alias) either throws or returns
+      *       @ref httpserver::hook_action::pass(), the dispatcher falls
+      *       back to the hardcoded empty-body 500 (DR-009 §5.2 point 4)
+      *       WITHOUT re-invoking @p h.
+      *
       * @param h @ref internal_error_handler_t callback; pass `nullptr` to clear.
       * @return reference to this builder for chaining.
       * @see webserver, not_found_handler, method_not_allowed_handler, feature_unavailable

src/httpserver/detail/webserver_impl.hpp

@@ -272,6 +272,24 @@ class webserver_impl {
     std::vector<phase_entry<::httpserver::hook_action(
             const ::httpserver::handler_exception_ctx&)>>
         hooks_handler_exception_;
+    // TASK-049: internal_error_handler alias slot. Last-position fallback
+    // in the handler_exception chain. Distinct from hooks_handler_exception_
+    // because it must fire AFTER all user hooks (DR-012 §4.10) -- the
+    // opposite of the TASK-048 aliases which run before user hooks. By
+    // sitting in a dedicated slot rather than the vector, the alias never
+    // contends for ordering when a user does add_hook(handler_exception, ...).
+    //
+    // Lifetime: written exactly once during install_default_alias_hooks_()
+    // at webserver construction, before start() is called -- the daemon is
+    // not yet running, so no synchronisation is required for the write.
+    // Read on the dispatch hot path from fire_handler_exception with no
+    // lock (single-writer-before-readers contract, same as
+    // parent->internal_error_handler). If a future task adds a runtime
+    // setter the writer MUST take hook_table_mutex_ exclusively and the
+    // reader MUST take it shared -- same pattern as the per-phase vectors.
+    std::function<::httpserver::hook_action(
+            const ::httpserver::handler_exception_ctx&)>
+        handler_exception_alias_;
     std::vector<phase_entry<::httpserver::hook_action(
             ::httpserver::after_handler_ctx&)>>
         hooks_after_handler_;

src/httpserver/detail/webserver_impl_dispatch.hpp

@@ -146,6 +146,35 @@ void fire_route_resolved(
 [[nodiscard]] std::optional<::httpserver::http_response>
 fire_before_handler(::httpserver::before_handler_ctx& ctx) noexcept;
 
+// TASK-049 -- handler_exception firing helper.
+//
+// Returns engaged optional iff some hook (user-added or the
+// internal_error_handler alias slot) short-circuited with respond_with().
+// The caller -- the catch arms in dispatch_resource_handler -- stashes
+// that response into mr->response_ and falls through to
+// materialize_and_queue_response in finalize_answer.
+//
+// Chain order:
+//   1. User-added hooks in hooks_handler_exception_ (registration order).
+//   2. handler_exception_alias_ (the v1 internal_error_handler), if set.
+// If no hook short-circuits, returns std::nullopt -- the caller then
+// emits the hardcoded empty-body 500 (DR-009 §5.2 point 4) DIRECTLY,
+// WITHOUT re-invoking the user internal_error_handler: the alias slot
+// has already had its turn at this request, so a second call would
+// observably invoke the user code twice.
+//
+// Per DR-012: a throwing hook in THIS phase is caught, logged via
+// log_dispatch_error, and the chain CONTINUES to the next hook -- this
+// is the one phase that does not abort to DR-009 §5.2 on a throwing
+// hook, because the whole point of the chain IS exception recovery.
+// The same containment applies to the alias slot.
+//
+// noexcept: same contract as fire_before_handler. Snapshot-copy failure
+// is logged and degraded to "as if no hooks were registered".
+[[nodiscard]] std::optional<::httpserver::http_response>
+fire_handler_exception(
+    const ::httpserver::handler_exception_ctx& ctx) noexcept;
+
 // TASK-031: invoke the user-supplied internal_error_handler safely.
 // On success, returns the response it produced. If the user handler
 // itself throws, logs generically via log_dispatch_error and returns

src/httpserver/webserver.hpp

@@ -140,10 +140,12 @@ namespace httpserver {
  *      other `std::exception`.
  *   6. The `log_error` callback may be invoked concurrently from multiple
  *      MHD worker threads; user implementations MUST be thread-safe.
+ *   7. Hook layering (DR-012 §4.10):
+ *      @ref hook_phase::handler_exception hooks fire BEFORE this alias;
+ *      throwing hooks are caught and the chain continues; (4) fires
+ *      without re-invoking the alias on full chain failure.
  *
- * The contract is the single source of truth for dispatch-time exception
- * handling; resource implementations are encouraged to throw rather than
- * synthesise an http_response with a 500 status.
+ * Resources are encouraged to throw rather than synthesise 500s.
 **/
 class webserver {
  public: