TASK-071 (A): wire install_not_found_alias_ and pin v1-404 behaviour

The install_not_found_alias_ hook body was previously labelled
"structurally deferred (TASK-048)". TASK-048 shipped; the deferral
comment was a misread of the design pinned in DR-012 §4.10 —
route_resolved is observation-only, so the on-wire 404 body
intentionally flows through webserver_impl::not_found_page (the v1
call site), and the alias seat at this phase exists as the
architectural anchor required by PRD-HOOK-REQ-009 (v1 setters
register as hook-bus subscriptions). The body is upgraded from a
stub-with-debt-comment to a documented no-op observation marker
that explicitly does NOT re-invoke the user handler (avoiding
double-counting of v1 observed call rates).

Pin the wire contract end-to-end with hooks_not_found_alias_test:
- default branch (no explicit handler) returns 404 "Not Found",
- custom branch returns the user handler's body once per miss,
- a user route_resolved observer co-fires alongside the alias seat
  (DR-012 §4.10 ordering — observation phase is not short-circuit-
  capable).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: etr

src/detail/webserver_aliases.cpp

@@ -283,28 +283,47 @@ void webserver::install_method_not_allowed_alias_() {
 }
 
 // ----------------------------------------------------------------
-// not_found_handler -> route_resolved (observation-only per DR-012).
+// not_found_handler -> route_resolved (observation-only per DR-012 §4.10).
 //
 // This is an alias. Calling not_found_handler(fn) registers a hook
 // at hook_phase::route_resolved. Equivalent to
 // ws.add_hook(hook_phase::route_resolved, ...).
 //
