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

{phoenix_channels_python_client-0.3.1/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.1
+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 |

{phoenix_channels_python_client-0.3.1 → 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 |

{phoenix_channels_python_client-0.3.1 → 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.1"
+__version__ = "0.4.0"
 __author__ = "Phoenix Channels Python Client"
 
 __all__ = [

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

@@ -234,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.1 → 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.3.1 → phoenix_channels_python_client-0.4.0}/phoenix_channels_python_client/reconnect_controller.py

@@ -4,9 +4,10 @@ import asyncio
 import logging
 import random
 from collections import deque
+from http import HTTPStatus
 
 from websockets import ClientConnection
-from websockets.exceptions import ConnectionClosed
+from websockets.exceptions import ConnectionClosed, InvalidStatus
 from websockets.frames import CloseCode
 
 from phoenix_channels_python_client.client_types import (
@@ -15,6 +16,20 @@ from phoenix_channels_python_client.client_types import (
 )
 from phoenix_channels_python_client.exceptions import PHXConnectionError
 
+# The Band platform answers every auth refusal with 403, and its websocket spec
+# (thenvoi-platform spec/websocket-api.draft.md) makes a rejected reconnect terminal.
+# A 401 could only come from an edge layer, so it and every other status retry.
+TERMINAL_HANDSHAKE_STATUS = HTTPStatus.FORBIDDEN
+
+
+def _terminal_decision(cause: str) -> ReconnectDecision:
+    return ReconnectDecision(
+        should_reconnect=False,
+        terminal_error=PHXConnectionError(
+            f"Reconnect disabled due to terminal {cause}"
+        ),
+    )
+
 
 class ReconnectControllerMixin:
     logger: logging.Logger
@@ -211,12 +226,8 @@ class ReconnectControllerMixin:
             and self.reconnect_policy.policy_violation_is_terminal
         ):
             reason = close_reason or "policy violation"
-            decision = ReconnectDecision(
-                should_reconnect=False,
-                terminal_error=PHXConnectionError(
-                    "Reconnect disabled due to terminal close code "
-                    f"{CloseCode.POLICY_VIOLATION} ({reason})"
-                ),
+            decision = _terminal_decision(
+                f"close code {CloseCode.POLICY_VIOLATION} ({reason})"
             )
             self.logger.debug(
                 "Disconnect classification result. close_code=%s close_reason=%s "
@@ -297,6 +308,17 @@ class ReconnectControllerMixin:
         )
         return decision
 
+    def _classify_connect_failure(self, error: Exception) -> ReconnectDecision:
+        if (
+            isinstance(error, InvalidStatus)
+            and error.response.status_code == TERMINAL_HANDSHAKE_STATUS
+        ):
+            return _terminal_decision(
+                f"handshake status {TERMINAL_HANDSHAKE_STATUS} "
+                f"({TERMINAL_HANDSHAKE_STATUS.phrase})"
+            )
+        return ReconnectDecision(should_reconnect=True)
+
     def _apply_disconnect_delay_override(
         self,
         computed_delay_s: float,

{phoenix_channels_python_client-0.3.1 → phoenix_channels_python_client-0.4.0}/phoenix_channels_python_client/supervisor.py

@@ -67,6 +67,7 @@ class _SupervisorRuntimeDeps(Protocol):
     def _classify_disconnect(
         self, close_code: int | None, close_reason: str
     ) -> ReconnectDecision: ...
+    def _classify_connect_failure(self, error: Exception) -> ReconnectDecision: ...
     def _apply_disconnect_delay_override(
         self, computed_delay_s: float, decision: ReconnectDecision
     ) -> float: ...
@@ -262,10 +263,19 @@ class SupervisorMixin:
             )
             self.logger.error("Connection failed and auto_reconnect=False: %s", exc)
             return False
+        # A requested stop outranks a refusal's terminal error.
+        if self._shutdown_event.is_set():
+            self.logger.debug(
+                "Ignoring a connect failure after shutdown began: %s", exc
+            )
+            return False
+        decision = self._deps._classify_connect_failure(exc)
+        if decision.terminal_error is not None:
+            self._record_terminal_error(decision.terminal_error)
+            return False
         if self._suppressed_after_disconnect(0.0):
             return False
-        if self._state != ClientState.SHUTTING_DOWN:
-            self._deps._transition_state(ClientState.RECONNECTING)
+        self._deps._transition_state(ClientState.RECONNECTING)
         return True
 
     def _adopt_connection(self, connection: ClientConnection) -> bool:
@@ -347,8 +357,7 @@ class SupervisorMixin:
         else:
             decision = self._deps._classify_disconnect(close.code, close.reason)
         if decision.terminal_error is not None:
-            self._terminal_error = decision.terminal_error
-            self.logger.error("%s", self._terminal_error)
+            self._record_terminal_error(decision.terminal_error)
             return None
 
         if not decision.should_reconnect:
@@ -364,13 +373,20 @@ class SupervisorMixin:
         self._deps._record_disconnect(connection_uptime_s=uptime_s)
         if not self._deps._should_suppress_reconnect():
             return False
-        self._terminal_error = PHXConnectionError(
-            "Reconnect suppressed after repeated rapid disconnects. "
-            "Likely duplicate connection or unstable endpoint."
+        self._record_terminal_error(
+            PHXConnectionError(
+                "Reconnect suppressed after repeated rapid disconnects. "
+                "Likely duplicate connection or unstable endpoint."
+            )
         )
-        self.logger.error("%s", self._terminal_error)
         return True
 
+    def _record_terminal_error(self, error: PHXConnectionError) -> None:
+        self._terminal_error = error
+        # Log records stay static: the cause reaches the caller as the raised error.
+        self.logger.error("Reconnect stopped by a terminal error")
+        self._settle_initial_connection(error)
+
     def _settle_initial_connection(self, error: Exception | None) -> None:
         """Resolve ``__aenter__``'s wait, unless it already ended or was cancelled."""
         future = self._initial_connection_future

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phoenix-channels-python-client
-Version: 0.3.1
+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 |

{phoenix_channels_python_client-0.3.1 → phoenix_channels_python_client-0.4.0}/pyproject.toml

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

{phoenix_channels_python_client-0.3.1 → phoenix_channels_python_client-0.4.0}/tests/test_connection.py

@@ -19,6 +19,7 @@ from tests.support import (
     EVENT,
     FAST_RECONNECT,
     STOP_REASON,
+    STOPS_ON_NORMAL_CLOSE,
     TOPIC,
     UNPARSEABLE_FRAME,
     deliver,
@@ -68,10 +69,12 @@ async def test_a_string_version_connects_and_receives_a_message(
     )
 
 
-async def test_run_forever_returns_when_the_server_closes_normally(
+async def test_run_forever_returns_on_a_normal_close_when_reconnecting_on_it_is_off(
     phoenix_server: FakePhoenixServer,
 ) -> None:
-    async with make_client(phoenix_server) as client:
+    async with make_client(
+        phoenix_server, reconnect_policy=STOPS_ON_NORMAL_CLOSE
+    ) as client:
         await client.subscribe_to_topic(TOPIC)
         run = asyncio.create_task(client.run_forever())
 

{phoenix_channels_python_client-0.3.1 → phoenix_channels_python_client-0.4.0}/tests/test_reconnect.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import asyncio
 from enum import StrEnum
+from http import HTTPStatus
 from typing import Any
 
 import pytest
@@ -14,6 +15,7 @@ from phoenix_channels_python_client.exceptions import PHXConnectionError, PHXTop
 from phoenix_channels_python_client.phx_messages import ChannelMessage, Event, PHXEvent
 from tests.fake_server import FakePhoenixServer
 from tests.support import (
+    API_KEY,
     ASYNC_TIMEOUT_S,
     EVENT,
     FAST_RECONNECT,
@@ -21,6 +23,8 @@ from tests.support import (
     LEAVE_TIMEOUT_S,
     OTHER_TOPIC,
     STOP_REASON,
+    STOPS_ON_NORMAL_CLOSE,
+    TERMINAL_REFUSAL,
     TOPIC,
     UNPARSEABLE_FRAME,
     BusyCallback,
@@ -28,7 +32,9 @@ from tests.support import (
     ReconnectCounter,
     deliver,
     derive_policy,
+    each_normal_close_code,
     each_protocol,
+    each_retried_refusal,
     expect_message,
     make_client,
     reconnect,
@@ -56,6 +62,9 @@ UNRECOGNISED_CLOSE_CODE = 4001
 # More than one, so a retry follows a failed retry.
 REFUSED_HANDSHAKES = 2
 
+TERMINAL_REFUSAL_ERROR = f"terminal handshake status {int(TERMINAL_REFUSAL)}"
+TERMINAL_STOP_LOG = "Reconnect stopped by a terminal error"
+
 
 class RejoinOutcome(StrEnum):
     REJOINED = "rejoined"
@@ -144,8 +153,11 @@ async def test_with_auto_reconnect_disabled_a_service_restart_disconnects(
         assert await wait_for_condition(lambda: client.connection is None)
 
 
+@each_retried_refusal
 async def test_consecutive_failed_connects_keep_retrying_until_the_server_accepts(
-    phoenix_server: FakePhoenixServer, received: asyncio.Queue[ChannelMessage]
+    phoenix_server: FakePhoenixServer,
+    received: asyncio.Queue[ChannelMessage],
+    refusal: HTTPStatus,
 ) -> None:
     reconnects = ReconnectCounter()
     client = make_client(
@@ -154,7 +166,7 @@ async def test_consecutive_failed_connects_keep_retrying_until_the_server_accept
     async with client:
         await client.subscribe_to_topic(TOPIC, received.put)
 
-        with phoenix_server.refusing(REFUSED_HANDSHAKES):
+        with phoenix_server.refusing(REFUSED_HANDSHAKES, refusal):
             await reconnect(phoenix_server, client)
 
         assert phoenix_server.refused_handshakes == REFUSED_HANDSHAKES
@@ -590,19 +602,113 @@ async def test_a_policy_violation_close_stops_reconnecting_with_a_terminal_error
 
 
 @each_protocol
-async def test_a_normal_close_does_not_reconnect_by_default(
+@each_normal_close_code
+async def test_a_normal_close_reconnects_by_default(
     phoenix_server: FakePhoenixServer,
+    received: asyncio.Queue[ChannelMessage],
+    close_code: CloseCode,
+) -> None:
+    async with make_client(phoenix_server, reconnect_policy=FAST_RECONNECT) as client:
+        await client.subscribe_to_topic(TOPIC, received.put)
+
+        await reconnect(phoenix_server, client, code=close_code)
+
+        await assert_delivers_after_rejoin(phoenix_server, client, TOPIC, received)
+
+
+@each_protocol
+@each_normal_close_code
+async def test_a_normal_close_stops_when_reconnecting_on_it_is_off(
+    phoenix_server: FakePhoenixServer, close_code: CloseCode
 ) -> None:
     phoenix_server.close_on_join_ids.add(phoenix_server.next_client_id)
-    phoenix_server.close_on_join_code = CloseCode.NORMAL_CLOSURE
+    phoenix_server.close_on_join_code = close_code
 
-    async with make_client(phoenix_server, reconnect_policy=FAST_RECONNECT) as client:
+    async with make_client(
+        phoenix_server, reconnect_policy=STOPS_ON_NORMAL_CLOSE
+    ) as client:
         await client.subscribe_to_topic(TOPIC)
         await asyncio.wait_for(client.run_forever(), ASYNC_TIMEOUT_S)
 
     assert phoenix_server.get_connection_attempts(FakePhoenixServer.SOCKET_PATH) == 1
 
 
+async def test_disabling_auto_reconnect_wins_over_a_normal_close(
+    phoenix_server: FakePhoenixServer,
+) -> None:
+    async with make_client(phoenix_server, reconnect_policy=FAST_RECONNECT) as client:
+        # What band-sdk's disable_reconnect does on a supersede: flip it once connected.
+        client.auto_reconnect = False
+
+        await phoenix_server.close_all_clients(code=CloseCode.GOING_AWAY)
+
+        await asyncio.wait_for(client.run_forever(), ASYNC_TIMEOUT_S)
+
+    assert phoenix_server.get_connection_attempts(FakePhoenixServer.SOCKET_PATH) == 1
+
+
+async def test_a_refused_handshake_after_a_close_is_terminal(
+    phoenix_server: FakePhoenixServer, caplog: pytest.LogCaptureFixture
+) -> None:
+    async with make_client(phoenix_server, reconnect_policy=FAST_RECONNECT) as client:
+        with phoenix_server.refusing(REFUSED_HANDSHAKES, TERMINAL_REFUSAL):
+            await phoenix_server.close_all_clients(code=CloseCode.GOING_AWAY)
+
+            with pytest.raises(
+                PHXConnectionError, match=TERMINAL_REFUSAL_ERROR
+            ) as stop:
+                await asyncio.wait_for(client.run_forever(), ASYNC_TIMEOUT_S)
+
+    assert phoenix_server.refused_handshakes == 1
+    assert API_KEY not in str(stop.value)
+    assert TERMINAL_STOP_LOG in caplog.text
+
+
+async def test_a_refused_handshake_on_entry_raises_instead_of_retrying(
+    phoenix_server: FakePhoenixServer,
+) -> None:
+    client = make_client(phoenix_server, reconnect_policy=FAST_RECONNECT)
+
+    with (
+        phoenix_server.refusing(REFUSED_HANDSHAKES, TERMINAL_REFUSAL),
+        pytest.raises(PHXConnectionError, match=TERMINAL_REFUSAL_ERROR) as stop,
+    ):
+        await asyncio.wait_for(client.__aenter__(), ASYNC_TIMEOUT_S)
+
+    assert phoenix_server.refused_handshakes == 1
+    assert API_KEY not in str(stop.value)
+
+
+async def test_refusals_on_entry_raise_the_suppression_error_not_a_generic_one(
+    phoenix_server: FakePhoenixServer,
+) -> None:
+    policy = derive_policy(
+        FAST_RECONNECT, rapid_suppress_disconnect_count=SUPPRESS_AFTER_DISCONNECTS
+    )
+    client = make_client(phoenix_server, reconnect_policy=policy)
+
+    with (
+        phoenix_server.refusing(2 * SUPPRESS_AFTER_DISCONNECTS),
+        pytest.raises(PHXConnectionError, match="Reconnect suppressed"),
+    ):
+        await asyncio.wait_for(client.__aenter__(), ASYNC_TIMEOUT_S)
+
+    assert phoenix_server.refused_handshakes == SUPPRESS_AFTER_DISCONNECTS
+
+
+@each_retried_refusal
+async def test_a_non_forbidden_refusal_on_entry_is_retried_until_accepted(
+    phoenix_server: FakePhoenixServer, refusal: HTTPStatus
+) -> None:
+    client = make_client(phoenix_server, reconnect_policy=FAST_RECONNECT)
+
+    with phoenix_server.refusing(REFUSED_HANDSHAKES, refusal):
+        async with client:
+            pass
+
+    assert phoenix_server.refused_handshakes == REFUSED_HANDSHAKES
+
+
 @each_protocol
 async def test_an_unrecognised_close_code_reconnects(
     phoenix_server: FakePhoenixServer, received: asyncio.Queue[ChannelMessage]

{phoenix_channels_python_client-0.3.1 → phoenix_channels_python_client-0.4.0}/tests/test_reconnect_policy_invariants.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 from collections import deque
 from collections.abc import Callable
+from http import HTTPStatus
 from itertools import pairwise
 from urllib.parse import parse_qs, urlsplit
 
@@ -11,7 +12,17 @@ from websockets.frames import CloseCode
 from phoenix_channels_python_client.client import PHXChannelsClient, ReconnectPolicy
 from phoenix_channels_python_client.exceptions import PHXConnectionError
 from tests.fake_server import FakePhoenixServer
-from tests.support import API_KEY, STOP_REASON, derive_policy, make_client
+from tests.support import (
+    API_KEY,
+    STOP_REASON,
+    STOPS_ON_NORMAL_CLOSE,
+    TERMINAL_REFUSAL,
+    derive_policy,
+    each_normal_close_code,
+    each_retried_refusal,
+    make_client,
+    refused,
+)
 
 # No jitter, and every pre-cooldown delay stays below the cooldown base.
 COOLDOWN_POLICY = ReconnectPolicy(
@@ -70,14 +81,32 @@ def test_the_logged_socket_url_masks_the_api_key() -> None:
     assert API_KEY not in client.channel_socket_url_redacted
 
 
+@each_normal_close_code
+def test_the_default_policy_reconnects_after_a_normal_close(
+    close_code: CloseCode,
+) -> None:
+    decision = _make_client()._classify_disconnect(close_code, STOP_REASON)
+
+    assert decision.should_reconnect is True
+    assert decision.terminal_error is None
+
+
+@each_normal_close_code
+def test_a_policy_not_reconnecting_on_a_normal_close_stops_without_an_error(
+    close_code: CloseCode,
+) -> None:
+    client = _make_client(STOPS_ON_NORMAL_CLOSE)
+
+    decision = client._classify_disconnect(close_code, STOP_REASON)
+
+    assert decision.should_reconnect is False
+    assert decision.terminal_error is None
+
+
 def test_close_codes_are_classified_by_the_policy() -> None:
     policy = ReconnectPolicy()
     client = _make_client(policy)
 
-    normal = client._classify_disconnect(CloseCode.NORMAL_CLOSURE, STOP_REASON)
-    assert normal.should_reconnect is False
-    assert normal.terminal_error is None
-
     violation = client._classify_disconnect(CloseCode.POLICY_VIOLATION, STOP_REASON)
     assert violation.should_reconnect is False
     assert isinstance(violation.terminal_error, PHXConnectionError)
@@ -93,6 +122,28 @@ def test_close_codes_are_classified_by_the_policy() -> None:
     assert busy.max_delay_s == policy.try_again_later_max_delay_s
 
 
+def test_a_forbidden_handshake_is_a_terminal_connect_failure() -> None:
+    decision = _make_client()._classify_connect_failure(refused(TERMINAL_REFUSAL))
+
+    assert decision.should_reconnect is False
+    assert isinstance(decision.terminal_error, PHXConnectionError)
+
+
+@each_retried_refusal
+def test_a_refusal_other_than_forbidden_is_retried(refusal: HTTPStatus) -> None:
+    decision = _make_client()._classify_connect_failure(refused(refusal))
+
+    assert decision.should_reconnect is True
+    assert decision.terminal_error is None
+
+
+def test_a_failed_tcp_connect_is_retried() -> None:
+    decision = _make_client()._classify_connect_failure(ConnectionRefusedError())
+
+    assert decision.should_reconnect is True
+    assert decision.terminal_error is None
+
+
 def test_the_rapid_cooldown_steps_from_its_base_up_to_its_cap() -> None:
     client = _make_client(COOLDOWN_POLICY)
     base = COOLDOWN_POLICY.rapid_cooldown_base_s

{phoenix_channels_python_client-0.3.1 → phoenix_channels_python_client-0.4.0}/tests/test_shutdown_races.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import asyncio
+from http import HTTPStatus
 from typing import Self
 
 import pytest
@@ -17,13 +18,18 @@ from tests.support import (
     FAST_RECONNECT,
     LEAVE_TIMEOUT_S,
     STOP_REASON,
+    STOPS_ON_NORMAL_CLOSE,
+    TERMINAL_REFUSAL,
     TOPIC,
     UNPARSEABLE_FRAME,
     ReconnectCounter,
     crash_with_rejoin_in_flight,
     deliver,
+    derive_policy,
+    each_refusal,
     make_client,
     reconnect,
+    refused,
     wait_for_condition,
     wait_forever,
 )
@@ -31,6 +37,13 @@ from tests.support import (
 # Long enough for a shutdown that isn't held to finish against the local server.
 SETTLE_S = 0.2
 
+# The backoff after a close, long enough that even its jitter's lower half
+# outlasts the test, so only a shutdown can end the wait.
+HELD_BACKOFF_S = 4 * ASYNC_TIMEOUT_S
+HELD_BACKOFF = derive_policy(
+    FAST_RECONNECT, base_delay_s=HELD_BACKOFF_S, max_delay_s=HELD_BACKOFF_S
+)
+
 
 class HeldCallback:
     """A topic callback that, once cancelled, holds its unwinding until released.
@@ -105,8 +118,9 @@ async def test_reconnect_landing_during_shutdown_is_closed(
         )
 
 
+@each_refusal
 async def test_a_connect_failure_during_shutdown_closes_cleanly(
-    phoenix_server: FakePhoenixServer,
+    phoenix_server: FakePhoenixServer, refusal: HTTPStatus
 ) -> None:
     client = make_client(phoenix_server, reconnect_policy=FAST_RECONNECT)
     async with client:
@@ -114,7 +128,7 @@ async def test_a_connect_failure_during_shutdown_closes_cleanly(
             run, stop = await shut_down_during_a_held_reconnect(
                 phoenix_server, client, held
             )
-            with phoenix_server.refusing(1):
+            with phoenix_server.refusing(1, refusal):
                 phoenix_server.handshake_gate.set()
                 # Inside the block: the shutdown would otherwise cancel the
                 # supervisor before the held reconnect fails.
@@ -124,6 +138,42 @@ async def test_a_connect_failure_during_shutdown_closes_cleanly(
         assert client._state is ClientState.CLOSED
 
 
+async def test_a_refusal_is_ignored_from_the_moment_shutdown_is_called(
+    phoenix_server: FakePhoenixServer,
+) -> None:
+    async with make_client(phoenix_server, reconnect_policy=FAST_RECONNECT) as client:
+        stop = asyncio.create_task(client.shutdown(STOP_REASON))
+        # shutdown() has run to its first await; the task it created has not started.
+        await asyncio.sleep(0)
+
+        assert client._state is ClientState.SHUTTING_DOWN
+        assert client._retry_after_connect_failure(refused(TERMINAL_REFUSAL)) is False
+        assert client._terminal_error is None
+
+        await asyncio.wait_for(stop, ASYNC_TIMEOUT_S)
+
+
+async def test_shutdown_during_the_reconnect_backoff_makes_no_new_connection(
+    phoenix_server: FakePhoenixServer,
+) -> None:
+    async with make_client(phoenix_server, reconnect_policy=HELD_BACKOFF) as client:
+        run = asyncio.create_task(client.run_forever(install_signal_handlers=False))
+        attempts = phoenix_server.get_connection_attempts(FakePhoenixServer.SOCKET_PATH)
+        await phoenix_server.close_all_clients(code=CloseCode.GOING_AWAY)
+        # The supervisor enters the backoff wait straight after this transition.
+        assert await wait_for_condition(
+            lambda: client._state is ClientState.RECONNECTING
+        )
+
+        await asyncio.wait_for(client.shutdown(STOP_REASON), ASYNC_TIMEOUT_S)
+
+        assert await asyncio.wait_for(run, ASYNC_TIMEOUT_S) is None
+        assert (
+            phoenix_server.get_connection_attempts(FakePhoenixServer.SOCKET_PATH)
+            == attempts
+        )
+
+
 async def test_shutdown_during_recovery_leaves_no_tasks(
     phoenix_server: FakePhoenixServer,
 ) -> None:
@@ -262,7 +312,8 @@ async def test_shutdown_from_a_topic_callback_cancels_the_callback(
 async def test_forced_close_racing_shutdown_does_not_leak_into_the_next_session(
     phoenix_server: FakePhoenixServer,
 ) -> None:
-    client = make_client(phoenix_server)
+    # A leaked forced-close flag would reconnect after the normal close below.
+    client = make_client(phoenix_server, reconnect_policy=STOPS_ON_NORMAL_CLOSE)
     async with client:
         await asyncio.wait_for(
             asyncio.gather(

{phoenix_channels_python_client-0.3.1 → phoenix_channels_python_client-0.4.0}/tests/test_supervisor_internals.py

@@ -6,7 +6,10 @@ import asyncio
 
 import pytest
 
-from phoenix_channels_python_client.client_types import ReconnectDecision
+from phoenix_channels_python_client.client_types import (
+    ClientState,
+    ReconnectDecision,
+)
 from phoenix_channels_python_client.exceptions import PHXConnectionError
 from phoenix_channels_python_client.phx_messages import (
     PHOENIX_TOPIC,
@@ -40,6 +43,26 @@ async def test_a_suppressed_reconnect_after_a_failed_connect_is_terminal() -> No
     await harness._supervisor_loop()
 
     assert isinstance(harness._terminal_error, PHXConnectionError)
+    assert harness._initial_connection_future is not None
+    assert harness._initial_connection_future.exception() is harness._terminal_error
+
+
+async def test_a_terminal_connect_failure_ends_the_loop_with_its_error() -> None:
+    terminal = PHXConnectionError("refused for good")
+    harness = SupervisorHarness(connect_failures=1)
+    harness.connect_failure_decision = ReconnectDecision(
+        should_reconnect=False, terminal_error=terminal
+    )
+    # Consulted first, it would replace the terminal error with its own.
+    harness.suppress_values = [True]
+
+    await harness._supervisor_loop()
+
+    assert harness.connect_attempts == 1
+    assert harness._terminal_error is terminal
+    assert harness._initial_connection_future is not None
+    assert harness._initial_connection_future.exception() is terminal
+    assert harness._state is ClientState.CLOSED
 
 
 async def test_the_initial_connect_retries_before_succeeding() -> None: