TASK-032: DR-008 thread-safety contract stress test

Adds test/integ/threadsafety_stress.cpp with two sub-tests:

1. concurrent_register_block_from_handlers_no_data_race — 16 curl
   clients hit an on_get lambda that re-enters the public webserver
   surface (register_path / unregister_path / block_ip / unblock_ip)
   for 60 s (default; HTTPSERVER_STRESS_SECONDS overrides). The
   TSan-clean rerun is the headline acceptance: the existing
   build-type=tsan matrix entry in verify-build.yml invokes make
   check, which auto-picks up the new check_PROGRAMS entry — no
   workflow edit required. Port 0 + get_bound_port() avoids
   collisions when the 60-s soak runs alongside other integ tests.

2. stop_from_handler_deadlocks_as_documented — opt-in (set
   HTTPSERVER_RUN_STOP_FROM_HANDLER=1) reproducer for the DR-008
   negative case. Forks a child that calls stop() inside an on_get
   handler; on this libmicrohttpd, MHD detects pthread_join(self)
   returning EDEADLK and aborts with "Failed to join a thread."
   The fork contains the abort so the parent test binary stays
   healthy. Either a non-zero child exit or a 5-second timeout
   (child SIGKILLed by parent) counts as positive observation of
   the contract.

Doxygen on webserver::stop() and ~webserver() now spells out the
deadlock-or-abort consequence of calling stop() from a handler
thread, pointing at DR-008 and §5.1.

Test wall-clock: 60 s default, ~5 s minimum locally. Acceptance
criteria all met: register_ok + unregister_ok > 0 and block_ok +
unblock_ok > 0 in every observed run. Full make check -j1 passes
42/42.

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

Author: etr

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

@@ -8,10 +8,10 @@
 Verify the documented thread-safety contract: `webserver` public methods are reentrant from inside a handler, except `stop()` and `~webserver()` which deadlock by design.
 
 **Action Items:**
-- [ ] Write a stress test (`test/threadsafety_stress.cpp`) that runs N concurrent handlers, each randomly invoking `register_resource`, `block_ip`, `unblock_ip`, `unregister_resource` against the running `webserver`.
-- [ ] Run under ThreadSanitizer in CI; assert no data races.
-- [ ] Add a separate test that calls `stop()` from inside a handler thread and asserts deadlock-detection (or simply documents the timeout); skip the test by default in CI but make it runnable on demand to validate the contract.
-- [ ] Document the deadlock case in `webserver::stop()` Doxygen.
+- [x] Write a stress test (`test/integ/threadsafety_stress.cpp`) that runs 16 concurrent curl clients, each request randomly invoking `register_path` (the non-deprecated successor to `register_resource`), `unregister_path`, `block_ip`, `unblock_ip` against the running `webserver` from inside an on_get lambda handler. Default duration 60 s; override with `HTTPSERVER_STRESS_SECONDS=N`.
+- [x] Run under ThreadSanitizer in CI; the existing `build-type: tsan` matrix entry in `.github/workflows/verify-build.yml` invokes `make check`, which auto-picks up every new `check_PROGRAMS` entry — no workflow edit needed.
+- [x] Add a separate test (`stop_from_handler_deadlocks_as_documented`) that calls `stop()` from inside a handler thread; opt-in via `HTTPSERVER_RUN_STOP_FROM_HANDLER=1`. The test forks a child so the abort/deadlock does not crash the test binary; either a non-zero child exit (libmicrohttpd self-join abort) or a 5 s timeout counts as positive observation of the contract.
+- [x] Document the deadlock case in `webserver::stop()` and `~webserver()` Doxygen.
 
 **Dependencies:**
 - Blocked by: TASK-027, TASK-031
@@ -26,4 +26,4 @@ Verify the documented thread-safety contract: `webserver` public methods are ree
 **Related Requirements:** PRD §2 NFR (concurrency)
 **Related Decisions:** DR-008, §5.1, §9 testing item 6, AR-006
 
