Merge TASK-052 (Hook bus doc/example/bench/stress closeout) into feature/v2.0

Author: etr

Makefile.am

@@ -40,7 +40,7 @@ endif
 
 EXTRA_DIST = libhttpserver.pc.in $(DX_CONFIG) scripts/extract-release-notes.sh scripts/validate-version.sh \
 	scripts/check-examples.sh scripts/check-readme.sh scripts/check-release-notes.sh \
-	scripts/check-doxygen.sh \
+	scripts/check-doxygen.sh scripts/check-hooks-doc-spotcheck.sh \
 	scripts/check-soversion.sh scripts/check-parallel-install.sh \
 	scripts/check-complexity.sh scripts/check-duplication.sh \
 	scripts/check-file-size.sh \
@@ -287,7 +287,7 @@ check-hygiene:
 # shared staged install to avoid paying two full `make install` costs on
 # every `make check`. Both sub-checks can still be invoked standalone (they
 # will do their own install when CHECK_*_SHARED is not set).
-check-local: check-headers check-examples check-readme check-release-notes check-doxygen
+check-local: check-headers check-examples check-readme check-release-notes check-doxygen check-hooks-doc-spotcheck
 	@echo "=== Shared staged install for check-install-layout and check-hygiene ==="
 	@rm -rf $(abs_top_builddir)/.shared-check-stage
 	@$(MAKE) $(AM_MAKEFLAGS) install DESTDIR=$(abs_top_builddir)/.shared-check-stage >check-shared-install.log 2>&1 || { \
@@ -331,6 +331,16 @@ check-doxygen:
 	@echo "=== check-doxygen: enforce TASK-043 zero-warning invariant ==="
 	@BUILD_DIR="$(abs_top_builddir)" $(top_srcdir)/scripts/check-doxygen.sh
 
+# TASK-052: hook-bus documentation spotcheck (per-header @file/@brief blocks,
+# eleven-phase enumeration on webserver::add_hook, five-permitted /
+# six-rejected enumeration on http_resource::add_hook, alias callouts on the
+# five v1 setters, hook-concurrency sentence in the class-level threading
+# block). Static grep-based gate; complements check-doxygen's full Doxygen
+# warning sweep.
+check-hooks-doc-spotcheck:
+	@echo "=== check-hooks-doc-spotcheck: enforce TASK-052 invariants on hook public surface ==="
+	@$(top_srcdir)/scripts/check-hooks-doc-spotcheck.sh
+
 # TASK-044: SOVERSION acceptance gate. Stages a clean DESTDIR install and
 # asserts that the v2.0 on-disk SONAME layout is correct (libhttpserver.so.2
 # on Linux / libhttpserver.2.dylib on Darwin, pkg-config --modversion 2.0.0,
@@ -375,7 +385,7 @@ lint-file-size:
 	@echo "=== lint-file-size: enforce per-file line-count ceiling ==="
 	@$(top_srcdir)/scripts/check-file-size.sh
 
-.PHONY: check-headers check-install-layout check-hygiene check-examples check-readme check-release-notes check-doxygen check-soversion check-parallel-install lint-complexity lint-duplication lint-file-size
+.PHONY: check-headers check-install-layout check-hygiene check-examples check-readme check-release-notes check-doxygen check-hooks-doc-spotcheck check-soversion check-parallel-install lint-complexity lint-duplication lint-file-size
 
 # TASK-039: top-level convenience rule that descends into test/ to
 # build and run the bench binaries (see test/Makefile.am and

README.md

@@ -95,6 +95,7 @@ The block above is reproduced byte-for-byte from
 * [WebSocket support](#websocket-support)
 * [Daemon introspection and external event loops](#daemon-introspection-and-external-event-loops)
 * [HTTP utils](#http-utils)
+* [Lifecycle hooks](#lifecycle-hooks)
 * [Threading contract](#threading-contract)
 * [Error propagation](#error-propagation)
 * [Feature availability](#feature-availability)
@@ -1510,6 +1511,93 @@ The following utility functions are available on `http::http_utils`:
 
 [Back to TOC](#table-of-contents)
 
+## Lifecycle hooks
+
+The hook bus is the single extension surface for observing or
+short-circuiting the request lifecycle. It replaces v1's single-slot
+patchwork (one `log_access` callback, one `not_found_handler`, one
+`method_not_allowed_handler`, one `internal_error_handler`, one
+`auth_handler`) with eleven distinct phases spanning connection,
+request, routing, handler, and response. Each phase accepts multiple
+subscribers and is observable both server-wide (via `webserver::add_hook`)
+and, for the five post-route-resolution phases, per-route (via
+`http_resource::add_hook`). The contract is captured in DR-012 and
+[`specs/architecture/04-components/hooks.md`](specs/architecture/04-components/hooks.md).
+
+Each call returns a move-only `hook_handle`. The handle's destructor
+removes the registration; `hook_handle::detach()` disarms the destructor
+so the registration persists for the webserver's lifetime.
+
+### Phases
+
+| Phase | Fires at | Short-circuit | Per-route eligible |
+|-------|----------|---------------|--------------------|
+| `connection_opened` | New TCP / TLS connection accepted by MHD | No | No |
+| `accept_decision` | After the default-policy / block-list verdict; the connection has been accepted or denied | No | No |
+| `connection_closed` | Connection torn down (peer close or server close) | No | No |
+| `request_received` | Request line and headers parsed, body not yet consumed | Yes (`hook_action`) | No |
+| `body_chunk` | Each upload-body chunk delivered by MHD | Yes (`hook_action`) | No |
+| `route_resolved` | After URL → resource resolution; carries the matched route or "no match" | No | No |
+| `before_handler` | After route resolution and method check, immediately before the handler runs | Yes (`hook_action`) | Yes |
+| `handler_exception` | Exception escapes the handler, before `internal_error_handler` is consulted | Yes (`hook_action`) | Yes |
+| `after_handler` | Handler returned a response, before it is queued on the wire (mutation point) | Yes (`hook_action`) | Yes |
+| `response_sent` | Response handed to `MHD_queue_response`; carries `status`, `bytes_queued`, `elapsed` | No | Yes |
+| `request_completed` | Request lifecycle finished (success or failure); last hook to fire per request | No | Yes |
+
+### Short-circuit semantics
+
+Phases marked "Short-circuit" return a `hook_action`:
+`hook_action::pass()` lets the chain continue;
+`hook_action::respond_with(response)` aborts the chain at that
+position. The wrapped response is sent on the wire in place of any
+handler output. Subsequent hooks in the same phase are not invoked.
+Observation-only phases (`connection_opened`, `accept_decision`,
+`connection_closed`, `route_resolved`, `response_sent`,
+`request_completed`) ignore the return; the chain always runs to
+completion.
+
+### Per-route hooks
+
+`http_resource::add_hook(phase, fn)` accepts only the five
+post-route-resolution phases: `before_handler`, `handler_exception`,
+`after_handler`, `response_sent`, `request_completed`. Per-route hooks
+fire after the server-wide chain at the same phase, and only if that
+server-wide chain did not short-circuit. Passing any other phase
+throws `std::invalid_argument` naming the rejected phase. See
+[`examples/per_route_auth.cpp`](examples/per_route_auth.cpp) for a
+worked example.
+
+### Examples
+
+* [`examples/banned_ip_log.cpp`](examples/banned_ip_log.cpp) — log every
+  banned-IP rejection via a single `accept_decision` hook.
+* [`examples/early_413.cpp`](examples/early_413.cpp) — return 413 from
+  a `request_received` hook before the body is consumed.
+* [`examples/clf_access_log.cpp`](examples/clf_access_log.cpp) — write
+  a Common Log Format access line from a `response_sent` hook.
+* [`examples/per_route_auth.cpp`](examples/per_route_auth.cpp) —
+  per-route HTTP Basic auth via `http_resource::add_hook(before_handler, ...)`.
+
+### v1 aliases
+
+Each of the v1 single-slot setters is an alias for an `add_hook` call
+at the corresponding phase. The aliases survive for ergonomic call
+sites; new code can use either form.
+
+| v1 setter | Equivalent `add_hook` call |
+|-----------|----------------------------|
+| `log_access(fn)` | `ws.add_hook(hook_phase::response_sent, fn)` |
+| `not_found_handler(fn)` | `ws.add_hook(hook_phase::route_resolved, fn)` |
+| `method_not_allowed_handler(fn)` | `ws.add_hook(hook_phase::before_handler, fn)` |
+| `internal_error_handler(fn)` | `ws.add_hook(hook_phase::handler_exception, fn)` |
+| `auth_handler(fn)` | `ws.add_hook(hook_phase::before_handler, fn)` |
+
+The aliases install observation-stub hooks under the same dispatch
+plumbing, so the on-the-wire behaviour is identical regardless of
+which form the caller used.
+
+[Back to TOC](#table-of-contents)
+
 ## Threading contract
 
 Distilled from
@@ -1717,6 +1805,21 @@ to the canonical example for each topic covered in this manual.
 * [`examples/client_cert_auth.cpp`](examples/client_cert_auth.cpp) —
   mutual TLS with X.509 client certificates.
 
+### Lifecycle hooks
+
+* [`examples/banned_ip_log.cpp`](examples/banned_ip_log.cpp) — log every
+  banned-IP rejection from a single `accept_decision` hook (issue #332).
+* [`examples/early_413.cpp`](examples/early_413.cpp) — short-circuit
+  oversized uploads with 413 before any body bytes are consumed via a
+  `request_received` hook (issue #273).
+* [`examples/clf_access_log.cpp`](examples/clf_access_log.cpp) —
+  Common Log Format access logger written as a `response_sent` hook
+  using the structured `status` / `bytes_queued` / `elapsed` context
+  fields (issues #281 and #69).
+* [`examples/per_route_auth.cpp`](examples/per_route_auth.cpp) —
+  per-route HTTP Basic auth via `http_resource::add_hook(before_handler,
+  ...)` that does not touch sibling routes (DR-012).
+
 ### Operations
 
 * [`examples/daemon_info.cpp`](examples/daemon_info.cpp) — introspect

RELEASE_NOTES.md

@@ -101,13 +101,25 @@ v1.x is end-of-life on the day v2.0 ships.
   uses `method_set`.
 - **`httpserver::constants` namespace.** `constexpr` replacements for
   every removed `#define`.
-- **Lifecycle hook bus (M5).** `ws.add_hook(hook_phase, std::function)`
-  registers observation/mutation hooks on the request/connection
-  lifecycle. The three connection-level phases — `connection_opened`,
-  `accept_decision`, `connection_closed` — fire on every connection;
-  `accept_decision` exposes `{peer, accepted, reason}` (closes #332,
-  see `examples/banned_ip_log.cpp`). The other eight phases land in
-  later M5 tasks.
+- **Lifecycle hook bus (`webserver::add_hook` / `http_resource::add_hook`).**
+  Eleven phases (`hook_phase` enum: `connection_opened`,
+  `accept_decision`, `connection_closed`, `request_received`,
+  `body_chunk`, `route_resolved`, `before_handler`,
+  `handler_exception`, `after_handler`, `response_sent`,
+  `request_completed`) spanning connection, request, routing, handler,
+  and response. Multi-subscriber, server-wide and per-route. The v1
+  single-slot setters (`log_access`, `not_found_handler`,
+  `method_not_allowed_handler`, `internal_error_handler`,
+  `auth_handler`) survive as documented aliases for the corresponding
+  `add_hook` calls. Each registration returns a move-only `hook_handle`
+  whose destructor erases the entry; `hook_handle::detach()` keeps the
+  registration alive for the webserver's lifetime. See
+  `specs/architecture/04-components/hooks.md` and
+  [`README.md#lifecycle-hooks`](README.md#lifecycle-hooks). Closes:
+  #332 (banned-IP log, `examples/banned_ip_log.cpp`), #281 + #69
+  (CLF / time-taken access log, `examples/clf_access_log.cpp`), #273
+  (early 413, `examples/early_413.cpp`); partially closes #272
+  (per-chunk observation; body steal deferred to v2.1).
 
 ## What's renamed (v1 → v2)
 

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 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
+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 per_route_auth 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
@@ -45,6 +45,11 @@ url_registration_SOURCES = url_registration.cpp
 minimal_ip_ban_SOURCES = minimal_ip_ban.cpp
 banned_ip_log_SOURCES = banned_ip_log.cpp
 early_413_SOURCES = early_413.cpp
+# TASK-052: per-route auth via http_resource::add_hook(before_handler).
+# Demonstrates that a hook registered on one resource fires only when
+# that resource is dispatched -- a private route can require credentials
+# without touching sibling routes (DR-012).
+per_route_auth_SOURCES = per_route_auth.cpp
 benchmark_select_SOURCES = benchmark_select.cpp
 benchmark_threads_SOURCES = benchmark_threads.cpp
 benchmark_nodelay_SOURCES = benchmark_nodelay.cpp

examples/README.md

@@ -70,6 +70,27 @@ TLS and authentication
 * `client_cert_auth.cpp` — mutual TLS with X.509 client certificates.
   Ships as a documentation artifact; not wired into `noinst_PROGRAMS`.
 
+Lifecycle hooks
+---------------
+
+The hook bus (DR-012, §4.10) lets user code observe and short-circuit
+every interesting point in the request lifecycle. The four examples
+below demonstrate the user-visible resolution of issues #332, #273,
+#281, #69, and the per-route hook contract introduced in TASK-051.
+
+* `banned_ip_log.cpp` — a single `accept_decision` hook logs every
+  banned-IP rejection to stderr. Resolves issue #332.
+* `early_413.cpp` — a single `request_received` hook returns
+  `respond_with(http_response::empty().with_status(413))` when
+  `Content-Length` exceeds the configured cap. The request body never
+  crosses the I/O boundary. Resolves issue #273.
+* `clf_access_log.cpp` — a single `response_sent` hook formats a
+  Common Log Format line using the structured context fields
+  (`status`, `bytes_queued`, `elapsed`). Resolves issues #281 and #69.
+* `per_route_auth.cpp` — `http_resource::add_hook(before_handler, ...)`
+  guards a single route with HTTP Basic auth without touching sibling
+  routes. Demonstrates per-route hook scoping (DR-012).
+
 Operations
 ----------
 

examples/per_route_auth.cpp

@@ -0,0 +1,106 @@
+// Demonstrates DR-012 / PRD-HOOK-REQ-006: a `before_handler` hook
+// registered via `http_resource::add_hook(...)` is per-route. The hook
+// fires only when *this* resource is dispatched -- a sibling route
+// registered on the same webserver is not touched.
+//
+// The example wires two resources:
+//
+//   /public  -- always 200 OK, no auth.
+//   /private -- a per-route before_handler hook checks the Authorization
+//               header (HTTP Basic). Missing or invalid credentials
+//               short-circuit with 401; valid credentials let the
+//               handler run and return 200 OK.
+//
+// SECURITY NOTE (CWE-798): the expected credentials are loaded from the
+// environment (AUTH_USER / AUTH_PASS); do not hardcode them. Set both
+// before running:
+//
+//   export AUTH_USER=alice AUTH_PASS=hunter2
+//   ./per_route_auth
+//
+// Then:
+//
+//   curl -v http://localhost:8080/public                       # 200 OK
+//   curl -v http://localhost:8080/private                      # 401
+//   curl -v -u alice:hunter2 http://localhost:8080/private     # 200 OK
+//
+// Contrast with `centralized_authentication.cpp`, which installs the
+// server-wide `auth_handler` setter (the v1 alias for a webserver-wide
+// before_handler hook). Per-route `add_hook` is the right shape when
+// only a subset of routes need protection without dragging the rest of
+// the surface through an auth_skip_paths list.
+
+#include <cstdlib>
+#include <functional>
+#include <iostream>
+#include <memory>
+#include <string>
+#include <string_view>
+
+#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!");
+    }
+};
+
+class private_resource : public hs::http_resource {
+ public:
+    hs::http_response render_get(const hs::http_request&) override {
+        return hs::http_response::string("Welcome to the private area.");
+    }
+};
+
+}  // namespace
+
+int main() {
+    const char* expected_user = std::getenv("AUTH_USER");
+    const char* expected_pass = std::getenv("AUTH_PASS");
+    if (expected_user == nullptr || expected_pass == nullptr) {
+        std::cerr << "per_route_auth: set AUTH_USER and AUTH_PASS before "
+                     "running.\n";
+        return 1;
+    }
+
+    hs::webserver ws{hs::create_webserver(8080)};
+
+    auto pub = std::make_shared<hello_resource>();
+    auto priv = std::make_shared<private_resource>();
+
+    // The hook is registered on `priv` ONLY. Dispatches against `pub`
+    // never enter this callback -- a sibling-route observation that is
+    // the load-bearing property of per-route hooks (DR-012).
+    std::string user{expected_user};
+    std::string pass{expected_pass};
+    auto h = priv->add_hook(hs::hook_phase::before_handler,
+        std::function<hs::hook_action(hs::before_handler_ctx&)>(
+            [user, pass](hs::before_handler_ctx& ctx) {
+                if (ctx.request == nullptr) {
+                    return hs::hook_action::pass();
+                }
+                std::string_view u = ctx.request->get_user();
+                std::string_view p = ctx.request->get_pass();
+                if (u == user && p == pass) {
+                    return hs::hook_action::pass();
+                }
+                return hs::hook_action::respond_with(
+                    hs::http_response::unauthorized(
+                        "Basic", "private-realm", "Unauthorized"));
+            }));
+
+    // Keep the handle in scope for the full server lifetime; its
+    // destructor at scope exit removes the registration. Since main()
+    // never returns (start(true) blocks), this is the simple shape.
+
+    ws.register_path("/public", pub);
+    ws.register_path("/private", priv);
+
+    ws.start(true);   // blocking
+    return 0;
+}

scripts/check-examples.sh

@@ -174,5 +174,33 @@ if [ "$unlisted" -gt 0 ]; then
     fail "$unlisted .cpp file(s) in examples/ are not listed in Makefile.am noinst_PROGRAMS — add them or add to KNOWN_ARTIFACTS"
 fi
 
-echo "check-examples: OK (hello_world.cpp = $loc LOC; shared_state.cpp asserted; Makefile.am coverage verified bidirectionally)"
+# ---- TASK-052: hook-example documentation coverage --------------------------
+# The four lifecycle-hook examples (banned_ip_log, early_413, clf_access_log,
+# per_route_auth) must be listed in both examples/README.md and the top-level
+# README.md so the user-visible resolution of issues #332, #281, #69, #273 is
+# discoverable. Per TASK-052 / Phase 3.
+EXAMPLES_README="$REPO_ROOT/examples/README.md"
+TOP_README="$REPO_ROOT/README.md"
+HOOK_EXAMPLES="banned_ip_log early_413 clf_access_log per_route_auth"
+
+for f in "$EXAMPLES_README" "$TOP_README"; do
+    [ -f "$f" ] || fail "$(basename "$f") does not exist"
+done
+
+missing_doc=0
+for ex in $HOOK_EXAMPLES; do
+    if ! grep -q "${ex}\\.cpp" "$EXAMPLES_README"; then
+        echo "check-examples: FAIL: examples/README.md does not mention ${ex}.cpp" >&2
+        missing_doc=$((missing_doc + 1))
+    fi
+    if ! grep -q "${ex}\\.cpp" "$TOP_README"; then
+        echo "check-examples: FAIL: README.md does not mention ${ex}.cpp" >&2
+        missing_doc=$((missing_doc + 1))
+    fi
+done
+if [ "$missing_doc" -gt 0 ]; then
+    fail "$missing_doc hook-example reference(s) missing from README docs (TASK-052)"
+fi
+
+echo "check-examples: OK (hello_world.cpp = $loc LOC; shared_state.cpp asserted; Makefile.am coverage verified bidirectionally; hook examples listed in both READMEs)"
 exit 0