semiont 0.6.12.dev2__py3-none-any.whl

semiont/client.py

@@ -0,0 +1,161 @@
+"""A client of one knowledge base: its eleven namespaces over a transport, the bytes that never ride the bus, and the gateway's own answers.
+
+A client owns a bus of its own (`bus`). Its transport delivers into that bus
+every frame it receives, and what the client's own parts say to each other (a
+viewer's signals) goes through it and never reaches the wire. The namespaces
+are attributes: `client.browse`, `client.mark`, and so on, with `yield_` for
+the one whose name Python keeps for itself.
+
+A client keeps its queries true: what `browse`, `gather` and `match` answer
+as live queries comes from its cache, and each event its transport delivers
+refreshes what the cache holds (`semiont.cached`). With a `persistence`, the
+small queries are kept there, and the next client of the same knowledge base
+shows them at once.
+
+A client is held with `async with`, and inside it listens for what keeps
+its queries true. On the way out its live queries end, its followed jobs end,
+every reader of its own bus is told there is no more, and the tasks it
+started have ended. It does not open or close its transport: whoever opened
+that closes it, after the client.
+
+    async with HttpTransport(origin, token=token) as transport:
+        async with SemiontClient(transport, transport.content, transport) as client:
+            resource = await client.browse.resource(resource_id).fresh()
+"""
+
+from dataclasses import dataclass
+from types import TracebackType
+from typing import Final, Self, final
+
+from semiont.bus import Bus
+from semiont.event_bus import EventBus
+from semiont.namespaces.auth import AuthNamespace
+from semiont.namespaces.beckon import BeckonNamespace
+from semiont.namespaces.bind import BindNamespace
+from semiont.namespaces.browse import BrowseNamespace
+from semiont.namespaces.frame import FrameNamespace
+from semiont.namespaces.gather import GatherNamespace
+from semiont.namespaces.job import JobNamespace
+from semiont.namespaces.links import Links
+from semiont.namespaces.live import CachePersistence, Live
+from semiont.namespaces.mark import MarkNamespace
+from semiont.namespaces.match import MatchNamespace
+from semiont.namespaces.refresher import Refresher
+from semiont.namespaces.system import SystemNamespace
+from semiont.namespaces.yield_ import YieldNamespace
+from semiont.timing import BUS_REQUEST_TIMEOUT_MS, INVALIDATION_WINDOW_MS, JOB_SILENCE_MS, JOB_STATUS_POLL_MS
+from semiont.transport import ContentTransport, GatewayOperations, Transport
+
+__all__ = ["CachePersistence", "ClientTiming", "SemiontClient"]
+
+
+@final
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ClientTiming:
+    """The waits a client keeps: `specs/src/client/timing.json`'s, unless a caller that must not wait them out says otherwise."""
+
+    bus_request_ms: int = BUS_REQUEST_TIMEOUT_MS
+    """How long a bus request waits for its reply."""
+    job_silence_ms: int = JOB_SILENCE_MS
+    """How long a followed job may say nothing before its status is asked for."""
+    job_status_poll_ms: int = JOB_STATUS_POLL_MS
+    """How often a silent job's status is asked for after that."""
+    invalidation_window_ms: int = INVALIDATION_WINDOW_MS
+    """How long the refetches events ask of one cached key are one refetch."""
+
+
+@final
+class SemiontClient[T: Transport]:
+    """See the module's documentation.
+
+    `content` carries the bytes and `gateway` answers for itself; over HTTP
+    the transport is all three. `transport` is kept as the kind of transport
+    it is, for what the namespaces do not cover: a frame on a channel by name,
+    a hold on a resource's scope.
+    """
+
+    def __init__(
+        self,
+        transport: T,
+        content: ContentTransport,
+        gateway: GatewayOperations,
+        *,
+        timing: ClientTiming | None = None,
+        persistence: CachePersistence | None = None,
+    ) -> None:
+        kept = ClientTiming() if timing is None else timing
+        self.transport: Final[T] = transport
+        self.timing: Final = kept
+        self.bus: Final = EventBus()
+        """The client's own bus: every frame the transport delivered, and every signal the client's parts gave each other."""
+        self.wire: Final = Bus(transport)
+        """The bus over the transport, typed by channel: an emit, a channel's frames, a request."""
+        transport.bridge_into(self.bus)
+        self._links: Final = Links(
+            wire=self.wire,
+            own=self.bus,
+            bus_request_ms=kept.bus_request_ms,
+            job_silence_ms=kept.job_silence_ms,
+            job_status_poll_ms=kept.job_status_poll_ms,
+        )
+        self._closed = False
+        self._held = False
+        self._live: Final = Live(self._links, persistence)
+        self._refresher: Final = Refresher(self._links, self._live, invalidation_window_ms=kept.invalidation_window_ms)
+
+        self.frame: Final = FrameNamespace(self._links)
+        """The vocabulary: what kinds of things exist."""
+        self.browse: Final = BrowseNamespace(self._links, content, self._live)
+        """Reads, and this viewer's own signals."""
+        self.mark: Final = MarkNamespace(self._links)
+        """Annotations, a resource's own metadata, and AI assistance."""
+        self.bind: Final = BindNamespace(self._links)
+        """Linking a reference to what it refers to."""
+        self.gather: Final = GatherNamespace(self._links, self._live)
+        """Assembling the context a model is given, and what refers to a resource."""
+        self.match: Final = MatchNamespace(self._links, self._live)
+        """Searching: for what a reference could refer to, and for resources by text."""
+        self.yield_: Final = YieldNamespace(self._links, content)
+        """Creating resources."""
+        self.beckon: Final = BeckonNamespace(self._links)
+        """Attention: driving the other participants' viewers."""
+        self.job: Final = JobNamespace(self._links)
+        """Jobs: their lifecycle, their status and their cancellation."""
+        self.auth: Final = AuthNamespace(gateway)
+        """The gateway's view of who is signed in."""
+        self.system: Final = SystemNamespace(gateway)
+        """What the knowledge base says about itself."""
+
+    async def __aenter__(self) -> Self:
+        if self._closed or self._held:
+            raise RuntimeError("a client is held once")
+        self._held = True
+        self._refresher.start()
+        self._live.kept_true()
+        return self
+
+    async def __aexit__(self, kind: type[BaseException] | None, error: BaseException | None, trace: TracebackType | None) -> None:
+        await self.close()
+
+    @property
+    def persistence_settled(self) -> bool:
+        """Whether every cache the client keeps is at rest: none is fetching, and none owes a save.
+
+        What is kept of the stream's place is kept only then (`semiont.resume`).
+        """
+        return self._live.persistence_settled
+
+    async def close(self) -> None:
+        """End the client.
+
+        The queries end first: every watcher's states end, a read asked for
+        after is refused as `bus.closed`, and what was owed to storage is
+        saved. Then its own bus ends, so every reader of it and every followed
+        job does, and then the tasks it started: a read still waiting for its
+        answer fails as `bus.closed`. Closing twice is closing once.
+        """
+        self._closed = True
+        self._refresher.dispose()
+        self._live.dispose()
+        self.bus.destroy()
+        await self._links.close()

