Merge TASK-032: Thread-safety contract stress test (DR-008)

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

Author: etr

specs/architecture/11-decisions/DR-008.md

@@ -19,4 +19,9 @@
 - `http_request` is single-threaded per request.
 - `http_response` is exclusively owned (value type).
 
+**Verification (TASK-032):**
+- `test/integ/threadsafety_stress.cpp` — stress test binary `threadsafety_stress` runs 16 concurrent curl clients for 60 seconds (override via `HTTPSERVER_STRESS_SECONDS=N`), each request randomly invoking `register_path`, `unregister_path`, `block_ip`, and `unblock_ip` against the running `webserver` from inside a handler thread. A duplicate-registration from a handler throws `std::invalid_argument` rather than causing a data race.
+- CI coverage: the `build-type: tsan` matrix entry in `.github/workflows/verify-build.yml` compiles with `-fsanitize=thread` and runs `make check`, which automatically picks up `threadsafety_stress` as a registered `check_PROGRAMS` entry — no separate workflow wiring is needed.
+- Opt-in negative test `stop_from_handler_deadlocks_as_documented` (enabled via `HTTPSERVER_RUN_STOP_FROM_HANDLER=1`) forks a child process that calls `stop()` from inside a handler. A non-zero child exit (libmicrohttpd self-join abort, exit code 42) or a 5-second parent timeout (exit code 43) both count as positive observation of the documented deadlock contract. These exit codes serve as regression sentinels.
+
 ---

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

specs/tasks/_index.md

@@ -114,7 +114,7 @@ Nominally: **13 sequential tasks**, each S–XL. Most other tasks parallelize of
 | TASK-029 | Naming consistency — `stop_and_wait`, `block_ip`/`unblock_ip` | M5 | Done | TASK-014 |
 | TASK-030 | `_handler` suffix renames + `explicit` constructor | M5 | Done | TASK-014 |
 | TASK-031 | Handler error-propagation contract (DR-009) | M5 | Done | TASK-027, TASK-030 |
-| TASK-032 | Thread-safety contract stress test (DR-008) | M5 | Not Started | TASK-027, TASK-031 |
+| TASK-032 | Thread-safety contract stress test (DR-008) | M5 | Done | TASK-027, TASK-031 |
 | TASK-033 | `create_webserver` builder cleanup | M5 | Not Started | TASK-006, TASK-014 |
 | TASK-034 | Build-flag-independent public API + `webserver::features()` | M5 | Not Started | TASK-003, TASK-019, TASK-033 |
 | TASK-035 | Smart-pointer `register_ws_resource` overloads | M5 | Not Started | TASK-014, TASK-034 |