-**Status:** Not Started
+**Status:** Done

src/httpserver/webserver.hpp

@@ -109,7 +109,15 @@ class webserver {
      // create_webserver. Callers must direct-init: webserver ws{cw};
      explicit webserver(const create_webserver& params);
      /**
-      * Destructor of the class
+      * Destructor.
+      *
+      * Calls stop() unconditionally, which joins libmicrohttpd's
+      * worker threads. For the same reason as stop(), destroying a
+      * webserver from inside a handler thread deadlocks (or, on some
+      * libmicrohttpd versions, aborts with "Failed to join a thread.").
+      * Destroy the webserver from the thread that constructed it.
+      *
+      * See specs/architecture/11-decisions/DR-008.md and §5.1.
      **/
      ~webserver();
      // PIMPL-owned: copy/move would slice the backing impl object.
@@ -125,8 +133,22 @@ class webserver {
      **/
      bool start(bool blocking = false);
      /**
-      * Method used to stop the webserver.
-      * @return true if the webserver is stopped.
+      * Stop the webserver.
+      *
+      * Joins libmicrohttpd's worker threads before returning. Safe to
+      * call from any thread *except* a handler thread: stop() blocks
+      * until every worker (including the calling one) drains, so a
+      * call from inside a handler self-joins and deadlocks (or, on
+      * some libmicrohttpd versions, aborts with "Failed to join a
+      * thread."). This is the documented DR-008 contract — see
+      * specs/architecture/11-decisions/DR-008.md and §5.1.
+      *
+      * For the same reason, ~webserver() (which calls stop())
+      * deadlocks if it runs on a handler thread; destroy the
+      * webserver from the thread that constructed it.
+      *
+      * @return true if the daemon was running and is now stopped;
+      *         false if it was already stopped.
      **/
      bool stop();
      /**

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 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 webserver_pimpl http_request_pimpl create_test_request http_request_arena http_request_const_getters http_request_tls_accessors webserver_register_smartptr webserver_register_path_prefix webserver_on_methods webserver_route route_table lookup_pipeline route_table_concurrency routing_regression
+check_PROGRAMS = basic file_upload http_utils threaded nodelay string_utilities http_endpoint ban_system ws_start_stop authentication 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 webserver_pimpl http_request_pimpl create_test_request http_request_arena http_request_const_getters http_request_tls_accessors webserver_register_smartptr webserver_register_path_prefix webserver_on_methods webserver_route route_table lookup_pipeline route_table_concurrency routing_regression threadsafety_stress
 
 MOSTLYCLEANFILES = *.gcda *.gcno *.gcov
 
@@ -233,6 +233,20 @@ lookup_pipeline_LDADD = $(LDADD) -lmicrohttpd
 route_table_concurrency_SOURCES = integ/route_table_concurrency.cpp
 route_table_concurrency_LDADD = $(LDADD) -lmicrohttpd
 
+# threadsafety_stress: TASK-032. DR-008 multi-thread contract gate.
+# Spawns 16 curl clients hitting an on_get handler that re-enters the
+# public webserver surface (register_path / unregister_path / block_ip /
+# unblock_ip) for HTTPSERVER_STRESS_SECONDS (default 60). The TSan-clean
+# rerun is the headline acceptance; the CI matrix `build-type: tsan`
+# entry in verify-build.yml picks this binary up via `make check`
+# without further wiring. A second sub-test reproduces the documented
+# stop()-from-handler deadlock; it is skipped by default and runs only
+# when HTTPSERVER_RUN_STOP_FROM_HANDLER=1.
+# Default LDADD (libhttpserver + curl) is sufficient — this test
+# touches only public webserver APIs and does not need a direct
+# microhttpd link.
+threadsafety_stress_SOURCES = integ/threadsafety_stress.cpp
+
 # routing_regression: TASK-028. v1 routing-test corpus regression gate.
 # Drives the public webserver registration surface (register_path /
 # register_prefix / on_get / on_post / unregister_path / unregister_prefix)