phoenix-channels-python-client 0.2.2__tar.gz → 0.2.4__tar.gz

{phoenix_channels_python_client-0.2.2/phoenix_channels_python_client.egg-info → phoenix_channels_python_client-0.2.4}/PKG-INFO

@@ -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.2 → phoenix_channels_python_client-0.2.4}/README.md

@@ -13,8 +13,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 .
@@ -25,8 +25,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.2 → phoenix_channels_python_client-0.2.4}/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-0.2.2 → phoenix_channels_python_client-0.2.4}/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-0.2.2 → phoenix_channels_python_client-0.2.4}/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-0.2.2 → phoenix_channels_python_client-0.2.4}/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-0.2.2 → phoenix_channels_python_client-0.2.4}/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-0.2.2 → phoenix_channels_python_client-0.2.4}/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 → phoenix_channels_python_client-0.2.4/phoenix_channels_python_client.egg-info}/PKG-INFO

@@ -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.2 → phoenix_channels_python_client-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "phoenix-channels-python-client"
-version = "0.2.2"
+version = "0.2.4"
 description = "A Python client library for connecting to Phoenix Channels"
 readme = "README.md"
 license = "MIT"

{phoenix_channels_python_client-0.2.2 → phoenix_channels_python_client-0.2.4}/tests/test_internal_components.py

@@ -70,9 +70,11 @@ class _FakeSocket:
 
     def __post_init__(self) -> None:
         self.closed = False
+        self.close_calls: list[tuple[int | None, str]] = []
 
-    async def close(self) -> None:
+    async def close(self, code: int | None = None, reason: str = "") -> None:
         self.closed = True
+        self.close_calls.append((code, reason))
         if self.close_raises:
             raise RuntimeError("close boom")
 
@@ -150,6 +152,8 @@ class _SupervisorHarness(SupervisorMixin):
         self._ref_counter = 0
         self._on_reconnect = None
         self._on_disconnect = None
+        self._on_heartbeat_ack = None
+        self._forced_close_pending = False
 
         self.transition_history: list[ClientState] = []
         self.disconnect_uptimes: list[float] = []
@@ -977,3 +981,158 @@ async def test_supervisor_callback_exception_does_not_crash_loop(
 
     await harness._supervisor_loop()
     assert harness.connection is None
+
+
+@pytest.mark.asyncio
+async def test_handle_heartbeat_response_fires_on_heartbeat_ack_callback() -> None:
+    harness = _SupervisorHarness()
+    harness._pending_heartbeat_ref = "5"
+
+    ack_count = 0
+
+    def on_heartbeat_ack() -> None:
+        nonlocal ack_count
+        ack_count += 1
+
+    harness._on_heartbeat_ack = on_heartbeat_ack
+
+    harness._handle_heartbeat_response(
+        make_message(topic="phoenix", event=PHXEvent.reply, payload={}, ref="5")
+    )
+
+    assert ack_count == 1
+    assert harness._pending_heartbeat_ref is None
+
+
+@pytest.mark.asyncio
+async def test_handle_heartbeat_response_ignores_mismatched_ref() -> None:
+    harness = _SupervisorHarness()
+    harness._pending_heartbeat_ref = "5"
+
+    ack_count = 0
+
+    def on_heartbeat_ack() -> None:
+        nonlocal ack_count
+        ack_count += 1
+
+    harness._on_heartbeat_ack = on_heartbeat_ack
+
+    harness._handle_heartbeat_response(
+        make_message(topic="phoenix", event=PHXEvent.reply, payload={}, ref="not-5")
+    )
+
+    assert ack_count == 0
+    assert harness._pending_heartbeat_ref == "5"
+
+
+@pytest.mark.asyncio
+async def test_handle_heartbeat_response_callback_exception_does_not_propagate() -> (
+    None
+):
+    harness = _SupervisorHarness()
+    harness._pending_heartbeat_ref = "5"
+
+    def bad_heartbeat_ack() -> None:
+        raise ValueError("callback boom")
+
+    harness._on_heartbeat_ack = bad_heartbeat_ack
+
+    harness._handle_heartbeat_response(
+        make_message(topic="phoenix", event=PHXEvent.reply, payload={}, ref="5")
+    )
+
+    assert harness._pending_heartbeat_ref is None
+
+
+@pytest.mark.asyncio
+async def test_handle_heartbeat_response_rejects_async_callback() -> None:
+    harness = _SupervisorHarness()
+    harness._pending_heartbeat_ref = "5"
+
+    ran: list[bool] = []
+
+    async def async_on_heartbeat_ack() -> None:
+        ran.append(True)
+
+    harness._on_heartbeat_ack = async_on_heartbeat_ack  # type: ignore[assignment]
+
+    harness._handle_heartbeat_response(
+        make_message(topic="phoenix", event=PHXEvent.reply, payload={}, ref="5")
+    )
+
+    assert harness._pending_heartbeat_ref is None
+    assert ran == []
+
+
+@pytest.mark.asyncio
+async def test_close_connection_closes_current_connection_for_reconnect() -> None:
+    harness = _SupervisorHarness()
+    socket = _FakeSocket()
+    harness.connection = cast(ClientConnection, socket)
+
+    await harness.close_connection("dead threshold exceeded")
+
+    assert socket.closed
+    assert socket.close_calls == [(4000, "dead threshold exceeded")]
+
+
+@pytest.mark.asyncio
+async def test_close_connection_is_noop_when_not_connected() -> None:
+    harness = _SupervisorHarness()
+    harness.connection = None
+
+    await harness.close_connection("dead threshold exceeded")
+
+    assert harness.connection is None
+
+
+@pytest.mark.asyncio
+async def test_close_connection_truncates_oversized_reason() -> None:
+    harness = _SupervisorHarness()
+    socket = _FakeSocket()
+    harness.connection = cast(ClientConnection, socket)
+
+    await harness.close_connection("x" * 200)
+
+    assert socket.close_calls[0][0] == 4000
+    sent_reason = socket.close_calls[0][1]
+    assert len(sent_reason.encode("utf-8")) <= 123
+    assert sent_reason == "x" * 123
+
+
+@pytest.mark.asyncio
+async def test_disconnect_classification_applies_when_not_forced(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    harness = _SupervisorHarness()
+    harness.disconnect_decision = ReconnectDecision(should_reconnect=False)
+
+    monkeypatch.setattr(
+        "phoenix_channels_python_client.supervisor.connect",
+        lambda _: asyncio.sleep(0, result=cast(ClientConnection, _FakeSocket())),
+    )
+
+    await harness._supervisor_loop()
+
+    assert harness.wait_delays == []
+
+
+@pytest.mark.asyncio
+async def test_forced_close_bypasses_disconnect_classification(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    harness = _SupervisorHarness()
+    harness._forced_close_pending = True
+    # What the real _classify_disconnect would decide for whatever code the
+    # remote happened to echo back; the forced-close path must not consult it.
+    harness.disconnect_decision = ReconnectDecision(should_reconnect=False)
+
+    monkeypatch.setattr(
+        "phoenix_channels_python_client.supervisor.connect",
+        lambda _: asyncio.sleep(0, result=cast(ClientConnection, _FakeSocket())),
+    )
+
+    await harness._supervisor_loop()
+
+    assert harness.wait_delays == [0.001]
+    assert harness._forced_close_pending is False