fix(retry): honor Retry-After: 0 end-to-end through transport

Per second-pass bot review on #112: the prior commit kept Retry-After: 0
on the error object, but transport's "if error.retry_after:" check
dropped 0 as falsy and fell through to backoff. Switched to
"is not None" in both sync and async transport. Added regression
tests that monkeypatch time.sleep / asyncio.sleep and assert the
delay is exactly 0.0 (not the backoff fallback).

Also addressed:
- config._validate_url docstring trimmed to one line (CLAUDE.md).
- Called via KalshiConfig._validate_url(...) rather than self.
  (staticmethod-through-self hides that no instance state is used).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: TexasCoding

kalshi/_base_client.py

@@ -165,8 +165,12 @@ def request(
             if not should_retry:
                 raise error
 
-            # Use Retry-After header if available for 429
-            if isinstance(error, KalshiRateLimitError) and error.retry_after:
+            # Use Retry-After header if available for 429.
+            # `is not None` — not truthy — so Retry-After: 0 ("retry immediately") is honored.
+            if (
+                isinstance(error, KalshiRateLimitError)
+                and error.retry_after is not None
+            ):
                 delay = min(error.retry_after, self._config.retry_max_delay)
             else:
                 delay = _compute_backoff(attempt, self._config)
@@ -279,7 +283,11 @@ async def request(
             if not should_retry:
                 raise error
 
-            if isinstance(error, KalshiRateLimitError) and error.retry_after:
+            # `is not None` so Retry-After: 0 ("retry immediately") is honored.
+            if (
+                isinstance(error, KalshiRateLimitError)
+                and error.retry_after is not None
+            ):
                 delay = min(error.retry_after, self._config.retry_max_delay)
             else:
                 delay = _compute_backoff(attempt, self._config)

kalshi/config.py

@@ -51,22 +51,12 @@ def __post_init__(self) -> None:
             object.__setattr__(self, "base_url", self.base_url.rstrip("/"))
         if self.ws_base_url.endswith("/"):
             object.__setattr__(self, "ws_base_url", self.ws_base_url.rstrip("/"))
-        self._validate_url(self.base_url, "base_url", secure="https", plaintext="http")
-        self._validate_url(self.ws_base_url, "ws_base_url", secure="wss", plaintext="ws")
+        KalshiConfig._validate_url(self.base_url, "base_url", secure="https", plaintext="http")
+        KalshiConfig._validate_url(self.ws_base_url, "ws_base_url", secure="wss", plaintext="ws")
 
     @staticmethod
     def _validate_url(url: str, field_name: str, *, secure: str, plaintext: str) -> None:
-        """Reject URLs that would leak API credentials.
-
-        An attacker who can write to the process environment (``docker run
-        -e``, CI variable, shell history) can otherwise redirect signed
-        requests to an arbitrary host. Enforce the secure scheme for remote
-        hosts; warn when the host isn't a known Kalshi endpoint so misroutes
-        surface in logs.
-
-        The plaintext scheme is permitted only for loopback hosts (localhost,
-        127.0.0.1, ::1) so local mock servers and tests still work.
-        """
+        """Reject URLs that would expose credentials (bad scheme or plaintext-to-remote)."""
         parsed = urlparse(url)
         scheme = parsed.scheme.lower()
         host = (parsed.hostname or "").lower()

tests/test_async_client.py

@@ -71,6 +71,31 @@ async def test_get_retries_on_429(self, transport: AsyncTransport) -> None:
         assert resp.status_code == 200
         assert route.call_count == 2
 
+    @respx.mock
+    @pytest.mark.asyncio
+    async def test_429_retry_after_zero_is_honored_end_to_end(
+        self, transport: AsyncTransport, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        # Async counterpart of the sync regression: `is not None` keeps Retry-After: 0.
+        sleeps: list[float] = []
+
+        async def fake_sleep(d: float) -> None:
+            sleeps.append(d)
+
+        # _base_client imports asyncio inside the method, so patch the module attr directly.
+        monkeypatch.setattr("asyncio.sleep", fake_sleep)
+        respx.get("https://test.kalshi.com/trade-api/v2/markets").mock(
+            side_effect=[
+                httpx.Response(429, headers={"Retry-After": "0"}, json={"message": "rl"}),
+                httpx.Response(200, json={"markets": []}),
+            ]
+        )
+        resp = await transport.request("GET", "/markets")
+        assert resp.status_code == 200
+        assert sleeps == [0.0], (
+            f"Expected one sleep of 0.0s honoring Retry-After: 0, got {sleeps!r}"
+        )
+
     @respx.mock
     @pytest.mark.asyncio
     async def test_get_retries_on_500(self, transport: AsyncTransport) -> None:

tests/test_client.py

@@ -180,6 +180,26 @@ def test_get_retries_on_429(self, transport: SyncTransport) -> None:
         assert resp.status_code == 200
         assert route.call_count == 2
 
+    @respx.mock
+    def test_429_retry_after_zero_is_honored_end_to_end(
+        self, transport: SyncTransport, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        # Regression: `if error.retry_after:` would drop 0 ("retry immediately") as falsy.
+        # `is not None` keeps it; assert the transport actually sleeps 0, not the backoff fallback.
+        sleeps: list[float] = []
+        monkeypatch.setattr("kalshi._base_client.time.sleep", lambda d: sleeps.append(d))
+        respx.get("https://test.kalshi.com/trade-api/v2/markets").mock(
+            side_effect=[
+                httpx.Response(429, headers={"Retry-After": "0"}, json={"message": "rl"}),
+                httpx.Response(200, json={"markets": []}),
+            ]
+        )
+        resp = transport.request("GET", "/markets")
+        assert resp.status_code == 200
+        assert sleeps == [0.0], (
+            f"Expected one sleep of 0.0s honoring Retry-After: 0, got {sleeps!r}"
+        )
+
     @respx.mock
     def test_get_retries_on_500(self, transport: SyncTransport) -> None:
         """500s are transient on GETs; demo routinely returns them mid-paginate."""