semiont/error_codes.py

@@ -0,0 +1,232 @@
+# Generated from specs/src/errors/codes.json; do not edit.
+# Regenerate: node scripts/spec/generate-error-codes-python.mjs
+
+"""The codes a Semiont client reports a failure under.
+
+Each vocabulary is a closed set: a `Literal` union, so a `match` over one that
+ends in `assert_never` is checked to name every code, and a tuple of the same
+codes to iterate.
+"""
+
+from collections.abc import Mapping
+from types import MappingProxyType
+from typing import Final, Literal
+
+__all__ = [
+    "BUS_REQUEST_CODE_BY_WIRE_CODE",
+    "BUS_REQUEST_ERROR_CODES",
+    "BusRequestErrorCode",
+    "IDENTITY_UNVERIFIABLE_REASONS",
+    "IdentityUnverifiableReason",
+    "JOB_ERROR_CODES",
+    "JobErrorCode",
+    "SEMIONT_SESSION_ERROR_CODES",
+    "SIGN_IN_ERROR_CODES",
+    "SemiontSessionErrorCode",
+    "SignInErrorCode",
+    "TRANSPORT_ERROR_CODES",
+    "TransportErrorCode",
+    "UNRECOGNIZED_FAILURE_CODE",
+    "transport_error_code_for_status",
+]
+
+# Why a bus request did not resolve. Some members restate a failure the answering peer declared
+# on the wire (`wire` names its `CommandError.code`); the rest are facts only the requesting
+# side knows, which is why this vocabulary and the wire's stay separate.
+type BusRequestErrorCode = Literal[
+    # No reply arrived within the time the request allowed.
+    "bus.timeout",
+    # The peer answered with a failure whose code this vocabulary does not name, or that states
+    # none.
+    "bus.rejected",
+    # The bus stopped before a reply came: its client was disposed, or its transport closed.
+    "bus.closed",
+    # The peer says this resource does not exist in its knowledge base.
+    "bus.not-found",
+    # THIS transport is not subscribed to the reply channel: a local misconfiguration, caught
+    # before emitting. Not to be confused with `bus.peer-unavailable`, which is the opposite
+    # end.
+    "bus.unsubscribed",
+    # The service that answers this channel is not connected. Transient by nature, a peer still
+    # starting, and therefore the one failure on this list worth retrying.
+    "bus.peer-unavailable",
+    # The peer says this caller may not do what it asked: authenticated, not permitted. Retrying
+    # under the same credential cannot succeed, so a consumer surfaces it and never spins on it.
+    "bus.unauthorized",
+    # The peer declined and nothing went wrong: a `job:claim` found no pending job of the
+    # requested types. The one member a consumer parks on.
+    "bus.none-pending",
+]
+
+BUS_REQUEST_ERROR_CODES: Final[tuple[BusRequestErrorCode, ...]] = (
+    "bus.timeout",
+    "bus.rejected",
+    "bus.closed",
+    "bus.not-found",
+    "bus.unsubscribed",
+    "bus.peer-unavailable",
+    "bus.unauthorized",
+    "bus.none-pending",
+)
+
+# The bus code a failure's own wire code (`CommandError.code`) becomes.
+BUS_REQUEST_CODE_BY_WIRE_CODE: Final[Mapping[str, BusRequestErrorCode]] = MappingProxyType(
+    {
+        "not-found": "bus.not-found",
+        "peer-unavailable": "bus.peer-unavailable",
+        "unauthorized": "bus.unauthorized",
+        "none-pending": "bus.none-pending",
+    }
+)
+
+# What a failure becomes when its code is one this vocabulary does not name, or absent.
+UNRECOGNIZED_FAILURE_CODE: Final[BusRequestErrorCode] = "bus.rejected"
+
+# Transport-neutral failure vocabulary. Every transport maps its native failures to one of
+# these, so a routing layer matches on the code without knowing the wire kind. Over HTTP the
+# mapping is by status: `status` is an exact status, `statusFrom` every status at or above it.
+type TransportErrorCode = Literal[
+    # Authentication is required: the token is missing or expired.
+    "unauthorized",
+    # Authenticated, and lacking permission.
+    "forbidden",
+    # The resource is missing.
+    "not-found",
+    # A concurrent modification, a duplicate, or another conflict with current state.
+    "conflict",
+    # The request is malformed.
+    "bad-request",
+    # A limit refused it; the refusal's `Retry-After` says when to return.
+    "rate-limited",
+    # The gateway is unreachable, the network failed, or the server answered 5xx.
+    "unavailable",
+    # A failure no other member names.
+    "error",
+]
+
+TRANSPORT_ERROR_CODES: Final[tuple[TransportErrorCode, ...]] = (
+    "unauthorized",
+    "forbidden",
+    "not-found",
+    "conflict",
+    "bad-request",
+    "rate-limited",
+    "unavailable",
+    "error",
+)
+
+
+def transport_error_code_for_status(status: int) -> TransportErrorCode:
+    """The transport code an HTTP status becomes."""
+    match status:
+        case 401:
+            return "unauthorized"
+        case 403:
+            return "forbidden"
+        case 404:
+            return "not-found"
+        case 409:
+            return "conflict"
+        case 400:
+            return "bad-request"
+        case 429:
+            return "rate-limited"
+        case _:
+            pass
+    if status >= 500:
+        return "unavailable"
+    return "error"
+
+
+# Why a job its client follows ended without a result. A failure the queue will retry is not one
+# of these: the job goes on, and its follower is told of the setback and keeps following.
+type JobErrorCode = Literal[
+    # The job failed and will not be tried again: the failure its worker reported, or the one
+    # its status states.
+    "job.failed",
+    # The job was cancelled before it ended, as its status states. Nothing announces a
+    # cancellation: its follower learns of it when it asks for the job's status.
+    "job.cancelled",
+    # The job said nothing for longer than its follower allows. The follower has asked for that
+    # job to be cancelled.
+    "job.stalled",
+]
+
+JOB_ERROR_CODES: Final[tuple[JobErrorCode, ...]] = (
+    "job.failed",
+    "job.cancelled",
+    "job.stalled",
+)
+
+# Why a session itself is unusable. Per-request failures stay with their caller.
+type SemiontSessionErrorCode = Literal[
+    # A session for the knowledge base could not be built or made ready.
+    "session.construct-failed",
+    # The stored credential could not be validated at startup, for a reason other than the
+    # gateway refusing it.
+    "session.auth-failed",
+    # The session could not be renewed: the issuer refused, or stayed unreachable until the
+    # retry budget was spent. Not a prompt to retry: retrying already happened.
+    "session.refresh-exhausted",
+    # The gateway refused a token the issuer had just issued. The two disagree about who may
+    # sign in, and renewing again cannot change the answer: the session is over, and signing in
+    # again is what is left.
+    "session.credential-refused",
+]
+
+SEMIONT_SESSION_ERROR_CODES: Final[tuple[SemiontSessionErrorCode, ...]] = (
+    "session.construct-failed",
+    "session.auth-failed",
+    "session.refresh-exhausted",
+    "session.credential-refused",
+)
+
+# Why a person could not be signed in at the issuer a knowledge base trusts, or a session could
+# not be renewed there. Over the authorization-code grant, the device grant, the refresh grant
+# and revocation alike.
+type SignInErrorCode = Literal[
+    # The knowledge base trusts no external issuer: there is nowhere to sign in.
+    "no-issuer",
+    # The knowledge base did not say which issuer it trusts, or the issuer did not describe
+    # itself, or described another issuer, or offers no endpoint the grant needs.
+    "discovery",
+    # A sign-in response arrived and no sign-in is pending here: it was completed already, or
+    # begun somewhere else.
+    "no-pending",
+    # The sign-in response does not belong to the pending sign-in.
+    "state",
+    # The person, or the issuer, refused the sign-in.
+    "denied",
+    # The device code ran out before it was approved.
+    "expired",
+    # The sign-in was abandoned by whoever began it.
+    "aborted",
+    # The issuer refused a token request, a device authorization or a revocation, or answered
+    # without what was asked for.
+    "exchange",
+]
+
+SIGN_IN_ERROR_CODES: Final[tuple[SignInErrorCode, ...]] = (
+    "no-issuer",
+    "discovery",
+    "no-pending",
+    "state",
+    "denied",
+    "expired",
+    "aborted",
+    "exchange",
+)
+
+# Why a knowledge base that was reached with a fresh sign-in could not be registered: it has to
+# say who it is, and nothing stands in for its answer.
+type IdentityUnverifiableReason = Literal[
+    # The knowledge base was not reached, so it said nothing.
+    "unreachable",
+    # The knowledge base answered that it cannot say what it is.
+    "not-reported",
+]
+
+IDENTITY_UNVERIFIABLE_REASONS: Final[tuple[IdentityUnverifiableReason, ...]] = (
+    "unreachable",
+    "not-reported",
+)

