net: improve performance of net.BlockList

* fix duplicate address insertion in SocketAddressBlockList
* fix BlockList rule listing order to match apply
* add minor bound check in BlockList
* improve performance of BlockList apply
* eliminating shared_ptr
* check fast api path
* add clear method to BlockList
* general storage improvements to BlockList
* use shared locks for BlockList reads
* add bulk address adding to BlockList
* add BlockList benchmark
* add remove range/subnet to BlockList
* add cidr notation parsing to BlockList
* add additional apis to BlockList
* add private subnet presets to BlockList
Signed-off-by: James M Snell <jasnell@gmail.com>
Assisted-by: OpenCode/Opus
PR-URL: #64974
Reviewed-By: Tim Perry <pimterry@gmail.com>
Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Ethan Arrowood <ethan@arrowood.dev>

Author: jasnell

benchmark/net/net-blocklist.js

@@ -0,0 +1,146 @@
+'use strict';
+
+constcommon=require('../common.js');
+const{ BlockList, SocketAddress }=require('net');
+
+consthasAddAddresses=typeofBlockList.prototype.addAddresses==='function';
+
+constoperations=['check','checkWithSocketAddress','addAddress'];
+if(hasAddAddresses){
+operations.push('addAddresses');
+}
+
+constbench=common.createBenchmark(main,{
+n: [1e6],
+ruleCount: [10,100,1000,10000],
+ruleType: ['address','subnet','mixed'],
+checkResult: ['hit','miss'],
+operation: operations,
+},{
+combinationFilter({ operation, ruleCount, ruleType }){
+// addAddress and addAddresses only need address rules, not subnets.
+if((operation==='addAddress'||operation==='addAddresses')&&
+ruleType!=='address'){
+returnfalse;
+}
+returntrue;
+},
+});
+
+functiongenerateIPv4(index){
+return`${(index>>>24)&0xff}.${(index>>>16)&0xff}.`+
+`${(index>>>8)&0xff}.${index&0xff}`;
+}
+
+functionbuildBlockList(ruleCount,ruleType){
+constblockList=newBlockList();
+
+if(ruleType==='address'||ruleType==='mixed'){
+constaddressCount=ruleType==='mixed' ?
+Math.floor(ruleCount/2) : ruleCount;
+constaddresses=[];
+for(leti=0;i<addressCount;i++){
+// Start from 10.0.0.1 to avoid 0.0.0.0
+addresses.push(generateIPv4(0x0a000001+i));
+}
+if(hasAddAddresses){
+blockList.addAddresses(addresses);
+}else{
+for(constaddrofaddresses){
+blockList.addAddress(addr);
+}
+}
+}
+
+if(ruleType==='subnet'||ruleType==='mixed'){
+constsubnetCount=ruleType==='mixed' ?
+Math.floor(ruleCount/2) : ruleCount;
+for(leti=0;i<subnetCount;i++){
+// Use distinct /24 subnets: 172.i.j.0/24
+constsecond=(i>>>8)&0xff;
+constthird=i&0xff;
+blockList.addSubnet(`172.${second}.${third}.0`,24);
+}
+}
+
+returnblockList;
+}
+
+functionmain({ n, ruleCount, ruleType, checkResult, operation }){
+if(operation==='check'){
+benchCheck(n,ruleCount,ruleType,checkResult);
+}elseif(operation==='checkWithSocketAddress'){
+benchCheckWithSocketAddress(n,ruleCount,ruleType,checkResult);
+}elseif(operation==='addAddress'){
+benchAddAddress(n,ruleCount);
+}elseif(operation==='addAddresses'){
+benchAddAddresses(n,ruleCount);
+}
+}
+
+// Benchmark check() with string addresses (the common JS API path).
+functionbenchCheck(n,ruleCount,ruleType,checkResult){
+constblockList=buildBlockList(ruleCount,ruleType);
+
+// For 'hit', use an address that's in the list.
+// For 'miss', use an address that's not in the list.
+constaddress=checkResult==='hit' ? '10.0.0.1' : '192.168.255.255';
+
+bench.start();
+for(leti=0;i<n;i++){
+blockList.check(address);
+}
+bench.end(n);
+}
+
+// Benchmark check() with pre-created SocketAddress objects
+// (avoids measuring SocketAddress construction overhead).
+functionbenchCheckWithSocketAddress(n,ruleCount,ruleType,checkResult){
+constblockList=buildBlockList(ruleCount,ruleType);
+
+constaddress=checkResult==='hit' ? '10.0.0.1' : '192.168.255.255';
+constsa=newSocketAddress({ address });
+
+bench.start();
+for(leti=0;i<n;i++){
+blockList.check(sa);
+}
+bench.end(n);
+}
+
+// Benchmark single addAddress() calls (one lock acquire per call).
+functionbenchAddAddress(n,ruleCount){
+// Scale n down for large rule counts to keep runtime reasonable.
+constiterations=Math.min(n,ruleCount*100);
+
+constaddresses=[];
+for(leti=0;i<ruleCount;i++){
+addresses.push(generateIPv4(0x0a000001+i));
+}
+
+bench.start();
+for(leti=0;i<iterations;i++){
+constblockList=newBlockList();
+for(letj=0;j<addresses.length;j++){
+blockList.addAddress(addresses[j]);
+}
+}
+bench.end(iterations);
+}
+
+// Benchmark batch addAddresses() (one lock acquire per batch).
+functionbenchAddAddresses(n,ruleCount){
+constiterations=Math.min(n,ruleCount*100);
+
+constaddresses=[];
+for(leti=0;i<ruleCount;i++){
+addresses.push(generateIPv4(0x0a000001+i));
+}
+
+bench.start();
+for(leti=0;i<iterations;i++){
+constblockList=newBlockList();
+blockList.addAddresses(addresses);
+}
+bench.end(iterations);
+}

doc/api/net.md

@@ -96,6 +96,47 @@ added:
 
 Adds a rule to block the given IP address.
 
+### `blockList.addAddresses(addresses[, type])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`addresses` {string\[]|net.SocketAddress\[]} An array of IPv4 or IPv6
+ addresses.
+*`type` {string} Either `'ipv4'` or `'ipv6'`. **Default:**`'ipv4'`.
+
+Adds multiple address rules to the block list in a single operation.
+This is more efficient than calling `blockList.addAddress()` repeatedly
+when adding a large number of individual addresses, as the addresses
+are inserted under a single internal lock acquisition.
+
+### `blockList.addCIDR(cidr)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`cidr` {string} An IPv4 or IPv6 subnet in CIDR notation (e.g.
+`'10.0.0.0/8'` or `'2001:db8::/32'`).
+
+Adds a subnet rule using CIDR notation. The address family is automatically
+detected from the address (IPv6 if the address contains `':'`, IPv4
+otherwise). This is equivalent to calling `blockList.addSubnet()` with
+the parsed network address, prefix length, and family.
+
+### `blockList.addCIDRs(cidrs)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`cidrs` {string\[]} An array of IPv4 or IPv6 subnets in CIDR notation.
+
+Adds multiple subnet rules using CIDR notation in a single call. The address
+family for each entry is automatically detected. This is equivalent to
+calling `blockList.addCIDR()` for each element of the array.
+
 ### `blockList.addRange(start, end[, type])`
 
 <!-- YAML
@@ -158,28 +199,13 @@ console.log(blockList.check('::ffff:7b7b:7b7b', 'ipv6')); // Prints: true
 console.log(blockList.check('::ffff:123.123.123.123', 'ipv6')); // Prints: true
 ```
 
-### `blockList.rules`
+### `blockList.clear()`
 
-<!-- YAML
-added:
- - v15.0.0
- - v14.18.0
+<!--
+added: REPLACEME
 -->
 
-* Type: {string\[]}
-
-The list of rules added to the blocklist.
-
-### `BlockList.isBlockList(value)`
-
-<!-- YAML
-added:
- - v23.4.0
- - v22.13.0
--->
-
-*`value` {any} Any JS value
-* Returns `true` if the `value` is a `net.BlockList`.
+Clears all rules from the `BlockList`.
 
 ### `blockList.fromJSON(value)`
 
@@ -205,6 +231,130 @@ blockList.fromJSON(JSON.stringify(data));
 
 *`value` Blocklist.rules
 
+### `BlockList.isBlockList(value)`
+
+<!-- YAML
+added:
+ - v23.4.0
+ - v22.13.0
+-->
+
+*`value` {any} Any JS value
+* Returns `true` if the `value` is a `net.BlockList`.
+
+### `BlockList.PRIVATE_RANGES`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {string\[]}
+
+A frozen array of CIDR strings representing private, loopback, and link-local
+IP address ranges. This can be passed to `blockList.addCIDRs()` to quickly
+populate a blocklist with all non-routable address ranges.
+
+The included ranges are:
+
+*`10.0.0.0/8` — RFC 1918 private IPv4
+*`172.16.0.0/12` — RFC 1918 private IPv4
+*`192.168.0.0/16` — RFC 1918 private IPv4
+*`127.0.0.0/8` — IPv4 loopback
+*`::1/128` — IPv6 loopback
+*`169.254.0.0/16` — IPv4 link-local
+*`fe80::/10` — IPv6 link-local
+*`fc00::/7` — IPv6 unique local (ULA)
+
+```js
+constblockList=newnet.BlockList();
+blockList.addCIDRs(net.BlockList.PRIVATE_RANGES);
+
+console.log(blockList.check('10.0.0.1')); // Prints: true
+console.log(blockList.check('127.0.0.1')); // Prints: true
+console.log(blockList.check('8.8.8.8')); // Prints: false
+```
+
+### `blockList.removeAddress(address[, type])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`address` {string|net.SocketAddress} An IPv4 or IPv6 address.
+*`type` {string} Either `'ipv4'` or `'ipv6'`. **Default:**`'ipv4'`.
+
+Removes a rule that was previously added with `blockList.addAddress()`. The
+address must match exactly the value used when the rule was added. If the
+specified address does not exist, this is a no-op.
+
+### `blockList.removeCIDR(cidr)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`cidr` {string} An IPv4 or IPv6 subnet in CIDR notation (e.g.
+`'10.0.0.0/8'` or `'2001:db8::/32'`).
+
+Removes a subnet rule using CIDR notation. The address family is automatically
+detected from the address. This is equivalent to calling
+`blockList.removeSubnet()` with the parsed network address, prefix length,
+and family. If the specified subnet does not exist, this is a no-op.
+
+### `blockList.removeRange(start, end[, type])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`start` {string|net.SocketAddress} The starting IPv4 or IPv6 address in the
+ range.
+*`end` {string|net.SocketAddress} The ending IPv4 or IPv6 address in the range.
+*`type` {string} Either `'ipv4'` or `'ipv6'`. **Default:**`'ipv4'`.
+
+Removes a rule that was previously added with `blockList.addRange()`. The `start`
+and `end` addresses must match exactly the values used when the rule was added.
+If the specified range does not exist, this is a no-op.
+
+### `blockList.removeSubnet(net, prefix[, type])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`net` {string|net.SocketAddress} The network IPv4 or IPv6 address.
+*`prefix` {number} The number of CIDR prefix bits. For IPv4, this
+ must be a value between `0` and `32`. For IPv6, this must be between
+`0` and `128`.
+*`type` {string} Either `'ipv4'` or `'ipv6'`. **Default:**`'ipv4'`.
+
+Removes a rule that was previously added with `blockList.addSubnet()`. The
+network address and prefix must match exactly the values used when the rule was
+added. If the specified subnet does not exist, this is a no-op.
+
+### `blockList.rules`
+
+<!-- YAML
+added:
+ - v15.0.0
+ - v14.18.0
+-->
+
+* Type: {string\[]}
+
+The list of rules added to the blocklist.
+
+### `blockList.size`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {number}
+
+The number of rules in the blocklist. This is equivalent to
+`blockList.rules.length` but does not allocate the rules array.
+
 ### `blockList.toJSON()`
 
 > Stability: 1.2 - Release candidate

