10xgraph-api 0.7.0__py3-none-any.whl

tenxgraph_api/src/app/core/exceptions/handle_errors.py

@@ -0,0 +1,363 @@
+# Handle all exceptions of the 10xGraph API here
+from fastapi import FastAPI
+from fastapi.exceptions import RequestValidationError
+from starlette.exceptions import HTTPException
+from starlette.requests import Request
+from tenxgraph.core.exceptions import (
+    GraphError,
+    GraphRecursionError,
+    MetricsError,
+    NodeError,
+    SchemaVersionError,
+    SerializationError,
+    StorageError,
+    TransientStorageError,
+)
+from tenxgraph.utils.validators import ValidationError
+
+from tenxgraph_api.src.app.core import logger
+from tenxgraph_api.src.app.core.config.settings import get_settings
+from tenxgraph_api.src.app.utils import error_response
+from tenxgraph_api.src.app.utils.schemas import ErrorSchemas
+
+from .resources_exceptions import ResourceNotFoundError as APIResourceNotFoundError
+from .user_exception import (
+    UserAccountError,
+    UserPermissionError,
+)
+
+
+def _sanitize_error_message(message: str, error_code: str, is_production: bool) -> str:
+    """
+    Sanitize error messages for production to avoid exposing internal details.
+
+    Args:
+        message: Original error message
+        error_code: Error code for the exception
+        is_production: Whether the app is in production mode
+
+    Returns:
+        Sanitized message (generic in production, detailed in development)
+    """
+    if not is_production:
+        return message
+
+    # Generic messages by status code category
+    generic_messages = {
+        "VALIDATION_ERROR": "The request data is invalid. Please check your input.",
+        "HTTPException": "An error occurred processing your request.",
+        "GRAPH_": "An error occurred executing the graph.",
+        "NODE_": "An error occurred in a graph node.",
+        "STORAGE_": "An error occurred accessing storage.",
+        "METRICS_": "An error occurred collecting metrics.",
+        "SCHEMA_VERSION_": "Schema version mismatch.",
+        "SERIALIZATION_": "An error occurred processing data.",
+    }
+
+    # Return generic message based on error code prefix
+    for prefix, generic_msg in generic_messages.items():
+        if error_code.startswith(prefix):
+            return generic_msg
+
+    return "An unexpected error occurred. Please contact support."
+
+
+def init_errors_handler(app: FastAPI):  # noqa: PLR0915
+    """
+    Initialize error handlers for the FastAPI application.
+
+    Args:
+        app (FastAPI): The FastAPI application instance.
+
+    Raises:
+        HTTPException: Handles HTTP exceptions.
+        RequestValidationError: Handles request validation errors.
+        ValueError: Handles value errors.
+        UserAccountError: Handles custom user account errors.
+        UserPermissionError: Handles custom user permission errors.
+        APIResourceNotFoundError: Handles custom API resource not found errors.
+    """
+    settings = get_settings()
+    is_production = settings.MODE == "production"
+
+    @app.exception_handler(HTTPException)
+    async def http_exception_handler(request: Request, exc: HTTPException):
+        logger.error(f"HTTP exception: url: {request.base_url}", exc_info=exc)
+
+        # Get request ID for tracking
+        request_id = getattr(request.state, "request_id", "unknown")
+
+        message = _sanitize_error_message(str(exc.detail), "HTTPException", is_production)
+
+        # Log full details but return sanitized message in production
+        if is_production:
+            logger.error(f"Request {request_id} - HTTPException details: {exc.detail}")
+
+        return error_response(
+            request,
+            error_code="HTTPException",
+            message=message,
+            status_code=exc.status_code,
+        )
+
+    @app.exception_handler(RequestValidationError)
+    async def validation_exception_handler(request: Request, exc: RequestValidationError):
+        request_id = getattr(request.state, "request_id", "unknown")
+        details = [ErrorSchemas(**error) for error in exc.errors()]
+
+        # Log where and why validation failed, never the submitted values: exc (and its
+        # traceback) embeds the raw request body, which can hold messages, files or tokens.
+        logger.warning(
+            "Request %s - validation failed: %s %s: %s",
+            request_id,
+            request.method,
+            request.url.path,
+            [f"{'.'.join(map(str, d.loc))}: {d.msg}" for d in details],
+        )
+
+        if is_production:
+            message = "The request data is invalid. Please check your input."
+        else:
+            message = str(exc.body) if exc.body else "Validation error"
+
+        return error_response(
+            request,
+            error_code="VALIDATION_ERROR",
+            message=message,
+            details=details if not is_production else None,
+            status_code=422,
+        )
+
+    @app.exception_handler(ValueError)
+    async def value_exception_handler(request: Request, exc: ValueError):
+        logger.error(f"Value error exception: url: {request.base_url}", exc_info=exc)
+
+        request_id = getattr(request.state, "request_id", "unknown")
+
+        message = str(exc)
+        if is_production:
+            logger.error(f"Request {request_id} - ValueError details: {message}")
+            message = "Invalid input provided."
+
+        return error_response(
+            request,
+            error_code="VALIDATION_ERROR",
+            message=message,
+            status_code=422,
+        )
+
+    ########################################
+    ##### Custom exception handler here ####
+    ########################################
+    @app.exception_handler(UserAccountError)
+    async def user_account_exception_handler(request: Request, exc: UserAccountError):
+        logger.warning("UserAccountError on %s: %s", request.url.path, exc.error_code)
+        response = error_response(
+            request,
+            error_code=exc.error_code,
+            message=exc.message,
+            status_code=exc.status_code,
+        )
+        if exc.status_code == 401:  # noqa: PLR2004
+            response.headers["WWW-Authenticate"] = 'Bearer realm="auth_required"'
+        return response
+
+    @app.exception_handler(UserPermissionError)
+    async def user_write_exception_handler(request: Request, exc: UserPermissionError):
+        logger.error(f"UserPermissionError: url: {request.base_url}", exc_info=exc)
+        return error_response(
+            request,
+            error_code=exc.error_code,
+            message=exc.message,
+            status_code=exc.status_code,
+        )
+
+    @app.exception_handler(APIResourceNotFoundError)
+    async def resource_not_found_exception_handler(request: Request, exc: APIResourceNotFoundError):
+        logger.error(f"ResourceNotFoundError: url: {request.base_url}", exc_info=exc)
+        return error_response(
+            request,
+            error_code=exc.error_code,
+            message=exc.message,
+            status_code=exc.status_code,
+        )
+
+    ## Need to handle 10xGraph specific exceptions here
+    @app.exception_handler(ValidationError)
+    async def graph_validation_exception_handler(request: Request, exc: ValidationError):
+        logger.error(f"10xGraph ValidationError: url: {request.base_url}", exc_info=exc)
+
+        request_id = getattr(request.state, "request_id", "unknown")
+        message = _sanitize_error_message(str(exc), "AGENTFLOW_VALIDATION_ERROR", is_production)
+
+        if is_production:
+            logger.error(f"Request {request_id} - 10xGraph ValidationError: {exc}")
+
+        return error_response(
+            request,
+            error_code="AGENTFLOW_VALIDATION_ERROR",
+            message=message,
+            status_code=422,
+        )
+
+    @app.exception_handler(GraphError)
+    async def graph_error_exception_handler(request: Request, exc: GraphError):
+        logger.error(f"GraphError: url: {request.base_url}", exc_info=exc)
+
+        request_id = getattr(request.state, "request_id", "unknown")
+        error_code = getattr(exc, "error_code", "GRAPH_000")
+        original_message = getattr(exc, "message", str(exc))
+        message = _sanitize_error_message(original_message, error_code, is_production)
+
+        if is_production:
+            logger.error(f"Request {request_id} - GraphError: {original_message}")
+
+        return error_response(
+            request,
+            error_code=error_code,
+            message=message,
+            details=getattr(exc, "context", None) if not is_production else None,
+            status_code=500,
+        )
+
+    @app.exception_handler(NodeError)
+    async def node_error_exception_handler(request: Request, exc: NodeError):
+        logger.error(f"NodeError: url: {request.base_url}", exc_info=exc)
+
+        request_id = getattr(request.state, "request_id", "unknown")
+        error_code = getattr(exc, "error_code", "NODE_000")
+        original_message = getattr(exc, "message", str(exc))
+        message = _sanitize_error_message(original_message, error_code, is_production)
+
+        if is_production:
+            logger.error(f"Request {request_id} - NodeError: {original_message}")
+
+        return error_response(
+            request,
+            error_code=error_code,
+            message=message,
+            details=getattr(exc, "context", None) if not is_production else None,
+            status_code=500,
+        )
+
+    @app.exception_handler(GraphRecursionError)
+    async def graph_recursion_error_exception_handler(request: Request, exc: GraphRecursionError):
+        logger.error(f"GraphRecursionError: url: {request.base_url}", exc_info=exc)
+
+        request_id = getattr(request.state, "request_id", "unknown")
+        error_code = getattr(exc, "error_code", "GRAPH_RECURSION_000")
+        original_message = getattr(exc, "message", str(exc))
+        message = _sanitize_error_message(original_message, error_code, is_production)
+
+        if is_production:
+            logger.error(f"Request {request_id} - GraphRecursionError: {original_message}")
+
+        return error_response(
+            request,
+            error_code=error_code,
+            message=message,
+            details=getattr(exc, "context", None) if not is_production else None,
+            status_code=500,
+        )
+
+    @app.exception_handler(StorageError)
+    async def storage_error_exception_handler(request: Request, exc: StorageError):
+        logger.error(f"StorageError: url: {request.base_url}", exc_info=exc)
+
+        request_id = getattr(request.state, "request_id", "unknown")
+        error_code = getattr(exc, "error_code", "STORAGE_000")
+        original_message = getattr(exc, "message", str(exc))
+        message = _sanitize_error_message(original_message, error_code, is_production)
+
+        if is_production:
+            logger.error(f"Request {request_id} - StorageError: {original_message}")
+
+        return error_response(
+            request,
+            error_code=error_code,
+            message=message,
+            details=getattr(exc, "context", None) if not is_production else None,
+            status_code=500,
+        )
+
+    @app.exception_handler(TransientStorageError)
+    async def transient_storage_error_exception_handler(
+        request: Request, exc: TransientStorageError
+    ):
+        logger.error(f"TransientStorageError: url: {request.base_url}", exc_info=exc)
+
+        request_id = getattr(request.state, "request_id", "unknown")
+        error_code = getattr(exc, "error_code", "TRANSIENT_STORAGE_000")
+        original_message = getattr(exc, "message", str(exc))
+        message = _sanitize_error_message(original_message, error_code, is_production)
+
+        if is_production:
+            logger.error(f"Request {request_id} - TransientStorageError: {original_message}")
+
+        return error_response(
+            request,
+            error_code=error_code,
+            message=message,
+            details=getattr(exc, "context", None) if not is_production else None,
+            status_code=503,
+        )
+
+    @app.exception_handler(MetricsError)
+    async def metrics_error_exception_handler(request: Request, exc: MetricsError):
+        logger.error(f"MetricsError: url: {request.base_url}", exc_info=exc)
+
+        request_id = getattr(request.state, "request_id", "unknown")
+        error_code = getattr(exc, "error_code", "METRICS_000")
+        original_message = getattr(exc, "message", str(exc))
+        message = _sanitize_error_message(original_message, error_code, is_production)
+
+        if is_production:
+            logger.error(f"Request {request_id} - MetricsError: {original_message}")
+
+        return error_response(
+            request,
+            error_code=error_code,
+            message=message,
+            details=getattr(exc, "context", None) if not is_production else None,
+            status_code=500,
+        )
+
+    @app.exception_handler(SchemaVersionError)
+    async def schema_version_error_exception_handler(request: Request, exc: SchemaVersionError):
+        logger.error(f"SchemaVersionError: url: {request.base_url}", exc_info=exc)
+
+        request_id = getattr(request.state, "request_id", "unknown")
+        error_code = getattr(exc, "error_code", "SCHEMA_VERSION_000")
+        original_message = getattr(exc, "message", str(exc))
+        message = _sanitize_error_message(original_message, error_code, is_production)
+
+        if is_production:
+            logger.error(f"Request {request_id} - SchemaVersionError: {original_message}")
+
+        return error_response(
+            request,
+            error_code=error_code,
+            message=message,
+            details=getattr(exc, "context", None) if not is_production else None,
+            status_code=422,
+        )
+
+    @app.exception_handler(SerializationError)
+    async def serialization_error_exception_handler(request: Request, exc: SerializationError):
+        logger.error(f"SerializationError: url: {request.base_url}", exc_info=exc)
+
+        request_id = getattr(request.state, "request_id", "unknown")
+        error_code = getattr(exc, "error_code", "SERIALIZATION_000")
+        original_message = getattr(exc, "message", str(exc))
+        message = _sanitize_error_message(original_message, error_code, is_production)
+
+        if is_production:
+            logger.error(f"Request {request_id} - SerializationError: {original_message}")
+
+        return error_response(
+            request,
+            error_code=error_code,
+            message=message,
+            details=getattr(exc, "context", None) if not is_production else None,
+            status_code=500,
+        )

