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

{phoenix_channels_python_client-0.3.1/phoenix_channels_python_client.egg-info → phoenix_channels_python_client-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phoenix-channels-python-client
-Version: 0.3.1
+Version: 0.4.1
 Summary: A Python client library for connecting to Phoenix Channels
 Author: Phoenix Channels Python Client
 License-Expression: MIT
@@ -19,6 +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: pytest-cov; extra == "dev"
 Requires-Dist: pre-commit>=3.0.0; extra == "dev"
 Requires-Dist: commitizen>=3.13.0; extra == "dev"
@@ -27,6 +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"
 Dynamic: license-file
 
 # Phoenix Channels Python Client
@@ -295,7 +297,8 @@ Everything after `api_key` is keyword-only:
 | `protocol_version` | `V2` | Phoenix Channels protocol version |
 | `auto_reconnect` | `True` | Reconnect and rejoin topics after a disconnect |
 | `reconnect_policy` | `ReconnectPolicy()` | Backoff and close-code handling (see below) |
-| `heartbeat_interval_s` | `30.0` | Heartbeat period; `None` disables heartbeats |
+| `heartbeat_interval_s` | `30.0` | Heartbeat period; `None` disables heartbeats and timeout enforcement |
+| `heartbeat_dead_threshold_s` | `None` | Optional finite positive acknowledgement-silence limit, greater than the enabled finite interval |
 | `join_timeout_s` | `10.0` | Wait for a join reply |
 | `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 |
@@ -310,18 +313,19 @@ Exceptions raised in callbacks are logged, not raised.
 
 ## Connection Lifecycle and Errors
 
-- `async with` waits for the first connection. With `auto_reconnect=True` it keeps retrying; with `auto_reconnect=False` a failed first connection raises `PHXConnectionError`.
-- `run_forever()` returns `None` after `shutdown()`, a signal, or a close that doesn't reconnect. It raises `PHXConnectionError` on a terminal close, after repeated rapid disconnects, or when the client has never entered `async with`.
+- `async with` waits for the first connection. With `auto_reconnect=True` it keeps retrying, except after a refused handshake with HTTP 403, which raises `PHXConnectionError`; with `auto_reconnect=False` a failed first connection raises `PHXConnectionError`.
+- `run_forever()` returns `None` after `shutdown()`, a signal, or a close that doesn't reconnect. It raises `PHXConnectionError` on a terminal close, a refused handshake with HTTP 403, after repeated rapid disconnects, or when the client has never entered `async with`.
 - `subscribe_to_topic()` raises `PHXTopicError` on a rejected join, a join timeout or a duplicate subscription, and `PHXConnectionError` while disconnected or if the connection drops before the join completes.
 - `await client.close_connection(reason)` force-closes the current connection; the client then reconnects if `auto_reconnect` is on. It does nothing if the client isn't connected or the connection is already closing.
 - Exceptions live in `phoenix_channels_python_client.exceptions`.
 
 ### Reconnects
 
-| Close code | Behaviour (defaults) |
+| Close code or handshake | Behaviour (defaults) |
 |---|---|
-| 1000, 1001 | Stop, unless `reconnect_on_normal_close=True` |
+| 1000, 1001 | Reconnect (Phoenix ≥ 1.8.8 sends 1001 for "reconnect expected"); stop with `reconnect_on_normal_close=False` |
 | 1008 | Stop with `PHXConnectionError` (`policy_violation_is_terminal=True`) |
+| Handshake refused with HTTP 403 | Stop with `PHXConnectionError`; other statuses (401, 5xx, …) retry with the backoff below |
 | 1012 | Reconnect after at least a random 1–5 s |
 | 1013 | Reconnect after at least a random 30–60 s |
 | Anything else, or no close frame | Reconnect with jittered backoff: 0.5 s × 2ⁿ, capped at 30 s, reset after 60 s of uptime |
@@ -345,7 +349,21 @@ The client drops the topic and calls `on_topic_lost(topic, error)` once when the
 
 ### Heartbeats
 
-The client sends a `heartbeat` on the `phoenix` topic every `heartbeat_interval_s`. A missed reply only logs a warning; to act on it, combine `on_heartbeat_ack` with `close_connection()`.
+The client sends a `heartbeat` on the `phoenix` topic every `heartbeat_interval_s`. By default, missed replies log warnings and sending continues with a new reference each interval.
+
+Set `heartbeat_dead_threshold_s` to enable closure after acknowledgement silence:
+
+```python
+client = PHXChannelsClient(
+    websocket_url, api_key,
+    heartbeat_interval_s=30.0,
+    heartbeat_dead_threshold_s=60.0,
+)
+```
+
+The deadline starts when each socket is adopted, including during rejoin and reconnect callbacks. Only a matching pending reply received strictly before expiry renews it, before `on_heartbeat_ack` runs. Enabled enforcement keeps one outstanding heartbeat, skipping sends until it is acknowledged or expires. WebSocket Pong and unrelated messages do not renew it. Rejoin completion grants no additional grace.
+
+Expiry or heartbeat send failure force-closes that socket; the supervisor handles cleanup and reconnect/rejoin according to `auto_reconnect` and the existing policy. The deadline bounds close initiation; the transport has its own close-handshake timeout. `heartbeat_interval_s=None` disables heartbeat activity even with a threshold, but a supplied threshold must still be finite and positive. Long thresholds do not prevent the server from applying its own inactivity timeout.
 
 ## Logging
 

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

@@ -264,7 +264,8 @@ Everything after `api_key` is keyword-only:
 | `protocol_version` | `V2` | Phoenix Channels protocol version |
 | `auto_reconnect` | `True` | Reconnect and rejoin topics after a disconnect |
 | `reconnect_policy` | `ReconnectPolicy()` | Backoff and close-code handling (see below) |
-| `heartbeat_interval_s` | `30.0` | Heartbeat period; `None` disables heartbeats |
+| `heartbeat_interval_s` | `30.0` | Heartbeat period; `None` disables heartbeats and timeout enforcement |
+| `heartbeat_dead_threshold_s` | `None` | Optional finite positive acknowledgement-silence limit, greater than the enabled finite interval |
 | `join_timeout_s` | `10.0` | Wait for a join reply |
 | `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 |
@@ -279,18 +280,19 @@ Exceptions raised in callbacks are logged, not raised.
 
 ## Connection Lifecycle and Errors
 
-- `async with` waits for the first connection. With `auto_reconnect=True` it keeps retrying; with `auto_reconnect=False` a failed first connection raises `PHXConnectionError`.
-- `run_forever()` returns `None` after `shutdown()`, a signal, or a close that doesn't reconnect. It raises `PHXConnectionError` on a terminal close, after repeated rapid disconnects, or when the client has never entered `async with`.
+- `async with` waits for the first connection. With `auto_reconnect=True` it keeps retrying, except after a refused handshake with HTTP 403, which raises `PHXConnectionError`; with `auto_reconnect=False` a failed first connection raises `PHXConnectionError`.
+- `run_forever()` returns `None` after `shutdown()`, a signal, or a close that doesn't reconnect. It raises `PHXConnectionError` on a terminal close, a refused handshake with HTTP 403, after repeated rapid disconnects, or when the client has never entered `async with`.
 - `subscribe_to_topic()` raises `PHXTopicError` on a rejected join, a join timeout or a duplicate subscription, and `PHXConnectionError` while disconnected or if the connection drops before the join completes.
 - `await client.close_connection(reason)` force-closes the current connection; the client then reconnects if `auto_reconnect` is on. It does nothing if the client isn't connected or the connection is already closing.
 - Exceptions live in `phoenix_channels_python_client.exceptions`.
 
 ### Reconnects
 
-| Close code | Behaviour (defaults) |
+| Close code or handshake | Behaviour (defaults) |
 |---|---|
-| 1000, 1001 | Stop, unless `reconnect_on_normal_close=True` |
+| 1000, 1001 | Reconnect (Phoenix ≥ 1.8.8 sends 1001 for "reconnect expected"); stop with `reconnect_on_normal_close=False` |
 | 1008 | Stop with `PHXConnectionError` (`policy_violation_is_terminal=True`) |
+| Handshake refused with HTTP 403 | Stop with `PHXConnectionError`; other statuses (401, 5xx, …) retry with the backoff below |
 | 1012 | Reconnect after at least a random 1–5 s |
 | 1013 | Reconnect after at least a random 30–60 s |
 | Anything else, or no close frame | Reconnect with jittered backoff: 0.5 s × 2ⁿ, capped at 30 s, reset after 60 s of uptime |
@@ -314,7 +316,21 @@ The client drops the topic and calls `on_topic_lost(topic, error)` once when the
 
 ### Heartbeats
 
-The client sends a `heartbeat` on the `phoenix` topic every `heartbeat_interval_s`. A missed reply only logs a warning; to act on it, combine `on_heartbeat_ack` with `close_connection()`.
+The client sends a `heartbeat` on the `phoenix` topic every `heartbeat_interval_s`. By default, missed replies log warnings and sending continues with a new reference each interval.
+
+Set `heartbeat_dead_threshold_s` to enable closure after acknowledgement silence:
+
+```python
+client = PHXChannelsClient(
+    websocket_url, api_key,
+    heartbeat_interval_s=30.0,
+    heartbeat_dead_threshold_s=60.0,
+)
+```
+
+The deadline starts when each socket is adopted, including during rejoin and reconnect callbacks. Only a matching pending reply received strictly before expiry renews it, before `on_heartbeat_ack` runs. Enabled enforcement keeps one outstanding heartbeat, skipping sends until it is acknowledged or expires. WebSocket Pong and unrelated messages do not renew it. Rejoin completion grants no additional grace.
+
+Expiry or heartbeat send failure force-closes that socket; the supervisor handles cleanup and reconnect/rejoin according to `auto_reconnect` and the existing policy. The deadline bounds close initiation; the transport has its own close-handshake timeout. `heartbeat_interval_s=None` disables heartbeat activity even with a threshold, but a supplied threshold must still be finite and positive. Long thresholds do not prevent the server from applying its own inactivity timeout.
 
 ## Logging
 

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

@@ -19,7 +19,7 @@ from phoenix_channels_python_client.protocol_handler import (
 )
 from phoenix_channels_python_client.utils import setup_logging
 
-__version__ = "0.3.1"
+__version__ = "0.4.1"
 __author__ = "Phoenix Channels Python Client"
 
 __all__ = [

{phoenix_channels_python_client-0.3.1 → phoenix_channels_python_client-0.4.1}/phoenix_channels_python_client/client.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import asyncio
 import logging
+import math
 from collections import deque
 from collections.abc import Awaitable, Callable
 from types import TracebackType
@@ -99,6 +100,19 @@ def _build_channel_socket_urls(
     )
 
 
+def _validate_heartbeat_threshold(
+    interval: float | None, threshold: float | None
+) -> None:
+    if threshold is None:
+        return
+    if not math.isfinite(threshold) or threshold <= 0:
+        raise ValueError("heartbeat_dead_threshold_s must be finite and > 0")
+    if interval is not None and (not math.isfinite(interval) or threshold <= interval):
+        raise ValueError(
+            "heartbeat_dead_threshold_s must exceed the finite heartbeat interval"
+        )
+
+
 class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerMixin):
     def __init__(  # noqa: PLR0913  # the public options
         self,
@@ -114,6 +128,7 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
         max_topic_queue_size: int = 1000,
         callback_drain_timeout_s: float = 2.0,
         heartbeat_interval_s: float | None = 30.0,
+        heartbeat_dead_threshold_s: float | None = None,
         on_reconnect: ReconnectCallback | None = None,
         on_disconnect: DisconnectCallback | None = None,
         on_heartbeat_ack: HeartbeatAckCallback | None = None,
@@ -128,6 +143,8 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
         if heartbeat_interval_s is not None and heartbeat_interval_s <= 0:
             raise ValueError("heartbeat_interval_s must be > 0 or None to disable")
 
+        _validate_heartbeat_threshold(heartbeat_interval_s, heartbeat_dead_threshold_s)
+
         if join_timeout_s <= 0:
             raise ValueError("join_timeout_s must be > 0")
         if leave_timeout_s <= 0:
@@ -170,6 +187,9 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
         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
+        self._heartbeat_timeout: asyncio.Timeout | None = None
         self._heartbeat_interval_s = heartbeat_interval_s
         self._heartbeat_task: asyncio.Task[None] | None = None
         self._pending_heartbeat_ref: str | None = None
@@ -234,18 +254,22 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
         if task is None:
             if self._is_fully_closed:
                 return
+            self._request_stop()
             task = self._shutdown_task = asyncio.create_task(self._shutdown(reason))
         # Every caller waits for the same shutdown, and one caller's
         # cancellation never aborts it.
         await asyncio.shield(task)
 
-    async def _shutdown(self, reason: str) -> None:
-        self.logger.info("Event loop shutting down! reason=%s", reason)
-
+    def _request_stop(self) -> None:
+        # Runs inside the shutdown() call, not in its task: a refusal or close landing
+        # before the task's first step must already see the stop.
         if self._state not in (ClientState.SHUTTING_DOWN, ClientState.CLOSED):
             self._transition_state(ClientState.SHUTTING_DOWN)
         self._shutdown_event.set()
 
+    async def _shutdown(self, reason: str) -> None:
+        self.logger.info("Event loop shutting down! reason=%s", reason)
+
         await self._unsubscribe_all()
         # Includes on_topic_lost callbacks still running for topics already gone.
         await cancel_and_wait(*self._lifecycle_tasks)

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

@@ -40,7 +40,10 @@ class ReconnectPolicy(BaseModel):
     factor: PositiveFloat = 2.0
     max_delay_s: NonNegativeFloat = 30.0
     stable_reset_s: PositiveFloat = 60.0
-    reconnect_on_normal_close: bool = False
+    # Phoenix >= 1.8.8 closes deliberate disconnects with 1001 ("reconnect
+    # expected"), and Bandit answers a close the peer started with 1000, so
+    # neither code is a stop signal.
+    reconnect_on_normal_close: bool = True
     policy_violation_is_terminal: bool = True
     service_restart_min_delay_s: NonNegativeFloat = 1.0
     service_restart_max_delay_s: NonNegativeFloat = 5.0

{phoenix_channels_python_client-0.3.1 → phoenix_channels_python_client-0.4.1}/phoenix_channels_python_client/reconnect_controller.py

@@ -4,9 +4,10 @@ import asyncio
 import logging
 import random
 from collections import deque
+from http import HTTPStatus
 
 from websockets import ClientConnection
-from websockets.exceptions import ConnectionClosed
+from websockets.exceptions import ConnectionClosed, InvalidStatus
 from websockets.frames import CloseCode
 
 from phoenix_channels_python_client.client_types import (
@@ -15,6 +16,20 @@ from phoenix_channels_python_client.client_types import (
 )
 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}"
+        ),
+    )
+
 
 class ReconnectControllerMixin:
     logger: logging.Logger
