mobius-error-py 1.0.0__py3-none-any.whl

mobius_error/handlers/exception_handler.py

@@ -0,0 +1,248 @@
+"""
+Mirrors com.aidtaas.mobius.error.services.handler.RestExceptionHandler
+
+Call ``register_exception_handlers(app)`` once at startup to install all
+handlers on a FastAPI application instance.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional
+
+from fastapi import FastAPI, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from starlette.exceptions import HTTPException as StarletteHTTPException
+from starlette.middleware.base import BaseHTTPMiddleware
+
+from mobius_error.config import App
+from mobius_error.errors.error_message import ErrorMessage
+from mobius_error.exceptions.access_violation_exception import AccessViolationException
+from mobius_error.exceptions.api_exception import ApiException
+from mobius_error.exceptions.application_exception import ApplicationException
+from mobius_error.exceptions.data_type_mismatch_exception import DataTypeMismatchException
+from mobius_error.exceptions.token_exception import TokenException
+from mobius_error.exceptions.validation_exception import ValidationException
+from mobius_error.kafka.producer import (
+    KafkaErrorProducer,
+    LogEventSender,
+    PyKafkaProducerClientSender,
+    get_error_producer,
+    set_error_producer,
+)
+from mobius_error.responses.api_error_response import ApiErrorResponse
+
+logger = logging.getLogger("mobius_error.handler")
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _emit(exc: Exception, resp: ApiErrorResponse) -> None:
+    """Fire-and-forget error event to Kafka if a producer is configured."""
+    producer = get_error_producer()
+    if producer is None:
+        return
+    producer.send_error_event(exc, resp)
+
+
+def _resolve_sender(
+    kafka_sender: Optional[LogEventSender],
+    kafka_producer: Optional[Any],
+    kafka_config: Optional[Any],
+) -> Optional[LogEventSender]:
+    if kafka_sender is not None:
+        return kafka_sender
+    if kafka_producer is not None:
+        return PyKafkaProducerClientSender(kafka_producer)
+    try:
+        from kafka_producer_client.action_logger import (  # type: ignore[import]
+            configure_kafka_producer,
+            get_kafka_producer,
+        )
+    except ImportError:
+        return None
+    try:
+        if kafka_config is not None:
+            configure_kafka_producer(kafka_config)
+        return PyKafkaProducerClientSender(get_kafka_producer())
+    except Exception:  # noqa: BLE001
+        logger.warning("mobius-error: could not initialize py-kafka-producer-client.", exc_info=True)
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Module-level exception handlers
+# ---------------------------------------------------------------------------
+
+def _handle_request_validation(_request: Request, exc: RequestValidationError) -> JSONResponse:
+    logger.error("Validation error :: %s", exc.errors())
+    resp = ApiErrorResponse.from_status_message_code(422, "Validation error", 400000)
+    for err in exc.errors():
+        field = " → ".join(str(loc) for loc in err.get("loc", []))
+        resp.add_sub_error(ErrorMessage(message=f"{field}: {err.get('msg', '')}"))
+    _emit(exc, resp)
+    return JSONResponse(status_code=422, content=resp.to_dict())
+
+
+def _handle_http_exception(_request: Request, exc: StarletteHTTPException) -> JSONResponse:
+    status = exc.status_code
+    detail = exc.detail or "HTTP error"
+    logger.error("HTTP %s :: %s", status, detail)
+    resp = ApiErrorResponse.from_status(status, str(detail))
+    _emit(exc, resp)
+    return JSONResponse(status_code=status, content=resp.to_dict())
+
+
+def _handle_token_exception(_request: Request, exc: TokenException) -> JSONResponse:
+    status = exc.http_status_code
+    logger.error("TokenException :: %s", exc)
+    error = exc.error
+    cause = error.error_message_description or exc.nested_error_message
+    resp = ApiErrorResponse.from_status_message_sub(
+        http_status_code=status,
+        message=error.error_message,
+        sub_error=cause if isinstance(cause, ErrorMessage) else None,
+        action_required=error.action_required,
+        error_code=error.error_code,
+    )
+    _emit(exc, resp)
+    return JSONResponse(status_code=status, content=resp.to_dict())
+
+
+def _handle_access_violation(_request: Request, exc: AccessViolationException) -> JSONResponse:
+    logger.error("AccessViolationException :: %s", exc)
+    resp = ApiErrorResponse.from_application_exception(403, exc)
+    _emit(exc, resp)
+    return JSONResponse(status_code=403, content=resp.to_dict())
+
+
+def _handle_data_type_mismatch(_request: Request, exc: DataTypeMismatchException) -> JSONResponse:
+    logger.error("DataTypeMismatchException :: %s", exc)
+    resp = ApiErrorResponse.from_application_exception(400, exc)
+    _emit(exc, resp)
+    return JSONResponse(status_code=400, content=resp.to_dict())
+
+
+def _handle_validation_exception(_request: Request, exc: ValidationException) -> JSONResponse:
+    logger.error("ValidationException :: %s", exc)
+    resp = ApiErrorResponse.from_application_exception(409, exc)
+    _emit(exc, resp)
+    return JSONResponse(status_code=409, content=resp.to_dict())
+
+
+def _handle_api_exception(_request: Request, exc: ApiException) -> JSONResponse:
+    status = exc.http_status_code
+    logger.error("ApiException :: %s", exc)
+    if exc.error_object is not None:
+        resp = ApiErrorResponse.from_application_exception(status, exc)
+        _emit(exc, resp)
+        return JSONResponse(status_code=status, content=resp.to_dict())
+    error = exc.error
+    cause = error.error_message_description or exc.nested_error_message
+    resp = ApiErrorResponse.from_status_message_sub(
+        http_status_code=status,
+        message=error.error_message,
+        sub_error=cause if isinstance(cause, ErrorMessage) else None,
+        action_required=error.action_required,
+        error_code=error.error_code,
+    )
+    _emit(exc, resp)
+    return JSONResponse(status_code=status, content=resp.to_dict())
+
+
+def _handle_application_exception(_request: Request, exc: ApplicationException) -> JSONResponse:
+    logger.error("ApplicationException :: %s", exc)
+    resp = ApiErrorResponse.from_application_exception(403, exc)
+    _emit(exc, resp)
+    return JSONResponse(status_code=403, content=resp.to_dict())
+
+
+def _handle_generic(_request: Request, exc: Exception) -> JSONResponse:
+    logger.error("Unexpected error :: %s", exc, exc_info=True)
+    resp = ApiErrorResponse.from_exception(500, exc)
+    _emit(exc, resp)
+    return JSONResponse(status_code=500, content=resp.to_dict())
+
+
+class _CatchAllMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next):  # type: ignore[override]
+        try:
+            return await call_next(request)
+        except Exception as exc:
+            logger.exception("Unexpected error (middleware) :: %s", exc)
+            resp = ApiErrorResponse.from_exception(500, exc)
+            _emit(exc, resp)
+            return JSONResponse(status_code=500, content=resp.to_dict())
+
+
+# ---------------------------------------------------------------------------
+# Public registration function
+# ---------------------------------------------------------------------------
+
+def register_exception_handlers(
+    app: FastAPI,
+    app_name: Optional[str] = None,
+    kafka_sender: Optional[LogEventSender] = None,
+    kafka_producer: Optional[Any] = None,
+    kafka_config: Optional[Any] = None,
+    topic: Optional[str] = None,
+    schema_id: Optional[str] = None,
+    tenant_id: Optional[str] = None,
+) -> Optional[KafkaErrorProducer]:
+    """
+    Register all Mobius-style exception handlers on a FastAPI app.
+
+    Parameters
+    ----------
+    app : FastAPI
+        The application instance.
+    app_name : str, optional
+        Sets ``App.app_name`` (equivalent to ``spring.application.name``).
+        If not provided, uses ``app.title``.
+    kafka_sender : LogEventSender, optional
+        Any object with ``send(value, *, topic)``. Highest priority.
+    kafka_producer : KafkaProducerClient, optional
+        A ``py-kafka-producer-client`` instance, wrapped automatically.
+    kafka_config : KafkaProducerConfig, optional
+        Configures the ``py-kafka-producer-client`` singleton.
+    topic : str, optional
+        Override the default Kafka topic (``platform-exception-topic``).
+    schema_id : str, optional
+        Override the default schema ID.
+    tenant_id : str, optional
+        Override the default tenant ID.
+
+    Returns
+    -------
+    KafkaErrorProducer or None
+        The registered producer, if any was configured.
+    """
+    name = app_name or app.title
+    App.set_app_name(name)
+
+    producer: Optional[KafkaErrorProducer] = None
+    sender = _resolve_sender(kafka_sender, kafka_producer, kafka_config)
+    if sender is not None:
+        producer = KafkaErrorProducer(sender, name, topic=topic, schema_id=schema_id, tenant_id=tenant_id)
+        set_error_producer(producer)
+    else:
+        logger.warning(
+            "mobius-error: no Kafka producer resolved; error events will not be published. "
+            "Pass kafka_config/kafka_producer/kafka_sender."
+        )
+
+    app.add_exception_handler(RequestValidationError, _handle_request_validation)
+    app.add_exception_handler(StarletteHTTPException, _handle_http_exception)
+    app.add_exception_handler(TokenException, _handle_token_exception)
+    app.add_exception_handler(AccessViolationException, _handle_access_violation)
+    app.add_exception_handler(DataTypeMismatchException, _handle_data_type_mismatch)
+    app.add_exception_handler(ValidationException, _handle_validation_exception)
+    app.add_exception_handler(ApiException, _handle_api_exception)
+    app.add_exception_handler(ApplicationException, _handle_application_exception)
+    app.add_exception_handler(Exception, _handle_generic)
+    app.add_middleware(_CatchAllMiddleware)
+
+    return producer

mobius_error/kafka/constants.py

@@ -0,0 +1,5 @@
+"""Kafka pipeline constants for the error schema — mirrors mobius-logging-py's constants.py."""
+
+TOPIC = "platform-exception-topic"
+SCHEMA_ID = "6a2bfc671730d70feb345ab5"
+TENANT_ID = "2cf76e5f-26ad-4f2c-bccc-f4bc1e7bfb64"

