refactor: extract ip_representation from http_utils.hpp (505 → 478)

First step of the FILE_LOC_MAX ratchet. Splits ip_representation
(struct + the five private parse helpers carved out during the CCN-10
sweep) into its own public sub-header httpserver/ip_representation.hpp.

http_utils.hpp keeps a re-include of the new header so existing
consumers of <httpserver/http_utils.hpp> still see the type without
any code change; the umbrella picks up the new header explicitly too
(every public sub-header is listed in <httpserver.hpp>). Detail
headers and downstream tests are unaffected — webserver_impl.hpp still
sees http::ip_representation through its existing http_utils.hpp
include.

FILE_LOC_MAX stays at 2700. The bar is pinned by the largest unfixed
file (webserver.cpp at 2673), so the threshold can't drop until the
top offender is decomposed. Each smaller-first step removes one file
from the offender list without ticking the bar; the bar steps happen
when the worst file shrinks.

Offender list updated in scripts/check-file-size.sh: six files remain
above the 500-line target.

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

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

Author: etr

scripts/check-file-size.sh

@@ -29,14 +29,19 @@
 # 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-21):
+# Current offenders above the long-term 500-line target (2026-05-22):
 #   src/webserver.cpp                          2673
 #   src/http_request.cpp                       1175
 #   src/httpserver/webserver.hpp                845
 #   src/http_utils.cpp                          730
 #   src/httpserver/detail/webserver_impl.hpp    674
 #   src/httpserver/http_request.hpp             656
-#   src/httpserver/http_utils.hpp               505
+#
+# 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.
 #
 # Exit codes:
 #   0  no violations

src/Makefile.am

@@ -30,7 +30,7 @@ libhttpserver_la_SOURCES = string_utilities.cpp webserver.cpp http_utils.cpp fil
 # 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/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 httpserver/hook_phase.hpp httpserver/hook_action.hpp httpserver/hook_handle.hpp httpserver/hook_context.hpp
+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/ip_representation.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 httpserver/hook_phase.hpp httpserver/hook_action.hpp httpserver/hook_handle.hpp httpserver/hook_context.hpp
 
 AM_CXXFLAGS += -fPIC -Wall
 

src/httpserver.hpp

@@ -40,6 +40,7 @@
 #include "httpserver/http_resource.hpp"
 #include "httpserver/http_response.hpp"
 #include "httpserver/http_utils.hpp"
+#include "httpserver/ip_representation.hpp"
 #include "httpserver/iovec_entry.hpp"
 #include "httpserver/file_info.hpp"
 #include "httpserver/webserver.hpp"

src/httpserver/http_utils.hpp

@@ -413,42 +413,15 @@ using arg_map = std::map<std::string, http_arg_value, http::arg_comparator>;
 using arg_view_map = std::map<std::string_view, http_arg_value, http::arg_comparator>;
 
 
-struct ip_representation {
-    http_utils::IP_version_T ip_version;
-    uint16_t pieces[16];
-    uint16_t mask;
-
-    explicit ip_representation(http_utils::IP_version_T ip_version) :
-        ip_version(ip_version) {
-            mask = constants::DEFAULT_MASK_VALUE;
-            std::fill(pieces, pieces + 16, 0);
-    }
-
-    explicit ip_representation(const std::string& ip);
-    explicit ip_representation(const struct sockaddr* ip);
-
-    bool operator<(const ip_representation& b) const;
-
-    int weight() const {
-        // variable-precision SWAR algorithm
-        uint16_t x = mask;
-        x = x - ((x >> 1) & 0x55555555);
-        x = (x & 0x33333333) + ((x >> 2) & 0x33333333);
-        return (((x + (x >> 4)) & 0x0F0F0F0F) * 0x01010101) >> 24;
-    }
+}  // namespace http
+}  // namespace httpserver
 
