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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dynamicforms-fastapi-viewsets
-Version: 0.8.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.3.1; 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.3.1; extra == 'muxws'
+Requires-Dist: muxws[starlette]>=0.4.1; extra == 'muxws'
 Description-Content-Type: text/markdown
 
 # DynamicForms FastAPI Viewsets
@@ -68,12 +68,14 @@ Celery-backed async execution and a matching Vue/TypeScript client counterpart.
   extra).
 - **Bulk operations** — first-class support for bulk create, update, partial update and destroy.
 - **muxws transport** — reach the same viewsets over a single WebSocket instead of one HTTP request
-  per call. A command is dispatched into an app built from the endpoints published on muxws, each
-  carrying the route kwargs REST is given, so validation, dependencies, response models and the
-  command middleware from `settings.viewsets_command_middleware` behave identically; that app is the
-  library's own, so what you attached anywhere but the endpoint itself sees a command only if you
-  pass your app to `process_command`. In the demo, a burst of 100 requests takes 156 ms over REST
-  and 37 ms over muxws.
+  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,
@@ -148,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.8.0 → dynamicforms_fastapi_viewsets-0.9.1}/README.md

@@ -17,12 +17,14 @@ Celery-backed async execution and a matching Vue/TypeScript client counterpart.
   extra).
 - **Bulk operations** — first-class support for bulk create, update, partial update and destroy.
 - **muxws transport** — reach the same viewsets over a single WebSocket instead of one HTTP request
-  per call. A command is dispatched into an app built from the endpoints published on muxws, each
-  carrying the route kwargs REST is given, so validation, dependencies, response models and the
-  command middleware from `settings.viewsets_command_middleware` behave identically; that app is the
-  library's own, so what you attached anywhere but the endpoint itself sees a command only if you
-  pass your app to `process_command`. In the demo, a burst of 100 requests takes 156 ms over REST
-  and 37 ms over muxws.
+  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,
@@ -97,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.8.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.1/fastapi_viewsets/conf.py