mobius_error/kafka/producer.py

@@ -0,0 +1,161 @@
+"""Kafka error-event producer. Mirrors KafkaLogProducer from mobius-logging-py.
+
+Sends a DataIngestionOperation envelope to the platform-exception-topic whenever
+an exception handler fires. Sending is best-effort and non-blocking (background
+thread pool). Failures are logged, never raised into the request path.
+"""
+from __future__ import annotations
+
+import logging
+import time
+import uuid
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Dict, Optional, Protocol, runtime_checkable
+
+from mobius_error.kafka import constants
+
+if TYPE_CHECKING:
+    from mobius_error.responses.api_error_response import ApiErrorResponse
+
+log = logging.getLogger(__name__)
+
+_executor = ThreadPoolExecutor(max_workers=2, thread_name_prefix="mobius-error-producer")
+
+
+@runtime_checkable
+class LogEventSender(Protocol):
+    """Anything able to publish a dict event to a topic.
+
+    Matches py-kafka-producer-client shape: ``value`` is a dict,
+    ``topic`` is keyword-only.
+    """
+
+    def send(self, value: Dict[str, Any], *, topic: str) -> Any: ...  # pragma: no cover
+
+
+class PyKafkaProducerClientSender:
+    """Adapter for the internal py-kafka-producer-client (>=0.1.7).
+
+    Signature::
+
+        producer.send(value: dict, *, topic: str | None = None, ...) -> None
+    """
+
+    def __init__(self, producer: Any) -> None:
+        self._producer = producer
+
+    def send(self, value: Dict[str, Any], *, topic: str) -> Any:
+        return self._producer.send(value, topic=topic)
+
+
+@dataclass
+class DataIngestionOperation:
+    """Envelope payload — same shape as the logging lib."""
+
+    actionType: str
+    object: Dict[str, Any]
+    id: str
+    schemaId: str
+    tenantId: str
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "actionType": self.actionType,
+            "object": self.object,
+            "id": self.id,
+            "schemaId": self.schemaId,
+            "tenantId": self.tenantId,
+        }
+
+
+def _cause_string(exc: Exception, resp: "ApiErrorResponse") -> Optional[str]:
+    """Return cause as a plain string, matching the sample payload shape."""
+    if exc.__cause__ is not None:
+        return str(exc.__cause__)
+    if resp.cause is not None:
+        return resp.cause.message or resp.cause.root_message
+    return None
+
+
+def _build_error_object(
+    exc: Exception,
+    resp: "ApiErrorResponse",
+    error_id: str,
+    timestamp_ms: int,
+    errorcategory: str,
+) -> Dict[str, Any]:
+    """Map ApiErrorResponse fields to the Error-Response-01 schema attribute names."""
+    return {
+        "errorid": error_id,                                            # string (PK)
+        "timestamp": timestamp_ms,                                      # long (ms)
+        "errorcategory": errorcategory,                                 # string
+        "errormessage": resp.error_message or None,                     # string
+        "origin": resp.origin or None,                                  # string
+        "httpstatuscode": resp.http_status_code,                        # integer (matches sample)
+        "errorcode": resp.error_code or None,                           # integer
+        "detailederrormessage": resp.detailed_error_message or None,    # longtext
+        "cause": _cause_string(exc, resp),                              # string (matches sample)
+        "suberrors": [se.to_dict() for se in resp.sub_errors],          # json_array (always present)
+        "actionsrequired": resp.actions_required or [],                 # string_array
+        "errorobject": resp.error_object,                               # json (null if absent)
+        "docurl": resp.doc_url or None,                                 # longtext
+        "hash": None,                                                   # string (null — reserved)
+    }
+
+
+class KafkaErrorProducer:
+    def __init__(
+        self,
+        sender: LogEventSender,
+        service_name: str,
+        *,
+        topic: Optional[str] = None,
+        schema_id: Optional[str] = None,
+        tenant_id: Optional[str] = None,
+    ) -> None:
+        self._sender = sender
+        self._service_name = service_name
+        self._topic = topic or constants.TOPIC
+        self._schema_id = schema_id or constants.SCHEMA_ID
+        self._tenant_id = tenant_id or constants.TENANT_ID
+
+    def send_error_event(
+        self,
+        exc: Exception,
+        resp: "ApiErrorResponse",
+        errorcategory: str = "PLATFORM",
+    ) -> None:
+        """Build the error object dict and ship it to the schema topic."""
+        timestamp_ms = int(time.time() * 1000)
+        error_id = f"{uuid.uuid4()}_{timestamp_ms}"
+        obj = _build_error_object(exc, resp, error_id, timestamp_ms, errorcategory)
+
+        payload = DataIngestionOperation(
+            actionType="CREATE",
+            object=obj,
+            id=error_id,
+            schemaId=self._schema_id,
+            tenantId=self._tenant_id,
+        )
+        _executor.submit(self._send, payload.to_dict())
+
+    def _send(self, value: Dict[str, Any]) -> None:
+        try:
+            self._sender.send(value, topic=self._topic)
+        except Exception:  # noqa: BLE001
+            log.warning("Failed to publish error event to schema topic", exc_info=True)
+
+
+# --- module-level default producer (set at app startup) ---
+
+_default_producer: Optional[KafkaErrorProducer] = None
+
+
+def set_error_producer(producer: Optional[KafkaErrorProducer]) -> None:
+    global _default_producer
+    _default_producer = producer
+
+
+def get_error_producer() -> Optional[KafkaErrorProducer]:
+    return _default_producer