semiont/errors.py

@@ -0,0 +1,147 @@
+"""A failure, as this SDK reports one: under a code of `specs/src/errors/codes.json`.
+
+Every failure is a `SemiontError`, and each vocabulary of codes has a class of
+its own, so `except BusRequestError` reads as what it catches and a `match`
+over `error.code` is checked to name every code.
+"""
+
+from abc import ABC, abstractmethod
+from collections.abc import Mapping
+from typing import Final, final, override
+
+from pydantic import JsonValue
+
+from semiont.error_codes import (
+    BUS_REQUEST_CODE_BY_WIRE_CODE,
+    UNRECOGNIZED_FAILURE_CODE,
+    BusRequestErrorCode,
+    JobErrorCode,
+    SemiontSessionErrorCode,
+    SignInErrorCode,
+    TransportErrorCode,
+    transport_error_code_for_status,
+)
+from semiont.identifiers import JobId
+
+__all__ = ["BusRequestError", "JobError", "SemiontError", "SessionError", "SignInError", "TransportError"]
+
+
+class SemiontError(Exception, ABC):
+    """One failure. Its text is for a person; a program reads its `code`."""
+
+    def __init__(self, message: str, *, status: int | None = None, retry_after_ms: int | None = None) -> None:
+        super().__init__(message)
+        self.message: Final = message
+        self.status: Final = status
+        """The HTTP status, when a server stated one."""
+        self.retry_after_ms: Final = retry_after_ms
+        """The wait a refusal's `Retry-After` stated, in milliseconds, when it stated one."""
+
+    @property
+    @abstractmethod
+    def code(self) -> str:
+        """Which failure this is, in its vocabulary."""
+
+
+@final
+class TransportError(SemiontError):
+    """A request a server refused, or one that got no answer."""
+
+    def __init__(self, code: TransportErrorCode, message: str, *, status: int | None = None, retry_after_ms: int | None = None) -> None:
+        super().__init__(message, status=status, retry_after_ms=retry_after_ms)
+        self._code: Final = code
+
+    @property
+    @override
+    def code(self) -> TransportErrorCode:
+        return self._code
+
+    @classmethod
+    def of_status(cls, message: str, status: int, retry_after_ms: int | None) -> "TransportError":
+        """A server answered, and its status decides the code."""
+        return cls(transport_error_code_for_status(status), message, status=status, retry_after_ms=retry_after_ms)
+
+    @classmethod
+    def without_response(cls, message: str) -> "TransportError":
+        """Nothing answered: the connection failed, or the request's deadline passed."""
+        return cls("unavailable", message)
+
+
+@final
+class BusRequestError(SemiontError):
+    """A request over the bus that did not resolve with its response."""
+
+    def __init__(self, code: BusRequestErrorCode, message: str, *, failure: Mapping[str, JsonValue] | None = None) -> None:
+        super().__init__(message)
+        self._code: Final = code
+        self.failure: Final = failure
+        """What the peer answered on the operation's failure channel, when the peer answered."""
+
+    @property
+    @override
+    def code(self) -> BusRequestErrorCode:
+        return self._code
+
+    @classmethod
+    def answered(cls, failure: Mapping[str, JsonValue]) -> "BusRequestError":
+        """The failure a peer answered with, under the code its own code becomes.
+
+        A failure that states no code, or one this vocabulary does not name,
+        is `UNRECOGNIZED_FAILURE_CODE`: the peer may be newer than this build.
+        """
+        stated = failure.get("code")
+        said = failure.get("message")
+        code = (
+            BUS_REQUEST_CODE_BY_WIRE_CODE.get(stated, UNRECOGNIZED_FAILURE_CODE) if isinstance(stated, str) else UNRECOGNIZED_FAILURE_CODE
+        )
+        return cls(code, said if isinstance(said, str) else "Bus request rejected", failure=failure)
+
+
+@final
+class JobError(SemiontError):
+    """A job its follower saw end without completing: it failed for good, was cancelled, or said nothing for too long."""
+
+    def __init__(self, code: JobErrorCode, message: str, *, job_id: JobId | None) -> None:
+        super().__init__(message)
+        self._code: Final = code
+        self.job_id: Final = job_id
+        """The job, when its creation was answered: one that stalled before that has no id."""
+
+    @property
+    @override
+    def code(self) -> JobErrorCode:
+        return self._code
+
+
+@final
+class SignInError(SemiontError):
+    """A sign-in at the issuer a knowledge base trusts, or a renewal there, that did not succeed.
+
+    One that carries a status is the issuer's answer. One that carries none
+    got no answer: a refusal and an outage are different events.
+    """
+
+    def __init__(self, code: SignInErrorCode, message: str, *, status: int | None = None) -> None:
+        super().__init__(message, status=status)
+        self._code: Final = code
+
+    @property
+    @override
+    def code(self) -> SignInErrorCode:
+        return self._code
+
+
+@final
+class SessionError(SemiontError):
+    """A failure that makes a session itself unusable. A request's own failure stays with its caller."""
+
+    def __init__(self, code: SemiontSessionErrorCode, message: str, *, kb_id: str) -> None:
+        super().__init__(message)
+        self._code: Final = code
+        self.kb_id: Final = kb_id
+        """The knowledge base the session was with."""
+
+    @property
+    @override
+    def code(self) -> SemiontSessionErrorCode:
+        return self._code

