solace-agent-mesh 1.11.2__py3-none-any.whl

solace_agent_mesh/gateway/http_sse/shared/error_dto.py

@@ -0,0 +1,107 @@
+"""
+Standardized error response DTOs for HTTP APIs.
+
+This module provides consistent error response formats that can be used
+across any web application for uniform error handling.
+"""
+
+from typing import Dict, List, Optional
+from pydantic import BaseModel, Field
+
+
+class EventErrorDTO(BaseModel):
+    """
+    Simplified and standardized error response format.
+
+    This provides consistent error responses across all endpoints with:
+    - message: Human-readable error description
+    - validationDetails: Field-level validation errors (optional)
+
+    Examples:
+        404 Not Found:
+        {
+            "message": "Could not find User with id: 123",
+            "validationDetails": null
+        }
+
+        422 Validation Error:
+        {
+            "message": "Invalid input data",
+            "validationDetails": {
+                "email": ["Invalid email format"],
+                "name": ["Name is required"]
+            }
+        }
+    """
+    message: str = Field(..., description="Human-readable error message")
+    validationDetails: Optional[Dict[str, List[str]]] = Field(
+        default=None,
+        description="Field-level validation errors"
+    )
+
+    @classmethod
+    def create(
+        cls,
+        message: str,
+        validation_details: Optional[Dict[str, List[str]]] = None
+    ) -> "EventErrorDTO":
+        """
+        Create a new EventErrorDTO.
+
+        Args:
+            message: Human-readable error message
+            validation_details: Optional field-level validation errors
+
+        Returns:
+            EventErrorDTO instance
+        """
+        return cls(
+            message=message,
+            validationDetails=validation_details
+        )
+
+    @classmethod
+    def not_found(cls, entity_type: str, entity_id: str) -> "EventErrorDTO":
+        """
+        Create a 404 Not Found error with standardized message format.
+
+        Args:
+            entity_type: The type of entity (e.g., "User", "Product", "Order")
+            entity_id: The ID that was not found
+
+        Returns:
+            EventErrorDTO with 404 message format
+
+        Example:
+            EventErrorDTO.not_found("User", "123")
+            # Returns: {"message": "Could not find User with id: 123", "validationDetails": null}
+        """
+        message = f"Could not find {entity_type} with id: {entity_id}"
+        return cls.create(message=message)
+
+    @classmethod
+    def validation_error(
+        cls,
+        message: str,
+        validation_details: Dict[str, List[str]]
+    ) -> "EventErrorDTO":
+        """
+        Create a validation error with field-level details.
+
+        Args:
+            message: Main validation error message
+            validation_details: Dict mapping field names to error lists
+
+        Returns:
+            EventErrorDTO with validation details
+
+        Example:
+            EventErrorDTO.validation_error(
+                "Invalid user data",
+                {"email": ["Invalid format"], "age": ["Must be positive"]}
+            )
+        """
+        return cls.create(
+            message=message,
+            validation_details=validation_details
+        )

solace_agent_mesh/gateway/http_sse/shared/exception_handlers.py

