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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phoenix-channels-python-client
-Version: 0.3.0
+Version: 0.4.0
 Summary: A Python client library for connecting to Phoenix Channels
 Author: Phoenix Channels Python Client
 License-Expression: MIT
@@ -310,18 +310,19 @@ Exceptions raised in callbacks are logged, not raised.
 
 ## Connection Lifecycle and Errors
 
-- `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`.
+- `async with` waits for the first connection. With `auto_reconnect=True` it keeps retrying, except after a refused handshake with HTTP 403, which raises `PHXConnectionError`; 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, a refused handshake with HTTP 403, 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, 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
 
-| Close code | Behaviour (defaults) |
+| Close code or handshake | Behaviour (defaults) |
 |---|---|
-| 1000, 1001 | Stop, unless `reconnect_on_normal_close=True` |
+| 1000, 1001 | Reconnect (Phoenix ≥ 1.8.8 sends 1001 for "reconnect expected"); stop with `reconnect_on_normal_close=False` |
 | 1008 | Stop with `PHXConnectionError` (`policy_violation_is_terminal=True`) |
+| Handshake refused with HTTP 403 | Stop with `PHXConnectionError`; other statuses (401, 5xx, …) retry with the backoff below |
 | 1012 | Reconnect after at least a random 1–5 s |
 | 1013 | Reconnect after at least a random 30–60 s |
 | Anything else, or no close frame | Reconnect with jittered backoff: 0.5 s × 2ⁿ, capped at 30 s, reset after 60 s of uptime |
@@ -365,7 +366,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
@@ -376,8 +377,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.3.0 → phoenix_channels_python_client-0.4.0}/README.md

@@ -279,18 +279,19 @@ Exceptions raised in callbacks are logged, not raised.
 
 ## Connection Lifecycle and Errors
 
-- `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`.
+- `async with` waits for the first connection. With `auto_reconnect=True` it keeps retrying, except after a refused handshake with HTTP 403, which raises `PHXConnectionError`; 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, a refused handshake with HTTP 403, 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, 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
 
-| Close code | Behaviour (defaults) |
+| Close code or handshake | Behaviour (defaults) |
 |---|---|
-| 1000, 1001 | Stop, unless `reconnect_on_normal_close=True` |
+| 1000, 1001 | Reconnect (Phoenix ≥ 1.8.8 sends 1001 for "reconnect expected"); stop with `reconnect_on_normal_close=False` |
 | 1008 | Stop with `PHXConnectionError` (`policy_violation_is_terminal=True`) |
+| Handshake refused with HTTP 403 | Stop with `PHXConnectionError`; other statuses (401, 5xx, …) retry with the backoff below |
 | 1012 | Reconnect after at least a random 1–5 s |
 | 1013 | Reconnect after at least a random 30–60 s |
 | Anything else, or no close frame | Reconnect with jittered backoff: 0.5 s × 2ⁿ, capped at 30 s, reset after 60 s of uptime |
@@ -334,7 +335,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
@@ -345,8 +346,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.3.0 → phoenix_channels_python_client-0.4.0}/phoenix_channels_python_client/__init__.py

@@ -19,7 +19,7 @@ from phoenix_channels_python_client.protocol_handler import (
 )
 from phoenix_channels_python_client.utils import setup_logging
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 __author__ = "Phoenix Channels Python Client"
 
 __all__ = [

phoenix_channels_python_client-0.4.0/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.3.0 → phoenix_channels_python_client-0.4.0}/phoenix_channels_python_client/client.py

@@ -5,13 +5,24 @@ import logging
 from collections import deque
 from collections.abc import Awaitable, Callable
 from types import TracebackType
-from typing import Self
+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
+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 (
     DEFAULT_PROTOCOL_VERSION,
@@ -36,39 +47,56 @@ 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):
@@ -92,7 +120,10 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
         on_topic_lost: TopicLostCallback | None = None,
         additional_headers: dict[str, str] | None = None,
     ) -> None:
-        self.logger = logger
+        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")
@@ -106,21 +137,18 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
         if callback_drain_timeout_s <= 0:
             raise ValueError("callback_drain_timeout_s must be > 0")
 
-        self._protocol_handler = PHXProtocolHandler(protocol_version)
+        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=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
@@ -152,6 +180,10 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
         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
@@ -202,18 +234,22 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
         if task is None:
             if self._is_fully_closed:
                 return
+            self._request_stop()
             task = self._shutdown_task = asyncio.create_task(self._shutdown(reason))
         # Every caller waits for the same shutdown, and one caller's
         # cancellation never aborts it.
         await asyncio.shield(task)
 
-    async def _shutdown(self, reason: str) -> None:
-        self.logger.info("Event loop shutting down! reason=%s", reason)
-
+    def _request_stop(self) -> None:
+        # Runs inside the shutdown() call, not in its task: a refusal or close landing
+        # before the task's first step must already see the stop.
         if self._state not in (ClientState.SHUTTING_DOWN, ClientState.CLOSED):
             self._transition_state(ClientState.SHUTTING_DOWN)
         self._shutdown_event.set()
 
+    async def _shutdown(self, reason: str) -> None:
+        self.logger.info("Event loop shutting down! reason=%s", reason)
+
         await self._unsubscribe_all()
         # Includes on_topic_lost callbacks still running for topics already gone.
         await cancel_and_wait(*self._lifecycle_tasks)

{phoenix_channels_python_client-0.3.0 → phoenix_channels_python_client-0.4.0}/phoenix_channels_python_client/client_types.py

@@ -40,7 +40,10 @@ class ReconnectPolicy(BaseModel):
     factor: PositiveFloat = 2.0
     max_delay_s: NonNegativeFloat = 30.0
     stable_reset_s: PositiveFloat = 60.0
-    reconnect_on_normal_close: bool = False
+    # Phoenix >= 1.8.8 closes deliberate disconnects with 1001 ("reconnect
+    # expected"), and Bandit answers a close the peer started with 1000, so
+    # neither code is a stop signal.
+    reconnect_on_normal_close: bool = True
     policy_violation_is_terminal: bool = True
     service_restart_min_delay_s: NonNegativeFloat = 1.0
     service_restart_max_delay_s: NonNegativeFloat = 5.0