benchmark/net/net-blocklist.js

@@ -0,0 +1,146 @@
+'use strict';
+
+constcommon=require('../common.js');
+const{ BlockList, SocketAddress }=require('net');
+
+consthasAddAddresses=typeofBlockList.prototype.addAddresses==='function';
+
+constoperations=['check','checkWithSocketAddress','addAddress'];
+if(hasAddAddresses){
+operations.push('addAddresses');
+}
+
+constbench=common.createBenchmark(main,{
+n: [1e6],
+ruleCount: [10,100,1000,10000],
+ruleType: ['address','subnet','mixed'],
+checkResult: ['hit','miss'],
+operation: operations,
+},{
+combinationFilter({ operation, ruleCount, ruleType }){
+// addAddress and addAddresses only need address rules, not subnets.
+if((operation==='addAddress'||operation==='addAddresses')&&
+ruleType!=='address'){
+returnfalse;
+}
+returntrue;
+},
+});
+
+functiongenerateIPv4(index){
+return`${(index>>>24)&0xff}.${(index>>>16)&0xff}.`+
+`${(index>>>8)&0xff}.${index&0xff}`;
+}
+
+functionbuildBlockList(ruleCount,ruleType){
+constblockList=newBlockList();
+
+if(ruleType==='address'||ruleType==='mixed'){
+constaddressCount=ruleType==='mixed' ?
+Math.floor(ruleCount/2) : ruleCount;
+constaddresses=[];
+for(leti=0;i<addressCount;i++){
+// Start from 10.0.0.1 to avoid 0.0.0.0
+addresses.push(generateIPv4(0x0a000001+i));
+}
+if(hasAddAddresses){
+blockList.addAddresses(addresses);
+}else{
+for(constaddrofaddresses){
+blockList.addAddress(addr);
+}
+}
+}
+
+if(ruleType==='subnet'||ruleType==='mixed'){
+constsubnetCount=ruleType==='mixed' ?
+Math.floor(ruleCount/2) : ruleCount;
+for(leti=0;i<subnetCount;i++){
+// Use distinct /24 subnets: 172.i.j.0/24
+constsecond=(i>>>8)&0xff;
+constthird=i&0xff;
+blockList.addSubnet(`172.${second}.${third}.0`,24);
+}
+}
+
+returnblockList;
+}
+
+functionmain({ n, ruleCount, ruleType, checkResult, operation }){
+if(operation==='check'){
+benchCheck(n,ruleCount,ruleType,checkResult);
+}elseif(operation==='checkWithSocketAddress'){
+benchCheckWithSocketAddress(n,ruleCount,ruleType,checkResult);
+}elseif(operation==='addAddress'){
+benchAddAddress(n,ruleCount);
+}elseif(operation==='addAddresses'){
+benchAddAddresses(n,ruleCount);
+}
+}
+
+// Benchmark check() with string addresses (the common JS API path).
+functionbenchCheck(n,ruleCount,ruleType,checkResult){
+constblockList=buildBlockList(ruleCount,ruleType);
+
+// For 'hit', use an address that's in the list.
+// For 'miss', use an address that's not in the list.
+constaddress=checkResult==='hit' ? '10.0.0.1' : '192.168.255.255';
+
+bench.start();
+for(leti=0;i<n;i++){
+blockList.check(address);
+}
+bench.end(n);
+}
+
+// Benchmark check() with pre-created SocketAddress objects
+// (avoids measuring SocketAddress construction overhead).
+functionbenchCheckWithSocketAddress(n,ruleCount,ruleType,checkResult){
+constblockList=buildBlockList(ruleCount,ruleType);
+
+constaddress=checkResult==='hit' ? '10.0.0.1' : '192.168.255.255';
+constsa=newSocketAddress({ address });
+
+bench.start();
+for(leti=0;i<n;i++){
+blockList.check(sa);
+}
+bench.end(n);
+}
+
+// Benchmark single addAddress() calls (one lock acquire per call).
+functionbenchAddAddress(n,ruleCount){
+// Scale n down for large rule counts to keep runtime reasonable.
+constiterations=Math.min(n,ruleCount*100);
+
+constaddresses=[];
+for(leti=0;i<ruleCount;i++){
+addresses.push(generateIPv4(0x0a000001+i));
+}
+
+bench.start();
+for(leti=0;i<iterations;i++){
+constblockList=newBlockList();
+for(letj=0;j<addresses.length;j++){
+blockList.addAddress(addresses[j]);
+}
+}
+bench.end(iterations);
+}
+
+// Benchmark batch addAddresses() (one lock acquire per batch).
+functionbenchAddAddresses(n,ruleCount){
+constiterations=Math.min(n,ruleCount*100);
+
+constaddresses=[];
+for(leti=0;i<ruleCount;i++){
+addresses.push(generateIPv4(0x0a000001+i));
+}
+
+bench.start();
+for(leti=0;i<iterations;i++){
+constblockList=newBlockList();
+blockList.addAddresses(addresses);
+}
+bench.end(iterations);
+}

doc/api/net.md

@@ -96,6 +96,47 @@ added:
 
 Adds a rule to block the given IP address.
 
+### `blockList.addAddresses(addresses[, type])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`addresses` {string\[]|net.SocketAddress\[]} An array of IPv4 or IPv6
+ addresses.
+*`type` {string} Either `'ipv4'` or `'ipv6'`. **Default:**`'ipv4'`.
+
+Adds multiple address rules to the block list in a single operation.
+This is more efficient than calling `blockList.addAddress()` repeatedly
+when adding a large number of individual addresses, as the addresses
+are inserted under a single internal lock acquisition.
+
+### `blockList.addCIDR(cidr)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`cidr` {string} An IPv4 or IPv6 subnet in CIDR notation (e.g.
+`'10.0.0.0/8'` or `'2001:db8::/32'`).
+
+Adds a subnet rule using CIDR notation. The address family is automatically
+detected from the address (IPv6 if the address contains `':'`, IPv4
+otherwise). This is equivalent to calling `blockList.addSubnet()` with
+the parsed network address, prefix length, and family.
+
+### `blockList.addCIDRs(cidrs)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`cidrs` {string\[]} An array of IPv4 or IPv6 subnets in CIDR notation.
+
+Adds multiple subnet rules using CIDR notation in a single call. The address
+family for each entry is automatically detected. This is equivalent to
+calling `blockList.addCIDR()` for each element of the array.
+
 ### `blockList.addRange(start, end[, type])`
 
 <!-- YAML
@@ -158,28 +199,13 @@ console.log(blockList.check('::ffff:7b7b:7b7b', 'ipv6')); // Prints: true
 console.log(blockList.check('::ffff:123.123.123.123', 'ipv6')); // Prints: true
 ```
 
-### `blockList.rules`
+### `blockList.clear()`
 
-<!-- YAML
-added:
- - v15.0.0
- - v14.18.0
+<!--
+added: REPLACEME
 -->
 
-* Type: {string\[]}
-
-The list of rules added to the blocklist.
-
-### `BlockList.isBlockList(value)`
-
-<!-- YAML
-added:
- - v23.4.0
- - v22.13.0
--->
-
-*`value` {any} Any JS value
-* Returns `true` if the `value` is a `net.BlockList`.
+Clears all rules from the `BlockList`.
 
 ### `blockList.fromJSON(value)`
 
@@ -205,6 +231,130 @@ blockList.fromJSON(JSON.stringify(data));
 
 *`value` Blocklist.rules
 
+### `BlockList.isBlockList(value)`
+
+<!-- YAML
+added:
+ - v23.4.0
+ - v22.13.0
+-->
+
+*`value` {any} Any JS value
+* Returns `true` if the `value` is a `net.BlockList`.
+
+### `BlockList.PRIVATE_RANGES`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {string\[]}
+
+A frozen array of CIDR strings representing private, loopback, and link-local
+IP address ranges. This can be passed to `blockList.addCIDRs()` to quickly
+populate a blocklist with all non-routable address ranges.
+
+The included ranges are:
+
+*`10.0.0.0/8` — RFC 1918 private IPv4
+*`172.16.0.0/12` — RFC 1918 private IPv4
+*`192.168.0.0/16` — RFC 1918 private IPv4
+*`127.0.0.0/8` — IPv4 loopback
+*`::1/128` — IPv6 loopback
+*`169.254.0.0/16` — IPv4 link-local
+*`fe80::/10` — IPv6 link-local
+*`fc00::/7` — IPv6 unique local (ULA)
+
+```js
+constblockList=newnet.BlockList();
+blockList.addCIDRs(net.BlockList.PRIVATE_RANGES);
+
+console.log(blockList.check('10.0.0.1')); // Prints: true
+console.log(blockList.check('127.0.0.1')); // Prints: true
+console.log(blockList.check('8.8.8.8')); // Prints: false
+```
+
+### `blockList.removeAddress(address[, type])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`address` {string|net.SocketAddress} An IPv4 or IPv6 address.
+*`type` {string} Either `'ipv4'` or `'ipv6'`. **Default:**`'ipv4'`.
+
+Removes a rule that was previously added with `blockList.addAddress()`. The
+address must match exactly the value used when the rule was added. If the
+specified address does not exist, this is a no-op.
+
+### `blockList.removeCIDR(cidr)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`cidr` {string} An IPv4 or IPv6 subnet in CIDR notation (e.g.
+`'10.0.0.0/8'` or `'2001:db8::/32'`).
+
+Removes a subnet rule using CIDR notation. The address family is automatically
+detected from the address. This is equivalent to calling
+`blockList.removeSubnet()` with the parsed network address, prefix length,
+and family. If the specified subnet does not exist, this is a no-op.
+
+### `blockList.removeRange(start, end[, type])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`start` {string|net.SocketAddress} The starting IPv4 or IPv6 address in the
+ range.
+*`end` {string|net.SocketAddress} The ending IPv4 or IPv6 address in the range.
+*`type` {string} Either `'ipv4'` or `'ipv6'`. **Default:**`'ipv4'`.
+
+Removes a rule that was previously added with `blockList.addRange()`. The `start`
+and `end` addresses must match exactly the values used when the rule was added.
+If the specified range does not exist, this is a no-op.
+
+### `blockList.removeSubnet(net, prefix[, type])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`net` {string|net.SocketAddress} The network IPv4 or IPv6 address.
+*`prefix` {number} The number of CIDR prefix bits. For IPv4, this
+ must be a value between `0` and `32`. For IPv6, this must be between
+`0` and `128`.
+*`type` {string} Either `'ipv4'` or `'ipv6'`. **Default:**`'ipv4'`.
+
+Removes a rule that was previously added with `blockList.addSubnet()`. The
+network address and prefix must match exactly the values used when the rule was
+added. If the specified subnet does not exist, this is a no-op.
+
+### `blockList.rules`
+
+<!-- YAML
+added:
+ - v15.0.0
+ - v14.18.0
+-->
+
+* Type: {string\[]}
+
+The list of rules added to the blocklist.
+
+### `blockList.size`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {number}
+
+The number of rules in the blocklist. This is equivalent to
+`blockList.rules.length` but does not allocate the rules array.
+
 ### `blockList.toJSON()`
 
 > Stability: 1.2 - Release candidate

