caprid-relay 0.1.0__py3-none-any.whl

caprid_relay/__init__.py

@@ -0,0 +1,133 @@
+"""Relay Python SDK.
+
+Owns the Relay product API and authentication convention, built on ``moq_core``. The default
+transport is native QUIC through aioquic (``caprid_relay.quic``), which reaches a relay natively with no
+browser; ``create_transport`` swaps in another implementation of the same seam.
+
+The public names are the rows of ``spec/vocabulary.md``, pinned by ``tests/test_exports.py``. From
+the core this package re-exports exactly what ``@caprid/relay`` re-exports, plus ``Closed``; every
+other protocol type (location filters, fetch, track status, the constants) is imported from
+``moq_core``, a declared dependency.
+"""
+
+from moq_core import (
+    Closed,
+    Goaway,
+    KeyValuePair,
+    LocationFilter,
+    MessageParameters,
+    MoqtObject,
+    MoqTrackSource,
+    MoqtTransport,
+    PublishDone,
+    RequestError,
+    SubscribeOk,
+    Subscription,
+    SubscriptionHandlers,
+)
+
+from ._awaitable import RelayAwaitable
+from ._subscription import RelaySubscription, SubscriptionEnd, SubscriptionEndKind
+from ._supervision import SupervisedStatus, SupervisionBackoff
+from .cancellation import CancellationToken, Cancelled
+from .connect import RelaySubscriber, RelaySubscriptionHandlers, connect_relay_subscriber
+from .connect_session import ConnectingTransport, RelayCredential, RelayTransportFactory
+from .errors import RelayError, RelayErrorCode, RelayErrorPhase
+from .namespace_events import NamespaceEvent, NamespaceEvents
+from .payload import read_json, read_text
+from .publish import RelayGroupWriter, RelayPublisher, RelayTrackWriter, connect_relay_publisher
+from .room_endpoint import room_endpoint
+from .subscription_events import (
+    GoawayEvent,
+    ObjectEvent,
+    PublisherDoneEvent,
+    StateNotifyEvent,
+    SubgroupEndEvent,
+    SubgroupResetEvent,
+    SubscribedEvent,
+    SubscriptionConnectionClosedError,
+    SubscriptionEvent,
+    SubscriptionEvents,
+    SubscriptionOverflowError,
+    SubscriptionRequestError,
+    UpdateOkEvent,
+)
+from .supervised_publisher import PublisherGeneration, SupervisedPublisher, connect_supervised_publisher
+from .supervised_subscriber import (
+    RestartReason,
+    SupervisedSubscriber,
+    WantHandlers,
+    WantSwitchedInfo,
+    connect_supervised_subscriber,
+)
+from .switchable import SwitchableHandlers, SwitchableSubscription, SwitchedInfo
+
+DEFAULT_ENDPOINT = "https://relay.mux.global"
+"""The default Relay endpoint pinned in ``spec/protocol.json``."""
+
+__all__ = [
+    "DEFAULT_ENDPOINT",
+    "CancellationToken",
+    "Cancelled",
+    "Closed",
+    "ConnectingTransport",
+    "Goaway",
+    "GoawayEvent",
+    "KeyValuePair",
+    "LocationFilter",
+    "MessageParameters",
+    "MoqTrackSource",
+    "MoqtObject",
+    "MoqtTransport",
+    "NamespaceEvent",
+    "NamespaceEvents",
+    "ObjectEvent",
+    "PublishDone",
+    "PublisherDoneEvent",
+    "PublisherGeneration",
+    "RelayAwaitable",
+    "RelayCredential",
+    "RelayError",
+    "RelayErrorCode",
+    "RelayErrorPhase",
+    "RelayGroupWriter",
+    "RelayPublisher",
+    "RelaySubscriber",
+    "RelaySubscription",
+    "RelaySubscriptionHandlers",
+    "RelayTrackWriter",
+    "RelayTransportFactory",
+    "RequestError",
+    "RestartReason",
+    "StateNotifyEvent",
+    "SubgroupEndEvent",
+    "SubgroupResetEvent",
+    "SubscribeOk",
+    "SubscribedEvent",
+    "Subscription",
+    "SubscriptionConnectionClosedError",
+    "SubscriptionEnd",
+    "SubscriptionEndKind",
+    "SubscriptionEvent",
+    "SubscriptionEvents",
+    "SubscriptionHandlers",
+    "SubscriptionOverflowError",
+    "SubscriptionRequestError",
+    "SupervisedPublisher",
+    "SupervisedStatus",
+    "SupervisedSubscriber",
+    "SupervisionBackoff",
+    "SwitchableHandlers",
+    "SwitchableSubscription",
+    "SwitchedInfo",
+    "UpdateOkEvent",
+    "WantHandlers",
+    "WantSwitchedInfo",
+    "connect_relay_publisher",
+    "connect_relay_subscriber",
+    "connect_supervised_publisher",
+    "connect_supervised_subscriber",
+    "read_json",
+    "read_text",
+    "room_endpoint",
+]

