phoenix-channels-python-client 0.4.1__tar.gz → 0.4.2__tar.gz

{phoenix_channels_python_client-0.4.1/phoenix_channels_python_client.egg-info → phoenix_channels_python_client-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phoenix-channels-python-client
-Version: 0.4.1
+Version: 0.4.2
 Summary: A Python client library for connecting to Phoenix Channels
 Author: Phoenix Channels Python Client
 License-Expression: MIT
@@ -19,7 +19,7 @@ Requires-Dist: websockets>=14.2
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-asyncio>=1.4; extra == "dev"
-Requires-Dist: looptime<0.8,>=0.7; extra == "dev"
+Requires-Dist: looptime<0.10,>=0.7; 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"
@@ -28,7 +28,7 @@ Requires-Dist: ruff; extra == "dev"
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-asyncio>=1.4; extra == "test"
-Requires-Dist: looptime<0.8,>=0.7; extra == "test"
+Requires-Dist: looptime<0.10,>=0.7; extra == "test"
 Dynamic: license-file
 
 # Phoenix Channels Python Client
@@ -303,13 +303,14 @@ Everything after `api_key` is keyword-only:
 | `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 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_reconnect` | `None` | `async () -> None`, called after required first-attempt reconciliation |
 | `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.
+Exceptions raised in ordinary message and lifecycle callbacks are logged, not raised.
+Join-response installation failures instead fail the join (see below).
 
 ## Connection Lifecycle and Errors
 
@@ -419,3 +420,69 @@ 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.
+
+### Ordered join responses
+
+Use the optional keyword-only `on_join_response` hook to install a snapshot from
+initial joins, socket rejoins and same-socket channel recovery:
+
+```python
+state = None
+
+def install_snapshot(response):
+    global state
+    state = validate_snapshot(response)
+
+await client.subscribe_to_topic(
+    "room:123", on_message, on_join_response=install_snapshot
+)
+```
+
+`JoinResponseCallback` is exported from the package. The hook receives the decoded
+successful `payload.response`; a missing response is `None`. The transport adds no
+application schema or empty snapshot. Installation runs synchronously before
+`is_topic_joined()` becomes true, subscribe completes, or later deltas deliver.
+Subscribe returns `None`. Success admits the subscription; a later disconnect or
+channel failure can already have changed its current readiness when the caller
+resumes.
+
+Hooks must be short, nonblocking and return `None`. Do not await, perform I/O,
+wait on locks, defer installation, or change task/client lifecycle inside them.
+Async callables, awaitable results and other non-`None` results fail admission.
+The join timeout bounds reply waiting and cannot preempt synchronous code. Hook
+exceptions (including directly raised `CancelledError`) fail with `PHXTopicError`
+and preserve their cause; arbitrary prior hook effects are not rolled back.
+Initial failure belongs to the caller. An established subscription whose installer
+fails is removed and reported once through `on_topic_lost`.
+
+Initial cancellation, timeout and leave remove the exact subscription. Physical
+cleanup remains owned if its waiter is canceled again, and shutdown awaits it.
+Never-established subscriptions are not adopted by automatic recovery. Recorded
+queue loss before a hook-enabled installation fails the attempt transiently;
+steady-state queues still drop their oldest message at capacity. There is no
+replay guarantee. A fresh client must install a fresh snapshot after process loss.
+
+Join replies match request refs on both protocols. V2 also filters stale channel
+generations by `join_ref`. V1 cannot reliably fence unsolicited events/lifecycle
+frames from older channels; it does not provide V2 event-generation isolation.
+
+### Optional reconnect participation
+
+`subscribe_to_topic(topic, async_callback=None, *, on_join_response=None,
+blocks_reconnect=True) -> None` preserves required recovery by default. Required
+topics reconcile their first socket-rejoin attempt sequentially before
+`on_reconnect`; transient failures continue through existing recovery/backoff.
+The barrier does not wait for eventual success of every required topic.
+
+Set `blocks_reconnect=False` for optional subscriptions. After required first
+attempts, their existing per-topic recovery tasks perform an immediate join and
+retry transient failures with the existing backoff. Required event delivery and
+`on_reconnect` do not wait for optional replies, old callback drains or retries.
+This option cannot isolate synchronous code that blocks the event loop. Explicit
+initial subscribe always waits for its own join response and installation.
+
+`on_reconnect` conveys no optional readiness or registration-absence guarantee.
+Check `is_topic_joined()` for current readiness and use `on_topic_lost` to replace
+permanently rejected optional subscriptions; do not blindly resubscribe them
+from `on_reconnect`. Leave, shutdown and another socket disconnect cancel/await
+the owned recovery; obsolete generations cannot install or revive a replacement.

{phoenix_channels_python_client-0.4.1 → phoenix_channels_python_client-0.4.2}/README.md

@@ -270,13 +270,14 @@ Everything after `api_key` is keyword-only:
 | `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 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_reconnect` | `None` | `async () -> None`, called after required first-attempt reconciliation |
 | `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.
+Exceptions raised in ordinary message and lifecycle callbacks are logged, not raised.
+Join-response installation failures instead fail the join (see below).
 
 ## Connection Lifecycle and Errors
 
@@ -386,3 +387,69 @@ 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.
+
+### Ordered join responses
+
+Use the optional keyword-only `on_join_response` hook to install a snapshot from
+initial joins, socket rejoins and same-socket channel recovery:
+
+```python
+state = None
+
+def install_snapshot(response):
+    global state
+    state = validate_snapshot(response)
+
+await client.subscribe_to_topic(
+    "room:123", on_message, on_join_response=install_snapshot
+)
+```
+
+`JoinResponseCallback` is exported from the package. The hook receives the decoded
+successful `payload.response`; a missing response is `None`. The transport adds no
+application schema or empty snapshot. Installation runs synchronously before
+`is_topic_joined()` becomes true, subscribe completes, or later deltas deliver.
+Subscribe returns `None`. Success admits the subscription; a later disconnect or
+channel failure can already have changed its current readiness when the caller
+resumes.
+
+Hooks must be short, nonblocking and return `None`. Do not await, perform I/O,
+wait on locks, defer installation, or change task/client lifecycle inside them.
+Async callables, awaitable results and other non-`None` results fail admission.
+The join timeout bounds reply waiting and cannot preempt synchronous code. Hook
+exceptions (including directly raised `CancelledError`) fail with `PHXTopicError`
+and preserve their cause; arbitrary prior hook effects are not rolled back.
+Initial failure belongs to the caller. An established subscription whose installer
+fails is removed and reported once through `on_topic_lost`.
+
+Initial cancellation, timeout and leave remove the exact subscription. Physical
+cleanup remains owned if its waiter is canceled again, and shutdown awaits it.
+Never-established subscriptions are not adopted by automatic recovery. Recorded
+queue loss before a hook-enabled installation fails the attempt transiently;
+steady-state queues still drop their oldest message at capacity. There is no
+replay guarantee. A fresh client must install a fresh snapshot after process loss.
+
+Join replies match request refs on both protocols. V2 also filters stale channel
+generations by `join_ref`. V1 cannot reliably fence unsolicited events/lifecycle
+frames from older channels; it does not provide V2 event-generation isolation.
+
+### Optional reconnect participation
+
+`subscribe_to_topic(topic, async_callback=None, *, on_join_response=None,
+blocks_reconnect=True) -> None` preserves required recovery by default. Required
+topics reconcile their first socket-rejoin attempt sequentially before
+`on_reconnect`; transient failures continue through existing recovery/backoff.
+The barrier does not wait for eventual success of every required topic.
+
+Set `blocks_reconnect=False` for optional subscriptions. After required first
+attempts, their existing per-topic recovery tasks perform an immediate join and
+retry transient failures with the existing backoff. Required event delivery and
+`on_reconnect` do not wait for optional replies, old callback drains or retries.
+This option cannot isolate synchronous code that blocks the event loop. Explicit
+initial subscribe always waits for its own join response and installation.
+
+`on_reconnect` conveys no optional readiness or registration-absence guarantee.
+Check `is_topic_joined()` for current readiness and use `on_topic_lost` to replace
+permanently rejected optional subscriptions; do not blindly resubscribe them
+from `on_reconnect`. Leave, shutdown and another socket disconnect cancel/await
+the owned recovery; obsolete generations cannot install or revive a replacement.

{phoenix_channels_python_client-0.4.1 → phoenix_channels_python_client-0.4.2}/phoenix_channels_python_client/__init__.py

@@ -13,18 +13,20 @@ from phoenix_channels_python_client.client import (
     ReconnectPolicy,
     TopicLostCallback,
 )
+from phoenix_channels_python_client.client_types import JoinResponseCallback
 from phoenix_channels_python_client.protocol_handler import (
     PhoenixChannelsProtocolVersion,
     PHXProtocolHandler,
 )
 from phoenix_channels_python_client.utils import setup_logging
 
-__version__ = "0.4.1"
+__version__ = "0.4.2"
 __author__ = "Phoenix Channels Python Client"
 
 __all__ = [
     "DisconnectCallback",
     "HeartbeatAckCallback",
+    "JoinResponseCallback",
     "PHXChannelsClient",
     "PHXProtocolHandler",
     "PhoenixChannelsProtocolVersion",

{phoenix_channels_python_client-0.4.1 → phoenix_channels_python_client-0.4.2}/phoenix_channels_python_client/client.py

@@ -198,6 +198,7 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
         self._on_heartbeat_ack = on_heartbeat_ack
         self._on_topic_lost = on_topic_lost
         self._lifecycle_tasks: set[asyncio.Task[None]] = set()
+        self._cleanup_tasks: set[asyncio.Task[None]] = set()
         self._forced_close_pending = False
 
     def redact_diagnostic(self, text: str) -> str:
@@ -215,6 +216,7 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
             self._state == ClientState.CLOSED
             and not self._topic_subscriptions
             and self.connection is None
+            and not self._cleanup_tasks
         )
 
     async def __aenter__(self) -> Self:
@@ -273,6 +275,8 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
         await self._unsubscribe_all()
         # Includes on_topic_lost callbacks still running for topics already gone.
         await cancel_and_wait(*self._lifecycle_tasks)
+        if self._cleanup_tasks:
+            await asyncio.gather(*self._cleanup_tasks)
         await self._stop_supervisor()
         await self._cleanup_connection()
         self._connected_event.clear()

{phoenix_channels_python_client-0.4.1 → phoenix_channels_python_client-0.4.2}/phoenix_channels_python_client/client_types.py

@@ -1,8 +1,9 @@
 from __future__ import annotations
 
+from collections.abc import Callable
 from dataclasses import dataclass
 from enum import StrEnum
-from typing import Self
+from typing import Any, Self
 
 from pydantic import (
     BaseModel,
@@ -15,6 +16,8 @@ from pydantic import (
 
 from phoenix_channels_python_client.exceptions import PHXConnectionError
 
+JoinResponseCallback = Callable[[Any], None]
+
 
 class ClientState(StrEnum):
     CONNECTING = "connecting"