TASK-048: fire route_resolved + before_handler; wire 404/405/auth aliases

- Extend before_handler_ctx with `method` + `resource` fields so the
  short-circuit-capable before_handler phase exposes the surface the
  405/auth aliases need (compile-time pinned by new ctx_shape test).
- Capture `matched_path_template` (owning copy) and `matched_is_prefix`
  on modded_request inside resolve_resource_for_request so the
  route_resolved + before_handler hook contexts can carry a
  route_descriptor whose string_view is safe across hook calls and
  concurrent unregister_path racing.
- New noexcept fire_* helpers on webserver_impl: fire_route_resolved
  (void/observation-only) and fire_before_handler (short-circuit-
  capable). Both use the templated TASK-046/047 dispatch primitives.
- Wire route_resolved firing in finalize_answer (after route resolution
  — gated, observation-only). Extracted into a small file-static
  helper to keep finalize_answer under the per-function CCN ceiling.
- Wire before_handler firing in dispatch_resource_handler (after the
  post-processor teardown, before the is_allowed + handler call). A
  hook returning respond_with(r) replaces the handler outright; the
  short-circuited response goes straight to materialization.
- Conditional alias install at webserver construction: when the user
  supplied `auth_handler`, `not_found_handler`, or
  `method_not_allowed_handler` on the builder, install one
  observation-stub hook at the matching phase
  (before_handler/before_handler/route_resolved). The hooks are
  intentional no-ops; the on-the-wire behaviour continues to flow
  through the v1 dispatch path. Their presence is the alias-equivalence
  story (PRD-HOOK-REQ-009 / §4.10 / DR-012). Conditional install
  preserves PRD-HOOK-REQ-008 zero-cost-when-unused for users who never
  set those callables.
- Doxygen on the three setters explicitly states the alias relationship
  and points at the equivalent add_hook call.
- Narrow hooks_no_firing sentinel: route_resolved + before_handler now
  fire on every request, so the silent set shrinks to 4 phases.
- File-size mitigation: extract error-page helpers (not_found_page,
  method_not_allowed_page, internal_error_page, log_dispatch_error,
  run_internal_error_handler_safely) into a new sibling TU
  detail/webserver_error_pages.cpp; alias installer body lives in a
  separate detail/webserver_aliases.cpp. Both kept webserver.cpp /
  webserver_dispatch.cpp under the 500-LOC ceiling.

New tests:
  - unit/hooks_before_handler_ctx_shape_test (compile-time pin)
  - unit/hooks_alias_count_test (the four +1 alias-count contracts)
  - integ/hooks_route_resolved_miss_and_hit (acceptance criterion 1)
  - integ/hooks_before_handler_short_circuit (acceptance criterion 2)

All 63 tests pass; check-headers, check-examples, check-readme,
check-release-notes, check-doxygen, check-install-layout, and
check-hygiene all green. file-size + complexity gates pass (the two
pre-existing complexity violations on `to_string` and
`hook_handle::remove` are unaffected by this task).

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

Author: etr

specs/tasks/M5-routing-lifecycle/TASK-048.md

@@ -32,4 +32,4 @@ Wire the routing-boundary observation phase and the pre-handler short-circuit ph
 **Related Requirements:** PRD-HOOK-REQ-002, PRD-HOOK-REQ-003, PRD-HOOK-REQ-005, PRD-HOOK-REQ-009
 **Related Decisions:** DR-012, §4.10
 
-**Status:** Not Started
+**Status:** Done

specs/tasks/_index.md

@@ -130,7 +130,7 @@ Nominally: **13 sequential tasks**, each S–XL. Most other tasks parallelize of
 | TASK-045 | Hook bus skeleton (`hook_phase`, `hook_action`, `hook_handle`, `webserver::add_hook`) | M5 | Done | TASK-009, TASK-014 |
 | TASK-046 | Fire `connection_opened` / `connection_closed` / `accept_decision` | M5 | Done | TASK-045 |
 | TASK-047 | Fire `request_received` and `body_chunk` (pre-handler short-circuit) | M5 | Done | TASK-045 |
-| TASK-048 | Fire `route_resolved` and `before_handler`; wire 404/405/auth aliases | M5 | Not Started | TASK-045, TASK-027, TASK-031 |
+| TASK-048 | Fire `route_resolved` and `before_handler`; wire 404/405/auth aliases | M5 | Done | TASK-045, TASK-027, TASK-031 |
 | TASK-049 | Fire `handler_exception`; wire `internal_error_handler` alias | M5 | Not Started | TASK-045, TASK-031 |
 | TASK-050 | Fire `after_handler` (post-handler short-circuit), `response_sent`, `request_completed`; wire `log_access` alias | M5 | Not Started | TASK-045 |
 | TASK-051 | Per-route hooks (`http_resource::add_hook`) | M5 | Not Started | TASK-045, TASK-048, TASK-049, TASK-050 |

src/Makefile.am

