iflow-mcp_developermode-korea_reversecore-mcp 1.0.0__py3-none-any.whl

reversecore_mcp/core/container.py

@@ -0,0 +1,288 @@
+"""
+Dependency Injection Container for Reversecore_MCP
+
+This module provides a lightweight dependency injection container that:
+- Centralizes service registration and lifecycle management
+- Enables easy testing through service replacement
+- Supports singleton and factory patterns
+- Allows async initialization of services
+
+Usage:
+    from reversecore_mcp.core.container import container, ServiceContainer
+
+    # Register services
+    container.register_singleton('r2_pool', R2ConnectionPool)
+    container.register_factory('config', get_config)
+
+    # Get services
+    pool = container.get('r2_pool')
+
+    # Override for testing
+    container.override('r2_pool', mock_pool)
+
+    # Reset overrides
+    container.reset_overrides()
+"""
+
+import asyncio
+import threading
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from reversecore_mcp.core.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+T = TypeVar("T")
+
+
+class ServiceContainer:
+    """
+    A lightweight dependency injection container.
+
+    Features:
+    - Singleton management (create once, reuse)
+    - Factory support (create new instance each time)
+    - Service overrides for testing
+    - Async initialization support
+    - Thread-safe operations
+    """
+
+    def __init__(self) -> None:
+        self._singletons: dict[str, Any] = {}
+        self._singleton_factories: dict[str, Callable[[], Any]] = {}
+        self._factories: dict[str, Callable[[], Any]] = {}
+        self._overrides: dict[str, Any] = {}
+        self._lock = threading.RLock()
+        self._initialized = False
+
+    def register_singleton(
+        self,
+        name: str,
+        factory: Callable[[], T] | type[T],
+        instance: T | None = None,
+    ) -> None:
+        """
+        Register a singleton service.
+
+        Args:
+            name: Service name for lookup
+            factory: Callable that creates the service instance
+            instance: Optional pre-created instance (skips factory)
+        """
+        with self._lock:
+            if instance is not None:
+                self._singletons[name] = instance
+            else:
+                self._singleton_factories[name] = factory
+
+    def register_factory(self, name: str, factory: Callable[[], T]) -> None:
+        """
+        Register a factory service (new instance each call).
+
+        Args:
+            name: Service name for lookup
+            factory: Callable that creates a new service instance
+        """
+        with self._lock:
+            self._factories[name] = factory
+
+    def get(self, name: str) -> Any:
+        """
+        Get a service by name.
+
+        Args:
+            name: Service name
+
+        Returns:
+            Service instance
+
+        Raises:
+            KeyError: If service not registered
+        """
+        with self._lock:
+            # Check overrides first (for testing)
+            if name in self._overrides:
+                return self._overrides[name]
+
+            # Check existing singletons
+            if name in self._singletons:
+                return self._singletons[name]
+
+            # Check singleton factories (lazy initialization)
+            if name in self._singleton_factories:
+                instance = self._singleton_factories[name]()
+                self._singletons[name] = instance
+                
+                # If container is already initialized, start the service immediately
+                if self._initialized and hasattr(instance, "start") and asyncio.iscoroutinefunction(instance.start):
+                    # We can't await here as get is sync, but we can schedule it
+                    # Warning: This creates a potential race condition for immediate use
+                    # ideally initialize_async should have caught this.
+                    # For safety, we log this event.
+                    logger.warning(f"Service '{name}' instantiated after initialization. Scheduling start.")
+                    asyncio.create_task(self._safe_start(name, instance))
+                    
+                return instance
+
+            # Check factories
+            if name in self._factories:
+                return self._factories[name]()
+
+            raise KeyError(f"Service '{name}' not registered")
+
+    def override(self, name: str, instance: Any) -> None:
+        """
+        Override a service for testing.
+
+        Args:
+            name: Service name to override
+            instance: Mock or test instance to use
+        """
+        with self._lock:
+            self._overrides[name] = instance
+            logger.debug(f"Service '{name}' overridden for testing")
+
+    def reset_overrides(self) -> None:
+        """Remove all test overrides."""
+        with self._lock:
+            self._overrides.clear()
+            logger.debug("All service overrides cleared")
+
+    def reset_singleton(self, name: str) -> None:
+        """
+        Reset a singleton (force re-creation on next get).
+
+        Args:
+            name: Service name to reset
+        """
+        with self._lock:
+            if name in self._singletons:
+                del self._singletons[name]
+                logger.debug(f"Singleton '{name}' reset")
+
+    def reset_all(self) -> None:
+        """Reset all singletons and overrides."""
+        with self._lock:
+            self._singletons.clear()
+            self._overrides.clear()
+            logger.debug("All services reset")
+
+    def has(self, name: str) -> bool:
+        """Check if a service is registered."""
+        with self._lock:
+            return (
+                name in self._overrides
+                or name in self._singletons
+                or name in self._singleton_factories
+                or name in self._factories
+            )
+
+    async def _safe_start(self, name: str, instance: Any) -> None:
+        """Helper to start a service safely in background."""
+        try:
+            await instance.start()
+            logger.info(f"Async service '{name}' started (lazy)")
+        except Exception as e:
+            logger.error(f"Failed to start '{name}': {e}")
+
+    async def initialize_async(self) -> None:
+        """
+        Initialize all async-capable singletons.
+
+        Call this during application startup.
+        """
+        if self._initialized:
+            return
+
+        with self._lock:
+            self._initialized = True
+
+            # Eagerly instantiate all singleton factories to ensure they are started
+            # This prevents race conditions where a service is accessed later but missed the start phase
+            for name in list(self._singleton_factories.keys()):
+                self.get(name)
+
+            # Initialize singletons that have async start methods
+            for name, instance in self._singletons.items():
+                if hasattr(instance, "start") and asyncio.iscoroutinefunction(instance.start):
+                    try:
+                        await instance.start()
+                        logger.info(f"Async service '{name}' started")
+                    except Exception as e:
+                        logger.error(f"Failed to start '{name}': {e}")
+
+    async def shutdown_async(self) -> None:
+        """
+        Shutdown all async-capable singletons.
+
+        Call this during application shutdown.
+        """
+        with self._lock:
+            self._initialized = False
+
+            # Stop singletons that have async stop methods
+            for name, instance in self._singletons.items():
+                if hasattr(instance, "stop") and asyncio.iscoroutinefunction(instance.stop):
+                    try:
+                        await instance.stop()
+                        logger.info(f"Async service '{name}' stopped")
+                    except Exception as e:
+                        logger.error(f"Failed to stop '{name}': {e}")
+
+                # Also try close_all for pools
+                if hasattr(instance, "close_all"):
+                    try:
+                        instance.close_all()
+                        logger.info(f"Service '{name}' closed")
+                    except Exception as e:
+                        logger.error(f"Failed to close '{name}': {e}")
+
+
+# Global container instance
+container = ServiceContainer()
+
+
+def _initialize_default_services() -> None:
+    """Register default services in the container."""
+    from reversecore_mcp.core.config import get_config
+    from reversecore_mcp.core.ghidra import GhidraService
+    from reversecore_mcp.core.r2_pool import R2ConnectionPool
+    from reversecore_mcp.core.resource_manager import ResourceManager
+
+    # Register config as factory (always fresh)
+    container.register_factory("config", get_config)
+
+    # Register R2 pool as singleton
+    container.register_singleton("r2_pool", R2ConnectionPool)
+
+    # Register resource manager as singleton
+    container.register_singleton("resource_manager", ResourceManager)
+
+    # Register Ghidra service as singleton
+    container.register_singleton("ghidra", GhidraService)
+
+
+# Initialize default services on module load
+_initialize_default_services()
+
+
+# Convenience functions for common services
+def get_r2_pool():
+    """Get the R2 connection pool instance."""
+    return container.get("r2_pool")
+
+
+def get_resource_manager():
+    """Get the resource manager instance."""
+    return container.get("resource_manager")
+
+
+def get_ghidra_service():
+    """Get the Ghidra service instance."""
+    return container.get("ghidra")
+
+
+def get_config_from_container():
+    """Get configuration from container."""
+    return container.get("config")