- private:
-    // Helpers carved out of the string-ctor to keep each function under
-    // the project cyclomatic-complexity bar. parse_ipv6 / parse_ipv4
-    // do the top-level dispatch; the rest serve parse_ipv6.
-    void parse_ipv4(const std::string& ip);
-    void parse_ipv6(const std::string& ip);
-    static unsigned int compute_ipv6_omitted_segments(std::vector<std::string>& parts);
-    void apply_ipv6_part(std::vector<std::string>& parts, unsigned int i,
-                         int& y, unsigned int omitted);
-    void parse_nested_ipv4(const std::vector<std::string>& parts,
-                           unsigned int i, int y);
-};
+// ip_representation lives in its own header; included here so existing
+// consumers of <httpserver/http_utils.hpp> still see the type.
+#include "httpserver/ip_representation.hpp"
+
+namespace httpserver {
+namespace http {
 
 /**
  * Method used to get an ip in form of string from a sockaddr structure.

src/httpserver/ip_representation.hpp

@@ -0,0 +1,86 @@
+/*
+     This file is part of libhttpserver
+     Copyright (C) 2011-2019 Sebastiano Merlino
+
+     This library is free software; you can redistribute it and/or
+     modify it under the terms of the GNU Lesser General Public
+     License as published by the Free Software Foundation; either
+     version 2.1 of the License, or (at your option) any later version.
+
+     This library is distributed in the hope that it will be useful,
+     but WITHOUT ANY WARRANTY; without even the implied warranty of
+     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+     Lesser General Public License for more details.
+
+     You should have received a copy of the GNU Lesser General Public
+     License along with this library; if not, write to the Free Software
+     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301
+     USA
+*/
+
+#if !defined (_HTTPSERVER_HPP_INSIDE_) && !defined (HTTPSERVER_COMPILATION)
+#error "Only <httpserver.hpp> or <httpserverpp> can be included directly."
+#endif
+
+#ifndef SRC_HTTPSERVER_IP_REPRESENTATION_HPP_
+#define SRC_HTTPSERVER_IP_REPRESENTATION_HPP_
+
+#include <stdint.h>
+
+#include <algorithm>
+#include <string>
+#include <vector>
+
+#include "httpserver/constants.hpp"
+#include "httpserver/http_utils.hpp"
+
+// Forward-declared at file scope; the parsing path in src/http_utils.cpp
+// pulls in <sys/socket.h> directly so the sockaddr ctor can read the
+// address family. Same rationale as http_utils.hpp: backend headers must
+// not leak through the umbrella to downstream consumers.
+struct sockaddr;
+
+namespace httpserver {
+namespace http {
+
+struct ip_representation {
+    http_utils::IP_version_T ip_version;
+    uint16_t pieces[16];
+    uint16_t mask;
+
+    explicit ip_representation(http_utils::IP_version_T ip_version) :
+        ip_version(ip_version) {
+            mask = constants::DEFAULT_MASK_VALUE;
+            std::fill(pieces, pieces + 16, 0);
+    }
+
+    explicit ip_representation(const std::string& ip);
+    explicit ip_representation(const struct sockaddr* ip);
+
+    bool operator<(const ip_representation& b) const;
+
+    int weight() const {
+        // variable-precision SWAR algorithm
+        uint16_t x = mask;
+        x = x - ((x >> 1) & 0x55555555);
+        x = (x & 0x33333333) + ((x >> 2) & 0x33333333);
+        return (((x + (x >> 4)) & 0x0F0F0F0F) * 0x01010101) >> 24;
+    }
+
+ private:
+    // Helpers carved out of the string-ctor to keep each function under
+    // the project cyclomatic-complexity bar. parse_ipv6 / parse_ipv4
+    // do the top-level dispatch; the rest serve parse_ipv6.
+    void parse_ipv4(const std::string& ip);
+    void parse_ipv6(const std::string& ip);
+    static unsigned int compute_ipv6_omitted_segments(std::vector<std::string>& parts);
+    void apply_ipv6_part(std::vector<std::string>& parts, unsigned int i,
+                         int& y, unsigned int omitted);
+    void parse_nested_ipv4(const std::vector<std::string>& parts,
+                           unsigned int i, int y);
+};
+
+}  // namespace http
+}  // namespace httpserver
+
+#endif  // SRC_HTTPSERVER_IP_REPRESENTATION_HPP_