benchmark/net/net-blocklist.js

@@ -0,0 +1,146 @@
+'use strict';
+
+constcommon=require('../common.js');
+const{ BlockList, SocketAddress }=require('net');
+
+consthasAddAddresses=typeofBlockList.prototype.addAddresses==='function';
+
+constoperations=['check','checkWithSocketAddress','addAddress'];
+if(hasAddAddresses){
+operations.push('addAddresses');
+}
+
+constbench=common.createBenchmark(main,{
+n: [1e6],
+ruleCount: [10,100,1000,10000],
+ruleType: ['address','subnet','mixed'],
+checkResult: ['hit','miss'],
+operation: operations,
+},{
+combinationFilter({ operation, ruleCount, ruleType }){
+// addAddress and addAddresses only need address rules, not subnets.
+if((operation==='addAddress'||operation==='addAddresses')&&
+ruleType!=='address'){
+returnfalse;
+}
+returntrue;
+},
+});
+
+functiongenerateIPv4(index){
+return`${(index>>>24)&0xff}.${(index>>>16)&0xff}.`+
+`${(index>>>8)&0xff}.${index&0xff}`;
+}
+
+functionbuildBlockList(ruleCount,ruleType){
+constblockList=newBlockList();
+
+if(ruleType==='address'||ruleType==='mixed'){
+constaddressCount=ruleType==='mixed' ?
+Math.floor(ruleCount/2) : ruleCount;
+constaddresses=[];
+for(leti=0;i<addressCount;i++){
+// Start from 10.0.0.1 to avoid 0.0.0.0
+addresses.push(generateIPv4(0x0a000001+i));
+}
+if(hasAddAddresses){
+blockList.addAddresses(addresses);
+}else{
+for(constaddrofaddresses){
+blockList.addAddress(addr);
+}
+}
+}
+
+if(ruleType==='subnet'||ruleType==='mixed'){
+constsubnetCount=ruleType==='mixed' ?
+Math.floor(ruleCount/2) : ruleCount;
+for(leti=0;i<subnetCount;i++){
+// Use distinct /24 subnets: 172.i.j.0/24
+constsecond=(i>>>8)&0xff;
+constthird=i&0xff;
+blockList.addSubnet(`172.${second}.${third}.0`,24);
+}
+}
+
+returnblockList;
+}
+
+functionmain({ n, ruleCount, ruleType, checkResult, operation }){
+if(operation==='check'){
+benchCheck(n,ruleCount,ruleType,checkResult);
+}elseif(operation==='checkWithSocketAddress'){
+benchCheckWithSocketAddress(n,ruleCount,ruleType,checkResult);
+}elseif(operation==='addAddress'){
+benchAddAddress(n,ruleCount);
+}elseif(operation==='addAddresses'){
+benchAddAddresses(n,ruleCount);
+}
+}
+
+// Benchmark check() with string addresses (the common JS API path).
+functionbenchCheck(n,ruleCount,ruleType,checkResult){
+constblockList=buildBlockList(ruleCount,ruleType);
+
+// For 'hit', use an address that's in the list.
+// For 'miss', use an address that's not in the list.
+constaddress=checkResult==='hit' ? '10.0.0.1' : '192.168.255.255';
+
+bench.start();
+for(leti=0;i<n;i++){
+blockList.check(address);
+}
+bench.end(n);
+}
+
+// Benchmark check() with pre-created SocketAddress objects
+// (avoids measuring SocketAddress construction overhead).
+functionbenchCheckWithSocketAddress(n,ruleCount,ruleType,checkResult){
+constblockList=buildBlockList(ruleCount,ruleType);
+
+constaddress=checkResult==='hit' ? '10.0.0.1' : '192.168.255.255';
+constsa=newSocketAddress({ address });
+
+bench.start();
+for(leti=0;i<n;i++){
+blockList.check(sa);
+}
+bench.end(n);
+}
+
+// Benchmark single addAddress() calls (one lock acquire per call).
+functionbenchAddAddress(n,ruleCount){
+// Scale n down for large rule counts to keep runtime reasonable.
+constiterations=Math.min(n,ruleCount*100);
+
+constaddresses=[];
+for(leti=0;i<ruleCount;i++){
+addresses.push(generateIPv4(0x0a000001+i));
+}
+
+bench.start();
+for(leti=0;i<iterations;i++){
+constblockList=newBlockList();
+for(letj=0;j<addresses.length;j++){
+blockList.addAddress(addresses[j]);
+}
+}
+bench.end(iterations);
+}
+
+// Benchmark batch addAddresses() (one lock acquire per batch).
+functionbenchAddAddresses(n,ruleCount){
+constiterations=Math.min(n,ruleCount*100);
+
+constaddresses=[];
+for(leti=0;i<ruleCount;i++){
+addresses.push(generateIPv4(0x0a000001+i));
+}
+
+bench.start();
+for(leti=0;i<iterations;i++){
+constblockList=newBlockList();
+blockList.addAddresses(addresses);
+}
+bench.end(iterations);
+}

doc/api/net.md

@@ -96,6 +96,47 @@ added:
 
 Adds a rule to block the given IP address.
 
+### `blockList.addAddresses(addresses[, type])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`addresses` {string\[]|net.SocketAddress\[]} An array of IPv4 or IPv6
+ addresses.
+*`type` {string} Either `'ipv4'` or `'ipv6'`. **Default:**`'ipv4'`.
+
+Adds multiple address rules to the block list in a single operation.
+This is more efficient than calling `blockList.addAddress()` repeatedly
+when adding a large number of individual addresses, as the addresses
+are inserted under a single internal lock acquisition.
+
+### `blockList.addCIDR(cidr)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`cidr` {string} An IPv4 or IPv6 subnet in CIDR notation (e.g.
+`'10.0.0.0/8'` or `'2001:db8::/32'`).
+
+Adds a subnet rule using CIDR notation. The address family is automatically
+detected from the address (IPv6 if the address contains `':'`, IPv4
+otherwise). This is equivalent to calling `blockList.addSubnet()` with
+the parsed network address, prefix length, and family.
+
+### `blockList.addCIDRs(cidrs)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`cidrs` {string\[]} An array of IPv4 or IPv6 subnets in CIDR notation.
+
+Adds multiple subnet rules using CIDR notation in a single call. The address
+family for each entry is automatically detected. This is equivalent to
+calling `blockList.addCIDR()` for each element of the array.
+
 ### `blockList.addRange(start, end[, type])`
 
 <!-- YAML
@@ -158,28 +199,13 @@ console.log(blockList.check('::ffff:7b7b:7b7b', 'ipv6')); // Prints: true
 console.log(blockList.check('::ffff:123.123.123.123', 'ipv6')); // Prints: true
 ```
 
-### `blockList.rules`
+### `blockList.clear()`
 
-<!-- YAML
-added:
- - v15.0.0
- - v14.18.0
+<!--
+added: REPLACEME
 -->
 
-* Type: {string\[]}
-
-The list of rules added to the blocklist.
-
-### `BlockList.isBlockList(value)`
-
-<!-- YAML
-added:
- - v23.4.0
- - v22.13.0
--->
-
-*`value` {any} Any JS value
-* Returns `true` if the `value` is a `net.BlockList`.
+Clears all rules from the `BlockList`.
 
 ### `blockList.fromJSON(value)`
 
@@ -205,6 +231,130 @@ blockList.fromJSON(JSON.stringify(data));
 
 *`value` Blocklist.rules
 
+### `BlockList.isBlockList(value)`
+
+<!-- YAML
+added:
+ - v23.4.0
+ - v22.13.0
+-->
+
+*`value` {any} Any JS value
+* Returns `true` if the `value` is a `net.BlockList`.
+
+### `BlockList.PRIVATE_RANGES`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {string\[]}
+
+A frozen array of CIDR strings representing private, loopback, and link-local
+IP address ranges. This can be passed to `blockList.addCIDRs()` to quickly
+populate a blocklist with all non-routable address ranges.
+
+The included ranges are:
+
+*`10.0.0.0/8` — RFC 1918 private IPv4
+*`172.16.0.0/12` — RFC 1918 private IPv4
+*`192.168.0.0/16` — RFC 1918 private IPv4
+*`127.0.0.0/8` — IPv4 loopback
+*`::1/128` — IPv6 loopback
+*`169.254.0.0/16` — IPv4 link-local
+*`fe80::/10` — IPv6 link-local
+*`fc00::/7` — IPv6 unique local (ULA)
+
+```js
+constblockList=newnet.BlockList();
+blockList.addCIDRs(net.BlockList.PRIVATE_RANGES);
+
+console.log(blockList.check('10.0.0.1')); // Prints: true
+console.log(blockList.check('127.0.0.1')); // Prints: true
+console.log(blockList.check('8.8.8.8')); // Prints: false
+```
+
+### `blockList.removeAddress(address[, type])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`address` {string|net.SocketAddress} An IPv4 or IPv6 address.
+*`type` {string} Either `'ipv4'` or `'ipv6'`. **Default:**`'ipv4'`.
+
+Removes a rule that was previously added with `blockList.addAddress()`. The
+address must match exactly the value used when the rule was added. If the
+specified address does not exist, this is a no-op.
+
+### `blockList.removeCIDR(cidr)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`cidr` {string} An IPv4 or IPv6 subnet in CIDR notation (e.g.
+`'10.0.0.0/8'` or `'2001:db8::/32'`).
+
+Removes a subnet rule using CIDR notation. The address family is automatically
+detected from the address. This is equivalent to calling
+`blockList.removeSubnet()` with the parsed network address, prefix length,
+and family. If the specified subnet does not exist, this is a no-op.
+
+### `blockList.removeRange(start, end[, type])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`start` {string|net.SocketAddress} The starting IPv4 or IPv6 address in the
+ range.
+*`end` {string|net.SocketAddress} The ending IPv4 or IPv6 address in the range.
+*`type` {string} Either `'ipv4'` or `'ipv6'`. **Default:**`'ipv4'`.
+
+Removes a rule that was previously added with `blockList.addRange()`. The `start`
+and `end` addresses must match exactly the values used when the rule was added.
+If the specified range does not exist, this is a no-op.
+
+### `blockList.removeSubnet(net, prefix[, type])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`net` {string|net.SocketAddress} The network IPv4 or IPv6 address.
+*`prefix` {number} The number of CIDR prefix bits. For IPv4, this
+ must be a value between `0` and `32`. For IPv6, this must be between
+`0` and `128`.
+*`type` {string} Either `'ipv4'` or `'ipv6'`. **Default:**`'ipv4'`.
+
+Removes a rule that was previously added with `blockList.addSubnet()`. The
+network address and prefix must match exactly the values used when the rule was
+added. If the specified subnet does not exist, this is a no-op.
+
+### `blockList.rules`
+
+<!-- YAML
+added:
+ - v15.0.0
+ - v14.18.0
+-->
+
+* Type: {string\[]}
+
+The list of rules added to the blocklist.
+
+### `blockList.size`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {number}
+
+The number of rules in the blocklist. This is equivalent to
+`blockList.rules.length` but does not allocate the rules array.
+
 ### `blockList.toJSON()`
 
 > Stability: 1.2 - Release candidate