reversecore_mcp/core/decorators.py

@@ -0,0 +1,152 @@
+"""
+Decorators for common tool execution patterns.
+
+This module provides decorators to reduce code duplication in tool functions
+by centralizing logging, error handling, and execution time measurement.
+"""
+
+import functools
+import os
+import time
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from reversecore_mcp.core.logging_config import get_logger
+from reversecore_mcp.core.result import ToolResult
+
+logger = get_logger(__name__)
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def log_execution(tool_name: str | None = None) -> Callable[[F], F]:
+    """
+    Decorator to add logging and error handling to tool functions.
+
+    This decorator:
+    - Logs function start and completion
+    - Measures execution time
+    - Handles common exceptions and formats errors
+    - Extracts file_name from function arguments if present
+
+    Args:
+        tool_name: Name of the tool (defaults to function name)
+
+    Returns:
+        Decorated function
+    """
+
+    def decorator(func: F) -> F:
+        # Use provided tool_name or function name
+        actual_tool_name = tool_name or func.__name__
+
+        # Check if function is async
+        import inspect
+
+        is_async = inspect.iscoroutinefunction(func)
+
+        if is_async:
+
+            @functools.wraps(func)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> ToolResult:
+                start_time = time.time()
+                file_name = None
+
+                # OPTIMIZATION: Extract filename without creating Path object
+                # Using os.path.basename() for cross-platform path handling
+                for arg_name in ["file_path", "path", "file"]:
+                    if arg_name in kwargs:
+                        path_str = kwargs[arg_name]
+                        if path_str:  # Handle empty strings
+                            file_name = os.path.basename(path_str)
+                        break
+                if not file_name and args:
+                    first_arg = args[0]
+                    if isinstance(first_arg, str) and first_arg:
+                        file_name = os.path.basename(first_arg)
+
+                # Log start
+                log_extra = {"tool_name": actual_tool_name}
+                if file_name:
+                    log_extra["file_name"] = file_name
+                logger.info(f"Starting {actual_tool_name}", extra=log_extra)
+
+                try:
+                    result = await func(*args, **kwargs)
+                    execution_time = int((time.time() - start_time) * 1000)
+
+                    # Add execution time to metadata
+                    if hasattr(result, "metadata"):
+                        if result.metadata is None:
+                            result.metadata = {}
+                        result.metadata["execution_time_ms"] = execution_time
+
+                    log_extra["execution_time_ms"] = execution_time
+                    logger.info(f"{actual_tool_name} completed successfully", extra=log_extra)
+                    return result
+                except Exception as exc:
+                    execution_time = int((time.time() - start_time) * 1000)
+                    log_extra["execution_time_ms"] = execution_time
+                    logger.error(
+                        f"{actual_tool_name} failed",
+                        extra=log_extra,
+                        exc_info=True,
+                    )
+                    # Critical: Re-raise exception so @handle_tool_errors can catch it
+                    # returning failure() here would hide the error from outer decorators
+                    raise
+
+            return async_wrapper  # type: ignore
+
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> ToolResult:
+            start_time = time.time()
+            file_name = None
+
+            # OPTIMIZATION: Extract filename without creating Path object
+            # Using os.path.basename() for cross-platform path handling
+            for arg_name in ["file_path", "path", "file"]:
+                if arg_name in kwargs:
+                    path_str = kwargs[arg_name]
+                    if path_str:  # Handle empty strings
+                        file_name = os.path.basename(path_str)
+                    break
+            if not file_name and args:
+                # Check first positional argument
+                first_arg = args[0]
+                if isinstance(first_arg, str) and first_arg:
+                    file_name = os.path.basename(first_arg)
+
+            # Log start
+            log_extra = {"tool_name": actual_tool_name}
+            if file_name:
+                log_extra["file_name"] = file_name
+            logger.info(f"Starting {actual_tool_name}", extra=log_extra)
+
+            try:
+                result = func(*args, **kwargs)
+                execution_time = int((time.time() - start_time) * 1000)
+
+                # Add execution time to metadata
+                if hasattr(result, "metadata"):
+                    if result.metadata is None:
+                        result.metadata = {}
+                    result.metadata["execution_time_ms"] = execution_time
+
+                log_extra["execution_time_ms"] = execution_time
+                logger.info(f"{actual_tool_name} completed successfully", extra=log_extra)
+                return result
+            except Exception as exc:
+                execution_time = int((time.time() - start_time) * 1000)
+                log_extra["execution_time_ms"] = execution_time
+                logger.error(
+                    f"{actual_tool_name} failed",
+                    extra=log_extra,
+                    exc_info=True,
+                )
+                # Critical: Re-raise exception so @handle_tool_errors can catch it
+                raise
+
+        return wrapper  # type: ignore
+
+    return decorator

