dynamicforms-fastapi-viewsets 0.9.0__tar.gz → 0.9.1__tar.gz

{dynamicforms_fastapi_viewsets-0.9.0 → dynamicforms_fastapi_viewsets-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dynamicforms-fastapi-viewsets
-Version: 0.9.0
+Version: 0.9.1
 Summary: Django REST Framework-style viewsets for FastAPI, with optional Celery-backed async execution and a Vue/TypeScript client counterpart.
 Project-URL: Homepage, https://github.com/dynamicforms/fastapi-viewsets
 Project-URL: Repository, https://github.com/dynamicforms/fastapi-viewsets
@@ -33,8 +33,8 @@ Requires-Dist: asgiref; extra == 'dev'
 Requires-Dist: celery; extra == 'dev'
 Requires-Dist: coverage; extra == 'dev'
 Requires-Dist: django; extra == 'dev'
-Requires-Dist: httpx; extra == 'dev'
-Requires-Dist: muxws[starlette,websockets]>=0.4.0; extra == 'dev'
+Requires-Dist: httpx2; extra == 'dev'
+Requires-Dist: muxws[starlette,websockets]>=0.4.1; extra == 'dev'
 Requires-Dist: pyjwt; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'
 Requires-Dist: pytest-asyncio; extra == 'dev'
@@ -46,7 +46,7 @@ Requires-Dist: django>=4.2; extra == 'django'
 Provides-Extra: jwt
 Requires-Dist: pyjwt>=2.8; extra == 'jwt'
 Provides-Extra: muxws
-Requires-Dist: muxws[starlette]>=0.4.0; extra == 'muxws'
+Requires-Dist: muxws[starlette]>=0.4.1; extra == 'muxws'
 Description-Content-Type: text/markdown
 
 # DynamicForms FastAPI Viewsets
@@ -71,6 +71,11 @@ Celery-backed async execution and a matching Vue/TypeScript client counterpart.
   per call. A command goes through your application as an HTTP request does - its middleware,
   exception handlers, router dependencies and state - so both transports behave identically. In the
   demo, a burst of 100 requests takes 156 ms over REST and 37 ms over muxws.
+- **Events** — publish an event to a topic and every frontend following it learns of it, as a muxws
+  push or on its next poll. `ChangeEvents` publishes every create, update and destroy of a viewset to
+  its routed base path; custom events are declared with `source()`. Every event is recorded before it
+  is pushed, so a dropped push costs latency, not an event. On the frontend, `watch()` on a ViewSet
+  follows its topic and `applyChanges()` applies each change to a list of rows.
 - **Three list shapes** — a bare array, offset paging, or cursor paging. A viewset declares which,
   and may let a client pick per request with an `X-List-Shape` header.
 - **Declarative filters** — declare which fields accept which operators and get query parameters,
@@ -145,8 +150,15 @@ An infinite-scrolling grid over a 5000-track library, cursor-paged. Switch the w
 the REST and muxws transports and between the in-memory and SQLite backends, and compare their
 latency side by side. Sorting and filtering are server-side.
 
-`--celery` needs Redis on localhost:6379. The end-to-end suite starts its own backend and dev
-server on their own ports.
+The grid follows its viewset's change events (`ChangeEvents` on the backend, `watch()` in the
+grid). Click a Favorite cell to toggle it: every tab showing the library applies the change, over
+muxws as a push, over REST on its next poll. A sorted or filtered grid reloads its list on the
+change: the row may have moved or left it.
+
+`--celery` needs Redis on localhost:6379. The worker runs the viewset calls of both backends and
+publishes their events through Redis. It runs as one process, because the in-memory library is a
+dict held by each process; the SQLite library is one file shared by every process. The end-to-end
+suite starts its own backend and dev server on their own ports.
 
 ## License
 

{dynamicforms_fastapi_viewsets-0.9.0 → dynamicforms_fastapi_viewsets-0.9.1}/README.md

@@ -20,6 +20,11 @@ Celery-backed async execution and a matching Vue/TypeScript client counterpart.
   per call. A command goes through your application as an HTTP request does - its middleware,
   exception handlers, router dependencies and state - so both transports behave identically. In the
   demo, a burst of 100 requests takes 156 ms over REST and 37 ms over muxws.
