feat(rate-limiter): wipe Redis counter state on disable transition

[gandhipratik203]

Summary

Closes IBM/mcp-context-forge#4576 — sub-issue of #4514 (rate-limiter runtime mode-toggle convergence).

When an operator flips the rate limiter to mode: disabled at runtime, the plugin now clears its accumulated counter state from Redis. Previously the counters survived the toggle, so an immediate re-enable (or a stale-mode worker still serving traffic) would block legitimate requests on counter values inherited from before the disable. After this change, disabled truly means "the limiter's effect is gone" — and re-enable starts every user with a fresh window.

Bumps cpex_rate_limiter 0.0.4 → 0.0.6.

---

What changes

When RateLimiterPlugin.shutdown() runs, the plugin reads plugin:<name>:mode from Redis. If the value is disabled, the plugin acquires a distributed single-flight lock (<prefix>-wipe-lock, 30s TTL safety net), runs SCAN + UNLINK over its configured redis_key_prefix, and releases the lock. The wipe is bounded to keys under the plugin's configured prefix; nothing outside that namespace is touched.

The mechanism piggybacks on the framework's existing reload_tenant path: when publish_plugin_mode_change("<name>", "disabled") lands, every gateway worker's invalidation listener fires factory.invalidate_all() → reload_tenant per cached context → manager.shutdown() → plugin.shutdown(). Single-flight via the lock ensures the SCAN+UNLINK runs once across the cluster, even if N workers all process the broadcast simultaneously.

---

Test coverage

TestWipeOnDisable class — 10 tests in tests/rate_limiter/test_redis_integration.py:

Test	Target
test_wipe_fires_when_mode_key_says_disabled	Happy path
test_no_wipe_when_mode_key_says_enforce	Graceful pod restart safety
test_no_wipe_when_mode_key_absent	Fresh-deploy / no-mode-key safety
test_no_wipe_when_redis_unreachable_for_mode_lookup	Fail-safe on Redis outage
test_wipe_is_idempotent_under_concurrent_shutdown	5-instance parallel shutdown converges
test_core_shutdown_runs_even_when_wipe_raises	Wipe failure doesn't leak Redis connections
test_wipe_skipped_when_another_worker_holds_lock	Distributed single-flight
test_wipe_only_deletes_keys_under_configured_prefix	Blast radius confined to configured prefix
test_full_toggle_journey_enforce_disable_reenforce	Single-instance journey: saturated user is no longer blocked after cycle
test_full_toggle_journey_across_multiple_instances	N=3 parallel instances: every user gets a fresh window after re-enable, not just the lock-winner's

Full local gate

cargo fmt -- --check                  clean
cargo clippy -- -D warnings           clean
make test-unit                        Rust tests: 58 passed
make test-integration                 pytest: 66 passed

---

Deployment caveats (worth knowing before merge)

Two pre-conditions for the wipe path to actually fire — intrinsic properties of how the wipe interacts with the framework's plugin lifecycle, worth flagging so operators aren't surprised at start-up:

1. Plugin must be loaded for the wipe to fire. When plugins/config.yaml has mode: "disabled" for the plugin from startup, the framework loader does not instantiate the plugin under any cached manager. No plugin instance ⇒ no shutdown to fire ⇒ no wipe path to run, regardless of how many subscribers receive the broadcast. In practice this means: the wipe only takes effect after the plugin has been in enforce mode at least once.
2. At least one cached manager required. factory.invalidate_all() iterates only cached managers; a fresh gateway with zero traffic has zero cached managers. The first request through the gateway warms a manager; subsequent toggle broadcasts then have something to act on.

Neither caveat affects production deployments after the first request. Both are worth documenting on the rate-limiter README so operators understand the start-up timing.

---

Migration notes

• No new required config. Existing deployments work unchanged. The wipe fires automatically on the disable transition.
• redis_key_prefix is the blast-radius boundary. If multiple rate-limiter instances share one Redis and use the same prefix, a disable on any one wipes counters for all. Default prefix is "rl"; operators with multiple limiters should set distinct prefixes.