Merge TASK-029: naming consistency — stop_and_wait, block_ip/unblock_ip

Author: etr

README.md

@@ -544,7 +544,7 @@ Once a webserver is created, you can manage its execution through the following
 * _**void** webserver::start(**bool** blocking):_ Allows to start a server. If the `blocking` flag is passed as `true`, it will block the execution of the current thread until a call to stop on the same webserver object is performed.
 * _**void** webserver::stop():_ Allows to stop a server. It immediately stops it.
 * _**bool** webserver::is_running():_ Checks if a server is running
-* _**void** webserver::sweet_kill():_ Allows to stop a server. It doesn't guarantee an immediate halt to allow for thread termination and connection closure.
+* _**void** webserver::stop_and_wait():_ Stop the webserver and wait for in-flight handlers to complete before returning. Use `stop()` when no such guarantee is required.
 * _**int** webserver::quiesce():_ Quiesce the daemon: stop accepting new connections while letting in-flight requests complete. Returns the listen socket file descriptor (the caller can close it), or `-1` on error.
 * _**bool** webserver::run():_ Run the webserver's event loop once (non-blocking). For use with external event loops when the server is started without internal threading. Returns `true` on success.
 * _**bool** webserver::run_wait(**int32_t** millisec):_ Run the webserver's event loop, blocking until there is activity or the timeout expires. Pass `-1` for indefinite wait. Returns `true` on success.
@@ -946,10 +946,8 @@ libhttpserver provides natively a system to blacklist and whitelist IP addresses
 The system supports both IPV4 and IPV6 and manages them transparently. The only requirement is for ipv6 to be enabled on your server - you'll have to enable this by using the `use_ipv6` method on `create_webserver`.
 
 You can explicitly ban or allow an IP address using the following methods on the `webserver` class:
-* _**void** ban_ip(**const std::string&** ip):_ Adds one IP (or a range of IPs) to the list of the banned ones. Takes in input a `string` that contains the IP (or range of IPs) to ban. To use when the `default_policy` is `ACCEPT`.
-* _**void** allow_ip(**const std::string&** ip):_ Adds one IP (or a range of IPs) to the list of the allowed ones. Takes in input a `string` that contains the IP (or range of IPs) to allow.  To use when the `default_policy` is `REJECT`.
-* _**void** unban_ip(**const std::string&** ip):_ Removes one IP (or a range of IPs) from the list of the banned ones. Takes in input a `string` that contains the IP (or range of IPs) to remove from the list.  To use when the `default_policy` is `ACCEPT`.
-* _**void** disallow_ip(**const std::string&** ip):_ Removes one IP (or a range of IPs) from the list of the allowed ones. Takes in input a `string` that contains the IP (or range of IPs) to remove from the list.  To use when the `default_policy` is `REJECT`.
+* _**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.
 
 ### IP String Format
 The IP string format can represent both IPV4 and IPV6. Addresses will be normalized by the webserver to operate in the same sapce. Any valid IPV4 or IPV6 textual representation works.
