Document rate-limit semantics precisely; mention it in the README

The PyPI-facing README still described the package as digest-auth only.
In the API reference, spell out the details a user needs to avoid
surprises: rate must be finite; per-domain buckets are keyed on host only;
Retry-After is honored on 429 only, delays just the request that received
it, and its sleep counts against the session ClientTimeout (hence the 60s
default cap); configuration is fixed at construction; and the rate limiter
should be listed last so internal retries by other middlewares are also
throttled.

Author: rodrigobnogueira

README.rst

@@ -26,9 +26,12 @@ aiohttp-client-middlewares
 Reusable client middlewares for aiohttp.
 
 ``aiohttp-client-middlewares`` is a small, pure-Python collection of
-ready-to-use *client* middlewares for ``aiohttp``. It currently provides
-``DigestAuthMiddleware``, vendored from aiohttp core; this package is the
-canonical home for it going forward.
+ready-to-use *client* middlewares for ``aiohttp``. It currently provides:
+
+- ``DigestAuthMiddleware`` -- HTTP Digest authentication, vendored from
+  aiohttp core; this package is the canonical home for it going forward.
+- ``RateLimitMiddleware`` -- client-side token-bucket rate limiting with
+  optional per-domain buckets and ``Retry-After`` handling.
 
 Middlewares plug into ``aiohttp.ClientSession`` through the client
 middleware API introduced in aiohttp 3.12, so they can wrap every outgoing

docs/api.rst

@@ -80,32 +80,51 @@ Digest authentication
 Rate limiting
 -------------
 
-.. class:: RateLimitMiddleware(rate=10.0, burst=10, per_domain=False, respect_retry_after=True, max_retry_after=300.0)
+.. class:: RateLimitMiddleware(rate=10.0, burst=10, per_domain=False, respect_retry_after=True, max_retry_after=60.0)
 
    Client middleware that throttles outgoing requests with a token bucket.
 
    :param float rate: Sustained request rate, in requests per second. Must be
-      greater than 0.
+      a positive, finite number.
    :param int burst: Number of requests allowed to go out back-to-back before
       throttling kicks in. Must be at least 1.
    :param bool per_domain: Keep an independent bucket per target host instead
-      of a single global bucket. The per-host buckets are never evicted, so only
-      enable this for a bounded, trusted set of hosts.
+      of a single global bucket. Buckets are keyed on the URL host only (port
+      and scheme are not distinguished) and are never evicted, so only enable
+      this for a bounded, trusted set of hosts.
    :param bool respect_retry_after: Sleep for the duration of a numeric
       ``Retry-After`` header on an HTTP 429 response before returning it to the
-      caller.
+      caller. Only the request that received the 429 sleeps -- concurrent
+      requests are not held back -- and the response is returned as-is
+      afterwards (there is no automatic retry). Other statuses that may carry
+      ``Retry-After`` (such as 503) are not inspected.
    :param max_retry_after: Upper bound, in seconds, on how long a ``Retry-After``
-      header may make the client sleep. Must be ``None`` (no cap) or a
-      non-negative, finite number. A server-sent ``Retry-After`` that is itself
-      non-finite (``inf``/``nan``) or non-positive is always ignored, so a
-      hostile server cannot stall the client indefinitely.
+      header may make the client sleep (default ``60.0``; ``0.0`` disables the
+      sleep entirely). Must be ``None`` (no cap) or a non-negative, finite
+      number. A server-sent ``Retry-After`` that is itself non-finite
+      (``inf``/``nan``) or non-positive is always ignored, so a hostile server
+      cannot stall the client indefinitely. The sleep happens inside the request
+      and counts against the session's :class:`~aiohttp.ClientTimeout` (whose
+      default ``total`` is 300 seconds), so keep the cap well below your total
+      timeout or the request will fail with a timeout error instead of returning
+      the 429 response.
    :type max_retry_after: float or None
 
    The middleware delays each request until the bucket grants it a slot, so the
    client never sends faster than ``rate`` requests per second while still
    allowing short bursts of up to ``burst`` requests. Slots are served in strict
    FIFO order.
 
+   Configuration is fixed at construction time: changing the attributes of an
+   existing instance does not reconfigure buckets that were already built.
+
+   Middleware order matters: middlewares listed earlier wrap the ones listed
+   later, and a middleware that retries internally (for example,
+   :class:`DigestAuthMiddleware` replaying a request after a 401) re-invokes
+   only the middlewares listed *after* it. List ``RateLimitMiddleware`` last so
+   that every request hitting the wire -- including such replays -- is
+   throttled.
+
    ``rate``, ``burst`` and ``max_retry_after`` are validated on construction and
    raise :exc:`ValueError` if out of range.