benchmark/net/net-blocklist.js

@@ -0,0 +1,146 @@
+'use strict';
+
+constcommon=require('../common.js');
+const{ BlockList, SocketAddress }=require('net');
+
+consthasAddAddresses=typeofBlockList.prototype.addAddresses==='function';
+
+constoperations=['check','checkWithSocketAddress','addAddress'];
+if(hasAddAddresses){
+operations.push('addAddresses');
+}
+
+constbench=common.createBenchmark(main,{
+n: [1e6],
+ruleCount: [10,100,1000,10000],
+ruleType: ['address','subnet','mixed'],
+checkResult: ['hit','miss'],
+operation: operations,
+},{
+combinationFilter({ operation, ruleCount, ruleType }){
+// addAddress and addAddresses only need address rules, not subnets.
+if((operation==='addAddress'||operation==='addAddresses')&&
+ruleType!=='address'){
+returnfalse;
+}
+returntrue;
+},
+});
+
+functiongenerateIPv4(index){
+return`${(index>>>24)&0xff}.${(index>>>16)&0xff}.`+
+`${(index>>>8)&0xff}.${index&0xff}`;
+}
+
+functionbuildBlockList(ruleCount,ruleType){
+constblockList=newBlockList();
+
+if(ruleType==='address'||ruleType==='mixed'){
+constaddressCount=ruleType==='mixed' ?
+Math.floor(ruleCount/2) : ruleCount;
+constaddresses=[];
+for(leti=0;i<addressCount;i++){
+// Start from 10.0.0.1 to avoid 0.0.0.0
+addresses.push(generateIPv4(0x0a000001+i));
+}
+if(hasAddAddresses){
+blockList.addAddresses(addresses);
+}else{
+for(constaddrofaddresses){
+blockList.addAddress(addr);
+}
+}
+}
+
+if(ruleType==='subnet'||ruleType==='mixed'){
+constsubnetCount=ruleType==='mixed' ?
+Math.floor(ruleCount/2) : ruleCount;
+for(leti=0;i<subnetCount;i++){
+// Use distinct /24 subnets: 172.i.j.0/24
+constsecond=(i>>>8)&0xff;
+constthird=i&0xff;
+blockList.addSubnet(`172.${second}.${third}.0`,24);
+}
+}
+
+returnblockList;
+}
+
+functionmain({ n, ruleCount, ruleType, checkResult, operation }){
+if(operation==='check'){
+benchCheck(n,ruleCount,ruleType,checkResult);
+}elseif(operation==='checkWithSocketAddress'){
+benchCheckWithSocketAddress(n,ruleCount,ruleType,checkResult);
+}elseif(operation==='addAddress'){
+benchAddAddress(n,ruleCount);
+}elseif(operation==='addAddresses'){
+benchAddAddresses(n,ruleCount);
+}
+}
+
+// Benchmark check() with string addresses (the common JS API path).
+functionbenchCheck(n,ruleCount,ruleType,checkResult){
+constblockList=buildBlockList(ruleCount,ruleType);
+
+// For 'hit', use an address that's in the list.
+// For 'miss', use an address that's not in the list.
+constaddress=checkResult==='hit' ? '10.0.0.1' : '192.168.255.255';
+
+bench.start();
+for(leti=0;i<n;i++){
+blockList.check(address);
+}
+bench.end(n);
+}
+
+// Benchmark check() with pre-created SocketAddress objects
+// (avoids measuring SocketAddress construction overhead).
+functionbenchCheckWithSocketAddress(n,ruleCount,ruleType,checkResult){
+constblockList=buildBlockList(ruleCount,ruleType);
+
+constaddress=checkResult==='hit' ? '10.0.0.1' : '192.168.255.255';
+constsa=newSocketAddress({ address });
+
+bench.start();
+for(leti=0;i<n;i++){
+blockList.check(sa);
+}
+bench.end(n);
+}
+
+// Benchmark single addAddress() calls (one lock acquire per call).
+functionbenchAddAddress(n,ruleCount){
+// Scale n down for large rule counts to keep runtime reasonable.
+constiterations=Math.min(n,ruleCount*100);
+
+constaddresses=[];
+for(leti=0;i<ruleCount;i++){
+addresses.push(generateIPv4(0x0a000001+i));
+}
+
+bench.start();
+for(leti=0;i<iterations;i++){
+constblockList=newBlockList();
+for(letj=0;j<addresses.length;j++){
+blockList.addAddress(addresses[j]);
+}
+}
+bench.end(iterations);
+}
+
+// Benchmark batch addAddresses() (one lock acquire per batch).
+functionbenchAddAddresses(n,ruleCount){
+constiterations=Math.min(n,ruleCount*100);
+
+constaddresses=[];
+for(leti=0;i<ruleCount;i++){
+addresses.push(generateIPv4(0x0a000001+i));
+}
+
+bench.start();
+for(leti=0;i<iterations;i++){
+constblockList=newBlockList();
+blockList.addAddresses(addresses);
+}
+bench.end(iterations);
+}

doc/api/net.md

@@ -96,6 +96,47 @@ added:
 
 Adds a rule to block the given IP address.
 
+### `blockList.addAddresses(addresses[, type])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`addresses` {string\[]|net.SocketAddress\[]} An array of IPv4 or IPv6
+ addresses.
+*`type` {string} Either `'ipv4'` or `'ipv6'`. **Default:**`'ipv4'`.
+
+Adds multiple address rules to the block list in a single operation.
+This is more efficient than calling `blockList.addAddress()` repeatedly
+when adding a large number of individual addresses, as the addresses
+are inserted under a single internal lock acquisition.
+
+### `blockList.addCIDR(cidr)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`cidr` {string} An IPv4 or IPv6 subnet in CIDR notation (e.g.
+`'10.0.0.0/8'` or `'2001:db8::/32'`).
+
+Adds a subnet rule using CIDR notation. The address family is automatically
+detected from the address (IPv6 if the address contains `':'`, IPv4
+otherwise). This is equivalent to calling `blockList.addSubnet()` with
+the parsed network address, prefix length, and family.
+
+### `blockList.addCIDRs(cidrs)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`cidrs` {string\[]} An array of IPv4 or IPv6 subnets in CIDR notation.
+
+Adds multiple subnet rules using CIDR notation in a single call. The address
+family for each entry is automatically detected. This is equivalent to
+calling `blockList.addCIDR()` for each element of the array.
+
 ### `blockList.addRange(start, end[, type])`
 
 <!-- YAML
@@ -158,28 +199,13 @@ console.log(blockList.check('::ffff:7b7b:7b7b', 'ipv6')); // Prints: true
 console.log(blockList.check('::ffff:123.123.123.123', 'ipv6')); // Prints: true
 ```
 
-### `blockList.rules`
+### `blockList.clear()`
 
-<!-- YAML
-added:
- - v15.0.0
- - v14.18.0
+<!--
+added: REPLACEME
 -->
 
-* Type: {string\[]}
-
-The list of rules added to the blocklist.
-
-### `BlockList.isBlockList(value)`
-
-<!-- YAML
-added:
- - v23.4.0
- - v22.13.0
--->
-
-*`value` {any} Any JS value
-* Returns `true` if the `value` is a `net.BlockList`.
+Clears all rules from the `BlockList`.
 
 ### `blockList.fromJSON(value)`
 
@@ -205,6 +231,130 @@ blockList.fromJSON(JSON.stringify(data));
 
 *`value` Blocklist.rules
 
+### `BlockList.isBlockList(value)`
+
+<!-- YAML
+added:
+ - v23.4.0
+ - v22.13.0
+-->
+
+*`value` {any} Any JS value
+* Returns `true` if the `value` is a `net.BlockList`.
+
+### `BlockList.PRIVATE_RANGES`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {string\[]}
+
+A frozen array of CIDR strings representing private, loopback, and link-local
+IP address ranges. This can be passed to `blockList.addCIDRs()` to quickly
+populate a blocklist with all non-routable address ranges.
+
+The included ranges are:
+
+*`10.0.0.0/8` — RFC 1918 private IPv4
+*`172.16.0.0/12` — RFC 1918 private IPv4
+*`192.168.0.0/16` — RFC 1918 private IPv4
+*`127.0.0.0/8` — IPv4 loopback
+*`::1/128` — IPv6 loopback
+*`169.254.0.0/16` — IPv4 link-local
+*`fe80::/10` — IPv6 link-local
+*`fc00::/7` — IPv6 unique local (ULA)
+
+```js
+constblockList=newnet.BlockList();
+blockList.addCIDRs(net.BlockList.PRIVATE_RANGES);
+
+console.log(blockList.check('10.0.0.1')); // Prints: true
+console.log(blockList.check('127.0.0.1')); // Prints: true
+console.log(blockList.check('8.8.8.8')); // Prints: false
+```
+
+### `blockList.removeAddress(address[, type])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`address` {string|net.SocketAddress} An IPv4 or IPv6 address.
+*`type` {string} Either `'ipv4'` or `'ipv6'`. **Default:**`'ipv4'`.
+
+Removes a rule that was previously added with `blockList.addAddress()`. The
+address must match exactly the value used when the rule was added. If the
+specified address does not exist, this is a no-op.
+
+### `blockList.removeCIDR(cidr)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`cidr` {string} An IPv4 or IPv6 subnet in CIDR notation (e.g.
+`'10.0.0.0/8'` or `'2001:db8::/32'`).
+
+Removes a subnet rule using CIDR notation. The address family is automatically
+detected from the address. This is equivalent to calling
+`blockList.removeSubnet()` with the parsed network address, prefix length,
+and family. If the specified subnet does not exist, this is a no-op.
+
+### `blockList.removeRange(start, end[, type])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`start` {string|net.SocketAddress} The starting IPv4 or IPv6 address in the
+ range.
+*`end` {string|net.SocketAddress} The ending IPv4 or IPv6 address in the range.
+*`type` {string} Either `'ipv4'` or `'ipv6'`. **Default:**`'ipv4'`.
+
+Removes a rule that was previously added with `blockList.addRange()`. The `start`
+and `end` addresses must match exactly the values used when the rule was added.
+If the specified range does not exist, this is a no-op.
+
+### `blockList.removeSubnet(net, prefix[, type])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`net` {string|net.SocketAddress} The network IPv4 or IPv6 address.
+*`prefix` {number} The number of CIDR prefix bits. For IPv4, this
+ must be a value between `0` and `32`. For IPv6, this must be between
+`0` and `128`.
+*`type` {string} Either `'ipv4'` or `'ipv6'`. **Default:**`'ipv4'`.
+
+Removes a rule that was previously added with `blockList.addSubnet()`. The
+network address and prefix must match exactly the values used when the rule was
+added. If the specified subnet does not exist, this is a no-op.
+
+### `blockList.rules`
+
+<!-- YAML
+added:
+ - v15.0.0
+ - v14.18.0
+-->
+
+* Type: {string\[]}
+
+The list of rules added to the blocklist.
+
+### `blockList.size`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {number}
+
+The number of rules in the blocklist. This is equivalent to
+`blockList.rules.length` but does not allocate the rules array.
+
 ### `blockList.toJSON()`
 
 > Stability: 1.2 - Release candidate

