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

{phoenix_channels_python_client-0.4.1/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.1
+Version: 0.4.3
 Summary: A Python client library for connecting to Phoenix Channels
 Author: Phoenix Channels Python Client
 License-Expression: MIT
@@ -19,7 +19,7 @@ Requires-Dist: websockets>=14.2
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-asyncio>=1.4; extra == "dev"
-Requires-Dist: looptime<0.8,>=0.7; extra == "dev"
+Requires-Dist: looptime<0.10,>=0.7; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: pre-commit>=3.0.0; extra == "dev"
 Requires-Dist: commitizen>=3.13.0; extra == "dev"
@@ -28,7 +28,7 @@ Requires-Dist: ruff; extra == "dev"
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-asyncio>=1.4; extra == "test"
-Requires-Dist: looptime<0.8,>=0.7; extra == "test"
+Requires-Dist: looptime<0.10,>=0.7; extra == "test"
 Dynamic: license-file
 
 # Phoenix Channels Python Client
@@ -303,13 +303,15 @@ Everything after `api_key` is keyword-only:
 | `leave_timeout_s` | `5.0` | Wait for a leave reply |
 | `max_topic_queue_size` | `1000` | Per-topic buffer; the oldest message is dropped when full |
 | `callback_drain_timeout_s` | `2.0` | How long the message being handled (its message handler, then its event handler) may finish before a rejoin cancels it; queued messages are dropped |
-| `on_reconnect` | `None` | `async () -> None`, called after topics are rejoined |
+| `on_reconnect` | `None` | `async () -> None`, called after required first-attempt reconciliation |
 | `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 callbacks are logged, not raised.
+Exceptions raised in ordinary message and lifecycle callbacks are logged, not raised.
+Join-response installation failures instead fail the join (see below).
 
 ## Connection Lifecycle and Errors
 
@@ -339,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.
@@ -419,3 +449,69 @@ headers, frame bodies, user/topic identities, and untrusted server error details
 Logs retain static lifecycle descriptions, native connection states,
 and exception types. Application data and caller-visible errors are not changed;
 applications remain responsible for logs outside this connection-owned boundary.
+
+### Ordered join responses
+
+Use the optional keyword-only `on_join_response` hook to install a snapshot from
+initial joins, socket rejoins and same-socket channel recovery:
+
+```python
+state = None
+
+def install_snapshot(response):
+    global state
+    state = validate_snapshot(response)
+
+await client.subscribe_to_topic(
+    "room:123", on_message, on_join_response=install_snapshot
+)
+```
+
+`JoinResponseCallback` is exported from the package. The hook receives the decoded
+successful `payload.response`; a missing response is `None`. The transport adds no
+application schema or empty snapshot. Installation runs synchronously before
+`is_topic_joined()` becomes true, subscribe completes, or later deltas deliver.
+Subscribe returns `None`. Success admits the subscription; a later disconnect or
+channel failure can already have changed its current readiness when the caller
+resumes.
+
+Hooks must be short, nonblocking and return `None`. Do not await, perform I/O,
+wait on locks, defer installation, or change task/client lifecycle inside them.
+Async callables, awaitable results and other non-`None` results fail admission.
+The join timeout bounds reply waiting and cannot preempt synchronous code. Hook
+exceptions (including directly raised `CancelledError`) fail with `PHXTopicError`
+and preserve their cause; arbitrary prior hook effects are not rolled back.
+Initial failure belongs to the caller. An established subscription whose installer
+fails is removed and reported once through `on_topic_lost`.
+
+Initial cancellation, timeout and leave remove the exact subscription. Physical
+cleanup remains owned if its waiter is canceled again, and shutdown awaits it.
+Never-established subscriptions are not adopted by automatic recovery. Recorded
+queue loss before a hook-enabled installation fails the attempt transiently;
+steady-state queues still drop their oldest message at capacity. There is no
+replay guarantee. A fresh client must install a fresh snapshot after process loss.
+
+Join replies match request refs on both protocols. V2 also filters stale channel
+generations by `join_ref`. V1 cannot reliably fence unsolicited events/lifecycle
+frames from older channels; it does not provide V2 event-generation isolation.
+
+### Optional reconnect participation
+
+`subscribe_to_topic(topic, async_callback=None, *, on_join_response=None,
+blocks_reconnect=True) -> None` preserves required recovery by default. Required
+topics reconcile their first socket-rejoin attempt sequentially before
+`on_reconnect`; transient failures continue through existing recovery/backoff.
+The barrier does not wait for eventual success of every required topic.
+
+Set `blocks_reconnect=False` for optional subscriptions. After required first
+attempts, their existing per-topic recovery tasks perform an immediate join and
+retry transient failures with the existing backoff. Required event delivery and
+`on_reconnect` do not wait for optional replies, old callback drains or retries.
+This option cannot isolate synchronous code that blocks the event loop. Explicit
+initial subscribe always waits for its own join response and installation.
+
+`on_reconnect` conveys no optional readiness or registration-absence guarantee.
+Check `is_topic_joined()` for current readiness and use `on_topic_lost` to replace
+permanently rejected optional subscriptions; do not blindly resubscribe them
+from `on_reconnect`. Leave, shutdown and another socket disconnect cancel/await
+the owned recovery; obsolete generations cannot install or revive a replacement.

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

@@ -270,13 +270,15 @@ Everything after `api_key` is keyword-only:
 | `leave_timeout_s` | `5.0` | Wait for a leave reply |
 | `max_topic_queue_size` | `1000` | Per-topic buffer; the oldest message is dropped when full |
 | `callback_drain_timeout_s` | `2.0` | How long the message being handled (its message handler, then its event handler) may finish before a rejoin cancels it; queued messages are dropped |
-| `on_reconnect` | `None` | `async () -> None`, called after topics are rejoined |
+| `on_reconnect` | `None` | `async () -> None`, called after required first-attempt reconciliation |
 | `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 callbacks are logged, not raised.
+Exceptions raised in ordinary message and lifecycle callbacks are logged, not raised.
+Join-response installation failures instead fail the join (see below).
 
 ## Connection Lifecycle and Errors
 
@@ -306,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.
@@ -386,3 +416,69 @@ headers, frame bodies, user/topic identities, and untrusted server error details
 Logs retain static lifecycle descriptions, native connection states,
 and exception types. Application data and caller-visible errors are not changed;
 applications remain responsible for logs outside this connection-owned boundary.
+
+### Ordered join responses
+
+Use the optional keyword-only `on_join_response` hook to install a snapshot from
+initial joins, socket rejoins and same-socket channel recovery:
+
+```python
+state = None
+
+def install_snapshot(response):
+    global state
+    state = validate_snapshot(response)
+
+await client.subscribe_to_topic(
+    "room:123", on_message, on_join_response=install_snapshot
+)
+```
+
+`JoinResponseCallback` is exported from the package. The hook receives the decoded
+successful `payload.response`; a missing response is `None`. The transport adds no
+application schema or empty snapshot. Installation runs synchronously before
+`is_topic_joined()` becomes true, subscribe completes, or later deltas deliver.
+Subscribe returns `None`. Success admits the subscription; a later disconnect or
+channel failure can already have changed its current readiness when the caller
+resumes.
+
+Hooks must be short, nonblocking and return `None`. Do not await, perform I/O,
+wait on locks, defer installation, or change task/client lifecycle inside them.
+Async callables, awaitable results and other non-`None` results fail admission.
+The join timeout bounds reply waiting and cannot preempt synchronous code. Hook
+exceptions (including directly raised `CancelledError`) fail with `PHXTopicError`
+and preserve their cause; arbitrary prior hook effects are not rolled back.
+Initial failure belongs to the caller. An established subscription whose installer
+fails is removed and reported once through `on_topic_lost`.
+
+Initial cancellation, timeout and leave remove the exact subscription. Physical
+cleanup remains owned if its waiter is canceled again, and shutdown awaits it.
+Never-established subscriptions are not adopted by automatic recovery. Recorded
+queue loss before a hook-enabled installation fails the attempt transiently;
+steady-state queues still drop their oldest message at capacity. There is no
+replay guarantee. A fresh client must install a fresh snapshot after process loss.
+
+Join replies match request refs on both protocols. V2 also filters stale channel
+generations by `join_ref`. V1 cannot reliably fence unsolicited events/lifecycle
+frames from older channels; it does not provide V2 event-generation isolation.
+
+### Optional reconnect participation
+
+`subscribe_to_topic(topic, async_callback=None, *, on_join_response=None,
+blocks_reconnect=True) -> None` preserves required recovery by default. Required
+topics reconcile their first socket-rejoin attempt sequentially before
+`on_reconnect`; transient failures continue through existing recovery/backoff.
+The barrier does not wait for eventual success of every required topic.
+
+Set `blocks_reconnect=False` for optional subscriptions. After required first
+attempts, their existing per-topic recovery tasks perform an immediate join and
+retry transient failures with the existing backoff. Required event delivery and
+`on_reconnect` do not wait for optional replies, old callback drains or retries.
+This option cannot isolate synchronous code that blocks the event loop. Explicit
+initial subscribe always waits for its own join response and installation.
+
+`on_reconnect` conveys no optional readiness or registration-absence guarantee.
+Check `is_topic_joined()` for current readiness and use `on_topic_lost` to replace
+permanently rejected optional subscriptions; do not blindly resubscribe them
+from `on_reconnect`. Leave, shutdown and another socket disconnect cancel/await
+the owned recovery; obsolete generations cannot install or revive a replacement.

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

@@ -13,22 +13,40 @@ from phoenix_channels_python_client.client import (
     ReconnectPolicy,
     TopicLostCallback,
 )
+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.1"
+__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.1 → 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,7 +200,10 @@ 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
 
     def redact_diagnostic(self, text: str) -> str:
@@ -215,6 +221,7 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
             self._state == ClientState.CLOSED
             and not self._topic_subscriptions
             and self.connection is None
+            and not self._cleanup_tasks
         )
 
     async def __aenter__(self) -> Self:
@@ -224,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()
@@ -273,6 +280,8 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
         await self._unsubscribe_all()
         # Includes on_topic_lost callbacks still running for topics already gone.
         await cancel_and_wait(*self._lifecycle_tasks)
+        if self._cleanup_tasks:
+            await asyncio.gather(*self._cleanup_tasks)
         await self._stop_supervisor()
         await self._cleanup_connection()
         self._connected_event.clear()

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

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
+import math
+from collections.abc import Callable
 from dataclasses import dataclass
 from enum import StrEnum
-from typing import Self
+from typing import Any, Self
 
 from pydantic import (
     BaseModel,
@@ -15,6 +17,8 @@ from pydantic import (
 
 from phoenix_channels_python_client.exceptions import PHXConnectionError
 
+JoinResponseCallback = Callable[[Any], None]
+
 
 class ClientState(StrEnum):
     CONNECTING = "connecting"
@@ -68,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]