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

@@ -1,5 +1,6 @@
 *.sw*
 *.*~
+*~
 *.in
 *.php
 *.pm
@@ -60,3 +61,5 @@ libtool
 .worktrees
 .claude
 CLAUDE.md
+.groundwork-plans/
+.DS_Store

ChangeLog

@@ -1,5 +1,29 @@
+Version 2.0.0
+
+	v2.0 release. See RELEASE_NOTES.md for the full v1->v2 porting summary.
+	SOVERSION bumped: shared library now ships as libhttpserver.so.2
+		(Linux) / libhttpserver.2.dylib (Darwin). Parallel-installable
+		with any prior libhttpserver.so.0/1 on disk (runtime artefacts
+		only; dev-time .la/.a/.pc/headers are last-installer-wins by
+		design).
+	Added per-function cyclomatic complexity gate
+		(scripts/check-complexity.sh via `lizard`) and copy/paste
+		detection gate (scripts/check-duplication.sh via PMD CPD with
+		the C++ tokenizer), wired into the existing CI lint lane and
+		exposed locally as `make lint-complexity` /
+		`make lint-duplication`. Initial CCN ceiling intentionally set
+		above the current worst offender so CI stays green; ratcheted
+		down per refactor commit until reaching the long-term target
+		of 10. Duplication gate runs at PMD's default
+		minimum-tokens=100 from day one (currently zero hits).
+
 Version 0.20.0
 
+	Raised minimum C++ standard to C++20. Build now requires gcc >= 11
+		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 +44,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

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 >= 11 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.

configure.ac

@@ -20,8 +20,8 @@
 # Process this file with autoconf to produce a configure script.
 
 AC_PREREQ(2.57)
-m4_define([libhttpserver_MAJOR_VERSION],[0])dnl
-m4_define([libhttpserver_MINOR_VERSION],[20])dnl
+m4_define([libhttpserver_MAJOR_VERSION],[2])dnl
+m4_define([libhttpserver_MINOR_VERSION],[0])dnl
 m4_define([libhttpserver_REVISION],[0])dnl
 m4_define([libhttpserver_PKG_VERSION],[libhttpserver_MAJOR_VERSION.libhttpserver_MINOR_VERSION.libhttpserver_REVISION])dnl
 m4_define([libhttpserver_LDF_VERSION],[libhttpserver_MAJOR_VERSION:libhttpserver_MINOR_VERSION:libhttpserver_REVISION])dnl
@@ -44,7 +44,7 @@ AC_LANG([C++])
 AC_SYS_LARGEFILE
 
 # Minimal feature-set required
-AX_CXX_COMPILE_STDCXX([17])
+AX_CXX_COMPILE_STDCXX([20], [noext], [mandatory])
 
 native_srcdir=$srcdir
 
@@ -80,10 +80,19 @@ For native Windows binaries, use the MinGW64 shell instead.
         ADDITIONAL_LIBS="-lpthread -no-undefined"
         NETWORK_LIBS="-lws2_32"
         native_srcdir=$(cd $srcdir; pwd -W)
+        # libmicrohttpd's <microhttpd.h> asserts _SYS_TYPES_FD_SET on Cygwin/MSYS.
+        # newlib defines that macro via <sys/select.h>, included from <sys/types.h>
+        # only when __BSD_VISIBLE -- i.e. when _DEFAULT_SOURCE is set. Strict ANSI
+        # C++ (-std=c++NN, AX_CXX_COMPILE_STDCXX noext) suppresses newlib's
+        # auto-define, so expose it explicitly here.
+        CPPFLAGS="-D_DEFAULT_SOURCE $CPPFLAGS"
         ;;
     *-cygwin*)
         NETWORK_HEADER="arpa/inet.h"
         ADDITIONAL_LIBS="-lpthread -no-undefined"
+        # See *-msys* note: libmicrohttpd's fd_set check needs _DEFAULT_SOURCE
+        # under -std=c++NN strict mode.
+        CPPFLAGS="-D_DEFAULT_SOURCE $CPPFLAGS"
         ;;
     *)
         NETWORK_HEADER="arpa/inet.h"
@@ -127,7 +136,11 @@ if test x"$host" = x"$build"; then
         [AC_MSG_ERROR(["microhttpd.h not found"])]
     )
 
