TASK-050: fire after_handler / response_sent / request_completed + log_access alias

Wires the three tail-end lifecycle hook phases and converts log_access into
a documented response_sent alias slot. Closes the structural holes left
open in TASK-045: issues #281 and #69 (CLF / time-taken access logging)
are now writable entirely in user code via add_hook(response_sent, ...).

Hook firing sites:
  - after_handler: fires in finalize_answer between dispatch_resource_handler
    (or 404 synthesis) and materialize_and_queue_response. Short-circuit-
    capable -- hook_action::respond_with(r) REPLACES mr->response_; a
    pass()-returning hook may have mutated *mr->response_ in place via
    ctx.response->with_header(...).
  - response_sent: fires in materialize_and_queue_response immediately
    after MHD_queue_response and BEFORE MHD_destroy_response. Carries the
    structured ctx fields {status, bytes_queued, elapsed} that issues #281
    and #69 asked for.
  - request_completed: fires from webserver_impl::request_completed BEFORE
    the modded_request is destroyed. ctx carries {resp (nullable),
    succeeded, duration}. A request_received short-circuit (e.g., a 413
    rejection) still reports succeeded == true because MHD drove the
    request to ordinary completion.

log_access(fn) alias:
  - Dedicated webserver_impl::log_access_alias_ single-slot member,
    mirroring TASK-049's handler_exception_alias_ contract (single-writer-
    at-construction). fire_response_sent invokes the slot AFTER the user
    vector so user hooks observe the response before the legacy logger
    formats it.
  - The v1 inline access_log call site in answer_to_connection is removed;
    the alias now emits "<path> METHOD: <method>" from a response_sent
    hook, preserving the existing log_access_callback integ test's
    substring assertions.

Misc structural changes:
  - modded_request::start_time -- captured once in answer_to_connection's
    fresh-request branch; consumed by response_sent.elapsed and
    request_completed.duration.
  - response_sent_ctx + request_completed_ctx grown with the spec'd
    fields (status, bytes_queued, elapsed, resp, succeeded).
  - webserver_request.cpp split: validate_websocket_handshake /
    complete_websocket_upgrade / try_handle_websocket_upgrade moved to
    webserver_websocket.cpp, and the new fire_*_gated helpers live in a
    new TU src/detail/webserver_finalize.cpp, both to stay under the
    FILE_LOC_MAX gate.

Tests:
  - hooks_after_handler_replaces_response: respond_with replaces wire.
  - hooks_after_handler_mutates_response_in_place: with_header pass()
    puts the header on the wire.
  - hooks_response_sent_carries_status_bytes_timing: ctx fields populated.
  - hooks_request_completed_fires_on_early_failure: 413-short-circuit
    request_completed reports succeeded == true + non-null resp.
  - hooks_response_sent_ctx_shape / hooks_request_completed_ctx_shape:
    compile-time pins for the new ctx fields.
  - hooks_log_access_alias_slot: log_access(fn) populates the alias slot
    and does NOT push into hooks_response_sent_ (mirrors TASK-049's
    handler_exception_alias_slot_test).
  - hooks_no_firing updated: after_handler / response_sent /
    request_completed are now wired and removed from not_yet_wired.

Example:
  - examples/clf_access_log.cpp -- a Common Log Format access logger
    written as a response_sent hook, demonstrating the closure of #281
    and #69.

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

Author: etr

examples/Makefile.am

@@ -19,7 +19,7 @@
 LDADD = $(top_builddir)/src/libhttpserver.la
 AM_CPPFLAGS = -I$(top_srcdir)/src -I$(top_srcdir)/src/httpserver/
 METASOURCES = AUTO
-noinst_PROGRAMS = hello_world shared_state service custom_error allowing_disallowing_methods handlers hello_with_get_arg args_processing setting_headers custom_access_log minimal_https minimal_file_response minimal_deferred url_registration minimal_ip_ban banned_ip_log early_413 benchmark_select benchmark_threads benchmark_nodelay deferred_with_accumulator file_upload file_upload_with_callback empty_response_example iovec_response_example pipe_response_example daemon_info external_event_loop turbo_mode binary_buffer_response
+noinst_PROGRAMS = hello_world shared_state service custom_error allowing_disallowing_methods handlers hello_with_get_arg args_processing setting_headers custom_access_log clf_access_log minimal_https minimal_file_response minimal_deferred url_registration minimal_ip_ban banned_ip_log early_413 benchmark_select benchmark_threads benchmark_nodelay deferred_with_accumulator file_upload file_upload_with_callback empty_response_example iovec_response_example pipe_response_example daemon_info external_event_loop turbo_mode binary_buffer_response
 
 hello_world_SOURCES = hello_world.cpp
 shared_state_SOURCES = shared_state.cpp
