feat(rate-limiter): pluggable algorithms, tenant isolation fix, and scale load test

- Add pluggable algorithm strategy: fixed_window, sliding_window, token_bucket
- Add Redis backend for shared cross-instance rate limiting
- Fix tenant isolation: skip by_tenant when tenant_id is None
- Fix sliding window: sweep expired timestamps before counting
- Fix backend validation: restore _validate_config check
- Fix token bucket memory path: apply max(1,...) guard to reset timestamp
- Add Redis integration tests for all three algorithms
- Add direct regression tests for get_current_user tenant_id fallback
- Add scale load test with Redis memory timeline and live algorithm detection
- Add RL_PACE_MULTIPLIER for near-limit pace testing and boundary burst detection
- Remove redundant algorithm locustfile; scale file is canonical
- Correct stale comments and README limitations

Signed-off-by: Pratik Gandhi <gandhipratik203@gmail.com>

Author: gandhipratik203

Makefile

@@ -2320,7 +2320,11 @@ load-test-agentgateway-mcp-server-time:    ## Load test external MCP server (loc
 # help: load-test-mcp-protocol-heavy - MCP-only protocol heavy test (500 users, 5min)
 
 MCP_PROTOCOL_LOCUSTFILE ?= tests/loadtest/locustfile_mcp_protocol.py
-MCP_RATE_LIMITER_LOCUSTFILE ?= tests/loadtest/locustfile_rate_limiter.py
+MCP_RATE_LIMITER_LOCUSTFILE ?= tests/loadtest/locustfile_rate_limiter_backend_correctness.py
+MCP_RATE_LIMITER_SCALE_LOCUSTFILE ?= tests/loadtest/locustfile_rate_limiter_scale.py
+RL_ALGORITHM ?= fixed_window
+RL_USERS ?= 100
+RL_SPAWN_RATE ?= 10
 MCP_PROTOCOL_HOST ?= http://localhost:4444
 MCP_BENCHMARK_HOST ?= http://localhost:8080
 MCP_BENCHMARK_SERVER_ID ?= 9779b6698cbd4b4995ee04a4fab38737
@@ -2437,6 +2441,40 @@ benchmark-rate-limiter:                     ## Rate limiter correctness test (1
 			--only-summary \
 			RateLimitedUser || true'
 
+
+# help: benchmark-rate-limiter-scale  - Multi-user scale test showing Redis memory divergence across algorithms
+.PHONY: benchmark-rate-limiter-scale
+RL_RUN_TIME ?= 300s
+benchmark-rate-limiter-scale:               ## Scale test: 500 unique users, Redis memory timeline per algorithm
+	@echo "📈 Running rate limiter scale test (resource divergence)..."
+	@echo "   Algorithm: $(RL_ALGORITHM)  (must match plugins/config.yaml)"
+	@echo "   Users:     $(RL_USERS) unique identities  (each creates own Redis key)"
+	@echo "   Spawn:     $(RL_SPAWN_RATE) users/s"
+	@echo "   Limit:     $(RL_LIMIT_PER_MIN) req/min per user"
+	@echo "   Duration:  $(RL_RUN_TIME)  (includes ~40s bootstrap for user registration)"
+	@echo ""
+	@echo "   Redis memory diverges between algorithms as users ramp up:"
+	@echo "     fixed_window:   ~0.1-0.3 KiB/key  (single integer)"
+	@echo "     sliding_window: ~1-3 KiB/key       (sorted set, $(RL_LIMIT_PER_MIN) entries)"
+	@echo "     token_bucket:   ~0.2 KiB/key       (hash: tokens + last_refill)"
+	@test -d "$(VENV_DIR)" || $(MAKE) venv
+	@/bin/bash -eu -o pipefail -c 'source $(VENV_DIR)/bin/activate && \
+		LOCUST_LOG_LEVEL=ERROR \
+		RL_ALGORITHM=$(RL_ALGORITHM) \
+		RL_LIMIT_PER_MIN=$(RL_LIMIT_PER_MIN) \
+		RL_USERS=$(RL_USERS) \
+		RL_SPAWN_RATE=$(RL_SPAWN_RATE) \
+		RL_RUN_TIME=$(RL_RUN_TIME) \
+		MCP_SERVER_ID=$(MCP_BENCHMARK_SERVER_ID) \
+		locust -f $(MCP_RATE_LIMITER_SCALE_LOCUSTFILE) \
+			--host=$(MCP_BENCHMARK_HOST) \
+			--users=$(RL_USERS) \
+			--spawn-rate=$(RL_SPAWN_RATE) \
+			--run-time=$(RL_RUN_TIME) \
+			--headless \
+			--only-summary \
+			ScaleComparisonUser || true'
+
 .PHONY: benchmark-mcp-mixed-300
 benchmark-mcp-mixed-300:                    ## Distributed 300-user mixed MCP benchmark
 	@echo "📊 Running distributed mixed MCP benchmark..."