-    CXXFLAGS="-DHTTPSERVER_COMPILATION -D_REENTRANT $LIBMICROHTTPD_CFLAGS $CXXFLAGS"
+    # -DHTTPSERVER_COMPILATION is intentionally NOT injected globally into
+    # CXXFLAGS. It is added per-target via AM_CPPFLAGS in src/Makefile.am and
+    # test/Makefile.am so that examples (and any other consumer-style TUs)
+    # build through the umbrella header without seeing the internal macro.
+    CXXFLAGS="-D_REENTRANT $LIBMICROHTTPD_CFLAGS $CXXFLAGS"
     LDFLAGS="$LIBMICROHTTPD_LIBS $NETWORK_LIBS $ADDITIONAL_LIBS $LDFLAGS"
 
     cond_cross_compile="no"
@@ -140,7 +153,9 @@ else
         [AC_MSG_ERROR(["microhttpd.h not found"])]
     )
 
-    CXXFLAGS="-DHTTPSERVER_COMPILATION -D_REENTRANT $CXXFLAGS"
+    # See note above: HTTPSERVER_COMPILATION is scoped to lib + tests via
+    # per-directory AM_CPPFLAGS, not injected globally into CXXFLAGS.
+    CXXFLAGS="-D_REENTRANT $CXXFLAGS"
     LDFLAGS="$NETWORK_LIBS $ADDITIONAL_LIBS $LDFLAGS"
 
     cond_cross_compile="yes"
@@ -221,7 +236,9 @@ AM_LDFLAGS="-lstdc++"
 
 if test x"$debugit" = x"yes"; then
     AC_DEFINE([DEBUG],[],[Debug Mode])
-    AM_CXXFLAGS="$AM_CXXFLAGS -DDEBUG -g -Wall -Wextra -Werror -pedantic -std=c++17 -Wno-unused-command-line-argument -O0"
+    # -std=c++20 is injected by AX_CXX_COMPILE_STDCXX into the CXX variable,
+    # not repeated here.  Omitting it avoids a double-standard flag conflict.
+    AM_CXXFLAGS="$AM_CXXFLAGS -DDEBUG -g -Wall -Wextra -Werror -pedantic -Wno-unused-command-line-argument -O0"
     AM_CFLAGS="$AM_CXXFLAGS -DDEBUG -g -Wall -Wextra -Werror -pedantic -Wno-unused-command-line-argument -O0"
 else
     AC_DEFINE([NDEBUG],[],[No-debug Mode])
@@ -308,7 +325,11 @@ DX_PDF_FEATURE(OFF)
 DX_PS_FEATURE(OFF)
 DX_INIT_DOXYGEN([$PACKAGE_NAME],[doxyconfig.in])
 
-LDFLAGS="$LDFLAGS -version-number libhttpserver_LDF_VERSION"
+# Export the libtool version-number triple so src/Makefile.am can scope it
+# to libhttpserver_la_LDFLAGS rather than injecting it into the global LDFLAGS
+# (which would affect all link steps, not just the shared library).
+LHT_LDF_VERSION="libhttpserver_LDF_VERSION"
+AC_SUBST(LHT_LDF_VERSION)
 
 AC_SUBST(LHT_LIBDEPS)
 AC_SUBST(AM_CXXFLAGS)

doxyconfig.in

@@ -610,7 +610,7 @@ RECURSIVE              = NO
 # excluded from the INPUT source files. This way you can easily exclude a
 # subdirectory from a directory tree whose root is specified with the INPUT tag.
 
-EXCLUDE                = test/* 
+EXCLUDE                = test/*
 
 # The EXCLUDE_SYMLINKS tag can be used select whether or not files or
 # directories that are symbolic links (a Unix filesystem feature) are excluded

examples/Makefile.am

@@ -19,24 +19,41 @@
 LDADD = $(top_builddir)/src/libhttpserver.la
 AM_CPPFLAGS = -I$(top_srcdir)/src -I$(top_srcdir)/src/httpserver/
 METASOURCES = AUTO
-noinst_PROGRAMS = hello_world service minimal_hello_world 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 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
+# client_cert_auth.cpp ships as a documentation artifact only; it is not
+# wired into noinst_PROGRAMS because it depends on extra GnuTLS APIs not
+# part of the public libhttpserver consumer surface.
+EXTRA_DIST = client_cert_auth.cpp
+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
 service_SOURCES = service.cpp
-minimal_hello_world_SOURCES = minimal_hello_world.cpp
 custom_error_SOURCES = custom_error.cpp
 allowing_disallowing_methods_SOURCES = allowing_disallowing_methods.cpp
 handlers_SOURCES = handlers.cpp
 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
 deferred_with_accumulator_SOURCES = deferred_with_accumulator.cpp
 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