@@ -0,0 +1,217 @@
+"""
+Generic FastAPI exception handlers for consistent HTTP error responses.
+
+This module provides FastAPI exception handlers that convert domain exceptions
+into appropriate HTTP responses with consistent formatting. These handlers
+can be used by any FastAPI application for uniform error handling.
+"""
+
+import logging
+
+from fastapi import HTTPException, Request, status
+from fastapi.responses import JSONResponse
+from fastapi.exceptions import RequestValidationError
+from pydantic import ValidationError as PydanticValidationError
+from starlette.exceptions import HTTPException as StarletteHTTPException
+
+from .exceptions import (
+    WebUIBackendException,
+    ValidationError,
+    EntityNotFoundError,
+    EntityAlreadyExistsError,
+    BusinessRuleViolationError,
+    ConfigurationError,
+    DataIntegrityError,
+    ExternalServiceError,
+)
+from .error_dto import EventErrorDTO
+
+log = logging.getLogger(__name__)
+
+
+def create_error_response(
+    status_code: int, message: str, validation_details: dict = None
+) -> JSONResponse:
+    """Create standardized error response using EventErrorDTO format."""
+    if validation_details:
+        error_dto = EventErrorDTO.validation_error(message, validation_details)
+    else:
+        error_dto = EventErrorDTO.create(message)
+
+    return JSONResponse(status_code=status_code, content=error_dto.model_dump())
+
+
+async def validation_error_handler(
+    request: Request, exc: ValidationError
+) -> JSONResponse:
+    """Handle domain validation errors - 422 Unprocessable Entity."""
+    if exc.validation_details:
+        error_dto = EventErrorDTO.validation_error(exc.message, exc.validation_details)
+    else:
+        error_dto = EventErrorDTO.create("bad request" if not exc.message else exc.message)
+
+    return JSONResponse(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, content=error_dto.model_dump())
+
+
+async def entity_not_found_handler(
+    request: Request, exc: EntityNotFoundError
+) -> JSONResponse:
+    """Handle entity not found errors - 404 Not Found."""
+    # Format: "Could not find applicationDomain with id: some-invalid-id"
+    message = f"Could not find {exc.entity_type} with id: {exc.entity_id}"
+    error_dto = EventErrorDTO.create(message)
+    return JSONResponse(status_code=status.HTTP_404_NOT_FOUND, content=error_dto.model_dump())
+
+
+async def entity_already_exists_handler(
+    request: Request, exc: EntityAlreadyExistsError
+) -> JSONResponse:
+    """Handle entity already exists errors - 409 Conflict."""
+    error_dto = EventErrorDTO.create(exc.message)
+    return JSONResponse(status_code=status.HTTP_409_CONFLICT, content=error_dto.model_dump())
+
+
+async def business_rule_violation_handler(
+    request: Request, exc: BusinessRuleViolationError
+) -> JSONResponse:
+    """Handle business rule violations - 422 Unprocessable Entity."""
+    error_dto = EventErrorDTO.create(exc.message)
+    return JSONResponse(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, content=error_dto.model_dump())
+
+
+async def configuration_error_handler(
+    request: Request, exc: ConfigurationError
+) -> JSONResponse:
+    """Handle configuration errors - 500 Internal Server Error."""
+    error_dto = EventErrorDTO.create("An unexpected server error occurred.")
+    return JSONResponse(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, content=error_dto.model_dump())
+
+
+async def data_integrity_error_handler(
+    request: Request, exc: DataIntegrityError
+) -> JSONResponse:
+    """Handle data integrity errors - 422 Unprocessable Entity."""
+    # Format: "An entity of type applicationDomain was passed in an invalid format"
+    message = f"An entity of type {exc.entity_type} was passed in an invalid format" if hasattr(exc, 'entity_type') else "bad request"
+    error_dto = EventErrorDTO.create(message)
+    return JSONResponse(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, content=error_dto.model_dump())
+
+
+async def external_service_error_handler(
+    request: Request, exc: ExternalServiceError
+) -> JSONResponse:
+    """Handle external service errors - 503 Service Unavailable."""
+    error_dto = EventErrorDTO.create("Service is unavailable.")
+    return JSONResponse(status_code=status.HTTP_503_SERVICE_UNAVAILABLE, content=error_dto.model_dump())
+
+
+async def webui_backend_exception_handler(
+    request: Request, exc: WebUIBackendException
+) -> JSONResponse:
+    """Handle generic WebUI backend exceptions - 500 Internal Server Error."""
+    log.error(
+        f"WebUIBackendException: {exc.message}",
+        extra={
+            "path": request.url.path,
+            "method": request.method,
+            "details": exc.details if hasattr(exc, 'details') else None
+        },
+        exc_info=True
+    )
+
+    message = exc.message if exc.message else "An unexpected server error occurred."
+    error_dto = EventErrorDTO.create(message)
+    return JSONResponse(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, content=error_dto.model_dump())
+
+
+async def http_exception_handler(
+    request: Request, exc: HTTPException
+) -> JSONResponse:
+    """Handle FastAPI HTTPExceptions with standardized format."""
+    # Map common HTTP status codes to standard messages (only used as fallback)
+    message_map = {
+        401: "An authentication error occurred. Try logging out and in again.",
+        403: "You do not have permissions to perform this operation",
+        404: f"Resource not found with path {request.url.path}",
+        405: f"Request method '{request.method}' is not supported",
+        406: "Unacceptable Content-type.",
+        429: "Rate limit exceeded message here",
+        500: "An unexpected server error occurred.",
+        501: "Not Implemented",
+        503: "Service is unavailable.",
+    }
+
+    message = exc.detail if exc.detail else message_map.get(exc.status_code, "bad request")
+    error_dto = EventErrorDTO.create(message)
+    return JSONResponse(status_code=exc.status_code, content=error_dto.model_dump())
+
+
+async def request_validation_exception_handler(
+    request: Request, exc: RequestValidationError
+) -> JSONResponse:
+    """Handle FastAPI request validation errors - 422 Unprocessable Entity."""
+    validation_details = {}
+    for error in exc.errors():
+        field_path = ".".join(str(x) for x in error["loc"] if x != "body")
+        if field_path not in validation_details:
+            validation_details[field_path] = []
+        validation_details[field_path].append(error["msg"])
+
+    if validation_details:
+        message = "body must not be empty" if not validation_details else "Validation error"
+        error_dto = EventErrorDTO.validation_error(message, validation_details)
+    else:
+        error_dto = EventErrorDTO.create("bad request")
+
+    return JSONResponse(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, content=error_dto.model_dump())
+
+
+async def pydantic_validation_exception_handler(
+    request: Request, exc: PydanticValidationError
+) -> JSONResponse:
+    """Handle Pydantic validation errors raised in service layer - 422 Unprocessable Entity."""
+    validation_details = {}
+    for error in exc.errors():
+        field_path = ".".join(str(loc) for loc in error["loc"])
+        if field_path not in validation_details:
+            validation_details[field_path] = []
+        validation_details[field_path].append(error["msg"])
+
+    error_dto = EventErrorDTO.validation_error("Validation failed", validation_details)
+    return JSONResponse(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, content=error_dto.model_dump())
+
+
+def register_exception_handlers(app):
+    """
+    Register all exception handlers with a FastAPI app.
+
+    This function registers all the generic exception handlers, providing
+    consistent error responses across the entire application.
+
+    Args:
+        app: FastAPI application instance
+
+    Example:
+        from fastapi import FastAPI
+        from solace_agent_mesh.gateway.http_sse.shared.exception_handlers import register_exception_handlers
+
+        app = FastAPI()
+        register_exception_handlers(app)
+    """
+    # Domain exception handlers
+    app.add_exception_handler(ValidationError, validation_error_handler)
+    app.add_exception_handler(EntityNotFoundError, entity_not_found_handler)
+    app.add_exception_handler(EntityAlreadyExistsError, entity_already_exists_handler)
+    app.add_exception_handler(
+        BusinessRuleViolationError, business_rule_violation_handler
+    )
+    app.add_exception_handler(ConfigurationError, configuration_error_handler)
+    app.add_exception_handler(DataIntegrityError, data_integrity_error_handler)
+    app.add_exception_handler(ExternalServiceError, external_service_error_handler)
+    app.add_exception_handler(WebUIBackendException, webui_backend_exception_handler)
+
+    # FastAPI built-in exception handlers
+    app.add_exception_handler(HTTPException, http_exception_handler)
+    app.add_exception_handler(StarletteHTTPException, http_exception_handler)
+    app.add_exception_handler(RequestValidationError, request_validation_exception_handler)
+    app.add_exception_handler(PydanticValidationError, pydantic_validation_exception_handler)