caprid_relay/_awaitable.py

@@ -0,0 +1,59 @@
+"""The type of every fact the SDK settles once and lets any number of tasks await."""
+
+from __future__ import annotations
+
+import asyncio
+import contextvars
+from collections.abc import Callable, Generator
+from typing import Any, Generic, TypeVar
+
+_T = TypeVar("_T")
+
+
+class RelayAwaitable(Generic[_T]):
+    """A fact the SDK settles once: a subscription's ``subscribed`` or ``ended``, a publisher's
+    ``announced``, or a connection's ``closed``.
+
+    Await it as often as needed. Each waiter is isolated: a task cancelled while awaiting, or an
+    ``asyncio.wait_for`` that times out, never touches the underlying result, where handing out the
+    future itself would let one impatient waiter destroy the signal for every later one. ``done()``,
+    ``result()``, ``exception()`` and ``add_done_callback()`` read the result directly and allocate
+    nothing, so polling is free. It is not an :class:`asyncio.Future`: it cannot be cancelled or
+    set. Wrap it with :func:`asyncio.ensure_future` for an API that needs a future.
+    """
+
+    __slots__ = ("_future",)
+
+    def __init__(self, future: asyncio.Future[_T]) -> None:
+        self._future = future
+
+    def __await__(self) -> Generator[Any, None, _T]:
+        future = self._future
+        if not future.done():
+            future = asyncio.shield(future)
+        return future.__await__()
+
+    def done(self) -> bool:
+        """Whether the result is in."""
+        return self._future.done()
+
+    def result(self) -> _T:
+        """The result; raises what awaiting would, or ``asyncio.InvalidStateError`` while pending."""
+        return self._future.result()
+
+    def exception(self) -> BaseException | None:
+        """The exception awaiting would raise, ``None`` for a plain result."""
+        return self._future.exception()
+
+    def add_done_callback(
+        self, callback: Callable[[asyncio.Future[_T]], object], *, context: contextvars.Context | None = None
+    ) -> None:
+        """Call ``callback`` with the settled future once the result is in."""
+        self._future.add_done_callback(callback, context=context)
+
+    def remove_done_callback(self, callback: Callable[[asyncio.Future[_T]], object]) -> int:
+        """Forget a callback; returns how many registrations were removed."""
+        return self._future.remove_done_callback(callback)
+
+
+__all__ = ["RelayAwaitable"]

caprid_relay/_bounded_events.py

