Merge TASK-034: Build-flag-independent public API + webserver::features() (PRD-FLG-REQ-001..005)

Author: etr

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

@@ -8,12 +8,12 @@
 Remove `#ifdef HAVE_*` from public headers and provide runtime feature reporting plus documented sentinel/throw behavior when a build-disabled feature is invoked.
 
 **Action Items:**
-- [ ] Remove `#ifdef HAVE_BAUTH | HAVE_DAUTH | HAVE_GNUTLS | HAVE_WEBSOCKET` guards from every public header — the methods are now declared unconditionally.
-- [ ] Implementation files: when the relevant `HAVE_*` is undefined, the implementation either returns the documented sentinel (empty `string_view`, `false`, `-1`) or throws `feature_unavailable` per §7.
-- [ ] Add `webserver::features()` returning `struct features { bool basic_auth; bool digest_auth; bool tls; bool websocket; };`. Implementation reads compile-time `HAVE_*` and returns a value.
-- [ ] `create_webserver::use_ssl(true)` on a non-TLS build throws `feature_unavailable` at `webserver` construction time (consistent across all features per §7).
-- [ ] `register_ws_resource` on a non-WebSocket build throws `feature_unavailable`.
-- [ ] Confirm `feature_unavailable.what()` always names both feature and the controlling flag (TASK-003 invariant).
+- [x] Remove `#ifdef HAVE_BAUTH | HAVE_DAUTH | HAVE_GNUTLS | HAVE_WEBSOCKET` guards from every public header — the methods are now declared unconditionally.
+- [x] Implementation files: when the relevant `HAVE_*` is undefined, the implementation either returns the documented sentinel (empty `string_view`, `false`, `-1`) or throws `feature_unavailable` per §7.
+- [x] Add `webserver::features()` returning `struct features { bool basic_auth; bool digest_auth; bool tls; bool websocket; };`. Implementation reads compile-time `HAVE_*` and returns a value.
+- [x] `create_webserver::use_ssl(true)` on a non-TLS build throws `feature_unavailable` at `webserver` construction time (consistent across all features per §7).
+- [x] `register_ws_resource` on a non-WebSocket build throws `feature_unavailable`.
+- [x] Confirm `feature_unavailable.what()` always names both feature and the controlling flag (TASK-003 invariant).
 
 **Dependencies:**
 - Blocked by: TASK-003, TASK-019, TASK-033
@@ -29,4 +29,4 @@ Remove `#ifdef HAVE_*` from public headers and provide runtime feature reporting
 **Related Requirements:** PRD-FLG-REQ-001..005
 **Related Decisions:** §7
 
-**Status:** Not Started
+**Status:** Done

specs/tasks/_index.md

@@ -116,7 +116,7 @@ Nominally: **13 sequential tasks**, each S–XL. Most other tasks parallelize of
 | TASK-031 | Handler error-propagation contract (DR-009) | M5 | Done | TASK-027, TASK-030 |
 | TASK-032 | Thread-safety contract stress test (DR-008) | M5 | Done | TASK-027, TASK-031 |
 | TASK-033 | `create_webserver` builder cleanup | M5 | Done | TASK-006, TASK-014 |
-| TASK-034 | Build-flag-independent public API + `webserver::features()` | M5 | Not Started | TASK-003, TASK-019, TASK-033 |
+| TASK-034 | Build-flag-independent public API + `webserver::features()` | M5 | Done | TASK-003, TASK-019, TASK-033 |
 | TASK-035 | Smart-pointer `register_ws_resource` overloads | M5 | Not Started | TASK-014, TASK-034 |
 | TASK-036 | Handler return-by-value dispatch cutover | M5 | Not Started | TASK-022, TASK-025, TASK-027, TASK-031 |
 | TASK-037 | CI test for build-flag invariance | M6 | Not Started | TASK-034 |

specs/unworked_review_issues/2026-05-14_211841_task-034.md