semiont/event_bus.py

@@ -0,0 +1,108 @@
+"""A client's own bus: frames published and read inside one process.
+
+A client makes one and hands it to its transport (`bridge_into`), which
+delivers into it every frame it receives. What the client's own parts say to
+each other goes through it too, and never reaches the wire.
+
+A frame is published to everyone or into one resource's scope, and a reader
+sees one or the other: a reader of a channel does not see a frame published
+into a scope, and a scope's reader sees only its own.
+
+A reader of one channel is given its frames in the order they were published.
+Two readers give no order between them, so one that needs what was said on
+several channels in the order it was said reads them as one (`frames_among`).
+
+By type (`publish`, `frames`), the channel is one of `semiont.channels`'
+constants and the payload is that channel's own, as on `semiont.bus.Bus`. By
+name (`emit`, `frames_on`), a channel is its name and a payload a JSON object.
+"""
+
+from collections.abc import Collection, Mapping
+from typing import Final, final, override
+
+from pydantic import JsonValue
+
+from semiont.bus import Typed
+from semiont.channel import Channel
+from semiont.events import Broadcast, Events
+from semiont.identifiers import ResourceId
+from semiont.model import WireModel
+from semiont.transport import Frame, FrameSink
+
+__all__ = ["EventBus"]
+
+
+@final
+class EventBus(FrameSink):
+    """See the module's documentation."""
+
+    def __init__(self) -> None:
+        self._views: Final[dict[tuple[str, ResourceId | None], Broadcast[Frame]]] = {}
+        """The readers of each channel: of what is published to everyone, and of each scope."""
+        self._among: list[tuple[frozenset[str], Broadcast[Frame]]] = []
+        """The readers of several channels at once, each with the channels it reads."""
+        self._destroyed = False
+
+    @property
+    def destroyed(self) -> bool:
+        """Whether the bus has ended."""
+        return self._destroyed
+
+    @override
+    def deliver(self, frame: Frame) -> None:
+        """Publish a frame as it is: to everyone, or into the scope it names. A destroyed bus has no reader to give it to."""
+        if frame.scope is None:
+            for channels, readers in self._among:
+                if frame.channel in channels:
+                    readers.deliver(frame)
+        view = self._views.get((frame.channel, frame.scope))
+        if view is not None:
+            view.deliver(frame)
+
+    def emit(
+        self, channel: str, payload: Mapping[str, JsonValue], *, scope: ResourceId | None = None, correlation_id: str | None = None
+    ) -> None:
+        """Publish one frame on the channel named `channel`: to everyone, or into `scope`."""
+        self.deliver(Frame(channel=channel, payload=payload, correlation_id=correlation_id, scope=scope))
+
+    def publish[P: WireModel](
+        self, channel: Channel[P], payload: P, *, scope: ResourceId | None = None, correlation_id: str | None = None
+    ) -> None:
+        """Publish one frame of `channel`: to everyone, or into `scope`."""
+        self.emit(channel.name, channel.encode(payload), scope=scope, correlation_id=correlation_id)
+
+    def frames_on(self, channel: str, *, scope: ResourceId | None = None) -> Events[Frame]:
+        """The frames published on the channel named `channel` from now on: to everyone, or into `scope`. Of a destroyed bus, none."""
+        view = self._views.get((channel, scope))
+        if view is None:
+            view = Broadcast[Frame]()
+            if self._destroyed:
+                view.close()
+            else:
+                self._views[channel, scope] = view
+        return view.listen()
+
+    def frames[P: WireModel](self, channel: Channel[P], *, scope: ResourceId | None = None) -> Typed[P]:
+        """The frames published on `channel` from now on, each with its payload decoded: to everyone, or into `scope`."""
+        return Typed(channel, self.frames_on(channel.name, scope=scope))
+
+    def frames_among(self, channels: Collection[str]) -> Events[Frame]:
+        """The frames published to everyone on any of `channels` from now on, in the order they were published."""
+        readers = Broadcast[Frame]()
+        if self._destroyed:
+            readers.close()
+        else:
+            # A view nobody reads any more is let go here, where the next one is made.
+            self._among = [(seen, kept) for seen, kept in self._among if kept.listening > 0]
+            self._among.append((frozenset(channels), readers))
+        return readers.listen()
+
+    def destroy(self) -> None:
+        """End every reader's frames, and every later reader's. Destroying twice is destroying once."""
+        self._destroyed = True
+        for view in self._views.values():
+            view.close()
+        for _, readers in self._among:
+            readers.close()
+        self._views.clear()
+        self._among.clear()