reversecore_mcp/core/error_formatting.py

@@ -0,0 +1,93 @@
+"""
+Error formatting utilities for structured error responses.
+"""
+
+from typing import Any
+
+from reversecore_mcp.core.config import get_config
+from reversecore_mcp.core.exceptions import ReversecoreError
+
+
+def format_error(
+    error: Exception, tool_name: str | None = None, hint: str | None = None
+) -> str | dict[str, Any]:
+    """
+    Format an error as string or structured JSON based on settings.
+
+    Args:
+        error: The exception to format
+        tool_name: Name of the tool that raised the error
+        hint: Optional hint message for resolving the error
+
+    Returns:
+        Error message as string (default) or structured dict (if structured_errors enabled)
+    """
+    # Check if structured errors are enabled
+    structured = get_config().structured_errors
+
+    if isinstance(error, ReversecoreError):
+        error_code = error.error_code
+        error_type = error.error_type
+        message = error.message
+        details = {}
+
+        # Add exception-specific details
+        if hasattr(error, "tool_name"):
+            details["tool_name"] = error.tool_name
+        if hasattr(error, "timeout_seconds"):
+            details["timeout_seconds"] = error.timeout_seconds
+        if hasattr(error, "max_size"):
+            details["max_size"] = error.max_size
+        if hasattr(error, "actual_size"):
+            details["actual_size"] = error.actual_size
+        if hasattr(error, "details"):
+            details.update(error.details)
+    else:
+        # Generic error
+        error_code = "RCMCP-E000"
+        error_type = "SYSTEM_ERROR"
+        message = str(error)
+        details = {"exception_type": type(error).__name__}
+
+    if tool_name:
+        details["tool_name"] = tool_name
+
+    if structured:
+        # Return structured JSON format
+        result: dict[str, Any] = {
+            "error_code": error_code,
+            "error_type": error_type,
+            "message": message,
+            "details": details,
+        }
+        if hint:
+            result["hint"] = hint
+        return result
+    else:
+        # Return simple string format (backward compatible)
+        error_str = f"Error: {message}"
+        if hint:
+            error_str += f" Hint: {hint}"
+        return error_str
+
+
+def get_validation_hint(error: ValueError) -> str:
+    """
+    Generate a helpful hint message for validation errors.
+
+    Args:
+        error: The ValueError exception
+
+    Returns:
+        Hint message string
+    """
+    error_msg = str(error).lower()
+
+    if "outside" in error_msg or "workspace" in error_msg:
+        return "Ensure the file is in the allowed workspace directory. Set REVERSECORE_WORKSPACE environment variable to change the workspace path."
+    elif "does not point to a file" in error_msg:
+        return "The specified path points to a directory, not a file. Please provide a file path."
+    elif "invalid file path" in error_msg:
+        return "The file path is invalid or the file does not exist. Please check the path and try again."
+    else:
+        return "Please check the input and try again."