solace_agent_mesh/gateway/http_sse/shared/exceptions.py

@@ -0,0 +1,192 @@
+"""
+Generic web exceptions for HTTP/REST APIs.
+
+This module provides a comprehensive set of generic exception classes
+that can be used by any web application for consistent error handling.
+"""
+
+from typing import Any, Dict, List, Optional
+from enum import Enum
+
+
+class EntityOperation(Enum):
+    """Operations that can be performed on entities."""
+    CREATE = "create"
+    UPDATE = "update"
+    DELETE = "delete"
+    READ = "read"
+
+
+class WebUIBackendException(Exception):
+    """Base exception for all web UI backend errors."""
+
+    def __init__(self, message: str, details: Optional[Dict[str, Any]] = None):
+        self.message = message
+        self.details = details or {}
+        super().__init__(self.message)
+
+
+class ValidationError(WebUIBackendException):
+    """
+    Exception for validation errors with field-level details.
+
+    This exception supports both simple validation messages and detailed
+    field-level validation errors with user-friendly message formatting.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        validation_details: Optional[Dict[str, List[str]]] = None,
+        entity_type: Optional[str] = None,
+        entity_identifier: Optional[str] = None
+    ):
+        self.validation_details = validation_details or {}
+        self.entity_type = entity_type
+        self.entity_identifier = entity_identifier
+        super().__init__(message)
+
+    def get_user_friendly_message(self, operation: EntityOperation) -> str:
+        """Generate a user-friendly error message based on context."""
+        if not self.entity_identifier or not self.entity_type:
+            return self.message
+
+        if self.validation_details:
+            field = next(iter(self.validation_details.keys()))
+            error_msg = self.validation_details[field][0]
+            return f"Unable to {operation.value} {self.entity_type} {self.entity_identifier} because of a problem with the {field}: {error_msg.lower()}"
+
+        if self.message:
+            return f"Unable to {operation.value} {self.entity_type} {self.entity_identifier}: {self.message.lower()}"
+
+        return self.message
+
+    @classmethod
+    def builder(cls):
+        """Create a ValidationErrorBuilder for fluent error construction."""
+        return ValidationErrorBuilder()
+
+
+class ValidationErrorBuilder:
+    """Builder for constructing ValidationError instances with fluent API."""
+
+    def __init__(self):
+        self._message = ""
+        self._validation_details = {}
+        self._entity_type = None
+        self._entity_identifier = None
+
+    def message(self, message: str):
+        """Set the main error message."""
+        self._message = message
+        return self
+
+    def formatted_message(self, pattern: str, *args):
+        """Set a formatted error message."""
+        self._message = pattern.format(*args)
+        return self
+
+    def validation_detail(self, field: str, errors: List[str]):
+        """Add validation details for a specific field."""
+        self._validation_details[field] = errors
+        return self
+
+    def formatted_validation_detail(self, field: str, pattern: str, *args):
+        """Add a formatted validation detail for a field."""
+        error_msg = pattern.format(*args)
+        self._validation_details[field] = [error_msg]
+        return self
+
+    def entity_type(self, entity_type: str):
+        """Set the entity type for context."""
+        self._entity_type = entity_type
+        return self
+
+    def entity_identifier(self, identifier: str):
+        """Set the entity identifier for context."""
+        self._entity_identifier = identifier
+        return self
+
+    def build(self) -> ValidationError:
+        """Build the ValidationError instance."""
+        return ValidationError(
+            self._message,
+            self._validation_details,
+            self._entity_type,
+            self._entity_identifier
+        )
+
+
+class EntityNotFoundError(WebUIBackendException):
+    """
+    Generic exception for when an entity is not found.
+
+    This replaces all specific "NotFound" exceptions with a single generic one.
+    Format: "Could not find {entity_type} with id: {entity_id}"
+    """
+
+    def __init__(self, entity_type: str, entity_id: str):
+        self.entity_type = entity_type
+        self.entity_id = str(entity_id)
+        message = f"Could not find {entity_type} with id: {self.entity_id}"
+        details = {"entity_type": entity_type, "entity_id": self.entity_id}
+        super().__init__(message, details)
+
+
+class EntityAlreadyExistsError(WebUIBackendException):
+    """Exception for when an entity already exists."""
+
+    def __init__(self, entity_type: str, identifier: str, value: Any = None):
+        self.entity_type = entity_type
+        self.identifier = identifier
+        self.value = str(value) if value is not None else None
+
+        if value is not None:
+            message = f"{entity_type} with {identifier} '{self.value}' already exists"
+        else:
+            message = f"{entity_type} already exists"
+
+        details = {"entity_type": entity_type, "identifier": identifier}
+        if self.value:
+            details["value"] = self.value
+
+        super().__init__(message, details)
+
+
+class BusinessRuleViolationError(WebUIBackendException):
+    """Exception for business rule violations."""
+
+    def __init__(self, rule: str, message: str):
+        self.rule = rule
+        details = {"rule": rule}
+        super().__init__(message, details)
+
+
+class ConfigurationError(WebUIBackendException):
+    """Exception for configuration-related errors."""
+
+    def __init__(self, component: str, message: str):
+        self.component = component
+        details = {"component": component}
+        super().__init__(message, details)
+
+
+class DataIntegrityError(WebUIBackendException):
+    """Exception for data integrity violations."""
+
+    def __init__(self, constraint: str, message: str):
+        self.constraint = constraint
+        details = {"constraint": constraint}
+        super().__init__(message, details)
+
+
+class ExternalServiceError(WebUIBackendException):
+    """Exception for external service communication errors."""
+
+    def __init__(self, service: str, message: str, status_code: Optional[int] = None):
+        self.service = service
+        self.status_code = status_code
+        details = {"service": service}
+        if status_code:
+            details["status_code"] = status_code
+        super().__init__(message, details)

solace_agent_mesh/gateway/http_sse/shared/pagination.py

@@ -0,0 +1,138 @@
+"""
+Pagination utilities for API responses.
+
+Provides standard pagination patterns for consistent API responses across the application.
+
+Default pagination settings:
+- Page number: 1
+- Page size: 20
+- Max page size: 100
+"""
+
+from pydantic import BaseModel, Field
+from typing import TypeVar, Generic
+
+T = TypeVar("T")
+
+DEFAULT_PAGE_NUMBER = 1
+DEFAULT_PAGE_SIZE = 20
+MAX_PAGE_SIZE = 100
+
+
+class PaginationParams(BaseModel):
+    """
+    Request parameters for pagination with sensible defaults.
+
+    Defaults:
+    - page_number: 1
+    - page_size: 20
+    """
+    page_number: int = Field(default=DEFAULT_PAGE_NUMBER, ge=1, alias="pageNumber")
+    page_size: int = Field(default=DEFAULT_PAGE_SIZE, ge=1, le=MAX_PAGE_SIZE, alias="pageSize")
+
+    @property
+    def offset(self) -> int:
+        """Calculate the offset for database queries."""
+        return (self.page_number - 1) * self.page_size
+
+    model_config = {"populate_by_name": True}
+
+
+def get_pagination_or_default(pagination: PaginationParams | None = None) -> PaginationParams:
+    """
+    Get pagination parameters or return defaults if None.
+
+    This helper ensures all paginated endpoints use the same defaults:
+    - page_number: 1
+    - page_size: 20
+
+    Args:
+        pagination: Optional pagination parameters
+
+    Returns:
+        PaginationParams with defaults if None provided
+
+    Example:
+        pagination = get_pagination_or_default(request_pagination)
+        # Always returns valid PaginationParams with defaults if None
+    """
+    if pagination is None:
+        return PaginationParams()
+    return pagination
+
+
+class PaginationMeta(BaseModel):
+    """Pagination metadata for API responses."""
+    page_number: int = Field(..., alias="pageNumber")
+    count: int
+    page_size: int = Field(..., alias="pageSize")
+    next_page: int | None = Field(..., alias="nextPage")
+    total_pages: int = Field(..., alias="totalPages")
+
+    model_config = {"populate_by_name": True}
+
+
+class Meta(BaseModel):
+    """Metadata container for API responses."""
+    pagination: PaginationMeta
+
+
+class PaginatedResponse(BaseModel, Generic[T]):
+    """Generic paginated response with data and metadata."""
+    data: list[T]
+    meta: Meta
+
+    @classmethod
+    def create(
+        cls, data: list[T], total_count: int, pagination: PaginationParams
+    ) -> "PaginatedResponse[T]":
+        """
+        Create a paginated response from data and pagination parameters.
+
+        Args:
+            data: List of items for current page
+            total_count: Total number of items across all pages
+            pagination: Pagination parameters used for the request
+
+        Returns:
+            PaginatedResponse with data and calculated metadata
+        """
+        total_pages = (total_count + pagination.page_size - 1) // pagination.page_size
+        next_page = pagination.page_number + 1 if pagination.page_number < total_pages else None
+
+        pagination_meta = PaginationMeta(
+            page_number=pagination.page_number,
+            count=total_count,
+            page_size=pagination.page_size,
+            next_page=next_page,
+            total_pages=total_pages,
+        )
+
+        return cls(
+            data=data,
+            meta=Meta(pagination=pagination_meta)
+        )
+
+    model_config = {"populate_by_name": True}
+
+
+class DataResponse(BaseModel, Generic[T]):
+    """Simple data response wrapper."""
+    data: T
+
+    @classmethod
+    def create(cls, data: T) -> "DataResponse[T]":
+        """Create a data response from data."""
+        return cls(data=data)
+
+
+__all__ = [
+    "PaginationParams",
+    "PaginationMeta",
+    "PaginatedResponse",
+    "DataResponse",
+    "get_pagination_or_default",
+    "DEFAULT_PAGE_NUMBER",
+    "DEFAULT_PAGE_SIZE",
+    "MAX_PAGE_SIZE",
+]