@@ -31,6 +31,12 @@ hello_with_get_arg_SOURCES = hello_with_get_arg.cpp
 args_processing_SOURCES = args_processing.cpp
 setting_headers_SOURCES = setting_headers.cpp
 custom_access_log_SOURCES = custom_access_log.cpp
+# TASK-050: CLF-format access logger written as a response_sent hook.
+# Demonstrates the resolution of issues #281 and #69 -- with the
+# structured response_sent_ctx (status / bytes_queued / elapsed), users
+# can write a real CLF / time-taken log line in user code, without a
+# library change.
+clf_access_log_SOURCES = clf_access_log.cpp
 minimal_https_SOURCES = minimal_https.cpp
 minimal_file_response_SOURCES = minimal_file_response.cpp
 minimal_deferred_SOURCES = minimal_deferred.cpp

examples/clf_access_log.cpp

@@ -0,0 +1,110 @@
+/*
+     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
+*/
+
+// clf_access_log.cpp -- Common Log Format access logger written as a
+// response_sent lifecycle hook, demonstrating the resolution of issues
+// #281 and #69. libhttpserver v1's log_access(fn) callback handed the
+// user a single string and was invoked at request-arrival time, so the
+// status code, byte count, and request duration were not yet known.
+// Issues #281 and #69 asked for a logger that could emit a real CLF /
+// `time-taken` line.
+//
+// In v2.0 the response_sent hook (DR-012 §4.10) fires immediately after
+// MHD_queue_response and carries the structured context users have been
+// asking for:
+//   - ctx.status        -- HTTP status code
+//   - ctx.bytes_queued  -- logical body size (Content-Length, when known)
+//   - ctx.elapsed       -- steady_clock nanoseconds from
+//                          answer_to_connection's first invocation
+//
+// This example uses those fields to emit a Common Log Format line on
+// stdout. The library no longer hard-codes a logging format -- you do.
+//
+// Run:
+//   ./clf_access_log     # blocks; serves on :8080
+//   curl http://localhost:8080/hello
+//   curl http://localhost:8080/hello?name=world
+//
+// Expected output (per request):
+//   - - - [26/May/2026:14:01:23 +0000] "GET /hello HTTP/1.1" 200 13 1
+
+#include <chrono>
+#include <cstdint>
+#include <cstdio>
+#include <ctime>
+#include <functional>
+#include <memory>
+#include <string>
+
+#include <httpserver.hpp>
+
+namespace hs = httpserver;
+
+namespace {
+
+class hello_resource : public hs::http_resource {
+ public:
+    hs::http_response render_get(const hs::http_request&) override {
+        return hs::http_response::string("Hello, World!");
+    }
+};
+
+void emit_clf_line(const hs::response_sent_ctx& ctx) {
+    std::time_t now = std::time(nullptr);
+    char ts[32];
+    std::tm tm_buf;
+#if defined(_WIN32) && !defined(__CYGWIN__)
+    localtime_s(&tm_buf, &now);
+#else
+    localtime_r(&now, &tm_buf);
+#endif
+    std::strftime(ts, sizeof(ts), "%d/%b/%Y:%H:%M:%S %z", &tm_buf);
+
+    int64_t ms = std::chrono::duration_cast<std::chrono::milliseconds>(
+                     ctx.elapsed).count();
+    std::string method, path;
+    if (ctx.request != nullptr) {
+        method = std::string(ctx.request->get_method());
+        path = std::string(ctx.request->get_path());
+    }
+    std::printf("- - - [%s] \"%s %s HTTP/1.1\" %d %zu %lld\n",
+                ts,
+                method.c_str(),
+                path.c_str(),
+                ctx.status,
+                ctx.bytes_queued,
+                static_cast<long long>(ms));  // NOLINT(runtime/int)
+    std::fflush(stdout);
+}
+
+}  // namespace
+
+int main() {
+    hs::webserver ws{hs::create_webserver(8080)};
+
+    auto h = ws.add_hook(hs::hook_phase::response_sent,
+        std::function<void(const hs::response_sent_ctx&)>(emit_clf_line));
+
+    auto resource = std::make_shared<hello_resource>();
+    ws.register_path("/hello", resource);
+
+    ws.start(true);
+    return 0;
+}

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 detail/webserver_error_pages.cpp detail/webserver_aliases.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 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>.

src/detail/webserver_aliases.cpp

@@ -62,6 +62,7 @@
 #include <string_view>
 #include <utility>
 
+#include "httpserver/create_webserver.hpp"
 #include "httpserver/hook_action.hpp"
 #include "httpserver/hook_context.hpp"
 #include "httpserver/hook_handle.hpp"
