refactor: split webserver.cpp 7-way + drop FILE_LOC_MAX to 500

Final step of the ratchet. The 2673-line webserver.cpp is decomposed
along the section markers already in the file into seven new TUs, each
focused on a single concern and well below the 500-line target. The
residual webserver.cpp keeps ctors / dtors / signal helpers / hooks
machinery and lands at 464 lines.

  src/detail/webserver_setup.cpp        437  MHD option array
                                              builders (add_base /
                                              tls / gnutls / extended /
                                              https_extra) + start-flag
                                              composers, daemon lifecycle
                                              (start, is_running, stop,
                                              run, run_wait, get_fdset,
                                              get_timeout, add_connection),
                                              and block_ip / unblock_ip.

  src/detail/webserver_register.cpp     360  register_path /
                                              register_prefix /
                                              register_resource (incl.
                                              the shared register_impl_
                                              funnel and detail::
                                              register_v2_route mirror)
                                              + unregister_impl_ /
                                              unregister_path /
                                              unregister_prefix /
                                              unregister_resource. Uses
                                              the shared route_tier
                                              helper.

  src/detail/webserver_routes.cpp       411  on_methods_ funnel + the
                                              seven on_* shortcuts +
                                              both route() overloads +
                                              the detail-namespace
                                              lambda_shim helpers
                                              (prepare_or_create_lambda_shim,
                                              commit_handlers_to_shim,
                                              insert_fresh_v1_entries,
                                              upsert_v2_table_entry +
                                              its sub-helpers). Uses
                                              the shared route_tier.

  src/detail/webserver_callbacks.cpp    477  MHD trampolines registered
                                              with libmicrohttpd
                                              (request_completed,
                                              connection_notify, policy_
                                              callback, error_log,
                                              access_log, uri_log,
                                              unescaper_func, PSK/SNI
                                              cred handlers) + the
                                              post_iterator family
                                              (handle_post_form_arg,
                                              setup_new_upload_file_info,
                                              manage_upload_stream,
                                              process_file_upload, the
                                              post_iterator trampoline).

  src/detail/webserver_websocket.cpp    227  HAVE_WEBSOCKET-gated TU.
                                              decode_websocket_buffer
                                              static helper +
                                              upgrade_handler MHD
                                              callback + the anonymous-
                                              namespace handshake
                                              helpers.

  src/detail/webserver_dispatch.cpp     460  Dispatch support services:
                                              not_found_page /
                                              method_not_allowed_page /
                                              internal_error_page /
                                              log_dispatch_error /
                                              run_internal_error_handler_safely
                                              + invalidate_route_cache +
                                              lookup_v2 (the v2 3-tier
                                              walk) + the route-table
                                              helpers
                                              (lookup_route_cache,
                                              scan_regex_routes,
                                              store_route_cache,
                                              apply_extracted_params,
                                              resolve_resource_for_request,
                                              apply_auth_short_circuit,
                                              dispatch_resource_handler).

  src/detail/webserver_request.cpp      488  Request lifecycle:
                                              should_skip_auth + its
                                              normalize_path helper +
                                              requests_answer_first_step /
                                              requests_answer_second_step,
                                              materialize_response /
                                              decorate_mhd_response /
                                              get_raw_response_with_fallback,
                                              the websocket-upgrade
                                              dispatch helpers
                                              (validate_websocket_handshake,
                                              complete_websocket_upgrade,
                                              try_handle_websocket_upgrade),
                                              materialize_and_queue_response,
                                              finalize_answer,
                                              complete_request,
                                              resolve_method_callback,
                                              and the answer_to_connection
                                              entrypoint.

  src/webserver.cpp                     464  Residual: license / includes
                                              / signal helpers
                                              (catcher, ignore_sigpipe)
                                              / webserver_impl ctor +
                                              dtor / webserver ctor +
                                              dtor + features() +
                                              stop_and_wait() / the
                                              TASK-045 hook bus
                                              (register_hook_impl
                                              anonymous-namespace helper
                                              + make_hook_handle_ +
                                              the eleven add_hook
                                              overloads).

One small companion header was extracted to share state across TUs:

  src/httpserver/detail/route_tier.hpp        Hoists the route_tier_kind
                                              enum + route_tier_result
                                              struct + classify_route_tier
                                              from an anonymous namespace
                                              in webserver.cpp into a
                                              detail header. Both
                                              webserver_register.cpp and
                                              webserver_routes.cpp call
                                              classify_route_tier; an
                                              anonymous-namespace
                                              definition no longer
                                              suffices once the TU is
                                              split. Marked inline so
                                              the ODR holds across
                                              translation units.