@@ -0,0 +1,117 @@
+import json
+
+from collections.abc import Awaitable, Callable
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from fastapi import Request
+    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]]]
+
+
+class Settings:
+    """
+    Global, mutable settings for fastapi_viewsets - configured once by the application, e.g.:
+
+        from fastapi_viewsets.conf import settings
+
+        async def auth_processor(request, viewset) -> dict:
+            return {"user": await authenticate(request)}
+
+        settings.viewsets_context_processors = [auth_processor]
+    """
+
+    def __init__(self):
+        self.viewsets_context_processors: list[ContextProcessor] = []
+        self.viewsets_context_json_encoder: type[json.JSONEncoder] | None = None
+        self.viewsets_context_json_decoder: type[json.JSONDecoder] | None = None
+        self.viewsets_command_middleware: list[CommandMiddleware] = []
+        self.viewsets_idempotency_ttl: float = 86400
+        """
+        Seconds an outcome recorded by `fastapi_viewsets.middleware.idempotency.Idempotency` is kept
+        after it was stored. A repeat after that runs the action again.
+        """
+        self.viewsets_idempotency_lock_ttl: float = 600
+        """
+        Seconds a running record of `Idempotency` is kept after it was written, unless the action
+        finishes first. Once it expires, a repeat runs the action again.
+        """
+        self.viewsets_auth_processors: list[AuthBackend] = []
+        self.default_action_configuration: dict[Any, Any] = {}
+        self.default_list_shape: str = "plain"
+        """
+        The shape a list endpoint answers in when the viewset does not say - "plain", "paginated"
+        or "cursor". An application that pages everything sets it once here instead of on every
+        viewset.
+        """
+        self.viewsets_register_muxws: bool = True
+        """
+        Whether a viewset is reachable over the muxws transport (see fastapi_viewsets/mux_ws/) when
+        it does not say either way itself. `route_viewset(register_muxws=...)` overrides this per
+        viewset, and `@transports(muxws=...)` overrides it again per endpoint - each
+        level only decides for the levels below it that left the question open (None). Read at
+        decoration time, so it must be set before any viewset class is decorated.
+        """
+        self.viewsets_security_scheme: SecurityBase | None = None
+        """
+        Purely for OpenAPI/Swagger discoverability (a lock icon + testable Authorize flow) - attached
+        as an extra sub-dependency alongside the per-route Middleware.depends() bridge (see
+        route_viewset.py), not otherwise consumed by this library. Must be set before any viewset
+        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.8.0 → dynamicforms_fastapi_viewsets-0.9.1}/fastapi_viewsets/decorators/__init__.py

@@ -2,8 +2,6 @@ from .celery_viewset import (
     celery_viewset,
     celery_viewset_client,
     celery_viewset_server,
-    set_celery_dispatch_hook,
-    set_celery_kwargs_hook,
     set_is_celery_worker,
 )
 from .route_viewset import route_viewset
@@ -13,7 +11,5 @@ __all__ = [
     "celery_viewset_client",
     "celery_viewset_server",
     "route_viewset",
-    "set_celery_dispatch_hook",
-    "set_celery_kwargs_hook",
     "set_is_celery_worker",
 ]

{dynamicforms_fastapi_viewsets-0.8.0 → dynamicforms_fastapi_viewsets-0.9.1}/fastapi_viewsets/decorators/build_schema.py

@@ -151,9 +151,8 @@ def build_schema(cls, base_path: str = "", default_tags=None, get_wrapper=None,
         def schema():
             return app.openapi()
 
-        # Marks this route as the framework's own /schema endpoint. The muxws transport has to
-        # skip it and substitute its own (which reports the muxws endpoint set, not this one) -
-        # see fastapi_viewsets/mux_ws/registry.py.
+        # Marks this route as the framework's own /schema endpoint. route_viewset replaces it with
+        # one /schema route per transport, each reporting the endpoints published on that transport.
         schema.__viewset_schema_endpoint__ = True
 
         schema_route_kwargs = dict(

{dynamicforms_fastapi_viewsets-0.8.0 → dynamicforms_fastapi_viewsets-0.9.1}/fastapi_viewsets/decorators/celery_viewset/__init__.py

@@ -6,7 +6,6 @@ from .client import (
     celery_viewset_client,
     DEFAULT_RESULT_TIMEOUT,
     get_registered_queue_keys,
-    set_celery_dispatch_hook,
 )
 from .result_reader import (
     get_process_queue_key,
@@ -16,7 +15,7 @@ from .result_reader import (
     start_result_reader,
     stop_result_reader,
 )
-from .server import celery_viewset_server, set_celery_kwargs_hook
+from .server import celery_viewset_server
 
 logger = logging.getLogger(__name__)
 
@@ -92,8 +91,6 @@ __all__ = [
     "celery_viewset_server",
     "DEFAULT_RESULT_TIMEOUT",
     "set_is_celery_worker",
-    "set_celery_kwargs_hook",
-    "set_celery_dispatch_hook",
     "start_result_reader",
     "stop_result_reader",
     "check_result_readers",

{dynamicforms_fastapi_viewsets-0.8.0 → dynamicforms_fastapi_viewsets-0.9.1}/fastapi_viewsets/decorators/celery_viewset/client.py

@@ -1,18 +1,20 @@
 import asyncio
+import inspect
 import logging
 import uuid
 
-from collections.abc import Awaitable, Callable
 from functools import wraps
 from typing import TYPE_CHECKING, TypeVar
 
 from pydantic import BaseModel
 
 from ...context import Context, SerializableObject, serialize_context, to_jsonable
-from ...exceptions import ResultTimeoutError
+from ...exceptions import ActionDispatchError, ResultTimeoutError
 from ..build_schema import build_schema
+from ..lifecycle_runner import current_call, DEFERRED_ACTIONS_ATTRIBUTE
 from ..primary_key_model_helper import PARTIAL_UPDATE_ACTIONS
 from . import result_reader
+from .payload import CONTEXT_KWARG, PARENT_KWARG, REQUEST_KWARG, request_to_jsonable
 from .result_reader import get_process_queue_key, get_result_queue_key
 
 if TYPE_CHECKING:
@@ -25,20 +27,6 @@ logger = logging.getLogger(__name__)
 
 DEFAULT_RESULT_TIMEOUT = 3600.0
 
-_celery_dispatch_hook: Callable[[dict], Awaitable[dict]] | None = None
-
-
-def set_celery_dispatch_hook(hook: Callable[[dict], Awaitable[dict]] | None) -> None:
-    """Register a callable awaited just before send_task; its return dict is merged into kwargs.
-
-    Receives the call's current kwargs (context included, if the action declares one) so a
-    registered hook can read what a context processor already put there instead of needing its own
-    request-level plumbing. Returns {} when there is nothing to add.
-    """
-    global _celery_dispatch_hook
-    _celery_dispatch_hook = hook
-
-
 # queue_keys registered by celery_viewset_client so far - populated at decoration (import) time,
 # used by check_result_readers() to spot a queue_key with no running result reader.
 _registered_queue_keys: set[str] = set()
@@ -111,8 +99,13 @@ async def _serialize_value(value, partial: bool = False):
 def _patch_method(
     cls: type, original_endpoint, task_name: str, celery_app, queue_key: str, result_timeout: float | None
 ):
-    """Replace the method on cls with an async version that sends a Celery task and awaits the result."""
+    """Replace the method on cls with an async version that sends a Celery task and awaits the result.
+
+    The task carries the call's context, request and parent execution (see `payload`) from
+    `current_call()`; a `context` the caller passes replaces the call's. A send that fails raises
+    `ActionDispatchError`. The action's name joins the class's `DEFERRED_ACTIONS_ATTRIBUTE`."""
     method_name = original_endpoint.__name__
+    declares_request = "request" in inspect.signature(original_endpoint).parameters
 
     @wraps(original_endpoint)
     async def async_client_wrapper(_self, *args, **kwargs):
@@ -122,32 +115,41 @@ def _patch_method(
         result_reader.register_future(correlation_id, future, queue_key)
 
         try:
+            call = current_call()
+            context = kwargs.pop("context", None)
+            if context is None:
+                context = call.context if call is not None else Context({})
+            if declares_request:
+                kwargs.pop("request", None)
+            parent = call.parent_of_dispatch() if call is not None else None
             serializable_args = [await _serialize_value(v) for v in args]
-            serializable_kwargs = {}
-            for k, v in kwargs.items():
-                if k == "context":
-                    serializable_kwargs[k] = await serialize_context(v.raw())
-                else:
-                    serializable_kwargs[k] = await _serialize_value(v, method_name in PARTIAL_UPDATE_ACTIONS)
+            serializable_kwargs = {
+                k: await _serialize_value(v, method_name in PARTIAL_UPDATE_ACTIONS) for k, v in kwargs.items()
+            }
             logger.info("Celery task scheduling: %s (correlation_id=%s)", task_name, correlation_id)
-            extra_kwargs = await _celery_dispatch_hook(kwargs) if _celery_dispatch_hook is not None else {}
-            # send_task() blocks while it connects and publishes to the broker.
-            await asyncio.to_thread(
-                celery_app.send_task,
-                task_name,
-                args=serializable_args,
-                kwargs={
-                    **serializable_kwargs,
-                    "_correlation_id": correlation_id,
-                    "_result_queue_key": get_process_queue_key(queue_key),
-                    **extra_kwargs,
-                },
-                # send_task() defaults ignore_result to False regardless of what the task was
-                # registered with (celery_viewset_server sets ignore_result=True) - Celery's
-                # per-request value overrides the task's own, so it must be repeated here or the
-                # worker still tries to JSON-encode the raw return value into its result backend.
-                ignore_result=True,
-            )
+            try:
+                # send_task() blocks while it connects and publishes to the broker.
+                await asyncio.to_thread(
+                    celery_app.send_task,
+                    task_name,
+                    args=serializable_args,
+                    kwargs={
+                        **serializable_kwargs,
+                        CONTEXT_KWARG: await serialize_context(context.raw()),
+                        REQUEST_KWARG: request_to_jsonable(call.request if call is not None else None),
+                        PARENT_KWARG: parent.to_jsonable() if parent is not None else None,
+                        "_correlation_id": correlation_id,
+                        "_result_queue_key": get_process_queue_key(queue_key),
+                    },
+                    # send_task() defaults ignore_result to False regardless of what the task was
+                    # registered with (celery_viewset_server sets ignore_result=True) - Celery's
+                    # per-request value overrides the task's own, so it must be repeated here or the
+                    # worker still tries to JSON-encode the raw return value into its result backend.
+                    ignore_result=True,
+                )
+            except Exception as error:
+                logger.error("Celery task not sent: %s (correlation_id=%s)", task_name, correlation_id)
+                raise ActionDispatchError(task_name) from error
             try:
                 return await asyncio.wait_for(future, result_timeout)
             except asyncio.TimeoutError:
@@ -157,3 +159,4 @@ def _patch_method(
             result_reader.unregister_future(correlation_id)
 
     setattr(cls, method_name, async_client_wrapper)
+    setattr(cls, DEFERRED_ACTIONS_ATTRIBUTE, frozenset(getattr(cls, DEFERRED_ACTIONS_ATTRIBUTE, ())) | {method_name})

dynamicforms_fastapi_viewsets-0.9.1/fastapi_viewsets/decorators/celery_viewset/payload.py

@@ -0,0 +1,56 @@
+"""
+The call data a `celery_viewset` task carries beside the action's own arguments: the call's context,
+its request and the execution it was dispatched in. `celery_viewset_client` writes them under the
+reserved kwargs below, and `celery_viewset_server` consumes them before the action is called.
+"""
+
+from typing import Any
+
+from fastapi import Request
+from fastapi.encoders import jsonable_encoder
+
+CONTEXT_KWARG = "_context"
+"""The call's context, as `serialize_context` encodes it."""
+REQUEST_KWARG = "_request"
+"""The call's request, as `request_to_jsonable` encodes it; None without one."""
+PARENT_KWARG = "_parent"
+"""The `ExecutionRef` the call was dispatched in, as `ExecutionRef.to_jsonable` encodes it; None
+for a call a request made."""
+
+
+def _address(value: Any) -> list | None:
+    return list(value) if value is not None else None
+
+
+def request_to_jsonable(request: Request | None) -> dict[str, Any] | None:
+    """The ASGI scope of `request` without its body, `app` and `state`, JSON-safe."""
+    if request is None:
+        return None
+    scope = request.scope
+    return {
+        "type": scope.get("type", "http"),
+        "http_version": scope.get("http_version", "1.1"),
+        "method": scope.get("method", "GET"),
+        "scheme": scope.get("scheme", "http"),
+        "path": scope.get("path", ""),
+        "root_path": scope.get("root_path", ""),
+        "query_string": scope.get("query_string", b"").decode("latin-1"),
+        "headers": [[name.decode("latin-1"), value.decode("latin-1")] for name, value in scope.get("headers", [])],
+        "path_params": jsonable_encoder(scope.get("path_params", {})),
+        "client": _address(scope.get("client")),
+        "server": _address(scope.get("server")),
+    }
+
+
+def request_from_jsonable(data: dict[str, Any] | None) -> Request | None:
+    """A `Request` over the scope `request_to_jsonable` encoded. Reading its body raises."""
+    if data is None:
+        return None
+    scope = {
+        **data,
+        "query_string": data["query_string"].encode("latin-1"),
+        "headers": [(name.encode("latin-1"), value.encode("latin-1")) for name, value in data["headers"]],
+        "client": tuple(data["client"]) if data["client"] is not None else None,
+        "server": tuple(data["server"]) if data["server"] is not None else None,
+    }
+    return Request(scope)

