v2.0: Modernization (M1-M6, 44 tasks)

.codacy.yaml

@@ -0,0 +1,13 @@
+---
+# Codacy project configuration.
+#
+# specs/ holds internal groundwork artifacts (product specs, architecture
+# notes, task records, review notes). They are not user-facing docs and are
+# not subject to the same markdown style as README/ChangeLog/CONTRIBUTING.
+#
+# test/*.md are internal test-suite documents (e.g. the v2.0 routing
+# regression gate at test/REGRESSION.md). Same rationale as specs/.
+exclude_paths:
+  - 'specs/**'
+  - 'test/*.md'
+  - 'test/**/*.md'

.gitignore

@@ -60,3 +60,5 @@ libtool
 .worktrees
 .claude
 CLAUDE.md
+.groundwork-plans/
+.DS_Store

ChangeLog

@@ -1,5 +1,10 @@
 Version 0.20.0
 
+	Raised minimum C++ standard to C++20. Build now requires gcc >= 10
+		or clang >= 13 (Apple Clang from Xcode 15+). Updated
+		AX_CXX_COMPILE_STDCXX macro (m4/ax_cxx_compile_stdcxx.m4) to
+		serial 25 to support C++20 detection. Pruned CI matrix rows
+		(gcc-9, clang-11, clang-12) that lack full C++20 support.
 	Raised minimum libmicrohttpd requirement to 1.0.0.
 	Migrated Basic Auth to v3 API (MHD_basic_auth_get_username_password3,
 		MHD_queue_basic_auth_required_response3) with UTF-8 support.
@@ -20,6 +25,16 @@ Version 0.20.0
 		suppress_date_header.
 	Added WebSocket support (conditional on HAVE_WEBSOCKET):
 		websocket_handler, websocket_session, register_ws_resource().
+	TASK-035: replaced the raw-pointer
+		register_ws_resource(string, websocket_handler*) overload with
+		smart-pointer overloads register_ws_resource(string,
+		unique_ptr<websocket_handler>) and register_ws_resource(string,
+		shared_ptr<websocket_handler>); added unregister_ws_resource(string).
+		Mirrors the TASK-023 register_resource ownership model and is
+		consistent with DR-010 / PRD-HDL-REQ-003 / PRD-HDL-REQ-005.
+		Duplicate registrations now throw std::invalid_argument
+		(previously a silent overwrite). On HAVE_WEBSOCKET-off builds
+		all three entry points throw feature_unavailable.
 	Added utility functions: reason_phrase(), is_feature_supported(),
 		get_mhd_version().
 	Added example and documentation for serving binary data from memory

Makefile.am

@@ -38,11 +38,289 @@ endif
 
 endif
 
