wred-ratelimit 0.1.0__tar.gz

wred_ratelimit-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,47 @@
+name: Tests
+
+on: [push, pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - python: "3.11"
+            dependencies: minimum
+          - python: "3.11"
+            dependencies: latest
+          - python: "3.14"
+            dependencies: latest
+    services:
+      redis:
+        image: redis:7-alpine
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 5s
+          --health-timeout 3s
+          --health-retries 10
+    env:
+      WRED_TEST_REDIS: redis://localhost:6379/15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install Redis for isolated restart test
+        run: sudo apt-get update && sudo apt-get install -y redis-server
+      - name: Install supported minimum dependencies
+        if: matrix.dependencies == 'minimum'
+        run: python -m pip install -e '.[test,redis]' 'limits==4.2.0' 'redis==5.2.0'
+      - name: Install latest compatible dependencies
+        if: matrix.dependencies == 'latest'
+        run: python -m pip install -e '.[test,redis]'
+      - run: python -m pytest -q

wred_ratelimit-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+.coverage

wred_ratelimit-0.1.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Harrison Erd
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

wred_ratelimit-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: wred-ratelimit
+Version: 0.1.0
+Summary: Optional ratelimit integration for Wred
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Requires-Dist: wred>=0.13,<0.14
+Requires-Dist: limits>=4.2,<6
+Requires-Dist: redis>=5.2 ; extra == "redis"
+Requires-Dist: pytest>=8 ; extra == "test"
+Requires-Dist: pytest-asyncio>=0.24 ; extra == "test"
+Requires-Dist: httpx>=0.27 ; extra == "test"
+Provides-Extra: redis
+Provides-Extra: test
+
+# wred-ratelimit
+
+Async per-handler quotas using `limits`. Python 3.11+, Wred 0.13.
+
+```sh
+pip install '.[redis]'
+```
+
+```python
+from wred import App
+from wred_ratelimit import Limiter
+
+app = App()
+limiter = Limiter.redis("redis://localhost:6379/0", namespace="orders-api")
+
+
+@app.route("/orders/{order_id}")
+@limiter.limit("30/minute")
+async def order(request, order_id):
+    return {"id": order_id}
+```
+
+`Limiter(storage=None, namespace='wred', strategy='moving', key=client_ip,
+fail_open=False, timeout=0.5)` uses an in-process store unless provided a limits
+async store. Choose `moving` or `fixed` windows. The memory store belongs to each
+limiter instance; use shared Redis for quotas across workers. All workers must
+share a namespace, Redis database, bucket, and rule for shared quotas.
+
+`Limiter.redis(url, storage_options=None, **options)` configures redis-py.
+`options` configure the limiter; `storage_options` configure the limits Redis
+storage and its client. Requires `limits>=4.2` and `redis>=5.2`.
+
+```python
+limiter = Limiter.redis(
+    "redis://localhost:6379/0",
+    namespace="orders-api",
+    timeout=0.15,  # total storage budget per admission/check, in seconds
+    storage_options={
+        "socket_connect_timeout": 0.1,
+        "socket_timeout": 0.1,
+        "max_connections": 50,  # per limiter instance, normally per worker
+    },
+)
+```
+
+Defaults are a 0.5-second total storage deadline, 0.2-second connect/read timeouts,
+100 connections per pool, and no automatic command retries. Tune these to your
+application's latency and concurrency budget. Redis URL query parameters take
+precedence over equivalent client options. A supplied `connection_pool` owns its
+own client settings. The total deadline still applies. A timeout can occur after
+Redis consumed quota but before the response arrived; automatically retrying a
+mutation can charge twice. Override the retry policy only with that tradeoff in mind.
+
+Use Python 3.12+ for latency-sensitive deployments. Python 3.11 remains compatible,
+but a connection-startup cancellation test with redis-py 5.2 showed cancellation
+delayed until the next timeout. This is consistent with the upstream
+[asyncio cancellation race](https://github.com/python/cpython/issues/86296).
+Deadlines rely on cooperative cancellation; keep socket timeouts short as a second
+bound, especially on 3.11 or with custom storage implementations.
+
+`limit(rule, key=None, bucket=None)` supports stacked rules. The default bucket is
+handler module + qualified name; set `bucket` explicitly when reusing a handler for
+distinct routes. Rejected requests consume outer quotas in a decorator stack.
+Keys may be sync or async request callbacks and are hashed before storage.
+
+The default identity uses the ASGI peer address, ignoring forwarded headers. Configure
+trusted-proxy handling in the server before using client IPs. A user/API-key callback
+must return a stable identity. Authentication must run before a user-based quota;
+place a separate IP quota outside authentication to limit failed attempts.
+
+Exhaustion returns JSON 429 and `Retry-After`. Storage failures and deadlines return
+503 unless `fail_open=True`. Once Redis denies a request, a failure fetching reset
+statistics preserves the 429, using a full window as a conservative `Retry-After`.
+Allowed HTTP requests do not fetch statistics. Rules are parsed when decorated.
+
+`await limiter.check(rule, identity, bucket='...')` consumes quota and returns
+`(allowed, retry_after)`, including reset information for allowed calls. It propagates
+storage failures and `TimeoutError` for service-level callers. The deadline covers
+storage operations, not identity callbacks or the handler. Unexpected errors outside
+the storage backend's declared exception types propagate; cancellation also propagates.
+
+The decorator logs handled failures at WARNING to `wred_ratelimit`, with record fields
+`namespace`, `bucket`, `fail_open`, `error_type`, and `quota_denied`. Configure your log
+formatter/exporter to include these fields. Identity values, Redis URLs, and exception
+messages are omitted. Monitor these events alongside HTTP 429/503 rates, request tail
+latency, Redis memory, and pool/connection usage. Direct `check()` callers own their
+error reporting. Avoid identities as metric labels.
+
+Use `async with limiter` or `await limiter.aclose()` in the hosting application's
+resource lifecycle. Wred itself does not implement lifespan.
+
+Tests: `pip install -e '.[test,redis]'`, then `pytest`.
+Set `WRED_TEST_REDIS=redis://localhost:6379/15` to include real Redis tests.
+Use a dedicated test instance/database. Cross-process tests verify shared quotas
+for both strategies. The restart test starts its own disposable Redis and requires
+the `redis-server` executable. CI runs real Redis with minimum and current dependencies.
+
+For a repeatable local load check, install the project and run:
+
+```sh
+REDIS_URL=redis://localhost:6379/15 python benchmarks/redis_load.py \
+    --workers 4 --concurrency 25 --requests 20000 --identities 1000 --quota 5
+```
+
+Use a dedicated benchmark Redis. The script exits unsuccessfully on an incorrect
+quota result or storage-error responses and prints throughput and p50/p95/p99
+latency. It exercises decorated handlers across processes, without HTTP network or
+application work. Each run creates a unique namespace whose keys expire in one hour.
+Repeat with `--strategy fixed` and with many distinct identities to assess memory
+and latency for your workload. This is a closed-loop load check, not an overload or
+production-capacity certification; validate your full application under sustained
+offered traffic and Redis failure/recovery before rollout.
+See [the recorded local baseline](benchmarks/README.md) for measured results and limits.
+
+Redis restarts without persistence, eviction, and failover that loses recent writes
+can reset quotas. The restart test explicitly verifies recovery after state loss;
+it does not promise quota continuity through failover. Choose persistence, memory
+limits/eviction policy, and availability settings for your enforcement requirements.
+Moving windows retain request timestamps and need more memory than fixed counters.
+Keep worker clocks synchronized. Cluster/Sentinel deployments can supply an appropriate
+limits async storage via `Limiter(storage=...)`; validate that topology separately.
+

wred_ratelimit-0.1.0/README.md

@@ -0,0 +1,121 @@
+# wred-ratelimit
+
+Async per-handler quotas using `limits`. Python 3.11+, Wred 0.13.
+
+```sh
+pip install '.[redis]'
+```
+
+```python
+from wred import App
+from wred_ratelimit import Limiter
+
+app = App()
+limiter = Limiter.redis("redis://localhost:6379/0", namespace="orders-api")
+
+
+@app.route("/orders/{order_id}")
+@limiter.limit("30/minute")
+async def order(request, order_id):
+    return {"id": order_id}
+```
+
+`Limiter(storage=None, namespace='wred', strategy='moving', key=client_ip,
+fail_open=False, timeout=0.5)` uses an in-process store unless provided a limits
+async store. Choose `moving` or `fixed` windows. The memory store belongs to each
+limiter instance; use shared Redis for quotas across workers. All workers must
+share a namespace, Redis database, bucket, and rule for shared quotas.
+
+`Limiter.redis(url, storage_options=None, **options)` configures redis-py.
+`options` configure the limiter; `storage_options` configure the limits Redis
+storage and its client. Requires `limits>=4.2` and `redis>=5.2`.
+
+```python
+limiter = Limiter.redis(
+    "redis://localhost:6379/0",
+    namespace="orders-api",
+    timeout=0.15,  # total storage budget per admission/check, in seconds
+    storage_options={
+        "socket_connect_timeout": 0.1,
+        "socket_timeout": 0.1,
+        "max_connections": 50,  # per limiter instance, normally per worker
+    },
+)
+```
+
+Defaults are a 0.5-second total storage deadline, 0.2-second connect/read timeouts,
+100 connections per pool, and no automatic command retries. Tune these to your
+application's latency and concurrency budget. Redis URL query parameters take
+precedence over equivalent client options. A supplied `connection_pool` owns its
+own client settings. The total deadline still applies. A timeout can occur after
+Redis consumed quota but before the response arrived; automatically retrying a
+mutation can charge twice. Override the retry policy only with that tradeoff in mind.
+
+Use Python 3.12+ for latency-sensitive deployments. Python 3.11 remains compatible,
+but a connection-startup cancellation test with redis-py 5.2 showed cancellation
+delayed until the next timeout. This is consistent with the upstream
+[asyncio cancellation race](https://github.com/python/cpython/issues/86296).
+Deadlines rely on cooperative cancellation; keep socket timeouts short as a second
+bound, especially on 3.11 or with custom storage implementations.
+
+`limit(rule, key=None, bucket=None)` supports stacked rules. The default bucket is
+handler module + qualified name; set `bucket` explicitly when reusing a handler for
+distinct routes. Rejected requests consume outer quotas in a decorator stack.
+Keys may be sync or async request callbacks and are hashed before storage.
+
+The default identity uses the ASGI peer address, ignoring forwarded headers. Configure
+trusted-proxy handling in the server before using client IPs. A user/API-key callback
+must return a stable identity. Authentication must run before a user-based quota;
+place a separate IP quota outside authentication to limit failed attempts.
+
+Exhaustion returns JSON 429 and `Retry-After`. Storage failures and deadlines return
+503 unless `fail_open=True`. Once Redis denies a request, a failure fetching reset
+statistics preserves the 429, using a full window as a conservative `Retry-After`.
+Allowed HTTP requests do not fetch statistics. Rules are parsed when decorated.
+
+`await limiter.check(rule, identity, bucket='...')` consumes quota and returns
+`(allowed, retry_after)`, including reset information for allowed calls. It propagates
+storage failures and `TimeoutError` for service-level callers. The deadline covers
+storage operations, not identity callbacks or the handler. Unexpected errors outside
+the storage backend's declared exception types propagate; cancellation also propagates.
+
+The decorator logs handled failures at WARNING to `wred_ratelimit`, with record fields
+`namespace`, `bucket`, `fail_open`, `error_type`, and `quota_denied`. Configure your log
+formatter/exporter to include these fields. Identity values, Redis URLs, and exception
+messages are omitted. Monitor these events alongside HTTP 429/503 rates, request tail
+latency, Redis memory, and pool/connection usage. Direct `check()` callers own their
+error reporting. Avoid identities as metric labels.
+
+Use `async with limiter` or `await limiter.aclose()` in the hosting application's
+resource lifecycle. Wred itself does not implement lifespan.
+
+Tests: `pip install -e '.[test,redis]'`, then `pytest`.
+Set `WRED_TEST_REDIS=redis://localhost:6379/15` to include real Redis tests.
+Use a dedicated test instance/database. Cross-process tests verify shared quotas
+for both strategies. The restart test starts its own disposable Redis and requires
+the `redis-server` executable. CI runs real Redis with minimum and current dependencies.
+
+For a repeatable local load check, install the project and run:
+
+```sh
+REDIS_URL=redis://localhost:6379/15 python benchmarks/redis_load.py \
+    --workers 4 --concurrency 25 --requests 20000 --identities 1000 --quota 5
+```
+
+Use a dedicated benchmark Redis. The script exits unsuccessfully on an incorrect
+quota result or storage-error responses and prints throughput and p50/p95/p99
+latency. It exercises decorated handlers across processes, without HTTP network or
+application work. Each run creates a unique namespace whose keys expire in one hour.
+Repeat with `--strategy fixed` and with many distinct identities to assess memory
+and latency for your workload. This is a closed-loop load check, not an overload or
+production-capacity certification; validate your full application under sustained
+offered traffic and Redis failure/recovery before rollout.
+See [the recorded local baseline](benchmarks/README.md) for measured results and limits.
+
+Redis restarts without persistence, eviction, and failover that loses recent writes
+can reset quotas. The restart test explicitly verifies recovery after state loss;
+it does not promise quota continuity through failover. Choose persistence, memory
+limits/eviction policy, and availability settings for your enforcement requirements.
+Moving windows retain request timestamps and need more memory than fixed counters.
+Keep worker clocks synchronized. Cluster/Sentinel deployments can supply an appropriate
+limits async storage via `Limiter(storage=...)`; validate that topology separately.

wred_ratelimit-0.1.0/benchmarks/README.md

@@ -0,0 +1,54 @@
+# Local Redis baseline
+
+Measured on 2026-11-01 using Python 3.14.4, limits 5.8.0, redis-py 8.1.0,
+Redis Server 8.0.5, and an Intel Core Ultra 7 256V host. Each scenario used a fresh
+Redis process over a Unix socket with persistence disabled. Four worker processes
+ran 25 concurrent decorated-handler calls each. No HTTP transport, TLS, proxy,
+authentication, or application workload was included.
+
+Each scenario ran 1,000,000 calls. The mixed workload used 10,000 identities and
+a quota of 25/hour: exactly 250,000 allowed and 750,000 denied. The all-allowed
+workload used 100,000 identities and a quota of 10/hour. All four runs matched
+the expected quota counts, with no 503 responses. Distinct workers shared identities.
+
+| Strategy | Workload | Duration | Calls/sec | p95 ms | p99 ms | Redis memory increase |
+| --- | --- | ---: | ---: | ---: | ---: | ---: |
+| Moving | Mixed | 23.479 s | 42,591 | 3.710 | 3.770 | 8.80 MiB |
+| Moving | All allowed | 18.179 s | 55,008 | 2.012 | 2.563 | 48.65 MiB |
+| Fixed | Mixed | 38.131 s | 26,225 | 4.551 | 4.677 | 2.54 MiB |
+| Fixed | All allowed | 16.447 s | 60,800 | 1.705 | 1.727 | 23.47 MiB |
+
+Memory increase is Redis `used_memory` after completion minus the idle-server
+baseline, not total process RSS or peak memory. The raw measurements include Redis
+peak memory in [results-2026-11-01.json](results-2026-11-01.json). Each run leaves
+its uniquely namespaced quota keys for one hour; use a dedicated benchmark server.
+
+Reproduce the two workloads for each strategy, with `REDIS_URL` pointing at a fresh
+disposable Redis instance:
+
+```sh
+python benchmarks/redis_load.py --strategy moving --requests 1000000 \
+    --workers 4 --concurrency 25 --identities 10000 --quota 25
+python benchmarks/redis_load.py --strategy moving --requests 1000000 \
+    --workers 4 --concurrency 25 --identities 100000 --quota 10
+```
+
+Repeat with `--strategy fixed`. The script reports handler latency and quota results;
+memory measurements above were collected separately through Redis INFO before and
+after each run.
+
+These are single, short, closed-loop local measurements. They are not steady-state
+capacity limits, an overload test, or a production SLO. Requests wait for earlier
+requests in each concurrency lane, so the latency distribution excludes queueing
+that would occur under sustained offered traffic above capacity. Mixed workloads
+transition from admission to rejection as quotas fill. Validate the complete service
+with realistic network latency, key distributions, bursts, expiry cycles, Redis
+failover, and application work before using these numbers for sizing.
+
+The correctness suite separately exercises cross-process quotas, stalled connections,
+pool exhaustion, and restart recovery. It passes on Python 3.11.11 with minimum
+dependencies (limits 4.2, redis-py 5.2), Python 3.13.2 with minimum and intermediate
+dependencies, and Python 3.14.4 with current dependencies. On 3.11, cancellation
+during Redis connection startup was delayed until the configured timeout; see the
+runtime caveat in the main README. Restart recovery does not preserve quota state
+when Redis has no persistence, and is not a replicated-failover continuity test.

wred_ratelimit-0.1.0/benchmarks/redis_load.py

@@ -0,0 +1,139 @@
+"""Exercise decorated handlers in independent processes against a disposable Redis.
+
+No HTTP server/network is included. Each run uses a unique namespace; its keys
+expire after one hour. REDIS_URL must point at a dedicated benchmark instance.
+"""
+
+import argparse
+import asyncio
+import json
+import math
+import multiprocessing
+import os
+import time
+import uuid
+from collections import Counter
+from concurrent.futures import ProcessPoolExecutor
+
+from wred import Request
+
+from wred_ratelimit import Limiter
+
+
+def worker(index, options, namespace):
+    async def run():
+        latencies = []
+        statuses = Counter()
+        per_worker, remainder = divmod(options["requests"], options["workers"])
+        first = index * per_worker + min(index, remainder)
+        indices = iter(range(first, first + per_worker + (index < remainder)))
+        async with Limiter.redis(
+            os.environ["REDIS_URL"],
+            namespace=namespace,
+            strategy=options["strategy"],
+            timeout=options["timeout"],
+            storage_options={"max_connections": options["concurrency"]},
+        ) as limiter:
+
+            @limiter.limit(f"{options['quota']}/hour", bucket="load")
+            async def handler(request):
+                return {}, [], 200
+
+            async def lane():
+                for number in indices:
+                    request = Request(
+                        {
+                            "path": "/",
+                            "method": "GET",
+                            "client": (str(number % options["identities"]), 1),
+                        },
+                        None,
+                        None,
+                    )
+                    start = time.perf_counter()
+                    result = await handler(request)
+                    latencies.append((time.perf_counter() - start) * 1000)
+                    statuses[result[2]] += 1
+
+            start = time.perf_counter()
+            await asyncio.gather(*(lane() for _ in range(options["concurrency"])))
+            end = time.perf_counter()
+        return dict(statuses), latencies, start, end
+
+    return asyncio.run(run())
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--workers", type=int, default=4)
+    parser.add_argument(
+        "--concurrency", type=int, default=25, help="Concurrent calls per worker"
+    )
+    parser.add_argument("--requests", type=int, default=20000)
+    parser.add_argument("--identities", type=int, default=1000)
+    parser.add_argument(
+        "--quota", type=int, default=5, help="Per-identity hourly quota"
+    )
+    parser.add_argument("--strategy", choices=["moving", "fixed"], default="moving")
+    parser.add_argument("--timeout", type=float, default=0.5)
+    options = vars(parser.parse_args())
+    if "REDIS_URL" not in os.environ:
+        parser.error("Set REDIS_URL to a dedicated benchmark Redis instance")
+    if any(
+        options[key] <= 0
+        for key in ("workers", "concurrency", "requests", "identities", "quota")
+    ):
+        parser.error("Counts must be positive")
+    if not math.isfinite(options["timeout"]) or options["timeout"] <= 0:
+        parser.error("Timeout must be finite and positive")
+
+    namespace = "wred-benchmark-" + uuid.uuid4().hex
+    with ProcessPoolExecutor(
+        max_workers=options["workers"], mp_context=multiprocessing.get_context("spawn")
+    ) as pool:
+        futures = [
+            pool.submit(worker, index, options, namespace)
+            for index in range(options["workers"])
+        ]
+        results = [future.result() for future in futures]
+    statuses = Counter()
+    latencies = []
+    for counts, timings, _, _ in results:
+        statuses.update(counts)
+        latencies.extend(timings)
+    latencies.sort()
+    elapsed = max(result[3] for result in results) - min(
+        result[2] for result in results
+    )
+    per_identity, remainder = divmod(options["requests"], options["identities"])
+    expected = remainder * min(options["quota"], per_identity + 1) + (
+        options["identities"] - remainder
+    ) * min(options["quota"], per_identity)
+    correct = (
+        statuses[200] == expected and statuses[429] == options["requests"] - expected
+    )
+    print(
+        json.dumps(
+            {
+                **options,
+                "namespace": namespace,
+                "elapsed_seconds": round(elapsed, 3),
+                "requests_per_second": round(len(latencies) / elapsed),
+                "latency_ms": {
+                    f"p{percentile}": round(
+                        latencies[math.ceil(len(latencies) * percentile / 100) - 1], 3
+                    )
+                    for percentile in (50, 95, 99)
+                },
+                "statuses": dict(statuses),
+                "expected_allowed": expected,
+                "quota_correct": correct,
+            },
+            indent=2,
+        )
+    )
+    raise SystemExit(0 if correct else 1)
+
+
+if __name__ == "__main__":
+    main()

wred_ratelimit-0.1.0/benchmarks/results-2026-11-01.json

@@ -0,0 +1,104 @@
+[
+  {
+    "workers": 4,
+    "concurrency": 25,
+    "requests": 1000000,
+    "identities": 10000,
+    "quota": 25,
+    "strategy": "moving",
+    "timeout": 0.5,
+    "namespace": "wred-benchmark-ce726911dbe448ffa3ff416040f454ce",
+    "elapsed_seconds": 23.479,
+    "requests_per_second": 42591,
+    "latency_ms": {
+      "p50": 2.39,
+      "p95": 3.71,
+      "p99": 3.77
+    },
+    "statuses": {
+      "200": 250000,
+      "429": 750000
+    },
+    "expected_allowed": 250000,
+    "quota_correct": true,
+    "redis_version": "8.0.5",
+    "redis_used_memory_delta_bytes": 9231176,
+    "redis_peak_memory_bytes": 11374008
+  },
+  {
+    "workers": 4,
+    "concurrency": 25,
+    "requests": 1000000,
+    "identities": 100000,
+    "quota": 10,
+    "strategy": "moving",
+    "timeout": 0.5,
+    "namespace": "wred-benchmark-7b1170ba730e4497b675dab6d6eecc47",
+    "elapsed_seconds": 18.179,
+    "requests_per_second": 55008,
+    "latency_ms": {
+      "p50": 1.776,
+      "p95": 2.012,
+      "p99": 2.563
+    },
+    "statuses": {
+      "200": 1000000
+    },
+    "expected_allowed": 1000000,
+    "quota_correct": true,
+    "redis_version": "8.0.5",
+    "redis_used_memory_delta_bytes": 51016896,
+    "redis_peak_memory_bytes": 51947200
+  },
+  {
+    "workers": 4,
+    "concurrency": 25,
+    "requests": 1000000,
+    "identities": 10000,
+    "quota": 25,
+    "strategy": "fixed",
+    "timeout": 0.5,
+    "namespace": "wred-benchmark-5453cb19ab4344ebac6b6dd8997d2d47",
+    "elapsed_seconds": 38.131,
+    "requests_per_second": 26225,
+    "latency_ms": {
+      "p50": 4.412,
+      "p95": 4.551,
+      "p99": 4.677
+    },
+    "statuses": {
+      "200": 250000,
+      "429": 750000
+    },
+    "expected_allowed": 250000,
+    "quota_correct": true,
+    "redis_version": "8.0.5",
+    "redis_used_memory_delta_bytes": 2665056,
+    "redis_peak_memory_bytes": 5180400
+  },
+  {
+    "workers": 4,
+    "concurrency": 25,
+    "requests": 1000000,
+    "identities": 100000,
+    "quota": 10,
+    "strategy": "fixed",
+    "timeout": 0.5,
+    "namespace": "wred-benchmark-c67ca2ff1ff44be2bac3b204b56c9bc4",
+    "elapsed_seconds": 16.447,
+    "requests_per_second": 60800,
+    "latency_ms": {
+      "p50": 1.66,
+      "p95": 1.705,
+      "p99": 1.727
+    },
+    "statuses": {
+      "200": 1000000
+    },
+    "expected_allowed": 1000000,
+    "quota_correct": true,
+    "redis_version": "8.0.5",
+    "redis_used_memory_delta_bytes": 24610688,
+    "redis_peak_memory_bytes": 25639376
+  }
+]

wred_ratelimit-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["flit_core>=3.12,<4"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name = "wred-ratelimit"
+version = "0.1.0"
+description = "Optional ratelimit integration for Wred"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "BSD-3-Clause"
+dependencies = ["wred>=0.13,<0.14", "limits>=4.2,<6"]
+
+[project.optional-dependencies]
+test = ["pytest>=8", "pytest-asyncio>=0.24", "httpx>=0.27"]
+redis = ["redis>=5.2"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

wred_ratelimit-0.1.0/tests/test_hardening.py

@@ -0,0 +1,141 @@
+import asyncio
+import logging
+
+import pytest
+from limits.aio.storage import MemoryStorage
+from wred import Request
+
+from wred_ratelimit import Limiter
+
+
+def request():
+    return Request(
+        {"path": "/", "method": "GET", "client": ("127.0.0.1", 1)}, None, None
+    )
+
+
+@pytest.mark.parametrize("strategy", ["moving", "fixed"])
+async def test_admission_survives_stats_failure_without_bypassing_denial(
+    strategy, caplog
+):
+    class StatsUnavailable(MemoryStorage):
+        async def get_moving_window(self, *args, **kwargs):
+            raise ValueError("stats unavailable")
+
+        async def get_expiry(self, *args, **kwargs):
+            raise ValueError("stats unavailable")
+
+    async with Limiter(
+        storage=StatsUnavailable(), strategy=strategy, fail_open=True
+    ) as limiter:
+
+        @limiter.limit("1/minute")
+        async def handler(request):
+            return {"ok": True}
+
+        with caplog.at_level(logging.WARNING, logger="wred_ratelimit"):
+            assert await handler(request()) == {"ok": True}
+            assert not caplog.records
+            denied = await handler(request())
+        assert denied[2] == 429
+        assert dict(denied[1])["retry-after"] == "60"
+        assert caplog.records[-1].error_type == "ValueError"
+
+
+@pytest.mark.parametrize("fail_open", [False, True])
+async def test_programming_errors_propagate(fail_open):
+    class BrokenStorage(MemoryStorage):
+        async def acquire_entry(self, *args, **kwargs):
+            raise TypeError("programming error")
+
+    async with Limiter(storage=BrokenStorage(), fail_open=fail_open) as limiter:
+
+        @limiter.limit("1/minute")
+        async def handler(request):
+            return {"ok": True}
+
+        with pytest.raises(TypeError, match="programming error"):
+            await handler(request())
+
+
+@pytest.fixture
+async def silent_redis():
+    connected = asyncio.Event()
+    writers = []
+
+    async def unresponsive(reader, writer):
+        writers.append(writer)
+        connected.set()
+        await reader.read()
+
+    server = await asyncio.start_server(unresponsive, "127.0.0.1", 0)
+    port = server.sockets[0].getsockname()[1]
+    try:
+        yield f"redis://127.0.0.1:{port}", connected
+    finally:
+        server.close()
+        for writer in writers:
+            writer.close()
+            await writer.wait_closed()
+        await server.wait_closed()
+
+
+@pytest.mark.parametrize("fail_open", [False, True])
+async def test_slow_redis_is_bounded_and_observable(fail_open, caplog, silent_redis):
+    url, _ = silent_redis
+    async with Limiter.redis(
+        url,
+        fail_open=fail_open,
+        timeout=0.05,
+        storage_options={"socket_timeout": 5, "socket_connect_timeout": 5},
+    ) as limiter:
+
+        @limiter.limit("1/minute", key=lambda request: "private-identity")
+        async def handler(request):
+            return {"ok": True}
+
+        with caplog.at_level(logging.WARNING, logger="wred_ratelimit"):
+            result = await asyncio.wait_for(handler(request()), timeout=1)
+        if fail_open:
+            assert result == {"ok": True}
+        else:
+            assert result[2] == 503
+        assert caplog.records[-1].error_type == "TimeoutError"
+        assert caplog.records[-1].fail_open is fail_open
+        assert "private-identity" not in caplog.text
+        async with asyncio.timeout(1):
+            with pytest.raises(TimeoutError):
+                await limiter.check("1/minute", "user", bucket="test")
+
+
+async def test_redis_pool_is_bounded_and_cancellation_propagates(caplog, silent_redis):
+    url, connected = silent_redis
+    pending = None
+    try:
+        async with Limiter.redis(
+            url,
+            timeout=10,
+            storage_options={"max_connections": 1, "socket_timeout": 10},
+        ) as limiter:
+
+            @limiter.limit("1/minute")
+            async def handler(request):
+                return {"ok": True}
+
+            pending = asyncio.create_task(handler(request()))
+            await asyncio.wait_for(connected.wait(), 1)
+            with caplog.at_level(logging.WARNING, logger="wred_ratelimit"):
+                result = await asyncio.wait_for(handler(request()), 1)
+            assert result[2] == 503
+            assert not pending.done()
+            assert caplog.records[-1].error_type in (
+                "ConnectionError",
+                "MaxConnectionsError",
+            )
+            pending.cancel()
+            with pytest.raises(asyncio.CancelledError):
+                await pending
+    finally:
+        if pending is not None and not pending.done():
+            pending.cancel()
+            await asyncio.gather(pending, return_exceptions=True)

wred_ratelimit-0.1.0/tests/test_limits.py

@@ -0,0 +1,73 @@
+import asyncio
+import os
+import uuid
+
+import httpx
+import pytest
+from wred import App
+
+from wred_ratelimit import Limiter
+
+
+@pytest.fixture(params=["memory", "redis"])
+async def limiter(request):
+    kwargs = {"namespace": uuid.uuid4().hex}
+    if request.param == "redis":
+        url = os.getenv("WRED_TEST_REDIS")
+        if not url:
+            pytest.skip("Set WRED_TEST_REDIS for real Redis integration")
+        result = Limiter.redis(url, **kwargs)
+    else:
+        result = Limiter(**kwargs)
+    yield result
+    await result.aclose()
+
+
+async def test_concurrent_quota_and_identity(limiter):
+    result = await asyncio.gather(
+        *(limiter.check("5/minute", "alice", bucket="orders") for _ in range(20))
+    )
+    assert sum(allowed for allowed, _ in result) == 5
+    assert all(retry > 0 for _, retry in result)
+    assert (await limiter.check("5/minute", "bob", bucket="orders"))[0]
+    assert (await limiter.check("5/minute", "alice", bucket="elsewhere"))[0]
+
+
+async def test_http_path_forwarding(limiter):
+    app = App()
+
+    @app.route("/{name}")
+    @limiter.limit("1/minute")
+    async def handler(request, name):
+        return {"name": name}
+
+    async with httpx.AsyncClient(
+        transport=httpx.ASGITransport(app), base_url="http://test"
+    ) as client:
+        assert (await client.get("/alice")).json() == {"name": "alice"}
+        result = await client.get("/bob", headers={"X-Forwarded-For": "1.2.3.4"})
+        assert result.status_code == 429 and int(result.headers["retry-after"]) > 0
+
+
+async def test_expiry_and_fixed_window():
+    limiter = Limiter(strategy="fixed")
+    assert (await limiter.check("1/second", "user", bucket="test"))[0]
+    assert not (await limiter.check("1/second", "user", bucket="test"))[0]
+    await asyncio.sleep(1.05)
+    assert (await limiter.check("1/second", "user", bucket="test"))[0]
+
+
+async def test_storage_outage():
+    limiter = Limiter.redis("redis://127.0.0.1:1")
+
+    @limiter.limit("1/minute")
+    async def handler(request):
+        return {"ok": True}
+
+    from wred import Request
+
+    request = Request({"path": "/", "method": "GET"}, None, None)
+    assert (await handler(request))[2] == 503
+    limiter.fail_open = True
+    assert await handler(request) == {"ok": True}
+    await limiter.aclose()

wred_ratelimit-0.1.0/tests/test_redis.py

@@ -0,0 +1,97 @@
+import asyncio
+import multiprocessing
+import os
+import shutil
+import uuid
+from concurrent.futures import ProcessPoolExecutor
+
+import pytest
+from wred import Request
+
+from wred_ratelimit import Limiter
+
+
+def consume_in_worker(url, namespace, strategy):
+    async def consume():
+        async with Limiter.redis(
+            url, namespace=namespace, strategy=strategy
+        ) as limiter:
+            decisions = await asyncio.gather(
+                *(
+                    limiter.check("17/minute", "shared", bucket="orders")
+                    for _ in range(50)
+                )
+            )
+            return sum(allowed for allowed, _ in decisions)
+
+    return asyncio.run(consume())
+
+
+@pytest.mark.parametrize("strategy", ["moving", "fixed"])
+def test_quota_is_shared_across_processes(strategy):
+    url = os.getenv("WRED_TEST_REDIS")
+    if not url:
+        pytest.skip("Set WRED_TEST_REDIS for real Redis integration")
+    namespace = uuid.uuid4().hex
+    with ProcessPoolExecutor(
+        max_workers=4, mp_context=multiprocessing.get_context("spawn")
+    ) as pool:
+        futures = [
+            pool.submit(consume_in_worker, url, namespace, strategy) for _ in range(4)
+        ]
+        assert sum(future.result(timeout=20) for future in futures) == 17
+
+
+async def test_recovers_after_redis_restart(tmp_path):
+    executable = shutil.which("redis-server")
+    if not executable:
+        pytest.skip("redis-server is required for restart integration")
+    socket = tmp_path / "redis.sock"
+    process = None
+
+    async def start():
+        nonlocal process
+        process = await asyncio.create_subprocess_exec(
+            executable,
+            "--port",
+            "0",
+            "--unixsocket",
+            str(socket),
+            "--save",
+            "",
+            "--appendonly",
+            "no",
+            stdout=asyncio.subprocess.DEVNULL,
+            stderr=asyncio.subprocess.DEVNULL,
+        )
+        async with asyncio.timeout(5):
+            while not socket.exists():
+                if process.returncode is not None:
+                    raise RuntimeError("Test Redis failed to start")
+                await asyncio.sleep(0.01)
+
+    async def stop():
+        if process is not None and process.returncode is None:
+            process.terminate()
+            await asyncio.wait_for(process.wait(), 5)
+        socket.unlink(missing_ok=True)
+
+    try:
+        await start()
+        async with Limiter.redis(f"redis+unix://{socket}") as limiter:
+
+            @limiter.limit("1/minute")
+            async def handler(request):
+                return {"ok": True}
+
+            request = Request({"path": "/", "method": "GET"}, None, None)
+            assert await handler(request) == {"ok": True}
+            assert (await handler(request))[2] == 429
+            await stop()
+            assert (await handler(request))[2] == 503
+            await start()
+            # This server has no persistence: reconnect works, but quotas reset.
+            assert await handler(request) == {"ok": True}
+            assert (await handler(request))[2] == 429
+    finally:
+        await stop()

wred_ratelimit-0.1.0/wred_ratelimit/__init__.py

@@ -0,0 +1,168 @@
+"""Per-handler request quotas using the async limits engine."""
+
+import asyncio
+import hashlib
+import inspect
+import logging
+import math
+import time
+from functools import wraps
+
+from limits import parse
+from limits.aio.storage import MemoryStorage, RedisStorage
+from limits.aio.strategies import FixedWindowRateLimiter, MovingWindowRateLimiter
+from limits.errors import StorageError
+
+__version__ = "0.1.0"
+logger = logging.getLogger(__name__)
+
+
+def client_ip(request):
+    """Use the ASGI peer address; forwarded headers are not trusted."""
+    return (request.scope.get("client") or ("unknown",))[0]
+
+
+class Limiter:
+    def __init__(
+        self,
+        *,
+        storage=None,
+        namespace="wred",
+        strategy="moving",
+        key=client_ip,
+        fail_open=False,
+        timeout=0.5,
+    ):
+        if strategy not in ("fixed", "moving"):
+            raise ValueError("strategy must be fixed or moving")
+        if not math.isfinite(timeout) or timeout <= 0:
+            raise ValueError("timeout must be a finite positive number of seconds")
+        self.storage = storage if storage is not None else MemoryStorage()
+        self.engine = (
+            MovingWindowRateLimiter if strategy == "moving" else FixedWindowRateLimiter
+        )(self.storage)
+        self.namespace, self.key, self.fail_open = namespace, key, fail_open
+        self.timeout = timeout
+        errors = self.storage.base_exceptions
+        if not isinstance(errors, tuple):
+            errors = (errors,)
+        self._storage_errors = (StorageError, TimeoutError, *errors)
+
+    @classmethod
+    def redis(cls, url, *, storage_options=None, **kwargs):
+        """Create Redis storage with bounded connections and no command retries.
+
+        ``storage_options`` are forwarded to the limits RedisStorage constructor.
+        Remaining keywords configure this Limiter. Redis URL options take precedence
+        over client keyword options, as in redis-py.
+        """
+        from redis.asyncio.retry import Retry
+        from redis.backoff import NoBackoff
+
+        options = {
+            "socket_connect_timeout": 0.2,
+            "socket_timeout": 0.2,
+            "max_connections": 100,
+            # A lost response does not mean the quota mutation failed. Retrying
+            # could charge a request twice.
+            "retry": Retry(NoBackoff(), 0),
+        }
+        options.update(storage_options or {})
+        return cls(
+            storage=RedisStorage(url, implementation="redispy", **options), **kwargs
+        )
+
+    def _identifiers(self, identity, bucket):
+        return (
+            self.namespace,
+            bucket,
+            hashlib.sha256(str(identity).encode()).hexdigest(),
+        )
+
+    async def _retry_after(self, item, identifiers):
+        stats = await self.engine.get_window_stats(item, *identifiers)
+        return max(1, math.ceil(stats.reset_time - time.time()))
+
+    async def check(self, rule, identity, *, bucket):
+        """Consume quota, returning (allowed, retry_after); storage errors propagate."""
+        item = parse(rule)
+        identifiers = self._identifiers(identity, bucket)
+        async with asyncio.timeout(self.timeout):
+            allowed = await self.engine.hit(item, *identifiers)
+            return allowed, await self._retry_after(item, identifiers)
+
+    def limit(self, rule, *, key=None, bucket=None):
+        item = parse(rule)
+
+        def decorate(handler):
+            route_bucket = bucket or f"{handler.__module__}.{handler.__qualname__}"
+
+            @wraps(handler)
+            async def wrapped(request, *args, **kwargs):
+                identity = (key or self.key)(request)
+                if inspect.isawaitable(identity):
+                    identity = await identity
+                identifiers = self._identifiers(identity, route_bucket)
+                allowed = None
+                # If statistics fail after a denial, keep the denial and use a
+                # conservative full window instead of allowing an exhausted quota.
+                retry = item.get_expiry()
+                try:
+                    async with asyncio.timeout(self.timeout):
+                        allowed = await self.engine.hit(item, *identifiers)
+                        if not allowed:
+                            retry = await self._retry_after(item, identifiers)
+                except self._storage_errors as exc:
+                    # Do not log identities, Redis URLs, or exception messages:
+                    # they can contain credentials or other sensitive data.
+                    logger.warning(
+                        "Rate limit storage failure",
+                        extra={
+                            "namespace": self.namespace,
+                            "bucket": route_bucket,
+                            "fail_open": self.fail_open,
+                            "error_type": type(exc).__name__,
+                            "quota_denied": allowed is False,
+                        },
+                    )
+                    if allowed is not False and not self.fail_open:
+                        return (
+                            {"detail": "Rate limit service unavailable"},
+                            [("content-type", "application/json")],
+                            503,
+                        )
+                if allowed is False:
+                    return (
+                        {"detail": "Rate limit exceeded"},
+                        [
+                            ("content-type", "application/json"),
+                            ("retry-after", str(retry)),
+                        ],
+                        429,
+                    )
+                return await handler(request, *args, **kwargs)
+
+            return wrapped
+
+        return decorate
+
+    async def aclose(self):
+        # limits owns a bridge over the redis-py connection.
+        bridge = getattr(self.storage, "bridge", None)
+        if bridge is not None:
+            closed = set()
+            for attr in ("storage", "storage_readonly"):
+                client = getattr(bridge, attr, None)
+                if (
+                    client is not None
+                    and id(client) not in closed
+                    and hasattr(client, "aclose")
+                ):
+                    await client.aclose()
+                    closed.add(id(client))
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *exc):
+        await self.aclose()