@@ -19,17 +19,18 @@
 AM_CPPFLAGS = -I../ -I$(srcdir)/httpserver/ -DHTTPSERVER_COMPILATION
 METASOURCES = AUTO
 lib_LTLIBRARIES = libhttpserver.la
-libhttpserver_la_SOURCES = string_utilities.cpp webserver.cpp http_utils.cpp file_info.cpp http_request.cpp http_response.cpp http_resource.cpp create_webserver.cpp create_test_request.cpp detail/http_endpoint.cpp detail/body.cpp
+# TASK-034 / PRD-FLG-REQ-001: websocket_handler.cpp is built and
+# websocket_handler.hpp is installed unconditionally so the public
+# surface is identical across HAVE_WEBSOCKET-on and HAVE_WEBSOCKET-off
+# builds. The WS-off branch in websocket_handler.cpp provides stub
+# definitions (every member throws feature_unavailable except is_valid()
+# which returns false).
+libhttpserver_la_SOURCES = string_utilities.cpp webserver.cpp http_utils.cpp file_info.cpp http_request.cpp http_response.cpp http_resource.cpp create_webserver.cpp create_test_request.cpp websocket_handler.cpp detail/http_endpoint.cpp detail/body.cpp
 # noinst_HEADERS: shipped in the tarball but NEVER installed under $prefix/include.
 # Detail headers (httpserver/detail/*.hpp) live here so they cannot leak to
 # downstream consumers — the public surface comes in through <httpserver.hpp>.
 noinst_HEADERS = httpserver/string_utilities.hpp httpserver/detail/modded_request.hpp httpserver/detail/http_endpoint.hpp httpserver/detail/body.hpp httpserver/detail/webserver_impl.hpp httpserver/detail/http_request_impl.hpp httpserver/detail/route_entry.hpp httpserver/detail/lambda_resource.hpp httpserver/detail/radix_tree.hpp httpserver/detail/route_cache.hpp gettext.h
-nobase_include_HEADERS = httpserver.hpp httpserver/body_kind.hpp httpserver/constants.hpp httpserver/create_webserver.hpp httpserver/create_test_request.hpp httpserver/webserver.hpp httpserver/http_utils.hpp httpserver/file_info.hpp httpserver/http_request.hpp httpserver/http_response.hpp httpserver/http_resource.hpp httpserver/feature_unavailable.hpp httpserver/iovec_entry.hpp httpserver/http_arg_value.hpp httpserver/http_method.hpp
-
-if HAVE_WEBSOCKET
-libhttpserver_la_SOURCES += websocket_handler.cpp
-nobase_include_HEADERS += httpserver/websocket_handler.hpp
-endif
+nobase_include_HEADERS = httpserver.hpp httpserver/body_kind.hpp httpserver/constants.hpp httpserver/create_webserver.hpp httpserver/create_test_request.hpp httpserver/webserver.hpp httpserver/websocket_handler.hpp httpserver/http_utils.hpp httpserver/file_info.hpp httpserver/http_request.hpp httpserver/http_response.hpp httpserver/http_resource.hpp httpserver/feature_unavailable.hpp httpserver/iovec_entry.hpp httpserver/http_arg_value.hpp httpserver/http_method.hpp
 
 AM_CXXFLAGS += -fPIC -Wall
 

src/Makefile.am

