Merge feature/ip-access-control-naming: symmetric allow/deny IP API

Renames block_ip/unblock_ip -> deny_ip/remove_denied_ip, adds the
allow_ip/remove_allowed_ip pair (making default_policy(REJECT) usable),
ban_system -> ip_access_control. make check green (doxygen gate fixed).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NpysYDDJac63yz2mZKKiDf

Author: etr

README.md

@@ -42,7 +42,7 @@ thread-safe by contract.
 - External event-loop integration (`run`, `run_wait`, `get_fdset`, `add_connection`)
 - Daemon introspection (bound port, active connections, listen FD)
 - Turbo mode, TCP_FASTOPEN, suppressed `Date` headers, configurable backlog
-- IP blocking with wildcard ranges (`block_ip` / `unblock_ip`), IPv4 & IPv6
+- IP access control with wildcard ranges — deny list (`deny_ip`) and allow list (`allow_ip`), IPv4 & IPv6
 - Architecture contracts you can rely on: threading (DR-008 / §5.1) and error propagation (DR-009 / §5.2)
 
 This README is a guided reference: it walks the v2.0 API surface section by
@@ -568,8 +568,10 @@ The rest of this section is a reference of every group of options.
 * **`.pedantic(bool = true)`** — strict HTTP-RFC parsing.
 * **`.regex_checking(bool = true)`** — validate path regexes at
   registration. Default `true`.
-* **`.ban_system(bool = true)`** — enable the IP block-list machinery
-  used by `block_ip` / `unblock_ip`. Default `true`.
+* **`.ip_access_control(bool = true)`** — enable the IP access-control
+  machinery used by `deny_ip` / `allow_ip` (and their `remove_*`
+  counterparts). Default `true`. When `false`, every connection is
+  admitted and both lists are ignored.
 * **`.post_process(bool = true)`** — auto-parse `application/x-www-form-urlencoded`
   and `multipart/form-data` bodies into the request's argument map.
   Default `true`.