normalize_path (and its apply_normalized_segment helper) — formerly
file-scope statics in webserver.cpp — co-locate with their only caller
(webserver_impl::should_skip_auth) in webserver_request.cpp.

FILE_LOC_MAX drops from 2700 to 500, the long-term project target.
The header comment in scripts/check-file-size.sh records the seven
ratchet steps that drove it down.

Verification:
  make check                          ALL PASS (includes hygiene,
                                      install-layout, doxygen, examples,
                                      readme, release-notes)
  ./scripts/check-file-size.sh        PASS at FILE_LOC_MAX=500

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

Author: etr

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

scripts/check-file-size.sh

@@ -29,22 +29,30 @@
 # scripts/check-complexity.sh. New files must come in well below the
 # long-term target; lifting FILE_LOC_MAX is not allowed.
 #
-# Current offenders above the long-term 500-line target (2026-05-22):
-#   src/webserver.cpp                          2673
+# Long-term target reached (2026-05-22): every .cpp/.hpp under src/ is
+# below the 500-line ceiling. The ratchet completed in seven steps:
 #
-# FILE_LOC_MAX is pinned by the largest unfixed file (webserver.cpp at
-# 2673), so it cannot drop until the top offender is decomposed. The
-# ratchet ticks once per shrink of the worst file, not once per fixed
-# offender — taking down a smaller file removes it from the list above
-# but leaves the threshold where it is.
+#   1. extract ip_representation from http_utils.hpp           (505 -> 478)
+#   2. extract auth surface from http_request.hpp              (656 -> 497)
+#   3. split webserver_impl.hpp into connection_state and
+#      webserver_impl_dispatch.hpp                              (674 -> 330)
+#   4. extract ip_representation impl from http_utils.cpp      (730 -> 493)
+#   5. split webserver.hpp into routes/ws/hooks sub-headers    (845 -> 498)
+#   6. split http_request.cpp 4-way (impl + impl_tls +
+#      http_request_auth + residual)                            (1175 -> 392)
+#   7. split webserver.cpp 7-way (setup + register + routes +
+#      callbacks + websocket + dispatch + request + residual)   (2673 -> 464)
+#
+# New files must come in well below the long-term target; lifting
+# FILE_LOC_MAX is not allowed.
 #
 # Exit codes:
 #   0  no violations
 #   1  one or more files exceed FILE_LOC_MAX
 set -euo pipefail
 
 REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-FILE_LOC_MAX="${FILE_LOC_MAX:-2700}"
+FILE_LOC_MAX="${FILE_LOC_MAX:-500}"
 
 cd "$REPO_ROOT"
 

src/Makefile.am

@@ -25,11 +25,11 @@ lib_LTLIBRARIES = libhttpserver.la
 # 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_request_auth.cpp http_response.cpp create_webserver.cpp create_test_request.cpp websocket_handler.cpp hook_handle.cpp detail/http_endpoint.cpp detail/body.cpp detail/ip_representation.cpp detail/http_request_impl.cpp detail/http_request_impl_tls.cpp
+libhttpserver_la_SOURCES = string_utilities.cpp webserver.cpp http_utils.cpp file_info.cpp http_request.cpp http_request_auth.cpp http_response.cpp create_webserver.cpp create_test_request.cpp websocket_handler.cpp hook_handle.cpp detail/http_endpoint.cpp detail/body.cpp detail/ip_representation.cpp detail/http_request_impl.cpp detail/http_request_impl_tls.cpp detail/webserver_setup.cpp detail/webserver_register.cpp detail/webserver_routes.cpp detail/webserver_callbacks.cpp detail/webserver_websocket.cpp detail/webserver_dispatch.cpp detail/webserver_request.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/webserver_impl_dispatch.hpp httpserver/detail/connection_state.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
+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/webserver_impl_dispatch.hpp httpserver/detail/connection_state.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 httpserver/detail/route_tier.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/webserver_routes.hpp httpserver/webserver_websocket.hpp httpserver/webserver_hooks.hpp httpserver/websocket_handler.hpp httpserver/http_utils.hpp httpserver/ip_representation.hpp httpserver/file_info.hpp httpserver/http_request.hpp httpserver/http_request_auth.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 httpserver/hook_phase.hpp httpserver/hook_action.hpp httpserver/hook_handle.hpp httpserver/hook_context.hpp
 
 AM_CXXFLAGS += -fPIC -Wall