feat: introduced a first version of an error handler

Author: JanssenBrm

app/auth.py

@@ -6,6 +6,8 @@
 from jwt import PyJWKClient
 from loguru import logger
 
+from app.error import AuthException
+
 from .config.settings import settings
 
 # Keycloak OIDC info
@@ -37,9 +39,9 @@ def _decode_token(token: str):
         )
         return payload
     except Exception:
-        raise HTTPException(
-            status_code=status.HTTP_401_UNAUTHORIZED,
-            detail="Could not validate credentials",
+        raise AuthException(
+            http_status=status.HTTP_401_UNAUTHORIZED,
+            message="Could not validate credentials!",
         )
 
 

app/database/db.py

@@ -35,7 +35,7 @@ def get_db():
         yield db
         db.commit()
     except Exception:
-        logger.exception("An error occurred during database retrieval")
+        logger.error("An error occurred during database retrieval")
         db.rollback()
         raise
     finally:

app/error.py

@@ -0,0 +1,62 @@
+from typing import Any, Dict, Optional
+from fastapi import status
+from pydantic import BaseModel
+
+
+class ErrorResponse(BaseModel):
+    status: str = "error"
+    error_code: str
+    message: str
+    details: Optional[Dict[str, Any]] = None
+    request_id: Optional[str] = None
+
+
+class DispatcherException(Exception):
+    """
+    Base domain exception for the APEx Dispatch API.
+    """
+
+    http_status: int = status.HTTP_400_BAD_REQUEST
+    error_code: str = "APEX_ERROR"
+    message: str = "An error occurred."
+    details: Optional[Dict[str, Any]] = None
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        error_code: Optional[str] = None,
+        http_status: Optional[int] = None,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        if message:
+            self.message = message
+        if error_code:
+            self.error_code = error_code
+        if http_status:
+            self.http_status = http_status
+        if details:
+            self.details = details
+
+    def __str__(self):
+        return f"{self.error_code}: {self.message}"
+
+
+class AuthException(DispatcherException):
+    def __init__(
+        self,
+        http_status: Optional[int] = status.HTTP_401_UNAUTHORIZED,
+        message: Optional[Dict[str, Any]] = "Authentication failed.",
+    ):
+        super().__init__(message, "AUTHENTICATION_FAILED", http_status)
+
+
+class JobNotFoundException(DispatcherException):
+    http_status: int = status.HTTP_404_NOT_FOUND
+    error_code: str = "JOB_NOT_FOUND"
+    message: str = "The requested job was not found."
+
+
+class InternalException(DispatcherException):
+    http_status: int = status.HTTP_500_INTERNAL_SERVER_ERROR
+    error_code: str = "INTERNAL_ERROR"
+    message: str = "An internal server error occurred."

app/main.py

@@ -2,6 +2,7 @@
 from fastapi.middleware.cors import CORSMiddleware
 
 from app.middleware.correlation_id import add_correlation_id
+from app.middleware.error_handling import register_exception_handlers
 from app.platforms.dispatcher import load_processing_platforms
 from app.services.tiles.base import load_grids
 from app.config.logger import setup_logging
@@ -28,6 +29,7 @@
 )
 
 app.middleware("http")(add_correlation_id)
+register_exception_handlers(app)
 
 # include routers
 app.include_router(tiles.router)

app/middleware/error_handling.py

@@ -0,0 +1,51 @@
+from fastapi import Request, status
+from fastapi.responses import JSONResponse
+from app.error import DispatcherException, ErrorResponse
+from app.middleware.correlation_id import correlation_id_ctx
+from loguru import logger
+
+
+def get_dispatcher_error_response(
+    exc: DispatcherException, request_id: str
+) -> ErrorResponse:
+    return ErrorResponse(
+        error_code=exc.error_code,
+        message=exc.message,
+        details=exc.details,
+        request_id=request_id,
+    )
+
+
+async def dispatch_exception_handler(request: Request, exc: DispatcherException):
+
+    content = get_dispatcher_error_response(exc, correlation_id_ctx.get())
+    logger.exception(f"DispatcherException raised: {exc.message}")
+    return JSONResponse(status_code=exc.http_status, content=content.dict())
+
+
+async def generic_exception_handler(request: Request, exc: Exception):
+
+    # DO NOT expose internal exceptions to the client
+    content = ErrorResponse(
+        error_code="INTERNAL_SERVER_ERROR",
+        message="An unexpected error occurred.",
+        details=None,
+        request_id=correlation_id_ctx.get(),
+    )
+
+    # Log exception to server logs for debugging
+    print(f"[ERROR] Request ID: {exc}")
+
+    return JSONResponse(
+        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, content=content.dict()
+    )
+
+
+def register_exception_handlers(app):
+    """
+    Call this in main.py after creating the FastAPI() instance.
+    """
+
+    app.add_exception_handler(DispatcherException, dispatch_exception_handler)
+    # app.add_exception_handler(RequestValidationError, validation_exception_handler)
+    app.add_exception_handler(Exception, generic_exception_handler)

