dynamicforms-fastapi-viewsets 0.11.4__tar.gz → 0.12.0__tar.gz

{dynamicforms_fastapi_viewsets-0.11.4 → dynamicforms_fastapi_viewsets-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dynamicforms-fastapi-viewsets
-Version: 0.11.4
+Version: 0.12.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

dynamicforms_fastapi_viewsets-0.12.0/fastapi_viewsets/__init__.py

@@ -0,0 +1,5 @@
+__version__ = "0.12.0"
+
+from .error_namespace import ERROR_NAMESPACE, ERROR_NAMESPACE_PYDANTIC
+
+__all__ = ["ERROR_NAMESPACE", "ERROR_NAMESPACE_PYDANTIC", "__version__"]

{dynamicforms_fastapi_viewsets-0.11.4 → dynamicforms_fastapi_viewsets-0.12.0}/fastapi_viewsets/cursor.py

@@ -34,6 +34,7 @@ from typing import Any, ClassVar, Generic, TYPE_CHECKING
 from pydantic import BaseModel, TypeAdapter
 from typing_extensions import TypeVar
 
+from .error_namespace import _namespaced
 from .filters import Filter
 
 if TYPE_CHECKING:
@@ -43,7 +44,10 @@ TItem = TypeVar("TItem")
 
 
 class CursorError(ValueError):
-    """The cursor is unreadable, or does not belong to the query it was sent with."""
+    """
+    The cursor is unreadable, or does not belong to the query it was sent with. `code` is one of the
+    cursor codes, `fastapi-viewsets.cursor_<reason>`.
+    """
 
     def __init__(self, message: str, code: str, params: dict[str, Any] | None = None):
         super().__init__(message)
@@ -135,16 +139,16 @@ def decode_cursor(raw: str, keys: CursorKeys, expected_query: str, annotations:
         payload = json.loads(base64.urlsafe_b64decode(padded))
     except (ValueError, binascii.Error) as error:
         raise CursorError(
-            f"cursor is not readable: {error}", code="cursor_unreadable", params={"error": str(error)}
+            f"cursor is not readable: {error}", code=_namespaced("cursor_unreadable"), params={"error": str(error)}
         ) from None
 
     if not isinstance(payload, dict) or not isinstance(payload.get("p"), dict):
-        raise CursorError("cursor is not readable: no position in it", code="cursor_missing_position")
+        raise CursorError("cursor is not readable: no position in it", code=_namespaced("cursor_missing_position"))
 
     if payload.get("q") != expected_query:
         raise CursorError(
             "this cursor was issued for a different ordering or filter - start from the first page",
-            code="cursor_stale",
+            code=_namespaced("cursor_stale"),
         )
 
     position = payload["p"]
@@ -152,7 +156,7 @@ def decode_cursor(raw: str, keys: CursorKeys, expected_query: str, annotations:
     if missing:
         raise CursorError(
             f"cursor has no value for ordering key(s): {', '.join(missing)}",
-            code="cursor_missing_keys",
+            code=_namespaced("cursor_missing_keys"),
             params={"missing": missing},
         )
 
@@ -168,7 +172,7 @@ def decode_cursor(raw: str, keys: CursorKeys, expected_query: str, annotations:
         except Exception as error:
             raise CursorError(
                 f"cursor value for {name!r} does not fit the field: {error}",
-                code="cursor_value_mismatch",
+                code=_namespaced("cursor_value_mismatch"),
                 params={"name": name, "error": str(error)},
             ) from None
 

{dynamicforms_fastapi_viewsets-0.11.4 → dynamicforms_fastapi_viewsets-0.12.0}/fastapi_viewsets/decorators/celery_viewset/result_reader.py

@@ -136,9 +136,9 @@ def _payload_error(data: dict) -> Exception:
 def error_payload(correlation_id: str, task: str | None, error: BaseException) -> dict:
     """
     The payload that fails one call with `error`: an `HTTPException` (a `DfViewSetError` with its
-    class), a `RequestValidationError` as a 422 with its errors as `detail`, any other error as
-    `ActionFailedError`. `http_status_code` and `http_detail` repeat the status and detail for a
-    reader that does not decode `error`.
+    class), a `RequestValidationError` as a 422 with its errors as `detail` and `class`
+    `"RequestValidationError"`, any other error as `ActionFailedError`. `http_status_code` and
+    `http_detail` repeat the status and detail for a reader that does not decode `error`.
     """
     if not isinstance(error, (HTTPException, RequestValidationError)):
         error = ActionFailedError(task)
@@ -169,9 +169,10 @@ def push_result(
     """
     Push a result or an error for one call. queue_key is the `_result_queue_key` the client sent with
     the task. An `error` that is an `HTTPException` reaches the caller as it is (a `DfViewSetError`
-    of a class `fastapi_viewsets.exceptions` defines keeps its class); a `RequestValidationError`
-    reaches it as an `HTTPException` 422 with its errors as `detail`; any other error reaches it as
-    `ActionFailedError`. `task` names the call's task in that error.
+    of a class `fastapi_viewsets.exceptions` defines keeps its class), and so does a
+    `RequestValidationError`; any other error reaches it as `ActionFailedError`. `task` names the
+    call's task in that error. The FastAPI process answers each as `fastapi_viewsets.error_responses`
+    answers it.
     """
     if error is not None:
         data = error_payload(correlation_id, task, error)

{dynamicforms_fastapi_viewsets-0.11.4 → dynamicforms_fastapi_viewsets-0.12.0}/fastapi_viewsets/decorators/celery_viewset/server.py

@@ -20,7 +20,6 @@ from functools import wraps
 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
 from fastapi.exceptions import RequestValidationError
 from pydantic import BaseModel, TypeAdapter, ValidationError
 
@@ -666,14 +665,13 @@ def celery_viewset_server(
                 _report("interrupted", task_name, call, lambda t: ActionInterruptedError(t, "time_limit"))
                 raise pool_timeout
             error = run.translate(caught)
-            if isinstance(error, RequestValidationError):
-                # a request the worker found invalid (a filter value that will not convert) answers as
-                # FastAPI answers one: 422 with the errors as `detail`
-                error = HTTPException(status_code=422, detail=jsonable_encoder(error.errors()))
             process_exit = isinstance(error, (KeyboardInterrupt, SystemExit))
             if process_exit:
                 pushed = ActionInterruptedError(task_name, "terminated")
-            elif isinstance(error, HTTPException):
+            elif isinstance(error, (HTTPException, RequestValidationError)):
+                # a request the worker found invalid (a filter value that will not convert) is pushed as
+                # the `RequestValidationError` it is, and answered as a request the FastAPI process found
+                # invalid
                 pushed = error
             else:
                 pushed = ActionFailedError(task_name)
@@ -686,12 +684,15 @@ def celery_viewset_server(
                     exc_info=caught,
                 )
             else:
+                status, detail = (
+                    (pushed.status_code, pushed.detail) if isinstance(pushed, HTTPException) else (422, pushed.errors())
+                )
                 logger.info(
                     "Celery task returned standard error: %s (correlation_id=%s): %d: %s",
                     task_name,
                     correlation_id,
-                    pushed.status_code,
-                    pushed.detail,
+                    status,
+                    detail,
                 )
             if process_exit and not _supervised():
                 _report("interrupted", task_name, call, lambda _t: pushed)

{dynamicforms_fastapi_viewsets-0.11.4 → dynamicforms_fastapi_viewsets-0.12.0}/fastapi_viewsets/decorators/route_viewset.py

@@ -24,6 +24,7 @@ from fastapi_viewsets.endpoint_docs import (
 from fastapi_viewsets.middleware import any_modifies_response_shape, Middleware, unwrap_viewset_result_type
 from fastapi_viewsets.mixins import FilterParam
 from fastapi_viewsets.mux_ws import register_viewset, resolve_register_muxws, resolve_register_rest
+from fastapi_viewsets.response_classes import with_error_responses
 from fastapi_viewsets.routing import MUXWS, openapi_endpoint, REST, transport_route_class
 
 from .build_schema import _pydantic_generic_args, build_schema, route_to_add_api_route_kwargs
@@ -418,7 +419,9 @@ def route_viewset(
             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)
+            route_kwargs = route_to_add_api_route_kwargs(
+                route, dependencies=dependencies, responses=with_error_responses(route.responses)
+            )
             # Per-viewset wording for an endpoint the mixin provided - the mixin's own docstring is
             # the same sentence on every viewset in the application. See endpoint_docs.py.
             route_kwargs.update(docs_for(cls, action_name))

dynamicforms_fastapi_viewsets-0.12.0/fastapi_viewsets/error_namespace.py

@@ -0,0 +1,57 @@
+"""
+The namespaces of the error codes this package's errors carry.
+
+An error code is `<namespace>.<code>`: `code` is snake_case without `.`, `namespace` one or more
+segments of `[a-z0-9]+(-[a-z0-9]+)*` joined by `.`, and a full code splits at its last `.`. The
+codes this package declares are in `ERROR_NAMESPACE`. `ERROR_NAMESPACE_PYDANTIC` is the namespace
+of pydantic's error types, which the field errors of a `fastapi-viewsets.validation_failed` body carry
+as `pydantic.<type>`, and of `pydantic.custom_error`, the field error of a type pydantic does not
+declare. A code the application gives an error is used as given.
+"""
+
+ERROR_NAMESPACE = "fastapi-viewsets"
+"""The namespace of every error code this package declares, e.g. `fastapi-viewsets.not_found`."""
+
+ERROR_NAMESPACE_PYDANTIC = "pydantic"
+"""The namespace of pydantic's error types, e.g. `pydantic.string_too_short`."""
+
+_PREFIX = f"{ERROR_NAMESPACE}."
+
+_DECLARED_CODES = frozenset(
+    {
+        "not_found",
+        "read_only",
+        "session_expired",
+        "not_authorized",
+        "rate_limited",
+        "result_timeout",
+        "result_reader_stopped",
+        "action_dispatch_failed",
+        "action_interrupted",
+        "action_failed",
+        "idempotency_key_invalid",
+        "idempotency_key_reused",
+        "unsupported_list_shape",
+        "event_topic_invalid",
+        "event_topic_refused",
+        "event_scope_missing",
+        "event_subscriptions_exceeded",
+        "event_cursors_exceeded",
+        "cursor_unreadable",
+        "cursor_missing_position",
+        "cursor_stale",
+        "cursor_missing_keys",
+        "cursor_value_mismatch",
+        "validation_failed",
+        "http_error",
+        "unhandled_error",
+        "command_invalid",
+        "pk_assigned_by_server",
+    }
+)
+"""Every code this package declares, without the namespace; each is built with `_namespaced()`."""
+
+
+def _namespaced(code: str) -> str:
+    """The full code of `code`, an error code this package declares."""
+    return f"{_PREFIX}{code}"

dynamicforms_fastapi_viewsets-0.12.0/fastapi_viewsets/error_responses.py

@@ -0,0 +1,261 @@
+"""
+The body of every error response: `ApiErrorBody`.
+
+    {
+        "detail": "Item with pk 42 not found",
+        "detail_code": "fastapi-viewsets.not_found",
+        "detail_params": {"pk": 42},
+        "field_errors": {}
+    }
+
+`error_body()` builds it from an exception:
+
+- a `DfViewSetError`: its `detail`, `code` and `params`;
+- a `RequestValidationError`: `fastapi-viewsets.validation_failed`, with its errors in
+  `field_errors`;
+- any other `HTTPException` (FastAPI's, Starlette's, one an application raises, Starlette's own
+  404 and 405 of the router): `fastapi-viewsets.http_error` with `params.status`;
+- any other exception: `fastapi-viewsets.unhandled_error` (`UnhandledError`), status 500, with no
+  part of the exception in the body.
+
+The routes of a viewset answer every error with this body without any registration (see
+`routing.TransportRoute`). `install_error_handlers(app)` answers the errors of the application's
+other routes, and of a request no route matches, with it too.
+"""
+
+from http import HTTPStatus
+from typing import Any, get_args
+
+from fastapi import FastAPI
+from fastapi.encoders import jsonable_encoder
+from fastapi.exception_handlers import http_exception_handler, request_validation_exception_handler
+from fastapi.exceptions import RequestValidationError
+from fastapi.utils import is_body_allowed_for_status_code
+from pydantic import BaseModel, Field
+from pydantic_core.core_schema import ErrorType
+from starlette.exceptions import HTTPException
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+
+from .error_namespace import _namespaced, ERROR_NAMESPACE_PYDANTIC
+from .exceptions import DfViewSetError, UnhandledError
+
+
+class ApiFieldError(BaseModel):
+    """One failure of one value of a request that failed validation."""
+
+    code: str = Field(
+        description=(
+            "pydantic's error type in the namespace `pydantic`, e.g. `pydantic.string_too_short`; "
+            "`pydantic.custom_error` for a type pydantic does not declare (a `PydanticCustomError` of the "
+            "application); `fastapi-viewsets.pk_assigned_by_server` for a primary key in a create's body."
+        ),
+        examples=["pydantic.string_too_short"],
+    )
+    params: dict[str, Any] = Field(
+        description=(
+            "The values pydantic built `detail` from (pydantic's `ctx`); `{}` without any. For "
+            "`pydantic.custom_error`: `{type, ctx}`, the custom error's type and its `ctx`."
+        ),
+        examples=[{"min_length": 3}, {"type": "app.slug_taken", "ctx": {"slug": "blue"}}],
+    )
+    detail: str = Field(
+        description="pydantic's English message (`msg`).",
+        examples=["String should have at least 3 characters"],
+    )
+
+
+class ApiErrorBody(BaseModel):
+    """The body of every error response."""
+
+    detail: str = Field(
+        description="English text of the error, interpolated from `detail_params`. Not translated.",
+        examples=["Item with pk 42 not found"],
+    )
+    detail_code: str = Field(
+        description=(
+            "The error's full code, `<namespace>.<code>`: `fastapi-viewsets.<code>` for the errors the "
+            "package raises, the application's own code as given for its own `DfViewSetError`."
+        ),
+        examples=["fastapi-viewsets.not_found"],
+    )
+    detail_params: dict[str, Any] = Field(
+        description="The values `detail` was interpolated with, by name; `{}` without any.",
+        examples=[{"pk": 42}],
+    )
+    field_errors: dict[str, list[ApiFieldError]] = Field(
+        description=(
+            "The failures of a request that failed validation (`fastapi-viewsets.validation_failed`), keyed "
+            "by field name: pydantic's `loc` without its first element (`body`, `query`, `path`, `header`, "
+            "`cookie`), joined with `.`; a failure of the body as a whole is keyed `''`. `{}` for every "
+            "other error."
+        ),
+        examples=[{}],
+    )
+
+
+VALIDATION_FAILED_DETAIL = "The request failed validation"
+"""The `detail` of `fastapi-viewsets.validation_failed`."""
+
+
+def _jsonable_ctx(ctx: dict[str, Any] | None) -> dict[str, Any]:
+    """pydantic's `ctx` as JSON values: an exception (the `error` of `value_error`) as its message."""
+    return jsonable_encoder(
+        {name: str(value) if isinstance(value, BaseException) else value for name, value in (ctx or {}).items()}
+    )
+
+
+PYDANTIC_ERROR_TYPES = frozenset(get_args(ErrorType))
+"""The error types pydantic declares: the values of `pydantic_core.core_schema.ErrorType`."""
+
+CUSTOM_ERROR_CODE = f"{ERROR_NAMESPACE_PYDANTIC}.custom_error"
+"""The code of a field error whose type pydantic does not declare."""
+
+_PACKAGE_FIELD_ERROR_CODES = {"pk_assigned_by_server": _namespaced("pk_assigned_by_server")}
+"""The codes of the `PydanticCustomError` types this package raises, by type."""
+
+
+def _field_error(error: Any) -> dict[str, Any]:
+    error_type = error.get("type")
+    ctx = _jsonable_ctx(error.get("ctx"))
+    if error_type in PYDANTIC_ERROR_TYPES:
+        code, params = f"{ERROR_NAMESPACE_PYDANTIC}.{error_type}", ctx
+    elif error_type in _PACKAGE_FIELD_ERROR_CODES:
+        code, params = _PACKAGE_FIELD_ERROR_CODES[error_type], ctx
+    else:
+        code, params = CUSTOM_ERROR_CODE, {"type": error_type, "ctx": ctx}
+    return {"code": code, "params": params, "detail": str(error.get("msg", ""))}
+
+
+def field_errors(errors: Any) -> dict[str, list[dict[str, Any]]]:
+    """
+    pydantic's errors (`RequestValidationError.errors()`) as `ApiErrorBody.field_errors`: keyed by
+    `loc` without its first element, joined with `.` (`("body", "address", "city")` is
+    `address.city`, `("body",)` is `''`), each `{code, params, detail}` with `msg` as `detail`.
+    `input` is left out.
+
+    - A `type` pydantic declares (`PYDANTIC_ERROR_TYPES`) is `code` in the namespace
+      `ERROR_NAMESPACE_PYDANTIC` (`pydantic.string_too_short`), with `ctx` as `params`.
+    - `pk_assigned_by_server`, the type this package raises, is `fastapi-viewsets.pk_assigned_by_server`,
+      with `ctx` as `params`.
+    - Any other `type` (a `PydanticCustomError` of the application) is `pydantic.custom_error`, with
+      `params` `{"type": <type>, "ctx": <ctx>}`: `ctx` is nested, so none of its keys collides with
+      `type`.
+    """
+    grouped: dict[str, list[dict[str, Any]]] = {}
+    for error in errors or ():
+        loc = error.get("loc") or ()
+        name = ".".join(str(part) for part in list(loc)[1:])
+        grouped.setdefault(name, []).append(_field_error(error))
+    return grouped
+
+
+def _body(detail: str, code: str, params: dict[str, Any], fields: dict | None = None) -> dict[str, Any]:
+    return {"detail": detail, "detail_code": code, "detail_params": params, "field_errors": fields or {}}
+
+
+def error_status(error: BaseException) -> int:
+    """The status `error` is answered with: an `HTTPException`'s own, 422 for a
+    `RequestValidationError`, 500 for any other exception."""
+    if isinstance(error, HTTPException):
+        return error.status_code
+    if isinstance(error, RequestValidationError):
+        return 422
+    return 500
+
+
+def error_body(error: BaseException) -> dict[str, Any]:
+    """
+    `error` as an `ApiErrorBody`, in JSON form.
+
+    - `DfViewSetError`: `detail`, `code` as `detail_code`, `params` as `detail_params`.
+    - `RequestValidationError`: `fastapi-viewsets.validation_failed`, `detail_params` `{}`, its errors
+      in `field_errors` (see `field_errors()`).
+    - another `HTTPException`: `fastapi-viewsets.http_error`, `detail_params` `{"status": <status>}`.
+      A string `detail` is the body's `detail`; any other `detail` is `detail_params.detail` and the
+      body's `detail` is the status phrase (`Bad Request`).
+    - any other exception: the body of `UnhandledError`.
+    """
+    if isinstance(error, RequestValidationError):
+        return _body(VALIDATION_FAILED_DETAIL, _namespaced("validation_failed"), {}, field_errors(error.errors()))
+    if not isinstance(error, HTTPException):
+        error = UnhandledError()
+    if isinstance(error, DfViewSetError):
+        return _body(jsonable_encoder(error.detail), error.code, jsonable_encoder(error.params))
+    params: dict[str, Any] = {"status": error.status_code}
+    detail = error.detail
+    if not isinstance(detail, str):
+        params["detail"] = jsonable_encoder(detail)
+        try:
+            detail = HTTPStatus(error.status_code).phrase
+        except ValueError:
+            detail = f"HTTP {error.status_code}"
+    return _body(detail, _namespaced("http_error"), params)
+
+
+def error_response(error: BaseException) -> Response:
+    """
+    The response that answers `error`: `error_status(error)`, `error_body(error)` as JSON, and an
+    `HTTPException`'s `headers`. A status that allows no body (204, 304) is answered without one.
+    """
+    status = error_status(error)
+    headers = getattr(error, "headers", None) if isinstance(error, HTTPException) else None
+    if not is_body_allowed_for_status_code(status):
+        return Response(status_code=status, headers=headers)
+    return JSONResponse(error_body(error), status_code=status, headers=headers)
+
+
+async def _handle_error(_request: Request, error: Exception) -> Response:
+    """The handler `install_error_handlers` registers, and the one a viewset route answers
+    `HTTPException` and `RequestValidationError` with. For `Exception` Starlette's
+    `ServerErrorMiddleware` re-raises the exception after the response, and the server logs it."""
+    return error_response(error)
+
+
+def install_error_handlers(app: FastAPI) -> None:
+    """
+    Registers the handlers that answer the errors of every route of `app` with an `ApiErrorBody`
+    (see `error_body()`), for `DfViewSetError`, `HTTPException` (Starlette's, which FastAPI's
+    subclasses), `RequestValidationError` and `Exception`. Starlette's own 404 of a path no route
+    matches and 405 of a method a route does not serve are `fastapi-viewsets.http_error` with
+    `params.status` 404 and 405. An exception without a handler of its own is answered with 500
+    `fastapi-viewsets.unhandled_error` and re-raised by Starlette, so the server logs it.
+
+    A handler the application registers for one of these classes afterwards replaces this one; a
+    handler for a more specific class, or for a status, takes precedence as Starlette's lookup
+    gives it.
+
+    The routes of a viewset answer with an `ApiErrorBody` whether or not this is called.
+    """
+    app.add_exception_handler(DfViewSetError, _handle_error)
+    app.add_exception_handler(HTTPException, _handle_error)
+    app.add_exception_handler(RequestValidationError, _handle_error)
+    app.add_exception_handler(Exception, _handle_error)
+
+
+_FASTAPI_HANDLERS = (http_exception_handler, request_validation_exception_handler)
+"""The handlers a FastAPI application registers by default."""
+
+
+EXCEPTION_HANDLERS_SCOPE_KEY = "starlette.exception_handlers"
+
+
+def uniform_exception_handlers(scope: dict[str, Any]) -> None:
+    """
+    Replaces, for the request of `scope`, FastAPI's default handlers of `HTTPException` and
+    `RequestValidationError` with one that answers an `ApiErrorBody`. Handlers the application
+    registered for a class or a status are kept.
+    """
+    exception_handlers, status_handlers = scope.get(EXCEPTION_HANDLERS_SCOPE_KEY) or ({}, {})
+    handlers = {
+        key: (_handle_error if handler in _FASTAPI_HANDLERS else handler) for key, handler in exception_handlers.items()
+    }
+    handlers.setdefault(HTTPException, _handle_error)
+    handlers.setdefault(RequestValidationError, _handle_error)
+    scope[EXCEPTION_HANDLERS_SCOPE_KEY] = (handlers, status_handlers)
+
+
+def answers_unhandled_itself(app: Any) -> bool:
+    """Whether `app` has a handler of its own, not `install_error_handlers`', for `Exception` or 500."""
+    handlers = getattr(app, "exception_handlers", None) or {}
+    return any(key in handlers and handlers[key] is not _handle_error for key in (Exception, 500))

{dynamicforms_fastapi_viewsets-0.11.4 → dynamicforms_fastapi_viewsets-0.12.0}/fastapi_viewsets/events/conftest.py

@@ -9,6 +9,7 @@ from typing import Any
 import pytest
 
 from ..conf import settings
+from ..error_namespace import ERROR_NAMESPACE
 from . import store as store_module
 from .delivery import reset_subscriptions
 from .redis import _APPEND_SCRIPT
@@ -257,3 +258,8 @@ class FakePubSub:
     async def aclose(self) -> None:
         await self.unsubscribe(*list(self.subscribed))
         self.closed = True
+
+
+def envelope(detail: str, code: str, **params: Any) -> dict[str, Any]:
+    """The `ApiErrorBody` of the package's error `code` (without the namespace)."""
+    return {"detail": detail, "detail_code": f"{ERROR_NAMESPACE}.{code}", "detail_params": params, "field_errors": {}}

{dynamicforms_fastapi_viewsets-0.11.4 → dynamicforms_fastapi_viewsets-0.12.0}/fastapi_viewsets/events/viewset.py

@@ -23,6 +23,7 @@ from starlette.exceptions import HTTPException
 from ..conf import settings
 from ..context import Context
 from ..decorators.route_viewset import route_viewset
+from ..error_responses import ApiErrorBody, error_body
 from ..exceptions import EventCursorsExceededError, EventTopicInvalidError
 from ..mux_ws.transports import transports
 from ..routing import PEER_SCOPE_KEY
@@ -91,13 +92,14 @@ class TopicAnswer(BaseModel):
     """
     The answer of `poll` for one topic. `events` is None when the log cannot answer the cursor; the
     caller then re-reads the state it displays. A topic that was refused, or that has neither form,
-    has `rev` and `events` None, `error` set to the code of the refusal and `status` to its HTTP
-    status. `error`, `status` and `scope` are left out of the serialized answer when they are None.
+    has `rev` and `events` None, `error` set to the `ApiErrorBody` of the refusal, as a call refused
+    with it is answered, and `status` to its HTTP status. `error`, `status` and `scope` are left out
+    of the serialized answer when they are None.
     """
 
     rev: int | None
     events: list[PolledEvent] | None
-    error: str | None = None
+    error: ApiErrorBody | None = None
     status: int | None = None
     """The HTTP status of the refusal; set on every answer with `error`."""
     scope: str | None = None
@@ -146,11 +148,6 @@ def _reauthorizer(request: Request, topic: str) -> Callable[[], Awaitable[str]]:
     return reauthorize
 
 
-def _error_code(error: HTTPException) -> str:
-    code = getattr(error, "code", None)
-    return code if isinstance(code, str) and code else "event_topic_refused"
-
-
 class EventsViewSet:
     """
     Subscriptions to event topics over a muxws socket, and polls of event topics over either
@@ -166,11 +163,12 @@ class EventsViewSet:
         Subscribes the socket the command arrived on to `topic` and answers the current rev of its
         store topic, with the scope key for a scoped viewset topic (see
         `fastapi_viewsets.events.scopes`). Every event published to the store topic after it is
-        pushed to the socket until the socket closes or unsubscribes. 422 `event_topic_invalid` for
-        a topic of neither form, 403 `event_topic_refused`, or the status of the authorizer's
-        `HTTPException`, for a topic the authorizers do not admit, 403 `event_scope_missing` for a
-        scoped topic whose resolver answers None, 409 `event_subscriptions_exceeded` for a socket
-        that already holds `settings.viewsets_event_max_subscriptions` topics. A subscribe refused
+        pushed to the socket until the socket closes or unsubscribes. 422
+        `fastapi-viewsets.event_topic_invalid` for a topic of neither form, 403
+        `fastapi-viewsets.event_topic_refused`, or the status of the authorizer's `HTTPException`, for
+        a topic the authorizers do not admit, 403 `fastapi-viewsets.event_scope_missing` for a scoped
+        topic whose resolver answers None, 409 `fastapi-viewsets.event_subscriptions_exceeded` for a
+        socket that already holds `settings.viewsets_event_max_subscriptions` topics. A subscribe refused
         with a status from 400 to 499 other than 429 removes the socket's subscription to the topic,
         if it holds one; any other error, a 429 or 5xx included, leaves it as it is. A command served by
         `process_command` without `peer=` raises `RuntimeError`.
@@ -208,18 +206,20 @@ class EventsViewSet:
         """
         Answers every cursor of the request. Per topic the authorizers run, then the store topic is
         resolved (see `fastapi_viewsets.events.scopes`); a refused topic answers `error` with the
-        refusal's code (`event_topic_refused`, `event_scope_missing`, or the `code` of the
-        `HTTPException` an authorizer raised, FastAPI's or Starlette's, `event_topic_refused` for one
-        without a `code`) and `status` with its HTTP status, and `event_topic_invalid` with 422 for a
-        topic of neither form, and the other topics are unaffected. A poll over muxws that refuses a
-        topic with a status from 400 to 499 other than 429 removes the socket's subscription to it;
+        `ApiErrorBody` of the refusal (`fastapi-viewsets.event_topic_refused`,
+        `fastapi-viewsets.event_scope_missing`, or the body of the `HTTPException` an authorizer raised,
+        FastAPI's or Starlette's: its own code for a `DfViewSetError`, `fastapi-viewsets.http_error`
+        for any other) and `status` with its HTTP status, and the body of
+        `fastapi-viewsets.event_topic_invalid` with 422 for a topic of neither form, and the other
+        topics are unaffected. A poll over muxws that refuses a topic with a status from 400
+        to 499 other than 429 removes the socket's subscription to it;
         a 429 or a status of 500 or above keeps it. A None cursor answers the topic's current rev
         and no events, a cursor equal to it `[]`, and any other cursor the events since it, or
         `events: null` when the log holds no event whose `prev` is the cursor. When the request
         carries `scopes`, a cursor of a topic whose entry in `scopes` (absent for none) differs from
         the scope key the server resolves answers the current rev and `events: null`. Every answer of
-        a scoped topic carries its `scope`. 422 `event_cursors_exceeded` for more cursors than
-        `settings.viewsets_event_max_subscriptions`.
+        a scoped topic carries its `scope`. 422 `fastapi-viewsets.event_cursors_exceeded` for more
+        cursors than `settings.viewsets_event_max_subscriptions`.
 
         The delivery filters run on every event since the cursor, with a `Subscription` of the
         topic whose `peer` is the socket the poll arrived on, None over REST, and whose `context` is
@@ -237,13 +237,16 @@ class EventsViewSet:
         admitted: list[ResolvedTopic] = []
         for topic in cursors:
             if not is_valid_topic(topic):
-                answers[topic] = TopicAnswer(rev=None, events=None, error="event_topic_invalid", status=422)
+                invalid = EventTopicInvalidError(topic)
+                answers[topic] = TopicAnswer(
+                    rev=None, events=None, error=error_body(invalid), status=invalid.status_code
+                )
                 continue
             try:
                 await authorize_topic(request, context, topic)
                 resolved = await resolve_topic(request, topic)
             except HTTPException as error:
-                answers[topic] = TopicAnswer(rev=None, events=None, error=_error_code(error), status=error.status_code)
+                answers[topic] = TopicAnswer(rev=None, events=None, error=error_body(error), status=error.status_code)
                 if peer is not None and delivery._is_refusal(error):
                     await delivery.unsubscribe(peer, topic)
                 continue