tenxgraph_api/src/app/core/exceptions/resources_exceptions.py

@@ -0,0 +1,72 @@
+from .general_exception import GeneralException
+
+
+class ResourceNotFoundError(GeneralException):
+    """
+    Exception raised when a requested resource is not found.
+
+    Attributes:
+        message (str): Explanation of the error.
+        status_code (int): HTTP status code for the error.
+        error_code (str): Specific error code for the error.
+    """
+
+    # Implementation here
+    def __init__(self, message="Resources not found"):
+        self.message = message
+        self.status_code = 404
+        self.error_code = "RESOURCE_NOT_FOUND"
+        super().__init__(
+            message=self.message,
+            status_code=self.status_code,
+            error_code=self.error_code,
+        )
+
+
+class ResourceDuplicationError(GeneralException):
+    """
+    Exception raised for duplicate resource requests.
+
+    This exception is used to indicate that a request has been made for a resource
+    that already exists, and such duplication is not allowed.
+
+    Attributes:
+        message (str): Explanation of the error. Defaults to "Duplicate request".
+        status_code (int): HTTP status code for the error. Defaults to 403.
+        error_code (str): Specific error code for duplicate requests.
+        Defaults to "DUPLICATE_REQUEST".
+    """
+
+    def __init__(self, message="Duplicate request"):
+        self.message = message
+        self.status_code = 403
+        self.error_code = "DUPLICATE_REQUEST"
+        super().__init__(
+            message=self.message,
+            status_code=self.status_code,
+            error_code=self.error_code,
+        )
+
+
+class InvalidOperationError(GeneralException):
+    """
+    Exception raised for invalid operations.
+
+    This exception is used to indicate that a particular operation is not supported.
+
+    Attributes:
+        message (str): Explanation of the error. Defaults to "Operation Not Supported".
+        status_code (int): HTTP status code for the error. Defaults to 403.
+        error_code (str): Specific error code for the exception.
+        Defaults to "InvalidOperationError".
+    """
+
+    def __init__(self, message="Operation Not Supported"):
+        self.message = message
+        self.status_code = 403
+        self.error_code = "InvalidOperationError"
+        super().__init__(
+            message=self.message,
+            status_code=self.status_code,
+            error_code=self.error_code,
+        )

