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

{phoenix_channels_python_client-0.4.0 → phoenix_channels_python_client-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phoenix-channels-python-client
-Version: 0.4.0
+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 |
@@ -346,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.4.0/phoenix_channels_python_client.egg-info/PKG-INFO → phoenix_channels_python_client-0.4.1/README.md

@@ -1,34 +1,3 @@
-Metadata-Version: 2.4
-Name: phoenix-channels-python-client
-Version: 0.4.0
-Summary: A Python client library for connecting to Phoenix Channels
-Author: Phoenix Channels Python Client
-License-Expression: MIT
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: pydantic>=2.8
-Requires-Dist: websockets>=14.2
-Provides-Extra: dev
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: pytest-asyncio>=1.4; 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"
-Requires-Dist: pyrefly; extra == "dev"
-Requires-Dist: ruff; extra == "dev"
-Provides-Extra: test
-Requires-Dist: pytest; extra == "test"
-Requires-Dist: pytest-asyncio>=1.4; extra == "test"
-Dynamic: license-file
-
 # Phoenix Channels Python Client
 
 [![PyPI version](https://img.shields.io/pypi/v/phoenix-channels-python-client.svg)](https://pypi.org/project/phoenix-channels-python-client/)
@@ -295,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 |
@@ -346,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.4.0 → 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.4.0"
+__version__ = "0.4.1"
 __author__ = "Phoenix Channels Python Client"
 
 __all__ = [

{phoenix_channels_python_client-0.4.0 → 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

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

@@ -94,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
@@ -118,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:
@@ -149,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
@@ -157,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
@@ -284,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)
@@ -299,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)
@@ -432,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.4.0/README.md → phoenix_channels_python_client-0.4.1/phoenix_channels_python_client.egg-info/PKG-INFO

@@ -1,3 +1,36 @@
+Metadata-Version: 2.4
+Name: phoenix-channels-python-client
+Version: 0.4.1
+Summary: A Python client library for connecting to Phoenix Channels
+Author: Phoenix Channels Python Client
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.8
+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"
+Requires-Dist: pyrefly; extra == "dev"
+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
 
 [![PyPI version](https://img.shields.io/pypi/v/phoenix-channels-python-client.svg)](https://pypi.org/project/phoenix-channels-python-client/)
@@ -264,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 |
@@ -315,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.4.0 → 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.4.0 → 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

{phoenix_channels_python_client-0.4.0 → phoenix_channels_python_client-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "phoenix-channels-python-client"
-version = "0.4.0"
+version = "0.4.1"
 description = "A Python client library for connecting to Phoenix Channels"
 readme = "README.md"
 license = "MIT"
@@ -28,6 +28,7 @@ classifiers = [
 dev = [
     "pytest",
     "pytest-asyncio>=1.4",
+    "looptime>=0.7,<0.8",
     "pytest-cov",
     "pre-commit>=3.0.0",
     "commitizen>=3.13.0",
@@ -37,6 +38,7 @@ dev = [
 test = [
     "pytest",
     "pytest-asyncio>=1.4",
+    "looptime>=0.7,<0.8",
 ]
 
 [tool.ruff.lint]