mobius_error/responses/api_error_response.py

@@ -0,0 +1,117 @@
+"""Mirrors com.aidtaas.mobius.error.services.response.ApiErrorResponse"""
+
+from __future__ import annotations
+from typing import Any, Optional
+
+from mobius_error.config import App
+from mobius_error.errors.error import Error
+from mobius_error.errors.error_message import ErrorMessage
+from mobius_error.exceptions.application_exception import ApplicationException
+from mobius_error.responses.error_response import ErrorResponse
+
+
+class ApiErrorResponse(ErrorResponse):
+
+    def __init__(
+        self,
+        http_status_code: int = 500,
+        error: Optional[Error] = None,
+        error_message: Optional[str] = None,
+        detailed_error_message: Optional[str] = None,
+        cause: Optional[ErrorMessage] = None,
+        sub_errors: Optional[list[ErrorMessage]] = None,
+        actions_required: Optional[list[str]] = None,
+        error_object: Any = None,
+        error_code: Optional[int] = None,
+    ) -> None:
+        super().__init__(
+            error=error,
+            error_message=error_message,
+            detailed_error_message=detailed_error_message,
+            cause=cause,
+            sub_errors=sub_errors,
+            actions_required=actions_required,
+            error_object=error_object,
+            origin=App.get_app_name(),
+        )
+        self.http_status_code: int = http_status_code
+
+        # Override error_message when explicitly supplied
+        if error_message and not error:
+            self.error_message = error_message
+        elif not error_message and not error:
+            self.error_message = "Encountered an unexpected error"
+
+        # Override error_code when explicitly supplied
+        if error_code is not None:
+            self.error_code = error_code
+
+    # ---- convenience factory methods matching Java overloads ----
+
+    @classmethod
+    def from_status(cls, http_status_code: int, message: str = "Encountered an unexpected error") -> "ApiErrorResponse":
+        return cls(http_status_code=http_status_code, error_message=message)
+
+    @classmethod
+    def from_status_and_error(cls, http_status_code: int, error: Error) -> "ApiErrorResponse":
+        return cls(http_status_code=http_status_code, error=error)
+
+    @classmethod
+    def from_status_message_code(cls, http_status_code: int, message: str, error_code: int) -> "ApiErrorResponse":
+        return cls(http_status_code=http_status_code, error_message=message, error_code=error_code)
+
+    @classmethod
+    def from_status_message_sub(
+        cls,
+        http_status_code: int,
+        message: str,
+        sub_error: Optional[ErrorMessage] = None,
+        action_required: Optional[str] = None,
+        error_code: Optional[int] = None,
+    ) -> "ApiErrorResponse":
+        resp = cls(
+            http_status_code=http_status_code,
+            error_message=message,
+            error_code=error_code,
+        )
+        if sub_error:
+            resp.add_sub_error(sub_error)
+        if action_required:
+            resp.add_action_required(action_required)
+        return resp
+
+    @classmethod
+    def from_application_exception(cls, http_status_code: int, exc: ApplicationException) -> "ApiErrorResponse":
+        resp = cls(
+            http_status_code=http_status_code,
+            error=exc.error,
+            error_message=exc.error.error_message,
+            error_object=exc.error_object,
+        )
+        resp.origin = exc.origin
+        resp.error_code = exc.error.error_code
+
+        if exc.detailed_error_message:
+            resp.detailed_error_message = exc.detailed_error_message
+
+        # nested cause
+        if exc.__cause__:
+            resp.cause = ErrorMessage(message=str(exc.__cause__))
+        elif exc.nested_error_message:
+            resp.cause = exc.nested_error_message
+
+        resp.add_sub_errors(exc.sub_errors)
+        resp.add_actions_required(exc.actions_required)
+        return resp
+
+    @classmethod
+    def from_exception(cls, http_status_code: int, exc: Exception) -> "ApiErrorResponse":
+        resp = cls(http_status_code=http_status_code, error_message=str(exc))
+        if exc.__cause__:
+            resp.cause = ErrorMessage(message=str(exc.__cause__))
+        return resp
+
+    def to_dict(self) -> dict[str, Any]:
+        d = super().to_dict()
+        d["httpStatusCode"] = self.http_status_code
+        return d