@@ -0,0 +1,166 @@
+"""The bounded events iterator both events forms share: one owned request, a queue bound and a
+cancellation token. ``subscription_events.py`` and ``namespace_events.py`` each supply the request
+and the events; this module owns the queue, the single pending read and the ending.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections import deque
+from collections.abc import Callable
+from types import TracebackType
+from typing import Generic, Protocol, Self, TypeVar
+
+from ._subscription import SubscriptionOverflowError
+from .cancellation import CancellationToken
+
+E = TypeVar("E")
+
+
+class OwnedRequest(Protocol):
+    """The request an iterator owns: all it needs is the cancel."""
+
+    def cancel(self, reason: object = None) -> None:
+        """Tear the request down; its echo through the sink is ignored."""
+
+
+class BoundedEventSink(Generic[E]):
+    """Where a producer delivers into a bounded iterator."""
+
+    __slots__ = ("_events",)
+
+    def __init__(self, events: BoundedEvents[E]) -> None:
+        self._events = events
+
+    def event(self, event: E) -> None:
+        """One event; past the capacity the iterator ends with ``SubscriptionOverflowError``."""
+        self._events._push(event)
+
+    def ended(self, error: BaseException | None = None) -> None:
+        """The producer ended: ``None`` finishes the iterator cleanly, anything else is raised from reads.
+
+        Either way the queue is discarded.
+        """
+        # An ending the iterator started (close, cancellation, overflow) echoes back here.
+        self._events._finish(error)
+
+    def complete(self) -> None:
+        """The producer finished cleanly: queued events are still read, then the iterator is done."""
+        self._events._finish(None, keep_queue=True)
+
+
+class BoundedEvents(Generic[E]):
+    """Single-consumer iterator over one owned request. Use ``async with`` for deterministic cleanup.
+
+    At most ``capacity`` events are retained. Overflow discards the queue, cancels only this request
+    and raises on reads. No transport backpressure is implied. Explicit close produces EOF; failures
+    raise.
+    """
+
+    def __init__(
+        self,
+        start: Callable[[BoundedEventSink[E]], OwnedRequest],
+        *,
+        capacity: int = 64,
+        cancellation: CancellationToken | None = None,
+    ) -> None:
+        if isinstance(capacity, bool) or not isinstance(capacity, int | float):
+            raise TypeError("capacity must be a number")
+        if not isinstance(capacity, int) or capacity <= 0:
+            raise ValueError("capacity must be a positive integer")
+        self._capacity = capacity
+        self._queue: deque[E] = deque()
+        # A one-element tuple, so an event that is itself ``None`` stays distinguishable from a wake.
+        self._pending: asyncio.Future[tuple[E] | None] | None = None
+        self._ended = False
+        self._failure: BaseException | None = None
+        self._request: OwnedRequest | None = None
+        self._cancellation = cancellation
+        if cancellation is not None and cancellation.cancelled:
+            self._finish(cancellation.reason)
+            return
+        if cancellation is not None:
+            cancellation.add_callback(self._finish)
+        try:
+            self._request = start(BoundedEventSink(self))
+        except BaseException:
+            self.close()
+            raise
+        # Events can overflow the queue before start() returns. The ending recorded then had no
+        # request to cancel, so cancel it now; the echo of that cancel is ignored.
+        if self._ended:
+            self._request.cancel(self._failure)
+
+    def _push(self, event: E) -> None:
+        if self._ended:
+            return
+        if self._pending is not None and not self._pending.done():
+            self._pending.set_result((event,))
+            return
+        if len(self._queue) == self._capacity:
+            self._finish(SubscriptionOverflowError("Subscription event buffer overflow"))
+            return
+        self._queue.append(event)
+
+    def _finish(self, error: BaseException | None = None, *, keep_queue: bool = False) -> None:
+        if self._ended:
+            return
+        self._ended = True
+        self._failure = error
+        # A pending read only exists while the queue is empty, so keeping it still settles that read as done.
+        if not keep_queue:
+            self._queue.clear()
+        if self._cancellation is not None:
+            self._cancellation.remove_callback(self._finish)
+        if self._request is not None:
+            self._request.cancel(error)
+        # Wake by value, not exception: abandoned reads cannot leak an unretrieved exception.
+        if self._pending is not None and not self._pending.done():
+            self._pending.set_result(None)
+
+    def __aiter__(self) -> Self:
+        return self
+
+    async def __anext__(self) -> E:
+        if self._pending is not None:
+            raise RuntimeError("Only one pending subscription read is supported")
+        try:
+            if not self._ended and not self._queue:
+                self._pending = asyncio.get_running_loop().create_future()
+                handed = await self._pending
+                # A handoff already completed before teardown belongs to the consumer, like TS.
+                if handed is not None:
+                    return handed[0]
+            # Events left by a clean completion are read before the end.
+            if self._queue:
+                return self._queue.popleft()
+            if self._ended:
+                if self._failure is not None:
+                    raise self._failure
+                raise StopAsyncIteration
+            raise RuntimeError("unreachable: an empty queue on a live iterator is awaited")
+        except asyncio.CancelledError:
+            self.close()
+            raise
+        finally:
+            self._pending = None
+
+    def close(self) -> None:
+        """Discard queued events and settle pending reads as EOF. Idempotent."""
+        self._finish()
+        self._queue.clear()
+
+    async def aclose(self) -> None:
+        """:meth:`close` as a coroutine, for ``contextlib.aclosing`` and other async-iterator cleanup."""
+        self.close()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None
+    ) -> None:
+        self.close()
+
+
+__all__ = ["BoundedEventSink", "BoundedEvents", "OwnedRequest"]

caprid_relay/_frame_reader.py

@@ -0,0 +1,179 @@
+"""The frame reader: a subscription's or a want's handlers that read its track as frames in decode order.
+
+It drives a sequencer it is given (``moq_media.FrameSequencer`` qualifies), which owns the ordering, the deadlines
+and the LOC format, so this package stays free of the format package. See the "Media subscribing" section of
+``spec/behavior.md``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable, Sequence
+from typing import Generic, Protocol, TypeVar
+
+from moq_core import KeyValuePair, MoqtObject, PublishDone, RequestError, SubgroupEnd, SubgroupReset, SubscribeOk
+
+from .connect import RelaySubscriptionHandlers
+from .supervised_subscriber import RestartReason, WantHandlers, WantSwitchedInfo
+
+F = TypeVar("F")
+F_co = TypeVar("F_co", covariant=True)
+
+# Poll at least this often while a wait runs: another track may reset or re-anchor the shared clock meanwhile.
+_CLOCK_RECHECK_US = 50_000
+
+
+class FrameReaderPoll(Protocol[F_co]):
+    """What a sequencer's ``poll()`` returns: the frames ready now, and when to poll again in microseconds."""
+
+    @property
+    def frames(self) -> Sequence[F_co]: ...
+
+    @property
+    def wait_us(self) -> int | None: ...
+
+
+class FrameReaderSequencer(Protocol[F_co]):
+    """What a :class:`FrameReader` drives: ``moq_media.FrameSequencer`` qualifies."""
+
+    track_properties: Sequence[KeyValuePair]
+
+    def object(self, obj: MoqtObject) -> None: ...
+
+    def group_ended(self, group_id: int) -> None: ...
+
+    def group_reset(self, group_id: int) -> None: ...
+
+    def restart(self) -> None: ...
+
+    def poll(self, max_frames: int | None = None) -> FrameReaderPoll[F_co]: ...
+
+
+class FrameReader(Generic[F]):
+    """Read a track as frames: feed the sequencer every event, and poll it as the application reads, or when a wait it
+    reports ends (at most 50 ms on, since another track may move a shared clock). Iterate it for the frames, in decode
+    order; :meth:`close` ends the iteration.
+
+    Pass :meth:`subscription_handlers` to ``RelaySubscriber.subscribe`` or :meth:`want_handlers` to
+    ``SupervisedSubscriber.want``. Each group is one subgroup, as the frame writer sends it, so a subgroup's end is its
+    group's. A want read through a reader keeps ``drain`` at 0, the default: a drained old subscription's groups would
+    arrive after the Move, indistinguishable from the new one's. Frames wait in the sequencer until they are read, and
+    lateness is judged then, so a slow reader gets fresh frames rather than a backlog.
+    """
+
+    def __init__(self, sequencer: FrameReaderSequencer[F]) -> None:
+        self._sequencer = sequencer
+        self._changed: asyncio.Event | None = None
+        self._closed = False
+
+    @property
+    def closed(self) -> bool:
+        """Whether :meth:`close` was called."""
+        return self._closed
+
+    def close(self) -> None:
+        """Stop delivering and drop frames not yet read. Later events are ignored."""
+        self._closed = True
+        self._wake()
+
+    def __aiter__(self) -> FrameReader[F]:
+        return self
+
+    async def __anext__(self) -> F:
+        while not self._closed:
+            # One frame per read: whatever waits stays in the sequencer, judged late when it is taken.
+            result = self._sequencer.poll(1)
+            if result.frames:
+                return result.frames[0]
+            changed = self._changed = self._changed or asyncio.Event()
+            changed.clear()
+            timeout = None if result.wait_us is None else min(result.wait_us, _CLOCK_RECHECK_US) / 1_000_000
+            try:
+                await asyncio.wait_for(changed.wait(), timeout)
+            except TimeoutError:
+                pass
+        raise StopAsyncIteration
+
+    # --- handlers
+
+    def subscription_handlers(
+        self,
+        *,
+        on_error: Callable[[RequestError], None] | None = None,
+        on_publisher_done: Callable[[PublishDone], None] | None = None,
+    ) -> RelaySubscriptionHandlers:
+        """Handlers for one subscription, with the application's own error and completion callbacks."""
+        return RelaySubscriptionHandlers(
+            on_subscribed=self._subscribed,
+            on_error=on_error,
+            on_object=self._object,
+            on_subgroup_end=self._subgroup_end,
+            on_subgroup_reset=self._subgroup_reset,
+            on_publisher_done=on_publisher_done,
+        )
+
+    def want_handlers(
+        self,
+        *,
+        on_subscribed: Callable[[SubscribeOk, tuple[str, ...]], None] | None = None,
+        on_publisher_done: Callable[[PublishDone], None] | None = None,
+        on_restarted: Callable[[RestartReason, tuple[str, ...]], None] | None = None,
+        on_switched: Callable[[WantSwitchedInfo], None] | None = None,
+        on_error: Callable[[BaseException], None] | None = None,
+    ) -> WantHandlers:
+        """Handlers for a want. A Restart and a Move start the sequencer over; the application's callbacks run after."""
+
+        def subscribed(info: SubscribeOk, namespace: tuple[str, ...]) -> None:
+            self._subscribed(info)
+            if on_subscribed is not None:
+                on_subscribed(info, namespace)
+
+        def restarted(reason: RestartReason, namespace: tuple[str, ...]) -> None:
+            self._event(self._sequencer.restart)
+            if on_restarted is not None:
+                on_restarted(reason, namespace)
+
+        def switched(info: WantSwitchedInfo) -> None:
+            def move() -> None:
+                self._sequencer.restart()
+                self._sequencer.track_properties = info.subscribed.track_properties
+
+            self._event(move)
+            if on_switched is not None:
+                on_switched(info)
+
+        return WantHandlers(
+            on_subscribed=subscribed,
+            on_object=self._object,
+            on_subgroup_end=self._subgroup_end,
+            on_subgroup_reset=self._subgroup_reset,
+            on_publisher_done=on_publisher_done,
+            on_restarted=restarted,
+            on_switched=switched,
+            on_error=on_error,
+        )
+
+    def _subscribed(self, info: SubscribeOk) -> None:
+        if not self._closed:
+            self._sequencer.track_properties = info.track_properties
+
+    def _object(self, obj: MoqtObject) -> None:
+        self._event(lambda: self._sequencer.object(obj))
+
+    def _subgroup_end(self, end: SubgroupEnd) -> None:
+        self._event(lambda: self._sequencer.group_ended(end.group_id))
+
+    def _subgroup_reset(self, reset: SubgroupReset) -> None:
+        self._event(lambda: self._sequencer.group_reset(reset.group_id))
+
+    # --- delivery
+
+    def _event(self, apply: Callable[[], None]) -> None:
+        if self._closed:
+            return
+        apply()
+        self._wake()
+
+    def _wake(self) -> None:
+        if self._changed is not None:
+            self._changed.set()

