Merge TASK-040: Rewrite examples/ for the v2.0 lambda-first idiom (PRD §3.4, PRD-HDL-REQ-001..006)

Three commits on task/TASK-040:
1. Rewrite the example suite to v2.0 idioms (`on_get` + lambda where it
   shines, `http_resource` class form with `std::make_unique` where
   shared state belongs in a class), add hello_world.cpp (≤10 LOC) and
   shared_state.cpp as the canonical pair, plus
   scripts/check-examples.sh (wired into `make check`) and
   scripts/verify-installed-examples.sh (compiles every example
   against an installed prefix to validate the consumer view of the
   v2.0 headers).
2. Validation-loop fixes: `override` everywhere, `make_shared`
   consistency, comment hygiene, hardened CI scripts (`set -eo
   pipefail`, mktemp trap cleanup, asserted compile count).
3. Snapshot of the unworked findings (1 major, 81 minor, 0 critical).

Verified: `make check` 48/48 green, `scripts/check-examples.sh` and
`scripts/verify-installed-examples.sh` both green on release and
`--enable-debug` builds of every example.

Author: etr

Makefile.am

@@ -39,6 +39,7 @@ endif
 endif
 
 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
@@ -281,7 +282,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-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 || { \
@@ -296,7 +297,14 @@ check-local: check-headers
 	    CHECK_HYGIENE_SHARED=yes
 	@rm -rf $(abs_top_builddir)/.shared-check-stage
 
-.PHONY: check-headers check-install-layout check-hygiene
+# 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

examples/Makefile.am

@@ -19,11 +19,11 @@
 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
+noinst_PROGRAMS = hello_world shared_state service 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
 
 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

examples/README.md

@@ -1,58 +1,122 @@
-Example Programs
-================
-
-hello_world.cpp	- a very simple example of using libhttpserver to
-		  create a Rest server capable of receiving and processing
-		  HTTP requests.  The server will be listening on port
-		  8080.
-
-
-service.cpp	- an example using more of the libhttpserver API.
-		  This creates a Rest server capable of running with
-		  HTTP or HTTPS (provided that libhttpserver and
-		  libmicrohttpd have been compiled with SSL support.
-
-		  The server can be configured via command line
-		  arguments:
+libhttpserver Examples
+======================
 
-		  -p <port>  - port number to listen on (default 8080)
-		  -s         - enable HTTPS
-		  -k         - server key filename (default "key.pem")
-		  -c         - server certificate filename (default "cert.pem")
+Every example is a standalone program built from a single `.cpp`. To
+build the suite locally:
+
+    ./bootstrap && mkdir build && cd build && ../configure && make
+
+Each binary lands in `build/examples/`. To verify that an example also
+compiles against an *installed* libhttpserver (the consumer view), run
+`scripts/verify-installed-examples.sh` after `make install`. To enforce
+the structural invariants on `hello_world.cpp` and `shared_state.cpp`
+(LOC budget, lambda-only form, mutex usage), run
+`scripts/check-examples.sh`.
+
+Start here
+----------
+
+* `hello_world.cpp` — ten lines, no subclassing, no raw pointers. The
+  canonical "hello world" demo and the PRD §3.4 acceptance fixture for
+  the v2.0 lambda idiom.
+* `shared_state.cpp` — the canonical example of when the class form is
+  the right shape: an `http_resource` subclass that shares a `std::mutex`-
+  guarded counter between `render_get` and `render_post`.
+
+HTTP basics
+-----------
+
+* `setting_headers.cpp` — attach response headers fluently with
+  `with_header`.
+* `hello_with_get_arg.cpp` — read a query-string parameter from
+  `http_request::get_arg`.
+* `args_processing.cpp` — iterate every form/query argument.
+* `custom_error.cpp` — install custom `not_found_handler` and
+  `method_not_allowed_handler` and let `set_allowing` restrict methods
+  on a resource.
+* `allowing_disallowing_methods.cpp` — narrow a resource to a single
+  HTTP method via the allow mask.
+* `url_registration.cpp` — exact paths, prefix matches, regex paths,
+  and parametric segments (with optional per-segment regex).
+* `handlers.cpp` — register distinct lambdas for GET and POST on the
+  same path; the dispatcher composes them.
+
+Response shapes
+---------------
+
+* `minimal_file_response.cpp` — stream a file from disk.
+* `binary_buffer_response.cpp` — return a binary buffer (e.g. a PNG).
+* `iovec_response_example.cpp` — gather a response body from multiple
+  borrowed buffers without copying.
+* `pipe_response_example.cpp` — stream from a pipe filled by a
+  background thread.
+* `empty_response_example.cpp` — bodyless responses for DELETE / HEAD.
+* `minimal_deferred.cpp` — deferred response: the body is produced
+  asynchronously by a callback.
+* `deferred_with_accumulator.cpp` — deferred response that mutates
+  shared state across calls.
+
+TLS and authentication
+----------------------
+
+* `minimal_https.cpp` — enable TLS with PEM key/cert files.
+* `minimal_https_psk.cpp` — TLS with pre-shared keys.
+* `basic_authentication.cpp` — per-request HTTP Basic auth inside the
+  handler.
+* `centralized_authentication.cpp` — server-wide `auth_handler` and
+  `auth_skip_paths`.
+* `digest_authentication.cpp` — per-request HTTP Digest auth via
+  `http_request::check_digest_auth`.
+* `client_cert_auth.cpp` — mutual TLS with X.509 client certificates.
+  Ships as a documentation artifact; not wired into `noinst_PROGRAMS`.
+
+Operations
+----------
+
+* `daemon_info.cpp` — introspect the running daemon (bound port,
+  listen FD, active connections).
+* `external_event_loop.cpp` — drive `EXTERNAL_SELECT` from the
+  application's loop via `run_wait`.
+* `custom_access_log.cpp` — server-wide access-log callback.
+* `minimal_ip_ban.cpp` — `block_ip` / `unblock_ip` under the default
+  ACCEPT policy.
+* `turbo_mode.cpp` — turbo, suppressed Date header, fastopen queue,
+  listen backlog.
+* `service.cpp` — the kitchen-sink reference example: CLI args,
+  optional TLS, all `render_*` overrides.
+
+Benchmarks
+----------
+
+* `benchmark_select.cpp`, `benchmark_threads.cpp`,
+  `benchmark_nodelay.cpp` — micro-benchmarks. See `test/v1_baseline/` for
+  v1.x reference numbers.
+
+WebSockets
+----------
+
+* `websocket_echo.cpp` — `websocket_handler` subclass registered via
+  `register_ws_resource` with `std::make_unique`.
+
+File upload
+-----------
+
+* `file_upload.cpp`, `file_upload_with_callback.cpp` — multipart
+  upload, GET serves the HTML form and POST processes the parts.
 
 Creating Certificates
 =====================
+
 Self-signed certificates can be created using OpenSSL using the
 following steps:
 
-	  $ openssl genrsa -des3 -passout pass:x -out server.pass.key 2048
-	  $ openssl rsa -passin pass:x -in server.pass.key -out server.key
-	  $ openssl req -new -key server.key -out server.csr
-	  $ openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt
+    $ openssl genrsa -des3 -passout pass:x -out server.pass.key 2048
+    $ openssl rsa -passin pass:x -in server.pass.key -out server.key
+    $ openssl req -new -key server.key -out server.csr
+    $ openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt
 
 On the last step when prompted for a challenge password it can be left
 empty.
 
 Thanks to https://devcenter.heroku.com/articles/ssl-certificate-self
 for these instructions.
-
-Keystore configuration
-======================
-If using a local client such as RestClient
-(https://github.com/wiztools/rest-client) for testing the Rest server
-then a keystore needs to be established.  These commands should be
-bundled with your Java installation.
-
-$ keytool -noprompt -import -keystore /path/to/restclient.store -alias
-restclient -file /path/to/server.crt
-
-The keys in the store can be listed as follows:
-
-$ keytool -list -v -keystore /path/to/restclient.store
-
-The client can then be configured to use this keystore.  Thanks to
-http://rubensgomes.blogspot.com/2012/01/how-to-set-up-restclient-for-ssl.html
-for instructions on configuring RestClient.
-
-
-

examples/allowing_disallowing_methods.cpp

@@ -22,6 +22,11 @@
 
 #include <httpserver.hpp>
 
+// The class form is required here: disallow_all() and set_allowing() are
+// methods on http_resource that control which HTTP methods are accepted.
+// Lambda-registered routes (ws.on_get / ws.on_post / etc.) target a single
+// method by construction and do not expose these per-resource controls.
+// Use the class form whenever you need fine-grained per-instance method ACLs.
 class hello_world_resource : public httpserver::http_resource {
  public:
      httpserver::http_response render(const httpserver::http_request&) {

examples/args_processing.cpp

@@ -1,6 +1,6 @@
 /*
     This file is part of libhttpserver
-    Copyright (C) 2011, 2012, 2013, 2014, 2015 Sebastiano Merlino
+    Copyright (C) 2011-2025 Sebastiano Merlino
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -18,25 +18,26 @@
     USA
 */
 
-#include <iostream>
-#include <memory>
-#include <sstream>
-#include <string>
-
-#include <httpserver.hpp>
-
-// This example demonstrates how to use get_args() and get_args_flat() to
+// args_processing.cpp - demonstrates get_args() and get_args_flat() to
 // process all query string and body arguments from an HTTP request.
 //
 // Try these URLs:
 //   http://localhost:8080/args?name=john&age=30
 //   http://localhost:8080/args?id=1&id=2&id=3  (multiple values for same key)
 //   http://localhost:8080/args?colors=red&colors=green&colors=blue
 
-class args_resource : public httpserver::http_resource {
- public:
-    httpserver::http_response render(const httpserver::http_request& req) {
-        std::stringstream response_body;
+#include <iostream>
+#include <sstream>
+#include <string>
+#include <string_view>
+
+#include <httpserver.hpp>
+
+int main() {
+    httpserver::webserver ws{httpserver::create_webserver(8080)};
+
+    ws.on_get("/args", [](const httpserver::http_request& req) {
+        std::ostringstream response_body;
 
         response_body << "=== Using get_args() (supports multiple values per key) ===\n\n";
 
@@ -83,20 +84,12 @@ class args_resource : public httpserver::http_resource {
         }
 
         return httpserver::http_response::string(response_body.str());
-    }
-};
-
-int main() {
-    httpserver::webserver ws{httpserver::create_webserver(8080)};
-
-    auto ar = std::make_shared<args_resource>();
-    ws.register_path("/args", ar);
+    });
 
     std::cout << "Server running on http://localhost:8080/args\n";
     std::cout << "Try: http://localhost:8080/args?name=john&age=30\n";
     std::cout << "Or:  http://localhost:8080/args?id=1&id=2&id=3\n";
 
     ws.start(true);
-
     return 0;
 }

examples/basic_authentication.cpp

@@ -1,6 +1,6 @@
 /*
      This file is part of libhttpserver
-     Copyright (C) 2011, 2012, 2013, 2014, 2015 Sebastiano Merlino
+     Copyright (C) 2011-2025 Sebastiano Merlino
 
      This library is free software; you can redistribute it and/or
      modify it under the terms of the GNU Lesser General Public
@@ -18,29 +18,31 @@
      USA
 */
 
-#include <memory>
+// basic_authentication.cpp - per-request HTTP Basic auth check inside a
+// lambda handler. For centralized auth that intercepts every request,
+// see centralized_authentication.cpp.
+//
+// NOTE: Credentials are hardcoded here for illustration only. In production,
+// load expected values from environment variables or a secrets store — never
+// from source code. Never reflect the password in the response body.
+
 #include <string>
 
 #include <httpserver.hpp>
 
-class user_pass_resource : public httpserver::http_resource {
- public:
-     httpserver::http_response render_get(const httpserver::http_request& req) {
-         if (req.get_user() != "myuser" || req.get_pass() != "mypass") {
-             return
-                 httpserver::http_response::unauthorized("Basic", "test@example.com", "FAIL");
-         }
-
-         return httpserver::http_response::string(std::string(req.get_user()) + " " + std::string(req.get_pass()));
-     }
-};
-
 int main() {
     httpserver::webserver ws{httpserver::create_webserver(8080)};
 
-    auto hwr = std::make_shared<user_pass_resource>();
-    ws.register_path("/hello", hwr);
-    ws.start(true);
+    ws.on_get("/hello", [](const httpserver::http_request& req) {
+        if (req.get_user() != "myuser" || req.get_pass() != "mypass") {
+            return httpserver::http_response::unauthorized(
+                "Basic", "test@example.com", "FAIL");
+        }
+        // Only echo the username — never reflect the password back to the client.
+        return httpserver::http_response::string(
+            "Hello, " + std::string(req.get_user()) + "!");
+    });
 
+    ws.start(true);
     return 0;
 }