csrd-service 0.1.0__tar.gz

csrd_service-0.1.0/.gitignore

@@ -0,0 +1,217 @@
+# 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
+
+# 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/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+*.db
+
+
+# Import linter cache
+.import_linter_cache/
+
+# IDE
+.idea/
+.idea/*

csrd_service-0.1.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: csrd-service
+Version: 0.1.0
+Summary: Service layer base class with domain error hierarchy
+Project-URL: Repository, https://github.com/csrd-api/fastapi-common
+Project-URL: Documentation, https://github.com/csrd-api/fastapi-common/tree/main/packages/service
+Project-URL: Changelog, https://github.com/csrd-api/fastapi-common/blob/main/CHANGELOG.md
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: csrd-context
+Requires-Dist: csrd-models

csrd_service-0.1.0/README.md

@@ -0,0 +1,98 @@
+# csrd.service
+
+Service-layer boilerplate for the **CSRD** pattern (Controller → Service → Repository / Delegate).
+
+## What it provides
+
+| Component | Purpose |
+|-----------|---------|
+| `BaseService` | Lightweight base class with per-class logger and request-context accessors (`current_user()`, `current_request_id()`) |
+| `ServiceError` | Base domain exception — keeps business logic free of `HTTPException` |
+| `NotFoundError` | 404 — resource doesn't exist |
+| `ConflictError` | 409 — duplicate, version mismatch, etc. |
+| `ValidationError` | 422 — business-rule validation (not schema validation) |
+| `AuthorizationError` | 403 — authenticated user lacks permission |
+| `DownstreamError` | 502 — a delegate call to another service failed |
+| `service_exception_handler` | FastAPI handler that maps any `ServiceError` → structured `APIErrorResponse` JSON |
+
+## Dependency tier
+
+```
+Tier 1 (standalone)     csrd.models · csrd.lifespan · csrd.context
+Tier 2 (uses Tier 1)    csrd.delegate · csrd.repository · csrd.service  ← NEW
+Tier 3 (uses Tier 1+2)  csrd.versioning
+```
+
+`csrd.service` depends on `csrd.context` and `csrd.models` only.  It does **not** import `csrd.repository` or `csrd.delegate` — your services accept those as constructor params.
+
+## Quick start
+
+```python
+from csrd.service import BaseService, NotFoundError, DownstreamError
+
+
+class OrderService(BaseService):
+    def __init__(self, repo: OrderRepository, payments: PaymentsDelegate):
+        super().__init__()
+        self._repo = repo
+        self._payments = payments
+
+    async def get_order(self, order_id: int) -> Order:
+        order = await self._repo.get_by_id(order_id)
+        if order is None:
+            raise NotFoundError("Order not found", detail=f"order_id={order_id}")
+        return order
+
+    async def place_order(self, cart: Cart) -> Order:
+        order = await self._repo.create(cart)
+        try:
+            await self._payments.charge(order)
+        except Exception as exc:
+            raise DownstreamError("Payment failed", cause=exc) from exc
+        return order
+```
+
+### Register the exception handler
+
+With `csrd.versioning`:
+
+```python
+from csrd.service import ServiceError, service_exception_handler
+
+configure_versioned_api(
+    app,
+    version_mapping=VERSIONS,
+    ex_handlers=[(ServiceError, service_exception_handler)],
+)
+```
+
+Or on a plain FastAPI app:
+
+```python
+app.add_exception_handler(ServiceError, service_exception_handler)
+```
+
+### Wire into FastAPI DI
+
+```python
+from functools import cache
+from typing import Annotated
+from fastapi import Depends
+
+@cache
+def order_service_factory(repo: OrderRepository, payments: PaymentsDelegate):
+    return OrderService(repo, payments)
+
+OrderServiceDep = Annotated[OrderService, Depends(order_service_factory)]
+
+# In your endpoint:
+@router.get("/orders/{order_id}")
+async def get_order(service: OrderServiceDep, order_id: int):
+    return await service.get_order(order_id)
+```
+
+## Installation
+
+```bash
+uv add csrd-service  # or: pip install csrd-service
+```

csrd_service-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "csrd-service"
+version = "0.1.0"
+description = "Service layer base class with domain error hierarchy"
+license = { text = "MIT" }
+requires-python = ">=3.12"
+dependencies = [
+    "csrd-context",
+    "csrd-models",
+]
+
+[tool.uv.sources]
+csrd-context = { workspace = true }
+csrd-models = { workspace = true }
+
+[project.urls]
+Repository = "https://github.com/csrd-api/fastapi-common"
+Documentation = "https://github.com/csrd-api/fastapi-common/tree/main/packages/service"
+Changelog = "https://github.com/csrd-api/fastapi-common/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/csrd"]

csrd_service-0.1.0/src/csrd/service/__init__.py

@@ -0,0 +1,34 @@
+"""Service layer boilerplate for the CSRD pattern.
+
+The ``csrd.service`` package provides:
+
+* :class:`BaseService` — lightweight base with context accessors.
+* **Domain errors** — :class:`ServiceError` hierarchy
+  (:class:`NotFoundError`, :class:`ConflictError`, :class:`ValidationError`,
+  :class:`AuthorizationError`, :class:`DownstreamError`) that keep business
+  logic free of ``HTTPException``.
+* :func:`service_exception_handler` — FastAPI handler that maps any
+  ``ServiceError`` to a structured ``APIErrorResponse`` JSON body.
+"""
+
+from ._base_service import BaseService
+from ._errors import (
+    AuthorizationError,
+    ConflictError,
+    DownstreamError,
+    NotFoundError,
+    ServiceError,
+    ValidationError,
+)
+from ._exception_handler import service_exception_handler
+
+__all__ = (
+    "AuthorizationError",
+    "BaseService",
+    "ConflictError",
+    "DownstreamError",
+    "NotFoundError",
+    "ServiceError",
+    "ValidationError",
+    "service_exception_handler",
+)

csrd_service-0.1.0/src/csrd/service/_base_service.py

@@ -0,0 +1,66 @@
+"""Lightweight base class for service-layer components.
+
+``BaseService`` provides:
+
+* Accessor helpers for the current request context (user claims, hit-id)
+  via ``csrd.context``.
+* A thin wrapper so subclasses can declare their repositories / delegates
+  as plain constructor params — no magic, just a convenient base.
+
+For logging, compose with ``LoggingMixin`` from ``csrd.logging``::
+
+    from csrd.logging import LoggingMixin
+
+    class OrderService(BaseService, LoggingMixin, auto_log=True):
+        def __init__(self, repo: OrderRepository, payments: PaymentsDelegate):
+            super().__init__()
+            self._repo = repo
+            self._payments = payments
+
+        async def place_order(self, cart: Cart) -> Order:
+            order = await self._repo.create(cart)
+            try:
+                await self._payments.charge(order)
+            except HTTPException as exc:
+                raise DownstreamError(
+                    "Payment failed", detail=str(exc.detail), cause=exc
+                ) from exc
+            return order
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from csrd.context import get_hit_id
+from csrd.context.platform import user_info_context
+
+if TYPE_CHECKING:
+    from csrd.models.claims import UserClaims
+
+
+class BaseService:
+    """Base class for service-layer components.
+
+    Provides contextual accessors for the current request.  For logging,
+    compose with :class:`csrd.logging.LoggingMixin`.
+
+    Subclasses should accept their repositories and delegates via
+    ``__init__`` — ``BaseService`` intentionally knows nothing about
+    those Tier-2 types so that it stays in Tier 2 itself.
+    """
+
+    # ── Context helpers ──────────────────────────────────────────────────
+
+    @staticmethod
+    def current_user() -> UserClaims | None:
+        """Return the authenticated user's claims for the current request, or ``None``."""
+        return user_info_context.get()  # type: ignore[return-value]
+
+    @staticmethod
+    def current_request_id() -> str | None:
+        """Return the current request's hit-id, or ``None``."""
+        return get_hit_id()
+
+
+__all__ = ("BaseService",)

csrd_service-0.1.0/src/csrd/service/_errors.py

@@ -0,0 +1,135 @@
+"""Domain error hierarchy for the service layer.
+
+Services raise these instead of ``HTTPException`` — keeping business logic
+transport-agnostic.  The versioning framework's exception handler (or a
+standalone handler registered via ``service_exception_handler``) maps them
+to structured ``APIErrorResponse`` JSON automatically.
+
+Each error carries:
+
+* ``message`` — human-readable summary (becomes the ``meta.error`` field)
+* ``detail`` — optional extended description (becomes ``errors[0].detail``)
+* ``code`` — optional machine-readable error code (e.g. ``"DUPLICATE_EMAIL"``)
+* ``status_code`` — HTTP status the handler will use (class-level default,
+  overridable per-instance)
+"""
+
+from __future__ import annotations
+
+
+class ServiceError(Exception):
+    """Base class for all domain/service-layer errors.
+
+    Subclasses set ``status_code`` as a class attribute.  Individual
+    raises can override via the constructor keyword.
+    """
+
+    status_code: int = 500
+
+    def __init__(
+        self,
+        message: str = "Internal service error",
+        *,
+        detail: str | None = None,
+        code: str | None = None,
+        status_code: int | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.detail = detail
+        self.code = code
+        if status_code is not None:
+            self.status_code = status_code
+
+
+class NotFoundError(ServiceError):
+    """The requested resource does not exist."""
+
+    status_code: int = 404
+
+    def __init__(
+        self,
+        message: str = "Resource not found",
+        *,
+        detail: str | None = None,
+        code: str | None = None,
+        status_code: int | None = None,
+    ) -> None:
+        super().__init__(message, detail=detail, code=code, status_code=status_code)
+
+
+class ConflictError(ServiceError):
+    """A write was rejected due to a conflict (duplicate, version mismatch, …)."""
+
+    status_code: int = 409
+
+    def __init__(
+        self,
+        message: str = "Conflict",
+        *,
+        detail: str | None = None,
+        code: str | None = None,
+        status_code: int | None = None,
+    ) -> None:
+        super().__init__(message, detail=detail, code=code, status_code=status_code)
+
+
+class ValidationError(ServiceError):
+    """Business-rule validation failed (distinct from request-schema validation)."""
+
+    status_code: int = 422
+
+    def __init__(
+        self,
+        message: str = "Validation failed",
+        *,
+        detail: str | None = None,
+        code: str | None = None,
+        status_code: int | None = None,
+    ) -> None:
+        super().__init__(message, detail=detail, code=code, status_code=status_code)
+
+
+class AuthorizationError(ServiceError):
+    """The authenticated user is not allowed to perform this action."""
+
+    status_code: int = 403
+
+    def __init__(
+        self,
+        message: str = "Forbidden",
+        *,
+        detail: str | None = None,
+        code: str | None = None,
+        status_code: int | None = None,
+    ) -> None:
+        super().__init__(message, detail=detail, code=code, status_code=status_code)
+
+
+class DownstreamError(ServiceError):
+    """A call to a downstream service (via a delegate) failed."""
+
+    status_code: int = 502
+
+    def __init__(
+        self,
+        message: str = "Downstream service error",
+        *,
+        detail: str | None = None,
+        code: str | None = None,
+        status_code: int | None = None,
+        cause: Exception | None = None,
+    ) -> None:
+        super().__init__(message, detail=detail, code=code, status_code=status_code)
+        if cause is not None:
+            self.__cause__ = cause
+
+
+__all__ = (
+    "AuthorizationError",
+    "ConflictError",
+    "DownstreamError",
+    "NotFoundError",
+    "ServiceError",
+    "ValidationError",
+)

csrd_service-0.1.0/src/csrd/service/_exception_handler.py

@@ -0,0 +1,73 @@
+"""FastAPI exception handler that maps ``ServiceError`` to ``APIErrorResponse``.
+
+Register with ``configure_versioned_api``::
+
+    from csrd.service import ServiceError, service_exception_handler
+
+    configure_versioned_api(
+        app,
+        version_mapping=VERSIONS,
+        ex_handlers=[(ServiceError, service_exception_handler)],
+    )
+
+Or register directly on a plain FastAPI app::
+
+    app.add_exception_handler(ServiceError, service_exception_handler)
+"""
+
+from __future__ import annotations
+
+import contextlib
+import datetime
+import uuid
+from datetime import UTC
+
+from fastapi import Request
+from fastapi.responses import JSONResponse
+
+from csrd.models.errors import APIErrorResponse, APIVersion, Error, ErrorMeta
+
+from ._errors import ServiceError
+
+
+def _get_request_id(request: Request) -> str:
+    """Best-effort extraction of request ID from scope, falling back to a UUID."""
+    try:
+        return str(request.scope["_request_context"]["hit_id"])
+    except (KeyError, TypeError):
+        return str(uuid.uuid4())
+
+
+def _get_api_version(request: Request) -> APIVersion:
+    served = None
+    with contextlib.suppress(AttributeError, TypeError):
+        served = request.scope.get("api_version")  # type: ignore[union-attr]
+    return APIVersion(served=served)
+
+
+async def service_exception_handler(request: Request, exc: ServiceError) -> JSONResponse:
+    """Convert a :class:`ServiceError` into a structured ``APIErrorResponse``."""
+    errors: list[Error] = []
+    if exc.detail or exc.code:
+        errors.append(Error(title=exc.message, detail=exc.detail, code=exc.code))
+
+    body = APIErrorResponse(
+        meta=ErrorMeta(
+            status=exc.status_code,
+            error=exc.message,
+            method=request.method,
+            path=request.url.path,
+            request_id=_get_request_id(request),
+            timestamp=datetime.datetime.now(UTC),
+            api_version=_get_api_version(request),
+        ),
+        errors=errors,
+    )
+
+    return JSONResponse(
+        status_code=exc.status_code,
+        content=body.as_dict(by_alias=True, mode="json"),
+    )
+
+
+__all__ = ("service_exception_handler",)

csrd_service-0.1.0/tests/test_service.py

@@ -0,0 +1,194 @@
+"""Tests for csrd.service — errors, BaseService, and exception handler."""
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from csrd.service import (
+    AuthorizationError,
+    BaseService,
+    ConflictError,
+    DownstreamError,
+    NotFoundError,
+    ServiceError,
+    ValidationError,
+    service_exception_handler,
+)
+
+# ── Domain Errors ────────────────────────────────────────────────────────
+
+
+class TestServiceError:
+    def test_default_message(self):
+        err = ServiceError()
+        assert str(err) == "Internal service error"
+        assert err.status_code == 500
+
+    def test_custom_message(self):
+        err = ServiceError("boom", detail="something broke", code="ERR_001")
+        assert err.message == "boom"
+        assert err.detail == "something broke"
+        assert err.code == "ERR_001"
+
+    def test_status_code_override(self):
+        err = ServiceError("custom", status_code=418)
+        assert err.status_code == 418
+
+    def test_is_exception(self):
+        with pytest.raises(ServiceError):
+            raise ServiceError("test")
+
+
+class TestNotFoundError:
+    def test_defaults(self):
+        err = NotFoundError()
+        assert err.status_code == 404
+        assert err.message == "Resource not found"
+
+    def test_custom(self):
+        err = NotFoundError("Order not found", detail="order_id=42", code="ORDER_MISSING")
+        assert err.status_code == 404
+        assert err.message == "Order not found"
+        assert err.detail == "order_id=42"
+        assert err.code == "ORDER_MISSING"
+
+    def test_is_service_error(self):
+        assert isinstance(NotFoundError(), ServiceError)
+
+
+class TestConflictError:
+    def test_defaults(self):
+        err = ConflictError()
+        assert err.status_code == 409
+        assert err.message == "Conflict"
+
+
+class TestValidationError:
+    def test_defaults(self):
+        err = ValidationError()
+        assert err.status_code == 422
+        assert err.message == "Validation failed"
+
+
+class TestAuthorizationError:
+    def test_defaults(self):
+        err = AuthorizationError()
+        assert err.status_code == 403
+        assert err.message == "Forbidden"
+
+
+class TestDownstreamError:
+    def test_defaults(self):
+        err = DownstreamError()
+        assert err.status_code == 502
+        assert err.message == "Downstream service error"
+
+    def test_with_cause(self):
+        cause = ValueError("connection refused")
+        err = DownstreamError("Payment service down", cause=cause)
+        assert err.__cause__ is cause
+
+    def test_subclass_hierarchy(self):
+        """All errors should be catchable as ServiceError."""
+        for cls in (
+            NotFoundError,
+            ConflictError,
+            ValidationError,
+            AuthorizationError,
+            DownstreamError,
+        ):
+            assert issubclass(cls, ServiceError)
+
+
+# ── BaseService ──────────────────────────────────────────────────────────
+
+
+class TestBaseService:
+    def test_current_user_none_outside_request(self):
+        svc = BaseService()
+        assert svc.current_user() is None
+
+    def test_current_request_id_none_outside_request(self):
+        svc = BaseService()
+        assert svc.current_request_id() is None
+
+
+# ── Exception Handler ────────────────────────────────────────────────────
+
+
+class TestServiceExceptionHandler:
+    def _make_app(self) -> FastAPI:
+        app = FastAPI()
+        app.add_exception_handler(ServiceError, service_exception_handler)  # type: ignore[arg-type]
+
+        @app.get("/not-found")
+        async def _not_found():
+            raise NotFoundError("User not found", detail="id=99", code="USER_MISSING")
+
+        @app.get("/conflict")
+        async def _conflict():
+            raise ConflictError("Duplicate email")
+
+        @app.get("/forbidden")
+        async def _forbidden():
+            raise AuthorizationError()
+
+        @app.get("/downstream")
+        async def _downstream():
+            raise DownstreamError("Payments unavailable", status_code=503)
+
+        @app.get("/bare")
+        async def _bare():
+            raise ServiceError()
+
+        return app
+
+    def test_not_found_response(self):
+        client = TestClient(self._make_app(), raise_server_exceptions=False)
+        resp = client.get("/not-found")
+        assert resp.status_code == 404
+        body = resp.json()
+        assert body["meta"]["status"] == 404
+        assert body["meta"]["error"] == "User not found"
+        assert body["errors"][0]["detail"] == "id=99"
+        assert body["errors"][0]["code"] == "USER_MISSING"
+
+    def test_conflict_response(self):
+        client = TestClient(self._make_app(), raise_server_exceptions=False)
+        resp = client.get("/conflict")
+        assert resp.status_code == 409
+        assert resp.json()["meta"]["error"] == "Duplicate email"
+
+    def test_forbidden_response(self):
+        client = TestClient(self._make_app(), raise_server_exceptions=False)
+        resp = client.get("/forbidden")
+        assert resp.status_code == 403
+
+    def test_downstream_with_custom_status(self):
+        client = TestClient(self._make_app(), raise_server_exceptions=False)
+        resp = client.get("/downstream")
+        assert resp.status_code == 503
+
+    def test_bare_service_error(self):
+        client = TestClient(self._make_app(), raise_server_exceptions=False)
+        resp = client.get("/bare")
+        assert resp.status_code == 500
+        body = resp.json()
+        assert body["meta"]["error"] == "Internal service error"
+        # No detail/code → errors list should be empty
+        assert body["errors"] == []
+
+    def test_response_has_camel_case_keys(self):
+        client = TestClient(self._make_app(), raise_server_exceptions=False)
+        resp = client.get("/not-found")
+        body = resp.json()
+        # meta fields should be camelCase
+        assert "requestId" in body["meta"]
+        assert "apiVersion" in body["meta"]
+
+    def test_response_has_method_and_path(self):
+        client = TestClient(self._make_app(), raise_server_exceptions=False)
+        resp = client.get("/not-found")
+        meta = resp.json()["meta"]
+        assert meta["method"] == "GET"
+        assert meta["path"] == "/not-found"