phoenix-channels-python-client 0.4.2__tar.gz → 0.4.3__tar.gz

{phoenix_channels_python_client-0.4.2/phoenix_channels_python_client.egg-info → phoenix_channels_python_client-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phoenix-channels-python-client
-Version: 0.4.2
+Version: 0.4.3
 Summary: A Python client library for connecting to Phoenix Channels
 Author: Phoenix Channels Python Client
 License-Expression: MIT
@@ -307,6 +307,7 @@ Everything after `api_key` is keyword-only:
 | `on_disconnect` | `None` | `async (error: Exception \| None) -> None`; `None` on a clean close |
 | `on_heartbeat_ack` | `None` | Synchronous `() -> None`; runs on the message path, so keep it fast |
 | `on_topic_lost` | `None` | `async (topic: str, error: Exception) -> None`, called when the client drops a topic you didn't unsubscribe |
+| `reconnect_decider` | `None` | Synchronous `(event: ReconnectEvent) -> ReconnectDecision`; replaces the built-in reconnect policy (see [Owning the reconnect policy](#owning-the-reconnect-policy)) |
 | `additional_headers` | `None` | Extra handshake headers sent on every (re)connect |
 
 Exceptions raised in ordinary message and lifecycle callbacks are logged, not raised.
@@ -340,6 +341,34 @@ base = ReconnectPolicy()
 policy = ReconnectPolicy.model_validate(base.model_dump() | {"max_delay_s": 10.0})
 ```
 
+### Owning the reconnect policy
+
+Pass `reconnect_decider` to make every reconnect decision yourself. While `auto_reconnect` is on, the client calls it with:
+
+- `Connecting()` before every connection attempt, the first included;
+- `Connected(generation)` when a socket is up, before any topic rejoins on it;
+- `Disconnected(close_code, close_reason)` after every close. A forced close (heartbeat expiry, `close_connection()`) has `close_code=None`, since the received code is unreliable then;
+- `ConnectFailed(error)` after every failed attempt, with the raw exception (a refused handshake is a `websockets` `InvalidStatus` carrying the response).
+
+It returns a `ReconnectDecision`:
+
+- `ReconnectDecision(should_reconnect=True, delay_s=2.0)` after `Disconnected` or `ConnectFailed` waits exactly 2 s before the next attempt; `delay_s` defaults to `0`. `Connecting` and `Connected` only proceed or stop, and a delay there stops the client with `PHXConnectionError`.
+- `ReconnectDecision(should_reconnect=False)` stops; `run_forever()` returns `None`, and before the first connection `async with` raises `PHXConnectionError`. A stop at `Connected` closes that socket before any rejoin.
+- `ReconnectDecision(should_reconnect=False, terminal_error=PHXConnectionError(...))` stops; `run_forever()` (or `async with`, before the first connection) raises that error.
+
+The decider replaces the whole built-in policy above, rapid-disconnect suppression included; the built-in policy is itself a decider over the same events. It runs inline on the client's supervisor task, so keep it fast and never block. The client calls the same decider on every `async with` entry, so reset any per-run state yourself; the built-in one is rebuilt each time. If it raises, the client stops with a `PHXConnectionError` whose `__cause__` is that exception; if it returns anything but a `ReconnectDecision` (an `async def` decider returns a coroutine), the client stops with a `PHXConnectionError` too. It is not asked once `shutdown()` has begun. To end a live connection, call `close_connection()` and stop at the next decision.
+
+```python
+def decide(event: ReconnectEvent) -> ReconnectDecision:
+    match event:
+        case ConnectFailed(error=InvalidStatus(response=response)) if response.status_code == 403:
+            return ReconnectDecision(should_reconnect=False, terminal_error=PHXConnectionError("refused"))
+        case Disconnected() | ConnectFailed():
+            return ReconnectDecision(should_reconnect=True, delay_s=1.0)
+        case _:
+            return ReconnectDecision(should_reconnect=True)
+```
+
 ### Channel recovery
 
 A channel can fail while the socket stays up. When its process crashes, the server sends `phx_error`, and the client rejoins that topic on the same socket, waiting the `ReconnectPolicy` backoff (`base_delay_s`, `factor`, `max_delay_s`, with equal jitter) before each attempt. A rejoin that times out is retried the same way, including one after a socket reconnect. A drop of the socket hands the topic to the socket's own rejoin.

{phoenix_channels_python_client-0.4.2 → phoenix_channels_python_client-0.4.3}/README.md

@@ -274,6 +274,7 @@ Everything after `api_key` is keyword-only:
 | `on_disconnect` | `None` | `async (error: Exception \| None) -> None`; `None` on a clean close |
 | `on_heartbeat_ack` | `None` | Synchronous `() -> None`; runs on the message path, so keep it fast |
 | `on_topic_lost` | `None` | `async (topic: str, error: Exception) -> None`, called when the client drops a topic you didn't unsubscribe |
+| `reconnect_decider` | `None` | Synchronous `(event: ReconnectEvent) -> ReconnectDecision`; replaces the built-in reconnect policy (see [Owning the reconnect policy](#owning-the-reconnect-policy)) |
 | `additional_headers` | `None` | Extra handshake headers sent on every (re)connect |
 
 Exceptions raised in ordinary message and lifecycle callbacks are logged, not raised.
@@ -307,6 +308,34 @@ base = ReconnectPolicy()
 policy = ReconnectPolicy.model_validate(base.model_dump() | {"max_delay_s": 10.0})
 ```
 
+### Owning the reconnect policy
+
+Pass `reconnect_decider` to make every reconnect decision yourself. While `auto_reconnect` is on, the client calls it with:
+
+- `Connecting()` before every connection attempt, the first included;
+- `Connected(generation)` when a socket is up, before any topic rejoins on it;
+- `Disconnected(close_code, close_reason)` after every close. A forced close (heartbeat expiry, `close_connection()`) has `close_code=None`, since the received code is unreliable then;
+- `ConnectFailed(error)` after every failed attempt, with the raw exception (a refused handshake is a `websockets` `InvalidStatus` carrying the response).
+
+It returns a `ReconnectDecision`:
+
+- `ReconnectDecision(should_reconnect=True, delay_s=2.0)` after `Disconnected` or `ConnectFailed` waits exactly 2 s before the next attempt; `delay_s` defaults to `0`. `Connecting` and `Connected` only proceed or stop, and a delay there stops the client with `PHXConnectionError`.
+- `ReconnectDecision(should_reconnect=False)` stops; `run_forever()` returns `None`, and before the first connection `async with` raises `PHXConnectionError`. A stop at `Connected` closes that socket before any rejoin.
+- `ReconnectDecision(should_reconnect=False, terminal_error=PHXConnectionError(...))` stops; `run_forever()` (or `async with`, before the first connection) raises that error.
+
+The decider replaces the whole built-in policy above, rapid-disconnect suppression included; the built-in policy is itself a decider over the same events. It runs inline on the client's supervisor task, so keep it fast and never block. The client calls the same decider on every `async with` entry, so reset any per-run state yourself; the built-in one is rebuilt each time. If it raises, the client stops with a `PHXConnectionError` whose `__cause__` is that exception; if it returns anything but a `ReconnectDecision` (an `async def` decider returns a coroutine), the client stops with a `PHXConnectionError` too. It is not asked once `shutdown()` has begun. To end a live connection, call `close_connection()` and stop at the next decision.
+
+```python
+def decide(event: ReconnectEvent) -> ReconnectDecision:
+    match event:
+        case ConnectFailed(error=InvalidStatus(response=response)) if response.status_code == 403:
+            return ReconnectDecision(should_reconnect=False, terminal_error=PHXConnectionError("refused"))
+        case Disconnected() | ConnectFailed():
+            return ReconnectDecision(should_reconnect=True, delay_s=1.0)
+        case _:
+            return ReconnectDecision(should_reconnect=True)
+```
+
 ### Channel recovery
 
 A channel can fail while the socket stays up. When its process crashes, the server sends `phx_error`, and the client rejoins that topic on the same socket, waiting the `ReconnectPolicy` backoff (`base_delay_s`, `factor`, `max_delay_s`, with equal jitter) before each attempt. A rejoin that times out is retried the same way, including one after a socket reconnect. A drop of the socket hands the topic to the socket's own rejoin.

{phoenix_channels_python_client-0.4.2 → phoenix_channels_python_client-0.4.3}/phoenix_channels_python_client/__init__.py

@@ -13,24 +13,40 @@ from phoenix_channels_python_client.client import (
     ReconnectPolicy,
     TopicLostCallback,
 )
-from phoenix_channels_python_client.client_types import JoinResponseCallback
+from phoenix_channels_python_client.client_types import (
+    Connected,
+    ConnectFailed,
+    Connecting,
+    Disconnected,
+    JoinResponseCallback,
+    ReconnectDecider,
+    ReconnectDecision,
+    ReconnectEvent,
+)
 from phoenix_channels_python_client.protocol_handler import (
     PhoenixChannelsProtocolVersion,
     PHXProtocolHandler,
 )
 from phoenix_channels_python_client.utils import setup_logging
 
-__version__ = "0.4.2"
+__version__ = "0.4.3"
 __author__ = "Phoenix Channels Python Client"
 
 __all__ = [
+    "ConnectFailed",
+    "Connected",
+    "Connecting",
     "DisconnectCallback",
+    "Disconnected",
     "HeartbeatAckCallback",
     "JoinResponseCallback",
     "PHXChannelsClient",
     "PHXProtocolHandler",
     "PhoenixChannelsProtocolVersion",
     "ReconnectCallback",
+    "ReconnectDecider",
+    "ReconnectDecision",
+    "ReconnectEvent",
     "ReconnectPolicy",
     "TopicLostCallback",
     "setup_logging",

{phoenix_channels_python_client-0.4.2 → phoenix_channels_python_client-0.4.3}/phoenix_channels_python_client/client.py

@@ -3,7 +3,6 @@ from __future__ import annotations
 import asyncio
 import logging
 import math
-from collections import deque
 from collections.abc import Awaitable, Callable
 from types import TracebackType
 from typing import Self, cast
@@ -19,7 +18,11 @@ from phoenix_channels_python_client.authentication import (
     select_authentication_header,
 )
 from phoenix_channels_python_client.client_state_machine import transition_client_state
-from phoenix_channels_python_client.client_types import ClientState, ReconnectPolicy
+from phoenix_channels_python_client.client_types import (
+    ClientState,
+    ReconnectDecider,
+    ReconnectPolicy,
+)
 from phoenix_channels_python_client.diagnostics import (
     ConnectionLogger,
     diagnostic_secrets,
@@ -114,7 +117,7 @@ def _validate_heartbeat_threshold(
 
 
 class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerMixin):
-    def __init__(  # noqa: PLR0913  # the public options
+    def __init__(  # noqa: PLR0913, PLR0915  # the public options
         self,
         websocket_url: str,
         api_key: str,
@@ -133,6 +136,7 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
         on_disconnect: DisconnectCallback | None = None,
         on_heartbeat_ack: HeartbeatAckCallback | None = None,
         on_topic_lost: TopicLostCallback | None = None,
+        reconnect_decider: ReconnectDecider | None = None,
         additional_headers: dict[str, str] | None = None,
     ) -> None:
         self.additional_headers = normalize_headers(additional_headers)
@@ -185,7 +189,6 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
         self._shutdown_task: asyncio.Task[None] | None = None
         self._message_routing_task: asyncio.Task[None] | None = None
         self._initial_connection_future: asyncio.Future[None] | None = None
-        self._rapid_disconnects: deque[float] = deque()
         self._terminal_error: Exception | None = None
         self._heartbeat_dead_threshold_s = heartbeat_dead_threshold_s
         self._heartbeat_deadline: float | None = None
@@ -197,6 +200,8 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
         self._on_disconnect = on_disconnect
         self._on_heartbeat_ack = on_heartbeat_ack
         self._on_topic_lost = on_topic_lost
+        self._reconnect_decider = reconnect_decider
+        self._decider = self._new_decider()
         self._lifecycle_tasks: set[asyncio.Task[None]] = set()
         self._cleanup_tasks: set[asyncio.Task[None]] = set()
         self._forced_close_pending = False
@@ -226,7 +231,7 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
 
         self._shutdown_event.clear()
         self._connected_event.clear()
-        self._rapid_disconnects.clear()
+        self._decider = self._new_decider()
         self._terminal_error = None
         self._conn_generation = 0
         self._initial_connection_future = asyncio.get_running_loop().create_future()

{phoenix_channels_python_client-0.4.2 → phoenix_channels_python_client-0.4.3}/phoenix_channels_python_client/client_types.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import math
 from collections.abc import Callable
 from dataclasses import dataclass
 from enum import StrEnum
@@ -71,9 +72,61 @@ class ReconnectPolicy(BaseModel):
         return self
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class ReconnectDecision:
+    """Whether the client goes on, and how long it waits before the next attempt.
+
+    ``delay_s`` applies after ``Disconnected`` and ``ConnectFailed``; a gate
+    (``Connecting``, ``Connected``) only proceeds or stops. A stop with a
+    ``terminal_error`` ends the client with that error.
+    """
+
     should_reconnect: bool
-    min_delay_s: float | None = None
-    max_delay_s: float | None = None
+    delay_s: float = 0.0
     terminal_error: PHXConnectionError | None = None
+
+    def __post_init__(self) -> None:
+        if not math.isfinite(self.delay_s) or self.delay_s < 0:
+            raise ValueError("delay_s must be finite and >= 0")
+        if not self.should_reconnect and self.delay_s:
+            raise ValueError("a stop has no delay_s")
+        if self.should_reconnect and self.terminal_error is not None:
+            raise ValueError("a terminal_error requires should_reconnect=False")
+
+
+PROCEED = ReconnectDecision(should_reconnect=True)
+
+
+@dataclass(frozen=True)
+class Connecting:
+    """A connection attempt is about to start."""
+
+
+@dataclass(frozen=True)
+class Connected:
+    """The socket for ``generation`` is up; topics rejoin only if this proceeds."""
+
+    generation: int
+
+
+@dataclass(frozen=True)
+class Disconnected:
+    """The connection closed. ``close_code`` is ``None`` for a forced close."""
+
+    close_code: int | None
+    close_reason: str
+
+
+@dataclass(frozen=True)
+class ConnectFailed:
+    """A connection attempt failed with ``error``, e.g. a refused handshake."""
+
+    error: Exception
+
+
+ReconnectEvent = Connecting | Connected | Disconnected | ConnectFailed
+
+# Decision points that only proceed or stop; no attempt follows them to delay.
+GATE_EVENTS = (Connecting, Connected)
+
+ReconnectDecider = Callable[[ReconnectEvent], ReconnectDecision]

phoenix_channels_python_client-0.4.3/phoenix_channels_python_client/default_decider.py

@@ -0,0 +1,228 @@
+"""The built-in reconnect policy, as a ``reconnect_decider``."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import random
+from collections import deque
+from http import HTTPStatus
+
+from websockets.exceptions import InvalidStatus
+from websockets.frames import CloseCode
+
+from phoenix_channels_python_client.client_types import (
+    PROCEED,
+    Connected,
+    ConnectFailed,
+    Disconnected,
+    ReconnectDecision,
+    ReconnectEvent,
+    ReconnectPolicy,
+)
+from phoenix_channels_python_client.exceptions import PHXConnectionError
+
+# The Band platform answers every auth refusal with 403, and its websocket spec
+# (thenvoi-platform spec/websocket-api.draft.md) makes a rejected reconnect terminal.
+# A 401 could only come from an edge layer, so it and every other status retry.
+TERMINAL_HANDSHAKE_STATUS = HTTPStatus.FORBIDDEN
+
+# A (low, high) range a close's backoff is raised into.
+DelayRange = tuple[float, float]
+
+
+def random_between(min_delay_s: float, max_delay_s: float) -> float:
+    low = max(0.0, min_delay_s)
+    high = max(low, max_delay_s)
+    if high == low:
+        return low
+    return low + (random.random() * (high - low))  # noqa: S311  # jitter
+
+
+def exponential_delay(policy: ReconnectPolicy, attempt: int) -> float:
+    """The policy's capped exponential backoff for ``attempt``, unjittered."""
+    return min(
+        policy.max_delay_s,
+        policy.base_delay_s * (policy.factor ** max(attempt, 0)),
+    )
+
+
+def equal_jitter(delay: float) -> float:
+    # Equal jitter avoids synchronization while keeping a meaningful minimum delay.
+    return random_between(delay / 2, delay)
+
+
+def _now() -> float:
+    return asyncio.get_running_loop().time()
+
+
+def _terminal_decision(cause: str) -> ReconnectDecision:
+    return ReconnectDecision(
+        should_reconnect=False,
+        terminal_error=PHXConnectionError(
+            f"Reconnect disabled due to terminal {cause}"
+        ),
+    )
+
+
+class DefaultReconnectDecider:
+    """Classifies closes and refusals, backs off, and stops on rapid churn.
+
+    Holds one run's backoff attempt and rapid-disconnect history, so the client
+    builds a fresh one each time it is entered.
+    """
+
+    def __init__(self, policy: ReconnectPolicy, logger: logging.Logger) -> None:
+        self._policy = policy
+        self._logger = logger
+        self._attempt = 0
+        self._rapid_disconnects: deque[float] = deque()
+        self._connected_at = 0.0
+
+    def __call__(self, event: ReconnectEvent) -> ReconnectDecision:
+        match event:
+            case Connected():
+                self._connected_at = _now()
+                return PROCEED
+            case Disconnected():
+                return self._after_close(event.close_code, event.close_reason)
+            case ConnectFailed():
+                return self._after_connect_failure(event.error)
+            case _:  # Connecting: always attempt.
+                return PROCEED
+
+    def _after_close(
+        self, close_code: int | None, close_reason: str
+    ) -> ReconnectDecision:
+        stop = self._stop_for_close(close_code, close_reason)
+        if stop is not None:
+            return stop
+        uptime_s = _now() - self._connected_at
+        if self._suppressed(uptime_s):
+            return self._suppression()
+        if uptime_s >= self._policy.stable_reset_s:
+            self._attempt = 0
+            self._rapid_disconnects.clear()
+        else:
+            self._attempt += 1
+        delay = self._backoff(self._attempt)
+        delay_range = self._delay_range_for_close(close_code)
+        if delay_range is not None:
+            delay = max(delay, random_between(*delay_range))
+        return ReconnectDecision(should_reconnect=True, delay_s=delay)
+
+    def _after_connect_failure(self, error: Exception) -> ReconnectDecision:
+        if (
+            isinstance(error, InvalidStatus)
+            and error.response.status_code == TERMINAL_HANDSHAKE_STATUS
+        ):
+            return _terminal_decision(
+                f"handshake status {TERMINAL_HANDSHAKE_STATUS} "
+                f"({TERMINAL_HANDSHAKE_STATUS.phrase})"
+            )
+        if self._suppressed(0.0):
+            return self._suppression()
+        delay = self._backoff(self._attempt)
+        self._attempt += 1
+        return ReconnectDecision(should_reconnect=True, delay_s=delay)
+
+    def _stop_for_close(
+        self, close_code: int | None, close_reason: str
+    ) -> ReconnectDecision | None:
+        if (
+            close_code in {CloseCode.NORMAL_CLOSURE, CloseCode.GOING_AWAY}
+            and not self._policy.reconnect_on_normal_close
+        ):
+            return ReconnectDecision(should_reconnect=False)
+        if (
+            close_code == CloseCode.POLICY_VIOLATION
+            and self._policy.policy_violation_is_terminal
+        ):
+            reason = close_reason or "policy violation"
+            return _terminal_decision(
+                f"close code {CloseCode.POLICY_VIOLATION} ({reason})"
+            )
+        return None
+
+    def _delay_range_for_close(self, close_code: int | None) -> DelayRange | None:
+        policy = self._policy
+        match close_code:
+            case CloseCode.SERVICE_RESTART:
+                return (
+                    policy.service_restart_min_delay_s,
+                    policy.service_restart_max_delay_s,
+                )
+            case CloseCode.TRY_AGAIN_LATER:
+                return (
+                    policy.try_again_later_min_delay_s,
+                    policy.try_again_later_max_delay_s,
+                )
+            case _:
+                return None
+
+    def _suppressed(self, uptime_s: float) -> bool:
+        """Record a disconnect after ``uptime_s``; whether churn now stops us."""
+        now = _now()
+        if uptime_s < self._policy.rapid_disconnect_uptime_s:
+            self._rapid_disconnects.append(now)
+        while (
+            self._rapid_disconnects
+            and now - self._rapid_disconnects[0] > self._policy.rapid_window_s
+        ):
+            self._rapid_disconnects.popleft()
+        threshold = self._policy.rapid_suppress_disconnect_count
+        rapid_count = len(self._rapid_disconnects)
+        self._logger.debug(
+            "Recorded disconnect. uptime_s=%s rapid_count=%s threshold=%s",
+            uptime_s,
+            rapid_count,
+            threshold,
+        )
+        return threshold > 0 and rapid_count >= threshold
+
+    def _suppression(self) -> ReconnectDecision:
+        return ReconnectDecision(
+            should_reconnect=False,
+            terminal_error=PHXConnectionError(
+                "Reconnect suppressed after repeated rapid disconnects. "
+                "Likely duplicate connection or unstable endpoint."
+            ),
+        )
+
+    def _rapid_floors(self) -> tuple[float, ...]:
+        """The floor for each rapid-disconnect count before the cooldown starts."""
+        return (
+            0.0,
+            self._policy.rapid_first_min_delay_s,
+            self._policy.rapid_second_min_delay_s,
+        )
+
+    def _backoff(self, attempt: int) -> float:
+        """The jittered wait for ``attempt``, raised to the rapid-disconnect floor."""
+        rapid_count = len(self._rapid_disconnects)
+        cooldown_steps = rapid_count - len(self._rapid_floors())
+        if cooldown_steps < 0:
+            floor = self._rapid_floors()[rapid_count]
+        else:
+            floor = min(
+                self._policy.rapid_cooldown_base_s
+                + (self._policy.rapid_cooldown_step_s * cooldown_steps),
+                self._policy.rapid_cooldown_max_s,
+            )
+        delay = max(exponential_delay(self._policy, attempt), floor)
+        if delay <= 0:
+            return 0.0
+        if cooldown_steps < 0:
+            computed = equal_jitter(delay)
+        else:
+            computed = random_between(
+                delay * self._policy.rapid_hold_down_jitter_low_ratio,
+                delay * self._policy.rapid_hold_down_jitter_high_ratio,
+            )
+        self._logger.debug(
+            "Computed reconnect delay. attempt=%s rapid_count=%s computed_delay_s=%s",
+            attempt,
+            rapid_count,
+            computed,
+        )
+        return computed

phoenix_channels_python_client-0.4.3/phoenix_channels_python_client/reconnect_controller.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import inspect
+import logging
+
+from websockets import ClientConnection
+from websockets.exceptions import ConnectionClosed
+
+from phoenix_channels_python_client.client_types import (
+    GATE_EVENTS,
+    ReconnectDecider,
+    ReconnectDecision,
+    ReconnectEvent,
+    ReconnectPolicy,
+)
+from phoenix_channels_python_client.default_decider import (
+    DefaultReconnectDecider,
+    equal_jitter,
+    exponential_delay,
+)
+from phoenix_channels_python_client.exceptions import PHXConnectionError
+
+
+def _decider_failure(message: str, cause: Exception | None = None) -> ReconnectDecision:
+    """A stop for a broken decider; never the built-in policy deciding instead."""
+    error = PHXConnectionError(message)
+    error.__cause__ = cause
+    return ReconnectDecision(should_reconnect=False, terminal_error=error)
+
+
+class ReconnectControllerMixin:
+    logger: logging.Logger
+
+    def redact_diagnostic(self, text: str) -> str:
+        raise NotImplementedError
+
+    reconnect_policy: ReconnectPolicy
+    _reconnect_decider: ReconnectDecider | None
+    _decider: ReconnectDecider
+
+    def _new_decider(self) -> ReconnectDecider:
+        """The consumer's decider, or a fresh built-in one for this run."""
+        if self._reconnect_decider is not None:
+            return self._reconnect_decider
+        return DefaultReconnectDecider(self.reconnect_policy, self.logger)
+
+    def _decide(self, event: ReconnectEvent) -> ReconnectDecision:
+        """The decider's answer to ``event``; a broken answer stops the client."""
+        try:
+            decision = self._decider(event)
+        except Exception as exc:
+            self.logger.exception("reconnect_decider failed; stopping the client")
+            return _decider_failure("reconnect_decider failed", exc)
+        if inspect.iscoroutine(decision):
+            decision.close()  # Never awaited; closed so it raises no warning.
+            return _decider_failure("reconnect_decider must be synchronous")
+        if not isinstance(decision, ReconnectDecision):
+            return _decider_failure("reconnect_decider returned no ReconnectDecision")
+        if decision.delay_s and isinstance(event, GATE_EVENTS):
+            # No attempt follows a gate, so its delay would be silently dropped.
+            return _decider_failure("reconnect_decider returned a delay for a gate")
+        return decision
+
+    def _channel_rejoin_delay(self, attempt: int) -> float:
+        # No rapid-disconnect floors: those describe socket churn, not one channel.
+        return equal_jitter(exponential_delay(self.reconnect_policy, attempt))
+
+    def _extract_close_details(
+        self,
+        *,
+        connection: ClientConnection,
+        routing_error: Exception | None,
+    ) -> tuple[int | None, str]:
+        if isinstance(routing_error, ConnectionClosed):
+            if routing_error.rcvd is not None:
+                return routing_error.rcvd.code, routing_error.rcvd.reason
+            if routing_error.sent is not None:
+                return routing_error.sent.code, routing_error.sent.reason
+        return connection.close_code, connection.close_reason or ""