benchmark/net/net-blocklist.js

@@ -0,0 +1,146 @@
+'use strict';
+
+constcommon=require('../common.js');
+const{ BlockList, SocketAddress }=require('net');
+
+consthasAddAddresses=typeofBlockList.prototype.addAddresses==='function';
+
+constoperations=['check','checkWithSocketAddress','addAddress'];
+if(hasAddAddresses){
+operations.push('addAddresses');
+}
+
+constbench=common.createBenchmark(main,{
+n: [1e6],
+ruleCount: [10,100,1000,10000],
+ruleType: ['address','subnet','mixed'],
+checkResult: ['hit','miss'],
+operation: operations,
+},{
+combinationFilter({ operation, ruleCount, ruleType }){
+// addAddress and addAddresses only need address rules, not subnets.
+if((operation==='addAddress'||operation==='addAddresses')&&
+ruleType!=='address'){
+returnfalse;
+}
+returntrue;
+},
+});
+
+functiongenerateIPv4(index){
+return`${(index>>>24)&0xff}.${(index>>>16)&0xff}.`+
+`${(index>>>8)&0xff}.${index&0xff}`;
+}
+
+functionbuildBlockList(ruleCount,ruleType){
+constblockList=newBlockList();
+
+if(ruleType==='address'||ruleType==='mixed'){
+constaddressCount=ruleType==='mixed' ?
+Math.floor(ruleCount/2) : ruleCount;
+constaddresses=[];
+for(leti=0;i<addressCount;i++){
+// Start from 10.0.0.1 to avoid 0.0.0.0
+addresses.push(generateIPv4(0x0a000001+i));
+}
+if(hasAddAddresses){
+blockList.addAddresses(addresses);
+}else{
+for(constaddrofaddresses){
+blockList.addAddress(addr);
+}
+}
+}
+
+if(ruleType==='subnet'||ruleType==='mixed'){
+constsubnetCount=ruleType==='mixed' ?
+Math.floor(ruleCount/2) : ruleCount;
+for(leti=0;i<subnetCount;i++){
+// Use distinct /24 subnets: 172.i.j.0/24
+constsecond=(i>>>8)&0xff;
+constthird=i&0xff;
+blockList.addSubnet(`172.${second}.${third}.0`,24);
+}
+}
+
+returnblockList;
+}
+
+functionmain({ n, ruleCount, ruleType, checkResult, operation }){
+if(operation==='check'){
+benchCheck(n,ruleCount,ruleType,checkResult);
+}elseif(operation==='checkWithSocketAddress'){
+benchCheckWithSocketAddress(n,ruleCount,ruleType,checkResult);
+}elseif(operation==='addAddress'){
+benchAddAddress(n,ruleCount);
+}elseif(operation==='addAddresses'){
+benchAddAddresses(n,ruleCount);
+}
+}
+
+// Benchmark check() with string addresses (the common JS API path).
+functionbenchCheck(n,ruleCount,ruleType,checkResult){
+constblockList=buildBlockList(ruleCount,ruleType);
+
+// For 'hit', use an address that's in the list.
+// For 'miss', use an address that's not in the list.
+constaddress=checkResult==='hit' ? '10.0.0.1' : '192.168.255.255';
+
+bench.start();
+for(leti=0;i<n;i++){
+blockList.check(address);
+}
+bench.end(n);
+}
+
+// Benchmark check() with pre-created SocketAddress objects
+// (avoids measuring SocketAddress construction overhead).
+functionbenchCheckWithSocketAddress(n,ruleCount,ruleType,checkResult){
+constblockList=buildBlockList(ruleCount,ruleType);
+
+constaddress=checkResult==='hit' ? '10.0.0.1' : '192.168.255.255';
+constsa=newSocketAddress({ address });
+
+bench.start();
+for(leti=0;i<n;i++){
+blockList.check(sa);
+}
+bench.end(n);
+}
+
+// Benchmark single addAddress() calls (one lock acquire per call).
+functionbenchAddAddress(n,ruleCount){
+// Scale n down for large rule counts to keep runtime reasonable.
+constiterations=Math.min(n,ruleCount*100);
+
+constaddresses=[];
+for(leti=0;i<ruleCount;i++){
+addresses.push(generateIPv4(0x0a000001+i));
+}
+
+bench.start();
+for(leti=0;i<iterations;i++){
+constblockList=newBlockList();
+for(letj=0;j<addresses.length;j++){
+blockList.addAddress(addresses[j]);
+}
+}
+bench.end(iterations);
+}
+
+// Benchmark batch addAddresses() (one lock acquire per batch).
+functionbenchAddAddresses(n,ruleCount){
+constiterations=Math.min(n,ruleCount*100);
+
+constaddresses=[];
+for(leti=0;i<ruleCount;i++){
+addresses.push(generateIPv4(0x0a000001+i));
+}
+
+bench.start();
+for(leti=0;i<iterations;i++){
+constblockList=newBlockList();
+blockList.addAddresses(addresses);
+}
+bench.end(iterations);
+}

doc/api/net.md

@@ -96,6 +96,47 @@ added:
 
 Adds a rule to block the given IP address.
 
+### `blockList.addAddresses(addresses[, type])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`addresses` {string\[]|net.SocketAddress\[]} An array of IPv4 or IPv6
+ addresses.
+*`type` {string} Either `'ipv4'` or `'ipv6'`. **Default:**`'ipv4'`.
+
+Adds multiple address rules to the block list in a single operation.
+This is more efficient than calling `blockList.addAddress()` repeatedly
+when adding a large number of individual addresses, as the addresses
+are inserted under a single internal lock acquisition.
+
+### `blockList.addCIDR(cidr)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`cidr` {string} An IPv4 or IPv6 subnet in CIDR notation (e.g.
+`'10.0.0.0/8'` or `'2001:db8::/32'`).
+
+Adds a subnet rule using CIDR notation. The address family is automatically
+detected from the address (IPv6 if the address contains `':'`, IPv4
+otherwise). This is equivalent to calling `blockList.addSubnet()` with
+the parsed network address, prefix length, and family.
+
+### `blockList.addCIDRs(cidrs)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`cidrs` {string\[]} An array of IPv4 or IPv6 subnets in CIDR notation.
+
+Adds multiple subnet rules using CIDR notation in a single call. The address
+family for each entry is automatically detected. This is equivalent to
+calling `blockList.addCIDR()` for each element of the array.
+
 ### `blockList.addRange(start, end[, type])`
 
 <!-- YAML
@@ -158,28 +199,13 @@ console.log(blockList.check('::ffff:7b7b:7b7b', 'ipv6')); // Prints: true
 console.log(blockList.check('::ffff:123.123.123.123', 'ipv6')); // Prints: true
 ```
 
-### `blockList.rules`
+### `blockList.clear()`
 
-<!-- YAML
-added:
- - v15.0.0
- - v14.18.0
+<!--
+added: REPLACEME
 -->
 
-* Type: {string\[]}
-
-The list of rules added to the blocklist.
-
-### `BlockList.isBlockList(value)`
-
-<!-- YAML
-added:
- - v23.4.0
- - v22.13.0
--->
-
-*`value` {any} Any JS value
-* Returns `true` if the `value` is a `net.BlockList`.
+Clears all rules from the `BlockList`.
 
 ### `blockList.fromJSON(value)`
 
@@ -205,6 +231,130 @@ blockList.fromJSON(JSON.stringify(data));
 
 *`value` Blocklist.rules
 
+### `BlockList.isBlockList(value)`
+
+<!-- YAML
+added:
+ - v23.4.0
+ - v22.13.0
+-->
+
+*`value` {any} Any JS value
+* Returns `true` if the `value` is a `net.BlockList`.
+
+### `BlockList.PRIVATE_RANGES`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {string\[]}
+
+A frozen array of CIDR strings representing private, loopback, and link-local
+IP address ranges. This can be passed to `blockList.addCIDRs()` to quickly
+populate a blocklist with all non-routable address ranges.
+
+The included ranges are:
+
+*`10.0.0.0/8` — RFC 1918 private IPv4
+*`172.16.0.0/12` — RFC 1918 private IPv4
+*`192.168.0.0/16` — RFC 1918 private IPv4
+*`127.0.0.0/8` — IPv4 loopback
+*`::1/128` — IPv6 loopback
+*`169.254.0.0/16` — IPv4 link-local
+*`fe80::/10` — IPv6 link-local
+*`fc00::/7` — IPv6 unique local (ULA)
+
+```js
+constblockList=newnet.BlockList();
+blockList.addCIDRs(net.BlockList.PRIVATE_RANGES);
+
+console.log(blockList.check('10.0.0.1')); // Prints: true
+console.log(blockList.check('127.0.0.1')); // Prints: true
+console.log(blockList.check('8.8.8.8')); // Prints: false
+```
+
+### `blockList.removeAddress(address[, type])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`address` {string|net.SocketAddress} An IPv4 or IPv6 address.
+*`type` {string} Either `'ipv4'` or `'ipv6'`. **Default:**`'ipv4'`.
+
+Removes a rule that was previously added with `blockList.addAddress()`. The
+address must match exactly the value used when the rule was added. If the
+specified address does not exist, this is a no-op.
+
+### `blockList.removeCIDR(cidr)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`cidr` {string} An IPv4 or IPv6 subnet in CIDR notation (e.g.
+`'10.0.0.0/8'` or `'2001:db8::/32'`).
+
+Removes a subnet rule using CIDR notation. The address family is automatically
+detected from the address. This is equivalent to calling
+`blockList.removeSubnet()` with the parsed network address, prefix length,
+and family. If the specified subnet does not exist, this is a no-op.
+
+### `blockList.removeRange(start, end[, type])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`start` {string|net.SocketAddress} The starting IPv4 or IPv6 address in the
+ range.
+*`end` {string|net.SocketAddress} The ending IPv4 or IPv6 address in the range.
+*`type` {string} Either `'ipv4'` or `'ipv6'`. **Default:**`'ipv4'`.
+
+Removes a rule that was previously added with `blockList.addRange()`. The `start`
+and `end` addresses must match exactly the values used when the rule was added.
+If the specified range does not exist, this is a no-op.
+
+### `blockList.removeSubnet(net, prefix[, type])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`net` {string|net.SocketAddress} The network IPv4 or IPv6 address.
+*`prefix` {number} The number of CIDR prefix bits. For IPv4, this
+ must be a value between `0` and `32`. For IPv6, this must be between
+`0` and `128`.
+*`type` {string} Either `'ipv4'` or `'ipv6'`. **Default:**`'ipv4'`.
+
+Removes a rule that was previously added with `blockList.addSubnet()`. The
+network address and prefix must match exactly the values used when the rule was
+added. If the specified subnet does not exist, this is a no-op.
+
+### `blockList.rules`
+
+<!-- YAML
+added:
+ - v15.0.0
+ - v14.18.0
+-->
+
+* Type: {string\[]}
+
+The list of rules added to the blocklist.
+
+### `blockList.size`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {number}
+
+The number of rules in the blocklist. This is equivalent to
+`blockList.rules.length` but does not allocate the rules array.
+
 ### `blockList.toJSON()`
 
 > Stability: 1.2 - Release candidate