caprid_relay/_settling_groups.py

@@ -0,0 +1,136 @@
+"""A publisher connection's settling groups (see ``CONTEXT.md``).
+
+A settling group is one whose operation completed once its FIN was handed to the transport, but whose
+FIN the relay has not acknowledged yet. aioquic queues without limit, so without a bound a dead uplink
+keeps accepting groups until the congestion window fills (about 190 one-kilobyte groups). Settling
+groups are what can pile up on a connection: open streams are already bounded by one per track. So
+before an operation opens its stream it waits while the connection has :data:`SETTLING_GROUP_LIMIT`
+settling groups, first come first served; it holds nothing while its stream is open, and its group
+joins the set once its FIN is handed over. The count can briefly exceed the limit by the number of
+groups open at that moment. The TypeScript SDK keeps the same set (``ts/src/settling-groups.ts``).
+
+A settling group that fails later (STOP_SENDING, a reset, session teardown) leaves the set like one
+that settles cleanly, and nobody hears of it: the cause surfaces as demand, a rebind, or the
+connection's ``closed``. A group with a SUBGROUP_DELIVERY_TIMEOUT (draft-ietf-moq-transport-22 section
+5.2) carries its timer here: started when the group joins, it resets the stream if the acknowledgement
+has not come by then, which fails the acknowledgement wait, so the group leaves the set the same
+silent way and frees its room. The timer belongs to the group: a subscription change or end and the
+track's close leave it running, and only the acknowledgement or the connection's end settles the
+group first. ``RelayPublisher.close()`` drains the set before it ends the session, because closing
+the connection discards whatever the relay has not acknowledged; delivery timeouts only end some of
+the drained groups sooner.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections import deque
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from moq_core._tasks import observe, spawn
+
+SETTLING_GROUP_LIMIT = 64
+"""Settling groups per publisher connection before new streams wait. Internal, not an option."""
+
+
+async def _settled(acknowledged: Awaitable[None]) -> None:
+    try:
+        await acknowledged
+    except Exception:  # a late failure is dropped: it surfaces elsewhere (see the module doc)
+        pass
+
+
+class SettlingGroups:
+    """The settling groups of one publisher connection, shared by every track on it."""
+
+    __slots__ = ("_limit", "_settling", "_waiting")
+
+    def __init__(self, limit: int = SETTLING_GROUP_LIMIT) -> None:
+        self._limit = limit
+        self._settling: set[asyncio.Task[None]] = set()
+        self._waiting: deque[asyncio.Future[None]] = deque()
+
+    @property
+    def size(self) -> int:
+        """How many groups are settling now."""
+        return len(self._settling)
+
+    def has_room(self) -> bool:
+        """Whether a new stream may open now: the connection is below the limit."""
+        return len(self._settling) < self._limit
+
+    async def wait_for_room(self, interrupted: asyncio.Future[None]) -> None:
+        """Wait until the connection is below the limit, in arrival order.
+
+        Raises the exception ``interrupted`` settles with, if that comes first; the wait then gives up
+        its place in the queue.
+        """
+        if self.has_room():
+            return
+
+        waiter: asyncio.Future[None] = asyncio.get_running_loop().create_future()
+        self._waiting.append(waiter)
+
+        try:
+            await asyncio.wait({waiter, interrupted}, return_when=asyncio.FIRST_COMPLETED)
+        finally:
+            if not waiter.done():
+                self._waiting.remove(waiter)
+                waiter.cancel()
+
+        if not waiter.done() or waiter.cancelled():
+            interrupted.result()
+
+    def add(
+        self,
+        acknowledged: Awaitable[None],
+        *,
+        timeout: float | None = None,
+        on_timeout: Callable[[], None] | None = None,
+    ) -> None:
+        """A group's FIN was handed over: count it until ``acknowledged`` settles, either way.
+
+        With a ``timeout`` (seconds, the group's SUBGROUP_DELIVERY_TIMEOUT), ``on_timeout`` runs if
+        ``acknowledged`` is still pending by then; it resets the group's stream, which settles
+        ``acknowledged`` with the reset.
+        """
+        tracked = spawn(_settled(acknowledged))
+        self._settling.add(tracked)
+        tracked.add_done_callback(self._settle)
+
+        if timeout is not None and on_timeout is not None:
+            timer = asyncio.get_running_loop().call_later(timeout, on_timeout)
+            tracked.add_done_callback(lambda _: timer.cancel())
+
+    async def drain(self, seconds: float, stop: asyncio.Future[Any], *also: Awaitable[None]) -> None:
+        """Wait for every settling group and each of ``also``, for at most ``seconds`` or until ``stop`` settles.
+
+        Never raises; whatever is still unsettled afterwards is left to the transport.
+        """
+        # Futures at once, so a wait cancelled before it starts still counts as awaited.
+        extra = [asyncio.ensure_future(awaitable) for awaitable in also]
+        waits = [*self._settling, *extra]
+
+        try:
+            if waits and not stop.done():
+                everything = asyncio.gather(*waits, return_exceptions=True)
+                observe(everything)
+                await asyncio.wait({everything, stop}, timeout=seconds, return_when=asyncio.FIRST_COMPLETED)
+        finally:
+            # Only the extra waits are ours to stop; the settling groups keep counting.
+            for wait in extra:
+                wait.cancel()
+
+    def _settle(self, tracked: asyncio.Task[None]) -> None:
+        self._settling.discard(tracked)
+
+        # Every waiter goes on, in arrival order, once the connection is below the limit again.
+        while self._waiting and self.has_room():
+            waiter = self._waiting.popleft()
+
+            if not waiter.done():
+                waiter.set_result(None)
+
+
+__all__ = ["SETTLING_GROUP_LIMIT", "SettlingGroups"]