tenxgraph_api/src/app/core/exceptions/user_exception.py

@@ -0,0 +1,58 @@
+from .general_exception import GeneralException
+
+
+class UserAccountError(GeneralException):
+    """
+    Exception raised for errors related to user account status.
+
+    This exception is raised when a user account is disabled and
+    the user needs to contact support.
+
+    Attributes:
+        message (str): Explanation of the error. Defaults to "User account is disabled,
+        please contact support".
+        error_code (str): Specific error code for this type of error.
+        Defaults to "USER_ACCOUNT_DISABLE".
+        status_code (int): HTTP status code for the error. Defaults to 403; a missing,
+        invalid or expired credential uses 401.
+    """
+
+    def __init__(
+        self,
+        message="User account is disabled, please contact support",
+        error_code="USER_ACCOUNT_DISABLE",
+        status_code=403,
+    ):
+        self.message = message
+        self.status_code = status_code
+        self.error_code = error_code
+        super().__init__(
+            message=self.message,
+            status_code=self.status_code,
+            error_code=self.error_code,
+        )
+
+
+class UserPermissionError(GeneralException):
+    """
+    Exception raised for user permission errors.
+
+    Attributes:
+        message (str): Explanation of the error.
+        status_code (int): HTTP status code for the error.
+        error_code (str): Specific error code for the permission error.
+
+    Args:
+        message (str, optional): Custom error message.
+        Defaults to "user don't have sufficient permission".
+    """
+
+    def __init__(self, message="user don't have sufficient permission"):
+        self.message = message
+        self.status_code = 403
+        self.error_code = "PERMISSION_ERROR"
+        super().__init__(
+            message=self.message,
+            status_code=self.status_code,
+            error_code=self.error_code,
+        )

