feat: gate subnet blocks on minimum unique-IP count with fraction/absolute threshold support

[chinrichs-godaddy]

Summary

• New behaviour: A subnet is only blocked when a configurable minimum number of distinct source IPs have been observed within it, preventing a single abusive IP from triggering a block for its entire /24 (or whatever subnetMaskBits is set to).
• New option minSubnetUniqueIps (default 0.5): accepts a fraction (0, 1) — resolved as a percentage of the subnet's host count — or an absolute count ≥ 1. 0.5 on a /24 requires 128 unique IPs before the subnet can be blocked. Set to 1 to restore legacy behaviour.
• New cluster option clusterMinSubnetUniqueIps (default 0.5): same fraction/absolute semantics as the local option. Cluster nodes publish per-subnet unique-IP counts to Redis via ZADD GT (max across nodes), and readThresholds gates subnet blocks on both the rate threshold and this count. The sliding window uses max(current, floor(prev × prevWeight)) for continuity at window boundaries.
• Both options are resolved to absolute integers inside the ConnectQOS constructor via the new resolveUniqueIpThreshold helper. Metrics and ClusterSync always receive integers.
• The local gate uses a "skip if count=0" design: direct isBadSubnet(subnetString) calls (no request context, so no IP timestamps populated) fall through to rate-only evaluation, preserving backward compatibility.

Changes

File	What changed
src/metrics.ts	Added minSubnetUniqueIps option, #subnetIpTimestamps LRU, getSubnetUniqueIpCount(), updated OnTrackFn signature to pass optional ip
src/connect.ts	Added resolveUniqueIpThreshold() helper, wired minSubnetUniqueIps defaults, added unique-IP gate in getSubnetStatus, passes ip through trackRequest → trackSubnet → onTrack → ClusterSync.recordHit
src/cluster.ts	Added clusterMinSubnetUniqueIps option, #subnetIpSets per-window tracking, ZADD GT publish, two extra zrangebyscore reads in readThresholds, isSubnetUniqueIpThresholdMet(), stale key cleanup
README.md	Documented both new options with fraction/absolute semantics in the main Options list and Cluster Options table
test/metrics.test.ts	Updated onTrack subnet test; added 4 tests for getSubnetUniqueIpCount
test/connect.test.ts	Added minSubnetUniqueIps: 1 to existing subnet tests; added 2 new scenario tests
test/cluster.test.ts	Added zadd to mock pipeline; added 3 new tests for ZADD GT publish and readThresholds gating

Test plan

• npm test — 126 tests pass, 0 failures
• Verified: single-IP flood does not trigger subnet block when minSubnetUniqueIps > 1
• Verified: subnet block fires once threshold unique IPs are observed
• Verified: stale IPs (beyond maxAge) are not counted
• Verified: cluster ZADD GT published with correct count per subnet per window
• Verified: cluster gate prevents block when unique IP count < threshold
• Verified: cluster gate allows block when both rate and unique IP threshold are met
• Verified: clusterMinSubnetUniqueIps: 1 disables gate (existing cluster subnet test unchanged)
• All existing subnet tests pass with minSubnetUniqueIps: 1 (legacy behaviour preserved)

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR introduces a “minimum unique source IPs per subnet” gate for subnet blocking (local and cluster modes) to avoid blocking an entire subnet due to a single abusive IP, with the threshold configurable as either a fraction of subnet size or an absolute count.

Changes:

• Adds local unique-IP tracking in Metrics and gates ConnectQOS subnet blocking on a resolved integer minSubnetUniqueIps threshold.
• Adds cluster-wide unique-IP aggregation (published via Redis ZADD GT) and gates cluster subnet blocks on both rate threshold and unique-IP count.
• Updates documentation and expands test coverage for the new behavior and Redis publish/read logic.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/metrics.ts	Adds minSubnetUniqueIps, per-subnet IP last-seen tracking, and getSubnetUniqueIpCount(); extends onTrack signature.
src/connect.ts	Resolves unique-IP thresholds, wires through IP context, and adds unique-IP gating for subnet status and cluster subnet blocks.
src/cluster.ts	Tracks/publishes per-subnet unique-IP counts and gates subnet blocking on unique-IP threshold during readThresholds().
README.md	Documents minSubnetUniqueIps and clusterMinSubnetUniqueIps with fraction/absolute semantics.
test/metrics.test.ts	Updates onTrack expectations and adds getSubnetUniqueIpCount() tests.
test/connect.test.ts	Adjusts existing subnet tests for legacy behavior and adds new unique-IP gating scenarios.
test/cluster.test.ts	Extends Redis mocks and adds tests for ZADD GT publish and read-time gating.

Comments suppressed due to low confidence (1)

src/connect.ts:353

• When callers use isBadSubnet(req) / getSubnetStatus(req) (i.e., a request object), the code resolves the subnet from the request IP but does not pass that IP into Metrics.trackSubnet(...). This means the unique-IP gate won’t collect per-IP timestamps for this API surface, and subnets can still be blocked by a single abusive IP even when minSubnetUniqueIps > 1.

    if (track && status === ActorStatus.Good) {
      // only track if we're NOT throttling
      // forward cache to avoid additional lookup
      this.#metrics.trackSubnet(sourceStr, sourceInfo as CacheItem);

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

src/cluster.ts:333

• The new per-window subnet_ips sorted sets are never trimmed to maxTrackedActors, unlike the other window ZSETs. In a multi-node cluster, each node can contribute different subnet members, so subnet_ips:w{n} can grow without bound for the duration of a window and increase Redis memory usage / read costs in readThresholds. Consider trimming subnet_ips with ZREMRANGEBYRANK using the same trimIndex logic as the other actor ZSETs (for each published window key).

    // Publish unique IP counts per subnet using ZADD GT so Redis retains the maximum
    // across all nodes. Publish under each window's own key so data is not lost when
    // sync() fires after a window boundary with no intervening recordHit() call.
    if (this.#clusterMinSubnetUniqueIps > 1 && this.#clusterMaxSubnetRate > 0 && this.#subnetIpSetsByWindow.size > 0) {
      for (const [w, windowSets] of this.#subnetIpSetsByWindow) {
        for (const [subnet, ipSet] of windowSets) {
          pipe.zadd(this.#subnetIpsKey(w), 'GT', ipSet.size, subnet);
        }
      }
    }

    // Trim sorted sets to maxTrackedActors (keep highest scores = top offenders).
    // Only trim types with active deltas — no unnecessary pipeline commands for idle types.
    // When the set has fewer than maxTrackedActors entries, ZREMRANGEBYRANK resolves
    // stop to a negative index that underflows past the start and is a no-op per Redis spec.
    const trimIndex = -(this.#maxTrackedActors + 1);
    if (ipDeltas.size > 0) pipe.zremrangebyrank(this.#windowKey('ip', win), 0, trimIndex);
    if (subnetDeltas.size > 0) pipe.zremrangebyrank(this.#windowKey('subnet', win), 0, trimIndex);
    if (hostDeltas.size > 0) pipe.zremrangebyrank(this.#windowKey('host', win), 0, trimIndex);

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.