@@ -977,10 +975,11 @@ Examples of valid IPs include:
     };
 
     int main(int argc, char** argv) {
-        webserver ws = create_webserver(8080)
-            .default_policy(http::http_utils::REJECT);
+        webserver ws = create_webserver(8080);
 
-        ws.allow_ip("127.0.0.1");
+        // Refuse connections from this address; everything else is accepted
+        // by default. Use a range like "127.0.0.*" to block a wildcard.
+        ws.block_ip("10.0.0.1");
 
         hello_world_resource hwr;
         ws.register_resource("/hello", &hwr);
@@ -1728,7 +1727,7 @@ You can also check this example on [github](https://github.com/etr/libhttpserver
         std::cout << "HTTP 404 reason: "
                   << http::http_utils::reason_phrase(404) << std::endl;
 
-        ws.sweet_kill();
+        ws.stop_and_wait();
         return 0;
     }
 ```

examples/daemon_info.cpp

@@ -53,7 +53,7 @@ int main() {
               << ". Press Ctrl+C to stop." << std::endl;
 
     // Block until interrupted
-    ws.sweet_kill();
+    ws.stop_and_wait();
 
     return 0;
 }

examples/minimal_ip_ban.cpp

@@ -29,10 +29,13 @@ class hello_world_resource : public httpserver::http_resource {
      }
 };
 
+// TASK-029: The v2.0 public IP-control API is the pair block_ip / unblock_ip,
+// usable under the default ACCEPT policy. The historical allow_ip /
+// disallow_ip pair (under REJECT) was dropped from the public surface.
 int main() {
-    httpserver::webserver ws = httpserver::create_webserver(8080).default_policy(httpserver::http::http_utils::REJECT);
+    httpserver::webserver ws = httpserver::create_webserver(8080);
 
-    ws.allow_ip("127.0.0.1");
+    ws.block_ip("10.0.0.1");
 
     auto hwr = std::make_shared<hello_world_resource>();
     ws.register_path("/hello", hwr);

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

@@ -8,11 +8,11 @@
 Collapse synonyms to a single canonical verb per concept, per PRD §3.7.
 
 **Action Items:**
-- [ ] Rename `webserver::sweet_kill` → `webserver::stop_and_wait`. Remove the old name.
-- [ ] Add `webserver::block_ip(std::string_view ip)` and `webserver::unblock_ip(std::string_view ip)`.
-- [ ] Remove `ban_ip`, `unban_ip`, `allow_ip`, `disallow_ip` from the public API. The internal ban list remains; it's just exposed under one name pair.
-- [ ] Verify no `// NOLINT(runtime/explicit)` survives on related constructors (covered in TASK-030).
-- [ ] Verify `shoutCAST` is preserved as-is (only camelCase exception, per PRD §3.7).
+- [x] Rename `webserver::sweet_kill` → `webserver::stop_and_wait`. Remove the old name.
+- [x] Add `webserver::block_ip(std::string_view ip)` and `webserver::unblock_ip(std::string_view ip)`.
+- [x] Remove `ban_ip`, `unban_ip`, `allow_ip`, `disallow_ip` from the public API. The internal ban list remains; it's just exposed under one name pair.
+- [x] Verify no `// NOLINT(runtime/explicit)` survives on related constructors (covered in TASK-030).
+- [x] Verify `shoutCAST` is preserved as-is (only camelCase exception, per PRD §3.7).
 
 **Dependencies:**
 - Blocked by: TASK-014
@@ -29,4 +29,4 @@ Collapse synonyms to a single canonical verb per concept, per PRD §3.7.
 **Related Requirements:** PRD-NAM-REQ-001, PRD-NAM-REQ-002, PRD-NAM-REQ-005
 **Related Decisions:** §3.7, OQ-004, OQ-005
 
-**Status:** Not Started
+**Status:** Done

specs/tasks/_index.md

@@ -111,7 +111,7 @@ Nominally: **13 sequential tasks**, each S–XL. Most other tasks parallelize of
 | TASK-026 | Generic `webserver::route(method, path, handler)` | M4 | Done | TASK-005, TASK-025 |
 | TASK-027 | 3-tier route table with LRU cache | M5 | Done | TASK-005, TASK-014, TASK-021, TASK-024, TASK-025, TASK-026 |
 | TASK-028 | Routing-semantics regression gate | M5 | Done | TASK-027 |
-| TASK-029 | Naming consistency — `stop_and_wait`, `block_ip`/`unblock_ip` | M5 | Not Started | TASK-014 |
+| TASK-029 | Naming consistency — `stop_and_wait`, `block_ip`/`unblock_ip` | M5 | Done | TASK-014 |
 | TASK-030 | `_handler` suffix renames + `explicit` constructor | M5 | Not Started | TASK-014 |
 | TASK-031 | Handler error-propagation contract (DR-009) | M5 | Not Started | TASK-027, TASK-030 |
 | TASK-032 | Thread-safety contract stress test (DR-008) | M5 | Not Started | TASK-027, TASK-031 |