@@ -25,7 +25,7 @@ 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
+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
 # 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>.

src/detail/webserver_aliases.cpp

@@ -0,0 +1,103 @@
+/*
+     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-048: lifecycle-hook alias installation for the three v1-derived
+// single-slot setters (auth_handler, not_found_handler,
+// method_not_allowed_handler).
+//
+// Each setter, when non-null on the create_webserver builder, registers
+// one observation hook at the matching phase:
+//
+//   - not_found_handler          -> hook_phase::route_resolved
+//   - method_not_allowed_handler -> hook_phase::before_handler
+//   - auth_handler               -> hook_phase::before_handler
+//
+// The hooks are intentionally no-op observation stubs. The on-the-wire
+// behaviour continues to flow through the existing inline dispatch
+// paths (which still consult parent->{not_found,method_not_allowed,auth}
+// _handler at the v1 call sites in webserver_dispatch.cpp /
+// webserver_error_pages.cpp). Their value is two-fold:
+//
+//   1. They make the alias relationship documented at PRD-HOOK-REQ-009 /
+//      §4.10 visible through the hook bus -- a user querying the hook
+//      count sees a slot for each setter they configured.
+//   2. They reserve the architectural seat: a future task can graduate
+//      these stubs to real hooks that perform the dispatch work,
+//      without changing the public API.
+//
+// The aliases are installed conditionally (only when the user supplied
+// a non-null callable). Users who never call any of the three setters
+// observe zero default hooks -- the zero-cost-when-unused invariant
+// (PRD-HOOK-REQ-008) holds.
+
+#include "httpserver/webserver.hpp"
+#include "httpserver/detail/webserver_impl.hpp"
+
+#include <functional>
+#include <utility>
+
+#include "httpserver/hook_action.hpp"
+#include "httpserver/hook_context.hpp"
+#include "httpserver/hook_handle.hpp"
+#include "httpserver/hook_phase.hpp"
+
+namespace httpserver {
+
+void webserver::install_default_alias_hooks_() {
+    // not_found_handler -> route_resolved (observation-only per DR-012).
+    if (not_found_handler != nullptr) {
+        std::move(add_hook(hook_phase::route_resolved,
+            std::function<void(const route_resolved_ctx&)>(
+                [](const route_resolved_ctx&) {
+                    // Observation stub. The actual 404 synthesis lives
+                    // in webserver_impl::not_found_page, consulted from
+                    // finalize_answer at the existing v1 call site.
+                })))
+            .detach();
+    }
+
+    // method_not_allowed_handler -> before_handler.
+    if (method_not_allowed_handler != nullptr) {
+        std::move(add_hook(hook_phase::before_handler,
+            std::function<hook_action(before_handler_ctx&)>(
+                [](before_handler_ctx&) {
+                    // Observation stub. The actual 405 synthesis lives
+                    // in webserver_impl::dispatch_resource_handler at the
+                    // existing v1 call site.
+                    return hook_action::pass();
+                })))
+            .detach();
+    }
+
+    // auth_handler -> before_handler.
+    if (auth_handler != nullptr) {
+        std::move(add_hook(hook_phase::before_handler,
+            std::function<hook_action(before_handler_ctx&)>(
+                [](before_handler_ctx&) {
+                    // Observation stub. The auth gate runs in
+                    // webserver_impl::apply_auth_short_circuit at the
+                    // existing v1 call site in finalize_answer.
+                    return hook_action::pass();
+                })))
+            .detach();
+    }
+}
+
+}  // namespace httpserver

src/detail/webserver_dispatch.cpp

@@ -86,74 +86,11 @@ using httpserver::http::http_utils;
 
 namespace detail {
 
-http_response webserver_impl::not_found_page(detail::modded_request* mr) const {
-    if (parent->not_found_handler != nullptr) {
-        return parent->not_found_handler(*mr->dhr);
-    }
-    return http_response::string(std::string{constants::NOT_FOUND_ERROR})
-        .with_status(http_utils::http_not_found);
-}
-
-http_response webserver_impl::method_not_allowed_page(detail::modded_request* mr) const {
-    if (parent->method_not_allowed_handler != nullptr) {
-        return parent->method_not_allowed_handler(*mr->dhr);
-    }
-    return http_response::string(std::string{constants::METHOD_ERROR})
-        .with_status(http_utils::http_method_not_allowed);
-}
-
-http_response webserver_impl::internal_error_page(
-    detail::modded_request* mr,
-    std::string_view msg,
-    bool force_our) const {
-    // TASK-031 / DR-009 §5.2 point 4: the double-fault fallback. Used when
-    // the user-supplied internal_error_handler itself threw or when the
-    // belt-and-suspenders site after get_raw_response_with_fallback fires.
-    // The body is intentionally empty and the message is intentionally
-    // ignored.
-    if (force_our) {
-        return http_response::empty()
-            .with_status(http_utils::http_internal_server_error);
-    }
-    // §5.2 point 2/3: invoke the user handler with the originating message.
-    if (parent->internal_error_handler != nullptr) {
-        return parent->internal_error_handler(*mr->dhr, msg);
-    }
-    // No handler configured: surface the message in the default body so
-    // the unset-handler path is informative for debugging. Operators who
-    // need a fixed body can wire a constant-returning handler.
-    return http_response::string(std::string{msg})
-        .with_status(http_utils::http_internal_server_error);
-}
-
-void webserver_impl::log_dispatch_error(std::string_view msg) const {
-    if (parent->log_error == nullptr) {
-        return;
-    }
-    // A misbehaving user logger must not poison the catch from inside the
-    // catch. Swallow any exception it throws; we have no recovery beyond
-    // dropping the log line.
-    try {
-        parent->log_error(std::string(msg));
-    } catch (...) {
-        // Intentionally suppressed.
-    }
-}
-
-http_response
-webserver_impl::run_internal_error_handler_safely(
-    detail::modded_request* mr,
-    std::string_view msg) const {
-    try {
-        return internal_error_page(mr, msg, /*force_our=*/false);
-    } catch (...) {
-        // §5.2 point 4: the user handler itself threw. Log generically
-        // and return an empty-body 500. No exception escapes from here.
-        log_dispatch_error("internal_error_handler threw; "
-                           "sending hardcoded empty-body 500");
-        return internal_error_page(mr, "", /*force_our=*/true);
-    }
-}
+// TASK-048: error-page helpers (not_found_page, method_not_allowed_page,
+// internal_error_page, log_dispatch_error, run_internal_error_handler_safely)
+// moved to detail/webserver_error_pages.cpp to keep this TU under the
+// 500-LOC ceiling (FILE_LOC_MAX in scripts/check-file-size.sh) once the
+// route_resolved and before_handler firing sites landed.
 
 void webserver_impl::invalidate_route_cache() {
     // Clear both the v1 and v2 caches. v1's cache is keyed on
@@ -349,12 +286,23 @@ bool webserver_impl::resolve_resource_for_request(detail::modded_request* mr,
 
     if (parent->single_resource) {
         hrm = registered_resources.begin()->second;
+        // single_resource: the one registered endpoint serves every URL.
+        // Capture its key for the route_resolved/before_handler hook ctx.
+        const auto& only = *registered_resources.begin();
+        mr->matched_path_template = only.first.get_url_complete();
+        mr->matched_is_prefix = only.first.is_family_url();
         return true;
     }
 
     auto fe = registered_resources_str.find(mr->standardized_url.c_str());
     if (fe != registered_resources_str.end()) {
         hrm = fe->second;
+        // Exact-match: the registration key equals the standardized URL.
+        // Copy into modded_request so the hook context's string_view is
+        // safe across hook calls even if a concurrent unregister_path
+        // erases the slot.
+        mr->matched_path_template = fe->first;
+        mr->matched_is_prefix = false;
         return true;
     }
 
@@ -365,6 +313,11 @@ bool webserver_impl::resolve_resource_for_request(detail::modded_request* mr,
     if (auto cached = lookup_route_cache(mr->standardized_url)) {
         hrm = cached->hrm;
         apply_extracted_params(mr, endpoint, cached->url_pars, cached->chunks);
+        // Cache layer dropped the matched endpoint at its API boundary;
+        // fall back to the requested URL as a stable approximation of
+        // the path_template (used by the route_resolved hook ctx only).
+        mr->matched_path_template = mr->standardized_url;
+        mr->matched_is_prefix = false;
         return true;
     }
 
@@ -375,6 +328,8 @@ bool webserver_impl::resolve_resource_for_request(detail::modded_request* mr,
     store_route_cache(mr->standardized_url, scan_hit->endpoint, hrm);
     apply_extracted_params(mr, endpoint, scan_hit->endpoint.get_url_pars(),
                            scan_hit->endpoint.get_chunk_positions());
+    mr->matched_path_template = scan_hit->endpoint.get_url_complete();
+    mr->matched_is_prefix = scan_hit->endpoint.is_family_url();
     return true;
 }
 
@@ -417,6 +372,31 @@ void webserver_impl::dispatch_resource_handler(detail::modded_request* mr,
             MHD_destroy_post_processor(mr->pp);
             mr->pp = nullptr;
         }
+        // TASK-048: before_handler firing site. Fires AFTER the
+        // post-processor teardown (so a hook observing form data sees
+        // it already destroyed -- consistent with the existing dispatch
+        // ordering) and BEFORE both is_allowed and the resource
+        // invocation. A short-circuit response replaces both. The
+        // any_hooks_ gate preserves zero-cost-when-unused.
+        if (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;
+            }
+        }
         if (hrm->is_allowed(mr->method_enum)) {
             // TASK-036: pointer-to-member dispatch returns http_response
             // by value (DR-004); the prvalue is moved into the