reversecore_mcp/core/error_handling.py

@@ -0,0 +1,142 @@
+"""Shared error handling utilities for tool wrappers."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from functools import wraps
+from typing import TypeVar
+
+from reversecore_mcp.core.exceptions import (
+    ExecutionTimeoutError,
+    OutputLimitExceededError,
+    ToolNotFoundError,
+    ValidationError,
+)
+from reversecore_mcp.core.logging_config import get_logger
+from reversecore_mcp.core.result import ToolResult, failure
+
+logger = get_logger(__name__)
+
+F = TypeVar("F", bound=Callable[..., ToolResult])
+
+
+def _handle_exception(exc: Exception, tool_name: str) -> ToolResult:
+    """Convert common exceptions into ToolResult failures.
+
+    This is the centralized exception handler that eliminates code duplication
+    between sync and async wrappers.
+
+    Args:
+        exc: The exception to handle
+        tool_name: Name of the tool that raised the exception
+
+    Returns:
+        ToolResult with appropriate error code and message
+    """
+    if isinstance(exc, ToolNotFoundError):
+        hint = f"Install with: apt-get install {exc.tool_name}"
+        return failure("TOOL_NOT_FOUND", str(exc), hint=hint)
+
+    if isinstance(exc, ExecutionTimeoutError):
+        return failure(
+            "TIMEOUT",
+            f"Command timed out after {exc.timeout_seconds} seconds",
+            timeout_seconds=exc.timeout_seconds,
+        )
+
+    if isinstance(exc, OutputLimitExceededError):
+        return failure(
+            "OUTPUT_LIMIT",
+            str(exc),
+            hint="Reduce output size or increase the limit",
+            details={
+                "max_size": exc.max_size,
+                "actual_size": exc.actual_size,
+            },
+        )
+
+    if isinstance(exc, ValidationError):
+        return failure(
+            "VALIDATION_ERROR",
+            str(exc),
+            hint="Ensure the file is in the workspace directory",
+            details=exc.details,
+        )
+
+    # Generic exception handler
+    logger.exception("Unexpected error in tool '%s'", tool_name)
+    return failure(
+        "INTERNAL_ERROR",
+        f"{tool_name} failed: {exc}",
+        exception_type=exc.__class__.__name__,
+    )
+
+
+def handle_tool_errors(func=None, *, max_retries: int = 0, backoff: float = 0.5) -> F:
+    """
+    Wrap a tool function to handle errors and optionally retry on failure.
+    
+    Supports usage as both:
+    @handle_tool_errors
+    def my_tool(): ...
+    
+    and:
+    @handle_tool_errors(max_retries=3)
+    def my_tool(): ...
+    """
+    import asyncio
+    import inspect
+    import time
+
+    def decorator(f: F) -> F:
+        is_async = inspect.iscoroutinefunction(f)
+        tool_name = f.__name__
+
+        if is_async:
+            @wraps(f)
+            async def async_wrapper(*args, **kwargs) -> ToolResult:
+                last_exception = None
+                for attempt in range(max_retries + 1):
+                    try:
+                        return await f(*args, **kwargs)
+                    except Exception as exc:
+                        last_exception = exc
+                        if attempt < max_retries:
+                            wait_time = backoff * (2 ** attempt)
+                            logger.warning(
+                                f"Tool '{tool_name}' failed (attempt {attempt+1}/{max_retries+1}). "
+                                f"Retrying in {wait_time:.1f}s. Error: {exc}"
+                            )
+                            await asyncio.sleep(wait_time)
+                        else:
+                            # Final attempt failed
+                            msg = f"Failed after {max_retries+1} attempts" if max_retries > 0 else None
+                            return _handle_exception(exc, tool_name)
+                # Should not reach here
+                return _handle_exception(last_exception, tool_name)
+            return async_wrapper  # type: ignore
+
+        else:
+            @wraps(f)
+            def sync_wrapper(*args, **kwargs) -> ToolResult:
+                last_exception = None
+                for attempt in range(max_retries + 1):
+                    try:
+                        return f(*args, **kwargs)
+                    except Exception as exc:
+                        last_exception = exc
+                        if attempt < max_retries:
+                            wait_time = backoff * (2 ** attempt)
+                            logger.warning(
+                                f"Tool '{tool_name}' failed (attempt {attempt+1}/{max_retries+1}). "
+                                f"Retrying in {wait_time:.1f}s. Error: {exc}"
+                            )
+                            time.sleep(wait_time)
+                        else:
+                            return _handle_exception(exc, tool_name)
+                return _handle_exception(last_exception, tool_name)
+            return sync_wrapper  # type: ignore
+
+    if func is None:
+        return decorator
+    return decorator(func)