PyAgoraRTC 0.2.1__tar.gz → 0.2.2__tar.gz

{pyagorartc-0.2.1 → pyagorartc-0.2.2}/.github/workflows/release.yml

@@ -66,7 +66,9 @@ jobs:
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2
         with:
-          files: dist/*
+          files: 
+            dist/*.whl
+            dist/*.tar.gz
           generate_release_notes: true
           prerelease: ${{ steps.version.outputs.prerelease }}
         env:

{pyagorartc-0.2.1 → pyagorartc-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: PyAgoraRTC
-Version: 0.2.1
+Version: 0.2.2
 Summary: Async Python client for Agora RTC signalling: edge discovery, SDP/ORTC negotiation and the WebSocket gateway session
 Project-URL: Homepage, https://github.com/mikey0000/PyAgoraRTC
 Project-URL: Documentation, https://github.com/mikey0000/PyAgoraRTC/tree/main/docs

{pyagorartc-0.2.1 → pyagorartc-0.2.2}/docs/decisions.md

@@ -191,7 +191,7 @@ socket and tasks and fires `on_closed(JOIN_FAILED)` before raising (a socket
 that closes after the join result but before `join()` acts on it is a failed
 join, `GatewayConnectError`, not a silently dead joined session); the
 gateway's quit, a socket close, the deadline and (with D22) `p2p_lost` fire
-their reasons. `close()` is idempotent and safe after a failed join. A
+their reasons, including when they land while `join()` is in flight (D29). `close()` is idempotent and safe after a failed join. A
 candidate added after `join()` is ignored with a DEBUG line (Q4).
 
 ## D24. `parse_offer` restores what `sdp_transform` coerces (amends D3)
@@ -250,3 +250,21 @@ defaults to `True`, preserving the Mammotion rule; PetKit passes `False`,
 which counts the announced uid as present so `on_user_offline` still tears
 the subscription down. A held stream logs its uid at DEBUG. Q18 decides the
 eventual default.
+
+## D29. A quit or `p2p_lost` during `join()` fails the join with its own reason (amends D23)
+
+The gateway sends the older session's 2003 quit when a second join on the
+same uid lands, which can be right behind the older session's own join
+result: the reader dispatches both before `join()` resumes. The handlers
+used to act only on a joined session, so the quit was dropped and `join()`
+answered for a session the gateway had already quit (a frozen feed in HA).
+A quit, or `p2p_lost` with `end_on_p2p_lost`, that arrives before `join()`
+has marked the session joined is recorded; `join()` then raises
+`GatewayConnectError` and `on_closed` fires once with `GATEWAY_QUIT` /
+`P2P_LOST`, not `JOIN_FAILED`: the join succeeded at the gateway and the
+reason is what the host acts on. It is checked ahead of the socket-close
+race, since the gateway closes the socket after the quit. One that arrives
+before the result fails the join at once instead of waiting out the
+timeout. `GatewayConnectError`, not `JoinRejectedError`: the join result was
+a success, and `JoinRejectedError` carries a join-result code the gateway
+never sent; this is the same shape as the socket-close race.

{pyagorartc-0.2.1 → pyagorartc-0.2.2}/docs/protocol.md

@@ -659,6 +659,11 @@ Negative case from the same test:
 
 - **Mammotion uid sharing.** Every Mammotion stream token shares one viewer uid. A second camera joining the same
   uid while the first is established gets the first one quit with code 2003.
+- **Timing against the join result.** The fake gateway, and the HA log that prompted D29, deliver the older
+  session's quit right after its own join result, often in the same read. A client must treat a quit that arrives
+  before it has acted on its join result as ending that join, not drop it for "not joined yet". The timing is from
+  a real HA DEBUG log (quit at 11:52:58.467, answer built 8 ms later, no ending reported); the frames themselves
+  were not logged.
 - **How the SDK handles it** (`handleNotification`, SDK:31150-31198): it maps `code` through the table below.
   - Code 28 with `detail` is a recover notification.
   - Code 30 is `K_VOS_FALLBACK`, whose `detail` is `"FALLBACKCN"` or `"fallback_hls"`.

{pyagorartc-0.2.1 → pyagorartc-0.2.2}/pyagorartc/session/session.py

@@ -124,6 +124,7 @@ class AgoraSession:
         self._reader_stopped = False
         self._join_started = False
         self._joined = False
+        self._pending_end: CloseReason | None = None
         self._own_uid = creds.uid
         self._token = creds.token
         self._rtx = False
@@ -193,8 +194,9 @@ class AgoraSession:
             JoinTimeoutError: No join result within ``options.join_timeout_s``.
             SdpError: The offer or the gateway ORTC could not be translated.
 
-        On any failure the socket is closed, owned tasks are cancelled and ``on_closed(JOIN_FAILED)`` fires
-        before the exception propagates (D9, D23).
+        On any failure the socket is closed, owned tasks are cancelled and ``on_closed`` fires before the
+        exception propagates: ``JOIN_FAILED``, or ``GATEWAY_QUIT`` / ``P2P_LOST`` when the gateway ended the
+        session before ``join`` finished, which raises ``GatewayConnectError`` (D9, D23, D29).
 
         """
         if self._join_started or self._close_reason is not None:
@@ -203,7 +205,7 @@ class AgoraSession:
         try:
             return await self._join(offer_sdp, session_id)
         except BaseException:
-            await self._end(CloseReason.JOIN_FAILED)
+            await self._end(self._pending_end or CloseReason.JOIN_FAILED)
             raise
 
     async def renew_token(self, token: str | None = None) -> None:
@@ -274,6 +276,9 @@ class AgoraSession:
             self._join_waiter = None
             timer.cancel()
         join = parse_join_result(frame)
+        if self._pending_end is not None:
+            # Checked first: the gateway usually closes the socket right after the quit it announced.
+            raise GatewayConnectError(f"gateway ended the session during join ({self._pending_end.value})")
         if self._reader_stopped:
             # The result arrived, but the message loop stopped before this task resumed to act on it.
             raise GatewayConnectError("gateway socket closed before the join completed")
@@ -486,8 +491,7 @@ class AgoraSession:
             notification.code,
             notification.detail,
         )
-        if self._joined:
-            await self._end(CloseReason.GATEWAY_QUIT)
+        await self._end_by_gateway(CloseReason.GATEWAY_QUIT)
 
     async def _on_p2p_lost(self, frame: GatewayFrame) -> None:
         lost = parse_p2p_lost(frame)
@@ -496,8 +500,16 @@ class AgoraSession:
             _LOGGER.debug("Gateway reported p2p_lost (code %s, %s); ignored", lost.code, lost.error)
             return
         _LOGGER.warning("Gateway reported p2p_lost (code %s, %s); ending the session", lost.code, lost.error)
+        await self._end_by_gateway(CloseReason.P2P_LOST)
+
+    async def _end_by_gateway(self, reason: CloseReason) -> None:
+        """End a joined session; while ``join`` is in flight, leave the ending for ``join`` to apply (D29)."""
         if self._joined:
-            await self._end(CloseReason.P2P_LOST)
+            await self._end(reason)
+            return
+        self._pending_end = self._pending_end or reason
+        if (waiter := self._join_waiter) is not None and not waiter.done():
+            waiter.set_exception(GatewayConnectError(f"gateway ended the session during join ({reason.value})"))
 
     async def _on_p2p_ok(self, frame: GatewayFrame) -> None:
         ok = parse_p2p_ok(frame.message)

{pyagorartc-0.2.1 → pyagorartc-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "PyAgoraRTC"
-version = "0.2.1"
+version = "0.2.2"
 description = "Async Python client for Agora RTC signalling: edge discovery, SDP/ORTC negotiation and the WebSocket gateway session"
 readme = "README.md"
 license = "GPL-3.0-or-later"

{pyagorartc-0.2.1 → pyagorartc-0.2.2}/tests/integration/test_session_join.py

@@ -8,7 +8,7 @@ from typing import TYPE_CHECKING
 import pytest
 
 from pyagorartc.const import EDGE_DOMAIN_SUFFIX
-from pyagorartc.exceptions import JoinRejectedError, JoinTimeoutError
+from pyagorartc.exceptions import GatewayConnectError, JoinRejectedError, JoinTimeoutError
 from pyagorartc.models import CloseReason, SessionOptions
 from pyagorartc.sdp import extract_inline_candidates
 from tests._helpers import RTC_TOKEN
@@ -165,3 +165,24 @@ class TestJoinFailure:
         with pytest.raises(JoinTimeoutError):
             await asyncio.wait_for(join, SESSION_TIMEOUT_S)
         assert r.closed.calls == [CloseReason.JOIN_FAILED]
+
+    @pytest.mark.regression
+    async def test_a_repeat_join_landing_with_the_first_result_fails_the_first_join_as_a_gateway_quit(
+        self, fake_agora: FakeAgora, new_session: Callable[..., SessionRig]
+    ) -> None:
+        """The 2003 quit reaching the first session with its join result was dropped; its ``join`` then answered."""
+        fake_agora.control(join_delay_s=5.0)
+        first, second = new_session(), new_session()
+        first_join = asyncio.ensure_future(first.session.join(CHROME_OFFER, SESSION_ID))
+        second_join = asyncio.ensure_future(second.session.join(CHROME_OFFER, SESSION_ID))
+        # Each session's join timer and the fake's two held join results.
+        await first.sleepers(4)
+
+        # Both held results fall due together: the first socket gets its result, then the second join's 2003.
+        await first.advance(5.0)
+
+        with pytest.raises(GatewayConnectError):
+            await asyncio.wait_for(first_join, SESSION_TIMEOUT_S)
+        await asyncio.wait_for(second_join, SESSION_TIMEOUT_S)
+        assert first.closed.calls == [CloseReason.GATEWAY_QUIT]
+        assert (second.closed.calls, second.session.is_joined) == ([], True)

pyagorartc-0.2.2/tests/unit/session/test_session_join_race.py

@@ -0,0 +1,95 @@
+"""An ending the gateway announces between the join result and ``join`` resuming (D23, D29)."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+
+import pytest
+
+from pyagorartc.exceptions import GatewayConnectError
+from pyagorartc.models import CloseReason, SessionOptions
+from tests._helpers import load_json_fixture
+from tests.unit.session._helpers import OFFER, SESSION_ID, TIMEOUT, all_done, rig
+
+if TYPE_CHECKING:
+    from tests.unit.session._helpers import Rig
+
+
+async def join_then(r: Rig, fixture: str) -> asyncio.Task[str]:
+    """Start ``join`` and feed the result and ``fixture`` together, so the reader dispatches both before it resumes."""
+    task = asyncio.ensure_future(r.session.join(OFFER, SESSION_ID))
+    await r.sent(1)
+    r.conn.feed({**load_json_fixture("gateway/join_ok.json"), "_id": r.conn.sent[0]["_id"]})
+    r.conn.feed(load_json_fixture(fixture))
+    return task
+
+
+class TestEndingDuringJoin:
+    @pytest.mark.regression
+    async def test_a_quit_right_after_the_result_fails_the_join_as_a_gateway_quit(self) -> None:
+        """A 2003 quit dispatched before ``join`` resumed was dropped, so ``join`` answered for a quit session."""
+        r = rig()
+        task = await join_then(r, "gateway/on_notification_quit.json")
+
+        with pytest.raises(GatewayConnectError, match="quit"):
+            await asyncio.wait_for(task, TIMEOUT)
+        assert r.closed.calls == [CloseReason.GATEWAY_QUIT]
+        assert not r.session.is_joined
+        assert all_done(r.spawned)
+        assert r.conn.sent_of_type("leave") == []
+
+    async def test_a_quit_then_a_socket_close_during_join_reports_the_quit(self) -> None:
+        """The gateway closes the socket after quitting; the quit, not the close, is why the join failed."""
+        r = rig()
+        task = await join_then(r, "gateway/on_notification_quit.json")
+        await r.conn.close()
+
+        with pytest.raises(GatewayConnectError, match="quit"):
+            await asyncio.wait_for(task, TIMEOUT)
+        assert r.closed.calls == [CloseReason.GATEWAY_QUIT]
+
+    async def test_a_quit_during_join_is_reported_once_after_close(self) -> None:
+        r = rig()
+        task = await join_then(r, "gateway/on_notification_quit.json")
+        with pytest.raises(GatewayConnectError):
+            await asyncio.wait_for(task, TIMEOUT)
+
+        await r.session.close()
+
+        assert r.closed.calls == [CloseReason.GATEWAY_QUIT]
+
+    @pytest.mark.regression
+    async def test_p2p_lost_right_after_the_result_fails_the_join_when_asked(self) -> None:
+        """With ``end_on_p2p_lost``, a p2p_lost dispatched before ``join`` resumed was dropped and the join succeeded."""
+        r = rig(SessionOptions(end_on_p2p_lost=True))
+        task = await join_then(r, "gateway/on_p2p_lost.json")
+
+        with pytest.raises(GatewayConnectError):
+            await asyncio.wait_for(task, TIMEOUT)
+        assert r.closed.calls == [CloseReason.P2P_LOST]
+        assert not r.session.is_joined
+        assert all_done(r.spawned)
+        assert r.conn.sent_of_type("leave") == []
+
+    async def test_p2p_lost_right_after_the_result_is_ignored_by_default(self) -> None:
+        r = rig()
+        task = await join_then(r, "gateway/on_p2p_lost.json")
+
+        answer = await asyncio.wait_for(task, TIMEOUT)
+
+        assert "a=setup:" in answer
+        assert (r.closed.calls, r.session.is_joined) == ([], True)
+
+    async def test_a_quit_before_the_result_fails_the_join_without_waiting_for_the_timeout(self) -> None:
+        """The quit fails the pending join at once rather than leaving it to ``join_timeout_s``."""
+        r = rig()
+        task = asyncio.ensure_future(r.session.join(OFFER, SESSION_ID))
+        await r.sent(1)
+
+        r.conn.feed(load_json_fixture("gateway/on_notification_quit.json"))
+
+        with pytest.raises(GatewayConnectError, match="quit"):
+            await asyncio.wait_for(task, TIMEOUT)
+        assert r.closed.calls == [CloseReason.GATEWAY_QUIT]
+        assert all_done(r.spawned)

{pyagorartc-0.2.1 → pyagorartc-0.2.2}/uv.lock

@@ -524,7 +524,7 @@ wheels = [
 
 [[package]]
 name = "pyagorartc"
-version = "0.2.1"
+version = "0.2.2"
 source = { editable = "." }
 dependencies = [
     { name = "aiohttp" },