app/routers/unit_jobs.py

@@ -5,6 +5,14 @@
 
 from app.auth import oauth2_scheme
 from app.database.db import get_db
+from app.error import (
+    AuthException,
+    DispatcherException,
+    ErrorResponse,
+    InternalException,
+    JobNotFoundException,
+)
+from app.middleware.error_handling import get_dispatcher_error_response
 from app.schemas.enum import OutputFormatEnum, ProcessTypeEnum
 from app.schemas.unit_job import (
     BaseJobRequest,
@@ -30,6 +38,19 @@
     status_code=status.HTTP_201_CREATED,
     tags=["Unit Jobs"],
     summary="Create a new processing job",
+    responses={
+        InternalException.http_status: {
+            "description": "Internal server error",
+            "model": ErrorResponse,
+            "content": {
+                "application/json": {
+                    "example": get_dispatcher_error_response(
+                        InternalException(), "request-id"
+                    )
+                }
+            },
+        },
+    },
 )
 async def create_unit_job(
     payload: Annotated[
@@ -105,65 +126,100 @@ async def create_unit_job(
     """Create a new processing job with the provided data."""
     try:
         return await create_processing_job(token, db, payload)
-    except HTTPException as e:
-        raise e
+    except DispatcherException as de:
+        raise de
     except Exception as e:
-        logger.exception(f"Error creating processing job: {e}")
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"An error occurred while creating the processing job: {e}",
+        logger.error(f"Error creating processing job: {e}")
+        raise InternalException(
+            message="An error occurred while creating processing job."
         )
 
 
 @router.get(
     "/unit_jobs/{job_id}",
     tags=["Unit Jobs"],
-    responses={404: {"description": "Processing job not found"}},
+    responses={
+        JobNotFoundException.http_status: {
+            "description": "Job not found",
+            "model": ErrorResponse,
+            "content": {
+                "application/json": {
+                    "example": get_dispatcher_error_response(
+                        JobNotFoundException(), "request-id"
+                    )
+                }
+            },
+        },
+        InternalException.http_status: {
+            "description": "Internal server error",
+            "model": ErrorResponse,
+            "content": {
+                "application/json": {
+                    "example": get_dispatcher_error_response(
+                        InternalException(), "request-id"
+                    )
+                }
+            },
+        },
+    },
 )
 async def get_job(
     job_id: int, db: Session = Depends(get_db), token: str = Depends(oauth2_scheme)
 ) -> ProcessingJob:
     try:
         job = await get_processing_job_by_user_id(token, db, job_id)
         if not job:
-            logger.error(f"Processing job {job_id} not found")
-            raise HTTPException(
-                status_code=404,
-                detail=f"Processing job {job_id} not found",
-            )
+            raise JobNotFoundException()
         return job
-    except HTTPException as e:
-        raise e
+    except DispatcherException as de:
+        raise de
     except Exception as e:
-        logger.exception(f"Error retrieving processing job {job_id}: {e}")
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"An error occurred while retrieving processing job {job_id}: {e}",
+        logger.error(f"Error retrieving processing job {job_id}: {e}")
+        raise InternalException(
+            message="An error occurred while retrieving the processing job."
         )
 
 
 @router.get(
     "/unit_jobs/{job_id}/results",
     tags=["Unit Jobs"],
-    responses={404: {"description": "Processing job not found"}},
+    responses={
+        JobNotFoundException.http_status: {
+            "description": "Job not found",
+            "model": ErrorResponse,
+            "content": {
+                "application/json": {
+                    "example": get_dispatcher_error_response(
+                        JobNotFoundException(), "request-id"
+                    )
+                }
+            },
+        },
+        InternalException.http_status: {
+            "description": "Internal server error",
+            "model": ErrorResponse,
+            "content": {
+                "application/json": {
+                    "example": get_dispatcher_error_response(
+                        InternalException(), "request-id"
+                    )
+                }
+            },
+        },
+    },
 )
 async def get_job_results(
     job_id: int, db: Session = Depends(get_db), token: str = Depends(oauth2_scheme)
 ) -> Collection | None:
     try:
         result = await get_processing_job_results(token, db, job_id)
         if not result:
-            logger.error(f"Result for processing job {job_id} not found")
-            raise HTTPException(
-                status_code=404,
-                detail=f"Result for processing job {job_id} not found",
-            )
+            raise JobNotFoundException()
         return result
-    except HTTPException as e:
-        raise e
+    except DispatcherException as de:
+        raise de
     except Exception as e:
-        logger.exception(f"Error getting results for processing job {job_id}: {e}")
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"An error occurred while retrieving results for processing job {job_id}: {e}",
+        logger.error(f"Error getting results for processing job {job_id}: {e}")
+        raise InternalException(
+            message="An error occurred while retrieving processing job results."
         )