+- **Events** — publish an event to a topic and every frontend following it learns of it, as a muxws
+  push or on its next poll. `ChangeEvents` publishes every create, update and destroy of a viewset to
+  its routed base path; custom events are declared with `source()`. Every event is recorded before it
+  is pushed, so a dropped push costs latency, not an event. On the frontend, `watch()` on a ViewSet
+  follows its topic and `applyChanges()` applies each change to a list of rows.
 - **Three list shapes** — a bare array, offset paging, or cursor paging. A viewset declares which,
   and may let a client pick per request with an `X-List-Shape` header.
 - **Declarative filters** — declare which fields accept which operators and get query parameters,
@@ -94,8 +99,15 @@ An infinite-scrolling grid over a 5000-track library, cursor-paged. Switch the w
 the REST and muxws transports and between the in-memory and SQLite backends, and compare their
 latency side by side. Sorting and filtering are server-side.
 
-`--celery` needs Redis on localhost:6379. The end-to-end suite starts its own backend and dev
-server on their own ports.
+The grid follows its viewset's change events (`ChangeEvents` on the backend, `watch()` in the
+grid). Click a Favorite cell to toggle it: every tab showing the library applies the change, over
+muxws as a push, over REST on its next poll. A sorted or filtered grid reloads its list on the
+change: the row may have moved or left it.
+
+`--celery` needs Redis on localhost:6379. The worker runs the viewset calls of both backends and
+publishes their events through Redis. It runs as one process, because the in-memory library is a
+dict held by each process; the SQLite library is one file shared by every process. The end-to-end
+suite starts its own backend and dev server on their own ports.
 
 ## License
 

dynamicforms_fastapi_viewsets-0.9.1/fastapi_viewsets/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.9.1"

{dynamicforms_fastapi_viewsets-0.9.0 → dynamicforms_fastapi_viewsets-0.9.1}/fastapi_viewsets/collection_viewset.py

@@ -102,6 +102,11 @@ class CollectionViewSet(AsyncCollectionViewSet[K, T]):
                 self._update_func = self._update_mapping
                 self._delete_func = container.__delitem__
 
+    @property
+    def pk_field_name(self) -> str:
+        """`pk_field`, the name the list's cursor shape and `ChangeEvents` read the pk under."""
+        return self.pk_field
+
     def _check_mutable(self):
         if not self.is_mutable:
             raise ReadOnlyCollectionError()

{dynamicforms_fastapi_viewsets-0.9.0 → dynamicforms_fastapi_viewsets-0.9.1}/fastapi_viewsets/conf.py

@@ -8,6 +8,9 @@ if TYPE_CHECKING:
     from fastapi.security.base import SecurityBase
 
     from .context.auth import AuthBackend
+    from .events.authorizers import EventAuthorizer
+    from .events.delivery import DeliveryFilter
+    from .events.store import EventStore
     from .middleware import CommandMiddleware
 
 ContextProcessor = Callable[["Request", Any], Awaitable[dict[str, Any]]]