benchmark/net/net-blocklist.js

@@ -0,0 +1,146 @@
+'use strict';
+
+constcommon=require('../common.js');
+const{ BlockList, SocketAddress }=require('net');
+
+consthasAddAddresses=typeofBlockList.prototype.addAddresses==='function';
+
+constoperations=['check','checkWithSocketAddress','addAddress'];
+if(hasAddAddresses){
+operations.push('addAddresses');
+}
+
+constbench=common.createBenchmark(main,{
+n: [1e6],
+ruleCount: [10,100,1000,10000],
+ruleType: ['address','subnet','mixed'],
+checkResult: ['hit','miss'],
+operation: operations,
+},{
+combinationFilter({ operation, ruleCount, ruleType }){
+// addAddress and addAddresses only need address rules, not subnets.
+if((operation==='addAddress'||operation==='addAddresses')&&
+ruleType!=='address'){
+returnfalse;
+}
+returntrue;
+},
+});
+
+functiongenerateIPv4(index){
+return`${(index>>>24)&0xff}.${(index>>>16)&0xff}.`+
+`${(index>>>8)&0xff}.${index&0xff}`;
+}
+
+functionbuildBlockList(ruleCount,ruleType){
+constblockList=newBlockList();
+
+if(ruleType==='address'||ruleType==='mixed'){
+constaddressCount=ruleType==='mixed' ?
+Math.floor(ruleCount/2) : ruleCount;
+constaddresses=[];
+for(leti=0;i<addressCount;i++){
+// Start from 10.0.0.1 to avoid 0.0.0.0
+addresses.push(generateIPv4(0x0a000001+i));
+}
+if(hasAddAddresses){
+blockList.addAddresses(addresses);
+}else{
+for(constaddrofaddresses){
+blockList.addAddress(addr);
+}
+}
+}
+
+if(ruleType==='subnet'||ruleType==='mixed'){
+constsubnetCount=ruleType==='mixed' ?
+Math.floor(ruleCount/2) : ruleCount;
+for(leti=0;i<subnetCount;i++){
+// Use distinct /24 subnets: 172.i.j.0/24
+constsecond=(i>>>8)&0xff;
+constthird=i&0xff;
+blockList.addSubnet(`172.${second}.${third}.0`,24);
+}
+}
+
+returnblockList;
+}
+
+functionmain({ n, ruleCount, ruleType, checkResult, operation }){
+if(operation==='check'){
+benchCheck(n,ruleCount,ruleType,checkResult);
+}elseif(operation==='checkWithSocketAddress'){
+benchCheckWithSocketAddress(n,ruleCount,ruleType,checkResult);
+}elseif(operation==='addAddress'){
+benchAddAddress(n,ruleCount);
+}elseif(operation==='addAddresses'){
+benchAddAddresses(n,ruleCount);
+}
+}
+
+// Benchmark check() with string addresses (the common JS API path).
+functionbenchCheck(n,ruleCount,ruleType,checkResult){
+constblockList=buildBlockList(ruleCount,ruleType);
+
+// For 'hit', use an address that's in the list.
+// For 'miss', use an address that's not in the list.
+constaddress=checkResult==='hit' ? '10.0.0.1' : '192.168.255.255';
+
+bench.start();
+for(leti=0;i<n;i++){
+blockList.check(address);
+}
+bench.end(n);
+}
+
+// Benchmark check() with pre-created SocketAddress objects
+// (avoids measuring SocketAddress construction overhead).
+functionbenchCheckWithSocketAddress(n,ruleCount,ruleType,checkResult){
+constblockList=buildBlockList(ruleCount,ruleType);
+
+constaddress=checkResult==='hit' ? '10.0.0.1' : '192.168.255.255';
+constsa=newSocketAddress({ address });
+
+bench.start();
+for(leti=0;i<n;i++){
+blockList.check(sa);
+}
+bench.end(n);
+}
+
+// Benchmark single addAddress() calls (one lock acquire per call).
+functionbenchAddAddress(n,ruleCount){
+// Scale n down for large rule counts to keep runtime reasonable.
+constiterations=Math.min(n,ruleCount*100);
+
+constaddresses=[];
+for(leti=0;i<ruleCount;i++){
+addresses.push(generateIPv4(0x0a000001+i));
+}
+
+bench.start();
+for(leti=0;i<iterations;i++){
+constblockList=newBlockList();
+for(letj=0;j<addresses.length;j++){
+blockList.addAddress(addresses[j]);
+}
+}
+bench.end(iterations);
+}
+
+// Benchmark batch addAddresses() (one lock acquire per batch).
+functionbenchAddAddresses(n,ruleCount){
+constiterations=Math.min(n,ruleCount*100);
+
+constaddresses=[];
+for(leti=0;i<ruleCount;i++){
+addresses.push(generateIPv4(0x0a000001+i));
+}
+
+bench.start();
+for(leti=0;i<iterations;i++){
+constblockList=newBlockList();
+blockList.addAddresses(addresses);
+}
+bench.end(iterations);
+}

doc/api/net.md

@@ -96,6 +96,47 @@ added:
 
 Adds a rule to block the given IP address.
 
+### `blockList.addAddresses(addresses[, type])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`addresses` {string\[]|net.SocketAddress\[]} An array of IPv4 or IPv6
+ addresses.
+*`type` {string} Either `'ipv4'` or `'ipv6'`. **Default:**`'ipv4'`.
+
+Adds multiple address rules to the block list in a single operation.
+This is more efficient than calling `blockList.addAddress()` repeatedly
+when adding a large number of individual addresses, as the addresses
+are inserted under a single internal lock acquisition.
+
+### `blockList.addCIDR(cidr)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`cidr` {string} An IPv4 or IPv6 subnet in CIDR notation (e.g.
+`'10.0.0.0/8'` or `'2001:db8::/32'`).
+
+Adds a subnet rule using CIDR notation. The address family is automatically
+detected from the address (IPv6 if the address contains `':'`, IPv4
+otherwise). This is equivalent to calling `blockList.addSubnet()` with
+the parsed network address, prefix length, and family.
+
+### `blockList.addCIDRs(cidrs)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`cidrs` {string\[]} An array of IPv4 or IPv6 subnets in CIDR notation.
+
+Adds multiple subnet rules using CIDR notation in a single call. The address
+family for each entry is automatically detected. This is equivalent to
+calling `blockList.addCIDR()` for each element of the array.
+
 ### `blockList.addRange(start, end[, type])`
 
 <!-- YAML
@@ -158,28 +199,13 @@ console.log(blockList.check('::ffff:7b7b:7b7b', 'ipv6')); // Prints: true
 console.log(blockList.check('::ffff:123.123.123.123', 'ipv6')); // Prints: true
 ```
 
-### `blockList.rules`
+### `blockList.clear()`
 
-<!-- YAML
-added:
- - v15.0.0
- - v14.18.0
+<!--
+added: REPLACEME
 -->
 
-* Type: {string\[]}
-
-The list of rules added to the blocklist.
-
-### `BlockList.isBlockList(value)`
-
-<!-- YAML
-added:
- - v23.4.0
- - v22.13.0
--->
-
-*`value` {any} Any JS value
-* Returns `true` if the `value` is a `net.BlockList`.
+Clears all rules from the `BlockList`.
 
 ### `blockList.fromJSON(value)`
 
@@ -205,6 +231,130 @@ blockList.fromJSON(JSON.stringify(data));
 
 *`value` Blocklist.rules
 
+### `BlockList.isBlockList(value)`
+
+<!-- YAML
+added:
+ - v23.4.0
+ - v22.13.0
+-->
+
+*`value` {any} Any JS value
+* Returns `true` if the `value` is a `net.BlockList`.
+
+### `BlockList.PRIVATE_RANGES`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {string\[]}
+
+A frozen array of CIDR strings representing private, loopback, and link-local
+IP address ranges. This can be passed to `blockList.addCIDRs()` to quickly
+populate a blocklist with all non-routable address ranges.
+
+The included ranges are:
+
+*`10.0.0.0/8` — RFC 1918 private IPv4
+*`172.16.0.0/12` — RFC 1918 private IPv4
+*`192.168.0.0/16` — RFC 1918 private IPv4
+*`127.0.0.0/8` — IPv4 loopback
+*`::1/128` — IPv6 loopback
+*`169.254.0.0/16` — IPv4 link-local
+*`fe80::/10` — IPv6 link-local
+*`fc00::/7` — IPv6 unique local (ULA)
+
+```js
+constblockList=newnet.BlockList();
+blockList.addCIDRs(net.BlockList.PRIVATE_RANGES);
+
+console.log(blockList.check('10.0.0.1')); // Prints: true
+console.log(blockList.check('127.0.0.1')); // Prints: true
+console.log(blockList.check('8.8.8.8')); // Prints: false
+```
+
+### `blockList.removeAddress(address[, type])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`address` {string|net.SocketAddress} An IPv4 or IPv6 address.
+*`type` {string} Either `'ipv4'` or `'ipv6'`. **Default:**`'ipv4'`.
+
+Removes a rule that was previously added with `blockList.addAddress()`. The
+address must match exactly the value used when the rule was added. If the
+specified address does not exist, this is a no-op.
+
+### `blockList.removeCIDR(cidr)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`cidr` {string} An IPv4 or IPv6 subnet in CIDR notation (e.g.
+`'10.0.0.0/8'` or `'2001:db8::/32'`).
+
+Removes a subnet rule using CIDR notation. The address family is automatically
+detected from the address. This is equivalent to calling
+`blockList.removeSubnet()` with the parsed network address, prefix length,
+and family. If the specified subnet does not exist, this is a no-op.
+
+### `blockList.removeRange(start, end[, type])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`start` {string|net.SocketAddress} The starting IPv4 or IPv6 address in the
+ range.
+*`end` {string|net.SocketAddress} The ending IPv4 or IPv6 address in the range.
+*`type` {string} Either `'ipv4'` or `'ipv6'`. **Default:**`'ipv4'`.
+
+Removes a rule that was previously added with `blockList.addRange()`. The `start`
+and `end` addresses must match exactly the values used when the rule was added.
+If the specified range does not exist, this is a no-op.
+
+### `blockList.removeSubnet(net, prefix[, type])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`net` {string|net.SocketAddress} The network IPv4 or IPv6 address.
+*`prefix` {number} The number of CIDR prefix bits. For IPv4, this
+ must be a value between `0` and `32`. For IPv6, this must be between
+`0` and `128`.
+*`type` {string} Either `'ipv4'` or `'ipv6'`. **Default:**`'ipv4'`.
+
+Removes a rule that was previously added with `blockList.addSubnet()`. The
+network address and prefix must match exactly the values used when the rule was
+added. If the specified subnet does not exist, this is a no-op.
+
+### `blockList.rules`
+
+<!-- YAML
+added:
+ - v15.0.0
+ - v14.18.0
+-->
+
+* Type: {string\[]}
+
+The list of rules added to the blocklist.
+
+### `blockList.size`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {number}
+
+The number of rules in the blocklist. This is equivalent to
+`blockList.rules.length` but does not allocate the rules array.
+
 ### `blockList.toJSON()`
 
 > Stability: 1.2 - Release candidate

