Narrow retry_with_backoff's default retryable tuple

The helper defaulted to retrying any Exception, which meant a
programming bug (TypeError, AttributeError, KeyError, ...) got retried
up to max_attempts times with exponential backoff before finally
propagating. Restrict the default to the transport- and cluster-level
error set that callers actually want auto-retried (OSError,
TimeoutError, DqliteError); callers that genuinely want "retry
anything" can still override the argument.

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

Author: antoineleclair

src/dqliteclient/retry.py

@@ -4,14 +4,27 @@
 import random
 from collections.abc import Awaitable, Callable
 
+from dqliteclient.exceptions import DqliteError
+
+# Default retry set: transport- and cluster-level errors that a caller
+# could reasonably want auto-retried. Leaves programming bugs
+# (TypeError, AttributeError, KeyError, …) to propagate on first call
+# so debugging is not buried under exponential-backoff pauses. Callers
+# that genuinely want "retry anything" can pass their own tuple.
+_DEFAULT_RETRYABLE: tuple[type[BaseException], ...] = (
+    OSError,
+    TimeoutError,
+    DqliteError,
+)
+
 
 async def retry_with_backoff[T](
     func: Callable[[], Awaitable[T]],
     max_attempts: int = 5,
     base_delay: float = 0.1,
     max_delay: float = 10.0,
     jitter: float = 0.1,
-    retryable_exceptions: tuple[type[Exception], ...] = (Exception,),
+    retryable_exceptions: tuple[type[BaseException], ...] = _DEFAULT_RETRYABLE,
 ) -> T:
     """Retry an async function with exponential backoff.
 
@@ -33,7 +46,7 @@ async def retry_with_backoff[T](
     if max_attempts < 1:
         raise ValueError("max_attempts must be at least 1")
 
-    last_error: Exception | None = None
+    last_error: BaseException | None = None
 
     for attempt in range(max_attempts):
         try:

tests/test_retry.py

@@ -30,7 +30,11 @@ async def fail_then_succeed() -> str:
                 raise ValueError("not yet")
             return "ok"
 
-        result = await retry_with_backoff(fail_then_succeed, base_delay=0.01)
+        result = await retry_with_backoff(
+            fail_then_succeed,
+            base_delay=0.01,
+            retryable_exceptions=(ValueError,),
+        )
         assert result == "ok"
         assert call_count == 3
 
@@ -43,7 +47,12 @@ async def always_fail() -> str:
             raise ValueError("fail")
 
         with pytest.raises(ValueError, match="fail"):
-            await retry_with_backoff(always_fail, max_attempts=3, base_delay=0.01)
+            await retry_with_backoff(
+                always_fail,
+                max_attempts=3,
+                base_delay=0.01,
+                retryable_exceptions=(ValueError,),
+            )
 
         assert call_count == 3
 
@@ -111,7 +120,12 @@ async def mock_sleep(delay: float) -> None:
 
         with patch("dqliteclient.retry.asyncio.sleep", side_effect=mock_sleep):
             await retry_with_backoff(
-                fail_twice, max_attempts=3, base_delay=0.1, max_delay=0.05, jitter=0
+                fail_twice,
+                max_attempts=3,
+                base_delay=0.1,
+                max_delay=0.05,
+                jitter=0,
+                retryable_exceptions=(ValueError,),
             )
 
         assert call_count == 3
@@ -151,9 +165,48 @@ def max_jitter(_low: float, high: float) -> float:
                 base_delay=1.0,
                 max_delay=2.0,
                 jitter=0.1,
+                retryable_exceptions=(ValueError,),
             )
 
         # Several attempts will hit the cap; none should exceed max_delay.
         assert sleep_args, "expected at least one sleep"
         for d in sleep_args:
             assert d <= 2.0, f"delay {d} exceeded max_delay=2.0"
+
+
+class TestRetryDefaults:
+    """The default retryable set is restricted to transport- / cluster-
+    level exceptions; programming bugs propagate on first call."""
+
+    async def test_default_retries_oserror(self) -> None:
+        call_count = 0
+
+        async def fail_once() -> str:
+            nonlocal call_count
+            call_count += 1
+            if call_count < 2:
+                raise OSError("transient")
+            return "ok"
+
+        result = await retry_with_backoff(fail_once, base_delay=0.01)
+        assert result == "ok"
+        assert call_count == 2
+
+    async def test_default_does_not_retry_programming_errors(self) -> None:
+        import pytest as _pytest
+
+        from dqliteclient.retry import retry_with_backoff
+
+        call_count = 0
+
+        async def buggy() -> str:
+            nonlocal call_count
+            call_count += 1
+            raise TypeError("bug")
+
+        with _pytest.raises(TypeError, match="bug"):
+            await retry_with_backoff(buggy, max_attempts=5, base_delay=0.01)
+
+        assert call_count == 1, (
+            "TypeError is outside the default retryable set and must propagate on the first call"
+        )