@@ -39,6 +39,31 @@
 
 namespace httpserver {
 
+// TASK-034 / PRD-FLG-REQ-001: defined here (not as a default member
+// initializer in the header) so the public header carries no
+// #ifdef HAVE_BAUTH. The library was compiled with the right
+// HAVE_BAUTH state; the consumer TU's HAVE_BAUTH is irrelevant.
+bool create_webserver::basic_auth_default() noexcept {
+#ifdef HAVE_BAUTH
+    return true;
+#else
+    return false;
+#endif
+}
+
+// security-reviewer-iter1-1 / PRD-FLG-REQ-001: same pattern as
+// basic_auth_default(). Returns true on HAVE_DAUTH-on builds
+// (preserving historical behaviour) and false on HAVE_DAUTH-off builds
+// so that an unmodified builder doesn't trip the feature_unavailable
+// throw added to webserver::webserver() for HAVE_DAUTH-off builds.
+bool create_webserver::digest_auth_default() noexcept {
+#ifdef HAVE_DAUTH
+    return true;
+#else
+    return false;
+#endif
+}
+
 create_webserver& create_webserver::bind_address(const std::string& ip) {
     _bind_address_storage = std::make_shared<struct sockaddr_storage>();
     std::memset(_bind_address_storage.get(), 0, sizeof(struct sockaddr_storage));

src/create_webserver.cpp

@@ -744,13 +744,21 @@ const std::string http_request::get_path_piece(int index) const {
     return EMPTY;
 }
 
-#ifdef HAVE_DAUTH
 http::http_utils::digest_auth_result http_request::check_digest_auth(
     const std::string& realm,
     const std::string& password,
     unsigned int nonce_timeout,
     uint32_t max_nc,
     http::http_utils::digest_algorithm algo) const {
+#ifdef HAVE_DAUTH
+    // CWE-476 guard: test-request path sets connection_ to nullptr.
+    // Passing nullptr to MHD_digest_auth_check3 is undefined behaviour;
+    // return the same WRONG_HEADER sentinel used on the HAVE_DAUTH-off
+    // path and by get_digested_user() when connection_ is null.
+    if (impl_->connection_ == nullptr) {
+        return http::http_utils::digest_auth_result::WRONG_HEADER;
+    }
+
     std::string_view digested_user = get_digested_user();
 
     enum MHD_DigestAuthResult result = MHD_digest_auth_check3(
@@ -764,6 +772,18 @@ http::http_utils::digest_auth_result http_request::check_digest_auth(
         static_cast<MHD_DigestAuthMultiAlgo3>(algo));
 
     return static_cast<http::http_utils::digest_auth_result>(result);
+#else
+    // TASK-034 §7 sentinel: DAUTH disabled at build time -> the
+    // call is documented to "return a sentinel result". WRONG_HEADER
+    // is the most explicit "this request was never authenticated"
+    // terminal value of the digest_auth_result enum.
+    (void)realm;
+    (void)password;
+    (void)nonce_timeout;
+    (void)max_nc;
+    (void)algo;
+    return http::http_utils::digest_auth_result::WRONG_HEADER;
+#endif
 }
 
 http::http_utils::digest_auth_result http_request::check_digest_auth_digest(
@@ -773,6 +793,12 @@ http::http_utils::digest_auth_result http_request::check_digest_auth_digest(
     unsigned int nonce_timeout,
     uint32_t max_nc,
     http::http_utils::digest_algorithm algo) const {
+#ifdef HAVE_DAUTH
+    // CWE-476 guard: same null-connection guard as check_digest_auth.
+    if (impl_->connection_ == nullptr) {
+        return http::http_utils::digest_auth_result::WRONG_HEADER;
+    }
+
     std::string_view digested_user = get_digested_user();
 
     enum MHD_DigestAuthResult result = MHD_digest_auth_check_digest3(
@@ -787,8 +813,16 @@ http::http_utils::digest_auth_result http_request::check_digest_auth_digest(
         static_cast<MHD_DigestAuthMultiAlgo3>(algo));
 
     return static_cast<http::http_utils::digest_auth_result>(result);
+#else
+    (void)realm;
+    (void)userdigest;
+    (void)userdigest_size;
+    (void)nonce_timeout;
+    (void)max_nc;
+    (void)algo;
+    return http::http_utils::digest_auth_result::WRONG_HEADER;
+#endif
 }
-#endif  // HAVE_DAUTH
 
 std::string_view http_request::get_header(std::string_view key) const {
     return impl_->get_connection_value(key, MHD_HEADER_KIND);
@@ -886,26 +920,33 @@ std::string_view http_request::get_querystring() const noexcept {
     return impl_->querystring;
 }
 
-#ifdef HAVE_BAUTH
 std::string_view http_request::get_user() const {
+#ifdef HAVE_BAUTH
     if (!impl_->username.empty()) {
         return impl_->username;
     }
     impl_->fetch_user_pass();
     return impl_->username;
+#else
+    // TASK-034 §7 sentinel: BAUTH disabled at build time -> empty view.
+    return std::string_view{};
+#endif
 }
 
 std::string_view http_request::get_pass() const {
+#ifdef HAVE_BAUTH
     if (!impl_->password.empty()) {
         return impl_->password;
     }
     impl_->fetch_user_pass();
     return impl_->password;
+#else
+    return std::string_view{};
+#endif
 }
-#endif  // HAVE_BAUTH
 
-#ifdef HAVE_DAUTH
 std::string_view http_request::get_digested_user() const {
+#ifdef HAVE_DAUTH
     if (!impl_->digested_user.empty()) {
         return impl_->digested_user;
     }
@@ -926,8 +967,11 @@ std::string_view http_request::get_digested_user() const {
     }
 
     return impl_->digested_user;
+#else
+    // TASK-034 §7 sentinel: DAUTH disabled at build time -> empty view.
+    return std::string_view{};
+#endif
 }
-#endif  // HAVE_DAUTH
 
 // ----------------------------------------------------------------------
 // TASK-019: high-level GnuTLS accessors. Public surface is unconditional
@@ -1104,9 +1148,10 @@ void http_request::set_file_cleanup_callback(file_cleanup_callback_ptr callback)
 
 std::ostream& operator<< (std::ostream& os, const http_request& r) {
     os << r.get_method() << " Request [";
-#ifdef HAVE_BAUTH
+    // TASK-034: get_user/get_pass are unconditional; they return empty
+    // on HAVE_BAUTH-off builds, so the dump prints two empty quoted
+    // strings in that case (harmless).
     os << "user:\"" << r.get_user() << "\" pass:\"" << r.get_pass() << "\"";
-#endif  // HAVE_BAUTH
     os << "] path:\"" << r.get_path() << "\"" << std::endl;
 
     http::dump_header_map(os, "Headers", r.get_headers());

src/http_request.cpp

@@ -39,9 +39,11 @@
 #include "httpserver/iovec_entry.hpp"
 #include "httpserver/file_info.hpp"
 #include "httpserver/webserver.hpp"
-#ifdef HAVE_WEBSOCKET
+// TASK-034: included unconditionally. websocket_handler.hpp is safe to
+// include in both HAVE_WEBSOCKET-on and HAVE_WEBSOCKET-off builds; the
+// member-function bodies in src/websocket_handler.cpp handle the
+// disabled-build sentinel behaviour (PRD-FLG-REQ-001).
 #include "httpserver/websocket_handler.hpp"
-#endif  // HAVE_WEBSOCKET
 
 #undef _HTTPSERVER_HPP_INSIDE_
 

src/httpserver.hpp

@@ -83,7 +83,10 @@ class create_test_request {
         return *this;
     }
 
-#ifdef HAVE_BAUTH
+    // TASK-034: setters are unconditional. On HAVE_BAUTH-off /
+    // HAVE_DAUTH-off builds the values are silently dropped on .build()
+    // (matching the sentinel-empty contract of the corresponding
+    // http_request accessors).
     create_test_request& user(const std::string& user) {
         _user = user;
         return *this;
@@ -93,14 +96,11 @@ class create_test_request {
         _pass = pass;
         return *this;
     }
-#endif  // HAVE_BAUTH
 
-#ifdef HAVE_DAUTH
     create_test_request& digested_user(const std::string& digested_user) {
         _digested_user = digested_user;
         return *this;
     }
-#endif  // HAVE_DAUTH
 
     create_test_request& requestor(const std::string& requestor) {
         _requestor = requestor;
@@ -112,12 +112,13 @@ class create_test_request {
         return *this;
     }
 
-#ifdef HAVE_GNUTLS
+    // TASK-034: setter is unconditional. On HAVE_GNUTLS-off builds the
+    // value is silently dropped (has_tls_session() returns false
+    // regardless — TASK-019 sentinel contract).
     create_test_request& tls_enabled(bool enabled = true) {
         _tls_enabled = enabled;
         return *this;
     }
-#endif  // HAVE_GNUTLS
 
     http_request build();
 
@@ -131,18 +132,16 @@ class create_test_request {
     http::header_map _cookies;
     std::map<std::string, std::vector<std::string>, http::arg_comparator> _args;
     std::string _querystring;
-#ifdef HAVE_BAUTH
+    // TASK-034: fields stored unconditionally. On HAVE_*-off builds the
+    // values are populated by the setters but silently dropped during
+    // .build() propagation, matching the sentinel-empty contract on
+    // the http_request accessor side.
     std::string _user;
     std::string _pass;
-#endif  // HAVE_BAUTH
-#ifdef HAVE_DAUTH
     std::string _digested_user;
-#endif  // HAVE_DAUTH
     std::string _requestor = "127.0.0.1";
     uint16_t _requestor_port = 0;
-#ifdef HAVE_GNUTLS
     bool _tls_enabled = false;
-#endif  // HAVE_GNUTLS
 };
 
 }  // namespace httpserver

src/httpserver/create_test_request.hpp

@@ -121,9 +121,11 @@ class create_webserver {
      create_webserver& nonce_nc_size(int v) { check_non_negative("nonce_nc_size", v); _nonce_nc_size = v; return *this; }
      create_webserver& default_policy(const http::http_utils::policy_T& v) { _default_policy = v; return *this; }
 
-#ifdef HAVE_BAUTH
+     // TASK-034 / PRD-FLG-REQ-001: setter is unconditional. The actual
+     // validation lives in webserver(const create_webserver&), which
+     // throws feature_unavailable when this is set to true on a
+     // HAVE_BAUTH-off build.
      create_webserver& basic_auth(bool enable = true) { _basic_auth_enabled = enable; return *this; }
-#endif  // HAVE_BAUTH
      create_webserver& digest_auth(bool enable = true) { _digest_auth_enabled = enable; return *this; }
      create_webserver& deferred(bool enable = true) { _deferred_enabled = enable; return *this; }
      create_webserver& regex_checking(bool enable = true) { _regex_checking = enable; return *this; }
@@ -209,10 +211,18 @@ class create_webserver {
      std::string _digest_auth_random = "";
      int _nonce_nc_size = 0;
      http::http_utils::policy_T _default_policy = http::http_utils::ACCEPT;
-#ifdef HAVE_BAUTH
-     bool _basic_auth_enabled = true;
-#endif  // HAVE_BAUTH
-     bool _digest_auth_enabled = true;
+     // TASK-034: stored unconditionally. The default values are computed
+     // by basic_auth_default() and digest_auth_default() in
+     // create_webserver.cpp, where the HAVE_BAUTH / HAVE_DAUTH build
+     // flags are reachable — that keeps the public header free of
+     // build-flag preprocessor gates (PRD-FLG-REQ-001) while preserving
+     // the historical defaults (true on the respective auth-on builds;
+     // false on auth-off builds so an unmodified builder doesn't trip
+     // the feature_unavailable throw at construction time).
+     static bool basic_auth_default() noexcept;
+     static bool digest_auth_default() noexcept;
+     bool _basic_auth_enabled = basic_auth_default();
+     bool _digest_auth_enabled = digest_auth_default();
      bool _regex_checking = true;
      bool _ban_system_enabled = true;
      bool _post_process_enabled = true;