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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phoenix-channels-python-client
-Version: 0.2.5
+Version: 0.3.1
 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()`.
@@ -349,7 +365,7 @@ setup_logging(logging.DEBUG)  # loggers live under "phoenix_channels_python_clie
 
 ## Security Considerations
 
-**API Key in URL**: This client passes the API key as a URL query parameter when connecting to the WebSocket (e.g., `wss://server.com/socket?api_key=xxx`). Even over WSS (encrypted in transit), the API key may be logged by:
+**API Key in URL**: Without an authentication header, this client passes the API key as a URL query parameter when connecting to the WebSocket (e.g., `wss://server.com/socket?api_key=xxx`). Even over WSS (encrypted in transit), the API key may be logged by:
 
 - Server access logs
 - Reverse proxies and load balancers
@@ -360,8 +376,28 @@ setup_logging(logging.DEBUG)  # loggers live under "phoenix_channels_python_clie
 - Use short-lived, rotatable tokens rather than long-lived API keys
 - Consider this limitation when evaluating this client for sensitive environments
 
-**Note:** The official Phoenix JS client (v1.8+) supports header-based authentication via the `authToken` option, which avoids URL logging. This client always sends `api_key` in the URL (logged URLs show `api_key=***`). Pass `additional_headers={"x-api-key": key}` to also send it as a handshake header on every (re)connect, e.g. for a proxy that reads it from there.
+Pass `additional_headers={"x-api-key": key}` or `{"x-auth-token": jwt}` to use header-only authentication on every connection and reconnect.
 
 ---
 
 **Need help?** Open an issue on GitHub or check the [Phoenix Channels documentation](https://hexdocs.pm/phoenix/channels.html) for more information about the Phoenix Channels protocol.
+
+### Authentication and diagnostic safety
+
+A nonempty `x-api-key` or `x-auth-token` handshake header selects header-only authentication on
+every connection and reconnect. Embedded API-key parameters are removed; empty
+or conflicting authentication headers and simultaneous token-query authentication
+are rejected before connecting. A JWT header overrides an embedded token and takes
+precedence over an API-key header, matching the platform. Without an authentication header, legacy query authentication
+is preserved and remains visible to servers and proxies. No fallback is attempted.
+
+`client.logger` forwards sanitized connection records without raw arguments,
+exception objects, or socket metadata. `client.redact_diagnostic(text)` applies
+the credential policy to transport errors a caller needs to retain. Caller-visible
+errors may still contain personal data and should not be logged outside this policy.
+
+Connection diagnostics omit dynamic strings and transport payloads, including URLs,
+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.

{phoenix_channels_python_client-0.2.5 → phoenix_channels_python_client-0.3.1}/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()`.
@@ -320,7 +334,7 @@ setup_logging(logging.DEBUG)  # loggers live under "phoenix_channels_python_clie
 
 ## Security Considerations
 
-**API Key in URL**: This client passes the API key as a URL query parameter when connecting to the WebSocket (e.g., `wss://server.com/socket?api_key=xxx`). Even over WSS (encrypted in transit), the API key may be logged by:
+**API Key in URL**: Without an authentication header, this client passes the API key as a URL query parameter when connecting to the WebSocket (e.g., `wss://server.com/socket?api_key=xxx`). Even over WSS (encrypted in transit), the API key may be logged by:
 
 - Server access logs
 - Reverse proxies and load balancers
@@ -331,8 +345,28 @@ setup_logging(logging.DEBUG)  # loggers live under "phoenix_channels_python_clie
 - Use short-lived, rotatable tokens rather than long-lived API keys
 - Consider this limitation when evaluating this client for sensitive environments
 
-**Note:** The official Phoenix JS client (v1.8+) supports header-based authentication via the `authToken` option, which avoids URL logging. This client always sends `api_key` in the URL (logged URLs show `api_key=***`). Pass `additional_headers={"x-api-key": key}` to also send it as a handshake header on every (re)connect, e.g. for a proxy that reads it from there.
+Pass `additional_headers={"x-api-key": key}` or `{"x-auth-token": jwt}` to use header-only authentication on every connection and reconnect.
 
 ---
 
 **Need help?** Open an issue on GitHub or check the [Phoenix Channels documentation](https://hexdocs.pm/phoenix/channels.html) for more information about the Phoenix Channels protocol.
+
+### Authentication and diagnostic safety
+
+A nonempty `x-api-key` or `x-auth-token` handshake header selects header-only authentication on
+every connection and reconnect. Embedded API-key parameters are removed; empty
+or conflicting authentication headers and simultaneous token-query authentication
+are rejected before connecting. A JWT header overrides an embedded token and takes
+precedence over an API-key header, matching the platform. Without an authentication header, legacy query authentication
+is preserved and remains visible to servers and proxies. No fallback is attempted.
+
+`client.logger` forwards sanitized connection records without raw arguments,
+exception objects, or socket metadata. `client.redact_diagnostic(text)` applies
+the credential policy to transport errors a caller needs to retain. Caller-visible
+errors may still contain personal data and should not be logged outside this policy.
+
+Connection diagnostics omit dynamic strings and transport payloads, including URLs,
+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.

{phoenix_channels_python_client-0.2.5 → phoenix_channels_python_client-0.3.1}/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.1"
 __author__ = "Phoenix Channels Python Client"
 
 __all__ = [
@@ -30,5 +30,6 @@ __all__ = [
     "PhoenixChannelsProtocolVersion",
     "ReconnectCallback",
     "ReconnectPolicy",
+    "TopicLostCallback",
     "setup_logging",
 ]

phoenix_channels_python_client-0.3.1/phoenix_channels_python_client/authentication.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from enum import StrEnum
+
+API_KEY_PARAMETER = "api_key"
+TOKEN_PARAMETER = "token"  # noqa: S105 -- protocol parameter name
+
+
+class AuthenticationHeader(StrEnum):
+    API_KEY = "x-api-key"
+    TOKEN = "x-auth-token"  # noqa: S105 -- protocol header name
+
+
+def normalize_headers(headers: dict[str, str] | None) -> dict[str, str]:
+    normalized = dict(headers or {})
+    for header in AuthenticationHeader:
+        credentials = [
+            value for name, value in normalized.items() if name.casefold() == header
+        ]
+        if not credentials:
+            continue
+        if (
+            any(not value.strip() for value in credentials)
+            or len(set(credentials)) != 1
+        ):
+            raise ValueError(f"{header} headers must contain one nonempty credential")
+        normalized = {
+            name: value
+            for name, value in normalized.items()
+            if name.casefold() != header
+        }
+        normalized[header] = credentials[0]
+    return normalized
+
+
+def select_authentication_header(
+    headers: dict[str, str],
+) -> AuthenticationHeader | None:
+    # The platform gives a supplied JWT precedence over an API key.
+    for header in (AuthenticationHeader.TOKEN, AuthenticationHeader.API_KEY):
+        if header in headers:
+            return header
+    return None

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

@@ -5,21 +5,29 @@ import logging
 from collections import deque
 from collections.abc import Awaitable, Callable
 from types import TracebackType
+from typing import Self, cast
 from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
 
 from websockets import ClientConnection
 
+from phoenix_channels_python_client.authentication import (
+    API_KEY_PARAMETER,
+    TOKEN_PARAMETER,
+    AuthenticationHeader,
+    normalize_headers,
+    select_authentication_header,
+)
 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.diagnostics import (
+    ConnectionLogger,
+    diagnostic_secrets,
 )
 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,51 +43,70 @@ 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(
-    websocket_url: str, api_key: str, vsn: str
+    websocket_url: str,
+    api_key: str,
+    vsn: str,
+    *,
+    header_auth: AuthenticationHeader | None = None,
 ) -> tuple[str, str]:
     split_url = urlsplit(websocket_url)
     query_params = parse_qsl(split_url.query, keep_blank_values=True)
+    if header_auth is AuthenticationHeader.API_KEY and any(
+        key.casefold() == TOKEN_PARAMETER and value for key, value in query_params
+    ):
+        raise ValueError("token query authentication cannot be combined with x-api-key")
     filtered = [
-        (key, value) for key, value in query_params if key not in {"api_key", "vsn"}
-    ]
-    with_auth = [*filtered, ("api_key", api_key), ("vsn", vsn)]
-
-    connect_url = urlunsplit(
-        (
-            split_url.scheme,
-            split_url.netloc,
-            split_url.path,
-            urlencode(with_auth),
-            split_url.fragment,
+        (key, value)
+        for key, value in query_params
+        if key.casefold()
+        not in (
+            {API_KEY_PARAMETER, "vsn", TOKEN_PARAMETER}
+            if header_auth
+            else {API_KEY_PARAMETER, "vsn"}
         )
-    )
-    redacted_url = urlunsplit(
-        (
-            split_url.scheme,
-            split_url.netloc,
-            split_url.path,
-            urlencode(
-                [
-                    (key, "***" if key == "api_key" else value)
-                    for key, value in with_auth
-                ]
-            ),
-            split_url.fragment,
+    ]
+    with_auth = [
+        *filtered,
+        *([] if header_auth else [(API_KEY_PARAMETER, api_key)]),
+        ("vsn", vsn),
+    ]
+
+    def build(params: list[tuple[str, str]]) -> str:
+        return urlunsplit(
+            (
+                split_url.scheme,
+                split_url.netloc,
+                split_url.path,
+                urlencode(params),
+                split_url.fragment,
+            )
         )
+
+    return build(with_auth), build(
+        [
+            (
+                key,
+                "***"
+                if key.casefold() in {API_KEY_PARAMETER, TOKEN_PARAMETER}
+                else value,
+            )
+            for key, value in with_auth
+        ]
     )
-    return connect_url, redacted_url
 
 
 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,9 +117,13 @@ 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,
-    ):
-        self.logger = logger
+    ) -> None:
+        self.additional_headers = normalize_headers(additional_headers)
+        self.logger = ConnectionLogger(
+            logger, diagnostic_secrets(websocket_url, api_key, self.additional_headers)
+        )
 
         if heartbeat_interval_s is not None and heartbeat_interval_s <= 0:
             raise ValueError("heartbeat_interval_s must be > 0 or None to disable")
@@ -105,30 +136,19 @@ 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, diagnostic_logger=self.logger
         )
         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,
+            header_auth=select_authentication_header(self.additional_headers),
         )
         self.channel_socket_url = connect_url
         self.channel_socket_url_redacted = redacted_url
 
-        # Extra WebSocket handshake headers, re-sent on every (re)connect. Lets a
-        # caller send the API key as an ``x-api-key`` header instead of (or
-        # alongside) the URL query, so a trusted proxy can inject/replace it
-        # in-header and the credential stays out of URL/proxy logs.
-        self.additional_headers = dict(additional_headers or {})
-
         self.auto_reconnect = auto_reconnect
         self.reconnect_policy = reconnect_policy or ReconnectPolicy()
         self.join_timeout_s = join_timeout_s
@@ -138,7 +158,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,8 +176,14 @@ 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
 
+    def redact_diagnostic(self, text: str) -> str:
+        """Sanitize untrusted transport error text using this connection's policy."""
+        return cast(ConnectionLogger, self.logger).redact(text)
+
     @property
     def _active_shutdown(self) -> asyncio.Task[None] | None:
         task = self._shutdown_task
@@ -172,11 +197,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 +206,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 +247,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 +282,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.1}/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