-EXTRA_DIST = libhttpserver.pc.in $(DX_CONFIG) scripts/extract-release-notes.sh scripts/validate-version.sh
+EXTRA_DIST = libhttpserver.pc.in $(DX_CONFIG) scripts/extract-release-notes.sh scripts/validate-version.sh \
+	scripts/check-examples.sh scripts/verify-installed-examples.sh \
+	test/headers/consumer_direct.cpp test/headers/consumer_detail.cpp test/headers/consumer_umbrella.cpp \
+	test/headers/consumer_post_umbrella.cpp \
+	test/headers/consumer_umbrella_no_backend.cpp
+
+# ---------------------------------------------------------------------------
+# Header-hygiene checks (TASK-002)
+#
+# check-headers verifies that the public/private header gates are wired up
+# correctly:
+#   A.1 a consumer including a public header WITHOUT the umbrella must hit the
+#       inclusion-gate #error.
+#   A.2 a consumer including a detail header WITHOUT HTTPSERVER_COMPILATION
+#       must hit the gate.
+#   A.3 a consumer including only the umbrella, WITHOUT HTTPSERVER_COMPILATION,
+#       must compile cleanly.
+#
+# The CXX invocations below override CXXFLAGS to '' so that
+# -DHTTPSERVER_COMPILATION (injected by configure.ac into CXXFLAGS for the
+# library and test build) does NOT leak into the consumer-style compile. We
+# still pass -std=c++20 explicitly because libhttpserver requires C++20.
+# ---------------------------------------------------------------------------
+
+# Compose CXX with: explicit -std, the source/build include search paths used by
+# the library, and $(CPPFLAGS) (e.g., -I/opt/homebrew/include from configure).
+# Deliberately omit $(CXXFLAGS), $(AM_CPPFLAGS), and any per-target CPPFLAGS so
+# that -DHTTPSERVER_COMPILATION (set in src/ and test/ AM_CPPFLAGS) cannot
+# leak into the consumer-style compile. A true consumer never has that macro.
+CHECK_HEADERS_CXX = $(CXX) -std=c++20 -I$(top_builddir) -I$(top_srcdir)/src -I$(top_srcdir)/src/httpserver $(CPPFLAGS)
+CHECK_HEADERS_GATE_MSG = Only <httpserver.hpp> or <httpserverpp> can be included directly
+
+check-headers:
+	@echo "=== check-headers A.1: direct public-header include must fail ==="
+	@if $(CHECK_HEADERS_CXX) -c $(top_srcdir)/test/headers/consumer_direct.cpp -o /dev/null 2>check-headers-A1.log; then \
+	    echo "FAIL: consumer_direct.cpp compiled but should have errored"; \
+	    cat check-headers-A1.log; \
+	    rm -f check-headers-A1.log; \
+	    exit 1; \
+	fi
+	@if ! grep -q "$(CHECK_HEADERS_GATE_MSG)" check-headers-A1.log; then \
+	    echo "FAIL: consumer_direct.cpp failed but not for the gate reason"; \
+	    cat check-headers-A1.log; \
+	    rm -f check-headers-A1.log; \
+	    exit 1; \
+	fi
+	@rm -f check-headers-A1.log
+	@echo "  PASS: A.1 gate fired as expected"
+	@echo "=== check-headers A.2: direct detail-header include must fail ==="
+	@if $(CHECK_HEADERS_CXX) -c $(top_srcdir)/test/headers/consumer_detail.cpp -o /dev/null 2>check-headers-A2.log; then \
+	    echo "FAIL: consumer_detail.cpp compiled but should have errored"; \
+	    cat check-headers-A2.log; \
+	    rm -f check-headers-A2.log; \
+	    exit 1; \
+	fi
+	@if ! grep -q "$(CHECK_HEADERS_GATE_MSG)" check-headers-A2.log; then \
+	    echo "FAIL: consumer_detail.cpp failed but not for the gate reason"; \
+	    cat check-headers-A2.log; \
+	    rm -f check-headers-A2.log; \
+	    exit 1; \
+	fi
+	@rm -f check-headers-A2.log
+	@echo "  PASS: A.2 gate fired as expected"
+	@echo "=== check-headers A.3: umbrella include must succeed ==="
+	@if ! $(CHECK_HEADERS_CXX) -c $(top_srcdir)/test/headers/consumer_umbrella.cpp -o consumer_umbrella.check.o 2>check-headers-A3.log; then \
+	    echo "FAIL: consumer_umbrella.cpp did not compile"; \
+	    cat check-headers-A3.log; \
+	    rm -f check-headers-A3.log consumer_umbrella.check.o; \
+	    exit 1; \
+	fi
+	@rm -f check-headers-A3.log consumer_umbrella.check.o
+	@echo "  PASS: A.3 umbrella compiled cleanly"
+	@echo "=== check-headers A.4: post-umbrella direct include must fail ==="
+	@if $(CHECK_HEADERS_CXX) -c $(top_srcdir)/test/headers/consumer_post_umbrella.cpp -o /dev/null 2>check-headers-A4.log; then \
+	    echo "FAIL: consumer_post_umbrella.cpp compiled but should have errored"; \
+	    cat check-headers-A4.log; \
+	    rm -f check-headers-A4.log; \
+	    exit 1; \
+	fi
+	@if ! grep -q "$(CHECK_HEADERS_GATE_MSG)" check-headers-A4.log; then \
+	    echo "FAIL: consumer_post_umbrella.cpp failed but not for the gate reason"; \
+	    cat check-headers-A4.log; \
+	    rm -f check-headers-A4.log; \
+	    exit 1; \
+	fi
+	@rm -f check-headers-A4.log
+	@echo "  PASS: A.4 umbrella does not leak _HTTPSERVER_HPP_INSIDE_"
+
+# check-install-layout asserts that `make install DESTDIR=$(STAGE)` produces
+# a public include tree with NO `detail/` directory and NO `*_impl.hpp` files.
+# This protects the public/private split as described in TASK-002 / DR-002.
+CHECK_INSTALL_STAGE = $(abs_top_builddir)/.install-stage
+
+check-install-layout:
+	@echo "=== check-install-layout: staged install must hide detail/ and *_impl.hpp ==="
+	@if test "$(CHECK_INSTALL_SHARED)" != "yes"; then \
+	    rm -rf $(CHECK_INSTALL_STAGE); \
+	    $(MAKE) $(AM_MAKEFLAGS) install DESTDIR=$(CHECK_INSTALL_STAGE) >check-install.log 2>&1 || { \
+	        echo "FAIL: staged install failed"; \
+	        cat check-install.log; \
+	        rm -f check-install.log; \
+	        rm -rf $(CHECK_INSTALL_STAGE); \
+	        exit 1; \
+	    }; \
+	    rm -f check-install.log; \
+	fi
+	@leaked_detail=`find $(CHECK_INSTALL_STAGE) -type d -name detail 2>/dev/null`; \
+	if test -n "$$leaked_detail"; then \
+	    echo "FAIL: detail/ directory leaked into install:"; \
+	    echo "$$leaked_detail"; \
+	    if test "$(CHECK_INSTALL_SHARED)" != "yes"; then rm -rf $(CHECK_INSTALL_STAGE); fi; \
+	    exit 1; \
+	fi
+	@leaked_impl=`find $(CHECK_INSTALL_STAGE) -name '*_impl.hpp' 2>/dev/null`; \
+	if test -n "$$leaked_impl"; then \
+	    echo "FAIL: *_impl.hpp file leaked into install:"; \
+	    echo "$$leaked_impl"; \
+	    if test "$(CHECK_INSTALL_SHARED)" != "yes"; then rm -rf $(CHECK_INSTALL_STAGE); fi; \
+	    exit 1; \
+	fi
+	@umbrella_count=`find $(CHECK_INSTALL_STAGE) -name 'httpserver.hpp' | wc -l | tr -d ' '`; \
+	if test "$$umbrella_count" != "1"; then \
+	    echo "FAIL: expected exactly 1 installed httpserver.hpp, got $$umbrella_count"; \
+	    if test "$(CHECK_INSTALL_SHARED)" != "yes"; then rm -rf $(CHECK_INSTALL_STAGE); fi; \
+	    exit 1; \
+	fi
+	@if test "$(CHECK_INSTALL_SHARED)" != "yes"; then rm -rf $(CHECK_INSTALL_STAGE); fi
+	@echo "  PASS: staged install layout is clean"
+
+# ---------------------------------------------------------------------------
+# Header-hygiene preprocessor gate (TASK-007).
+#
+# This is the preprocessor-grep half of the TASK-007 enforcement (the
+# compile-time half lives as `header_hygiene` in test/Makefile.am).
+#
+# Procedure:
+#   1. Stage `make install DESTDIR=$(CHECK_HYGIENE_STAGE)` to get a
+#      pristine public include tree -- exactly what packagers and
+#      downstream consumers see.
+#   2. Preprocess test/headers/consumer_umbrella_no_backend.cpp using
+#      ONLY -I$(CHECK_HYGIENE_STAGE)$(includedir) plus $(CPPFLAGS) (so
+#      e.g. /opt/homebrew/include is on the search path -- the grep
+#      below NEEDS to resolve <microhttpd.h> if the umbrella pulls it
+#      in, otherwise we couldn't detect the leak).
+#   3. Grep the cpp output for `# <line> "<file>"` line markers that
+#      name any forbidden backend header. The line-marker filter
+#      avoids false positives from substrings in code or comments.
+#
+# HEADER_HYGIENE_STRICT controls whether a leak is fatal:
+#   - "yes" (default since TASK-020): leaks fail the build. The umbrella
+#           is now clean and any regression should break CI loudly.
+#   - "no"  (legacy): leaks were reported as EXPECTED-FAIL and exit 0
+#           while M2-M5 were in flight. Override from the command line
+#           (`make check-hygiene HEADER_HYGIENE_STRICT=no`) only if you
+#           are deliberately running against an in-flight umbrella.
+#
+# Cross-reference: keep HEADER_HYGIENE_FORBIDDEN in sync with the
+# #ifdef ladder in test/unit/header_hygiene_test.cpp.
+#
+# TASK-020 caveat (libc++ AND libstdc++ in thread mode): <pthread.h>
+# is intentionally absent from the forbidden list below. Both
+# mainstream STLs unconditionally pull <pthread.h> in from any STL
+# container header (<vector>, <string>, <map>, etc.) when threading
+# is enabled:
+#   - libc++ (Apple's default STL on macOS) routes through
+#     <__thread/support/pthread.h>.
+#   - libstdc++ in thread-enabled mode (which is the default whenever
+#     -D_REENTRANT is set, as configure.ac does) routes through
+#     <bits/gthr-default.h>, which #include <pthread.h> directly.
+# The resulting `# N "...pthread.h"` line markers therefore appear in
+# the preprocessed output even though libhttpserver itself does not
+# include <pthread.h>. The runtime sentinel
+# test/unit/header_hygiene_test.cpp keeps the pthread guards but skips
+# them on both libc++ (_LIBCPP_VERSION) and libstdc++ in thread mode
+# (_GLIBCXX_HAS_GTHREADS), so the guards still fire on STLs that don't
+# route std::thread through pthread (e.g. MSVC's Microsoft STL).
+# ---------------------------------------------------------------------------
+
+HEADER_HYGIENE_FORBIDDEN = microhttpd\.h|gnutls/gnutls\.h|sys/socket\.h|sys/uio\.h
+CHECK_HYGIENE_STAGE      = $(abs_top_builddir)/.hygiene-stage
+CHECK_HYGIENE_CXX        = $(CXX) -std=c++20 -E -I$(CHECK_HYGIENE_STAGE)$(includedir) $(CPPFLAGS)
+HEADER_HYGIENE_STRICT   ?= yes
+
+# Sentinel file: only re-run the staged install when headers have changed.
+# This is an mtime gate used exclusively for standalone `make check-hygiene`
+# invocations — it avoids paying a full `make install` cost on every
+# repeated standalone run.  When check-local drives check-hygiene it sets
+# CHECK_HYGIENE_SHARED=yes and passes CHECK_HYGIENE_STAGE pointing at its
+# own pre-built shared stage, so this stamp target is bypassed entirely.
+HYGIENE_STAMP = $(CHECK_HYGIENE_STAGE)/.hygiene-stamp
+
+$(HYGIENE_STAMP): $(wildcard $(top_srcdir)/src/httpserver/*.hpp)
+	@rm -rf $(CHECK_HYGIENE_STAGE)
+	@$(MAKE) $(AM_MAKEFLAGS) install DESTDIR=$(CHECK_HYGIENE_STAGE) >check-hygiene-install.log 2>&1 || { \
+	    echo "FAIL: staged install failed"; cat check-hygiene-install.log; \
+	    rm -f check-hygiene-install.log; rm -rf $(CHECK_HYGIENE_STAGE); exit 1; }
+	@rm -f check-hygiene-install.log
+	@touch $(HYGIENE_STAMP)
+
+check-hygiene:
+	@echo "=== check-hygiene: <httpserver.hpp> must not transitively include backend headers ==="
+	@if test "$(CHECK_HYGIENE_SHARED)" != "yes"; then \
+	    $(MAKE) $(AM_MAKEFLAGS) $(HYGIENE_STAMP); \
+	else \
+	    if ! test -d "$(CHECK_HYGIENE_STAGE)"; then \
+	        echo "FAIL: CHECK_HYGIENE_SHARED=yes but stage dir '$(CHECK_HYGIENE_STAGE)' does not exist."; \
+	        echo "  Always pair CHECK_HYGIENE_SHARED=yes with CHECK_HYGIENE_STAGE=<valid-dir>."; \
+	        exit 1; \
+	    fi; \
+	fi
+	@status=0; \
+	if ! $(CHECK_HYGIENE_CXX) $(top_srcdir)/test/headers/consumer_umbrella_no_backend.cpp >check-hygiene.i 2>check-hygiene.err; then \
+	    if test "$(HEADER_HYGIENE_STRICT)" = "yes"; then \
+	        echo "FAIL: preprocessor failed"; cat check-hygiene.err; \
+	        status=1; \
+	    else \
+	        echo "EXPECTED-FAIL (informational until M5): preprocessor failed against staged install."; \
+	        echo "  This is expected while M2-M5 are in flight (e.g. webserver.hpp still"; \
+	        echo "  references private detail headers that aren't shipped)."; \
+	        echo "  Tail of preprocessor diagnostics:"; \
+	        sed 's/^/    /' check-hygiene.err | tail -10; \
+	    fi; \
+	else \
+	    leaks=`grep -hE '^# [0-9]+ "[^"]*/($(HEADER_HYGIENE_FORBIDDEN))"' check-hygiene.i | awk '{print $$3}' | sort -u`; \
+	    if test -n "$$leaks"; then \
+	        if test "$(HEADER_HYGIENE_STRICT)" = "yes"; then \
+	            echo "FAIL: forbidden headers leaked through <httpserver.hpp>:"; \
+	            echo "$$leaks"; \
+	            status=1; \
+	        else \
+	            echo "EXPECTED-FAIL (informational until M5): forbidden headers currently leak through <httpserver.hpp>:"; \
+	            echo "$$leaks"; \
+	        fi; \
+	    else \
+	        echo "  PASS: no forbidden headers reached the consumer TU"; \
+	    fi; \
+	fi; \
+	rm -f check-hygiene.i check-hygiene.err; \
+	exit $$status
+
+# check-local runs check-install-layout and check-hygiene against a single
+# 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
+	@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 || { \
+	    echo "FAIL: shared staged install failed"; cat check-shared-install.log; \
+	    rm -f check-shared-install.log; rm -rf $(abs_top_builddir)/.shared-check-stage; exit 1; }
+	@rm -f check-shared-install.log
+	@$(MAKE) $(AM_MAKEFLAGS) check-install-layout \
+	    CHECK_INSTALL_STAGE=$(abs_top_builddir)/.shared-check-stage \
+	    CHECK_INSTALL_SHARED=yes
+	@$(MAKE) $(AM_MAKEFLAGS) check-hygiene \
+	    CHECK_HYGIENE_STAGE=$(abs_top_builddir)/.shared-check-stage \
+	    CHECK_HYGIENE_SHARED=yes
+	@rm -rf $(abs_top_builddir)/.shared-check-stage
+
+# TASK-040: enforce static invariants on the two flagship examples
+# (hello_world.cpp <= 10 LOC, lambda-only; shared_state.cpp class+mutex).
+# Run as part of `make check` via check-local.
+check-examples:
+	@echo "=== check-examples: enforce TASK-040 invariants on examples/ ==="
+	@$(top_srcdir)/scripts/check-examples.sh
+
+.PHONY: check-headers check-install-layout check-hygiene check-examples
+
+# TASK-039: top-level convenience rule that descends into test/ to
+# build and run the bench binaries (see test/Makefile.am and
+# test/PERFORMANCE.md). NOT wired into `make check`; release-mode
+# only.
+bench:
+	$(MAKE) -C test bench
+
+.PHONY: bench
 
 MOSTLYCLEANFILES = $(DX_CLEANFILES) *.gcda *.gcno *.gcov
 DISTCLEANFILES = DIST_REVISION
 
+clean-local:
+	rm -rf $(CHECK_HYGIENE_STAGE) $(abs_top_builddir)/.shared-check-stage $(CHECK_INSTALL_STAGE)
+
 pkgconfigdir = $(libdir)/pkgconfig
 pkgconfig_DATA = libhttpserver.pc
 

README.CentOS-7

@@ -1,7 +1,8 @@
 ## Cent OS 7 / RHEL 7
 
-CentOS 7 has a lower version of gcc (4.8.7) that is barely C++11 capable and this library
-needs a better compiler.  We recommend at least gcc 5+
+CentOS 7's stock gcc (4.8.7) is far too old: this library requires a C++20 compiler
+(gcc >= 10 or clang >= 13).
 
-We recommend installing devtoolset-8
-https://www.softwarecollections.org/en/scls/rhscl/devtoolset-8/
+Install gcc-toolset-14 (or newer) from the RHEL/CentOS Software Collections and
+`source /opt/rh/gcc-toolset-14/enable` before configuring. The same workaround applies
+to RHEL 9 systems whose stock gcc-11 lacks some C++20 library features.