csrd-service 0.1.0__py3-none-any.whl

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/_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/_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/_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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+csrd/service/__init__.py,sha256=F3qOtDjIUxjgrXIjZmN6Obwp7oWA9MScIacIonpd8eM,991
+csrd/service/_base_service.py,sha256=KE_8GLXjAP4uuUtV_LIn2rgzsSAnVMuE4R2z303xw1c,2277
+csrd/service/_errors.py,sha256=UMbBeIJ0afrrj3wQVRsdjSdcbOFsvMctkeAnU6lkqlg,3809
+csrd/service/_exception_handler.py,sha256=ZlpDGxPj-A9f9OQVTQneDl8v5k3lKCi2IaGnHArMrMo,2145
+csrd/service/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+csrd_service-0.1.0.dist-info/METADATA,sha256=pwnAeB5f4_GjmO2S1B04qll9AyOUfPxO3c8pbVSQsbY,466
+csrd_service-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+csrd_service-0.1.0.dist-info/RECORD,,

csrd_service-0.1.0.dist-info/WHEEL

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