af-fastapi-exceptions 0.0.2__py3-none-any.whl

af_fastapi_exceptions-0.0.2.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: af-fastapi-exceptions
+Version: 0.0.2
+Summary: Reusable FastAPI base exceptions, ApiMessage, and a unified exception handler
+License: MIT
+Author: Allfly
+Author-email: engineering@allfly.io
+Requires-Python: >=3.13,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: fastapi (>=0.100.0)
+Requires-Dist: loguru (>=0.7.0)
+Requires-Dist: starlette (>=0.27.0)
+Description-Content-Type: text/markdown
+
+# af-fastapi-exceptions
+
+Reusable exception handling for FastAPI apps: a base `ServiceError` hierarchy you can raise
+(and extend), plus a middleware + validation handler so that **every** error — raised before,
+during, or after the route — reaches the client as the same JSON body.
+
+**Bring your own response model.** The library never defines or imposes a response schema —
+you pass your own model down, and the handlers use only the slice they need (construct it with
+`message` + `errors`, then call `.model_dump()`). Your app keeps one model for both success and
+error responses; nothing is coupled across the boundary.
+
+## Installation
+
+```bash
+pip install af-fastapi-exceptions
+# or with Poetry:
+poetry add af-fastapi-exceptions
+```
+
+## Raising errors
+
+Raise a `ServiceError` (or a subclass) anywhere; the middleware turns it into your response
+model with the right status code.
+
+```python
+from allfly.fastapi.exceptions import EntityNotFoundError, ForbiddenError
+
+def get_user(user_id: str):
+    user = repo.find(user_id)
+    if not user:
+        raise EntityNotFoundError(f"No user {user_id}")   # -> 404
+    if not user.active:
+        raise ForbiddenError()                            # -> 403
+    return user
+```
+
+Built-in classes: `UnauthorizedRequestError` (401), `ForbiddenError` (403),
+`BadRequestError` (400), `EntityNotFoundError` (404), `ResourceConflictError` (409),
+`UnprocessableRequestError` (422), `UnsupportedFeatureError` (501),
+`DownstreamServiceError` (502).
+
+`ServiceWarning` is a `ServiceError` subclass for **expected/recoverable** conditions — logged
+at `warning` level instead of `error`. `ForbiddenError` and `UnsupportedFeatureError` are
+warnings.
+
+### Extend them
+
+```python
+from allfly.fastapi.exceptions import UnprocessableRequestError
+
+class FopError(UnprocessableRequestError):
+    def __init__(self, message="Payment method was rejected."):
+        super().__init__(message)
+```
+
+## Your response model
+
+Provide any model whose instances have a `.model_dump()` and that can be constructed with
+`message=` and `errors=` (a pydantic model with those two fields — plus whatever else you want,
+e.g. `timestamp`, `metadata` — is the common case). The library only ever sets `message` and
+`errors`; the rest come from your model's defaults. This is the `ApiErrorBody` protocol:
+
+```python
+class ApiErrorBody(Protocol):
+    def __init__(self, *, message: str, errors: list[str]) -> None: ...
+    def model_dump(self, *, mode: str = "json", exclude_none: bool = True) -> dict: ...
+```
+
+## Wiring it into your app
+
+```python
+from fastapi import FastAPI
+from fastapi.exceptions import RequestValidationError
+from allfly.fastapi.exceptions import (
+    ExceptionMiddleware,
+    DefaultExceptionHandlerSettings,
+    build_validation_handler,
+    build_error_responses,
+)
+from myapp.models import ApiMessage   # <-- YOUR model
+
+app = FastAPI(responses=build_error_responses(ApiMessage))   # OpenAPI error schemas
+
+# Catches ServiceError (-> its status) and any unexpected Exception (-> 500).
+app.add_middleware(
+    ExceptionMiddleware,
+    error_model=ApiMessage,
+    settings=DefaultExceptionHandlerSettings(production=is_production()),
+)
+
+# RequestValidationError is raised during request parsing, before the middleware runs,
+# so register it as an exception handler too — same body, built from your model.
+app.add_exception_handler(RequestValidationError, build_validation_handler(ApiMessage))
+```
+
+## Settings (why not read your env directly?)
+
+The middleware only needs to know one thing: **are we in production?** (In production the 500
+handler hides the raw exception string; otherwise it includes it to aid debugging.)
+
+Rather than force a settings system on you, it takes any object matching the
+`ExceptionHandlerSettings` protocol — a single `production: bool`. Use the provided
+`DefaultExceptionHandlerSettings`, or pass your own object exposing `production`.
+
+## Logging
+
+Handlers log via [loguru](https://github.com/Delgan/loguru) — `ServiceWarning` at `warning`,
+real errors at `error`/`exception`. If your app doesn't configure loguru, the messages are
+simply not emitted at higher levels by default.
+

af_fastapi_exceptions-0.0.2.dist-info/RECORD

@@ -0,0 +1,7 @@
+allfly/fastapi/exceptions/__init__.py,sha256=V7vElyhWtXV56z3h78CbH4OHS3k9Y8ORYz7wob8zpXg,1008
+allfly/fastapi/exceptions/exceptions.py,sha256=QajjDtTfhYnpj_l22hwbaxfDuH0NuKCmuKF8Y3nzBJQ,2067
+allfly/fastapi/exceptions/middleware.py,sha256=hUYW0Uk96UE1PyO0vWaUqBcd9RnLwqTMIRpKtWRY7mY,4736
+allfly/fastapi/exceptions/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+af_fastapi_exceptions-0.0.2.dist-info/METADATA,sha256=CpXvYi8lTJcjhLNk2KLIDWNYP4VKu_03t7pvENe9Rpw,4753
+af_fastapi_exceptions-0.0.2.dist-info/WHEEL,sha256=EGEvSphFYqXKs23-kQBeyNoJP1nrT8ZJKQoi5p5DYL8,88
+af_fastapi_exceptions-0.0.2.dist-info/RECORD,,

af_fastapi_exceptions-0.0.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.4.0
+Root-Is-Purelib: true
+Tag: py3-none-any

allfly/fastapi/exceptions/__init__.py

@@ -0,0 +1,41 @@
+from allfly.fastapi.exceptions.exceptions import (
+    BadRequestError,
+    DownstreamServiceError,
+    EntityNotFoundError,
+    ForbiddenError,
+    ResourceConflictError,
+    ServiceError,
+    ServiceWarning,
+    UnauthorizedRequestError,
+    UnprocessableRequestError,
+    UnsupportedFeatureError,
+)
+from allfly.fastapi.exceptions.middleware import (
+    ApiErrorBody,
+    DefaultExceptionHandlerSettings,
+    ExceptionHandlerSettings,
+    ExceptionMiddleware,
+    build_error_responses,
+    build_validation_handler,
+)
+
+__version__ = "0.0.0"
+
+__all__ = [
+    "ServiceError",
+    "ServiceWarning",
+    "UnauthorizedRequestError",
+    "ForbiddenError",
+    "BadRequestError",
+    "EntityNotFoundError",
+    "ResourceConflictError",
+    "UnprocessableRequestError",
+    "UnsupportedFeatureError",
+    "DownstreamServiceError",
+    "ExceptionMiddleware",
+    "build_validation_handler",
+    "build_error_responses",
+    "ApiErrorBody",
+    "ExceptionHandlerSettings",
+    "DefaultExceptionHandlerSettings",
+]

allfly/fastapi/exceptions/exceptions.py

@@ -0,0 +1,70 @@
+from dataclasses import dataclass
+
+from starlette import status
+
+
+@dataclass
+class ServiceError(Exception):
+    message: str
+    status_code: int
+
+    def __post_init__(self):
+        super().__init__()
+
+    def __str__(self):
+        return self.message
+
+
+@dataclass
+class ServiceWarning(ServiceError):  # noqa: N818 — intentionally not named *Error; these are expected conditions
+    """Raised for expected/recoverable conditions that don't warrant error-level logging."""
+
+    pass
+
+
+class UnauthorizedRequestError(ServiceError):
+    def __init__(self, message="Unauthorized Request"):
+        status_code = status.HTTP_401_UNAUTHORIZED
+        super().__init__(message, status_code)
+
+
+class ForbiddenError(ServiceWarning):
+    def __init__(self, message="Forbidden Request"):
+        status_code = status.HTTP_403_FORBIDDEN
+        super().__init__(message, status_code)
+
+
+class BadRequestError(ServiceError):
+    def __init__(self, message="Bad Request"):
+        status_code = status.HTTP_400_BAD_REQUEST
+        super().__init__(message, status_code)
+
+
+class EntityNotFoundError(ServiceError):
+    def __init__(self, message="Entity not found"):
+        status_code = status.HTTP_404_NOT_FOUND
+        super().__init__(message, status_code)
+
+
+class ResourceConflictError(ServiceError):
+    def __init__(self, message="Request creates a conflict"):
+        status_code = status.HTTP_409_CONFLICT
+        super().__init__(message, status_code)
+
+
+class UnprocessableRequestError(ServiceError):
+    def __init__(self, message="Unprocessable Request"):
+        status_code = status.HTTP_422_UNPROCESSABLE_ENTITY
+        super().__init__(message, status_code)
+
+
+class UnsupportedFeatureError(ServiceWarning):
+    def __init__(self, message="Not implemented"):
+        status_code = status.HTTP_501_NOT_IMPLEMENTED
+        super().__init__(message, status_code)
+
+
+class DownstreamServiceError(ServiceError):
+    def __init__(self, message="Downstream service error"):
+        status_code = status.HTTP_502_BAD_GATEWAY
+        super().__init__(message, status_code)

allfly/fastapi/exceptions/middleware.py

@@ -0,0 +1,116 @@
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+from fastapi.exceptions import RequestValidationError
+from loguru import logger
+from starlette import status
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+from allfly.fastapi.exceptions.exceptions import ServiceError, ServiceWarning
+
+
+class ApiErrorBody(Protocol):
+    def __init__(self, *, message: str, errors: list[str]) -> None: ...
+
+    def model_dump(self, *, mode: str = "json", exclude_none: bool = True) -> dict[str, Any]: ...
+
+
+class ExceptionHandlerSettings(Protocol):
+    production: bool
+
+
+@dataclass
+class DefaultExceptionHandlerSettings:
+    production: bool = False
+
+
+def _handle_unexpected_error(
+    request: Request, e: Exception, settings: ExceptionHandlerSettings, error_model: type[ApiErrorBody]
+) -> JSONResponse:
+    logger.opt(exception=e).exception("Internal server error occurred", extra={"path": request.url.path}, exc_info=True)
+    errors = [] if settings.production else [str(e)]
+    body = error_model(message="internal server error", errors=errors)
+    return JSONResponse(
+        content=body.model_dump(mode="json", exclude_none=True),
+        media_type="application/json",
+        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+    )
+
+
+def _handle_service_error(request: Request, e: ServiceError, error_model: type[ApiErrorBody]) -> JSONResponse:
+    if isinstance(e, ServiceWarning):
+        logger.warning(
+            "Expected service condition",
+            extra={"path": request.url.path, "error_type": type(e).__name__},
+        )
+    else:
+        logger.opt(exception=e).exception(
+            "Service error occurred",
+            extra={"path": request.url.path, "error_type": type(e).__name__},
+        )
+    body = error_model(message="service error", errors=[e.message])
+    response_content = body.model_dump(mode="json", exclude_none=True)
+    if not isinstance(e, ServiceWarning):
+        logger.error(f"ServiceError response - status: {e.status_code}, content: {response_content}")
+    return JSONResponse(
+        content=response_content,
+        media_type="application/json",
+        status_code=e.status_code,
+    )
+
+
+def build_validation_handler(error_model: type[ApiErrorBody]):
+    async def handle_validation_error(request: Request, exc: RequestValidationError) -> JSONResponse:
+        logger.warning(f"Validation error details: {exc.errors()}")
+        errors = []
+        for error in exc.errors():
+            location = ".".join(str(loc) for loc in error["loc"] if loc != "body")
+            message = error["msg"]
+            error_type = error.get("type", "unknown")
+            detailed_error = (
+                f"Field: {location if location else 'N/A'}, Error: {message}, Type: {error_type}, Received: "
+                f"{error.get('input', 'not provided')}"
+            )
+            errors.append(detailed_error)
+            logger.warning(detailed_error)
+        body = error_model(message="Request Validation Error", errors=errors)
+        return JSONResponse(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            content=body.model_dump(mode="json", exclude_none=True),
+        )
+
+    return handle_validation_error
+
+
+def build_error_responses(error_model: type[ApiErrorBody]) -> dict:
+    return {
+        status.HTTP_401_UNAUTHORIZED: {
+            "model": error_model,
+            "description": "Authentication data in the request is invalid",
+        },
+        status.HTTP_403_FORBIDDEN: {"model": error_model, "description": "Not authorized"},
+        status.HTTP_404_NOT_FOUND: {"model": error_model, "description": "Not found"},
+        status.HTTP_409_CONFLICT: {"model": error_model, "description": "Resource conflict detected"},
+        status.HTTP_422_UNPROCESSABLE_ENTITY: {
+            "model": error_model,
+            "description": "Understood the request, but can't and won't process it",
+        },
+        status.HTTP_400_BAD_REQUEST: {"model": error_model, "description": "Bad request"},
+    }
+
+
+class ExceptionMiddleware(BaseHTTPMiddleware):
+    def __init__(self, app, error_model: type[ApiErrorBody], settings: ExceptionHandlerSettings | None = None):
+        super().__init__(app)
+        self._error_model = error_model
+        self._settings = settings or DefaultExceptionHandlerSettings()
+
+    async def dispatch(self, request: Request, call_next):
+        try:
+            return await call_next(request)
+        except ServiceError as e:
+            return _handle_service_error(request, e, self._error_model)
+        except Exception as e:
+            return _handle_unexpected_error(request, e, self._settings, self._error_model)