{dynamicforms_fastapi_viewsets-0.8.0 → dynamicforms_fastapi_viewsets-0.9.1}/fastapi_viewsets/decorators/celery_viewset/server.py

@@ -1,12 +1,12 @@
 import asyncio
+import contextlib
 import functools
 import inspect
 import logging
 import types
 
-from collections.abc import Callable
 from functools import wraps
-from typing import get_args, get_origin, get_type_hints, TYPE_CHECKING, TypeVar, Union
+from typing import Any, get_args, get_origin, get_type_hints, TYPE_CHECKING, TypeVar, Union
 
 from fastapi import HTTPException
 from fastapi.encoders import jsonable_encoder
@@ -14,6 +14,7 @@ from fastapi.exceptions import RequestValidationError
 from pydantic import BaseModel, TypeAdapter, ValidationError
 
 from ...context import Context, deserialize_context, to_jsonable
+from ...middleware import ExecutionRef
 from ..build_schema import build_schema
 from ..lifecycle_runner import lifecycle_runner, LifecycleType
 from ..primary_key_model_helper import (
@@ -24,6 +25,7 @@ from ..primary_key_model_helper import (
     typecast_to_original_model,
 )
 from ..route_viewset import build_type_map, resolve_typevars
+from .payload import CONTEXT_KWARG, PARENT_KWARG, request_from_jsonable, REQUEST_KWARG
 from .result_reader import push_payload
 
 if TYPE_CHECKING:
@@ -35,19 +37,6 @@ logger = logging.getLogger(__name__)
 
 T = TypeVar("T")
 
-_celery_kwargs_hook: Callable[[Callable, dict], tuple[Callable, dict]] | None = None
-
-
-def set_celery_kwargs_hook(hook: Callable[[Callable, dict], tuple[Callable, dict]] | None) -> None:
-    """Register a callable that may wrap the runner and/or consume kwargs before reconstruction.
-
-    Receives (runner, kwargs), must return (runner, kwargs). Called with kwargs still raw - before
-    _reconstruct_kwargs, which passes through any key it has no type hint for, so a key the hook
-    does not consume would otherwise reach the action as an argument it never declared.
-    """
-    global _celery_kwargs_hook
-    _celery_kwargs_hook = hook
-
 
 def _unwrap_optional(hint):
     """Before Python 3.11, `get_type_hints()` implicitly wraps a None-defaulted parameter's
@@ -119,17 +108,11 @@ _model_without_pk = functools.lru_cache(create_model_without_pk)
 def _reconstruct_kwargs(original_endpoint, kwargs: dict, cls: type = None) -> dict:
     """Reconstruct dict values back into Pydantic BaseModel instances based on endpoint type hints.
 
-    `context` is handled unconditionally (by name, not by type hint) via deserialize_context - see
-    fastapi_viewsets/context - since its declared type is a plain Context and its actual values
-    may need SerializableObject-aware reconstruction.
+    The call's context, request and parent arrive under the reserved kwargs of `payload`, which the
+    task consumes before this runs.
     """
     result = {}
-    remaining = {}
-    for key, value in kwargs.items():
-        if key == "context" and isinstance(value, dict):
-            result[key] = Context(deserialize_context(value))
-        else:
-            remaining[key] = value
+    remaining = dict(kwargs)
 
     try:
         hints = get_type_hints(original_endpoint)
@@ -154,6 +137,22 @@ def _reconstruct_kwargs(original_endpoint, kwargs: dict, cls: type = None) -> di
     return result
 
 
+def _run_to_end(loop: asyncio.AbstractEventLoop, coroutine) -> Any:
+    """Runs `coroutine` on `loop` as a task and returns its result. An exception that interrupts the
+    loop while the task is suspended (Celery's time limit, raised from a signal handler) cancels the
+    task and runs it until it has unwound, so its `finally` blocks and `Middleware.execute()` see the
+    interruption; the exception is then raised."""
+    task = loop.create_task(coroutine)
+    try:
+        return loop.run_until_complete(task)
+    except BaseException:
+        if not task.done():
+            task.cancel()
+            with contextlib.suppress(BaseException):  # the interruption is what propagates
+                loop.run_until_complete(task)
+        raise
+
+
 def celery_viewset_server(
     celery_app: "Celery",
     task_prefix: str,
@@ -165,6 +164,8 @@ def celery_viewset_server(
         instance = cls() if lifecycle == "singleton" else None
 
         def get_sync_wrapper(original_endpoint, task_name: str):
+            parameters = inspect.signature(original_endpoint).parameters
+
             @wraps(original_endpoint)
             def sync_wrapper(*args, **kwargs):
                 nonlocal instance
@@ -186,11 +187,26 @@ def celery_viewset_server(
 
                 logger.info("Celery task executing: %s (correlation_id=%s)", task_name, correlation_id)
                 try:
-                    run = loop.run_until_complete
-                    if _celery_kwargs_hook is not None:
-                        run, kwargs = _celery_kwargs_hook(run, kwargs)
+                    context = Context(deserialize_context(kwargs.pop(CONTEXT_KWARG, None) or {}))
+                    request = request_from_jsonable(kwargs.pop(REQUEST_KWARG, None))
+                    parent = ExecutionRef.from_jsonable(kwargs.pop(PARENT_KWARG, None))
                     kwargs = _reconstruct_kwargs(original_endpoint, kwargs, cls)
-                    result = run(lifecycle_runner(original_endpoint, instance, cls, lifecycle, *args, **kwargs))
+                    result = _run_to_end(
+                        loop,
+                        lifecycle_runner(
+                            original_endpoint,
+                            instance,
+                            cls,
+                            lifecycle,
+                            *args,
+                            needs_context="context" in parameters,
+                            request=request,
+                            forwards_request="request" in parameters,
+                            context=context,
+                            parent=parent,
+                            **kwargs,
+                        ),
+                    )
                     logger.info("Celery task completed: %s (correlation_id=%s)", task_name, correlation_id)
                     if correlation_id and result_queue_key and redis_client is not None:
                         push_payload(