solace-agent-mesh 1.4.6__py3-none-any.whl → 1.4.8__py3-none-any.whl

solace_agent_mesh/gateway/http_sse/shared/__init__.py

@@ -1,7 +1,8 @@
 """
 Shared Utilities and Constants
 
-Contains common utilities, constants, enums, and types used across layers.
+Contains common utilities, constants, enums, types, and exception handling
+used across layers.
 """
 
 from .auth_utils import get_current_user
@@ -14,7 +15,71 @@ from .timestamp_utils import (
     validate_epoch_ms,
 )
 
+# Exception handling exports
+from .exceptions import (
+    WebUIBackendException,
+    ValidationError,
+    EntityNotFoundError,
+    EntityAlreadyExistsError,
+    BusinessRuleViolationError,
+    ConfigurationError,
+    DataIntegrityError,
+    ExternalServiceError,
+    EntityOperation,
+    ValidationErrorBuilder,
+)
+from .error_dto import EventErrorDTO
+from .exception_handlers import (
+    register_exception_handlers,
+    create_error_response,
+    validation_error_handler,
+    entity_not_found_handler,
+    entity_already_exists_handler,
+    business_rule_violation_handler,
+    configuration_error_handler,
+    data_integrity_error_handler,
+    external_service_error_handler,
+    webui_backend_exception_handler,
+)
+
+# Repository base classes
+from .base_repository import (
+    BaseRepository,
+    PaginatedRepository,
+    ValidationMixin,
+)
+
+# Pagination utilities
+from .pagination import (
+    PaginationParams,
+    PaginatedResponse,
+    DataResponse,
+)
+
+# Database utilities
+from .database_exceptions import (
+    DatabaseExceptionHandler,
+    DatabaseErrorDecorator,
+    handle_database_errors,
+)
+# Database helpers (SimpleJSON type only - transaction management removed)
+from .database_helpers import SimpleJSON
+
+# Generic utilities
+from .utils import generate_uuid, to_snake_case, to_pascal_case
+
+# Response utilities
+from .response_utils import (
+    create_data_response,
+    create_paginated_response,
+    create_empty_data_response,
+    create_success_response,
+    create_list_response,
+    StandardResponseMixin,
+)
+
 __all__ = [
+    # Utilities
     "get_current_user",
     "now_epoch_ms",
     "epoch_ms_to_iso8601",
@@ -22,4 +87,60 @@ __all__ = [
     "datetime_to_epoch_ms",
     "epoch_ms_to_datetime",
     "validate_epoch_ms",
+
+    # Exception classes
+    "WebUIBackendException",
+    "ValidationError",
+    "EntityNotFoundError",
+    "EntityAlreadyExistsError",
+    "BusinessRuleViolationError",
+    "ConfigurationError",
+    "DataIntegrityError",
+    "ExternalServiceError",
+    "EntityOperation",
+    "ValidationErrorBuilder",
+
+    # Error response DTO
+    "EventErrorDTO",
+
+    # Exception handlers
+    "register_exception_handlers",
+    "create_error_response",
+    "validation_error_handler",
+    "entity_not_found_handler",
+    "entity_already_exists_handler",
+    "business_rule_violation_handler",
+    "configuration_error_handler",
+    "data_integrity_error_handler",
+    "external_service_error_handler",
+    "webui_backend_exception_handler",
+
+    # Repository base classes
+    "BaseRepository",
+    "PaginatedRepository",
+    "ValidationMixin",
+
+    # Pagination utilities
+    "PaginationParams",
+    "PaginatedResponse",
+    "DataResponse",
+
+    # Database utilities
+    "DatabaseExceptionHandler",
+    "DatabaseErrorDecorator",
+    "handle_database_errors",
+    # Database transaction functions removed - use FastAPI dependency injection
+
+    # Generic utilities
+    "generate_uuid",
+    "to_snake_case",
+    "to_pascal_case",
+
+    # Response utilities
+    "create_data_response",
+    "create_paginated_response",
+    "create_empty_data_response",
+    "create_success_response",
+    "create_list_response",
+    "StandardResponseMixin",
 ]

solace_agent_mesh/gateway/http_sse/shared/base_repository.py

@@ -0,0 +1,278 @@
+"""
+Base repository classes with proper transaction management.
+
+This module provides base classes for repositories that follow FastAPI best practices
+for database session management and transaction handling.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Dict, Any, List, Optional, TypeVar, Generic, Type
+from sqlalchemy.orm import Session
+from sqlalchemy.exc import NoResultFound
+from .exceptions import EntityNotFoundError, ValidationError
+from .types import PaginationInfo
+
+
+T = TypeVar('T')
+ModelType = TypeVar('ModelType')
+EntityType = TypeVar('EntityType')
+
+
+class BaseRepository(ABC, Generic[ModelType, EntityType]):
+    """
+    Abstract base class for repositories with common database operations.
+
+    This base class provides common patterns for database operations
+    without manual transaction management, following the principle that
+    transactions should be handled at the service/API layer.
+    """
+
+    def __init__(self, model_class: Type[ModelType], entity_class: Type[EntityType]):
+        """
+        Initialize repository with model and entity classes.
+
+        Args:
+            model_class: SQLAlchemy model class
+            entity_class: Pydantic entity class
+        """
+        self.model_class = model_class
+        self.entity_class = entity_class
+
+    @property
+    @abstractmethod
+    def entity_name(self) -> str:
+        """Return the entity name for error messages."""
+        pass
+
+    def create(self, session: Session, create_data: Dict[str, Any]) -> EntityType:
+        """
+        Create a new entity.
+
+        Args:
+            session: Database session (managed externally)
+            create_data: Data for creating the entity
+
+        Returns:
+            Created entity
+
+        Note:
+            This method does NOT commit the transaction.
+            Commit/rollback is handled by the service layer.
+        """
+        model_instance = self.model_class(**create_data)
+
+        session.add(model_instance)
+        session.flush()  # Flush to get generated IDs
+        session.refresh(model_instance)
+
+        entity = self.entity_class.model_validate(model_instance)
+
+        return entity
+
+    def get_by_id(self, session: Session, entity_id: Any) -> EntityType:
+        """
+        Get entity by ID.
+
+        Args:
+            session: Database session
+            entity_id: Entity identifier
+
+        Returns:
+            Entity instance
+
+        Raises:
+            EntityNotFoundError: If entity not found
+        """
+        model_instance = session.query(self.model_class).filter(
+            self.model_class.id == str(entity_id)
+        ).first()
+
+        if not model_instance:
+            raise EntityNotFoundError(self.entity_name, entity_id)
+
+        return self.entity_class.model_validate(model_instance)
+
+    def get_all(self, session: Session, limit: Optional[int] = None, offset: Optional[int] = None) -> List[EntityType]:
+        """
+        Get all entities with optional pagination.
+
+        Args:
+            session: Database session
+            limit: Maximum number of results
+            offset: Number of results to skip
+
+        Returns:
+            List of entities
+        """
+        query = session.query(self.model_class)
+
+        if offset:
+            query = query.offset(offset)
+        if limit:
+            query = query.limit(limit)
+
+        model_instances = query.all()
+        return [self.entity_class.model_validate(instance) for instance in model_instances]
+
+    def update(self, session: Session, entity_id: Any, update_data: Dict[str, Any]) -> EntityType:
+        """
+        Update an entity.
+
+        Args:
+            session: Database session
+            entity_id: Entity identifier
+            update_data: Data to update
+
+        Returns:
+            Updated entity
+
+        Raises:
+            EntityNotFoundError: If entity not found
+        """
+        model_instance = session.query(self.model_class).filter(
+            self.model_class.id == str(entity_id)
+        ).first()
+
+        if not model_instance:
+            raise EntityNotFoundError(self.entity_name, entity_id)
+
+        for key, value in update_data.items():
+            if value is not None and hasattr(model_instance, key):
+                setattr(model_instance, key, value)
+
+        session.flush()  # Flush to validate constraints
+        session.refresh(model_instance)
+
+        entity = self.entity_class.model_validate(model_instance)
+
+        return entity
+
+    def delete(self, session: Session, entity_id: Any) -> None:
+        """
+        Delete an entity.
+
+        Args:
+            session: Database session
+            entity_id: Entity identifier
+
+        Raises:
+            EntityNotFoundError: If entity not found
+        """
+        model_instance = session.query(self.model_class).filter(
+            self.model_class.id == str(entity_id)
+        ).first()
+
+        if not model_instance:
+            raise EntityNotFoundError(self.entity_name, entity_id)
+
+        session.delete(model_instance)
+        session.flush()  # Flush to validate constraints
+
+    def exists(self, session: Session, entity_id: Any) -> bool:
+        """
+        Check if an entity exists.
+
+        Args:
+            session: Database session
+            entity_id: Entity identifier
+
+        Returns:
+            True if entity exists, False otherwise
+        """
+        count = session.query(self.model_class).filter(
+            self.model_class.id == str(entity_id)
+        ).count()
+
+        return count > 0
+
+    def count(self, session: Session) -> int:
+        """
+        Get total count of entities.
+
+        Args:
+            session: Database session
+
+        Returns:
+            Total number of entities
+        """
+        return session.query(self.model_class).count()
+
+
+class PaginatedRepository(BaseRepository[ModelType, EntityType]):
+    """
+    Base repository with enhanced pagination support.
+    """
+
+    def get_paginated(self, session: Session, page_number: int, page_size: int) -> tuple[List[EntityType], int]:
+        """
+        Get paginated results.
+
+        Args:
+            session: Database session
+            page_number: Page number (1-based)
+            page_size: Number of items per page
+
+        Returns:
+            Tuple of (entities, total_count)
+        """
+        offset = (page_number - 1) * page_size
+
+        total_count = self.count(session)
+
+        entities = self.get_all(session, limit=page_size, offset=offset)
+
+        return entities, total_count
+
+    def get_paginated_with_info(self, session: Session, pagination: PaginationInfo) -> tuple[List[EntityType], PaginationInfo]:
+        """
+        Get paginated results with complete pagination info.
+
+        Args:
+            session: Database session
+            pagination: Pagination parameters
+
+        Returns:
+            Tuple of (entities, updated_pagination_info)
+        """
+        entities, total_count = self.get_paginated(session, pagination.page, pagination.page_size)
+
+        updated_pagination = PaginationInfo(
+            page=pagination.page,
+            page_size=pagination.page_size,
+            total_items=total_count,
+            total_pages=(total_count + pagination.page_size - 1) // pagination.page_size,
+            has_next=pagination.page * pagination.page_size < total_count,
+            has_previous=pagination.page > 1
+        )
+
+        return entities, updated_pagination
+
+
+class ValidationMixin:
+    """
+    Mixin for repositories that need validation logic.
+    """
+
+    def validate_create_data(self, create_data: Dict[str, Any]) -> None:
+        """
+        Validate data before creation.
+
+        Args:
+            create_data: Data to validate
+
+        Raises:
+            ValidationError: If validation fails
+        """
+        pass
+
+    def validate_update_data(self, update_data: Dict[str, Any]) -> None:
+        """
+        Validate data before update.
+
+        Args:
+            update_data: Data to validate
+
+        Raises:
+            ValidationError: If validation fails
+        """
+        pass

solace_agent_mesh/gateway/http_sse/shared/database_exceptions.py

@@ -0,0 +1,274 @@
+"""
+Database Exception Handling
+
+Provides centralized handling for converting SQLAlchemy exceptions to domain exceptions.
+This handler translates low-level database errors into meaningful business exceptions
+that can be properly handled by the API layer.
+"""
+
+from typing import Optional, Dict, List
+from sqlalchemy.exc import IntegrityError, SQLAlchemyError, OperationalError, DatabaseError
+from .exceptions import ValidationError, DataIntegrityError, EntityAlreadyExistsError
+
+
+class DatabaseExceptionHandler:
+    """
+    Centralized handler for converting SQLAlchemy exceptions to domain exceptions.
+
+    This handler translates low-level database errors into meaningful business exceptions
+    that can be properly handled by the API layer.
+    """
+
+    @staticmethod
+    def handle_integrity_error(e: IntegrityError, entity_type: str = "Resource") -> ValidationError:
+        """
+        Convert SQLAlchemy integrity constraint violations to domain exceptions.
+
+        Args:
+            e: The SQLAlchemy IntegrityError
+            entity_type: The type of entity being operated on
+
+        Returns:
+            ValidationError with appropriate message and validation details
+        """
+        # Try to get the most descriptive error message for constraint matching
+        full_message = str(e)
+        orig_message = str(e.orig) if hasattr(e, 'orig') and e.orig else ""
+
+        # Use the message that contains constraint information
+        if any(keyword in full_message for keyword in ['constraint', 'UNIQUE', 'NULL', 'CHECK', 'FOREIGN']):
+            # Extract the most specific constraint line from the full message
+            lines = full_message.split('\n')
+
+            # Prioritize SQL lines that contain actual constraint details
+            for line in lines:
+                if '[SQL:' in line and any(keyword in line for keyword in ['UNIQUE', 'NULL', 'CHECK', 'FOREIGN']):
+                    # Extract just the SQL part without the [SQL: ] wrapper
+                    if '[SQL:' in line and ']' in line:
+                        error_message = line.split('[SQL:')[1].split(']')[0].strip()
+                        break
+                    error_message = line.strip()
+                    break
+            else:
+                # Fallback to any line with constraint keywords
+                for line in lines:
+                    if any(keyword in line for keyword in ['constraint', 'UNIQUE', 'NULL', 'CHECK', 'FOREIGN']):
+                        error_message = line.strip()
+                        break
+                else:
+                    error_message = full_message
+        else:
+            # Fallback to orig if no constraint info in main message
+            error_message = orig_message or full_message
+
+        # Handle UNIQUE constraint violations and concurrent modifications
+        if ("UNIQUE constraint failed" in error_message or
+            "duplicate key value" in error_message.lower() or
+            "concurrent modification" in error_message.lower() or
+            "row was updated or deleted by another transaction" in error_message.lower()):
+            field_name = DatabaseExceptionHandler._extract_field_from_unique_error(error_message)
+            return EntityAlreadyExistsError(
+                entity_type=entity_type,
+                identifier=field_name,
+                value="provided value"
+            )
+
+        # Handle NOT NULL constraint violations
+        if "NOT NULL constraint failed" in error_message or "null value in column" in error_message.lower():
+            field_name = DatabaseExceptionHandler._extract_field_from_null_error(error_message)
+            return ValidationError(
+                message="Required field is missing",
+                validation_details={field_name: ["This field is required"]},
+                entity_type=entity_type
+            )
+
+        # Handle CHECK constraint violations
+        if "CHECK constraint failed" in error_message or "check constraint" in error_message.lower():
+            constraint_name = DatabaseExceptionHandler._extract_constraint_name(error_message)
+            field_name = DatabaseExceptionHandler._map_constraint_to_field(constraint_name)
+            return ValidationError(
+                message="Field validation failed",
+                validation_details={field_name: ["Value violates validation rules"]},
+                entity_type=entity_type
+            )
+
+        # Handle FOREIGN KEY constraint violations
+        if "FOREIGN KEY constraint failed" in error_message or "foreign key constraint" in error_message.lower():
+            return ValidationError(
+                message="Referenced resource does not exist",
+                validation_details={"reference": ["Invalid reference to related resource"]},
+                entity_type=entity_type
+            )
+
+        # Generic integrity error fallback
+        return DataIntegrityError(
+            constraint="integrity_violation",
+            message=f"Database constraint violation: {error_message}"
+        )
+
+    @staticmethod
+    def handle_operational_error(e: OperationalError, entity_type: str = "Resource") -> DataIntegrityError:
+        """
+        Handle SQLAlchemy operational errors (connection issues, timeouts, etc.).
+
+        Args:
+            e: The SQLAlchemy OperationalError
+            entity_type: The type of entity being operated on
+
+        Returns:
+            DataIntegrityError with appropriate message
+        """
+        error_message = str(e.orig) if hasattr(e, 'orig') else str(e)
+
+        if "timeout" in error_message.lower():
+            return DataIntegrityError(
+                constraint="timeout",
+                message="Database operation timed out. Please try again."
+            )
+
+        if "connection" in error_message.lower():
+            return DataIntegrityError(
+                constraint="connection_error",
+                message="Database connection failed. Please try again later."
+            )
+
+        return DataIntegrityError(
+            constraint="operational_error",
+            message="Database operation failed. Please contact support if this persists."
+        )
+
+    @staticmethod
+    def handle_database_error(e: DatabaseError, entity_type: str = "Resource") -> DataIntegrityError:
+        """
+        Handle general SQLAlchemy database errors.
+
+        Args:
+            e: The SQLAlchemy DatabaseError
+            entity_type: The type of entity being operated on
+
+        Returns:
+            DataIntegrityError with appropriate message
+        """
+        error_message = str(e.orig) if hasattr(e, 'orig') else str(e)
+
+        return DataIntegrityError(
+            constraint="database_error",
+            message="A database error occurred. Please contact support."
+        )
+
+    @staticmethod
+    def handle_sqlalchemy_error(e: SQLAlchemyError, entity_type: str = "Resource") -> DataIntegrityError:
+        """
+        Handle any other SQLAlchemy errors not caught by specific handlers.
+
+        Args:
+            e: The SQLAlchemy error
+            entity_type: The type of entity being operated on
+
+        Returns:
+            DataIntegrityError with generic message
+        """
+        error_message = str(e)
+
+        return DataIntegrityError(
+            constraint="sqlalchemy_error",
+            message="An unexpected database error occurred. Please contact support."
+        )
+
+    @staticmethod
+    def _extract_field_from_unique_error(error_message: str) -> str:
+        """Extract field name from UNIQUE constraint error message."""
+        # Try to extract field name from common formats
+        if "agents.name" in error_message:
+            return "name"
+        elif "agents.id" in error_message:
+            return "id"
+        elif "." in error_message:
+            # Extract field after table.field pattern
+            parts = error_message.split(".")
+            if len(parts) > 1:
+                field_part = parts[1].split()[0]  # Get first word after dot
+                return field_part.strip('()"\'')
+
+        return "field"  # Generic fallback
+
+    @staticmethod
+    def _extract_field_from_null_error(error_message: str) -> str:
+        """Extract field name from NOT NULL constraint error message."""
+        # Common patterns: "NOT NULL constraint failed: agents.name"
+        if ":" in error_message:
+            field_part = error_message.split(":")[-1].strip()
+            if "." in field_part:
+                return field_part.split(".")[-1]
+            return field_part
+
+        return "field"  # Generic fallback
+
+    @staticmethod
+    def _extract_constraint_name(error_message: str) -> str:
+        """Extract constraint name from CHECK constraint error message."""
+        # Common patterns: "CHECK constraint failed: check_name_length"
+        if ":" in error_message:
+            constraint_part = error_message.split(":")[-1].strip()
+            return constraint_part
+
+        return "unknown_constraint"
+
+    @staticmethod
+    def _map_constraint_to_field(constraint_name: str) -> str:
+        """Map database constraint names to user-friendly field names."""
+        constraint_field_map = {
+            "check_name_length": "name",
+            "check_description_length": "description",
+            "check_system_prompt_length": "systemPrompt",
+            "check_created_by_length": "createdBy",
+            "check_updated_by_length": "updatedBy",
+            "check_id_length": "id"
+        }
+
+        return constraint_field_map.get(constraint_name, "field")
+
+
+class DatabaseErrorDecorator:
+    """
+    Decorator class for wrapping repository methods with database exception handling.
+    """
+
+    def __init__(self, entity_type: str = "Resource"):
+        self.entity_type = entity_type
+
+    def __call__(self, func):
+        """
+        Decorator that wraps repository methods with database exception handling.
+
+        Args:
+            func: The repository method to wrap
+
+        Returns:
+            Wrapped function with exception handling
+        """
+        def wrapper(*args, **kwargs):
+            try:
+                return func(*args, **kwargs)
+            except IntegrityError as e:
+                raise DatabaseExceptionHandler.handle_integrity_error(e, self.entity_type)
+            except OperationalError as e:
+                raise DatabaseExceptionHandler.handle_operational_error(e, self.entity_type)
+            except DatabaseError as e:
+                raise DatabaseExceptionHandler.handle_database_error(e, self.entity_type)
+            except SQLAlchemyError as e:
+                raise DatabaseExceptionHandler.handle_sqlalchemy_error(e, self.entity_type)
+
+        return wrapper
+
+
+def handle_database_errors(entity_type: str = "Resource"):
+    """
+    Convenience decorator for database exception handling.
+
+    Usage:
+        @handle_database_errors("Agent")
+        def create_agent(self, ...):
+            # Repository method implementation
+    """
+    return DatabaseErrorDecorator(entity_type)