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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phoenix-channels-python-client
-Version: 0.2.4
+Version: 0.2.5
 Summary: A Python client library for connecting to Phoenix Channels
 Author: Phoenix Channels Python Client
 License-Expression: MIT
@@ -17,14 +17,14 @@ License-File: LICENSE
 Requires-Dist: websockets>=14.2
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
-Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.4; extra == "dev"
 Requires-Dist: pre-commit>=3.0.0; extra == "dev"
 Requires-Dist: commitizen>=3.13.0; extra == "dev"
 Requires-Dist: pyrefly; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
-Requires-Dist: pytest-asyncio; extra == "test"
+Requires-Dist: pytest-asyncio>=1.4; extra == "test"
 Dynamic: license-file
 
 # Phoenix Channels Python Client
@@ -39,7 +39,11 @@ A modern, async Python client library for connecting to [Phoenix Channels](https
 
 ### For Users
 
-Install from source:
+```bash
+pip install phoenix-channels-python-client
+```
+
+Or from source:
 
 ```bash
 git clone https://github.com/band-ai/phoenix-channels-python-client.git
@@ -65,7 +69,6 @@ pip install -e ".[dev]"
 Run tests:
 
 ```bash
-pip install -e ".[test]"
 pytest
 ```
 
@@ -96,26 +99,56 @@ async def main():
         # Subscribe to a topic
         await client.subscribe_to_topic("room:lobby", handle_message)
         
-        # Use built-in convenience method to keep connection alive
-        await client.run_forever()  # Handles Ctrl+C automatically
+        # Ctrl+C or SIGTERM shuts the client down and run_forever() returns.
+        # The previous handlers are restored first, so a second signal reaches them.
+        await client.run_forever()
 
 if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-## Phoenix System Events
+### Owning process signals yourself
+
+If your application owns its process signals (a service, desktop app or test
+runner), call `client.run_forever(install_signal_handlers=False)`. It then
+leaves signal handlers alone; stop the client by scheduling
+`client.shutdown(reason)` on the client's event loop, and `run_forever()`
+returns `None`:
+
+```python
+loop = asyncio.get_running_loop()
+async with asyncio.TaskGroup() as tasks:
+    loop.add_signal_handler(
+        signal.SIGTERM, lambda: tasks.create_task(client.shutdown("SIGTERM"))
+    )
+    try:
+        await client.run_forever(install_signal_handlers=False)
+    finally:
+        # Once the group exits, a later SIGTERM must not reach the closed group.
+        loop.remove_signal_handler(signal.SIGTERM)
+```
+
+From a plain `signal.signal` handler or another thread, use
+`loop.call_soon_threadsafe(...)` instead: a bare `asyncio.create_task` there
+doesn't wake a loop blocked on I/O, so the shutdown can stall until the next
+network activity. See [`examples/embedded_host_signals.py`](examples/embedded_host_signals.py).
 
-Phoenix Channels uses several reserved event names for internal protocol communication. The client library automatically handles these system events to manage connections, subscriptions, and message routing:
+With the default, handlers are installed only when `run_forever()` runs on the
+main thread; elsewhere it just waits. A handler you registered with
+`loop.add_signal_handler` before calling `run_forever()` still fires for the
+same signal; one registered while it runs replaces the client's.
 
-- `phx_join` - Channel join requests
-- `phx_reply` - Server replies to client messages  
-- `phx_leave` - Channel leave notifications
-- `phx_close` - Channel close events
-- `phx_error` - Channel error events
+## Phoenix System Events
 
-**Important:** You should avoid using these event names when handling custom events in your application, as they are reserved for Phoenix's internal protocol. The library uses these events to determine message routing and connection state management.
+Phoenix reserves `phx_join`, `phx_reply`, `phx_leave`, `phx_close` and
+`phx_error`. Don't use these names for your own events.
 
-If you have a specific use case that requires handling these system events directly, you can do so, but be aware that this may interfere with the library's automatic connection management.
+- 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.
 
 ## Protocol Versions
 
@@ -130,7 +163,7 @@ async with PHXChannelsClient(
     api_key="your-api-key"
     # protocol_version defaults to v2.0
 ) as client:
-    # Your code here
+    ...  # your code here
 ```
 
 ### Protocol v1.0
@@ -142,9 +175,11 @@ async with PHXChannelsClient(
     api_key="your-api-key",
     protocol_version=PhoenixChannelsProtocolVersion.V1
 ) as client:
-    # Your code here
+    ...  # your code here
 ```
 
+The client adds `vsn=2.0.0` (V2) or `vsn=1.0.0` (V1) to the socket URL.
+
 ## Usage Examples
 
 ### Basic Topic Subscription
@@ -186,7 +221,7 @@ The library provides two complementary ways to handle incoming messages:
 1. **Message handler runs first** (if set) - receives the full message
 2. **Event-specific handler runs second** (if matching event) - receives just the payload
 
-You can add, remove, or change either type of handler at any time during your connection.
+All handlers must be `async def`. You can add, remove, or change either type of handler at any time during your connection.
 
 ### Event-Specific Handlers
 
@@ -225,10 +260,13 @@ You can unsubscribe from topics to stop receiving messages and clean up resource
 import asyncio
 from phoenix_channels_python_client import PHXChannelsClient
 
+async def on_message(msg):
+    print(f"Message: {msg.payload}")
+
 async def main():
     async with PHXChannelsClient("ws://localhost:4000/socket/websocket", "api-key") as client:
         # Subscribe to a topic
-        await client.subscribe_to_topic("room:lobby", lambda msg: print(f"Message: {msg.payload}"))
+        await client.subscribe_to_topic("room:lobby", on_message)
         
         # Do some work...
         await asyncio.sleep(5)
@@ -245,13 +283,73 @@ asyncio.run(main())
 
 **Notes on unsubscription:**
 - Removes all handlers (both message and event-specific) for that topic
-- Sends a leave message to the Phoenix server
+- Sends `phx_leave` and waits for the reply (`leave_timeout_s`, default 5 s)
+- Raises `PHXTopicError` if the topic isn't subscribed or the leave times out, and `PHXConnectionError` while disconnected
+
+## Configuration
+
+Everything after `api_key` is keyword-only:
+
+| Option | Default | Meaning |
+|---|---|---|
+| `protocol_version` | `V2` | Phoenix Channels protocol version |
+| `auto_reconnect` | `True` | Reconnect and rejoin topics after a disconnect |
+| `reconnect_policy` | `ReconnectPolicy()` | Backoff and close-code handling (see below) |
+| `heartbeat_interval_s` | `30.0` | Heartbeat period; `None` disables heartbeats |
+| `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 |
+| `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 |
+| `additional_headers` | `None` | Extra handshake headers sent on every (re)connect |
+
+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`.
+- `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.
+- Exceptions live in `phoenix_channels_python_client.exceptions`.
+
+### Reconnects
+
+| Close code | Behaviour (defaults) |
+|---|---|
+| 1000, 1001 | Stop, unless `reconnect_on_normal_close=True` |
+| 1008 | Stop with `PHXConnectionError` (`policy_violation_is_terminal=True`) |
+| 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 |
+
+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`.
+
+### 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()`.
+
+## Logging
+
+```python
+import logging
+from phoenix_channels_python_client import setup_logging
+
+setup_logging(logging.DEBUG)  # loggers live under "phoenix_channels_python_client"
+```
+
+## Examples
+
+- [`examples/minimal_phx_events_client.py`](examples/minimal_phx_events_client.py): subscribe to a topic and log messages until Ctrl+C or SIGTERM.
+- [`examples/embedded_host_signals.py`](examples/embedded_host_signals.py): run the client in a host that owns its process signals.
 
 ---
 
 ## 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`). While the connection uses WSS (encrypted in transit), the API key may be logged by:
+**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:
 
 - Server access logs
 - Reverse proxies and load balancers
@@ -262,7 +360,7 @@ asyncio.run(main())
 - 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 Python client currently uses the older `params` style for broad compatibility.
+**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.
 
 ---
 

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

@@ -10,7 +10,11 @@ A modern, async Python client library for connecting to [Phoenix Channels](https
 
 ### For Users
 
-Install from source:
+```bash
+pip install phoenix-channels-python-client
+```
+
+Or from source:
 
 ```bash
 git clone https://github.com/band-ai/phoenix-channels-python-client.git
@@ -36,7 +40,6 @@ pip install -e ".[dev]"
 Run tests:
 
 ```bash
-pip install -e ".[test]"
 pytest
 ```
 
@@ -67,26 +70,56 @@ async def main():
         # Subscribe to a topic
         await client.subscribe_to_topic("room:lobby", handle_message)
         
-        # Use built-in convenience method to keep connection alive
-        await client.run_forever()  # Handles Ctrl+C automatically
+        # Ctrl+C or SIGTERM shuts the client down and run_forever() returns.
+        # The previous handlers are restored first, so a second signal reaches them.
+        await client.run_forever()
 
 if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-## Phoenix System Events
+### Owning process signals yourself
+
+If your application owns its process signals (a service, desktop app or test
+runner), call `client.run_forever(install_signal_handlers=False)`. It then
+leaves signal handlers alone; stop the client by scheduling
+`client.shutdown(reason)` on the client's event loop, and `run_forever()`
+returns `None`:
+
+```python
+loop = asyncio.get_running_loop()
+async with asyncio.TaskGroup() as tasks:
+    loop.add_signal_handler(
+        signal.SIGTERM, lambda: tasks.create_task(client.shutdown("SIGTERM"))
+    )
+    try:
+        await client.run_forever(install_signal_handlers=False)
+    finally:
+        # Once the group exits, a later SIGTERM must not reach the closed group.
+        loop.remove_signal_handler(signal.SIGTERM)
+```
+
+From a plain `signal.signal` handler or another thread, use
+`loop.call_soon_threadsafe(...)` instead: a bare `asyncio.create_task` there
+doesn't wake a loop blocked on I/O, so the shutdown can stall until the next
+network activity. See [`examples/embedded_host_signals.py`](examples/embedded_host_signals.py).
 
-Phoenix Channels uses several reserved event names for internal protocol communication. The client library automatically handles these system events to manage connections, subscriptions, and message routing:
+With the default, handlers are installed only when `run_forever()` runs on the
+main thread; elsewhere it just waits. A handler you registered with
+`loop.add_signal_handler` before calling `run_forever()` still fires for the
+same signal; one registered while it runs replaces the client's.
 
-- `phx_join` - Channel join requests
-- `phx_reply` - Server replies to client messages  
-- `phx_leave` - Channel leave notifications
-- `phx_close` - Channel close events
-- `phx_error` - Channel error events
+## Phoenix System Events
 
-**Important:** You should avoid using these event names when handling custom events in your application, as they are reserved for Phoenix's internal protocol. The library uses these events to determine message routing and connection state management.
+Phoenix reserves `phx_join`, `phx_reply`, `phx_leave`, `phx_close` and
+`phx_error`. Don't use these names for your own events.
 
-If you have a specific use case that requires handling these system events directly, you can do so, but be aware that this may interfere with the library's automatic connection management.
+- 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.
 
 ## Protocol Versions
 
@@ -101,7 +134,7 @@ async with PHXChannelsClient(
     api_key="your-api-key"
     # protocol_version defaults to v2.0
 ) as client:
-    # Your code here
+    ...  # your code here
 ```
 
 ### Protocol v1.0
@@ -113,9 +146,11 @@ async with PHXChannelsClient(
     api_key="your-api-key",
     protocol_version=PhoenixChannelsProtocolVersion.V1
 ) as client:
-    # Your code here
+    ...  # your code here
 ```
 
+The client adds `vsn=2.0.0` (V2) or `vsn=1.0.0` (V1) to the socket URL.
+
 ## Usage Examples
 
 ### Basic Topic Subscription
@@ -157,7 +192,7 @@ The library provides two complementary ways to handle incoming messages:
 1. **Message handler runs first** (if set) - receives the full message
 2. **Event-specific handler runs second** (if matching event) - receives just the payload
 
-You can add, remove, or change either type of handler at any time during your connection.
+All handlers must be `async def`. You can add, remove, or change either type of handler at any time during your connection.
 
 ### Event-Specific Handlers
 
@@ -196,10 +231,13 @@ You can unsubscribe from topics to stop receiving messages and clean up resource
 import asyncio
 from phoenix_channels_python_client import PHXChannelsClient
 
+async def on_message(msg):
+    print(f"Message: {msg.payload}")
+
 async def main():
     async with PHXChannelsClient("ws://localhost:4000/socket/websocket", "api-key") as client:
         # Subscribe to a topic
-        await client.subscribe_to_topic("room:lobby", lambda msg: print(f"Message: {msg.payload}"))
+        await client.subscribe_to_topic("room:lobby", on_message)
         
         # Do some work...
         await asyncio.sleep(5)
@@ -216,13 +254,73 @@ asyncio.run(main())
 
 **Notes on unsubscription:**
 - Removes all handlers (both message and event-specific) for that topic
-- Sends a leave message to the Phoenix server
+- Sends `phx_leave` and waits for the reply (`leave_timeout_s`, default 5 s)
+- Raises `PHXTopicError` if the topic isn't subscribed or the leave times out, and `PHXConnectionError` while disconnected
+
+## Configuration
+
+Everything after `api_key` is keyword-only:
+
+| Option | Default | Meaning |
+|---|---|---|
+| `protocol_version` | `V2` | Phoenix Channels protocol version |
+| `auto_reconnect` | `True` | Reconnect and rejoin topics after a disconnect |
+| `reconnect_policy` | `ReconnectPolicy()` | Backoff and close-code handling (see below) |
+| `heartbeat_interval_s` | `30.0` | Heartbeat period; `None` disables heartbeats |
+| `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 |
+| `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 |
+| `additional_headers` | `None` | Extra handshake headers sent on every (re)connect |
+
+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`.
+- `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.
+- Exceptions live in `phoenix_channels_python_client.exceptions`.
+
+### Reconnects
+
+| Close code | Behaviour (defaults) |
+|---|---|
+| 1000, 1001 | Stop, unless `reconnect_on_normal_close=True` |
+| 1008 | Stop with `PHXConnectionError` (`policy_violation_is_terminal=True`) |
+| 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 |
+
+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`.
+
+### 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()`.
+
+## Logging
+
+```python
+import logging
+from phoenix_channels_python_client import setup_logging
+
+setup_logging(logging.DEBUG)  # loggers live under "phoenix_channels_python_client"
+```
+
+## Examples
+
+- [`examples/minimal_phx_events_client.py`](examples/minimal_phx_events_client.py): subscribe to a topic and log messages until Ctrl+C or SIGTERM.
+- [`examples/embedded_host_signals.py`](examples/embedded_host_signals.py): run the client in a host that owns its process signals.
 
 ---
 
 ## 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`). While the connection uses WSS (encrypted in transit), the API key may be logged by:
+**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:
 
 - Server access logs
 - Reverse proxies and load balancers
@@ -233,7 +331,7 @@ asyncio.run(main())
 - 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 Python client currently uses the older `params` style for broad compatibility.
+**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.
 
 ---
 

{phoenix_channels_python_client-0.2.4 → phoenix_channels_python_client-0.2.5}/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.2.4"
+__version__ = "0.2.5"
 __author__ = "Phoenix Channels Python Client"
 
 __all__ = [

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

@@ -25,6 +25,7 @@ from phoenix_channels_python_client.reconnect_controller import ReconnectControl
 from phoenix_channels_python_client.supervisor import SupervisorMixin
 from phoenix_channels_python_client.topic_runtime import TopicRuntimeMixin
 from phoenix_channels_python_client.topic_subscription import TopicSubscription
+from phoenix_channels_python_client.utils import cancel_and_wait
 
 logger = logging.getLogger(__name__)
 
@@ -145,6 +146,7 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
         self._connected_event = asyncio.Event()
         self._conn_generation = 0
         self._supervisor_task: asyncio.Task[None] | None = None
+        self._shutdown_task: asyncio.Task[None] | None = None
         self._message_routing_task: asyncio.Task[None] | None = None
         self._initial_connection_future: asyncio.Future[None] | None = None
         self._rapid_disconnects: deque[float] = deque()
@@ -157,13 +159,26 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
         self._on_heartbeat_ack = on_heartbeat_ack
         self._forced_close_pending = False
 
+    @property
+    def _active_shutdown(self) -> asyncio.Task[None] | None:
+        task = self._shutdown_task
+        return task if task is not None and not task.done() else None
+
+    @property
+    def _is_fully_closed(self) -> bool:
+        return (
+            self._state == ClientState.CLOSED
+            and not self._topic_subscriptions
+            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:
         self.logger.debug("Entering PHXChannelsClient context")
-        if self._state != ClientState.CLOSED:
+        if self._state != ClientState.CLOSED or self._active_shutdown is not None:
             raise PHXConnectionError("Client is already running")
 
         self._shutdown_event.clear()
@@ -192,51 +207,52 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
         self.logger.debug("Leaving PHXChannelsClient context")
         await self.shutdown("Leaving PHXChannelsClient context")
 
-    async def shutdown(
-        self,
-        reason: str,
-    ) -> None:
-        if (
-            self._state == ClientState.CLOSED
-            and not self._topic_subscriptions
-            and self.connection is None
-        ):
-            return
-
+    async def shutdown(self, reason: str) -> None:
+        task = self._active_shutdown
+        if task is None:
+            if self._is_fully_closed:
+                return
+            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)
 
         if self._state not in (ClientState.SHUTTING_DOWN, ClientState.CLOSED):
             self._transition_state(ClientState.SHUTTING_DOWN)
-
         self._shutdown_event.set()
 
-        topics_to_unsubscribe = list(self._topic_subscriptions.keys())
-        if topics_to_unsubscribe:
-            unsubscribe_tasks = [
-                self.unsubscribe_from_topic(topic, _allow_disconnected=True)
-                for topic in topics_to_unsubscribe
-            ]
-            results = await asyncio.gather(*unsubscribe_tasks, return_exceptions=True)
-
-            for topic, result in zip(topics_to_unsubscribe, results, strict=False):
-                if isinstance(result, Exception):
-                    self.logger.warning(
-                        "Failed to unsubscribe from topic %s during shutdown: %s",
-                        topic,
-                        result,
-                    )
-
-        if self._supervisor_task and not self._supervisor_task.done():
-            self._supervisor_task.cancel()
-            try:
-                await self._supervisor_task
-            except asyncio.CancelledError:
-                self.logger.debug("Supervisor task cancelled during shutdown")
-
+        await self._unsubscribe_all()
+        await self._stop_supervisor()
         await self._cleanup_connection()
         self._connected_event.clear()
         self._transition_state(ClientState.CLOSED)
 
+    async def _unsubscribe_all(self) -> None:
+        topics = list(self._topic_subscriptions)
+        results = await asyncio.gather(
+            *(
+                self.unsubscribe_from_topic(topic, _allow_disconnected=True)
+                for topic in topics
+            ),
+            return_exceptions=True,
+        )
+        for topic, result in zip(topics, results, strict=True):
+            if isinstance(result, Exception):
+                self.logger.warning(
+                    "Failed to unsubscribe from topic %s during shutdown: %s",
+                    topic,
+                    result,
+                )
+
+    async def _stop_supervisor(self) -> None:
+        # Cleared, so run_forever() after the stop reports the client isn't running.
+        supervisor, self._supervisor_task = self._supervisor_task, None
+        if supervisor is not None and not supervisor.done():
+            await cancel_and_wait(supervisor)
+
     def _transition_state(self, new_state: ClientState) -> None:
         if self._state == new_state:
             return