mobius_error/responses/error_response.py

@@ -0,0 +1,84 @@
+"""Mirrors com.aidtaas.mobius.error.services.response.ErrorResponse"""
+
+from __future__ import annotations
+import time
+from typing import Any, Optional
+
+from mobius_error.errors.error import Error
+from mobius_error.errors.error_message import ErrorMessage
+
+
+DOC_URL = "https://mobiusdtaas.atlassian.net/wiki/spaces/EN/pages/2360868868/Mobius+Documentation+for+Common+Issues"
+
+
+class ErrorResponse:
+
+    def __init__(
+        self,
+        error: Optional[Error] = None,
+        error_message: Optional[str] = None,
+        detailed_error_message: Optional[str] = None,
+        cause: Optional[ErrorMessage] = None,
+        sub_errors: Optional[list[ErrorMessage]] = None,
+        actions_required: Optional[list[str]] = None,
+        error_object: Any = None,
+        origin: Optional[str] = None,
+    ) -> None:
+        self.timestamp: int = int(time.time() * 1000)
+        self.origin: Optional[str] = origin
+        self.error_code: int = error.error_code if error else 500001
+        self.error_message: str = (
+            error.error_message if error else (error_message or "")
+        )
+        self.detailed_error_message: Optional[str] = detailed_error_message
+        self.sub_errors: list[ErrorMessage] = list(sub_errors) if sub_errors else []
+        self.actions_required: list[str] = list(actions_required) if actions_required else []
+        self.cause: Optional[ErrorMessage] = cause
+        self.error_object: Any = error_object
+        self.doc_url: str = DOC_URL
+
+        # populate action_required from Error if provided
+        if error and error.action_required:
+            if error.action_required not in self.actions_required:
+                self.actions_required.append(error.action_required)
+
+    # ---- helpers ----
+
+    def add_sub_error(self, sub_error: ErrorMessage) -> None:
+        if sub_error is not None:
+            self.sub_errors.append(sub_error)
+
+    def add_sub_errors(self, sub_errors: list[ErrorMessage]) -> None:
+        if sub_errors:
+            self.sub_errors.extend(sub_errors)
+
+    def add_action_required(self, action: str) -> None:
+        if action:
+            self.actions_required.append(action)
+
+    def add_actions_required(self, actions: list[str]) -> None:
+        if actions:
+            self.actions_required.extend(actions)
+
+    # ---- serialisation ----
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-serialisable dict, omitting empty fields (NON_EMPTY)."""
+        d: dict[str, Any] = {"timestamp": self.timestamp}
+        if self.origin:
+            d["origin"] = self.origin
+        d["errorCode"] = self.error_code
+        if self.error_message:
+            d["errorMessage"] = self.error_message
+        if self.detailed_error_message:
+            d["detailedErrorMessage"] = self.detailed_error_message
+        if self.sub_errors:
+            d["subErrors"] = [se.to_dict() for se in self.sub_errors]
+        if self.actions_required:
+            d["actionsRequired"] = self.actions_required
+        if self.cause is not None:
+            d["cause"] = self.cause.to_dict()
+        if self.error_object is not None:
+            d["errorObject"] = self.error_object
+        d["docUrl"] = self.doc_url
+        return d