@@ -107,6 +108,28 @@ void install_internal_error_alias_(
         make_internal_error_alias_(std::move(user_handler));
 }
 
+// TASK-050: install the log_access alias into the dedicated response_sent
+// alias slot on webserver_impl. Extracted from install_default_alias_hooks_
+// for the same reason as install_internal_error_alias_: keeping the host
+// function under the project CCN gate. See webserver_impl::log_access_alias_
+// for the lifetime contract.
+void install_log_access_alias_(
+        detail::webserver_impl* impl,
+        log_access_ptr user_logger) {
+    if (user_logger == nullptr) return;
+    impl->log_access_alias_ =
+        [user_logger = std::move(user_logger)](
+                const response_sent_ctx& ctx) {
+        if (ctx.request == nullptr) return;
+        std::string line;
+        line.reserve(64);
+        line += std::string(ctx.request->get_path());
+        line += " METHOD: ";
+        line += std::string(ctx.request->get_method());
+        user_logger(line);
+    };
+}
+
 // 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.
@@ -264,6 +287,31 @@ void webserver::install_default_alias_hooks_() {
     // 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);
+
+    // ----------------------------------------------------------------
+    // log_access -> response_sent alias slot. [TASK-050]
+    //
+    // This is an alias. Calling log_access(fn) on the create_webserver
+    // builder wires `fn` into the dedicated single-slot member
+    // webserver_impl::log_access_alias_, which fire_response_sent
+    // invokes AFTER the user-added response_sent vector. Users who want
+    // the structured ctx (status, bytes_queued, elapsed -- the data
+    // issues #281 and #69 asked for) should call
+    // add_hook(hook_phase::response_sent, ...) directly.
+    //
+    // Format compatibility: the pre-TASK-050 access log was emitted by
+    // webserver_impl::access_log(parent, complete_uri + " METHOD: " +
+    // method) at request-arrival time from inside answer_to_connection.
+    // The existing log_access_callback integ test (test/integ/basic.cpp)
+    // asserts the substrings "/logtest" AND "METHOD" appear in the
+    // logged line. To keep that test passing without modification we
+    // emit a line that contains both, formatted as:
+    //     <path> METHOD: <method>
+    // using ctx.request->get_path() and ctx.request->get_method(). The
+    // alias body is null-safe (early-returns if ctx.request is null),
+    // which is structurally impossible at the fire site but the guard
+    // costs nothing and documents the contract.
+    install_log_access_alias_(impl_.get(), log_access);
 }
 
 }  // namespace httpserver

src/detail/webserver_callbacks.cpp

@@ -95,7 +95,23 @@ namespace detail {
 void webserver_impl::request_completed(void *cls, struct MHD_Connection *connection, void **con_cls, enum MHD_RequestTerminationCode toe) {
     // These parameters are passed to respect the MHD interface, but are not needed here.
     std::ignore = cls;
-    std::ignore = toe;
+
+    // TASK-050: fire request_completed BEFORE the modded_request is
+    // destroyed so the ctx pointers remain backed by live storage. The
+    // gate-and-fire helper reads any_hooks_[request_completed] and
+    // builds the ctx from mr->dhr, mr->response_, and the MHD
+    // termination code. The fire site is the very first thing this
+    // callback does, while mr is still untouched.
+    auto* mr = static_cast<detail::modded_request*>(*con_cls);
+    if (mr != nullptr) {
+        // mr->ws is the parent webserver -- set in answer_to_connection
+        // (hoisted there at TASK-050 time). For paths where
+        // answer_to_connection never ran (e.g., very early MHD failures),
+        // mr->ws may be null; skip the fire site in that degenerate case.
+        if (mr->ws != nullptr && mr->ws->impl_ != nullptr) {
+            mr->ws->impl_->fire_request_completed_gated(mr, toe);
+        }
+    }
 
     // (1) Destroy the modded_request first. This runs ~http_request,
     //     which calls the arena_deleter on the impl's unique_ptr (a
@@ -303,9 +319,9 @@ void webserver_impl::error_log(void* cls, const char* fmt, va_list ap) {
     if (dws->log_error != nullptr) dws->log_error(msg);
 }
 
-void webserver_impl::access_log(webserver* dws, const string& uri) {
-    if (dws->log_access != nullptr) dws->log_access(uri);
-}
+// TASK-050: webserver_impl::access_log removed. log_access is now a
+// response_sent hook alias installed in webserver_aliases.cpp; the v1
+// inline call site in answer_to_connection has been removed.
 
 size_t webserver_impl::unescaper_func(void * cls, struct MHD_Connection *c, char *s) {
     // Parameter needed to respect MHD interface, but not needed here.