@@ -211,12 +226,8 @@ class ReconnectControllerMixin:
             and self.reconnect_policy.policy_violation_is_terminal
         ):
             reason = close_reason or "policy violation"
-            decision = ReconnectDecision(
-                should_reconnect=False,
-                terminal_error=PHXConnectionError(
-                    "Reconnect disabled due to terminal close code "
-                    f"{CloseCode.POLICY_VIOLATION} ({reason})"
-                ),
+            decision = _terminal_decision(
+                f"close code {CloseCode.POLICY_VIOLATION} ({reason})"
             )
             self.logger.debug(
                 "Disconnect classification result. close_code=%s close_reason=%s "
@@ -297,6 +308,17 @@ class ReconnectControllerMixin:
         )
         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,

{phoenix_channels_python_client-0.3.1 → phoenix_channels_python_client-0.4.1}/phoenix_channels_python_client/supervisor.py

@@ -67,6 +67,7 @@ class _SupervisorRuntimeDeps(Protocol):
     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: ...
@@ -93,6 +94,9 @@ class SupervisorMixin:
     _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
+    _heartbeat_timeout: asyncio.Timeout | None
     _heartbeat_interval_s: float | None
     _heartbeat_task: asyncio.Task[None] | None
     _pending_heartbeat_ref: str | None
@@ -117,6 +121,17 @@ class SupervisorMixin:
 
     def _handle_heartbeat_response(self, message: ChannelMessage) -> None:
         if message.ref is not None and message.ref == self._pending_heartbeat_ref:
+            if self._heartbeat_dead_threshold_s is not None:
+                timer = self._heartbeat_timeout
+                now = asyncio.get_running_loop().time()
+                if (
+                    timer is None
+                    or timer.expired()
+                    or (deadline := timer.when()) is None
+                    or now >= deadline
+                ):
+                    return
+                timer.reschedule(now + self._heartbeat_dead_threshold_s)
             self.logger.debug("Heartbeat acknowledged (ref=%s)", message.ref)
             self._pending_heartbeat_ref = None
             if self._on_heartbeat_ack is not None:
@@ -148,6 +163,11 @@ class SupervisorMixin:
         connection = self.connection
         if connection is None:
             return
+        await self._force_close_connection(connection, reason)
+
+    async def _force_close_connection(
+        self, connection: ClientConnection, reason: str
+    ) -> None:
         if connection.state is not State.OPEN:
             self.logger.debug(
                 "Not forcing a close; connection is already %s", connection.state.name
@@ -156,52 +176,67 @@ class SupervisorMixin:
         reason = _truncate_close_reason(reason)
         self.logger.info("Forcing connection close: %s", reason)
         self._forced_close_pending = True
-        await connection.close(code=_FORCED_CLOSE_CODE, reason=reason)
-
-    async def _heartbeat_loop(self, connection: ClientConnection) -> None:
-        if self._heartbeat_interval_s is None:
-            return
-
-        self.logger.debug(
-            "Starting heartbeat loop (interval=%ss)", self._heartbeat_interval_s
-        )
-
         try:
-            while not self._shutdown_event.is_set():
-                await self._wait_for_shutdown_or_timeout(self._heartbeat_interval_s)
-                if self._shutdown_event.is_set():
-                    break
+            await connection.close(code=_FORCED_CLOSE_CODE, reason=reason)
+        except (Exception, asyncio.CancelledError):
+            connection.transport.abort()
+            raise
 
-                if self._pending_heartbeat_ref is not None:
-                    self.logger.warning(
-                        "Heartbeat response not received for ref=%s; server may be "
-                        "unresponsive",
-                        self._pending_heartbeat_ref,
-                    )
+    async def _heartbeat_loop(
+        self, connection: ClientConnection, deadline: float | None = None
+    ) -> None:
+        timer = asyncio.timeout_at(deadline)
+        try:
+            async with timer:
+                self._heartbeat_timeout = timer
+                try:
+                    await self._send_heartbeats(connection)
+                finally:
+                    self._heartbeat_timeout = None
+        except TimeoutError:
+            if timer.expired():
+                self.logger.warning("Heartbeat acknowledgement deadline expired")
+            elif self._heartbeat_dead_threshold_s is not None:
+                self.logger.exception("Heartbeat send timed out")
+        except Exception:
+            if self._heartbeat_dead_threshold_s is None:
+                self.logger.debug("Failed to send heartbeat; connection likely closing")
+                return
+            self.logger.exception("Failed to send heartbeat")
+        else:
+            return
 
-                ref = self._deps._generate_ref()
-                self._pending_heartbeat_ref = ref
+        if self._heartbeat_dead_threshold_s is not None:
+            try:
+                await self._force_close_connection(connection, "Heartbeat failed")
+            except Exception:
+                self.logger.exception("Failed to close heartbeat connection")
 
-                heartbeat_message = make_message(
-                    topic=PHOENIX_TOPIC,
-                    event=HEARTBEAT_EVENT,
-                    payload={},
-                    ref=ref,
+    async def _send_heartbeats(self, connection: ClientConnection) -> None:
+        interval = self._heartbeat_interval_s
+        if interval is None:
+            return
+        while not self._shutdown_event.is_set():
+            await self._wait_for_shutdown_or_timeout(interval)
+            if self._shutdown_event.is_set():
+                return
+            if self._pending_heartbeat_ref is not None:
+                if self._heartbeat_dead_threshold_s is not None:
+                    continue
+                self.logger.warning(
+                    "Heartbeat response not received for ref=%s; server may be "
+                    "unresponsive",
+                    self._pending_heartbeat_ref,
                 )
-
-                try:
-                    await self._protocol_handler.send_message(
-                        connection, heartbeat_message
-                    )
-                    self.logger.debug("Sent heartbeat (ref=%s)", ref)
-                except Exception:  # noqa: BLE001  # any send failure ends the loop
-                    self.logger.debug(
-                        "Failed to send heartbeat; connection likely closing"
-                    )
-                    break
-        except asyncio.CancelledError:
-            self.logger.debug("Heartbeat loop cancelled")
-            raise
+            ref = self._deps._generate_ref()
+            self._pending_heartbeat_ref = ref
+            await self._protocol_handler.send_message(
+                connection,
+                make_message(
+                    topic=PHOENIX_TOPIC, event=HEARTBEAT_EVENT, payload={}, ref=ref
+                ),
+            )
+            self.logger.debug("Sent heartbeat (ref=%s)", ref)
 
     async def _supervisor_loop(self) -> None:
         attempt = 0
@@ -262,10 +297,19 @@ class SupervisorMixin:
             )
             self.logger.error("Connection failed and auto_reconnect=False: %s", exc)
             return False
+        # 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
-        if self._state != ClientState.SHUTTING_DOWN:
-            self._deps._transition_state(ClientState.RECONNECTING)
+        self._deps._transition_state(ClientState.RECONNECTING)
         return True
 
     def _adopt_connection(self, connection: ClientConnection) -> bool:
@@ -274,6 +318,12 @@ class SupervisorMixin:
             # shutdown() began during the handshake; its own cleanup closes
             # this socket.
             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)
@@ -289,7 +339,9 @@ class SupervisorMixin:
         # a rejoin is still waiting on one, before cleanup runs.
         routing.add_done_callback(self._fail_joins_when_routing_stops)
         if self._heartbeat_interval_s is not None:
-            self._heartbeat_task = asyncio.create_task(self._heartbeat_loop(connection))
+            self._heartbeat_task = asyncio.create_task(
+                self._heartbeat_loop(connection, self._heartbeat_deadline)
+            )
 
         try:
             await self._deps._rejoin_topics(generation)
@@ -347,8 +399,7 @@ class SupervisorMixin:
         else:
             decision = self._deps._classify_disconnect(close.code, close.reason)
         if decision.terminal_error is not None:
-            self._terminal_error = decision.terminal_error
-            self.logger.error("%s", self._terminal_error)
+            self._record_terminal_error(decision.terminal_error)
             return None
 
         if not decision.should_reconnect:
@@ -364,13 +415,20 @@ class SupervisorMixin:
         self._deps._record_disconnect(connection_uptime_s=uptime_s)
         if not self._deps._should_suppress_reconnect():
             return False
-        self._terminal_error = PHXConnectionError(
-            "Reconnect suppressed after repeated rapid disconnects. "
-            "Likely duplicate connection or unstable endpoint."
+        self._record_terminal_error(
+            PHXConnectionError(
+                "Reconnect suppressed after repeated rapid disconnects. "
+                "Likely duplicate connection or unstable endpoint."
+            )
         )
-        self.logger.error("%s", self._terminal_error)
         return True
 
+    def _record_terminal_error(self, error: PHXConnectionError) -> None:
+        self._terminal_error = error
+        # Log records stay static: the cause reaches the caller as the raised error.
+        self.logger.error("Reconnect stopped by a terminal error")
+        self._settle_initial_connection(error)
+
     def _settle_initial_connection(self, error: Exception | None) -> None:
         """Resolve ``__aenter__``'s wait, unless it already ended or was cancelled."""
         future = self._initial_connection_future
@@ -416,6 +474,7 @@ class SupervisorMixin:
         ]
         self.connection = None
         self._heartbeat_task = None
+        self._heartbeat_deadline = None
         self._message_routing_task = None
         self._pending_heartbeat_ref = None
         self._connected_event.clear()

{phoenix_channels_python_client-0.3.1 → phoenix_channels_python_client-0.4.1/phoenix_channels_python_client.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phoenix-channels-python-client
-Version: 0.3.1
+Version: 0.4.1
 Summary: A Python client library for connecting to Phoenix Channels
 Author: Phoenix Channels Python Client
 License-Expression: MIT
@@ -19,6 +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: pytest-cov; extra == "dev"
 Requires-Dist: pre-commit>=3.0.0; extra == "dev"
 Requires-Dist: commitizen>=3.13.0; extra == "dev"
@@ -27,6 +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"
 Dynamic: license-file
 
 # Phoenix Channels Python Client
@@ -295,7 +297,8 @@ Everything after `api_key` is keyword-only:
 | `protocol_version` | `V2` | Phoenix Channels protocol version |
 | `auto_reconnect` | `True` | Reconnect and rejoin topics after a disconnect |
 | `reconnect_policy` | `ReconnectPolicy()` | Backoff and close-code handling (see below) |
-| `heartbeat_interval_s` | `30.0` | Heartbeat period; `None` disables heartbeats |
+| `heartbeat_interval_s` | `30.0` | Heartbeat period; `None` disables heartbeats and timeout enforcement |
+| `heartbeat_dead_threshold_s` | `None` | Optional finite positive acknowledgement-silence limit, greater than the enabled finite interval |
 | `join_timeout_s` | `10.0` | Wait for a join reply |
 | `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 |
@@ -310,18 +313,19 @@ Exceptions raised in callbacks are logged, not raised.
 
 ## Connection Lifecycle and Errors
 
-- `async with` waits for the first connection. With `auto_reconnect=True` it keeps retrying; with `auto_reconnect=False` a failed first connection raises `PHXConnectionError`.
-- `run_forever()` returns `None` after `shutdown()`, a signal, or a close that doesn't reconnect. It raises `PHXConnectionError` on a terminal close, after repeated rapid disconnects, or when the client has never entered `async with`.
+- `async with` waits for the first connection. With `auto_reconnect=True` it keeps retrying, except after a refused handshake with HTTP 403, which raises `PHXConnectionError`; with `auto_reconnect=False` a failed first connection raises `PHXConnectionError`.
+- `run_forever()` returns `None` after `shutdown()`, a signal, or a close that doesn't reconnect. It raises `PHXConnectionError` on a terminal close, a refused handshake with HTTP 403, after repeated rapid disconnects, or when the client has never entered `async with`.
 - `subscribe_to_topic()` raises `PHXTopicError` on a rejected join, a join timeout or a duplicate subscription, and `PHXConnectionError` while disconnected or if the connection drops before the join completes.
 - `await client.close_connection(reason)` force-closes the current connection; the client then reconnects if `auto_reconnect` is on. It does nothing if the client isn't connected or the connection is already closing.
 - Exceptions live in `phoenix_channels_python_client.exceptions`.
 
 ### Reconnects
 
-| Close code | Behaviour (defaults) |
+| Close code or handshake | Behaviour (defaults) |
 |---|---|
-| 1000, 1001 | Stop, unless `reconnect_on_normal_close=True` |
+| 1000, 1001 | Reconnect (Phoenix ≥ 1.8.8 sends 1001 for "reconnect expected"); stop with `reconnect_on_normal_close=False` |
 | 1008 | Stop with `PHXConnectionError` (`policy_violation_is_terminal=True`) |
+| Handshake refused with HTTP 403 | Stop with `PHXConnectionError`; other statuses (401, 5xx, …) retry with the backoff below |
 | 1012 | Reconnect after at least a random 1–5 s |
 | 1013 | Reconnect after at least a random 30–60 s |
 | Anything else, or no close frame | Reconnect with jittered backoff: 0.5 s × 2ⁿ, capped at 30 s, reset after 60 s of uptime |
@@ -345,7 +349,21 @@ The client drops the topic and calls `on_topic_lost(topic, error)` once when the
 
 ### Heartbeats
 
-The client sends a `heartbeat` on the `phoenix` topic every `heartbeat_interval_s`. A missed reply only logs a warning; to act on it, combine `on_heartbeat_ack` with `close_connection()`.
+The client sends a `heartbeat` on the `phoenix` topic every `heartbeat_interval_s`. By default, missed replies log warnings and sending continues with a new reference each interval.
+
+Set `heartbeat_dead_threshold_s` to enable closure after acknowledgement silence:
+
+```python
+client = PHXChannelsClient(
+    websocket_url, api_key,
+    heartbeat_interval_s=30.0,
+    heartbeat_dead_threshold_s=60.0,
+)
+```
+
+The deadline starts when each socket is adopted, including during rejoin and reconnect callbacks. Only a matching pending reply received strictly before expiry renews it, before `on_heartbeat_ack` runs. Enabled enforcement keeps one outstanding heartbeat, skipping sends until it is acknowledged or expires. WebSocket Pong and unrelated messages do not renew it. Rejoin completion grants no additional grace.
+
+Expiry or heartbeat send failure force-closes that socket; the supervisor handles cleanup and reconnect/rejoin according to `auto_reconnect` and the existing policy. The deadline bounds close initiation; the transport has its own close-handshake timeout. `heartbeat_interval_s=None` disables heartbeat activity even with a threshold, but a supplied threshold must still be finite and positive. Long thresholds do not prevent the server from applying its own inactivity timeout.
 
 ## Logging
 

{phoenix_channels_python_client-0.3.1 → phoenix_channels_python_client-0.4.1}/phoenix_channels_python_client.egg-info/SOURCES.txt

@@ -27,6 +27,7 @@ tests/test_channel_recovery.py
 tests/test_client_state.py
 tests/test_connection.py
 tests/test_heartbeat.py
+tests/test_heartbeat_timeout.py
 tests/test_protocol_handler.py
 tests/test_reconnect.py
 tests/test_reconnect_policy_invariants.py

{phoenix_channels_python_client-0.3.1 → phoenix_channels_python_client-0.4.1}/phoenix_channels_python_client.egg-info/requires.txt

@@ -4,6 +4,7 @@ websockets>=14.2
 [dev]
 pytest
 pytest-asyncio>=1.4
+looptime<0.8,>=0.7
 pytest-cov
 pre-commit>=3.0.0
 commitizen>=3.13.0
@@ -13,3 +14,4 @@ ruff
 [test]
 pytest
 pytest-asyncio>=1.4
+looptime<0.8,>=0.7