voltwire-fastapi-exceptions 0.0.1__tar.gz

voltwire_fastapi_exceptions-0.0.1/.gitignore

@@ -0,0 +1,221 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Local tool state
+.omc/

voltwire_fastapi_exceptions-0.0.1/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.5
+Name: voltwire-fastapi-exceptions
+Version: 0.0.1
+Summary: Reusable FastAPI base exceptions, ApiMessage, and a unified exception handler
+Author-email: Hermann Steidel <hsteidel.software@gmail.com>
+License-Expression: MIT
+Requires-Python: <4.0,>=3.13
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: starlette>=0.27.0
+Description-Content-Type: text/markdown
+
+<img src="https://raw.githubusercontent.com/hsteidel/voltwire/main/assets/icons/fastapi-exceptions.svg" alt="" width="56" height="56" align="left">
+
+# voltwire-fastapi-exceptions
+
+Reusable exception handling for FastAPI apps: a base `AppError` 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 voltwire-fastapi-exceptions
+# or with Poetry:
+poetry add voltwire-fastapi-exceptions
+```
+
+## Raising errors
+
+Raise an `AppError` (or a subclass) anywhere; the middleware turns it into your response
+model with the right status code.
+
+```python
+from voltwire.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).
+
+`AppWarning` is an `AppError` subclass for **expected/recoverable** conditions — logged
+at `warning` level instead of `error`. `ForbiddenError` and `UnsupportedFeatureError` are
+warnings.
+
+### Extend them
+
+```python
+from voltwire.fastapi.exceptions import UnprocessableRequestError
+
+class DivideByZeroError(UnprocessableRequestError):
+    def __init__(self, message="Cannot divide by zero"):
+        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 voltwire.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 AppError (-> 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 `logging.getLogger(__name__)` (Python's standard `logging` module) —
+`AppWarning` at `warning`, real errors at `error`/`exception`. To activate debug output:
+
+```python
+import logging
+logging.getLogger("voltwire.fastapi.exceptions").setLevel(logging.DEBUG)
+```
+
+If your app uses [loguru](https://github.com/Delgan/loguru), intercept stdlib logging once at startup:
+
+```python
+import logging
+from loguru import logger
+
+class InterceptHandler(logging.Handler):
+    def emit(self, record: logging.LogRecord) -> None:
+        logger.opt(depth=6, exception=record.exc_info).log(
+            record.levelname, record.getMessage()
+        )
+
+logging.getLogger("voltwire.fastapi.exceptions").addHandler(InterceptHandler())
+```

voltwire_fastapi_exceptions-0.0.1/README.md

@@ -0,0 +1,130 @@
+<img src="https://raw.githubusercontent.com/hsteidel/voltwire/main/assets/icons/fastapi-exceptions.svg" alt="" width="56" height="56" align="left">
+
+# voltwire-fastapi-exceptions
+
+Reusable exception handling for FastAPI apps: a base `AppError` 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 voltwire-fastapi-exceptions
+# or with Poetry:
+poetry add voltwire-fastapi-exceptions
+```
+
+## Raising errors
+
+Raise an `AppError` (or a subclass) anywhere; the middleware turns it into your response
+model with the right status code.
+
+```python
+from voltwire.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).
+
+`AppWarning` is an `AppError` subclass for **expected/recoverable** conditions — logged
+at `warning` level instead of `error`. `ForbiddenError` and `UnsupportedFeatureError` are
+warnings.
+
+### Extend them
+
+```python
+from voltwire.fastapi.exceptions import UnprocessableRequestError
+
+class DivideByZeroError(UnprocessableRequestError):
+    def __init__(self, message="Cannot divide by zero"):
+        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 voltwire.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 AppError (-> 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 `logging.getLogger(__name__)` (Python's standard `logging` module) —
+`AppWarning` at `warning`, real errors at `error`/`exception`. To activate debug output:
+
+```python
+import logging
+logging.getLogger("voltwire.fastapi.exceptions").setLevel(logging.DEBUG)
+```
+
+If your app uses [loguru](https://github.com/Delgan/loguru), intercept stdlib logging once at startup:
+
+```python
+import logging
+from loguru import logger
+
+class InterceptHandler(logging.Handler):
+    def emit(self, record: logging.LogRecord) -> None:
+        logger.opt(depth=6, exception=record.exc_info).log(
+            record.levelname, record.getMessage()
+        )
+
+logging.getLogger("voltwire.fastapi.exceptions").addHandler(InterceptHandler())
+```

voltwire_fastapi_exceptions-0.0.1/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "voltwire-fastapi-exceptions"
+version = "0.0.1"
+description = "Reusable FastAPI base exceptions, ApiMessage, and a unified exception handler"
+authors = [{name = "Hermann Steidel", email = "hsteidel.software@gmail.com"}]
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.13,<4.0"
+dependencies = [
+    "fastapi>=0.100.0",
+    "starlette>=0.27.0",
+]
+
+[dependency-groups]
+dev = ["pytest>=8.0"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/voltwire"]

voltwire_fastapi_exceptions-0.0.1/src/voltwire/fastapi/exceptions/__init__.py

@@ -0,0 +1,33 @@
+from voltwire.fastapi.exceptions.exceptions import *  # noqa: F401, F403
+from voltwire.fastapi.exceptions.middleware import (
+    ApiErrorBody,
+    DefaultExceptionHandlerSettings,
+    ExceptionHandlerSettings,
+    ExceptionMiddleware,
+    build_error_responses,
+    build_validation_handler,
+)
+
+__version__ = "0.0.0"
+
+__all__ = [
+    "AppError",
+    "AppWarning",
+    "UnauthorizedRequestError",
+    "ForbiddenError",
+    "BadRequestError",
+    "EntityNotFoundError",
+    "EntityNotFoundWarning",
+    "ResourceConflictError",
+    "ResourceConflictWarning",
+    "UnprocessableRequestError",
+    "UnprocessableRequestWarning",
+    "UnsupportedFeatureError",
+    "DownstreamServiceError",
+    "ExceptionMiddleware",
+    "build_validation_handler",
+    "build_error_responses",
+    "ApiErrorBody",
+    "ExceptionHandlerSettings",
+    "DefaultExceptionHandlerSettings",
+]

voltwire_fastapi_exceptions-0.0.1/src/voltwire/fastapi/exceptions/exceptions.py

@@ -0,0 +1,83 @@
+from dataclasses import dataclass
+
+from starlette import status
+
+
+@dataclass
+class AppError(Exception):
+    message: str
+    status_code: int
+
+    def __post_init__(self):
+        super().__init__()
+
+    def __str__(self):
+        return self.message
+
+
+@dataclass
+class AppWarning(AppError):  # 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(AppError):
+    def __init__(self, message="Unauthorized Request"):
+        status_code = status.HTTP_401_UNAUTHORIZED
+        super().__init__(message, status_code)
+
+
+class ForbiddenError(AppWarning):
+    def __init__(self, message="Forbidden Request"):
+        status_code = status.HTTP_403_FORBIDDEN
+        super().__init__(message, status_code)
+
+
+class BadRequestError(AppError):
+    def __init__(self, message="Bad Request"):
+        status_code = status.HTTP_400_BAD_REQUEST
+        super().__init__(message, status_code)
+
+
+class EntityNotFoundError(AppError):
+    def __init__(self, message="Entity not found"):
+        status_code = status.HTTP_404_NOT_FOUND
+        super().__init__(message, status_code)
+
+class EntityNotFoundWarning(AppWarning):
+    def __init__(self, message="Entity not found"):
+        super().__init__(message, status.HTTP_404_NOT_FOUND)
+
+class ResourceConflictError(AppError):
+    def __init__(self, message="Request creates a conflict"):
+        status_code = status.HTTP_409_CONFLICT
+        super().__init__(message, status_code)
+
+class ResourceConflictWarning(AppWarning):
+    def __init__(self, message="Request creates a conflict"):
+        status_code = status.HTTP_409_CONFLICT
+        super().__init__(message, status_code)
+
+class UnprocessableRequestError(AppError):
+    def __init__(self, message="Unprocessable Request"):
+        status_code = status.HTTP_422_UNPROCESSABLE_ENTITY
+        super().__init__(message, status_code)
+
+class UnprocessableRequestWarning(AppWarning):
+    def __init__(self, message="Unprocessable Request"):
+        status_code = status.HTTP_422_UNPROCESSABLE_ENTITY
+        super().__init__(message, status_code)
+
+
+class UnsupportedFeatureError(AppWarning):
+    def __init__(self, message="Not implemented"):
+        status_code = status.HTTP_501_NOT_IMPLEMENTED
+        super().__init__(message, status_code)
+
+
+class DownstreamServiceError(AppError):
+    def __init__(self, message="Downstream service error"):
+        status_code = status.HTTP_502_BAD_GATEWAY
+        super().__init__(message, status_code)
+

voltwire_fastapi_exceptions-0.0.1/src/voltwire/fastapi/exceptions/middleware.py

@@ -0,0 +1,117 @@
+import logging
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+from fastapi.exceptions import RequestValidationError
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+from voltwire.fastapi.exceptions.exceptions import AppError, AppWarning
+
+logger = logging.getLogger(__name__)
+
+
+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.exception("Internal server error occurred", extra={"path": request.url.path})
+    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=500,
+    )
+
+
+def _handle_service_error(request: Request, e: AppError, error_model: type[ApiErrorBody]) -> JSONResponse:
+    if isinstance(e, AppWarning):
+        logger.warning(
+            "Expected service condition",
+            extra={"path": request.url.path, "error_type": type(e).__name__},
+        )
+    else:
+        logger.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, AppWarning):
+        logger.error(f"AppError 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=422,
+            content=body.model_dump(mode="json", exclude_none=True),
+        )
+
+    return handle_validation_error
+
+
+def build_error_responses(error_model: type[ApiErrorBody]) -> dict:
+    return {
+        401: {
+            "model": error_model,
+            "description": "Authentication data in the request is invalid",
+        },
+        403: {"model": error_model, "description": "Not authorized"},
+        404: {"model": error_model, "description": "Not found"},
+        409: {"model": error_model, "description": "Resource conflict detected"},
+        422: {
+            "model": error_model,
+            "description": "Understood the request, but can't and won't process it",
+        },
+        400: {"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 AppError 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)

voltwire_fastapi_exceptions-0.0.1/tests/test_exceptions.py

@@ -0,0 +1,43 @@
+from starlette import status
+
+from voltwire.fastapi.exceptions import (
+    BadRequestError,
+    DownstreamServiceError,
+    EntityNotFoundError,
+    ForbiddenError,
+    ResourceConflictError,
+    AppError,
+    AppWarning,
+    UnauthorizedRequestError,
+    UnprocessableRequestError,
+    UnsupportedFeatureError,
+)
+
+
+def test_subclass_status_codes_and_default_messages():
+    cases = [
+        (UnauthorizedRequestError(), status.HTTP_401_UNAUTHORIZED),
+        (ForbiddenError(), status.HTTP_403_FORBIDDEN),
+        (BadRequestError(), status.HTTP_400_BAD_REQUEST),
+        (EntityNotFoundError(), status.HTTP_404_NOT_FOUND),
+        (ResourceConflictError(), status.HTTP_409_CONFLICT),
+        (UnprocessableRequestError(), status.HTTP_422_UNPROCESSABLE_ENTITY),
+        (UnsupportedFeatureError(), status.HTTP_501_NOT_IMPLEMENTED),
+        (DownstreamServiceError(), status.HTTP_502_BAD_GATEWAY),
+    ]
+    for err, code in cases:
+        assert err.status_code == code
+        assert isinstance(err.message, str) and err.message
+
+
+def test_custom_message_and_str():
+    err = EntityNotFoundError("no user 5")
+    assert err.message == "no user 5"
+    assert str(err) == "no user 5"
+
+
+def test_warnings_are_service_errors():
+    assert issubclass(AppWarning, AppError)
+    assert isinstance(ForbiddenError(), AppWarning)
+    assert isinstance(UnsupportedFeatureError(), AppWarning)
+    assert not isinstance(BadRequestError(), AppWarning)

voltwire_fastapi_exceptions-0.0.1/tests/test_middleware.py

@@ -0,0 +1,89 @@
+import asyncio
+import json
+
+from fastapi.exceptions import RequestValidationError
+from starlette import status
+from starlette.requests import Request
+
+from voltwire.fastapi.exceptions import (
+    DefaultExceptionHandlerSettings,
+    EntityNotFoundError,
+    build_error_responses,
+    build_validation_handler,
+)
+from voltwire.fastapi.exceptions.middleware import _handle_service_error, _handle_unexpected_error
+
+
+class FakeApiMessage:
+    def __init__(self, *, message: str, errors: list[str]):
+        self.message = message
+        self.errors = errors
+
+    def model_dump(self, *, mode: str = "json", exclude_none: bool = True) -> dict:
+        return {"message": self.message, "errors": self.errors}
+
+
+def _request(path: str = "/x") -> Request:
+    return Request(
+        {
+            "type": "http",
+            "http_version": "1.1",
+            "method": "GET",
+            "scheme": "http",
+            "server": ("test", 80),
+            "path": path,
+            "query_string": b"",
+            "headers": [],
+        }
+    )
+
+
+def _body(response) -> dict:
+    return json.loads(response.body)
+
+
+def test_service_error_uses_caller_model():
+    response = _handle_service_error(_request(), EntityNotFoundError("nope"), FakeApiMessage)
+    assert response.status_code == 404
+    assert _body(response) == {"message": "service error", "errors": ["nope"]}
+
+
+def test_unexpected_error_hides_detail_in_production():
+    response = _handle_unexpected_error(
+        _request(), ValueError("boom"), DefaultExceptionHandlerSettings(production=True), FakeApiMessage
+    )
+    assert response.status_code == 500
+    assert _body(response)["errors"] == []
+
+
+def test_unexpected_error_includes_detail_outside_production():
+    response = _handle_unexpected_error(
+        _request(), ValueError("boom"), DefaultExceptionHandlerSettings(production=False), FakeApiMessage
+    )
+    assert response.status_code == 500
+    assert _body(response)["errors"] == ["boom"]
+
+
+def test_validation_handler_uses_caller_model():
+    handler = build_validation_handler(FakeApiMessage)
+    exc = RequestValidationError([{"loc": ("body", "name"), "msg": "field required", "type": "missing", "input": None}])
+    response = asyncio.run(handler(_request(), exc))
+    assert response.status_code == 422
+    body = _body(response)
+    assert body["message"] == "Request Validation Error"
+    assert len(body["errors"]) == 1
+    assert "field required" in body["errors"][0]
+
+
+def test_build_error_responses_maps_caller_model():
+    responses = build_error_responses(FakeApiMessage)
+    for code in (
+        status.HTTP_401_UNAUTHORIZED,
+        status.HTTP_403_FORBIDDEN,
+        status.HTTP_404_NOT_FOUND,
+        status.HTTP_409_CONFLICT,
+        status.HTTP_422_UNPROCESSABLE_ENTITY,
+        status.HTTP_400_BAD_REQUEST,
+    ):
+        assert responses[code]["model"] is FakeApiMessage
+        assert responses[code]["description"]