benchmark/net/net-blocklist.js

@@ -0,0 +1,146 @@
+'use strict';
+
+constcommon=require('../common.js');
+const{ BlockList, SocketAddress }=require('net');
+
+consthasAddAddresses=typeofBlockList.prototype.addAddresses==='function';
+
+constoperations=['check','checkWithSocketAddress','addAddress'];
+if(hasAddAddresses){
+operations.push('addAddresses');
+}
+
+constbench=common.createBenchmark(main,{
+n: [1e6],
+ruleCount: [10,100,1000,10000],
+ruleType: ['address','subnet','mixed'],
+checkResult: ['hit','miss'],
+operation: operations,
+},{
+combinationFilter({ operation, ruleCount, ruleType }){
+// addAddress and addAddresses only need address rules, not subnets.
+if((operation==='addAddress'||operation==='addAddresses')&&
+ruleType!=='address'){
+returnfalse;
+}
+returntrue;
+},
+});
+
+functiongenerateIPv4(index){
+return`${(index>>>24)&0xff}.${(index>>>16)&0xff}.`+
+`${(index>>>8)&0xff}.${index&0xff}`;
+}
+
+functionbuildBlockList(ruleCount,ruleType){
+constblockList=newBlockList();
+
+if(ruleType==='address'||ruleType==='mixed'){
+constaddressCount=ruleType==='mixed' ?
+Math.floor(ruleCount/2) : ruleCount;
+constaddresses=[];
+for(leti=0;i<addressCount;i++){
+// Start from 10.0.0.1 to avoid 0.0.0.0
+addresses.push(generateIPv4(0x0a000001+i));
+}
+if(hasAddAddresses){
+blockList.addAddresses(addresses);
+}else{
+for(constaddrofaddresses){
+blockList.addAddress(addr);
+}
+}
+}
+
+if(ruleType==='subnet'||ruleType==='mixed'){
+constsubnetCount=ruleType==='mixed' ?
+Math.floor(ruleCount/2) : ruleCount;
+for(leti=0;i<subnetCount;i++){
+// Use distinct /24 subnets: 172.i.j.0/24
+constsecond=(i>>>8)&0xff;
+constthird=i&0xff;
+blockList.addSubnet(`172.${second}.${third}.0`,24);
+}
+}
+
+returnblockList;
+}
+
+functionmain({ n, ruleCount, ruleType, checkResult, operation }){
+if(operation==='check'){
+benchCheck(n,ruleCount,ruleType,checkResult);
+}elseif(operation==='checkWithSocketAddress'){
+benchCheckWithSocketAddress(n,ruleCount,ruleType,checkResult);
+}elseif(operation==='addAddress'){
+benchAddAddress(n,ruleCount);
+}elseif(operation==='addAddresses'){
+benchAddAddresses(n,ruleCount);
+}
+}
+
+// Benchmark check() with string addresses (the common JS API path).
+functionbenchCheck(n,ruleCount,ruleType,checkResult){
+constblockList=buildBlockList(ruleCount,ruleType);
+
+// For 'hit', use an address that's in the list.
+// For 'miss', use an address that's not in the list.
+constaddress=checkResult==='hit' ? '10.0.0.1' : '192.168.255.255';
+
+bench.start();
+for(leti=0;i<n;i++){
+blockList.check(address);
+}
+bench.end(n);
+}
+
+// Benchmark check() with pre-created SocketAddress objects
+// (avoids measuring SocketAddress construction overhead).
+functionbenchCheckWithSocketAddress(n,ruleCount,ruleType,checkResult){
+constblockList=buildBlockList(ruleCount,ruleType);
+
+constaddress=checkResult==='hit' ? '10.0.0.1' : '192.168.255.255';
+constsa=newSocketAddress({ address });
+
+bench.start();
+for(leti=0;i<n;i++){
+blockList.check(sa);
+}
+bench.end(n);
+}
+
+// Benchmark single addAddress() calls (one lock acquire per call).
+functionbenchAddAddress(n,ruleCount){
+// Scale n down for large rule counts to keep runtime reasonable.
+constiterations=Math.min(n,ruleCount*100);
+
+constaddresses=[];
+for(leti=0;i<ruleCount;i++){
+addresses.push(generateIPv4(0x0a000001+i));
+}
+
+bench.start();
+for(leti=0;i<iterations;i++){
+constblockList=newBlockList();
+for(letj=0;j<addresses.length;j++){
+blockList.addAddress(addresses[j]);
+}
+}
+bench.end(iterations);
+}
+
+// Benchmark batch addAddresses() (one lock acquire per batch).
+functionbenchAddAddresses(n,ruleCount){
+constiterations=Math.min(n,ruleCount*100);
+
+constaddresses=[];
+for(leti=0;i<ruleCount;i++){
+addresses.push(generateIPv4(0x0a000001+i));
+}
+
+bench.start();
+for(leti=0;i<iterations;i++){
+constblockList=newBlockList();
+blockList.addAddresses(addresses);
+}
+bench.end(iterations);
+}

doc/api/net.md

@@ -96,6 +96,47 @@ added:
 
 Adds a rule to block the given IP address.
 
+### `blockList.addAddresses(addresses[, type])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`addresses` {string\[]|net.SocketAddress\[]} An array of IPv4 or IPv6
+ addresses.
+*`type` {string} Either `'ipv4'` or `'ipv6'`. **Default:**`'ipv4'`.
+
+Adds multiple address rules to the block list in a single operation.
+This is more efficient than calling `blockList.addAddress()` repeatedly
+when adding a large number of individual addresses, as the addresses
+are inserted under a single internal lock acquisition.
+
+### `blockList.addCIDR(cidr)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`cidr` {string} An IPv4 or IPv6 subnet in CIDR notation (e.g.
+`'10.0.0.0/8'` or `'2001:db8::/32'`).
+
+Adds a subnet rule using CIDR notation. The address family is automatically
+detected from the address (IPv6 if the address contains `':'`, IPv4
+otherwise). This is equivalent to calling `blockList.addSubnet()` with
+the parsed network address, prefix length, and family.
+
+### `blockList.addCIDRs(cidrs)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`cidrs` {string\[]} An array of IPv4 or IPv6 subnets in CIDR notation.
+
+Adds multiple subnet rules using CIDR notation in a single call. The address
+family for each entry is automatically detected. This is equivalent to
+calling `blockList.addCIDR()` for each element of the array.
+
 ### `blockList.addRange(start, end[, type])`
 
 <!-- YAML
@@ -158,28 +199,13 @@ console.log(blockList.check('::ffff:7b7b:7b7b', 'ipv6')); // Prints: true
 console.log(blockList.check('::ffff:123.123.123.123', 'ipv6')); // Prints: true
 ```
 
-### `blockList.rules`
+### `blockList.clear()`
 
-<!-- YAML
-added:
- - v15.0.0
- - v14.18.0
+<!--
+added: REPLACEME
 -->
 
-* Type: {string\[]}
-
-The list of rules added to the blocklist.
-
-### `BlockList.isBlockList(value)`
-
-<!-- YAML
-added:
- - v23.4.0
- - v22.13.0
--->
-
-*`value` {any} Any JS value
-* Returns `true` if the `value` is a `net.BlockList`.
+Clears all rules from the `BlockList`.
 
 ### `blockList.fromJSON(value)`
 
@@ -205,6 +231,130 @@ blockList.fromJSON(JSON.stringify(data));
 
 *`value` Blocklist.rules
 
+### `BlockList.isBlockList(value)`
+
+<!-- YAML
+added:
+ - v23.4.0
+ - v22.13.0
+-->
+
+*`value` {any} Any JS value
+* Returns `true` if the `value` is a `net.BlockList`.
+
+### `BlockList.PRIVATE_RANGES`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {string\[]}
+
+A frozen array of CIDR strings representing private, loopback, and link-local
+IP address ranges. This can be passed to `blockList.addCIDRs()` to quickly
+populate a blocklist with all non-routable address ranges.
+
+The included ranges are:
+
+*`10.0.0.0/8` — RFC 1918 private IPv4
+*`172.16.0.0/12` — RFC 1918 private IPv4
+*`192.168.0.0/16` — RFC 1918 private IPv4
+*`127.0.0.0/8` — IPv4 loopback
+*`::1/128` — IPv6 loopback
+*`169.254.0.0/16` — IPv4 link-local
+*`fe80::/10` — IPv6 link-local
+*`fc00::/7` — IPv6 unique local (ULA)
+
+```js
+constblockList=newnet.BlockList();
+blockList.addCIDRs(net.BlockList.PRIVATE_RANGES);
+
+console.log(blockList.check('10.0.0.1')); // Prints: true
+console.log(blockList.check('127.0.0.1')); // Prints: true
+console.log(blockList.check('8.8.8.8')); // Prints: false
+```
+
+### `blockList.removeAddress(address[, type])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`address` {string|net.SocketAddress} An IPv4 or IPv6 address.
+*`type` {string} Either `'ipv4'` or `'ipv6'`. **Default:**`'ipv4'`.
+
+Removes a rule that was previously added with `blockList.addAddress()`. The
+address must match exactly the value used when the rule was added. If the
+specified address does not exist, this is a no-op.
+
+### `blockList.removeCIDR(cidr)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`cidr` {string} An IPv4 or IPv6 subnet in CIDR notation (e.g.
+`'10.0.0.0/8'` or `'2001:db8::/32'`).
+
+Removes a subnet rule using CIDR notation. The address family is automatically
+detected from the address. This is equivalent to calling
+`blockList.removeSubnet()` with the parsed network address, prefix length,
+and family. If the specified subnet does not exist, this is a no-op.
+
+### `blockList.removeRange(start, end[, type])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`start` {string|net.SocketAddress} The starting IPv4 or IPv6 address in the
+ range.
+*`end` {string|net.SocketAddress} The ending IPv4 or IPv6 address in the range.
+*`type` {string} Either `'ipv4'` or `'ipv6'`. **Default:**`'ipv4'`.
+
+Removes a rule that was previously added with `blockList.addRange()`. The `start`
+and `end` addresses must match exactly the values used when the rule was added.
+If the specified range does not exist, this is a no-op.
+
+### `blockList.removeSubnet(net, prefix[, type])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`net` {string|net.SocketAddress} The network IPv4 or IPv6 address.
+*`prefix` {number} The number of CIDR prefix bits. For IPv4, this
+ must be a value between `0` and `32`. For IPv6, this must be between
+`0` and `128`.
+*`type` {string} Either `'ipv4'` or `'ipv6'`. **Default:**`'ipv4'`.
+
+Removes a rule that was previously added with `blockList.addSubnet()`. The
+network address and prefix must match exactly the values used when the rule was
+added. If the specified subnet does not exist, this is a no-op.
+
+### `blockList.rules`
+
+<!-- YAML
+added:
+ - v15.0.0
+ - v14.18.0
+-->
+
+* Type: {string\[]}
+
+The list of rules added to the blocklist.
+
+### `blockList.size`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {number}
+
+The number of rules in the blocklist. This is equivalent to
+`blockList.rules.length` but does not allocate the rules array.
+
 ### `blockList.toJSON()`
 
 > Stability: 1.2 - Release candidate

