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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dynamicforms-fastapi-viewsets
-Version: 0.8.0
+Version: 0.9.0
 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
@@ -34,7 +34,7 @@ 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: muxws[starlette,websockets]>=0.4.0; 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.0; extra == 'muxws'
 Description-Content-Type: text/markdown
 
 # DynamicForms FastAPI Viewsets
@@ -68,12 +68,9 @@ 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.
 - **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,

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

@@ -17,12 +17,9 @@ 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.
 - **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,

dynamicforms_fastapi_viewsets-0.9.0/fastapi_viewsets/__init__.py

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

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

@@ -30,6 +30,16 @@ class Settings:
         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"

{dynamicforms_fastapi_viewsets-0.8.0 → dynamicforms_fastapi_viewsets-0.9.0}/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.0}/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.0}/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.0}/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.0/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.0}/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(

dynamicforms_fastapi_viewsets-0.9.0/fastapi_viewsets/decorators/lifecycle_runner.py

@@ -0,0 +1,173 @@
+import functools
+
+from collections.abc import Callable
+from contextvars import ContextVar
+from dataclasses import dataclass
+from typing import Any, Literal, TYPE_CHECKING, TypeVar
+
+from ..action_configuration import extra_middlewares_for, resolve_action_configuration
+from ..conf import settings
+from ..context import Context, get_shared_context
+from ..middleware import ActionExecution, ExecutionRef, run_command_chain, run_execution_chain, ViewSetResult
+
+if TYPE_CHECKING:
+    from fastapi import Request
+
+T = TypeVar("T")
+
+LifecycleType = Literal["singleton", "per-request", "instance-key"]
+
+DEFERRED_ACTIONS_ATTRIBUTE = "__viewset_deferred_actions__"
+"""
+The class attribute holding the names of the actions whose method on that class hands the call to
+an executor instead of executing it (`celery_viewset_client` sets it). `lifecycle_runner` runs no
+`Middleware.execute()` around such a method, its override in a subclass included; the executor's
+`lifecycle_runner` runs it around the real execution.
+"""
+
+
+@dataclass(frozen=True)
+class CurrentCall:
+    """The call `lifecycle_runner` is running in this task, for a method that hands it on."""
+
+    context: Context
+    request: "Request | None"
+    execution: ActionExecution | None
+    """Set while the action executes in this process; None while a deferred action hands it on."""
+    parent: ExecutionRef | None
+
+    def parent_of_dispatch(self) -> ExecutionRef | None:
+        """The `parent` of an action handed to an executor now: this execution when one runs, else
+        this call's own parent (the deferred method handing its own call on)."""
+        return self.execution.ref() if self.execution is not None else self.parent
+
+
+_current_call: ContextVar[CurrentCall | None] = ContextVar("viewsets_current_call", default=None)
+
+
+def current_call() -> CurrentCall | None:
+    """The call `lifecycle_runner` is running in this task; None outside any call."""
+    return _current_call.get()
+
+
+def effective_middlewares(action_configuration: dict) -> list:
+    return settings.viewsets_command_middleware + extra_middlewares_for(
+        action_configuration, settings.viewsets_command_middleware
+    )
+
+
+async def lifecycle_runner(
+    original_endpoint: Callable,
+    singleton_instance: T,
+    cls: type[T],
+    lifecycle: LifecycleType = "singleton",
+    *args,
+    response: Any = None,
+    needs_context: bool = False,
+    request: "Request | None" = None,
+    forwards_request: bool = False,
+    context: Context | None = None,
+    parent: ExecutionRef | None = None,
+    **kwargs,
+):
+    """
+    `response` is reserved for the command middleware chain (see below) - callers that have no
+    live Response object (e.g. `celery_viewset_server`, running in a worker process) simply omit
+    it, and the chain is never invoked - the worker just executes the action and returns the plain
+    result; command middleware only ever runs once that result is back in the FastAPI process.
+
+    `context` is the call's data when the caller already has it (`celery_viewset_server`, from the
+    task payload); without it a Context is built via settings.viewsets_context_processors against
+    whichever instance ends up handling this lifecycle. Either way it is bound to this action's
+    configuration and is the context the middleware chains read. `needs_context` injects it into
+    kwargs as `context`, for a method declaring that parameter. `forwards_request` passes `request`
+    on to a method that declares a `request` parameter. `parent` is the execution in which the call
+    was dispatched.
+
+    `Middleware.execute()` of the effective middlewares runs around the method call itself, unless
+    the action is deferred on `cls` (`DEFERRED_ACTIONS_ATTRIBUTE`). While the method runs, the call
+    is readable through `current_call()`.
+    """
+
+    if forwards_request:
+        kwargs["request"] = request
+
+    action = original_endpoint.__name__
+    action_configuration: dict = {}
+    chain_context: Context | None = None
+
+    async def inject_context(req_instance: Any) -> None:
+        nonlocal action_configuration, chain_context
+        action_configuration = resolve_action_configuration(cls, action)
+        if context is None:
+            chain_context = await get_shared_context(request, req_instance, action_configuration, action)
+        else:
+            chain_context = Context(context.raw(), action_configuration=action_configuration, action_name=action)
+        if needs_context:
+            kwargs["context"] = chain_context
+
+    async def call_bound(req_instance: Any) -> Any:
+        bound_method = getattr(req_instance, action, None)
+        method = bound_method if bound_method is not None else functools.partial(original_endpoint, req_instance)
+        if action in getattr(cls, DEFERRED_ACTIONS_ATTRIBUTE, ()):
+            marker = _current_call.set(CurrentCall(chain_context, request, None, parent))
+            try:
+                return await method(*args, **kwargs)
+            finally:
+                _current_call.reset(marker)
+        execution = ActionExecution(cls, req_instance, action, args, dict(kwargs), chain_context, request, parent)
+        marker = _current_call.set(CurrentCall(chain_context, request, execution, parent))
+        try:
+            return await run_execution_chain(
+                effective_middlewares(action_configuration), execution, lambda: method(*args, **kwargs)
+            )
+        finally:
+            _current_call.reset(marker)
+
+    async def execute(req_instance: Any) -> Any:
+        if response is None:
+            # Worker-only (celery_viewset_server) invocation - no live Response to shape, so the
+            # command middleware chain (whose whole job is producing/mutating response-level side
+            # effects) never runs here; just execute and return the plain result.
+            return await call_bound(req_instance)
+
+        async def final_handler() -> ViewSetResult:
+            raw = await call_bound(req_instance)
+            # An endpoint may return a ViewSetResult directly (see ViewSetResult in
+            # fastapi_viewsets/middleware) to reach status_code/headers/cookies itself - passed
+            # through as-is.
+            return raw if isinstance(raw, ViewSetResult) else ViewSetResult(body=raw)
+
+        result = await run_command_chain(
+            effective_middlewares(action_configuration), request, req_instance, chain_context, final_handler
+        )
+        for key, value in result.headers.items():
+            response.headers[key] = str(value)
+        for key, value in result.cookies.items():
+            response.set_cookie(key, str(value))
+        if result.status_code is not None:
+            response.status_code = result.status_code
+        return result.body
+
+    async def run_with_state(req_instance: Any) -> Any:
+        if hasattr(req_instance, "load_state"):
+            await req_instance.load_state()
+
+        try:
+            await inject_context(req_instance)
+            return await execute(req_instance)
+        finally:
+            if hasattr(req_instance, "save_state"):
+                await req_instance.save_state()
+
+    if lifecycle == "singleton":
+        return await run_with_state(singleton_instance)
+    elif lifecycle == "per-request":
+        req_instance = cls()
+        await inject_context(req_instance)
+        return await execute(req_instance)
+    elif lifecycle == "instance-key":
+        req_instance = cls()
+        return await run_with_state(req_instance)
+
+    raise ValueError(f"unknown lifecycle {lifecycle!r}; one of: singleton, per-request, instance-key")