-// Structural note: route_resolved_ctx does not carry a mutable
-// response slot, so the 404 synthesis for user-provided handlers
-// remains in webserver_impl::not_found_page (called from
-// finalize_answer). The hook registers the alias in the bus so the
-// hook count is observable and the architectural seat is reserved.
+// Structural pin: per DR-012 §4.10, route_resolved is observation-only
+// — it cannot mutate the in-flight response or its delivery, and
+// route_resolved_ctx exposes no mutable response slot. The user-
+// provided not_found_handler is therefore consulted at the v1 call
+// site webserver_impl::not_found_page (invoked from finalize_answer
+// and the materialize-fallback path; see src/detail/webserver_error_pages.cpp
+// and src/detail/webserver_request.cpp). The alias seat here is the
+// architectural anchor: it reserves a stable hook[0] index at this
+// phase (per PRD-HOOK-REQ-009), it keeps the hook count observable
+// via the public hook API (verified by hooks_alias_count_test), and
+// it gives future observation-only integrations (logging, metrics)
+// a known phase boundary to subscribe alongside. The on-wire 404
+// body shape is pinned by hooks_not_found_alias_test (default and
+// custom branches) and by basic.cpp:custom_not_found_handler.
+//
+// TASK-071: previously labelled "structurally deferred (TASK-048)".
+// TASK-048 shipped; the deferral was a misread of the design — the
+// phase being observation-only is not a deferral, it IS the design
+// (see DR-012 §4.10). The body remains a documented no-op observation
+// marker; the forward-debt comment has been removed.
 void webserver::install_not_found_alias_() {
     if (not_found_handler == nullptr) return;
     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.
-                // Route_resolved_ctx does not carry mr->response so
-                // the spec's "stash into mr->response" is structurally
-                // deferred (see TASK-048 spec §action item 3 note).
+            [](const route_resolved_ctx& ctx) {
+                // Pure observation marker. The on-wire 404 body is
+                // synthesised by webserver_impl::not_found_page; this
+                // hook intentionally does NOT re-invoke the user
+                // handler (doing so would double-count the user
+                // handler's call rate and violate v1 observed-call-
+                // count semantics). DR-012 §4.10 forbids mutating the
+                // response from this phase. The discard of `ctx` makes
+                // explicit that no response-shaping decision is taken
+                // here.
+                (void) ctx;
             }))
         .detach();
 }

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 digest_challenge_format deferred http_resource http_response create_webserver create_webserver_explicit new_response_types daemon_info uri_log feature_unavailable header_hygiene_iovec header_hygiene iovec_entry http_method constants body http_response_sbo http_response_factories http_response_digest_factory http_response_move_sanitizer webserver_pimpl http_request_pimpl create_test_request http_request_arena http_request_const_getters http_request_tls_accessors http_request_operator_stream webserver_register_smartptr webserver_register_path_prefix webserver_on_methods webserver_route route_table lookup_pipeline route_table_concurrency routing_regression route_lookup_canonicalize auth_skip_normalize http_resource_allow_cache v2_dispatch_contract threadsafety_stress webserver_features webserver_ws_unavailable webserver_register_ws_smartptr webserver_dauth_unavailable consumer_fixture header_hygiene_hooks hook_api_shape hooks_no_firing hooks_accept_ctx_shape hooks_connection_lifecycle hooks_accept_decision_banned hooks_accept_decision_throwing hooks_body_chunk_ctx_shape hooks_request_received_short_circuit hooks_body_chunk_observes_progress hooks_body_chunk_short_circuit_no_leak hooks_before_handler_ctx_shape hooks_route_resolved_miss_and_hit hooks_before_handler_short_circuit hooks_alias_count hooks_alias_functional hooks_handler_exception_chain hooks_handler_exception_user_handler_throws_continues_chain hooks_handler_exception_fallback_to_hardcoded_500 hooks_handler_exception_slot hooks_response_sent_ctx_shape hooks_request_completed_ctx_shape hooks_after_handler_replaces_response hooks_after_handler_mutates_response_in_place hooks_response_sent_carries_status_bytes_timing hooks_request_completed_fires_on_early_failure hooks_log_access_alias_slot hooks_per_route_invalid_phase_throws hooks_per_route_order hooks_per_route_early_413_per_endpoint hooks_per_route_resource_destroyed_first hooks_per_route_concurrent_registration auth_handler_optional_signature no_v1_compat_shim cookie_header_sentinel cookie_render cookie_deprecation_sentinel http_response_cookie_wire http_request_cookies_parsed peer_address_to_string secure_zero_dce connection_state_sentinel connection_state_body_residue
+check_PROGRAMS = basic file_upload http_utils threaded nodelay string_utilities http_endpoint ban_system ws_start_stop authentication digest_challenge_format deferred http_resource http_response create_webserver create_webserver_explicit new_response_types daemon_info uri_log feature_unavailable header_hygiene_iovec header_hygiene iovec_entry http_method constants body http_response_sbo http_response_factories http_response_digest_factory http_response_move_sanitizer webserver_pimpl http_request_pimpl create_test_request http_request_arena http_request_const_getters http_request_tls_accessors http_request_operator_stream webserver_register_smartptr webserver_register_path_prefix webserver_on_methods webserver_route route_table lookup_pipeline route_table_concurrency routing_regression route_lookup_canonicalize auth_skip_normalize http_resource_allow_cache v2_dispatch_contract threadsafety_stress webserver_features webserver_ws_unavailable webserver_register_ws_smartptr webserver_dauth_unavailable consumer_fixture header_hygiene_hooks hook_api_shape hooks_no_firing hooks_accept_ctx_shape hooks_connection_lifecycle hooks_accept_decision_banned hooks_accept_decision_throwing hooks_body_chunk_ctx_shape hooks_request_received_short_circuit hooks_body_chunk_observes_progress hooks_body_chunk_short_circuit_no_leak hooks_before_handler_ctx_shape hooks_route_resolved_miss_and_hit hooks_before_handler_short_circuit hooks_alias_count hooks_alias_functional hooks_handler_exception_chain hooks_handler_exception_user_handler_throws_continues_chain hooks_handler_exception_fallback_to_hardcoded_500 hooks_handler_exception_slot hooks_response_sent_ctx_shape hooks_request_completed_ctx_shape hooks_after_handler_replaces_response hooks_after_handler_mutates_response_in_place hooks_response_sent_carries_status_bytes_timing hooks_request_completed_fires_on_early_failure hooks_log_access_alias_slot hooks_per_route_invalid_phase_throws hooks_per_route_order hooks_per_route_early_413_per_endpoint hooks_per_route_resource_destroyed_first hooks_per_route_concurrent_registration hooks_not_found_alias auth_handler_optional_signature no_v1_compat_shim cookie_header_sentinel cookie_render cookie_deprecation_sentinel http_response_cookie_wire http_request_cookies_parsed peer_address_to_string secure_zero_dce connection_state_sentinel connection_state_body_residue
 
 MOSTLYCLEANFILES = *.gcda *.gcno *.gcov
 
@@ -497,6 +497,13 @@ no_v1_compat_shim_SOURCES = unit/no_v1_compat_shim_test.cpp
 # that short-circuits the chain (not a no-op stub): a user hook registered
 # after the alias does NOT fire for method-not-allowed requests.
 hooks_alias_functional_SOURCES = integ/hooks_alias_functional_test.cpp