docs/docs/using/plugins/plugins.md

@@ -40,7 +40,7 @@ Plugins for improving system reliability, performance, and resource management.
 |--------|------|-------------|
 | [Circuit Breaker](https://github.com/IBM/mcp-context-forge/tree/main/plugins/circuit_breaker) | Native | Trips per-tool breaker on high error rates or consecutive failures and blocks during cooldown |
 | [Watchdog](https://github.com/IBM/mcp-context-forge/tree/main/plugins/watchdog) | Native | Enforces maximum runtime for tools with warn or block actions on threshold violations |
-| [Rate Limiter](https://github.com/IBM/mcp-context-forge/tree/main/plugins/rate_limiter) | Native | Fixed-window in-memory rate limiting by user, tenant, or tool |
+| [Rate Limiter](https://github.com/IBM/mcp-context-forge/tree/main/plugins/rate_limiter) | Native | Per-user, tenant, and tool rate limiting with selectable algorithms (fixed_window, sliding_window, token_bucket) and memory or Redis backends |
 | [Cached Tool Result](https://github.com/IBM/mcp-context-forge/tree/main/plugins/cached_tool_result) | Native | Caches idempotent tool results in-memory with configurable TTL and key fields |
 | [Response Cache by Prompt](https://github.com/IBM/mcp-context-forge/tree/main/plugins/response_cache_by_prompt) | Native | Advisory response cache using cosine similarity over prompt/input fields with configurable threshold |
 | [Retry with Backoff](https://github.com/IBM/mcp-context-forge/tree/main/plugins/retry_with_backoff) | Native | Annotates retry/backoff policy in metadata with exponential backoff on specific HTTP status codes |

mcpgateway/auth.py

@@ -998,11 +998,12 @@ async def _set_auth_method_from_payload(payload: dict) -> None:
             # Get plugin contexts from request state if available
             global_context = getattr(request.state, "plugin_global_context", None) if request else None
             if not global_context:
-                # Create global context
+                # Propagate team_id → tenant_id for by_tenant rate limiting
+                team_id = getattr(getattr(request, "state", None), "team_id", None) if request else None
                 global_context = GlobalContext(
                     request_id=request_id,
                     server_id=None,
-                    tenant_id=None,
+                    tenant_id=team_id,
                 )
 
             context_table = getattr(request.state, "plugin_context_table", None) if request else None
@@ -1532,5 +1533,11 @@ def _inject_userinfo_instate(request: Optional[object] = None, user: Optional[Em
         global_context.user["is_admin"] = user.is_admin
         global_context.user["full_name"] = user.full_name
 
+    # Propagate team_id → tenant_id for by_tenant rate limiting (only when not already set)
+    if request and global_context.tenant_id is None:
+        team_id = getattr(getattr(request, "state", None), "team_id", None)
+        if team_id:
+            global_context.tenant_id = team_id
+
     if request and global_context:
         request.state.plugin_global_context = global_context

plugins/config.yaml

@@ -222,6 +222,7 @@ plugins:
       redis_url: "redis://redis:6379/0"
       redis_key_prefix: "rl"
       redis_fallback: true
+      algorithm: "fixed_window"
       by_user: "30/m"
       by_tenant: "3000/m"
       by_tool: {}

plugins/rate_limiter/README.md

@@ -3,7 +3,7 @@
 > Author: Mihai Criveti
 > Version: 0.1.0
 
-Enforces fixed-window rate limits per user, tenant, and tool across `tool_pre_invoke` and `prompt_pre_fetch` hooks. Supports an in-process memory backend (single-instance) and a Redis backend (shared across all gateway instances).
+Enforces rate limits per user, tenant, and tool across `tool_pre_invoke` and `prompt_pre_fetch` hooks. Supports pluggable counting algorithms (fixed window, sliding window, token bucket), an in-process memory backend (single-instance), and a Redis backend (shared across all gateway instances).
 
 ## Hooks
 
@@ -32,6 +32,9 @@ If any configured dimension is exceeded, the plugin returns a violation with HTT
       search: "10/m"
       summarise: "5/m"
 
+    # Algorithm — choose one (default: fixed_window)
+    algorithm: "fixed_window"    # fixed_window | sliding_window | token_bucket
+
     # Backend — choose one
     backend: "memory"    # default: single-process, resets on restart
     # backend: "redis"   # shared across all gateway instances
@@ -49,6 +52,7 @@ If any configured dimension is exceeded, the plugin returns a violation with HTT
 | `by_user` | string | `null` | Per-user rate limit, e.g. `"60/m"` |
 | `by_tenant` | string | `null` | Per-tenant rate limit, e.g. `"600/m"` |
 | `by_tool` | dict | `{}` | Per-tool overrides, e.g. `{"search": "10/m"}` |
+| `algorithm` | string | `"fixed_window"` | Counting algorithm: `"fixed_window"`, `"sliding_window"`, or `"token_bucket"` |
 | `backend` | string | `"memory"` | `"memory"` or `"redis"` |
 | `redis_url` | string | `null` | Redis connection URL (required when `backend: redis`) |
 | `redis_key_prefix` | string | `"rl"` | Prefix for all Redis keys |
@@ -69,18 +73,44 @@ Every request (allowed or blocked) includes:
 | `X-RateLimit-Reset` | Unix timestamp when the current window resets |
 | `Retry-After` | Seconds until the window resets (blocked requests only) |
 
+## Algorithms
+
+Three counting algorithms are available, selected via the `algorithm` config field.
+
+| Algorithm | Config value | Best for | Trade-off |
+|---|---|---|---|
+| Fixed window | `fixed_window` | General use, lowest overhead | Up to 2× the limit at window boundaries |
+| Sliding window | `sliding_window` | Smooth enforcement, no boundary burst | Higher memory: stores one timestamp per request per key |
+| Token bucket | `token_bucket` | Bursty workloads — allows short spikes up to capacity | Slightly higher Redis overhead: stores `{tokens, last_refill}` hash per key |
+
+### Fixed window (default)
+
+Counts requests in a fixed time slot (e.g. "minute 14:03"). Resets at the slot boundary. Simple and fast. The 2× burst at a boundary (N requests at the end of slot T, N requests at the start of T+1) is a known trade-off; use `by_user` with headroom if this matters.
+
+### Sliding window
+
+Stores a timestamp for every request in the current window. At each check, expired timestamps are discarded and the remaining count is compared against the limit. Prevents boundary bursts entirely. Memory usage grows with request volume — roughly one float per request per active key.
+
+### Token bucket
+
+Each identity (user, tenant, tool) has a bucket that holds up to `count` tokens. Tokens refill at a steady rate of `count/window`. A request consumes one token. Bursts up to the bucket capacity are allowed; sustained rate above `count/window` is rejected. Useful for APIs where short spikes are acceptable but sustained overload is not.
+
+**Redis support:** `token_bucket` with `backend: redis` is fully supported. The plugin stores `{tokens, last_refill}` in a Redis hash per key and uses an atomic Lua script to refill and consume tokens in a single round-trip — the same pattern as the other two algorithms. This means `token_bucket` enforces a true cluster-wide limit in multi-instance deployments.
+
 ## Backends
 
 ### Memory backend (default)
 
 - Counters are stored in a process-local dict (`_store`)
 - An `asyncio.Lock` serialises all counter reads and writes — safe under concurrent asyncio tasks
-- A background sweep task evicts expired windows every 0.5s — memory is bounded to active windows only
+- A background sweep task evicts expired windows every 0.5s — for `fixed_window` and `token_bucket`, expired entries are removed promptly; for `sliding_window`, keys with fully stale timestamps are evicted by the sweep
 - **Limitation:** state is not shared across processes or hosts. In a multi-instance deployment (e.g. 3 gateway instances behind nginx), each instance tracks its own counter — the effective limit is `N × configured_limit`
 
 ### Redis backend
 
-- Counters are stored in Redis using an atomic Lua `INCR`+`EXPIRE` script — a single Redis call per check with no race condition
+- `fixed_window`: atomic Lua `INCR`+`EXPIRE` — one Redis round-trip per check, no race condition
+- `sliding_window`: atomic Lua `ZADD`+`ZREMRANGEBYSCORE`+`ZCARD`+`EXPIRE` — one round-trip, no race condition
+- `token_bucket`: atomic Lua script — reads `{tokens, last_refill}` hash, refills proportionally, consumes 1 token, writes back — one round-trip, no race condition
 - All gateway instances share the same counter — the configured limit is the true cluster-wide limit
 - Requires `redis_url` to be set
 - If `redis_fallback: true` (default) and Redis is unavailable, the plugin falls back to the in-process `MemoryBackend` automatically — requests are never blocked due to Redis downtime
@@ -111,6 +141,34 @@ config:
     search: "10/m"
 ```
 
+### Sliding window (no boundary bursts)
+
+```yaml
+config:
+  algorithm: "sliding_window"
+  by_user: "30/m"
+  by_tenant: "300/m"
+```
+
+### Token bucket — memory backend (default)
+
+```yaml
+config:
+  algorithm: "token_bucket"
+  by_user: "30/m"   # bucket holds 30 tokens, refills at 30/min
+```
+
+### Token bucket — Redis backend (multi-instance)
+
+```yaml
+config:
+  algorithm: "token_bucket"
+  backend: "redis"
+  redis_url: "redis://redis:6379/0"
+  redis_fallback: true
+  by_user: "30/m"
+```
+
 ### Permissive mode (observe without blocking)
 
 ```yaml
@@ -126,7 +184,9 @@ In `permissive` mode the plugin records violations and emits `X-RateLimit-*` hea
 | Limitation | Severity | Status |
 |---|---|---|
 | Memory backend not shared across processes | HIGH | Use Redis backend for multi-instance deployments |
-| Fixed window allows up to 2× limit at window boundary | LOW | Deferred — use `by_user` with headroom as a workaround |
+| Fixed window allows up to 2× limit at window boundary | LOW | Use `sliding_window` algorithm, or use `by_user` with headroom |
+| `by_tool` matching is case-sensitive | LOW | Fixed — tool names are now normalised with `.strip().lower()` at init |
+| Whitespace-only user identity bypasses anonymous bucket | LOW | Documented gap; strip identities before passing to hooks |
 | No per-server limits (`server_id` dimension missing) | LOW | Not implemented |
 | No config hot-reload — rate string changes require restart | LOW | Not implemented |
 | Memory backend not safe under threaded workers (gunicorn `--threads`) | LOW | asyncio.Lock is loop-safe; use async workers (`-k uvicorn`) |