@@ -64,6 +67,51 @@ class Settings:
         class is decorated with route_viewset, as `viewsets_command_middleware` must, which decides
         `disable_response_model` when the routes are built.
         """
+        self.viewsets_event_store: EventStore | None = None
+        """
+        The `EventStore` of `fastapi_viewsets.events`: it assigns each event its rev, keeps the
+        topic's log for `poll` and carries the event to `deliver()` in every process that watches
+        the topic. None is one `MemoryEventStore` for this process. A deployment of more than one
+        process, a Celery worker included, sets a `RedisEventStore` in every process.
+        """
+        self.viewsets_event_authorizers: list[EventAuthorizer] = []
+        """
+        The functions that decide whether a caller may follow a topic, consulted in list order on
+        every `subscribe` and on every `poll`, per topic. The first `True` admits the topic, the first
+        `False` refuses it, and no decision refuses it: an empty list refuses every topic.
+        """
+        self.viewsets_event_delivery_filters: list[DeliveryFilter] = []
+        """
+        The functions that decide, per subscription and per event, whether a push is sent. A filter
+        that answers False skips that socket; a filter that raises counts as True.
+        """
+        self.viewsets_event_log_size: int = 32
+        """
+        The number of a topic's most recent events the store keeps for `poll`. 0 keeps none, and a
+        poll from any cursor behind the topic's rev answers `events: null`.
+        """
+        self.viewsets_event_log_ttl: float = 60.0
+        """
+        Seconds a topic's log is kept after the topic's last event. The topic's rev counter is kept
+        without expiry. `RedisEventStore` sets it as the log key's expiry; `MemoryEventStore` empties
+        an expired log when it next reads or appends to it.
+        """
+        self.viewsets_event_push_timeout: float = 2.0
+        """
+        Seconds the delivery filters and `peer.notify()` of one push of one event to one socket may
+        take together. `notify()` queues the push on the socket and returns without waiting for the
+        socket to send it. A push that takes longer is cancelled and logged at debug level.
+        """
+        self.viewsets_event_max_subscriptions: int = 256
+        """
+        The number of topics one socket may hold; a subscription beyond it raises
+        `EventSubscriptionsExceededError` (409). Also the number of cursors one poll may carry.
+        """
+        self.viewsets_event_poll_after_ms: int = 0
+        """
+        `poll_after_ms` of every poll answer: the shortest interval, in milliseconds, at which a
+        client polls.
+        """
 
 
 settings = Settings()

{dynamicforms_fastapi_viewsets-0.9.0 → dynamicforms_fastapi_viewsets-0.9.1}/fastapi_viewsets/decorators/route_viewset.py

@@ -38,6 +38,14 @@ from .primary_key_model_helper import (
 
 T = TypeVar("T")
 
+MIDDLEWARE_DEPENDS_ATTRIBUTE = "__viewset_middleware_depends__"
+"""
+Set to True on the dependency `route_viewset` appends to each route's `dependencies`, which runs
+`Middleware.depends()` of the effective middlewares. The other entries of a route's `dependencies`
+are the application's: those of `FastAPI(dependencies=...)`, of `include_router`, of the
+`APIRouter` and of the route itself.
+"""
+
 
 def build_type_map(cls: type[T], current_map: dict = None) -> dict:
     if current_map is None:
@@ -131,11 +139,12 @@ def _make_middleware_depends(cls: type, action_name: str):
         async def middleware_depends(request: Request) -> None:
             await _run(request)
 
-        return middleware_depends
+    else:
 
-    async def middleware_depends(request: Request, _credential=Depends(scheme)) -> None:  # noqa: B008
-        await _run(request)
+        async def middleware_depends(request: Request, _credential=Depends(scheme)) -> None:  # noqa: B008
+            await _run(request)
 
+    setattr(middleware_depends, MIDDLEWARE_DEPENDS_ATTRIBUTE, True)
     return middleware_depends
 
 
@@ -148,14 +157,17 @@ def route_viewset(
     register_rest: bool = None,
 ):
     """
+    Sets `cls.__viewset_metadata__`, a dict of `base_path`, `lifecycle`, `router` (the argument),
+    `pk_field_name` (the argument, None without it) and `paths`: each action name, the endpoint
+    method's name, mapped to its route's path relative to `base_path` (`""` for `list_items`,
+    `"/{pk}"` for `retrieve`, `"/bulk"` for `bulk_create`). Every endpoint added to `router` carries
+    `__viewset_class__` (`cls`) and `__viewset_action__` (the action name); the `/schema` endpoints
+    carry the action name `"schema"`.
+
     `register_rest` and `register_muxws` decide which transports this viewset is published on.
     True registers, False does not, and None - the default - defers: REST to "yes", muxws to
     `settings.viewsets_register_muxws`. Individual endpoints override either again with
     `@transports(...)`.
