msaas-errors 0.1.0__py3-none-any.whl

errors/__init__.py

@@ -0,0 +1,52 @@
+"""willian-errors: Standardized error handling for willian-* backend APIs."""
+
+from errors.config import ErrorConfig, init_errors
+from errors.context import ErrorContext, with_error_context
+from errors.exceptions import (
+    AppError,
+    AuthenticationError,
+    AuthorizationError,
+    BusinessLogicError,
+    ConflictError,
+    ExternalServiceError,
+    InternalError,
+    NotFoundError,
+    RateLimitError,
+    ValidationError,
+)
+from errors.handler import setup_error_handling
+from errors.monitoring import ErrorMetrics, ErrorMonitoringHook, MonitoringBridge
+from errors.problem_details import ProblemDetail, from_problem_detail, to_problem_detail
+from errors.responses import ErrorResponse, ValidationErrorResponse, error_responses
+from errors.retry import retriable
+from errors.severity import ErrorCategory, ErrorSeverity
+
+__all__ = [
+    "AppError",
+    "AuthenticationError",
+    "AuthorizationError",
+    "BusinessLogicError",
+    "ConflictError",
+    "ErrorCategory",
+    "ErrorConfig",
+    "ErrorContext",
+    "ErrorMetrics",
+    "ErrorMonitoringHook",
+    "ErrorResponse",
+    "ErrorSeverity",
+    "ExternalServiceError",
+    "InternalError",
+    "MonitoringBridge",
+    "NotFoundError",
+    "ProblemDetail",
+    "RateLimitError",
+    "ValidationError",
+    "ValidationErrorResponse",
+    "error_responses",
+    "from_problem_detail",
+    "init_errors",
+    "retriable",
+    "setup_error_handling",
+    "to_problem_detail",
+    "with_error_context",
+]

errors/config.py

