phoenix-channels-python-client 0.2.2__py3-none-any.whl → 0.2.4__py3-none-any.whl

phoenix_channels_python_client/__init__.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 
 from phoenix_channels_python_client.client import (
     DisconnectCallback,
+    HeartbeatAckCallback,
     PHXChannelsClient,
     ReconnectCallback,
     ReconnectPolicy,
@@ -18,11 +19,12 @@ from phoenix_channels_python_client.protocol_handler import (
 )
 from phoenix_channels_python_client.utils import setup_logging
 
-__version__ = "0.2.2"
+__version__ = "0.2.4"
 __author__ = "Phoenix Channels Python Client"
 
 __all__ = [
     "DisconnectCallback",
+    "HeartbeatAckCallback",
     "PHXChannelsClient",
     "PHXProtocolHandler",
     "PhoenixChannelsProtocolVersion",

phoenix_channels_python_client/client.py

@@ -30,6 +30,10 @@ logger = logging.getLogger(__name__)
 
 ReconnectCallback = Callable[[], Awaitable[None]]
 DisconnectCallback = Callable[[Exception | None], Awaitable[None]]
+# Must be synchronous and fast: unlike the callbacks above, this runs inline
+# on the message-routing hot path, so blocking work here stalls heartbeat
+# sends and message routing for every connection.
+HeartbeatAckCallback = Callable[[], None]
 
 
 def _build_channel_socket_urls(
@@ -84,6 +88,7 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
         heartbeat_interval_s: float | None = 30.0,
         on_reconnect: ReconnectCallback | None = None,
         on_disconnect: DisconnectCallback | None = None,
+        on_heartbeat_ack: HeartbeatAckCallback | None = None,
         additional_headers: dict[str, str] | None = None,
     ):
         self.logger = logger
@@ -149,6 +154,8 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
         self._pending_heartbeat_ref: str | None = None
         self._on_reconnect = on_reconnect
         self._on_disconnect = on_disconnect
+        self._on_heartbeat_ack = on_heartbeat_ack
+        self._forced_close_pending = False
 
     @staticmethod
     def reconnect_policy_is_invalid(policy: ReconnectPolicy) -> bool:

phoenix_channels_python_client/phx_messages.py

@@ -6,6 +6,9 @@ from functools import cached_property
 from typing import Any, NewType
 
 
+PHOENIX_TOPIC = "phoenix"
+
+
 @unique
 class PHXEvent(Enum):
     close = "phx_close"

phoenix_channels_python_client/protocol_handler.py

@@ -8,7 +8,11 @@ from enum import Enum
 
 from websockets import ClientConnection
 
-from phoenix_channels_python_client.phx_messages import ChannelMessage, Event
+from phoenix_channels_python_client.phx_messages import (
+    PHOENIX_TOPIC,
+    ChannelMessage,
+    Event,
+)
 from phoenix_channels_python_client.topic_subscription import TopicSubscription
 from phoenix_channels_python_client.utils import make_message
 
@@ -155,7 +159,7 @@ class PHXProtocolHandler:
             self.logger.debug("Processing message - %s", phx_message)
             topic = phx_message.topic
 
-            if topic == "phoenix":
+            if topic == PHOENIX_TOPIC:
                 if on_heartbeat_response is not None:
                     on_heartbeat_response(phx_message)
                 continue

phoenix_channels_python_client/reconnect_controller.py

@@ -7,6 +7,7 @@ from collections import deque
 
 from websockets import ClientConnection
 from websockets.exceptions import ConnectionClosed
+from websockets.frames import CloseCode
 
 from phoenix_channels_python_client.client_types import (
     ReconnectDecision,
@@ -159,7 +160,7 @@ class ReconnectControllerMixin:
             return decision
 
         if (
-            close_code in {1000, 1001}
+            close_code in {CloseCode.NORMAL_CLOSURE, CloseCode.GOING_AWAY}
             and not self.reconnect_policy.reconnect_on_normal_close
         ):
             decision = ReconnectDecision(should_reconnect=False)
@@ -176,12 +177,15 @@ class ReconnectControllerMixin:
             )
             return decision
 
-        if close_code == 1008 and self.reconnect_policy.policy_violation_is_terminal:
+        if (
+            close_code == CloseCode.POLICY_VIOLATION
+            and self.reconnect_policy.policy_violation_is_terminal
+        ):
             reason = close_reason or "policy violation"
             decision = ReconnectDecision(
                 should_reconnect=False,
                 terminal_error=PHXConnectionError(
-                    f"Reconnect disabled due to terminal close code 1008 ({reason})"
+                    f"Reconnect disabled due to terminal close code {CloseCode.POLICY_VIOLATION} ({reason})"
                 ),
             )
             logger.debug(
@@ -199,7 +203,7 @@ class ReconnectControllerMixin:
             )
             return decision
 
-        if close_code == 1012:
+        if close_code == CloseCode.SERVICE_RESTART:
             decision = ReconnectDecision(
                 should_reconnect=True,
                 min_delay_s=self.reconnect_policy.service_restart_min_delay_s,
@@ -222,7 +226,7 @@ class ReconnectControllerMixin:
             )
             return decision
 
-        if close_code == 1013:
+        if close_code == CloseCode.TRY_AGAIN_LATER:
             decision = ReconnectDecision(
                 should_reconnect=True,
                 min_delay_s=self.reconnect_policy.try_again_later_min_delay_s,

phoenix_channels_python_client/supervisor.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import asyncio
+import inspect
 import logging
 import signal
 from collections import deque
@@ -17,11 +18,31 @@ from phoenix_channels_python_client.client_types import (
     ReconnectPolicy,
 )
 from phoenix_channels_python_client.exceptions import PHXConnectionError
-from phoenix_channels_python_client.phx_messages import ChannelMessage, Event
+from phoenix_channels_python_client.phx_messages import (
+    PHOENIX_TOPIC,
+    ChannelMessage,
+    Event,
+)
 from phoenix_channels_python_client.protocol_handler import PHXProtocolHandler
 from phoenix_channels_python_client.topic_subscription import TopicSubscription
 from phoenix_channels_python_client.utils import make_message
 
+# RFC 6455 §7.4.2 private-use range (4000-4999, unregistrable); outside
+# _classify_disconnect's specially-handled codes, so a forced close
+# reconnects like any other unclassified disconnect.
+_FORCED_CLOSE_CODE = 4000
+
+# RFC 6455 §5.5.1: control frames (including Close) cap at 125 bytes total;
+# 2 of those bytes are the close code, leaving 123 for the reason.
+_MAX_CLOSE_REASON_BYTES = 123
+
+
+def _truncate_close_reason(reason: str) -> str:
+    encoded = reason.encode("utf-8")
+    if len(encoded) <= _MAX_CLOSE_REASON_BYTES:
+        return reason
+    return encoded[:_MAX_CLOSE_REASON_BYTES].decode("utf-8", errors="ignore")
+
 
 class _SupervisorRuntimeDeps(Protocol):
     async def _rejoin_topics(self, generation: int) -> None: ...
@@ -65,6 +86,8 @@ class SupervisorMixin:
     _pending_heartbeat_ref: str | None
     _on_reconnect: Callable[[], Awaitable[None]] | None
     _on_disconnect: Callable[[Exception | None], Awaitable[None]] | None
+    _on_heartbeat_ack: Callable[[], None] | None
+    _forced_close_pending: bool
 
     async def _start_processing(
         self, connection: ClientConnection, conn_generation: int
@@ -80,6 +103,37 @@ class SupervisorMixin:
         if message.ref is not None and message.ref == self._pending_heartbeat_ref:
             self.logger.debug("Heartbeat acknowledged (ref=%s)", message.ref)
             self._pending_heartbeat_ref = None
+            if self._on_heartbeat_ack is not None:
+                try:
+                    result = self._on_heartbeat_ack()
+                    if inspect.iscoroutine(result):
+                        result.close()
+                        raise TypeError(
+                            "on_heartbeat_ack must be synchronous; an async "
+                            "function was passed and its body never ran"
+                        )
+                except Exception:
+                    self.logger.exception("Error in on_heartbeat_ack callback")
+
+    async def _invoke_callback_safely(
+        self, label: str, callback: Callable[..., Awaitable[None]], *args: object
+    ) -> None:
+        try:
+            await callback(*args)
+        except Exception:
+            self.logger.exception("Error in %s callback", label)
+
+    async def close_connection(self, reason: str) -> None:
+        """Force-close the current connection so the supervisor's own
+        disconnect handling decides whether to reconnect. No-op if not
+        currently connected."""
+        connection = self.connection
+        if connection is None:
+            return
+        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:
@@ -105,7 +159,7 @@ class SupervisorMixin:
                 self._pending_heartbeat_ref = ref
 
                 heartbeat_message = make_message(
-                    topic="phoenix",
+                    topic=PHOENIX_TOPIC,
                     event=Event("heartbeat"),
                     payload={},
                     ref=ref,
@@ -208,10 +262,9 @@ class SupervisorMixin:
                     self._initial_connection_future.set_result(None)
 
                 if generation > 1 and self._on_reconnect is not None:
-                    try:
-                        await self._on_reconnect()
-                    except Exception:
-                        self.logger.exception("Error in on_reconnect callback")
+                    await self._invoke_callback_safely(
+                        "on_reconnect", self._on_reconnect
+                    )
 
                 try:
                     await self._message_routing_task
@@ -234,14 +287,15 @@ class SupervisorMixin:
                     connection=connection,
                     routing_error=routing_error,
                 )
+                forced_close = self._forced_close_pending
+                self._forced_close_pending = False
 
                 await self._cleanup_connection()
 
                 if self._on_disconnect is not None:
-                    try:
-                        await self._on_disconnect(routing_error)
-                    except Exception:
-                        self.logger.exception("Error in on_disconnect callback")
+                    await self._invoke_callback_safely(
+                        "on_disconnect", self._on_disconnect, routing_error
+                    )
 
                 if self._shutdown_event.is_set():
                     break
@@ -249,7 +303,17 @@ class SupervisorMixin:
                 if not self.auto_reconnect:
                     break
 
-                decision = runtime_deps._classify_disconnect(close_code, close_reason)
+                if forced_close:
+                    # The remote's echoed close code isn't guaranteed to match
+                    # what we sent (websockets' close_code reflects the code
+                    # *received*, not sent), so classification would be
+                    # unreliable here; a forced close always reconnects like
+                    # any other unclassified disconnect.
+                    decision = ReconnectDecision(should_reconnect=True)
+                else:
+                    decision = runtime_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)

{phoenix_channels_python_client-0.2.2.dist-info → phoenix_channels_python_client-0.2.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phoenix-channels-python-client
-Version: 0.2.2
+Version: 0.2.4
 Summary: A Python client library for connecting to Phoenix Channels
 Author: Phoenix Channels Python Client
 License-Expression: MIT
@@ -42,8 +42,8 @@ A modern, async Python client library for connecting to [Phoenix Channels](https
 Install from source:
 
 ```bash
-git clone https://github.com/your-org/phoenix_channels_python_client.git
-cd phoenix_channels_python_client
+git clone https://github.com/band-ai/phoenix-channels-python-client.git
+cd phoenix-channels-python-client
 python3 -m venv venv
 source venv/bin/activate  # On Windows: venv\Scripts\activate
 pip install .
@@ -54,8 +54,8 @@ pip install .
 Set up development environment:
 
 ```bash
-git clone https://github.com/your-org/phoenix_channels_python_client.git
-cd phoenix_channels_python_client
+git clone https://github.com/band-ai/phoenix-channels-python-client.git
+cd phoenix-channels-python-client
 python3 -m venv venv
 source venv/bin/activate  # On Windows: venv\Scripts\activate
 python3 -m pip install -U pip

phoenix_channels_python_client-0.2.4.dist-info/RECORD

@@ -0,0 +1,17 @@
+phoenix_channels_python_client/__init__.py,sha256=EVdevvtteX6B9wQewjgbn_f_S3H-w4YkIRpeXK0oKZE,791
+phoenix_channels_python_client/client.py,sha256=EAy1vVC3JInfNk6RYvbE6d8ZC5YmPNho1q474IrptHQ,9546
+phoenix_channels_python_client/client_state_machine.py,sha256=Exr5wjYB0VXpCq1-tGHN4VraNman1M1vWN073rRFZFo,1124
+phoenix_channels_python_client/client_types.py,sha256=Gyyf72zDpAZtGcnbXJMW6Xj6PksdOM6bh-BXjlN6U5Y,3889
+phoenix_channels_python_client/exceptions.py,sha256=1cpnD_SO3En-yZKS47QSlLjLnK-29gOBcBVHoBQVMkg,227
+phoenix_channels_python_client/phx_messages.py,sha256=lvtyECL_CwUlP_yom57f0U_OpGJsOqETy7KEtdu_yf4,1214
+phoenix_channels_python_client/protocol_handler.py,sha256=ohnZN0Z3GmM0xiRAhLD5n4XtbL37A_HvEgs5b_uBmg8,8141
+phoenix_channels_python_client/reconnect_controller.py,sha256=R924_f59fQN7jvQXFfQxKb6LDBYxheSPszOFETpZ5iI,11025
+phoenix_channels_python_client/supervisor.py,sha256=OU1ywX1dAAvw1cNNtFaO6CqdI_G_J7oRevx-rzpQrUI,18133
+phoenix_channels_python_client/topic_runtime.py,sha256=IkZ6tXxRP5Svc8vkuAUo-ic5K_pfsHmYHmabRAHmYnQ,21829
+phoenix_channels_python_client/topic_subscription.py,sha256=J0wcCsfP9laQ7DxT-6e7OdhQrK_t1zu3n3gcnuedvFI,1916
+phoenix_channels_python_client/utils.py,sha256=MdxW2tq5MTCE7RQhhajwChMipSHXJyopBwq5ORo0Vao,1616
+phoenix_channels_python_client-0.2.4.dist-info/licenses/LICENSE,sha256=zwqkIClV_fMWOC0Auvd0DYqZMLL0-hIqeKd6tygE39g,1064
+phoenix_channels_python_client-0.2.4.dist-info/METADATA,sha256=gPYMjC6UbmF8CSHUh7U5VV6WZ7sJZe1GS_ZbsC5nUTM,9157
+phoenix_channels_python_client-0.2.4.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+phoenix_channels_python_client-0.2.4.dist-info/top_level.txt,sha256=ZYXMGCOeev4cyNU9XvNGHKt1wOgVkFHaS9TlwDa4eDU,31
+phoenix_channels_python_client-0.2.4.dist-info/RECORD,,

{phoenix_channels_python_client-0.2.2.dist-info → phoenix_channels_python_client-0.2.4.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (83.0.0)
+Generator: setuptools (84.0.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

phoenix_channels_python_client-0.2.2.dist-info/RECORD

@@ -1,17 +0,0 @@
-phoenix_channels_python_client/__init__.py,sha256=LCv6fVM36IZ2Vf60SlKFZnmcT8vkJS7wgvfTitS-sac,737
-phoenix_channels_python_client/client.py,sha256=1h-34mci3HB7UtBI_3JmZVep_-9coXxCNS7NnWfOUZk,9148
-phoenix_channels_python_client/client_state_machine.py,sha256=Exr5wjYB0VXpCq1-tGHN4VraNman1M1vWN073rRFZFo,1124
-phoenix_channels_python_client/client_types.py,sha256=Gyyf72zDpAZtGcnbXJMW6Xj6PksdOM6bh-BXjlN6U5Y,3889
-phoenix_channels_python_client/exceptions.py,sha256=1cpnD_SO3En-yZKS47QSlLjLnK-29gOBcBVHoBQVMkg,227
-phoenix_channels_python_client/phx_messages.py,sha256=EiJX0KbcpJBtNj0r3j4zdN9qCb7fzJB87TtjuFYGDwQ,1186
-phoenix_channels_python_client/protocol_handler.py,sha256=6nuespMcWWhVQwea8W3eANr_Ea6BcZBqNj1ui1WvDuE,8105
-phoenix_channels_python_client/reconnect_controller.py,sha256=v2YXx5qVlxxQw8jUy-5kvrkMDR_slRRVqhJr7GrZsUk,10825
-phoenix_channels_python_client/supervisor.py,sha256=l4-awiJiSVU4qBhCJeDkKnNnAw_1dLWlrE0y_2e74Zw,15464
-phoenix_channels_python_client/topic_runtime.py,sha256=IkZ6tXxRP5Svc8vkuAUo-ic5K_pfsHmYHmabRAHmYnQ,21829
-phoenix_channels_python_client/topic_subscription.py,sha256=J0wcCsfP9laQ7DxT-6e7OdhQrK_t1zu3n3gcnuedvFI,1916
-phoenix_channels_python_client/utils.py,sha256=MdxW2tq5MTCE7RQhhajwChMipSHXJyopBwq5ORo0Vao,1616
-phoenix_channels_python_client-0.2.2.dist-info/licenses/LICENSE,sha256=zwqkIClV_fMWOC0Auvd0DYqZMLL0-hIqeKd6tygE39g,1064
-phoenix_channels_python_client-0.2.2.dist-info/METADATA,sha256=uKqLijxsab8Y8Q962t4lxi8u6Rsv3HzXoz-6QG543xE,9159
-phoenix_channels_python_client-0.2.2.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-phoenix_channels_python_client-0.2.2.dist-info/top_level.txt,sha256=ZYXMGCOeev4cyNU9XvNGHKt1wOgVkFHaS9TlwDa4eDU,31
-phoenix_channels_python_client-0.2.2.dist-info/RECORD,,