-
-    Two parameters rather than one because there are two transports. If a third ever arrives, the
-    replacement is a single mapping - `transports={"rest": False}`, absent key meaning defer -
-    rather than a third `register_*`; see GAPS.md for why a set of flags is the worse shape.
     """
 
     if lifecycle not in get_args(LifecycleType):
@@ -172,8 +184,7 @@ def route_viewset(
             cls_name = cls_name[: -len("ViewSet")]
         default_tags = [cls_name] if cls_name else None
         # The viewset's own docstring becomes the description of the group its endpoints appear
-        # under - the section intro that was otherwise blank however well each endpoint was
-        # documented. See endpoint_docs.apply_viewset_tags.
+        # under. See endpoint_docs.apply_viewset_tags.
         if cls_name:
             register_tag(cls_name, viewset_description(cls))
 
@@ -378,11 +389,13 @@ def route_viewset(
         def is_schema_route(route) -> bool:
             return getattr(route.endpoint, "__viewset_schema_endpoint__", False)
 
-        def add_route(route_kwargs: dict, transports: set[str]) -> None:
+        def add_route(route_kwargs: dict, transports: set[str], action_name: str) -> None:
             # One route per endpoint on the application's router, whichever transports publish it,
             # so both transports go through the application's middleware, exception handlers and
             # router dependencies. The route matches only its own transports (see routing.py), and
             # only a route published on REST appears in the application's OpenAPI document.
+            route_kwargs["endpoint"].__viewset_class__ = cls
+            route_kwargs["endpoint"].__viewset_action__ = action_name
             router.add_api_route(
                 **{**route_kwargs, "include_in_schema": route_kwargs["include_in_schema"] and REST in transports},
                 route_class_override=transport_route_class(router.route_class, frozenset(transports)),
@@ -396,9 +409,14 @@ def route_viewset(
         rest_routes = []
         muxws_routes = []
         documented = set()
+        # action name -> the route's path after base_path, so that a route's path on the application
+        # is the routed base path (include_router prefix + base_path) followed by it
+        paths: dict[str, str] = {}
+        base = base_path.rstrip("/")
         for route in cls.__router.routes:
             action_name = route.endpoint.__name__  # survives @wraps(original_endpoint) in get_wrapper
             documented.add(action_name)
+            paths.setdefault(action_name, route.path[len(base) :] if route.path.startswith(base) else route.path)
             dependencies = list(route.dependencies or []) + [Depends(_make_middleware_depends(cls, action_name))]
             route_kwargs = route_to_add_api_route_kwargs(route, dependencies=dependencies)
             # Per-viewset wording for an endpoint the mixin provided - the mixin's own docstring is
@@ -412,9 +430,9 @@ def route_viewset(
                 if on_rest:
                     rest_schema_kwargs = {**route_kwargs, "endpoint": openapi_endpoint(rest_routes)}
                     rest_routes.append(rest_schema_kwargs)
-                    add_route(rest_schema_kwargs, {REST})
+                    add_route(rest_schema_kwargs, {REST}, action_name)
                 if on_muxws_any:
-                    add_route({**route_kwargs, "endpoint": openapi_endpoint(muxws_routes)}, {MUXWS})
+                    add_route({**route_kwargs, "endpoint": openapi_endpoint(muxws_routes)}, {MUXWS}, action_name)
                 continue
 
             on_muxws = resolve_register_muxws(route.endpoint, register_muxws)
@@ -426,7 +444,7 @@ def route_viewset(
                 transports.add(MUXWS)
                 muxws_routes.append(route_kwargs)
             if transports:
-                add_route(route_kwargs, transports)
+                add_route(route_kwargs, transports, action_name)
 
         # Checked here rather than in the decorator, which runs before any route exists. A name
         # that matches nothing would otherwise leave that endpoint on the mixin's generic
@@ -441,7 +459,13 @@ def route_viewset(
         if muxws_routes:
             register_viewset(cls, base_path, muxws_routes, default_tags)
 
-        cls.__viewset_metadata__ = {"base_path": base_path, "lifecycle": lifecycle, "router": router}
+        cls.__viewset_metadata__ = {
+            "base_path": base_path,
+            "lifecycle": lifecycle,
+            "router": router,
+            "pk_field_name": pk_field_name,
+            "paths": paths,
+        }
 
         return cls
 

dynamicforms_fastapi_viewsets-0.9.1/fastapi_viewsets/events/__init__.py

@@ -0,0 +1,92 @@
+"""
+Events: the backend publishes an event to a topic, and every frontend following the topic learns of
+it, as a push over its muxws socket or on its next poll.
+
+    from fastapi_viewsets.events import Event, source
+
+    class ImportFinished(Event):
+        event_name = "import_finished"
+
+        file: str
+        rows: int
+
+    imports = source("imports")
+
+    await imports.publish(ImportFinished(file="members.csv", rows=412), key="7")   # topic "imports:7"
+
+Every event is recorded in the store (`settings.viewsets_event_store`) before it is pushed. The
+application calls `start_events()` and `stop_events()` from its lifespan.
+"""
+
+from .authorizers import (
+    allow_all,
+    allow_authenticated,
+    authorize_topic,
+    DeclaredSources,
+    EventAuthorizer,
+    ViewsetTopics,
+)
+from .changes import Change, ChangeEvents, RecordsChanged, routed_base_path, TOPIC_CONTEXT_KEY
+from .delivery import (
+    deliver,
+    DeliveryFilter,
+    drop_peer,
+    reset_subscriptions,
+    subscribe,
+    Subscription,
+    subscriptions,
+    topics_of,
+    unsubscribe,
+    wait_for_pushes,
+)
+from .event import Event
+from .lifecycle import check_events, start_events, stop_events
+from .sources import declared_source, publish, reset_sources, Source, source
+from .store import EventStore, get_store, LoggedEvent, MAX_REV, MemoryEventStore
+from .topics import is_valid_topic, is_viewset_topic, SOURCE_NAME_PATTERN, split_custom_topic, validate_topic
+from .viewset import EventsViewSet, register_events
+
+__all__ = [
+    "MAX_REV",
+    "SOURCE_NAME_PATTERN",
+    "TOPIC_CONTEXT_KEY",
+    "Change",
+    "ChangeEvents",
+    "DeclaredSources",
+    "DeliveryFilter",
+    "Event",
+    "EventAuthorizer",
+    "EventStore",
+    "EventsViewSet",
+    "LoggedEvent",
+    "MemoryEventStore",
+    "RecordsChanged",
+    "Source",
+    "Subscription",
+    "ViewsetTopics",
+    "allow_all",
+    "allow_authenticated",
+    "authorize_topic",
+    "check_events",
+    "declared_source",
+    "deliver",
+    "drop_peer",
+    "get_store",
+    "is_valid_topic",
+    "is_viewset_topic",
+    "publish",
+    "register_events",
+    "reset_sources",
+    "reset_subscriptions",
+    "routed_base_path",
+    "source",
+    "split_custom_topic",
+    "start_events",
+    "stop_events",
+    "subscribe",
+    "subscriptions",
+    "topics_of",
+    "unsubscribe",
+    "validate_topic",
+    "wait_for_pushes",
+]

dynamicforms_fastapi_viewsets-0.9.1/fastapi_viewsets/events/authorizers.py

@@ -0,0 +1,252 @@
+"""
+The functions that decide whether a caller may follow a topic, and the authorizers shipped with the
+package. `settings.viewsets_event_authorizers` lists the ones an application uses:
+
+    settings.viewsets_event_authorizers = [ViewsetTopics(), DeclaredSources()]
+"""
+
+import inspect
+
+from collections.abc import Awaitable, Callable, Iterator
+from contextlib import AsyncExitStack
+from dataclasses import dataclass
+from typing import Any
+
+from fastapi import Request
+from fastapi.dependencies.models import Dependant
+from fastapi.dependencies.utils import get_parameterless_sub_dependant, solve_dependencies
+from starlette.routing import compile_path
+
+from ..action_configuration import extra_middlewares_for, resolve_action_configuration
+from ..conf import settings
+from ..context import Context
+from ..decorators.route_viewset import MIDDLEWARE_DEPENDS_ATTRIBUTE
+from ..exceptions import EventTopicRefusedError
+from ..middleware import Middleware
+from .sources import declared_source
+from .topics import is_viewset_topic, split_custom_topic
+
+EventAuthorizer = Callable[[Request, Context, str], Awaitable[bool | None]]
+"""
+`await authorizer(request, context, topic)`: True admits the topic, False refuses it, None leaves
+the decision to the next authorizer in `settings.viewsets_event_authorizers`. An `HTTPException` it
+raises refuses the topic with that exception.
+"""
+
+
+async def authorize_topic(request: Request, context: Context, topic: str) -> None:
+    """
+    Runs `settings.viewsets_event_authorizers` in list order for `topic` and returns when one
+    admits it. The first True admits the topic; the first False, or no decision at all, raises
+    `EventTopicRefusedError` (403). An exception an authorizer raises, an `HTTPException` included,
+    propagates and the authorizers after it do not run. An authorizer may also return its decision
+    without an awaitable.
+    """
+    for authorizer in settings.viewsets_event_authorizers:
+        decision = authorizer(request, context, topic)
+        if inspect.isawaitable(decision):
+            decision = await decision
+        if decision is None:
+            continue
+        if decision:
+            return
+        break
+    raise EventTopicRefusedError(topic)
+
+
+async def allow_all(_request: Request, _context: Context, _topic: str) -> bool:
+    """Admits every topic."""
+    return True
+
+
+async def allow_authenticated(_request: Request, context: Context, _topic: str) -> bool | None:
+    """Admits a topic when `await context.user` is truthy; None otherwise, and for a context without
+    `user`."""
+    if "user" not in context:
+        return None
+    return True if await context.user else None
+
+
+class DeclaredSources:
+    """
+    Admits a custom topic through the `authorizer` of the source that declared its name: the answer
+    is that authorizer's. A viewset topic, a name no source declared, and a source declared without
+    an authorizer get None.
+    """
+
+    async def __call__(self, request: Request, context: Context, topic: str) -> bool | None:
+        parts = split_custom_topic(topic)
+        if parts is None:
+            return None
+        declared = declared_source(parts[0])
+        if declared is None or declared.authorizer is None:
+            return None
+        decision = declared.authorizer(request, context, topic)
+        if inspect.isawaitable(decision):
+            decision = await decision
+        return decision
+
+    def __repr__(self) -> str:
+        return "DeclaredSources()"
+
+
+def _routes(app: Any) -> Iterator[Any]:
+    """Every route of `app` with every `include_router` prefix and dependency applied: its `path`,
+    `endpoint` and `dependencies` are those the application serves the route with."""
+    try:
+        from fastapi.routing import iter_route_contexts
+    except ImportError:  # a FastAPI whose include_router copies the routes, prefixed, onto the app
+        yield from app.routes
+        return
+    yield from iter_route_contexts(app.routes)
+
+
+def _gate_action(cls: type) -> str | None:
+    """The action whose admission admits a caller to `cls`'s topic: `list_items`, else `retrieve`."""
+    paths = getattr(cls, "__viewset_metadata__", {}).get("paths", {})
+    for action in ("list_items", "retrieve"):
+        if action in paths:
+            return action
+    return None
+
+
+@dataclass(frozen=True)
+class ViewsetMatch:
+    """The viewset a topic belongs to, as `match_viewset` finds it."""
+
+    viewset_class: type
+    action: str
+    """`list_items`, or `retrieve` for a class without `list_items`."""
+    route: Any
+    """The application's route of `action`."""
+    path_params: dict[str, Any]
+    """The values of the path parameters of the routed base path, read from the topic and converted
+    as Starlette converts them for a request."""
+
+
+def match_viewset(app: Any, topic: str) -> ViewsetMatch | None:
+    """
+    The first route of `app`, in routing order, whose endpoint carries `__viewset_class__` and, as
+    `__viewset_action__`, the class's `list_items`, or `retrieve` for a class without `list_items`,
+    and whose path without that action's path in `__viewset_metadata__["paths"]` matches `topic`
+    as Starlette matches a request path, path parameters included: `/clubs/{club_id}/tracks`
+    matches the topic `/clubs/7/tracks`. None when no route matches.
+    """
+    for route in _routes(app):
+        endpoint = getattr(route, "endpoint", None)
+        cls = getattr(endpoint, "__viewset_class__", None)
+        path = getattr(route, "path", None)
+        if cls is None or not isinstance(path, str):
+            continue
+        action = _gate_action(cls)
+        if action is None or getattr(endpoint, "__viewset_action__", None) != action:
+            continue
+        relative = cls.__viewset_metadata__["paths"][action]
+        if not path.endswith(relative):
+            continue
+        regex, _format, convertors = compile_path(path[: len(path) - len(relative)] if relative else path)
+        matched = regex.match(topic)
+        if matched is None:
+            continue
+        params = {name: convertors[name].convert(value) for name, value in matched.groupdict().items()}
+        return ViewsetMatch(cls, action, route, params)
+    return None
+
+
+def find_viewset(app: Any, topic: str) -> tuple[type, str] | None:
+    """`(viewset class, action)` of `match_viewset(app, topic)`, or None."""
+    found = match_viewset(app, topic)
+    return (found.viewset_class, found.action) if found is not None else None
+
+
+def _with_path_params(request: Request, path_params: dict[str, Any]) -> Request:
+    """`request`, or a copy of it whose `path_params` are `path_params` when there are any."""
+    if not path_params:
+        return request
+    return Request({**request.scope, "path_params": path_params}, request.receive)
+
+
+async def _route_dependencies_admit(request: Request, route: Any) -> bool:
+    """
+    Resolves the route's `dependencies` other than the one that runs `Middleware.depends()` (those of
+    the application, of `include_router`, of the `APIRouter` and of the route) against `request`,
+    as FastAPI resolves them before the endpoint, honouring `app.dependency_overrides`. False when a
+    parameter of one does not validate; an exception one raises propagates.
+    """
+    dependencies = [
+        depends
+        for depends in getattr(route, "dependencies", None) or ()
+        if not getattr(depends.dependency, MIDDLEWARE_DEPENDS_ATTRIBUTE, False)
+    ]
+    if not dependencies:
+        return True
+    path = getattr(route, "path_format", None) or route.path
+    dependant = Dependant(
+        path=path,
+        dependencies=[get_parameterless_sub_dependant(depends=depends, path=path) for depends in dependencies],
+    )
+    accepted = inspect.signature(solve_dependencies).parameters
+    async with AsyncExitStack() as stack:
+        scope = {
+            **request.scope,
+            "fastapi_astack": stack,
+            "fastapi_inner_astack": stack,
+            "fastapi_function_astack": stack,
+        }
+        arguments: dict[str, Any] = {
+            "request": Request(scope, request.receive),
+            "dependant": dependant,
+            "dependency_overrides_provider": getattr(route, "dependency_overrides_provider", None),
+        }
+        if "async_exit_stack" in accepted:
+            arguments["async_exit_stack"] = stack
+        if "embed_body_fields" in accepted:
+            arguments["embed_body_fields"] = False
+        solved = await solve_dependencies(**arguments)
+    errors = solved.errors if hasattr(solved, "errors") else solved[1]
+    return not errors
+
+
+class ViewsetTopics:
+    """
+    Admits a viewset's topic to a caller the viewset itself admits to its `list_items`, or to its
+    `retrieve` when it has no `list_items`.
+
+    A topic that does not start with `/`, and a topic no viewset on `request.app` has, get None (see
+    `match_viewset`). For the viewset found, the checks a request to that action passes run against
+    the calling request, which carries the path parameters read from the topic as `path_params`:
+
+    1. the route's `dependencies` other than `route_viewset`'s own, those of the application, of
+       `include_router`, of the `APIRouter` and of the route itself; a parameter of one that does not
+       validate refuses the topic (False);
+    2. `depends()` of every effective middleware, with the viewset class and the calling context
+       rebound to the action's `@action_configuration`, `Context(context.raw(),
+       action_configuration=..., action_name=...)`: `settings.viewsets_command_middleware` followed
+       by the middleware instances the configuration adds.
+
+    An `HTTPException` propagates: `Session` raises 401, `Authorization` 403, `RateLimiter` 429 and
+    counts the call as one call of that action. When none raises, the topic is admitted.
+    """
+
+    async def __call__(self, request: Request, context: Context, topic: str) -> bool | None:
+        if not is_viewset_topic(topic):
+            return None
+        found = match_viewset(request.app, topic)
+        if found is None:
+            return None
+        cls, action = found.viewset_class, found.action
+        checked = _with_path_params(request, found.path_params)
+        if not await _route_dependencies_admit(checked, found.route):
+            return False
+        action_configuration = resolve_action_configuration(cls, action)
+        bound = Context(context.raw(), action_configuration=action_configuration, action_name=action)
+        middlewares = settings.viewsets_command_middleware + extra_middlewares_for(
+            action_configuration, settings.viewsets_command_middleware
+        )
+        for middleware in middlewares:
+            if isinstance(middleware, Middleware):
+                await middleware.depends(checked, cls, bound)
+        return True
+
+    def __repr__(self) -> str:
+        return "ViewsetTopics()"