tenxgraph_api/src/app/core/middleware/__init__.py

@@ -0,0 +1,25 @@
+"""Middleware modules for tenxgraph_api."""
+
+from .rate_limit import (
+    BaseRateLimitBackend,
+    MemoryRateLimitBackend,
+    RateLimitDecision,
+    RateLimitMiddleware,
+    RedisRateLimitBackend,
+    build_backend,
+)
+from .request_limits import RequestSizeLimitMiddleware
+from .security_headers import SecurityHeadersMiddleware, create_security_headers_middleware
+
+
+__all__ = [
+    "BaseRateLimitBackend",
+    "RateLimitMiddleware",
+    "RateLimitDecision",
+    "MemoryRateLimitBackend",
+    "RedisRateLimitBackend",
+    "build_backend",
+    "RequestSizeLimitMiddleware",
+    "SecurityHeadersMiddleware",
+    "create_security_headers_middleware",
+]

tenxgraph_api/src/app/core/middleware/rate_limit/__init__.py

@@ -0,0 +1,15 @@
+from .base import BaseRateLimitBackend, RateLimitDecision
+from .factory import build_backend
+from .memory import MemoryRateLimitBackend
+from .middleware import RateLimitMiddleware
+from .redis import RedisRateLimitBackend
+
+
+__all__ = [
+    "BaseRateLimitBackend",
+    "MemoryRateLimitBackend",
+    "RateLimitDecision",
+    "RateLimitMiddleware",
+    "RedisRateLimitBackend",
+    "build_backend",
+]