benchmark/net/net-blocklist.js

@@ -0,0 +1,146 @@
+'use strict';
+
+constcommon=require('../common.js');
+const{ BlockList, SocketAddress }=require('net');
+
+consthasAddAddresses=typeofBlockList.prototype.addAddresses==='function';
+
+constoperations=['check','checkWithSocketAddress','addAddress'];
+if(hasAddAddresses){
+operations.push('addAddresses');
+}
+
+constbench=common.createBenchmark(main,{
+n: [1e6],
+ruleCount: [10,100,1000,10000],
+ruleType: ['address','subnet','mixed'],
+checkResult: ['hit','miss'],
+operation: operations,
+},{
+combinationFilter({ operation, ruleCount, ruleType }){
+// addAddress and addAddresses only need address rules, not subnets.
+if((operation==='addAddress'||operation==='addAddresses')&&
+ruleType!=='address'){
+returnfalse;
+}
+returntrue;
+},
+});
+
+functiongenerateIPv4(index){
+return`${(index>>>24)&0xff}.${(index>>>16)&0xff}.`+
+`${(index>>>8)&0xff}.${index&0xff}`;
+}
+
+functionbuildBlockList(ruleCount,ruleType){
+constblockList=newBlockList();
+
+if(ruleType==='address'||ruleType==='mixed'){
+constaddressCount=ruleType==='mixed' ?
+Math.floor(ruleCount/2) : ruleCount;
+constaddresses=[];
+for(leti=0;i<addressCount;i++){
+// Start from 10.0.0.1 to avoid 0.0.0.0
+addresses.push(generateIPv4(0x0a000001+i));
+}
+if(hasAddAddresses){
+blockList.addAddresses(addresses);
+}else{
+for(constaddrofaddresses){
+blockList.addAddress(addr);
+}
+}
+}
+
+if(ruleType==='subnet'||ruleType==='mixed'){
+constsubnetCount=ruleType==='mixed' ?
+Math.floor(ruleCount/2) : ruleCount;
+for(leti=0;i<subnetCount;i++){
+// Use distinct /24 subnets: 172.i.j.0/24
+constsecond=(i>>>8)&0xff;
+constthird=i&0xff;
+blockList.addSubnet(`172.${second}.${third}.0`,24);
+}
+}
+
+returnblockList;
+}
+
+functionmain({ n, ruleCount, ruleType, checkResult, operation }){
+if(operation==='check'){
+benchCheck(n,ruleCount,ruleType,checkResult);
+}elseif(operation==='checkWithSocketAddress'){
+benchCheckWithSocketAddress(n,ruleCount,ruleType,checkResult);
+}elseif(operation==='addAddress'){
+benchAddAddress(n,ruleCount);
+}elseif(operation==='addAddresses'){
+benchAddAddresses(n,ruleCount);
+}
+}
+
+// Benchmark check() with string addresses (the common JS API path).
+functionbenchCheck(n,ruleCount,ruleType,checkResult){
+constblockList=buildBlockList(ruleCount,ruleType);
+
+// For 'hit', use an address that's in the list.
+// For 'miss', use an address that's not in the list.
+constaddress=checkResult==='hit' ? '10.0.0.1' : '192.168.255.255';
+
+bench.start();
+for(leti=0;i<n;i++){
+blockList.check(address);
+}
+bench.end(n);
+}
+
+// Benchmark check() with pre-created SocketAddress objects
+// (avoids measuring SocketAddress construction overhead).
+functionbenchCheckWithSocketAddress(n,ruleCount,ruleType,checkResult){
+constblockList=buildBlockList(ruleCount,ruleType);
+
+constaddress=checkResult==='hit' ? '10.0.0.1' : '192.168.255.255';
+constsa=newSocketAddress({ address });
+
+bench.start();
+for(leti=0;i<n;i++){
+blockList.check(sa);
+}
+bench.end(n);
+}
+
+// Benchmark single addAddress() calls (one lock acquire per call).
+functionbenchAddAddress(n,ruleCount){
+// Scale n down for large rule counts to keep runtime reasonable.
+constiterations=Math.min(n,ruleCount*100);
+
+constaddresses=[];
+for(leti=0;i<ruleCount;i++){
+addresses.push(generateIPv4(0x0a000001+i));
+}
+
+bench.start();
+for(leti=0;i<iterations;i++){
+constblockList=newBlockList();
+for(letj=0;j<addresses.length;j++){
+blockList.addAddress(addresses[j]);
+}
+}
+bench.end(iterations);
+}
+
+// Benchmark batch addAddresses() (one lock acquire per batch).
+functionbenchAddAddresses(n,ruleCount){
+constiterations=Math.min(n,ruleCount*100);
+
+constaddresses=[];
+for(leti=0;i<ruleCount;i++){
+addresses.push(generateIPv4(0x0a000001+i));
+}
+
+bench.start();
+for(leti=0;i<iterations;i++){
+constblockList=newBlockList();
+blockList.addAddresses(addresses);
+}
+bench.end(iterations);
+}

doc/api/net.md

@@ -96,6 +96,47 @@ added:
 
 Adds a rule to block the given IP address.
 
+### `blockList.addAddresses(addresses[, type])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`addresses` {string\[]|net.SocketAddress\[]} An array of IPv4 or IPv6
+ addresses.
+*`type` {string} Either `'ipv4'` or `'ipv6'`. **Default:**`'ipv4'`.
+
+Adds multiple address rules to the block list in a single operation.
+This is more efficient than calling `blockList.addAddress()` repeatedly
+when adding a large number of individual addresses, as the addresses
+are inserted under a single internal lock acquisition.
+
+### `blockList.addCIDR(cidr)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`cidr` {string} An IPv4 or IPv6 subnet in CIDR notation (e.g.
+`'10.0.0.0/8'` or `'2001:db8::/32'`).
+
+Adds a subnet rule using CIDR notation. The address family is automatically
+detected from the address (IPv6 if the address contains `':'`, IPv4
+otherwise). This is equivalent to calling `blockList.addSubnet()` with
+the parsed network address, prefix length, and family.
+
+### `blockList.addCIDRs(cidrs)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`cidrs` {string\[]} An array of IPv4 or IPv6 subnets in CIDR notation.
+
+Adds multiple subnet rules using CIDR notation in a single call. The address
+family for each entry is automatically detected. This is equivalent to
+calling `blockList.addCIDR()` for each element of the array.
+
 ### `blockList.addRange(start, end[, type])`
 
 <!-- YAML
@@ -158,28 +199,13 @@ console.log(blockList.check('::ffff:7b7b:7b7b', 'ipv6')); // Prints: true
 console.log(blockList.check('::ffff:123.123.123.123', 'ipv6')); // Prints: true
 ```
 
-### `blockList.rules`
+### `blockList.clear()`
 
-<!-- YAML
-added:
- - v15.0.0
- - v14.18.0
+<!--
+added: REPLACEME
 -->
 
-* Type: {string\[]}
-
-The list of rules added to the blocklist.
-
-### `BlockList.isBlockList(value)`
-
-<!-- YAML
-added:
- - v23.4.0
- - v22.13.0
--->
-
-*`value` {any} Any JS value
-* Returns `true` if the `value` is a `net.BlockList`.
+Clears all rules from the `BlockList`.
 
 ### `blockList.fromJSON(value)`
 
@@ -205,6 +231,130 @@ blockList.fromJSON(JSON.stringify(data));
 
 *`value` Blocklist.rules
 
+### `BlockList.isBlockList(value)`
+
+<!-- YAML
+added:
+ - v23.4.0
+ - v22.13.0
+-->
+
+*`value` {any} Any JS value
+* Returns `true` if the `value` is a `net.BlockList`.
+
+### `BlockList.PRIVATE_RANGES`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {string\[]}
+
+A frozen array of CIDR strings representing private, loopback, and link-local
+IP address ranges. This can be passed to `blockList.addCIDRs()` to quickly
+populate a blocklist with all non-routable address ranges.
+
+The included ranges are:
+
+*`10.0.0.0/8` — RFC 1918 private IPv4
+*`172.16.0.0/12` — RFC 1918 private IPv4
+*`192.168.0.0/16` — RFC 1918 private IPv4
+*`127.0.0.0/8` — IPv4 loopback
+*`::1/128` — IPv6 loopback
+*`169.254.0.0/16` — IPv4 link-local
+*`fe80::/10` — IPv6 link-local
+*`fc00::/7` — IPv6 unique local (ULA)
+
+```js
+constblockList=newnet.BlockList();
+blockList.addCIDRs(net.BlockList.PRIVATE_RANGES);
+
+console.log(blockList.check('10.0.0.1')); // Prints: true
+console.log(blockList.check('127.0.0.1')); // Prints: true
+console.log(blockList.check('8.8.8.8')); // Prints: false
+```
+
+### `blockList.removeAddress(address[, type])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`address` {string|net.SocketAddress} An IPv4 or IPv6 address.
+*`type` {string} Either `'ipv4'` or `'ipv6'`. **Default:**`'ipv4'`.
+
+Removes a rule that was previously added with `blockList.addAddress()`. The
+address must match exactly the value used when the rule was added. If the
+specified address does not exist, this is a no-op.
+
+### `blockList.removeCIDR(cidr)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`cidr` {string} An IPv4 or IPv6 subnet in CIDR notation (e.g.
+`'10.0.0.0/8'` or `'2001:db8::/32'`).
+
+Removes a subnet rule using CIDR notation. The address family is automatically
+detected from the address. This is equivalent to calling
+`blockList.removeSubnet()` with the parsed network address, prefix length,
+and family. If the specified subnet does not exist, this is a no-op.
+
+### `blockList.removeRange(start, end[, type])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`start` {string|net.SocketAddress} The starting IPv4 or IPv6 address in the
+ range.
+*`end` {string|net.SocketAddress} The ending IPv4 or IPv6 address in the range.
+*`type` {string} Either `'ipv4'` or `'ipv6'`. **Default:**`'ipv4'`.
+
+Removes a rule that was previously added with `blockList.addRange()`. The `start`
+and `end` addresses must match exactly the values used when the rule was added.
+If the specified range does not exist, this is a no-op.
+
+### `blockList.removeSubnet(net, prefix[, type])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`net` {string|net.SocketAddress} The network IPv4 or IPv6 address.
+*`prefix` {number} The number of CIDR prefix bits. For IPv4, this
+ must be a value between `0` and `32`. For IPv6, this must be between
+`0` and `128`.
+*`type` {string} Either `'ipv4'` or `'ipv6'`. **Default:**`'ipv4'`.
+
+Removes a rule that was previously added with `blockList.addSubnet()`. The
+network address and prefix must match exactly the values used when the rule was
+added. If the specified subnet does not exist, this is a no-op.
+
+### `blockList.rules`
+
+<!-- YAML
+added:
+ - v15.0.0
+ - v14.18.0
+-->
+
+* Type: {string\[]}
+
+The list of rules added to the blocklist.
+
+### `blockList.size`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {number}
+
+The number of rules in the blocklist. This is equivalent to
+`blockList.rules.length` but does not allocate the rules array.
+
 ### `blockList.toJSON()`
 
 > Stability: 1.2 - Release candidate