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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phoenix-channels-python-client
-Version: 0.4.0
+Version: 0.4.2
 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.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"
@@ -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.10,>=0.7; extra == "test"
 Dynamic: license-file
 
 # Phoenix Channels Python Client
@@ -295,18 +297,20 @@ 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 |
 | `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 |
 | `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
 
@@ -346,7 +350,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
 
@@ -402,3 +420,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.0 → phoenix_channels_python_client-0.4.2}/README.md

@@ -264,18 +264,20 @@ 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 |
 | `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 |
 | `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
 
@@ -315,7 +317,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
 
@@ -371,3 +387,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.0 → phoenix_channels_python_client-0.4.2}/phoenix_channels_python_client/__init__.py

@@ -13,18 +13,20 @@ from phoenix_channels_python_client.client import (
     ReconnectPolicy,
     TopicLostCallback,
 )
+from phoenix_channels_python_client.client_types import JoinResponseCallback
 from phoenix_channels_python_client.protocol_handler import (
     PhoenixChannelsProtocolVersion,
     PHXProtocolHandler,
 )
 from phoenix_channels_python_client.utils import setup_logging
 
-__version__ = "0.4.0"
+__version__ = "0.4.2"
 __author__ = "Phoenix Channels Python Client"
 
 __all__ = [
     "DisconnectCallback",
     "HeartbeatAckCallback",
+    "JoinResponseCallback",
     "PHXChannelsClient",
     "PHXProtocolHandler",
     "PhoenixChannelsProtocolVersion",

{phoenix_channels_python_client-0.4.0 → phoenix_channels_python_client-0.4.2}/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
@@ -178,6 +198,7 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
         self._on_heartbeat_ack = on_heartbeat_ack
         self._on_topic_lost = on_topic_lost
         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:
@@ -195,6 +216,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:
@@ -253,6 +275,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.0 → phoenix_channels_python_client-0.4.2}/phoenix_channels_python_client/client_types.py

@@ -1,8 +1,9 @@
 from __future__ import annotations
 
+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 +16,8 @@ from pydantic import (
 
 from phoenix_channels_python_client.exceptions import PHXConnectionError
 
+JoinResponseCallback = Callable[[Any], None]
+
 
 class ClientState(StrEnum):
     CONNECTING = "connecting"

{phoenix_channels_python_client-0.4.0 → phoenix_channels_python_client-0.4.2}/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()