phoenix-channels-python-client 0.2.5__tar.gz → 0.3.0__tar.gz

{phoenix_channels_python_client-0.2.5/phoenix_channels_python_client.egg-info → phoenix_channels_python_client-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phoenix-channels-python-client
-Version: 0.2.5
+Version: 0.3.0
 Summary: A Python client library for connecting to Phoenix Channels
 Author: Phoenix Channels Python Client
 License-Expression: MIT
@@ -14,10 +14,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"
@@ -60,21 +62,19 @@ Set up development environment:
 ```bash
 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
-pip install -e ".[dev]"
+uv sync --extra dev
 ```
 
 Run tests:
 
 ```bash
-pytest
+uv run pytest
 ```
 
 ### Dependencies
 
 - Python 3.11+
+- `pydantic>=2.8`
 - `websockets>=14.2`
 
 ## Quick Start
@@ -144,11 +144,11 @@ Phoenix reserves `phx_join`, `phx_reply`, `phx_leave`, `phx_close` and
 `phx_error`. Don't use these names for your own events.
 
 - The client sends `phx_join` and `phx_leave` and consumes their `phx_reply`.
-- A server `phx_close` or `phx_error` reaches your message handler like any
-  other message; the client does not rejoin or unsubscribe on its own.
-- For an event-specific handler on these, register `PHXEvent.close` or
-  `PHXEvent.error` from `phoenix_channels_python_client.phx_messages`; the
-  plain strings don't match.
+- The client handles `phx_error` and `phx_close` itself, and neither reaches
+  your handlers: a crashed channel is rejoined, and a channel the server
+  closes loses its topic (see [Channel recovery](#channel-recovery)).
+- `add_event_handler` raises `ValueError` for `PHXEvent.error` and
+  `PHXEvent.close`. Use `on_topic_lost` and `is_topic_joined()` instead.
 
 ## Protocol Versions
 
@@ -299,10 +299,11 @@ Everything after `api_key` is keyword-only:
 | `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 a running callback may finish before a rejoin cancels it |
+| `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_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.
@@ -311,8 +312,8 @@ Exceptions raised in callbacks are logged, not raised.
 
 - `async with` waits for the first connection. With `auto_reconnect=True` it keeps retrying; with `auto_reconnect=False` a failed first connection raises `PHXConnectionError`.
 - `run_forever()` returns `None` after `shutdown()`, a signal, or a close that doesn't reconnect. It raises `PHXConnectionError` on a terminal close, after repeated rapid disconnects, or when the client has never entered `async with`.
-- `subscribe_to_topic()` raises `PHXTopicError` on a rejected join, a join timeout or a duplicate subscription.
-- `await client.close_connection(reason)` force-closes the current connection; the client then reconnects if `auto_reconnect` is on.
+- `subscribe_to_topic()` raises `PHXTopicError` on a rejected join, a join timeout or a duplicate subscription, and `PHXConnectionError` while disconnected or if the connection drops before the join completes.
+- `await client.close_connection(reason)` force-closes the current connection; the client then reconnects if `auto_reconnect` is on. It does nothing if the client isn't connected or the connection is already closing.
 - Exceptions live in `phoenix_channels_python_client.exceptions`.
 
 ### Reconnects
@@ -327,6 +328,21 @@ Exceptions raised in callbacks are logged, not raised.
 
 Disconnects within 5 s of connecting count as rapid and get longer minimum delays; ten within 60 s stop the client with `PHXConnectionError`. Tune all of this with `ReconnectPolicy`.
 
+A `ReconnectPolicy` is validated when it is built: an out-of-range or unknown field raises `pydantic.ValidationError`, which is a `ValueError`. To derive one policy from another, validate the merged fields:
+
+```python
+base = ReconnectPolicy()
+policy = ReconnectPolicy.model_validate(base.model_dump() | {"max_delay_s": 10.0})
+```
+
+### Channel recovery
+
+A channel can fail while the socket stays up. When its process crashes, the server sends `phx_error`, and the client rejoins that topic on the same socket, waiting the `ReconnectPolicy` backoff (`base_delay_s`, `factor`, `max_delay_s`, with equal jitter) before each attempt. A rejoin that times out is retried the same way, including one after a socket reconnect. A drop of the socket hands the topic to the socket's own rejoin.
+
+The client drops the topic and calls `on_topic_lost(topic, error)` once when the server rejects a rejoin, after a crash or a reconnect, closes the channel with `phx_close`, or its message processor fails. It never calls it for `unsubscribe_from_topic()`, `shutdown()` or a failed first `subscribe_to_topic()`, which raises instead. Subscribing to the topic again from the callback works. `shutdown()` cancels the callback, including when the callback itself called `shutdown()`, so code after that call does not run.
+
+`get_current_subscriptions()` lists the subscribed topics. `is_topic_joined(topic)` tells whether a topic's channel is joined right now: it's false while the socket is down or a crashed channel waits to rejoin. Unsubscribing a topic whose channel is being recovered completes without waiting for a leave reply.
+
 ### 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()`.

{phoenix_channels_python_client-0.2.5 → phoenix_channels_python_client-0.3.0}/README.md

@@ -31,21 +31,19 @@ Set up development environment:
 ```bash
 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
-pip install -e ".[dev]"
+uv sync --extra dev
 ```
 
 Run tests:
 
 ```bash
-pytest
+uv run pytest
 ```
 
 ### Dependencies
 
 - Python 3.11+
+- `pydantic>=2.8`
 - `websockets>=14.2`
 
 ## Quick Start
@@ -115,11 +113,11 @@ Phoenix reserves `phx_join`, `phx_reply`, `phx_leave`, `phx_close` and
 `phx_error`. Don't use these names for your own events.
 
 - The client sends `phx_join` and `phx_leave` and consumes their `phx_reply`.
-- A server `phx_close` or `phx_error` reaches your message handler like any
-  other message; the client does not rejoin or unsubscribe on its own.
-- For an event-specific handler on these, register `PHXEvent.close` or
-  `PHXEvent.error` from `phoenix_channels_python_client.phx_messages`; the
-  plain strings don't match.
+- The client handles `phx_error` and `phx_close` itself, and neither reaches
+  your handlers: a crashed channel is rejoined, and a channel the server
+  closes loses its topic (see [Channel recovery](#channel-recovery)).
+- `add_event_handler` raises `ValueError` for `PHXEvent.error` and
+  `PHXEvent.close`. Use `on_topic_lost` and `is_topic_joined()` instead.
 
 ## Protocol Versions
 
@@ -270,10 +268,11 @@ Everything after `api_key` is keyword-only:
 | `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 a running callback may finish before a rejoin cancels it |
+| `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_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.
@@ -282,8 +281,8 @@ Exceptions raised in callbacks are logged, not raised.
 
 - `async with` waits for the first connection. With `auto_reconnect=True` it keeps retrying; with `auto_reconnect=False` a failed first connection raises `PHXConnectionError`.
 - `run_forever()` returns `None` after `shutdown()`, a signal, or a close that doesn't reconnect. It raises `PHXConnectionError` on a terminal close, after repeated rapid disconnects, or when the client has never entered `async with`.
-- `subscribe_to_topic()` raises `PHXTopicError` on a rejected join, a join timeout or a duplicate subscription.
-- `await client.close_connection(reason)` force-closes the current connection; the client then reconnects if `auto_reconnect` is on.
+- `subscribe_to_topic()` raises `PHXTopicError` on a rejected join, a join timeout or a duplicate subscription, and `PHXConnectionError` while disconnected or if the connection drops before the join completes.
+- `await client.close_connection(reason)` force-closes the current connection; the client then reconnects if `auto_reconnect` is on. It does nothing if the client isn't connected or the connection is already closing.
 - Exceptions live in `phoenix_channels_python_client.exceptions`.
 
 ### Reconnects
@@ -298,6 +297,21 @@ Exceptions raised in callbacks are logged, not raised.
 
 Disconnects within 5 s of connecting count as rapid and get longer minimum delays; ten within 60 s stop the client with `PHXConnectionError`. Tune all of this with `ReconnectPolicy`.
 
+A `ReconnectPolicy` is validated when it is built: an out-of-range or unknown field raises `pydantic.ValidationError`, which is a `ValueError`. To derive one policy from another, validate the merged fields:
+
+```python
+base = ReconnectPolicy()
+policy = ReconnectPolicy.model_validate(base.model_dump() | {"max_delay_s": 10.0})
+```
+
+### Channel recovery
+
+A channel can fail while the socket stays up. When its process crashes, the server sends `phx_error`, and the client rejoins that topic on the same socket, waiting the `ReconnectPolicy` backoff (`base_delay_s`, `factor`, `max_delay_s`, with equal jitter) before each attempt. A rejoin that times out is retried the same way, including one after a socket reconnect. A drop of the socket hands the topic to the socket's own rejoin.
+
+The client drops the topic and calls `on_topic_lost(topic, error)` once when the server rejects a rejoin, after a crash or a reconnect, closes the channel with `phx_close`, or its message processor fails. It never calls it for `unsubscribe_from_topic()`, `shutdown()` or a failed first `subscribe_to_topic()`, which raises instead. Subscribing to the topic again from the callback works. `shutdown()` cancels the callback, including when the callback itself called `shutdown()`, so code after that call does not run.
+
+`get_current_subscriptions()` lists the subscribed topics. `is_topic_joined(topic)` tells whether a topic's channel is joined right now: it's false while the socket is down or a crashed channel waits to rejoin. Unsubscribing a topic whose channel is being recovered completes without waiting for a leave reply.
+
 ### 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()`.

{phoenix_channels_python_client-0.2.5 → phoenix_channels_python_client-0.3.0}/phoenix_channels_python_client/__init__.py

@@ -1,5 +1,4 @@
-"""
-Phoenix Channels Python Client
+"""Phoenix Channels Python Client.
 
 A Python client library for connecting to Phoenix Channels.
 """
@@ -12,14 +11,15 @@ from phoenix_channels_python_client.client import (
     PHXChannelsClient,
     ReconnectCallback,
     ReconnectPolicy,
+    TopicLostCallback,
 )
 from phoenix_channels_python_client.protocol_handler import (
-    PHXProtocolHandler,
     PhoenixChannelsProtocolVersion,
+    PHXProtocolHandler,
 )
 from phoenix_channels_python_client.utils import setup_logging
 
-__version__ = "0.2.5"
+__version__ = "0.3.0"
 __author__ = "Phoenix Channels Python Client"
 
 __all__ = [
@@ -30,5 +30,6 @@ __all__ = [
     "PhoenixChannelsProtocolVersion",
     "ReconnectCallback",
     "ReconnectPolicy",
+    "TopicLostCallback",
     "setup_logging",
 ]

{phoenix_channels_python_client-0.2.5 → phoenix_channels_python_client-0.3.0}/phoenix_channels_python_client/client.py

@@ -5,21 +5,18 @@ import logging
 from collections import deque
 from collections.abc import Awaitable, Callable
 from types import TracebackType
+from typing import Self
 from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
 
 from websockets import ClientConnection
 
 from phoenix_channels_python_client.client_state_machine import transition_client_state
-from phoenix_channels_python_client.client_types import (
-    ClientState,
-    ReconnectPolicy,
-    reconnect_policy_is_invalid,
-    validate_reconnect_policy,
-)
+from phoenix_channels_python_client.client_types import ClientState, ReconnectPolicy
 from phoenix_channels_python_client.exceptions import PHXConnectionError
 from phoenix_channels_python_client.protocol_handler import (
-    PHXProtocolHandler,
+    DEFAULT_PROTOCOL_VERSION,
     PhoenixChannelsProtocolVersion,
+    PHXProtocolHandler,
 )
 from phoenix_channels_python_client.reconnect_controller import ReconnectControllerMixin
 from phoenix_channels_python_client.supervisor import SupervisorMixin
@@ -35,6 +32,7 @@ DisconnectCallback = Callable[[Exception | None], Awaitable[None]]
 # on the message-routing hot path, so blocking work here stalls heartbeat
 # sends and message routing for every connection.
 HeartbeatAckCallback = Callable[[], None]
+TopicLostCallback = Callable[[str, Exception], Awaitable[None]]
 
 
 def _build_channel_socket_urls(
@@ -74,12 +72,13 @@ def _build_channel_socket_urls(
 
 
 class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerMixin):
-    def __init__(
+    def __init__(  # noqa: PLR0913  # the public options
         self,
         websocket_url: str,
         api_key: str,
         *,
-        protocol_version: PhoenixChannelsProtocolVersion = PhoenixChannelsProtocolVersion.V2,
+        protocol_version: PhoenixChannelsProtocolVersion
+        | str = DEFAULT_PROTOCOL_VERSION,
         auto_reconnect: bool = True,
         reconnect_policy: ReconnectPolicy | None = None,
         join_timeout_s: float = 10.0,
@@ -90,8 +89,9 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
         on_reconnect: ReconnectCallback | None = None,
         on_disconnect: DisconnectCallback | None = None,
         on_heartbeat_ack: HeartbeatAckCallback | None = None,
+        on_topic_lost: TopicLostCallback | None = None,
         additional_headers: dict[str, str] | None = None,
-    ):
+    ) -> None:
         self.logger = logger
 
         if heartbeat_interval_s is not None and heartbeat_interval_s <= 0:
@@ -105,20 +105,12 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
             raise ValueError("max_topic_queue_size must be > 0")
         if callback_drain_timeout_s <= 0:
             raise ValueError("callback_drain_timeout_s must be > 0")
-        try:
-            validate_reconnect_policy(reconnect_policy or ReconnectPolicy())
-        except ValueError as exc:
-            raise ValueError("Invalid reconnect policy configuration") from exc
-
-        vsn = (
-            "2.0.0"
-            if protocol_version == PhoenixChannelsProtocolVersion.V2
-            else "1.0.0"
-        )
+
+        self._protocol_handler = PHXProtocolHandler(protocol_version)
         connect_url, redacted_url = _build_channel_socket_urls(
             websocket_url=websocket_url,
             api_key=api_key,
-            vsn=vsn,
+            vsn=self._protocol_handler.protocol_version.vsn,
         )
         self.channel_socket_url = connect_url
         self.channel_socket_url_redacted = redacted_url
@@ -138,7 +130,6 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
 
         self.connection: ClientConnection | None = None
         self._topic_subscriptions: dict[str, TopicSubscription] = {}
-        self._protocol_handler = PHXProtocolHandler(protocol_version)
         self._ref_counter = 0
         self._state = ClientState.CLOSED
         self._topics_lock = asyncio.Lock()
@@ -157,6 +148,8 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
         self._on_reconnect = on_reconnect
         self._on_disconnect = on_disconnect
         self._on_heartbeat_ack = on_heartbeat_ack
+        self._on_topic_lost = on_topic_lost
+        self._lifecycle_tasks: set[asyncio.Task[None]] = set()
         self._forced_close_pending = False
 
     @property
@@ -172,11 +165,7 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
             and self.connection is None
         )
 
-    @staticmethod
-    def reconnect_policy_is_invalid(policy: ReconnectPolicy) -> bool:
-        return reconnect_policy_is_invalid(policy)
-
-    async def __aenter__(self) -> PHXChannelsClient:
+    async def __aenter__(self) -> Self:
         self.logger.debug("Entering PHXChannelsClient context")
         if self._state != ClientState.CLOSED or self._active_shutdown is not None:
             raise PHXConnectionError("Client is already running")
@@ -185,6 +174,7 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
         self._connected_event.clear()
         self._rapid_disconnects.clear()
         self._terminal_error = None
+        self._conn_generation = 0
         self._initial_connection_future = asyncio.get_running_loop().create_future()
         self._transition_state(ClientState.CONNECTING)
 
@@ -225,6 +215,8 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
         self._shutdown_event.set()
 
         await self._unsubscribe_all()
+        # Includes on_topic_lost callbacks still running for topics already gone.
+        await cancel_and_wait(*self._lifecycle_tasks)
         await self._stop_supervisor()
         await self._cleanup_connection()
         self._connected_event.clear()
@@ -258,7 +250,5 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
             return
 
         transitioned_state = transition_client_state(self._state, new_state)
-        self.logger.debug(
-            "Client state transition: %s -> %s", self._state.value, new_state.value
-        )
+        self.logger.debug("Client state transition: %s -> %s", self._state, new_state)
         self._state = transitioned_state

{phoenix_channels_python_client-0.2.5 → phoenix_channels_python_client-0.3.0}/phoenix_channels_python_client/client_state_machine.py

@@ -31,8 +31,6 @@ def transition_client_state(
     }
 
     if new_state not in allowed_transitions[current]:
-        raise RuntimeError(
-            f"Invalid state transition {current.value} -> {new_state.value}"
-        )
+        raise RuntimeError(f"Invalid state transition {current} -> {new_state}")
 
     return new_state

phoenix_channels_python_client-0.3.0/phoenix_channels_python_client/client_types.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Self
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    NonNegativeFloat,
+    NonNegativeInt,
+    PositiveFloat,
+    model_validator,
+)
+
+from phoenix_channels_python_client.exceptions import PHXConnectionError
+
+
+class ClientState(StrEnum):
+    CONNECTING = "connecting"
+    CONNECTED = "connected"
+    RECONNECTING = "reconnecting"
+    SHUTTING_DOWN = "shutting_down"
+    CLOSED = "closed"
+
+
+# Each (low, high) pair of fields where high must not be below low.
+_ORDERED_POLICY_FIELDS = (
+    ("service_restart_min_delay_s", "service_restart_max_delay_s"),
+    ("try_again_later_min_delay_s", "try_again_later_max_delay_s"),
+    ("rapid_cooldown_base_s", "rapid_cooldown_max_s"),
+    ("rapid_hold_down_jitter_low_ratio", "rapid_hold_down_jitter_high_ratio"),
+)
+
+
+class ReconnectPolicy(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    base_delay_s: NonNegativeFloat = 0.5
+    factor: PositiveFloat = 2.0
+    max_delay_s: NonNegativeFloat = 30.0
+    stable_reset_s: PositiveFloat = 60.0
+    reconnect_on_normal_close: bool = False
+    policy_violation_is_terminal: bool = True
+    service_restart_min_delay_s: NonNegativeFloat = 1.0
+    service_restart_max_delay_s: NonNegativeFloat = 5.0
+    try_again_later_min_delay_s: NonNegativeFloat = 30.0
+    try_again_later_max_delay_s: NonNegativeFloat = 60.0
+    rapid_disconnect_uptime_s: NonNegativeFloat = 5.0
+    rapid_window_s: PositiveFloat = 60.0
+    rapid_first_min_delay_s: NonNegativeFloat = 2.0
+    rapid_second_min_delay_s: NonNegativeFloat = 10.0
+    rapid_cooldown_base_s: NonNegativeFloat = 60.0
+    rapid_cooldown_step_s: NonNegativeFloat = 30.0
+    rapid_cooldown_max_s: NonNegativeFloat = 300.0
+    rapid_suppress_disconnect_count: NonNegativeInt = 10
+    rapid_hold_down_jitter_low_ratio: NonNegativeFloat = 0.25
+    rapid_hold_down_jitter_high_ratio: NonNegativeFloat = 1.0
+
+    @model_validator(mode="after")
+    def _check_ordering(self) -> Self:
+        for low, high in _ORDERED_POLICY_FIELDS:
+            if getattr(self, high) < getattr(self, low):
+                raise ValueError(f"{high} must be >= {low}")
+        return self
+
+
+@dataclass(frozen=True)
+class ReconnectDecision:
+    should_reconnect: bool
+    min_delay_s: float | None = None
+    max_delay_s: float | None = None
+    terminal_error: PHXConnectionError | None = None

{phoenix_channels_python_client-0.2.5 → phoenix_channels_python_client-0.3.0}/phoenix_channels_python_client/exceptions.py

@@ -8,5 +8,3 @@ class PHXTopicError(PHXClientError):
 
 class PHXConnectionError(PHXClientError):
     """Raised when there's an error connecting to the Phoenix WebSocket server."""
-
-    pass

{phoenix_channels_python_client-0.2.5 → phoenix_channels_python_client-0.3.0}/phoenix_channels_python_client/phx_messages.py

@@ -1,10 +1,10 @@
 from __future__ import annotations
 
-from dataclasses import dataclass
 from enum import Enum, unique
 from functools import cached_property
-from typing import Any, NewType
+from typing import Annotated, Any, NewType
 
+from pydantic import BaseModel, ConfigDict, Field
 
 PHOENIX_TOPIC = "phoenix"
 
@@ -21,16 +21,25 @@ class PHXEvent(Enum):
         return self.value
 
 
+# The client handles these itself: a crash rejoins, a close loses the topic.
+CLIENT_LIFECYCLE_EVENTS = frozenset({PHXEvent.error, PHXEvent.close})
+
 UserEvent = NewType("UserEvent", str)
 # Compatibility alias for existing imports and call sites.
 Event = UserEvent
+# Not a PHXEvent member: that would reroute make_message and change a public enum.
+HEARTBEAT_EVENT = Event("heartbeat")
 ChannelEvent = PHXEvent | UserEvent
 
+# Servers may send a ref as a JSON number; the client matches refs as strings.
+Ref = Annotated[str | None, Field(coerce_numbers_to_str=True)]
+
+
+class BasePHXMessage(BaseModel):
+    model_config = ConfigDict(frozen=True)
 
-@dataclass(frozen=True)
-class BasePHXMessage:
     topic: str
-    ref: str | None
+    ref: Ref
     payload: dict[str, Any]
 
     @cached_property
@@ -41,16 +50,14 @@ class BasePHXMessage:
         return subtopic
 
 
-@dataclass(frozen=True)
 class PHXMessage(BasePHXMessage):
     event: Event
-    join_ref: str | None = None
+    join_ref: Ref = None
 
 
-@dataclass(frozen=True)
 class PHXEventMessage(BasePHXMessage):
     event: PHXEvent
-    join_ref: str | None = None
+    join_ref: Ref = None
 
 
 ChannelMessage = PHXMessage | PHXEventMessage