tenxgraph_api/src/app/core/middleware/rate_limit/base.py

@@ -0,0 +1,27 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class RateLimitDecision:
+    """Result of a single rate-limit check."""
+
+    allowed: bool
+    remaining: int
+    reset_after: int
+
+
+class BaseRateLimitBackend(ABC):
+    """Abstract base class for rate-limit backends.
+
+    Users can implement this class and bind an instance into InjectQ when they
+    need a backend other than the built-in memory or Redis implementations.
+    """
+
+    @abstractmethod
+    async def check(self, key: str, *, limit: int, window: int) -> RateLimitDecision:
+        """Atomically check and record a request for *key*."""
+
+    @abstractmethod
+    async def close(self) -> None:
+        """Release resources held by the backend, if any."""

tenxgraph_api/src/app/core/middleware/rate_limit/factory.py

@@ -0,0 +1,98 @@
+import logging
+from typing import TYPE_CHECKING, Any
+
+from injectq import InjectQ
+
+from tenxgraph_api.src.app.core.config.graph_config import RateLimitConfig
+
+from .base import BaseRateLimitBackend
+from .memory import MemoryRateLimitBackend
+from .redis import RedisRateLimitBackend
+
+
+if TYPE_CHECKING:
+    from redis.asyncio import Redis
+
+
+logger = logging.getLogger("tenxgraph_api.rate_limit")
+
+
+def build_backend(
+    config: RateLimitConfig,
+    container: InjectQ | None = None,
+) -> BaseRateLimitBackend:
+    """Build or resolve the configured rate-limit backend.
+
+    Custom backends are provided by binding a ``BaseRateLimitBackend`` instance
+    into InjectQ, matching the style used by auth/authorization.
+    """
+    container = container or InjectQ.get_instance()
+
+    injected_backend = container.try_get(BaseRateLimitBackend)
+    if config.backend == "custom":
+        if not injected_backend:
+            raise ValueError(
+                "rate_limit.backend='custom' requires a BaseRateLimitBackend "
+                "instance bound in InjectQ"
+            )
+        return injected_backend
+
+    if config.backend == "redis":
+        return _build_redis_backend(config, container)
+
+    logger.info("Rate-limit backend: memory (in-process, not shared across workers)")
+    return MemoryRateLimitBackend()
+
+
+def _build_redis_backend(
+    config: RateLimitConfig,
+    container: InjectQ,
+) -> RedisRateLimitBackend:
+    redis = _get_redis_from_container(container)
+    if redis is not None:
+        logger.info(
+            "Rate-limit backend: Redis from InjectQ (prefix=%s, fail_open=%s)",
+            config.redis_prefix,
+            config.fail_open,
+        )
+        return RedisRateLimitBackend(
+            redis=redis,
+            prefix=config.redis_prefix,
+            fail_open=config.fail_open,
+            close_redis=False,
+        )
+
+    if not config.redis_url:
+        raise ValueError("rate_limit.redis.url is required when no Redis client is bound")
+
+    backend = RedisRateLimitBackend.from_url(
+        redis_url=config.redis_url,
+        prefix=config.redis_prefix,
+        fail_open=config.fail_open,
+    )
+    _bind_redis(container, backend._redis)
+    logger.info(
+        "Rate-limit backend: created Redis and bound it in InjectQ (prefix=%s, fail_open=%s)",
+        config.redis_prefix,
+        config.fail_open,
+    )
+    return backend
+
+
+def _get_redis_from_container(container: InjectQ) -> Any | None:
+    redis = container.try_get("redis")
+    if redis is not None:
+        return redis
+
+    redis = container.try_get("redis_client")
+    if redis is not None:
+        return redis
+
+    return container.try_get("Redis")
+
+
+def _bind_redis(container: InjectQ, redis: "Redis") -> None:
+    if Redis is not None:
+        container.bind_instance(Redis, redis)
+    container.bind_instance("redis", redis)
+    container.bind_instance("redis_client", redis)