+# TASK-071 sub-item A. End-to-end pin for the not_found_handler ->
+# route_resolved alias seat: default-branch "Not Found" body, custom-branch
+# user-handler body, and DR-012 §4.10 ordering (a user route_resolved hook
+# co-fires alongside the alias seat — observation phase is not short-
+# circuit-capable). Cross-pins the wire contract so a future structural
+# refactor of install_not_found_alias_ cannot silently regress it.
+hooks_not_found_alias_SOURCES = integ/hooks_not_found_alias_test.cpp
 
 # TASK-049 -- handler_exception firing site and internal_error_handler
 # alias slot. Adds:

test/integ/hooks_not_found_alias_test.cpp

@@ -0,0 +1,179 @@
+/*
+     This file is part of libhttpserver
+     Copyright (C) 2011-2026 Sebastiano Merlino
+*/
+
+// TASK-071: end-to-end pin for the not_found_handler -> route_resolved
+// alias seat.
+//
+// Sub-item A from TASK-071 — replace the empty stub callback in
+// webserver::install_not_found_alias_ with the wired observation hook
+// documented per DR-012 §4.10. The on-wire 404 body still flows through
+// webserver_impl::not_found_page (route_resolved is observation-only;
+// the response slot is not exposed at this phase), but the alias seat
+// in the bus must be a real hook so:
+//
+//   (1) PRD-HOOK-REQ-009: v1 setters expose themselves as hook-bus
+//       subscriptions (verified by hooks_alias_count_test already; we
+//       cross-pin the on-wire behaviour here).
+//   (2) AC-1: a fresh webserver with no explicit not_found_handler
+//       returns 404 with the canonical "Not Found" body.
+//   (3) AC-1 (custom branch): a webserver with a user not_found_handler
+//       returns 404 with the user-supplied body on a miss path.
+//   (4) DR-012 §4.10 ordering pin: user-registered route_resolved hooks
+//       still fire alongside the alias seat (observation phase is not
+//       short-circuit-capable). A user observation hook must still see
+//       the miss.
+
+#include <curl/curl.h>
+
+#include <atomic>
+#include <chrono>
+#include <functional>
+#include <memory>
+#include <string>
+#include <thread>
+
+#include "./httpserver.hpp"
+#include "./littletest.hpp"
+
+using httpserver::create_webserver;
+using httpserver::hook_phase;
+using httpserver::http_request;
+using httpserver::http_response;
+using httpserver::route_resolved_ctx;
+using httpserver::webserver;
+
+#define PORT_DEFAULT 8211
+#define PORT_CUSTOM  8212
+#define PORT_ORDER   8213
+
+namespace {
+
+size_t writefunc(void* ptr, size_t size, size_t nmemb, std::string* s) {
+    s->append(reinterpret_cast<char*>(ptr), size * nmemb);
+    return size * nmemb;
+}
+
+CURLcode get_url(int port, const std::string& path,
+                 long* http_code,  // NOLINT(runtime/int)
+                 std::string* body) {
+    CURL* curl = curl_easy_init();
+    if (curl == nullptr) return CURLE_FAILED_INIT;
+    std::string url = "http://127.0.0.1:" + std::to_string(port) + path;
+    curl_easy_setopt(curl, CURLOPT_URL, url.c_str());
+    curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, writefunc);
+    curl_easy_setopt(curl, CURLOPT_WRITEDATA, body);
+    CURLcode rc = curl_easy_perform(curl);
+    if (http_code != nullptr) {
+        curl_easy_getinfo(curl, CURLINFO_RESPONSE_CODE, http_code);
+    }
+    curl_easy_cleanup(curl);
+    return rc;
+}
+
+}  // namespace
+
+LT_BEGIN_SUITE(hooks_not_found_alias_suite)
+    void set_up() {}
+    void tear_down() {}
+LT_END_SUITE(hooks_not_found_alias_suite)
+
+// AC-1, default branch. With no explicit not_found_handler, a request
+// for a missing route returns 404 with the canonical "Not Found" body.
+// Pinned end-to-end so any future structural refactor of
+// install_not_found_alias_ cannot silently regress the wire contract.
+LT_BEGIN_AUTO_TEST(hooks_not_found_alias_suite,
+                   not_found_alias_default_body_when_no_user_handler)
+    webserver ws{create_webserver(PORT_DEFAULT)};
+    ws.start(false);
+    std::this_thread::sleep_for(std::chrono::milliseconds(50));
+
+    long code = 0;  // NOLINT(runtime/int)
+    std::string body;
+    LT_CHECK_EQ(get_url(PORT_DEFAULT, "/nonexistent", &code, &body), CURLE_OK);
+
+    ws.stop();
+
+    LT_CHECK_EQ(code, 404L);
+    // constants::NOT_FOUND_ERROR == "Not Found" (src/httpserver/constants.hpp:51).
+    LT_CHECK_EQ(body, std::string("Not Found"));
+LT_END_AUTO_TEST(not_found_alias_default_body_when_no_user_handler)
+
+// AC-1, custom branch. With an explicit not_found_handler, a request for
+// a missing route returns 404 with the user-supplied body. The alias
+// seat is wired (verified separately by hooks_alias_count_test), and the
+// on-wire 404 body flows through webserver_impl::not_found_page calling
+// the same handler — the user handler is invoked exactly once per miss
+// (not double-counted by the alias hook body, which is observation-only).
+LT_BEGIN_AUTO_TEST(hooks_not_found_alias_suite,
+                   not_found_alias_invokes_user_handler_on_miss_with_v1_body)
+    std::atomic<int> handler_calls{0};
+    auto user_not_found = [&handler_calls](const http_request&) {
+        handler_calls.fetch_add(1, std::memory_order_relaxed);
+        return http_response::string("CUSTOM_404").with_status(404);
+    };
+
+    webserver ws{create_webserver(PORT_CUSTOM).not_found_handler(user_not_found)};
+    ws.start(false);
+    std::this_thread::sleep_for(std::chrono::milliseconds(50));
+
+    long code = 0;  // NOLINT(runtime/int)
+    std::string body;
+    LT_CHECK_EQ(get_url(PORT_CUSTOM, "/nonexistent", &code, &body), CURLE_OK);
+
+    ws.stop();
+
+    LT_CHECK_EQ(code, 404L);
+    LT_CHECK_EQ(body, std::string("CUSTOM_404"));
+    // The user handler fires exactly once. The alias hook body is a
+    // pure observation marker (DR-012 §4.10); it does NOT re-invoke
+    // the user handler. The on-wire body comes from not_found_page.
+    LT_CHECK_EQ(handler_calls.load(), 1);
+LT_END_AUTO_TEST(not_found_alias_invokes_user_handler_on_miss_with_v1_body)
+
+// DR-012 §4.10 ordering pin. The alias seat installs hook[0] at
+// route_resolved when not_found_handler is set; a user-added observation
+// hook becomes hook[1]. Both fire on a miss (observation phase is not
+// short-circuit-capable). Cross-pins that the alias upgrade did not
+// accidentally suppress co-registered user hooks.
+LT_BEGIN_AUTO_TEST(hooks_not_found_alias_suite,
+                   not_found_alias_does_not_suppress_user_route_resolved_hook)
+    std::atomic<int> user_observer_calls{0};
+    std::atomic<int> user_observer_misses{0};
+    auto user_not_found = [](const http_request&) {
+        return http_response::string("CUSTOM_404").with_status(404);
+    };
+
+    webserver ws{create_webserver(PORT_ORDER).not_found_handler(user_not_found)};
+
+    auto h = ws.add_hook(hook_phase::route_resolved,
+        std::function<void(const route_resolved_ctx&)>(
+            [&user_observer_calls, &user_observer_misses]
+            (const route_resolved_ctx& ctx) {
+                user_observer_calls.fetch_add(1, std::memory_order_relaxed);
+                if (!ctx.matched.has_value()) {
+                    user_observer_misses.fetch_add(1,
+                                                   std::memory_order_relaxed);
+                }
+            }));
+
+    ws.start(false);
+    std::this_thread::sleep_for(std::chrono::milliseconds(50));
+
+    long code = 0;  // NOLINT(runtime/int)
+    std::string body;
+    LT_CHECK_EQ(get_url(PORT_ORDER, "/nonexistent", &code, &body), CURLE_OK);
+
+    ws.stop();
+
+    LT_CHECK_EQ(code, 404L);
+    LT_CHECK_EQ(body, std::string("CUSTOM_404"));
+    // User observation hook fired once on the miss path.
+    LT_CHECK_EQ(user_observer_calls.load(), 1);
+    LT_CHECK_EQ(user_observer_misses.load(), 1);
+LT_END_AUTO_TEST(not_found_alias_does_not_suppress_user_route_resolved_hook)
+
+LT_BEGIN_AUTO_TEST_ENV()
+    AUTORUN_TESTS()
+LT_END_AUTO_TEST_ENV()