fix(queue): honor Retry-After on transient errors (review feedback)

Use the Retry-After header (delta-seconds form, floored at 0.5s and
capped at 60s) for the retry delay on 429/503-style responses, and use
the stop-aware wait() instead of sleep() so a long delay can't block
shutdown.

Author: ErikBjare

aw_client/client.py

@@ -425,6 +425,21 @@ def _warn_queue_before_connect(self) -> None:
 QueuedRequest = namedtuple("QueuedRequest", ["endpoint", "data"])
 Bucket = namedtuple("Bucket", ["id", "type"])
 
+# Bounds for the delay before retrying a queued request after a
+# transient server error (e.g. 429/503), honoring Retry-After if given.
+RETRY_DELAY_DEFAULT = 0.5
+RETRY_DELAY_MAX = 60.0
+
+
+def _retry_delay(response: req.Response) -> float:
+    """Delay before retrying, honoring the Retry-After header (delta-seconds
+    form) if present and sane; the HTTP-date form falls back to the default."""
+    try:
+        delay = float(response.headers.get("Retry-After", RETRY_DELAY_DEFAULT))
+    except ValueError:
+        return RETRY_DELAY_DEFAULT
+    return max(RETRY_DELAY_DEFAULT, min(delay, RETRY_DELAY_MAX))
+
 
 class RequestQueue(threading.Thread):
     """Used to asynchronously send heartbeats.
@@ -539,17 +554,20 @@ def _dispatch_request(self) -> None:
             # NOTE: `e.response is not None` matters: Response.__bool__ is
             # False for any non-2xx status, so a plain `if e.response` never
             # matches an error response.
-            status_code = e.response.status_code if e.response is not None else None
-            if status_code in self.RETRY_STATUS_CODES:
+            response = e.response
+            status_code = response.status_code if response is not None else None
+            if response is not None and status_code in self.RETRY_STATUS_CODES:
                 # Transient server-side problem (busy, overloaded, restarting
                 # or behind a flaky proxy) - the request itself is likely
                 # fine, so keep it in the queue and retry. Heartbeats are safe
                 # to replay: a duplicate of an already-processed heartbeat
                 # merges into the last event as a no-op.
+                delay = _retry_delay(response)
                 logger.warning(
-                    f"Server error {status_code}, will retry: {request.endpoint}"
+                    f"Server error {status_code}, will retry in {delay}s: {request.endpoint}"
                 )
-                sleep(0.5)
+                # stop-aware wait, so a long Retry-After can't block shutdown
+                self.wait(delay)
                 return
             else:
                 # Client errors (e.g. HTTP 400 - bad request, see

tests/test_requestqueue.py

@@ -177,3 +177,21 @@ def test_dispatch_keeps_queue_on_connection_error():
 
     assert rq._get_next() is not None  # still queued
     assert rq.connected is False
+
+
+def test_retry_delay_honors_retry_after():
+    from aw_client.client import _retry_delay, RETRY_DELAY_DEFAULT, RETRY_DELAY_MAX
+
+    def resp(retry_after=None):
+        r = requests.Response()
+        r.status_code = 429
+        if retry_after is not None:
+            r.headers["Retry-After"] = retry_after
+        return r
+
+    assert _retry_delay(resp()) == RETRY_DELAY_DEFAULT  # absent
+    assert _retry_delay(resp("2")) == 2.0  # delta-seconds
+    assert _retry_delay(resp("9999")) == RETRY_DELAY_MAX  # capped
+    assert _retry_delay(resp("0")) == RETRY_DELAY_DEFAULT  # floored
+    # HTTP-date form is not parsed, falls back to default
+    assert _retry_delay(resp("Wed, 21 Oct 2026 07:28:00 GMT")) == RETRY_DELAY_DEFAULT