@@ -0,0 +1,71 @@
+"""Global error handling configuration.
+
+Call ``init_errors(config)`` once at application startup to set defaults
+used by the handler, problem detail serializer, and logging integration.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from errors.monitoring import MonitoringBridge
+
+# Module-level singleton -- mutated by init_errors, read everywhere else.
+_config: ErrorConfig | None = None
+
+# Separate module-level storage for the monitoring bridge (not frozen).
+_monitoring: MonitoringBridge | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ErrorConfig:
+    """Configuration for the willian-errors library."""
+
+    include_stacktrace: bool = False
+    """Include stack traces in error responses. Never enable in production."""
+
+    type_base_url: str = "https://errors.willian.dev/"
+    """Base URL for RFC 7807 ``type`` URIs."""
+
+    log_level: str = "ERROR"
+    """Default log level for captured errors."""
+
+    default_tags: dict[str, str] = field(default_factory=dict)
+    """Default tags applied to all errors (e.g. service, env)."""
+
+
+def init_errors(
+    config: ErrorConfig | None = None,
+    *,
+    monitoring: MonitoringBridge | None = None,
+) -> ErrorConfig:
+    """Initialize the global error configuration.
+
+    Can be called multiple times; the last call wins.
+    Returns the active config.
+    """
+    global _config, _monitoring  # noqa: PLW0603
+    _config = config or ErrorConfig()
+    _monitoring = monitoring
+    return _config
+
+
+def get_config() -> ErrorConfig:
+    """Return the active config, lazily initializing with defaults if needed."""
+    global _config  # noqa: PLW0603
+    if _config is None:
+        _config = ErrorConfig()
+    return _config
+
+
+def get_monitoring() -> MonitoringBridge | None:
+    """Return the active monitoring bridge, or None if not configured."""
+    return _monitoring
+
+
+def set_monitoring(bridge: MonitoringBridge) -> None:
+    """Set the global monitoring bridge."""
+    global _monitoring  # noqa: PLW0603
+    _monitoring = bridge

errors/context.py

@@ -0,0 +1,65 @@
+"""Error context propagation via ContextVars.
+
+Provides a request-scoped context (request_id, user_id, endpoint, etc.)
+that is automatically attached to error responses by the handler.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from typing import Any
+
+_error_context_var: ContextVar[ErrorContext | None] = ContextVar("error_context", default=None)
+
+
+@dataclass(slots=True)
+class ErrorContext:
+    """Request-scoped metadata attached to error responses."""
+
+    request_id: str | None = None
+    user_id: str | None = None
+    endpoint: str | None = None
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize non-None fields to a dict."""
+        result: dict[str, Any] = {}
+        if self.request_id:
+            result["request_id"] = self.request_id
+        if self.user_id:
+            result["user_id"] = self.user_id
+        if self.endpoint:
+            result["endpoint"] = self.endpoint
+        if self.extra:
+            result.update(self.extra)
+        return result
+
+
+@contextmanager
+def with_error_context(
+    *,
+    request_id: str | None = None,
+    user_id: str | None = None,
+    endpoint: str | None = None,
+    **extra: Any,
+) -> Iterator[ErrorContext]:
+    """Set error context for the current scope. Restores previous on exit."""
+    ctx = ErrorContext(
+        request_id=request_id,
+        user_id=user_id,
+        endpoint=endpoint,
+        extra=extra,
+    )
+    token = _error_context_var.set(ctx)
+    try:
+        yield ctx
+    finally:
+        _error_context_var.reset(token)
+
+
+def get_error_context() -> ErrorContext | None:
+    """Return the current error context, or None if not set."""
+    return _error_context_var.get()

errors/exceptions.py

@@ -0,0 +1,261 @@
+"""Exception hierarchy for willian-* backend APIs.
+
+All application errors inherit from AppError and carry structured metadata
+(status_code, error_code, message, details, severity, category) for
+consistent API responses and monitoring integration.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import uuid
+from typing import Any
+
+from errors.severity import ErrorCategory, ErrorSeverity
+
+
+class AppError(Exception):
+    """Base application error with structured metadata for API responses."""
+
+    status_code: int = 500
+    error_code: str = "INTERNAL_ERROR"
+    default_severity: ErrorSeverity = ErrorSeverity.ERROR
+    default_category: ErrorCategory = ErrorCategory.SERVER
+    default_is_retryable: bool = False
+
+    def __init__(
+        self,
+        message: str = "An unexpected error occurred",
+        *,
+        details: dict[str, Any] | None = None,
+        status_code: int | None = None,
+        error_code: str | None = None,
+        severity: ErrorSeverity | None = None,
+        category: ErrorCategory | None = None,
+        tags: dict[str, str] | None = None,
+        is_retryable: bool | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.details = details or {}
+        if status_code is not None:
+            self.status_code = status_code
+        if error_code is not None:
+            self.error_code = error_code
+
+        # Monitoring fields
+        self.severity = severity or self.default_severity
+        self.category = category or self.default_category
+        self.error_id = uuid.uuid4().hex[:12]
+        self.tags: dict[str, str] = tags or {}
+        self.is_retryable = is_retryable if is_retryable is not None else self.default_is_retryable
+
+    @property
+    def fingerprint(self) -> str:
+        """Grouping key for monitoring tools (error_code + message hash)."""
+        msg_hash = hashlib.md5(self.message.encode(), usedforsecurity=False).hexdigest()[:8]
+        return f"{self.error_code}:{msg_hash}"
+
+    @property
+    def metric_name(self) -> str:
+        """Dot-separated metric name for counters."""
+        return f"errors.{self.category.value}"
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}("
+            f"status_code={self.status_code}, "
+            f"error_code={self.error_code!r}, "
+            f"message={self.message!r}, "
+            f"severity={self.severity.name})"
+        )
+
+
+class ValidationError(AppError):
+    """Request validation failed (422). Carries field-level error details."""
+
+    status_code: int = 422
+    error_code: str = "VALIDATION_ERROR"
+    default_severity: ErrorSeverity = ErrorSeverity.WARNING
+    default_category: ErrorCategory = ErrorCategory.VALIDATION
+
+    def __init__(
+        self,
+        message: str = "Validation failed",
+        *,
+        field_errors: list[dict[str, Any]] | None = None,
+        details: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        merged = dict(details or {})
+        if field_errors is not None:
+            merged["field_errors"] = field_errors
+        super().__init__(message, details=merged, **kwargs)
+        self.field_errors = field_errors or []
+
+
+class NotFoundError(AppError):
+    """Resource not found (404)."""
+
+    status_code: int = 404
+    error_code: str = "NOT_FOUND"
+    default_severity: ErrorSeverity = ErrorSeverity.INFO
+    default_category: ErrorCategory = ErrorCategory.NOT_FOUND
+
+    def __init__(
+        self,
+        message: str = "Resource not found",
+        *,
+        resource_type: str | None = None,
+        resource_id: str | None = None,
+        details: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        merged = dict(details or {})
+        if resource_type:
+            merged["resource_type"] = resource_type
+        if resource_id:
+            merged["resource_id"] = resource_id
+        super().__init__(message, details=merged, **kwargs)
+
+
+class ConflictError(AppError):
+    """Resource conflict (409)."""
+
+    status_code: int = 409
+    error_code: str = "CONFLICT"
+    default_severity: ErrorSeverity = ErrorSeverity.WARNING
+    default_category: ErrorCategory = ErrorCategory.CONFLICT
+
+    def __init__(
+        self,
+        message: str = "Resource conflict",
+        *,
+        details: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, details=details, **kwargs)
+
+
+class AuthenticationError(AppError):
+    """Authentication required or failed (401)."""
+
+    status_code: int = 401
+    error_code: str = "AUTHENTICATION_ERROR"
+    default_severity: ErrorSeverity = ErrorSeverity.WARNING
+    default_category: ErrorCategory = ErrorCategory.AUTHENTICATION
+
+    def __init__(
+        self,
+        message: str = "Authentication required",
+        *,
+        details: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, details=details, **kwargs)
+
+
+class AuthorizationError(AppError):
+    """Insufficient permissions (403)."""
+
+    status_code: int = 403
+    error_code: str = "AUTHORIZATION_ERROR"
+    default_severity: ErrorSeverity = ErrorSeverity.WARNING
+    default_category: ErrorCategory = ErrorCategory.AUTHORIZATION
+
+    def __init__(
+        self,
+        message: str = "Permission denied",
+        *,
+        details: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, details=details, **kwargs)
+
+
+class RateLimitError(AppError):
+    """Rate limit exceeded (429). Includes retry_after hint."""
+
+    status_code: int = 429
+    error_code: str = "RATE_LIMIT_EXCEEDED"
+    default_severity: ErrorSeverity = ErrorSeverity.INFO
+    default_category: ErrorCategory = ErrorCategory.RATE_LIMIT
+    default_is_retryable: bool = True
+
+    def __init__(
+        self,
+        message: str = "Rate limit exceeded",
+        *,
+        retry_after: int | None = None,
+        details: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        merged = dict(details or {})
+        if retry_after is not None:
+            merged["retry_after"] = retry_after
+        super().__init__(message, details=merged, **kwargs)
+        self.retry_after = retry_after
+
+
+class ExternalServiceError(AppError):
+    """Upstream/external service failure (502)."""
+
+    status_code: int = 502
+    error_code: str = "EXTERNAL_SERVICE_ERROR"
+    default_severity: ErrorSeverity = ErrorSeverity.ERROR
+    default_category: ErrorCategory = ErrorCategory.INFRASTRUCTURE
+    default_is_retryable: bool = True
+
+    def __init__(
+        self,
+        message: str = "External service unavailable",
+        *,
+        service_name: str | None = None,
+        details: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        merged = dict(details or {})
+        if service_name:
+            merged["service_name"] = service_name
+        super().__init__(message, details=merged, **kwargs)
+
+
+class InternalError(AppError):
+    """Generic internal server error (500)."""
+
+    status_code: int = 500
+    error_code: str = "INTERNAL_ERROR"
+    default_severity: ErrorSeverity = ErrorSeverity.CRITICAL
+    default_category: ErrorCategory = ErrorCategory.SERVER
+
+    def __init__(
+        self,
+        message: str = "An unexpected error occurred",
+        *,
+        details: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, details=details, **kwargs)
+
+
+class BusinessLogicError(AppError):
+    """Business rule violation (422)."""
+
+    status_code: int = 422
+    error_code: str = "BUSINESS_LOGIC_ERROR"
+    default_severity: ErrorSeverity = ErrorSeverity.WARNING
+    default_category: ErrorCategory = ErrorCategory.BUSINESS_LOGIC
+
+    def __init__(
+        self,
+        message: str = "Business rule violation",
+        *,
+        rule: str | None = None,
+        details: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        merged = dict(details or {})
+        if rule:
+            merged["rule"] = rule
+        super().__init__(message, details=merged, **kwargs)
+        self.rule = rule

errors/handler.py

@@ -0,0 +1,179 @@
+"""FastAPI error handler integration.
+
+Call ``setup_error_handling(app)`` to register exception handlers that convert
+all errors into RFC 7807 Problem Details JSON responses.
+"""
+
+from __future__ import annotations
+
+import logging
+import traceback
+import uuid
+from typing import TYPE_CHECKING, Any
+
+from errors.config import get_config, get_monitoring
+from errors.context import get_error_context, with_error_context
+from errors.exceptions import AppError, RateLimitError, ValidationError
+from errors.problem_details import ProblemDetail, to_problem_detail
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI, Request
+    from fastapi.responses import JSONResponse
+
+logger = logging.getLogger("errors")
+
+
+def _try_structlog() -> Any:
+    """Return structlog.get_logger if structlog is installed, else None."""
+    try:
+        import structlog
+
+        return structlog.get_logger("errors")
+    except ImportError:
+        return None
+
+
+def _get_logger() -> Any:
+    """Return a structlog logger if available, otherwise stdlib logger."""
+    return _try_structlog() or logger
+
+
+def _extract_request_id(request: Any) -> str:
+    """Extract request_id from header or generate a new one."""
+    for header in ("x-request-id", "x-trace-id", "request-id"):
+        value = request.headers.get(header)
+        if value:
+            return value
+    return uuid.uuid4().hex[:16]
+
+
+def _build_unhandled_response(request: Any, exc: Exception, request_id: str) -> Any:
+    """Build a JSON response for an unhandled exception."""
+    from fastapi.responses import JSONResponse
+
+    config = get_config()
+    log = _get_logger()
+    log.error(
+        "unhandled_exception",
+        exc_type=type(exc).__name__,
+        message=str(exc),
+        request_id=request_id,
+    )
+
+    extensions: dict[str, Any] = {"request_id": request_id}
+    if config.include_stacktrace:
+        extensions["stacktrace"] = traceback.format_exception(exc)
+
+    pd = ProblemDetail(
+        type=f"{config.type_base_url.rstrip('/')}/internal-error",
+        title="Internal Error",
+        status=500,
+        detail="An unexpected error occurred",
+        instance=str(request.url),
+        error_code="INTERNAL_ERROR",
+        extensions=extensions,
+    )
+    return JSONResponse(
+        status_code=500,
+        content=pd.model_dump(exclude_none=True),
+        media_type="application/problem+json",
+    )
+
+
+def setup_error_handling(app: FastAPI) -> None:
+    """Register exception handlers on a FastAPI application."""
+    from fastapi.exceptions import RequestValidationError
+    from fastapi.responses import JSONResponse
+    from starlette.middleware.base import BaseHTTPMiddleware
+
+    class ErrorContextMiddleware(BaseHTTPMiddleware):
+        """Populate error context and catch unhandled exceptions."""
+
+        async def dispatch(self, request: Request, call_next: Any) -> Any:
+            request_id = _extract_request_id(request)
+            with with_error_context(
+                request_id=request_id,
+                endpoint=f"{request.method} {request.url.path}",
+            ):
+                try:
+                    response = await call_next(request)
+                    response.headers["x-request-id"] = request_id
+                    return response
+                except Exception as exc:
+                    # AppError and RequestValidationError are handled by
+                    # dedicated handlers registered below.
+                    if isinstance(exc, (AppError, RequestValidationError)):
+                        raise
+                    return _build_unhandled_response(request, exc, request_id)
+
+    app.add_middleware(ErrorContextMiddleware)
+
+    @app.exception_handler(AppError)
+    async def _handle_app_error(request: Request, exc: AppError) -> JSONResponse:
+        ctx = get_error_context()
+        request_id = ctx.request_id if ctx else _extract_request_id(request)
+
+        # Apply default tags from config
+        config = get_config()
+        if config.default_tags:
+            for k, v in config.default_tags.items():
+                exc.tags.setdefault(k, v)
+
+        log = _get_logger()
+        log_method = getattr(log, "warning" if exc.status_code < 500 else "error", log.error)
+        log_method(
+            "app_error",
+            error_code=exc.error_code,
+            status_code=exc.status_code,
+            message=exc.message,
+            severity=exc.severity.name,
+            category=exc.category.value,
+            error_id=exc.error_id,
+            is_retryable=exc.is_retryable,
+            request_id=request_id,
+        )
+
+        # Report to monitoring bridge
+        monitoring = get_monitoring()
+        if monitoring:
+            await monitoring.report(exc, ctx)
+
+        pd = to_problem_detail(exc, instance=str(request.url))
+        pd.extensions["request_id"] = request_id
+        if ctx:
+            pd.extensions.update({k: v for k, v in ctx.to_dict().items() if k != "request_id"})
+
+        headers: dict[str, str] = {}
+        if isinstance(exc, RateLimitError) and exc.retry_after is not None:
+            headers["Retry-After"] = str(exc.retry_after)
+
+        return JSONResponse(
+            status_code=exc.status_code,
+            content=pd.model_dump(exclude_none=True),
+            headers=headers or None,
+            media_type="application/problem+json",
+        )
+
+    @app.exception_handler(RequestValidationError)
+    async def _handle_validation_error(
+        request: Request, exc: RequestValidationError
+    ) -> JSONResponse:
+        field_errors = [
+            {
+                "field": ".".join(str(loc) for loc in err.get("loc", ())),
+                "message": err.get("msg", "Invalid value"),
+                "type": err.get("type", "value_error"),
+            }
+            for err in exc.errors()
+        ]
+        app_error = ValidationError(
+            message="Request validation failed",
+            field_errors=field_errors,
+        )
+        return await _handle_app_error(request, app_error)
+
+    @app.exception_handler(Exception)
+    async def _handle_unhandled(request: Request, exc: Exception) -> JSONResponse:
+        ctx = get_error_context()
+        request_id = ctx.request_id if ctx else _extract_request_id(request)
+        return _build_unhandled_response(request, exc, request_id)

errors/monitoring.py

@@ -0,0 +1,120 @@
+"""Error monitoring bridge and in-process metrics collector.
+
+Provides a protocol for external monitoring tool integration (Datadog, Sentry,
+Grafana) and an in-process metrics collector for error counters and summaries.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections import deque
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from errors.context import ErrorContext
+    from errors.exceptions import AppError
+
+logger = logging.getLogger("errors.monitoring")
+
+MAX_RECENT_ERRORS = 100
+
+
+@runtime_checkable
+class ErrorMonitoringHook(Protocol):
+    """Protocol for monitoring tool integration.
+
+    Implement this protocol to send errors to external monitoring systems.
+    """
+
+    async def on_error(self, error: AppError, context: ErrorContext | None) -> None: ...
+
+
+class ErrorMetrics:
+    """In-process error metrics collector.
+
+    Tracks error counts by code, severity, and category, plus a ring buffer
+    of recent errors for inspection via health/metrics endpoints.
+    """
+
+    def __init__(self) -> None:
+        self._counters: dict[str, int] = {}
+        self._by_severity: dict[str, int] = {}
+        self._by_category: dict[str, int] = {}
+        self._recent: deque[dict[str, Any]] = deque(maxlen=MAX_RECENT_ERRORS)
+
+    def record(self, error: AppError) -> None:
+        """Record an error occurrence for metrics."""
+        code = error.error_code
+        severity = error.severity.name
+        category = error.category.value
+
+        self._counters[code] = self._counters.get(code, 0) + 1
+        self._by_severity[severity] = self._by_severity.get(severity, 0) + 1
+        self._by_category[category] = self._by_category.get(category, 0) + 1
+
+        self._recent.append(
+            {
+                "error_id": error.error_id,
+                "error_code": code,
+                "message": error.message,
+                "severity": severity,
+                "category": category,
+                "fingerprint": error.fingerprint,
+                "is_retryable": error.is_retryable,
+                "timestamp": datetime.now(UTC).isoformat(),
+            }
+        )
+
+    def get_summary(self) -> dict[str, Any]:
+        """Get error metrics summary (for /health or /metrics endpoint)."""
+        return {
+            "total_errors": sum(self._counters.values()),
+            "by_code": dict(self._counters),
+            "by_severity": dict(self._by_severity),
+            "by_category": dict(self._by_category),
+            "recent_errors": list(self._recent)[-10:],
+        }
+
+    def reset(self) -> None:
+        """Reset all metrics to zero."""
+        self._counters.clear()
+        self._by_severity.clear()
+        self._by_category.clear()
+        self._recent.clear()
+
+
+class MonitoringBridge:
+    """Bridge to external monitoring tools.
+
+    Aggregates in-process metrics and dispatches error events to registered
+    monitoring hooks (Datadog, Sentry, etc). Hook failures are silently
+    caught to never break the application.
+    """
+
+    def __init__(self) -> None:
+        self._hooks: list[ErrorMonitoringHook] = []
+        self._metrics = ErrorMetrics()
+
+    def add_hook(self, hook: ErrorMonitoringHook) -> None:
+        """Register a monitoring hook."""
+        self._hooks.append(hook)
+
+    async def report(self, error: AppError, context: ErrorContext | None = None) -> None:
+        """Report error to all registered hooks and record metrics."""
+        self._metrics.record(error)
+        for hook in self._hooks:
+            try:
+                await hook.on_error(error, context)
+            except Exception:
+                logger.debug(
+                    "Monitoring hook %s failed for error %s",
+                    type(hook).__name__,
+                    error.error_id,
+                    exc_info=True,
+                )
+
+    @property
+    def metrics(self) -> ErrorMetrics:
+        """Return the in-process metrics collector."""
+        return self._metrics

errors/problem_details.py

@@ -0,0 +1,140 @@
+"""RFC 7807 Problem Details representation.
+
+Converts between ``AppError`` instances and the standard Problem Details
+JSON structure used in all willian-* API responses.
+
+Reference: https://www.rfc-editor.org/rfc/rfc7807
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from errors.config import get_config
+from errors.exceptions import AppError
+
+
+class ProblemDetail(BaseModel):
+    """RFC 7807 Problem Details model."""
+
+    type: str = Field(
+        default="about:blank",
+        description="URI reference identifying the problem type.",
+    )
+    title: str = Field(
+        default="Internal Server Error",
+        description="Short human-readable summary of the problem type.",
+    )
+    status: int = Field(
+        default=500,
+        description="HTTP status code.",
+    )
+    detail: str = Field(
+        default="An unexpected error occurred",
+        description="Human-readable explanation specific to this occurrence.",
+    )
+    instance: str | None = Field(
+        default=None,
+        description="URI reference identifying the specific occurrence.",
+    )
+    error_code: str = Field(
+        default="INTERNAL_ERROR",
+        description="Machine-readable error code.",
+    )
+    severity: str | None = Field(
+        default=None,
+        description="Error severity level (DEBUG, INFO, WARNING, ERROR, CRITICAL).",
+    )
+    category: str | None = Field(
+        default=None,
+        description="Error category for dashboarding.",
+    )
+    error_id: str | None = Field(
+        default=None,
+        description="Unique error occurrence identifier.",
+    )
+    is_retryable: bool = Field(
+        default=False,
+        description="Whether the client should retry the request.",
+    )
+    extensions: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Additional problem-specific properties.",
+    )
+
+    model_config = {"extra": "allow"}
+
+
+def _error_code_to_type_slug(error_code: str) -> str:
+    """Convert an error code like 'NOT_FOUND' to a URL slug 'not-found'."""
+    return error_code.lower().replace("_", "-")
+
+
+def to_problem_detail(
+    error: AppError,
+    *,
+    instance: str | None = None,
+    type_base_url: str | None = None,
+) -> ProblemDetail:
+    """Convert an AppError to an RFC 7807 ProblemDetail."""
+    config = get_config()
+    base_url = (type_base_url or config.type_base_url).rstrip("/")
+    slug = _error_code_to_type_slug(error.error_code)
+
+    return ProblemDetail(
+        type=f"{base_url}/{slug}",
+        title=error.error_code.replace("_", " ").title(),
+        status=error.status_code,
+        detail=error.message,
+        instance=instance,
+        error_code=error.error_code,
+        severity=error.severity.name,
+        category=error.category.value,
+        error_id=error.error_id,
+        is_retryable=error.is_retryable,
+        extensions=error.details,
+    )
+
+
+# Registry for reverse lookups -- maps error_code to AppError subclass.
+_ERROR_REGISTRY: dict[str, type[AppError]] = {}
+
+
+def _build_error_registry() -> dict[str, type[AppError]]:
+    """Build a registry of error_code -> AppError subclass (lazy, cached)."""
+    if _ERROR_REGISTRY:
+        return _ERROR_REGISTRY
+
+    def _collect(cls: type[AppError]) -> None:
+        code = cls.__dict__.get("error_code")
+        if code and cls is not AppError:
+            _ERROR_REGISTRY[code] = cls
+        for sub in cls.__subclasses__():
+            _collect(sub)
+
+    _collect(AppError)
+    return _ERROR_REGISTRY
+
+
+def from_problem_detail(pd: ProblemDetail) -> AppError:
+    """Reconstruct an AppError from an RFC 7807 ProblemDetail.
+
+    Falls back to a generic AppError if the error_code is not recognized.
+    Always constructs via the base ``AppError`` constructor to avoid
+    subclass-specific kwargs, then patches the class for ``isinstance`` checks.
+    """
+    registry = _build_error_registry()
+    error_cls = registry.get(pd.error_code, AppError)
+
+    # Build through AppError to avoid subclass __init__ signature mismatches,
+    # then set __class__ so isinstance() works as expected.
+    instance = AppError(
+        message=pd.detail,
+        status_code=pd.status,
+        error_code=pd.error_code,
+        details=pd.extensions,
+    )
+    instance.__class__ = error_cls
+    return instance

errors/responses.py

@@ -0,0 +1,84 @@
+"""OpenAPI response schema helpers for FastAPI routes.
+
+Usage::
+
+    from errors import error_responses
+
+    @router.get("/items/{id}", responses=error_responses(404, 422))
+    async def get_item(id: str): ...
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class FieldError(BaseModel):
+    """A single field-level validation error."""
+
+    field: str = Field(description="Dot-separated field path (e.g. 'body.email').")
+    message: str = Field(description="Human-readable error message.")
+    type: str = Field(description="Machine-readable error type.")
+
+
+class ErrorResponse(BaseModel):
+    """Standard RFC 7807 error response for OpenAPI docs."""
+
+    type: str = Field(
+        default="about:blank",
+        description="URI reference identifying the problem type.",
+    )
+    title: str = Field(description="Short summary of the problem.")
+    status: int = Field(description="HTTP status code.")
+    detail: str = Field(description="Explanation specific to this occurrence.")
+    instance: str | None = Field(default=None, description="URI of this occurrence.")
+    error_code: str = Field(description="Machine-readable error code.")
+    request_id: str | None = Field(default=None, description="Request trace identifier.")
+    severity: str = Field(default="ERROR", description="Error severity level.")
+    category: str = Field(default="server", description="Error category.")
+    error_id: str = Field(default="", description="Unique error occurrence identifier.")
+    is_retryable: bool = Field(default=False, description="Whether the client should retry.")
+
+
+class ValidationErrorResponse(ErrorResponse):
+    """Error response with field-level validation errors."""
+
+    field_errors: list[FieldError] = Field(
+        default_factory=list,
+        description="Field-level validation errors.",
+    )
+
+
+# Mapping of HTTP status codes to their OpenAPI schema descriptors.
+_STATUS_SCHEMAS: dict[int, dict[str, Any]] = {
+    400: {"description": "Bad Request", "model": ErrorResponse},
+    401: {"description": "Authentication Required", "model": ErrorResponse},
+    403: {"description": "Permission Denied", "model": ErrorResponse},
+    404: {"description": "Resource Not Found", "model": ErrorResponse},
+    409: {"description": "Resource Conflict", "model": ErrorResponse},
+    422: {"description": "Validation Error", "model": ValidationErrorResponse},
+    429: {"description": "Rate Limit Exceeded", "model": ErrorResponse},
+    500: {"description": "Internal Server Error", "model": ErrorResponse},
+    502: {"description": "External Service Error", "model": ErrorResponse},
+}
+
+
+def error_responses(*status_codes: int) -> dict[int, dict[str, Any]]:
+    """Generate OpenAPI ``responses`` dict for the given status codes.
+
+    Example::
+
+        @router.get("/items/{id}", responses=error_responses(404, 422))
+        async def get_item(id: str): ...
+
+    Returns a dict like ``{404: {"description": ..., "model": ...}}``.
+    """
+    result: dict[int, dict[str, Any]] = {}
+    for code in status_codes:
+        if code in _STATUS_SCHEMAS:
+            result[code] = _STATUS_SCHEMAS[code]
+        else:
+            result[code] = {"description": f"Error {code}", "model": ErrorResponse}
+    return result

errors/retry.py

@@ -0,0 +1,115 @@
+"""Retry decorator for transient failures.
+
+Provides ``@retriable`` for functions that call external services and may
+encounter transient network or upstream errors.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import logging
+import time
+from collections.abc import Callable
+from typing import Any, ParamSpec, TypeVar
+
+from errors.exceptions import ExternalServiceError
+
+logger = logging.getLogger("errors.retry")
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+# Default exception types considered retryable.
+DEFAULT_RETRYABLE: tuple[type[BaseException], ...] = (
+    ExternalServiceError,
+    ConnectionError,
+    TimeoutError,
+    OSError,
+)
+
+
+def _compute_delay(attempt: int, backoff: str, base_delay: float) -> float:
+    """Compute delay in seconds for the given attempt number."""
+    if backoff == "exponential":
+        return base_delay * (2 ** (attempt - 1))
+    if backoff == "linear":
+        return base_delay * attempt
+    return base_delay  # constant
+
+
+def retriable(
+    *,
+    max_retries: int = 3,
+    backoff: str = "exponential",
+    base_delay: float = 0.5,
+    retryable_exceptions: tuple[type[BaseException], ...] | None = None,
+) -> Callable[[Callable[P, T]], Callable[P, T]]:
+    """Decorator that retries a function on transient failures.
+
+    Supports both sync and async callables.
+
+    Args:
+        max_retries: Maximum number of retry attempts after the first failure.
+        backoff: Backoff strategy -- ``"exponential"``, ``"linear"``, or ``"constant"``.
+        base_delay: Base delay in seconds between retries.
+        retryable_exceptions: Exception types that trigger a retry.
+            Defaults to ExternalServiceError, ConnectionError, TimeoutError, OSError.
+    """
+    exc_types = retryable_exceptions or DEFAULT_RETRYABLE
+
+    def decorator(fn: Callable[P, Any]) -> Callable[P, Any]:
+        if asyncio.iscoroutinefunction(fn):
+
+            @functools.wraps(fn)
+            async def async_wrapper(*args: P.args, **kwargs: P.kwargs) -> Any:
+                last_exc: BaseException | None = None
+                for attempt in range(1, max_retries + 2):  # 1 initial + max_retries
+                    try:
+                        return await fn(*args, **kwargs)
+                    except exc_types as exc:
+                        last_exc = exc
+                        if attempt <= max_retries:
+                            delay = _compute_delay(attempt, backoff, base_delay)
+                            logger.warning(
+                                "Retry attempt %d/%d for %s after %.2fs: %s",
+                                attempt,
+                                max_retries,
+                                fn.__qualname__,
+                                delay,
+                                exc,
+                            )
+                            await asyncio.sleep(delay)
+                        else:
+                            raise
+                raise last_exc  # type: ignore[misc]  # unreachable but satisfies mypy
+
+            return async_wrapper  # type: ignore[return-value]
+        else:
+
+            @functools.wraps(fn)
+            def sync_wrapper(*args: P.args, **kwargs: P.kwargs) -> Any:
+                last_exc: BaseException | None = None
+                for attempt in range(1, max_retries + 2):
+                    try:
+                        return fn(*args, **kwargs)
+                    except exc_types as exc:
+                        last_exc = exc
+                        if attempt <= max_retries:
+                            delay = _compute_delay(attempt, backoff, base_delay)
+                            logger.warning(
+                                "Retry attempt %d/%d for %s after %.2fs: %s",
+                                attempt,
+                                max_retries,
+                                fn.__qualname__,
+                                delay,
+                                exc,
+                            )
+                            time.sleep(delay)
+                        else:
+                            raise
+                raise last_exc  # type: ignore[misc]
+
+            return sync_wrapper  # type: ignore[return-value]
+
+    return decorator  # type: ignore[return-value]

errors/severity.py

@@ -0,0 +1,86 @@
+"""Error severity levels and categories for monitoring and alerting.
+
+Provides structured classification of errors for integration with monitoring
+tools like Datadog, Sentry, and Grafana dashboards.
+"""
+
+from __future__ import annotations
+
+from enum import IntEnum, StrEnum
+
+
+class ErrorSeverity(IntEnum):
+    """Error severity levels for monitoring tools (Datadog, Sentry, Grafana).
+
+    Values are ordered so comparisons work naturally:
+    ``ErrorSeverity.WARNING < ErrorSeverity.ERROR`` is True.
+    """
+
+    DEBUG = 10
+    INFO = 20
+    WARNING = 30
+    ERROR = 40
+    CRITICAL = 50
+
+
+class ErrorCategory(StrEnum):
+    """Error categories for dashboarding and alerting."""
+
+    VALIDATION = "validation"
+    AUTHENTICATION = "authentication"
+    AUTHORIZATION = "authorization"
+    NOT_FOUND = "not_found"
+    CONFLICT = "conflict"
+    RATE_LIMIT = "rate_limit"
+    CLIENT = "client"
+    SERVER = "server"
+    INFRASTRUCTURE = "infrastructure"
+    BUSINESS_LOGIC = "business_logic"
+
+
+# Default severity based on HTTP status code ranges.
+_STATUS_TO_SEVERITY: dict[int, ErrorSeverity] = {
+    400: ErrorSeverity.WARNING,
+    401: ErrorSeverity.WARNING,
+    403: ErrorSeverity.WARNING,
+    404: ErrorSeverity.INFO,
+    409: ErrorSeverity.WARNING,
+    422: ErrorSeverity.WARNING,
+    429: ErrorSeverity.INFO,
+    500: ErrorSeverity.CRITICAL,
+    502: ErrorSeverity.ERROR,
+}
+
+
+def severity_for_status(status_code: int) -> ErrorSeverity:
+    """Return the default severity for a given HTTP status code."""
+    if status_code in _STATUS_TO_SEVERITY:
+        return _STATUS_TO_SEVERITY[status_code]
+    if status_code < 400:
+        return ErrorSeverity.DEBUG
+    if status_code < 500:
+        return ErrorSeverity.WARNING
+    return ErrorSeverity.ERROR
+
+
+# Default category based on HTTP status code.
+_STATUS_TO_CATEGORY: dict[int, ErrorCategory] = {
+    400: ErrorCategory.CLIENT,
+    401: ErrorCategory.AUTHENTICATION,
+    403: ErrorCategory.AUTHORIZATION,
+    404: ErrorCategory.NOT_FOUND,
+    409: ErrorCategory.CONFLICT,
+    422: ErrorCategory.VALIDATION,
+    429: ErrorCategory.RATE_LIMIT,
+    500: ErrorCategory.SERVER,
+    502: ErrorCategory.INFRASTRUCTURE,
+}
+
+
+def category_for_status(status_code: int) -> ErrorCategory:
+    """Return the default category for a given HTTP status code."""
+    if status_code in _STATUS_TO_CATEGORY:
+        return _STATUS_TO_CATEGORY[status_code]
+    if status_code < 500:
+        return ErrorCategory.CLIENT
+    return ErrorCategory.SERVER

msaas_errors-0.1.0.dist-info/METADATA

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: msaas-errors
+Version: 0.1.0
+Summary: Standardized error handling library for platform backend APIs
+Requires-Python: >=3.12
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: structlog>=23.0; extra == 'dev'
+Provides-Extra: structlog
+Requires-Dist: structlog>=23.0; extra == 'structlog'

msaas_errors-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+errors/__init__.py,sha256=8G_hbj0-3RFlrE7bhVTHedwgCe1RP8cSxmTt90VWb2Y,1467
+errors/config.py,sha256=QOgpm-JNq8eo1c-pp5Di0GLsNEbyD4ohdd8nlFXpn54,2091
+errors/context.py,sha256=-095zy2madw33eMWSe0Zuy5Cv37nYGJj3cpk6lWySG8,1871
+errors/exceptions.py,sha256=zLQ7HdVWzW1OhVMRpEDGwrkdK42XjojMAu2YR4gevE0,8149
+errors/handler.py,sha256=GwQMn1pPivBY2eXT2yOzi4mJtzMrPaxamMEMmGy3wY0,6286
+errors/monitoring.py,sha256=Pdrvy0lCMoBP6xxmarwO5CSAY9pgoIQb6yQOaaL9-SE,4022
+errors/problem_details.py,sha256=GTKM9VJoKXygO2jJA71KYwepBFKEhdcR8h71p8wJ3KM,4322
+errors/responses.py,sha256=-qYGiaK-TDTQOznrVaTq0mrU3csWXsxvwiM5aiEj_7w,3277
+errors/retry.py,sha256=1c9ZTcRShPi66uNLWcOU0RcRZItx0-4fT1qvrhU519s,4242
+errors/severity.py,sha256=npUH-HceA4-gSebEkGxnj-dvjpWts6bhqoQACkYejdk,2481
+msaas_errors-0.1.0.dist-info/METADATA,sha256=9kL9bPhmw1XGGp0C5-1q8ulH_PcXDAuSWKhRCjeWC6E,537
+msaas_errors-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+msaas_errors-0.1.0.dist-info/RECORD,,

msaas_errors-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