@@ -691,11 +693,13 @@ httpserver::webserver ws{cfg};
 
 These dovetail with the runtime methods covered under [Daemon
 introspection and external event loops](#daemon-introspection-and-external-event-loops).
-The `default_policy` controls the IP block list semantics:
+The `default_policy` selects which list is the exception list — i.e. what
+happens to an address on neither list:
 
 * **`.default_policy(http::http_utils::policy_T p)`** — `ACCEPT` (default)
-  treats `block_ip` as a deny list; `REJECT` flips the semantics so
-  `block_ip` becomes an allow list.
+  admits every address except those on the deny list (`deny_ip`); `REJECT`
+  refuses every address except those on the allow list (`allow_ip`). Under
+  either policy an allow entry overrides a matching deny entry.
 
 ### Runtime operations on `webserver`
 
@@ -1089,16 +1093,22 @@ The only requirement for IPv6 is that it is enabled on the underlying
 server — set `use_ipv6(true)` on `create_webserver` (or `use_dual_stack(true)`
 for both stacks on the same socket).
 
-You can explicitly block or unblock IP addresses (or wildcard ranges)
-at runtime using these methods on `webserver`:
-
-* **`void block_ip(std::string_view ip)`** — add one IP (or a range,
-  e.g. `"127.0.0.*"`) to the block list. Connections from a matching
-  address are refused at the policy callback. Intended for use under the
-  default `ACCEPT` policy.
-* **`void unblock_ip(std::string_view ip)`** — remove one IP (or a
-  range) from the block list. Idempotent: removing an entry that is not
-  currently blocked is a no-op.
+You can populate the deny list and the allow list (with individual IPs or
+wildcard ranges) at runtime using these methods on `webserver`:
+
+* **`void deny_ip(std::string_view ip)`** — add one IP (or a range,
+  e.g. `"127.0.0.*"`) to the deny list. Connections from a matching
+  address are refused at the policy callback. This is the exception list
+  under the default `ACCEPT` policy.
+* **`void remove_denied_ip(std::string_view ip)`** — remove one IP (or a
+  range) from the deny list. Idempotent: removing an entry that is not
+  currently denied is a no-op.
+* **`void allow_ip(std::string_view ip)`** — add one IP (or a range) to
+  the allow list. This is the exception list under the `REJECT` policy
+  (permit only these). Under `ACCEPT`, an allow entry overrides a
+  matching `deny_ip` entry.
+* **`void remove_allowed_ip(std::string_view ip)`** — remove one IP (or a
+  range) from the allow list. Idempotent.
 
 ### IP string format
 
@@ -1120,19 +1130,19 @@ Examples of valid IPs include:
 
 ### Allow-list mode
 
-By default, `block_ip` defines a deny list under the `ACCEPT` policy.
-To flip the semantics so `block_ip` defines an *allow* list under a
-default-deny policy, set the policy on the builder:
+By default (`ACCEPT` policy) the deny list is the exception list: use
+`deny_ip` to refuse specific addresses and admit everyone else. To invert
+this into an allow list — refuse everyone except specific addresses — set
+the default policy to `REJECT` and populate the allow list with `allow_ip`:
 
 ```cpp
 webserver ws{create_webserver(8080)
     .default_policy(http::http_utils::REJECT)};
-ws.block_ip("192.168.0.*");  // permits 192.168.0.0/24, blocks everything else
+ws.allow_ip("192.168.0.*");  // permits 192.168.0.0/24, refuses everything else
 ```
 
-See [`examples/minimal_ip_ban.cpp`](examples/minimal_ip_ban.cpp) for a
-worked example of `block_ip` and `unblock_ip` under the default
-`ACCEPT` policy.
+See [`examples/minimal_ip_access_control.cpp`](examples/minimal_ip_access_control.cpp)
+for a worked example of both modes.
 
 [Back to TOC](#table-of-contents)
 
@@ -1605,8 +1615,8 @@ worked example.
 
 ### Examples
 
-* [`examples/banned_ip_log.cpp`](examples/banned_ip_log.cpp) — log every
-  banned-IP rejection via a single `accept_decision` hook.
+* [`examples/denied_ip_log.cpp`](examples/denied_ip_log.cpp) — log every
+  denied-IP rejection via a single `accept_decision` hook.
 * [`examples/early_413.cpp`](examples/early_413.cpp) — return 413 from
   a `request_received` hook before the body is consumed.
 * [`examples/clf_access_log.cpp`](examples/clf_access_log.cpp) — write
@@ -1780,10 +1790,11 @@ try {
 }
 ```
 
-Block lists, IP-allow handling, and similar features that do not depend
-on external libraries are always available: `webserver::block_ip(addr)`
-and `webserver::unblock_ip(addr)` install and clear per-server blocks at
-runtime regardless of build flags.
+Deny lists, IP-allow handling, and similar features that do not depend
+on external libraries are always available: `webserver::deny_ip(addr)` /
+`webserver::remove_denied_ip(addr)` and `webserver::allow_ip(addr)` /
+`webserver::remove_allowed_ip(addr)` install and clear per-server access
+rules at runtime regardless of build flags.
 
 [Back to TOC](#table-of-contents)
 
@@ -1864,8 +1875,8 @@ to the canonical example for each topic covered in this manual.
 
 ### Lifecycle hooks
 
-* [`examples/banned_ip_log.cpp`](examples/banned_ip_log.cpp) — log every
-  banned-IP rejection from a single `accept_decision` hook (issue #332).
+* [`examples/denied_ip_log.cpp`](examples/denied_ip_log.cpp) — log every
+  denied-IP rejection from a single `accept_decision` hook (issue #332).
 * [`examples/early_413.cpp`](examples/early_413.cpp) — short-circuit
   oversized uploads with 413 before any body bytes are consumed via a
   `request_received` hook (issue #273).
@@ -1885,8 +1896,8 @@ to the canonical example for each topic covered in this manual.
   drive `EXTERNAL_SELECT` from the application's loop via `run_wait`.
 * [`examples/custom_access_log.cpp`](examples/custom_access_log.cpp) —
   server-wide access-log callback.
-* [`examples/minimal_ip_ban.cpp`](examples/minimal_ip_ban.cpp) —
-  `block_ip` / `unblock_ip` under the default `ACCEPT` policy.
+* [`examples/minimal_ip_access_control.cpp`](examples/minimal_ip_access_control.cpp) —
+  `deny_ip` / `allow_ip` under the `ACCEPT` and `REJECT` policies.
 * [`examples/turbo_mode.cpp`](examples/turbo_mode.cpp) — turbo,
   suppressed Date header, fastopen queue, listen backlog.
 * [`examples/service.cpp`](examples/service.cpp) — kitchen-sink

RELEASE_NOTES.md

@@ -34,8 +34,13 @@ v1.x is end-of-life on the day v2.0 ships.
   smart-pointer overload.
 - **`sweet_kill`.** Removed. Use `stop_and_wait()` (or `stop()` for the
   signal-only form).
-- **IP allow/deny verbs.** `ban_ip`, `unban_ip`, `allow_ip`,
-  `disallow_ip` are removed. Use `block_ip` / `unblock_ip`.
+- **IP allow/deny verbs.** The v1 `ban_ip` / `unban_ip` / `allow_ip` /
+  `disallow_ip` quartet is renamed for a symmetric, unambiguous surface:
+  `deny_ip` / `remove_denied_ip` operate the deny list, and `allow_ip` /
+  `remove_allowed_ip` operate the allow list. `default_policy(ACCEPT)`
+  makes the deny list the exception list (block only these); `REJECT`
+  makes the allow list the exception list (permit only these). An allow
+  entry overrides a matching deny entry. See "What's renamed".
 - **Paired `no_*` boolean setters.** `no_basic_auth`, `no_digest_auth`,
   `no_ssl`, `no_debug`, `no_pedantic`, `no_deferred`, `no_regex_checking`,
   `no_ban_system`, `no_post_process`, `no_single_resource`, `no_ipv6`,
@@ -92,7 +97,7 @@ v1.x is end-of-life on the day v2.0 ships.
   configured validator callback is dead code. The
   v2 replacement is `webserver::add_hook(hook_phase::request_received,
   ...)` returning `hook_action::respond_with(http_response)` to reject
-  a request, or `webserver::block_ip`/`unblock_ip` for a connection-scoped
+  a request, or `webserver::deny_ip`/`remove_denied_ip` for a connection-scoped
   veto; `hook_phase::accept_decision` is observation-only (Short-circuit:
   no, per `specs/architecture/04-components/hooks.md`) and cannot reject
   a connection. The legacy
@@ -166,7 +171,7 @@ v1.x is end-of-life on the day v2.0 ships.
   `hook_handle::detach()` keeps the registration alive for the
   webserver's lifetime. See `specs/architecture/04-components/hooks.md`
   and [`README.md#lifecycle-hooks`](README.md#lifecycle-hooks). Closes:
-  #332 (banned-IP log, `examples/banned_ip_log.cpp`), #281 + #69
+  #332 (denied-IP log, `examples/denied_ip_log.cpp`), #281 + #69
   (CLF / time-taken access log, `examples/clf_access_log.cpp`), #273
   (early 413, `examples/early_413.cpp`); partially closes #272
   (per-chunk observation; body steal deferred to v2.1).
@@ -179,10 +184,10 @@ and see the v2 replacement.
 | v1 | v2 |
 |---|---|
 | `sweet_kill` | `stop_and_wait` |
-| `ban_ip` | `block_ip` |
-| `unban_ip` | `unblock_ip` |
-| `allow_ip` | `unblock_ip` (or `block_ip` to deny) |
-| `disallow_ip` | `block_ip` (or `unblock_ip` to allow) |
+| `ban_ip` | `deny_ip` |
+| `unban_ip` | `remove_denied_ip` |
+| `allow_ip` | `allow_ip` (unchanged; allow list) |
+| `disallow_ip` | `remove_allowed_ip` |
 | `not_found_resource` (setter) | `not_found_handler` |
 | `method_not_allowed_resource` (setter) | `method_not_allowed_handler` |
 | `internal_error_resource` (setter) | `internal_error_handler` |

doxyconfig.in

@@ -179,7 +179,7 @@ TAB_SIZE               = 8
 # will result in a user-defined paragraph with heading "Side Effects:".
 # You can put \n's in the value part of an alias to insert newlines.
 
-ALIASES                =
+ALIASES                = "security=\par Security:^^"
 
 # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C
 # sources only. Doxygen will then generate output that is more tailored for C.

examples/Makefile.am

@@ -19,7 +19,7 @@
 LDADD = $(top_builddir)/src/libhttpserver.la
 AM_CPPFLAGS = -I$(top_srcdir)/src -I$(top_srcdir)/src/httpserver/
 METASOURCES = AUTO
-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
+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_access_control denied_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
@@ -42,8 +42,8 @@ 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
+minimal_ip_access_control_SOURCES = minimal_ip_access_control.cpp
+denied_ip_log_SOURCES = denied_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

examples/README.md

@@ -78,8 +78,8 @@ every interesting point in the request lifecycle. The four examples
 below demonstrate the user-visible resolution of issues #332, #273,
 #281, #69, and the per-route hook contract introduced in TASK-051.
 
-* `banned_ip_log.cpp` — a single `accept_decision` hook logs every
-  banned-IP rejection to stderr. Resolves issue #332.
+* `denied_ip_log.cpp` — a single `accept_decision` hook logs every
+  denied-IP rejection to stderr. Resolves issue #332.
 * `early_413.cpp` — a single `request_received` hook returns
   `respond_with(http_response::empty().with_status(413))` when
   `Content-Length` exceeds the configured cap. The request body never
@@ -99,8 +99,8 @@ Operations
 * `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.
+* `minimal_ip_access_control.cpp` — `deny_ip` / `allow_ip` under the
+  `ACCEPT` and `REJECT` policies.
 * `turbo_mode.cpp` — turbo, suppressed Date header, fastopen queue,
   listen backlog.
 * `service.cpp` — the kitchen-sink reference example: CLI args,

examples/banned_ip_log.cpp examples/denied_ip_log.cppexamples/banned_ip_log.cpp renamed to examples/denied_ip_log.cpp

@@ -18,18 +18,18 @@
      USA
 */
 
-// Demonstrates the solution to issue #332: log every banned-IP rejection.
+// Demonstrates the solution to issue #332: log every denied-IP rejection.
 //
-// Configure the daemon with an ACCEPT default policy, block the IPs you
-// want denied via ws.block_ip(), and register a connection-level
+// Configure the daemon with an ACCEPT default policy, deny the IPs you
+// want refused via ws.deny_ip(), and register a connection-level
 // `accept_decision` hook that logs every rejection to stderr.
 //
 // The hook is observation-only: throwing from it does not flip the
 // decision (the daemon still rejects the connection per the policy
 // callback's return), so it is safe to do I/O here.
 //
-// Run, then attempt to connect from one of the blocked IPs to see
-// stderr show a "[BANNED] ..." line per attempt.
+// Run, then attempt to connect from one of the denied IPs to see
+// stderr show a "[DENIED] ..." line per attempt.
 
 #include <functional>
 #include <iostream>
@@ -51,15 +51,15 @@ int main() {
     hs::webserver ws{hs::create_webserver(8080)
                          .default_policy(hs::http::http_utils::ACCEPT)};
 
-    // Block whatever client IP you want denied. The shipping example
+    // Deny whatever client IP you want refused. The shipping example
     // uses an RFC-1918 placeholder; swap with your client's address.
-    ws.block_ip("10.0.0.1");
+    ws.deny_ip("10.0.0.1");
 
     auto h = ws.add_hook(hs::hook_phase::accept_decision,
         std::function<void(const hs::accept_ctx&)>(
             [](const hs::accept_ctx& ctx) {
                 if (!ctx.accepted) {
-                    std::cerr << "[BANNED] peer=" << ctx.peer.to_string()
+                    std::cerr << "[DENIED] peer=" << ctx.peer.to_string()
                               << " reason="
                               << (ctx.reason.has_value()
                                       ? std::string(*ctx.reason)

examples/minimal_ip_ban.cpp examples/minimal_ip_access_control.cppexamples/minimal_ip_ban.cpp renamed to examples/minimal_ip_access_control.cpp

@@ -18,18 +18,31 @@
      USA
 */
 
-// minimal_ip_ban.cpp - demonstrate the v2.0 IP block API.
+// minimal_ip_access_control.cpp - demonstrate the IP access-control API.
 //
-// TASK-029: the v2.0 public IP-control surface is the pair block_ip /
-// unblock_ip, usable under the default ACCEPT policy. The historical
-// allow_ip / disallow_ip pair (under REJECT) was dropped.
+// Two lists, selected by create_webserver::default_policy():
+//   - deny_ip / remove_denied_ip : the exception list under the default
+//     ACCEPT policy (permit everyone except these).
+//   - allow_ip / remove_allowed_ip : the exception list under the REJECT
+//     policy (permit only these). Under ACCEPT, an allow entry also
+//     overrides a matching deny entry (allow wins).
 
 #include <httpserver.hpp>
 
 int main() {
+    // Default ACCEPT policy: block-list mode. Everyone is admitted except
+    // addresses on the deny list.
     httpserver::webserver ws{httpserver::create_webserver(8080)};
-
-    ws.block_ip("10.0.0.1");
+    ws.deny_ip("10.0.0.1");
+
+    // Allow-list mode: flip the default to REJECT, then permit only the
+    // addresses you allow_ip. Everyone else is refused at the policy
+    // callback.
+    //
+    //   httpserver::webserver ws{
+    //       httpserver::create_webserver(8080)
+    //           .default_policy(httpserver::http::http_utils::REJECT)};
+    //   ws.allow_ip("127.0.0.1");   // only localhost may connect
 
     ws.on_get("/hello", [](const httpserver::http_request&) {
         return httpserver::http_response::string("Hello, World!");

scripts/check-examples.sh

@@ -184,13 +184,13 @@ if [ "$unlisted" -gt 0 ]; then
 fi
 
 # ---- TASK-052: hook-example documentation coverage --------------------------
-# The four lifecycle-hook examples (banned_ip_log, early_413, clf_access_log,
+# The four lifecycle-hook examples (denied_ip_log, early_413, clf_access_log,
 # per_route_auth) must be listed in both examples/README.md and the top-level
 # README.md so the user-visible resolution of issues #332, #281, #69, #273 is
 # discoverable. Per TASK-052 / Phase 3.
 EXAMPLES_README="$REPO_ROOT/examples/README.md"
 TOP_README="$REPO_ROOT/README.md"
-HOOK_EXAMPLES="banned_ip_log early_413 clf_access_log per_route_auth"
+HOOK_EXAMPLES="denied_ip_log early_413 clf_access_log per_route_auth"
 
 for f in "$EXAMPLES_README" "$TOP_README"; do
     [ -f "$f" ] || fail "$(basename "$f") does not exist"