phoenix-channels-python-client 0.4.2__py3-none-any.whl → 0.4.4__py3-none-any.whl

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.4"
 __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/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()
@@ -236,7 +241,8 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
 
         try:
             await self._initial_connection_future
-        except Exception:
+        except (Exception, asyncio.CancelledError):
+            # Not BaseException: awaiting cleanup on GeneratorExit raises RuntimeError.
             await self.shutdown("Initial connection failed")
             raise
 

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/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/reconnect_controller.py

@@ -1,34 +1,31 @@
 from __future__ import annotations
 
-import asyncio
+import inspect
 import logging
-import random
-from collections import deque
-from http import HTTPStatus
 
 from websockets import ClientConnection
-from websockets.exceptions import ConnectionClosed, InvalidStatus
-from websockets.frames import CloseCode
+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
 
-# 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
-
 
-def _terminal_decision(cause: str) -> ReconnectDecision:
-    return ReconnectDecision(
-        should_reconnect=False,
-        terminal_error=PHXConnectionError(
-            f"Reconnect disabled due to terminal {cause}"
-        ),
-    )
+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:
@@ -38,137 +35,35 @@ class ReconnectControllerMixin:
         raise NotImplementedError
 
     reconnect_policy: ReconnectPolicy
-    _rapid_disconnects: deque[float]
-
-    def _prune_rapid_disconnects(self, now: float) -> None:
-        while (
-            self._rapid_disconnects
-            and now - self._rapid_disconnects[0] > self.reconnect_policy.rapid_window_s
-        ):
-            self._rapid_disconnects.popleft()
-
-    def _record_disconnect(self, connection_uptime_s: float) -> None:
-        now = asyncio.get_running_loop().time()
-        if connection_uptime_s < self.reconnect_policy.rapid_disconnect_uptime_s:
-            self._rapid_disconnects.append(now)
-        self._prune_rapid_disconnects(now)
-        self.logger.debug(
-            "Recorded disconnect. uptime_s=%s rapid_count=%s rapid_window_s=%s",
-            connection_uptime_s,
-            len(self._rapid_disconnects),
-            self.reconnect_policy.rapid_window_s,
-            extra={
-                "connection_uptime_s": connection_uptime_s,
-                "rapid_count": len(self._rapid_disconnects),
-                "rapid_window_s": self.reconnect_policy.rapid_window_s,
-            },
-        )
-
-    def _should_suppress_reconnect(self) -> bool:
-        threshold = self.reconnect_policy.rapid_suppress_disconnect_count
-        should_suppress = threshold > 0 and len(self._rapid_disconnects) >= threshold
-        if should_suppress:
-            self.logger.debug(
-                "Reconnect suppression threshold met. rapid_count=%s threshold=%s",
-                len(self._rapid_disconnects),
-                threshold,
-                extra={
-                    "rapid_count": len(self._rapid_disconnects),
-                    "threshold": threshold,
-                },
-            )
-        return should_suppress
-
-    def _rapid_floors(self) -> tuple[float, ...]:
-        """The floor for each rapid-disconnect count before the cooldown starts."""
-        return (
-            0.0,
-            self.reconnect_policy.rapid_first_min_delay_s,
-            self.reconnect_policy.rapid_second_min_delay_s,
-        )
-
-    def _rapid_cooldown_steps(self, rapid_count: int) -> int:
-        """Steps into the cooldown; negative while a floor still applies."""
-        return rapid_count - len(self._rapid_floors())
-
-    def _rapid_min_delay(self, rapid_count: int) -> float:
-        steps = self._rapid_cooldown_steps(rapid_count)
-        if steps < 0:
-            return self._rapid_floors()[rapid_count]
-        return min(
-            self.reconnect_policy.rapid_cooldown_base_s
-            + (self.reconnect_policy.rapid_cooldown_step_s * steps),
-            self.reconnect_policy.rapid_cooldown_max_s,
-        )
-
-    def _exponential_delay(self, attempt: int) -> float:
-        """The policy's capped exponential backoff for ``attempt``, unjittered."""
-        return min(
-            self.reconnect_policy.max_delay_s,
-            self.reconnect_policy.base_delay_s
-            * (self.reconnect_policy.factor ** max(attempt, 0)),
-        )
-
-    def _equal_jitter(self, delay: float) -> float:
-        # Equal jitter avoids synchronization while keeping a meaningful minimum delay.
-        return self._random_between(delay / 2, delay)
+    _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 self._equal_jitter(self._exponential_delay(attempt))
-
-    def _compute_reconnect_delay(self, attempt: int) -> float:
-        base_delay = self._exponential_delay(attempt)
-
-        rapid_count = len(self._rapid_disconnects)
-        min_delay = self._rapid_min_delay(rapid_count)
-
-        delay = max(base_delay, min_delay)
-        if delay <= 0:
-            return 0.0
-
-        if self._rapid_cooldown_steps(rapid_count) >= 0:
-            low_ratio = self.reconnect_policy.rapid_hold_down_jitter_low_ratio
-            high_ratio = self.reconnect_policy.rapid_hold_down_jitter_high_ratio
-            min_jittered = delay * low_ratio
-            max_jittered = delay * high_ratio
-            computed = self._random_between(min_jittered, max_jittered)
-            self.logger.debug(
-                "Computed reconnect delay with hold-down jitter. attempt=%s "
-                "rapid_count=%s base_delay_s=%s min_delay_s=%s computed_delay_s=%s",
-                attempt,
-                rapid_count,
-                base_delay,
-                min_delay,
-                computed,
-                extra={
-                    "attempt": attempt,
-                    "rapid_count": rapid_count,
-                    "base_delay_s": base_delay,
-                    "min_delay_s": min_delay,
-                    "computed_delay_s": computed,
-                },
-            )
-            return computed
-
-        computed = self._equal_jitter(delay)
-        self.logger.debug(
-            "Computed reconnect delay with equal jitter. attempt=%s rapid_count=%s "
-            "base_delay_s=%s min_delay_s=%s computed_delay_s=%s",
-            attempt,
-            rapid_count,
-            base_delay,
-            min_delay,
-            computed,
-            extra={
-                "attempt": attempt,
-                "rapid_count": rapid_count,
-                "base_delay_s": base_delay,
-                "min_delay_s": min_delay,
-                "computed_delay_s": computed,
-            },
-        )
-        return computed
+        return equal_jitter(exponential_delay(self.reconnect_policy, attempt))
 
     def _extract_close_details(
         self,
@@ -182,160 +77,3 @@ class ReconnectControllerMixin:
             if routing_error.sent is not None:
                 return routing_error.sent.code, routing_error.sent.reason
         return connection.close_code, connection.close_reason or ""
-
-    def _classify_disconnect(
-        self, close_code: int | None, close_reason: str
-    ) -> ReconnectDecision:
-        if close_code is None:
-            decision = ReconnectDecision(should_reconnect=True)
-            self.logger.debug(
-                "Disconnect classification result. close_code=%s close_reason=%s "
-                "should_reconnect=%s",
-                close_code,
-                close_reason,
-                decision.should_reconnect,
-                extra={
-                    "close_code": close_code,
-                    "close_reason": close_reason,
-                    "should_reconnect": decision.should_reconnect,
-                },
-            )
-            return decision
-
-        if (
-            close_code in {CloseCode.NORMAL_CLOSURE, CloseCode.GOING_AWAY}
-            and not self.reconnect_policy.reconnect_on_normal_close
-        ):
-            decision = ReconnectDecision(should_reconnect=False)
-            self.logger.debug(
-                "Disconnect classification result. close_code=%s close_reason=%s "
-                "should_reconnect=%s",
-                close_code,
-                close_reason,
-                decision.should_reconnect,
-                extra={
-                    "close_code": close_code,
-                    "close_reason": close_reason,
-                    "should_reconnect": decision.should_reconnect,
-                },
-            )
-            return decision
-
-        if (
-            close_code == CloseCode.POLICY_VIOLATION
-            and self.reconnect_policy.policy_violation_is_terminal
-        ):
-            reason = close_reason or "policy violation"
-            decision = _terminal_decision(
-                f"close code {CloseCode.POLICY_VIOLATION} ({reason})"
-            )
-            self.logger.debug(
-                "Disconnect classification result. close_code=%s close_reason=%s "
-                "should_reconnect=%s terminal=%s",
-                close_code,
-                close_reason,
-                decision.should_reconnect,
-                decision.terminal_error,
-                extra={
-                    "close_code": close_code,
-                    "close_reason": close_reason,
-                    "should_reconnect": decision.should_reconnect,
-                    "terminal": True,
-                },
-            )
-            return decision
-
-        if close_code == CloseCode.SERVICE_RESTART:
-            decision = ReconnectDecision(
-                should_reconnect=True,
-                min_delay_s=self.reconnect_policy.service_restart_min_delay_s,
-                max_delay_s=self.reconnect_policy.service_restart_max_delay_s,
-            )
-            self.logger.debug(
-                "Disconnect classification result. close_code=%s close_reason=%s "
-                "should_reconnect=%s min_delay_s=%s max_delay_s=%s",
-                close_code,
-                close_reason,
-                decision.should_reconnect,
-                decision.min_delay_s,
-                decision.max_delay_s,
-                extra={
-                    "close_code": close_code,
-                    "close_reason": close_reason,
-                    "should_reconnect": decision.should_reconnect,
-                    "min_delay_s": decision.min_delay_s,
-                    "max_delay_s": decision.max_delay_s,
-                },
-            )
-            return decision
-
-        if close_code == CloseCode.TRY_AGAIN_LATER:
-            decision = ReconnectDecision(
-                should_reconnect=True,
-                min_delay_s=self.reconnect_policy.try_again_later_min_delay_s,
-                max_delay_s=self.reconnect_policy.try_again_later_max_delay_s,
-            )
-            self.logger.debug(
-                "Disconnect classification result. close_code=%s close_reason=%s "
-                "should_reconnect=%s min_delay_s=%s max_delay_s=%s",
-                close_code,
-                close_reason,
-                decision.should_reconnect,
-                decision.min_delay_s,
-                decision.max_delay_s,
-                extra={
-                    "close_code": close_code,
-                    "close_reason": close_reason,
-                    "should_reconnect": decision.should_reconnect,
-                    "min_delay_s": decision.min_delay_s,
-                    "max_delay_s": decision.max_delay_s,
-                },
-            )
-            return decision
-
-        decision = ReconnectDecision(should_reconnect=True)
-        self.logger.debug(
-            "Disconnect classification result. close_code=%s close_reason=%s "
-            "should_reconnect=%s",
-            close_code,
-            close_reason,
-            decision.should_reconnect,
-            extra={
-                "close_code": close_code,
-                "close_reason": close_reason,
-                "should_reconnect": decision.should_reconnect,
-            },
-        )
-        return decision
-
-    def _classify_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})"
-            )
-        return ReconnectDecision(should_reconnect=True)
-
-    def _apply_disconnect_delay_override(
-        self,
-        computed_delay_s: float,
-        decision: ReconnectDecision,
-    ) -> float:
-        if decision.min_delay_s is None:
-            return computed_delay_s
-
-        if decision.max_delay_s is None:
-            return max(computed_delay_s, decision.min_delay_s)
-
-        override = self._random_between(decision.min_delay_s, decision.max_delay_s)
-        return max(computed_delay_s, override)
-
-    def _random_between(self, 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

phoenix_channels_python_client/supervisor.py

@@ -3,7 +3,6 @@ from __future__ import annotations
 import asyncio
 import inspect
 import logging
-from collections import deque
 from collections.abc import Awaitable, Callable
 from contextlib import nullcontext
 from typing import NamedTuple, Protocol, cast
@@ -14,8 +13,12 @@ from websockets.protocol import State
 
 from phoenix_channels_python_client.client_types import (
     ClientState,
+    Connected,
+    ConnectFailed,
+    Connecting,
+    Disconnected,
     ReconnectDecision,
-    ReconnectPolicy,
+    ReconnectEvent,
 )
 from phoenix_channels_python_client.exceptions import PHXConnectionError
 from phoenix_channels_python_client.phx_messages import (
@@ -28,9 +31,8 @@ from phoenix_channels_python_client.shutdown_signals import handle_shutdown_sign
 from phoenix_channels_python_client.topic_subscription import TopicSubscription
 from phoenix_channels_python_client.utils import cancel_and_wait, make_message
 
-# RFC 6455 §7.4.2 private-use range (4000-4999, unregistrable); outside
-# _classify_disconnect's specially-handled codes, so a forced close
-# reconnects like any other unclassified disconnect.
+# RFC 6455 §7.4.2 private-use range (4000-4999, unregistrable). The decider
+# never sees it: a forced close is decided with close_code=None.
 _FORCED_CLOSE_CODE = 4000
 
 # RFC 6455 §5.5.1: control frames (including Close) cap at 125 bytes total;
@@ -58,19 +60,10 @@ class _SupervisorRuntimeDeps(Protocol):
     async def _rejoin_topics(self, generation: int) -> None: ...
     def _fail_pending_joins(self, error: Exception) -> None: ...
     def _channel_recoveries(self) -> list[asyncio.Task[None]]: ...
-    def _record_disconnect(self, connection_uptime_s: float) -> None: ...
-    def _should_suppress_reconnect(self) -> bool: ...
-    def _compute_reconnect_delay(self, attempt: int) -> float: ...
     def _extract_close_details(
         self, *, connection: ClientConnection, routing_error: Exception | None
     ) -> tuple[int | None, str]: ...
-    def _classify_disconnect(
-        self, close_code: int | None, close_reason: str
-    ) -> ReconnectDecision: ...
-    def _classify_connect_failure(self, error: Exception) -> ReconnectDecision: ...
-    def _apply_disconnect_delay_override(
-        self, computed_delay_s: float, decision: ReconnectDecision
-    ) -> float: ...
+    def _decide(self, event: ReconnectEvent) -> ReconnectDecision: ...
     def _transition_state(self, new_state: ClientState) -> None: ...
     async def shutdown(self, reason: str) -> None: ...
 
@@ -81,7 +74,6 @@ class SupervisorMixin:
     channel_socket_url_redacted: str
     additional_headers: dict[str, str]
     auto_reconnect: bool
-    reconnect_policy: ReconnectPolicy
     connection: ClientConnection | None
     _topic_subscriptions: dict[str, TopicSubscription]
     _protocol_handler: PHXProtocolHandler
@@ -92,7 +84,6 @@ class SupervisorMixin:
     _supervisor_task: asyncio.Task[None] | None
     _message_routing_task: asyncio.Task[None] | None
     _initial_connection_future: asyncio.Future[None] | None
-    _rapid_disconnects: deque[float]
     _terminal_error: Exception | None
     _heartbeat_dead_threshold_s: float | None
     _heartbeat_deadline: float | None
@@ -239,42 +230,29 @@ class SupervisorMixin:
             self.logger.debug("Sent heartbeat (ref=%s)", ref)
 
     async def _supervisor_loop(self) -> None:
-        attempt = 0
         try:
             while not self._shutdown_event.is_set():
+                if self.auto_reconnect and self._proceeds(Connecting()) is None:
+                    break
                 try:
                     connection = await self._connect()
                 except Exception as exc:  # noqa: BLE001  # each failure is retried
-                    if not self._retry_after_connect_failure(exc):
+                    decision = self._retry_after_connect_failure(exc)
+                    if decision is None:
                         break
-                    delay = self._deps._compute_reconnect_delay(attempt=attempt)
-                    attempt += 1
-                    await self._wait_for_shutdown_or_timeout(delay)
+                    await self._wait_for_shutdown_or_timeout(decision.delay_s)
                     continue
 
-                if not self._adopt_connection(connection):
+                if not await self._adopt_connection(connection):
                     break
-                connected_since = asyncio.get_running_loop().time()
                 routing = await self._start_session(connection)
                 routing_error = await self._await_routing(routing)
                 close = await self._end_session(connection, routing_error)
                 decision = self._decide_reconnect(close)
                 if decision is None:
                     break
-
-                uptime = asyncio.get_running_loop().time() - connected_since
-                if self._suppressed_after_disconnect(uptime):
-                    break
-                if uptime >= self.reconnect_policy.stable_reset_s:
-                    attempt = 0
-                    self._rapid_disconnects.clear()
-                else:
-                    attempt += 1
-
                 self._deps._transition_state(ClientState.RECONNECTING)
-                delay = self._deps._compute_reconnect_delay(attempt=attempt)
-                delay = self._deps._apply_disconnect_delay_override(delay, decision)
-                await self._wait_for_shutdown_or_timeout(delay)
+                await self._wait_for_shutdown_or_timeout(decision.delay_s)
         finally:
             self._settle_supervisor_exit()
 
@@ -285,7 +263,8 @@ class SupervisorMixin:
             logger=self.logger,
         )
 
-    def _retry_after_connect_failure(self, exc: Exception) -> bool:
+    def _retry_after_connect_failure(self, exc: Exception) -> ReconnectDecision | None:
+        """The decision to retry after ``exc``, or ``None`` to stop."""
         if not self.auto_reconnect:
             self._settle_initial_connection(
                 PHXConnectionError(
@@ -296,35 +275,38 @@ class SupervisorMixin:
                 )
             )
             self.logger.error("Connection failed and auto_reconnect=False: %s", exc)
-            return False
+            return None
         # A requested stop outranks a refusal's terminal error.
         if self._shutdown_event.is_set():
             self.logger.debug(
                 "Ignoring a connect failure after shutdown began: %s", exc
             )
-            return False
-        decision = self._deps._classify_connect_failure(exc)
-        if decision.terminal_error is not None:
-            self._record_terminal_error(decision.terminal_error)
-            return False
-        if self._suppressed_after_disconnect(0.0):
-            return False
-        self._deps._transition_state(ClientState.RECONNECTING)
-        return True
+            return None
+        decision = self._proceeds(ConnectFailed(exc))
+        if decision is not None:
+            self._deps._transition_state(ClientState.RECONNECTING)
+        return decision
 
-    def _adopt_connection(self, connection: ClientConnection) -> bool:
+    async def _adopt_connection(self, connection: ClientConnection) -> bool:
         self.connection = connection
         if self._shutdown_event.is_set():
             # shutdown() began during the handshake; its own cleanup closes
             # this socket.
             return False
+        self._conn_generation += 1
+        if (
+            self.auto_reconnect
+            and self._proceeds(Connected(self._conn_generation)) is None
+        ):
+            # Refused before any topic rejoins on it.
+            await self._cleanup_connection()
+            return False
         self._heartbeat_deadline = (
             asyncio.get_running_loop().time() + self._heartbeat_dead_threshold_s
             if self._heartbeat_interval_s is not None
             and self._heartbeat_dead_threshold_s is not None
             else None
         )
-        self._conn_generation += 1
         self._connected_event.set()
         self._deps._transition_state(ClientState.CONNECTED)
         return True
@@ -392,36 +374,25 @@ class SupervisorMixin:
         if self._shutdown_event.is_set() or not self.auto_reconnect:
             return None
 
-        if close.forced:
-            # websockets reports the close code it received, not the one we
-            # sent, so classifying a forced close would be unreliable.
-            decision = ReconnectDecision(should_reconnect=True)
-        else:
-            decision = self._deps._classify_disconnect(close.code, close.reason)
+        # websockets reports the close code it received, not the one we sent,
+        # so a forced close carries no code to decide on.
+        event = (
+            Disconnected(close_code=None, close_reason="")
+            if close.forced
+            else Disconnected(close_code=close.code, close_reason=close.reason)
+        )
+        return self._proceeds(event)
+
+    def _proceeds(self, event: ReconnectEvent) -> ReconnectDecision | None:
+        """The decision to go on after ``event``, or ``None`` when it stops."""
+        decision = self._deps._decide(event)
+        if decision.should_reconnect:
+            return decision
         if decision.terminal_error is not None:
             self._record_terminal_error(decision.terminal_error)
-            return None
-
-        if not decision.should_reconnect:
-            self.logger.info(
-                "Reconnect disabled for close code %s reason=%s",
-                close.code,
-                close.reason,
-            )
-            return None
-        return decision
-
-    def _suppressed_after_disconnect(self, uptime_s: float) -> bool:
-        self._deps._record_disconnect(connection_uptime_s=uptime_s)
-        if not self._deps._should_suppress_reconnect():
-            return False
-        self._record_terminal_error(
-            PHXConnectionError(
-                "Reconnect suppressed after repeated rapid disconnects. "
-                "Likely duplicate connection or unstable endpoint."
-            )
-        )
-        return True
+        else:
+            self.logger.info("Reconnect stopped by the reconnect policy")
+        return None
 
     def _record_terminal_error(self, error: PHXConnectionError) -> None:
         self._terminal_error = error

{phoenix_channels_python_client-0.4.2.dist-info → phoenix_channels_python_client-0.4.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phoenix-channels-python-client
-Version: 0.4.2
+Version: 0.4.4
 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.dist-info → phoenix_channels_python_client-0.4.4.dist-info}/RECORD

@@ -1,20 +1,21 @@
-phoenix_channels_python_client/__init__.py,sha256=U7e0kRYKad0m3hB-dGHHw72cAp2yFmcD1dEy7y9MUsg,944
+phoenix_channels_python_client/__init__.py,sha256=sskkEUbwcMux5BkaBeH6X7CZlLBC_VoIW1QYRSlL-5E,1233
 phoenix_channels_python_client/authentication.py,sha256=r_UtblJDKr0ynUyxf_WDoMdErDcqvKD8y_iip-PLR-0,1353
-phoenix_channels_python_client/client.py,sha256=TM0glWR-k9nscbeXZhSbpwjP1f_hwvmBf6RFKGKWP0Q,12413
+phoenix_channels_python_client/client.py,sha256=IlF_vF399lNkPZMTl7VL67glJ7NCLJuWNv3pvCXPtv8,12644
 phoenix_channels_python_client/client_state_machine.py,sha256=pjIHK55C4MZII_xnEOZXfiJ6drNrLcC0EPtWXRRGUuY,1090
-phoenix_channels_python_client/client_types.py,sha256=VFfOcV3gtse6_FXbZ8Rv3VgNH0UWw17t-AxSjK8zSA0,2725
+phoenix_channels_python_client/client_types.py,sha256=yvayfL9ynDsx1kXG976ZFR8pWY64SFYYJUbC550x08U,4304
+phoenix_channels_python_client/default_decider.py,sha256=R_EuLtatl19rqNfkGB0N0bnSA_oTSGaxm2f894fsKd0,8191
 phoenix_channels_python_client/diagnostics.py,sha256=vaf3pDIZvRTNh1QZCVgPKPAlQaonl9of1JQ5Ow7Cvf8,3987
 phoenix_channels_python_client/exceptions.py,sha256=_fS9Zfn751WmykTnDCcJjGpVCRrUqgqPUpTI3B-xzF0,217
 phoenix_channels_python_client/phx_messages.py,sha256=F_uW79oNaJm6Mpm9wtSrLIJL0KVPQMRA7E5l0-S6j0Q,1614
 phoenix_channels_python_client/protocol_handler.py,sha256=J5kHCcFVltwQH-4PJZxsQA0NTQE7jqjvZ8jmP5tWN54,8967
-phoenix_channels_python_client/reconnect_controller.py,sha256=N7LUIbSzptGOqIwSlYROLm1nZklL_i53i9nID0ytJ_w,13120
+phoenix_channels_python_client/reconnect_controller.py,sha256=a1ER5D-AKviY3fEJiIzUJ_whE5Y-eUugfnLeDtP6xGQ,3149
 phoenix_channels_python_client/shutdown_signals.py,sha256=qbcfJnp7pBcu07WolZyJyqNarFaUb0f7GaasqZGvi9E,4067
-phoenix_channels_python_client/supervisor.py,sha256=Y486DE6At_C0BbZxQn3Y37_PMhpry49ygXwrOnZGoGw,22020
+phoenix_channels_python_client/supervisor.py,sha256=TzdQq8K6PLja1soBU1esDHVR3kMLX190ZFCPCuoSnZA,20742
 phoenix_channels_python_client/topic_runtime.py,sha256=zSccUxUZ1UVcawHR--OTNaXCR64Wn0WQhXuhyNnoizo,36414
 phoenix_channels_python_client/topic_subscription.py,sha256=CMlBbXB6fLiFe3XQYmrrvrKVQ6T4YVmSSieL-oYFLY8,2783
 phoenix_channels_python_client/utils.py,sha256=YFo2N2h9UJ9vcSYUCGfbElsEVgyc3vM2103t8bZdEd8,2204
-phoenix_channels_python_client-0.4.2.dist-info/licenses/LICENSE,sha256=zwqkIClV_fMWOC0Auvd0DYqZMLL0-hIqeKd6tygE39g,1064
-phoenix_channels_python_client-0.4.2.dist-info/METADATA,sha256=e7-FH4z4uC9RybopdTPghXaRvmNh7jcXyb_NufC4wjs,22444
-phoenix_channels_python_client-0.4.2.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
-phoenix_channels_python_client-0.4.2.dist-info/top_level.txt,sha256=ZYXMGCOeev4cyNU9XvNGHKt1wOgVkFHaS9TlwDa4eDU,31
-phoenix_channels_python_client-0.4.2.dist-info/RECORD,,
+phoenix_channels_python_client-0.4.4.dist-info/licenses/LICENSE,sha256=zwqkIClV_fMWOC0Auvd0DYqZMLL0-hIqeKd6tygE39g,1064
+phoenix_channels_python_client-0.4.4.dist-info/METADATA,sha256=NKxcBucgeI2bI-dsS2oeKEZ7Anb4lUOclhXrKYlSD4s,25238
+phoenix_channels_python_client-0.4.4.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+phoenix_channels_python_client-0.4.4.dist-info/top_level.txt,sha256=ZYXMGCOeev4cyNU9XvNGHKt1wOgVkFHaS9TlwDa4eDU,31
+phoenix_channels_python_client-0.4.4.dist-info/RECORD,,