phoenix_channels_python_client-0.4.0/phoenix_channels_python_client/diagnostics.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import json
+import logging
+import re
+from urllib.parse import parse_qsl, quote, quote_plus, urlsplit
+
+from websockets.protocol import State
+
+from phoenix_channels_python_client.authentication import (
+    API_KEY_PARAMETER,
+    TOKEN_PARAMETER,
+    AuthenticationHeader,
+)
+
+REDACTED = "[REDACTED]"
+PERCENT_ESCAPE = re.compile(r"%[0-9a-fA-F]{2}")
+
+
+AUTHENTICATION_NAMES = frozenset(
+    {
+        API_KEY_PARAMETER,
+        TOKEN_PARAMETER,
+        *AuthenticationHeader,
+        "x-token",
+        "authorization",
+        "cookie",
+    }
+)
+AUTHENTICATION_LABEL = re.compile(
+    r"(?i)((?:"
+    + "|".join(
+        re.escape(name) for name in sorted(AUTHENTICATION_NAMES, key=len, reverse=True)
+    )
+    + r")[\"\']?\s*[:=]\s*[\"\']?(?:(?:Bearer|Basic)\s+)?)([^\s&\"\']+)"
+)
+
+
+class ConnectionLogger(logging.Logger):
+    """Forward only sanitized records; raw transport objects never reach handlers."""
+
+    def __init__(self, target: logging.Logger, secrets: set[str]) -> None:
+        super().__init__(target.name)
+        self.target = target
+        self.parent = target
+        variants = sorted(
+            {
+                encoded
+                for secret in secrets
+                if secret
+                for encoded in (
+                    secret,
+                    quote(secret, safe=""),
+                    quote(secret),
+                    quote(secret, safe=";/?:@&=+$,#-_.!~*'()"),
+                    quote_plus(secret, safe=""),
+                    json.dumps(secret)[1:-1],
+                )
+            },
+            key=len,
+            reverse=True,
+        )
+
+        self.patterns = [
+            re.compile(
+                PERCENT_ESCAPE.sub(lambda match: f"(?i:{match[0]})", re.escape(secret))
+            )
+            for secret in variants
+        ]
+
+    def isEnabledFor(self, level: int) -> bool:  # noqa: N802 -- logging API
+        # Connection loggers are intentionally absent from the global registry,
+        # so its cache invalidation cannot track their effective level.
+        return (
+            not self.disabled
+            and not self.target.disabled
+            and self.manager.disable < level
+            and level >= self.getEffectiveLevel()
+        )
+
+    def redact(self, text: str) -> str:
+        for pattern in self.patterns:
+            text = pattern.sub(REDACTED, text)
+        return AUTHENTICATION_LABEL.sub(lambda match: match[1] + REDACTED, text)
+
+    def handle(self, record: logging.LogRecord) -> None:
+        if self.target.disabled:
+            return
+        message = str(record.msg)
+        if (
+            record.msg == "= connection is %s"
+            and isinstance(record.args, tuple)
+            and len(record.args) == 1
+            and isinstance(record.args[0], str)
+            and record.args[0] in State.__members__
+        ):
+            message = record.msg % record.args
+        if record.exc_info and record.exc_info[0]:
+            message += " [" + record.exc_info[0].__name__ + "]"
+        safe_record = logging.LogRecord(
+            record.name,
+            record.levelno,
+            record.pathname,
+            record.lineno,
+            self.redact(message),
+            (),
+            None,
+            record.funcName,
+        )
+        filtered = self.target.filter(safe_record)
+        if filtered:
+            if isinstance(filtered, logging.LogRecord):
+                safe_record = filtered
+            super().handle(safe_record)
+
+
+def diagnostic_secrets(url: str, api_key: str, headers: dict[str, str]) -> set[str]:
+    """Collect connection credentials without changing authentication bytes."""
+    return {
+        api_key,
+        *(
+            value
+            for name, value in parse_qsl(urlsplit(url).query)
+            if name.casefold() in AUTHENTICATION_NAMES
+        ),
+        *(
+            value
+            for name, value in headers.items()
+            if name.casefold() in AUTHENTICATION_NAMES
+        ),
+    }

{phoenix_channels_python_client-0.3.0 → phoenix_channels_python_client-0.4.0}/phoenix_channels_python_client/protocol_handler.py

@@ -9,6 +9,7 @@ from typing import Any, NamedTuple
 
 from websockets import ClientConnection
 
+from phoenix_channels_python_client.diagnostics import ConnectionLogger
 from phoenix_channels_python_client.phx_messages import (
     PHOENIX_TOPIC,
     ChannelMessage,
@@ -110,6 +111,8 @@ class PHXProtocolHandler:
         self,
         protocol_version: PhoenixChannelsProtocolVersion
         | str = DEFAULT_PROTOCOL_VERSION,
+        *,
+        diagnostic_logger: logging.Logger | None = None,
     ) -> None:
         # Non-v2 values select v1 for compatibility with the original client.
         self.protocol_version = (
@@ -117,7 +120,9 @@ class PHXProtocolHandler:
             if protocol_version == PhoenixChannelsProtocolVersion.V2
             else PhoenixChannelsProtocolVersion.V1
         )
-        self.logger = logger.getChild("ProtocolHandler")
+        self.logger = diagnostic_logger or ConnectionLogger(
+            logger.getChild("ProtocolHandler"), set()
+        )
         self.logger.debug(
             "Initialized PHXProtocolHandler for protocol version %s",
             self.protocol_version,