grasp-sdk 0.1.0__py3-none-any.whl

grasp_sdk/utils/auth.py

@@ -0,0 +1,227 @@
+"""Authentication utilities for Grasp SDK Python implementation.
+
+This module provides authentication and key verification functionality
+for the Grasp platform.
+"""
+
+import asyncio
+from typing import Dict, Any, Optional, TYPE_CHECKING
+from urllib.parse import quote
+
+try:
+    import aiohttp
+except ImportError:
+    aiohttp = None
+
+if TYPE_CHECKING:
+    from aiohttp import ClientSession
+
+from ..models import ISandboxConfig
+
+
+class AuthError(Exception):
+    """Exception raised for authentication errors."""
+    pass
+
+
+class KeyVerificationError(AuthError):
+    """Exception raised when key verification fails."""
+    pass
+
+
+async def login(token: str) -> Dict[str, Any]:
+    """Authenticates with the Grasp platform using a token.
+    
+    Args:
+        token: Authentication token to verify
+        
+    Returns:
+        Dict[str, Any]: Response from the authentication API
+        
+    Raises:
+        AuthError: If authentication fails
+        ImportError: If aiohttp is not installed
+    """
+    if aiohttp is None:
+        raise ImportError("aiohttp is required for authentication. Install with: pip install aiohttp")
+    
+    url = f"https://d1toyru2btfpfr.cloudfront.net/api/key/verify?token={quote(token)}"
+    
+    try:
+        if aiohttp is None:
+            raise ImportError("aiohttp is required for authentication. Install with: pip install aiohttp")
+        
+        async with aiohttp.ClientSession() as session:
+            async with session.get(url) as response:
+                if response.status == 200:
+                    return await response.json()
+                elif response.status == 401:
+                    raise AuthError("Invalid authentication token")
+                elif response.status == 403:
+                    raise AuthError("Access forbidden - token may be expired")
+                else:
+                    response.raise_for_status()
+                    return await response.json()
+    except Exception as e:
+        if aiohttp is not None and isinstance(e, aiohttp.ClientError):
+            raise AuthError(f"Network error during authentication: {str(e)}")
+        else:
+            raise AuthError(f"Unexpected error during authentication: {str(e)}")
+
+
+async def verify(config: ISandboxConfig) -> Dict[str, Any]:
+    """Verifies the sandbox configuration and authenticates.
+    
+    Args:
+        config: Sandbox configuration containing the API key
+        
+    Returns:
+        Dict[str, Any]: Authentication response
+        
+    Raises:
+        KeyVerificationError: If the key is missing or invalid
+        AuthError: If authentication fails
+    """
+    if not config['key']:
+        raise KeyVerificationError('Grasp key is required')
+    
+    try:
+        return await login(config['key'])
+    except AuthError:
+        raise
+    except Exception as e:
+        raise KeyVerificationError(f"Key verification failed: {str(e)}")
+
+
+def verify_sync(config: ISandboxConfig) -> Dict[str, Any]:
+    """Synchronous wrapper for the verify function.
+    
+    Args:
+        config: Sandbox configuration containing the API key
+        
+    Returns:
+        Dict[str, Any]: Authentication response
+        
+    Raises:
+        KeyVerificationError: If the key is missing or invalid
+        AuthError: If authentication fails
+    """
+    try:
+        loop = asyncio.get_event_loop()
+    except RuntimeError:
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+    
+    return loop.run_until_complete(verify(config))
+
+
+async def validate_token(token: str) -> bool:
+    """Validates a token without raising exceptions.
+    
+    Args:
+        token: Token to validate
+        
+    Returns:
+        bool: True if token is valid, False otherwise
+    """
+    try:
+        await login(token)
+        return True
+    except (AuthError, Exception):
+        return False
+
+
+def validate_token_sync(token: str) -> bool:
+    """Synchronous wrapper for token validation.
+    
+    Args:
+        token: Token to validate
+        
+    Returns:
+        bool: True if token is valid, False otherwise
+    """
+    try:
+        loop = asyncio.get_event_loop()
+    except RuntimeError:
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+    
+    return loop.run_until_complete(validate_token(token))
+
+
+class AuthManager:
+    """Authentication manager for handling multiple tokens and sessions."""
+    
+    def __init__(self):
+        """Initialize the authentication manager."""
+        if aiohttp is None:
+            raise ImportError("aiohttp is required for AuthManager. Install with: pip install aiohttp")
+        self._verified_tokens: Dict[str, Dict[str, Any]] = {}
+        self._session: Optional['ClientSession'] = None
+    
+    async def __aenter__(self):
+        """Async context manager entry."""
+        if aiohttp is None:
+            raise ImportError("aiohttp is required for AuthManager. Install with: pip install aiohttp")
+        self._session = aiohttp.ClientSession()
+        return self
+    
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit."""
+        if self._session:
+            await self._session.close()
+    
+    async def verify_token(self, token: str, force_refresh: bool = False) -> Dict[str, Any]:
+        """Verify a token with caching support.
+        
+        Args:
+            token: Token to verify
+            force_refresh: Whether to force a new verification
+            
+        Returns:
+            Dict[str, Any]: Verification response
+            
+        Raises:
+            AuthError: If verification fails
+        """
+        if not force_refresh and token in self._verified_tokens:
+            return self._verified_tokens[token]
+        
+        url = f"https://d1toyru2btfpfr.cloudfront.net/api/key/verify?token={quote(token)}"
+        
+        if not self._session:
+            raise AuthError("AuthManager not properly initialized. Use as async context manager.")
+        
+        try:
+            async with self._session.get(url) as response:
+                if response.status == 200:
+                    result = await response.json()
+                    self._verified_tokens[token] = result
+                    return result
+                elif response.status == 401:
+                    raise AuthError("Invalid authentication token")
+                elif response.status == 403:
+                    raise AuthError("Access forbidden - token may be expired")
+                else:
+                    response.raise_for_status()
+                    return await response.json()
+        except Exception as e:
+            if aiohttp is not None and isinstance(e, aiohttp.ClientError):
+                raise AuthError(f"Network error during authentication: {str(e)}")
+            else:
+                raise AuthError(f"Unexpected error during authentication: {str(e)}")
+    
+    def clear_cache(self) -> None:
+        """Clear the token verification cache."""
+        self._verified_tokens.clear()
+    
+    def is_token_cached(self, token: str) -> bool:
+        """Check if a token is cached.
+        
+        Args:
+            token: Token to check
+            
+        Returns:
+            bool: True if token is cached
+        """
+        return token in self._verified_tokens

grasp_sdk/utils/config.py

@@ -0,0 +1,150 @@
+"""Configuration management for Grasp SDK Python implementation.
+
+This module provides configuration loading from environment variables
+and default configuration constants.
+"""
+
+import os
+from typing import Dict, Any, Optional
+from dotenv import load_dotenv
+from ..models import ISandboxConfig, IBrowserConfig
+
+# Load environment variables from .env.grasp file
+load_dotenv('.env.grasp')
+
+
+def get_config() -> Dict[str, Any]:
+    """Gets application configuration from environment variables.
+    
+    Returns:
+        Dict[str, Any]: Application configuration object containing
+                       sandbox and logger configurations.
+    """
+    return {
+        'sandbox': {
+            'key': os.getenv('GRASP_KEY', ''),
+            'templateId': 'playwright-pnpm-template',
+            'timeout': int(os.getenv('GRASP_SERVICE_TIMEOUT', '900000')),
+            'debug': os.getenv('GRASP_DEBUG', 'false').lower() == 'true',
+        },
+        'logger': {
+            'level': os.getenv('GRASP_LOG_LEVEL', 'info'),
+            'console': True,
+            'file': os.getenv('GRASP_LOG_FILE'),
+        },
+    }
+
+
+def get_sandbox_config() -> ISandboxConfig:
+    """Gets sandbox-specific configuration.
+    
+    Returns:
+        ISandboxConfig: Sandbox configuration object.
+    """
+    config = get_config()
+    sandbox_config = ISandboxConfig(
+        key=config['sandbox']['key'],
+        templateId=config['sandbox']['templateId'],
+        timeout=config['sandbox']['timeout'],
+        debug=config['sandbox'].get('debug', False),
+    )
+    
+    # Only add workspace if it exists
+    workspace = os.getenv('GRASP_WORKSPACE')
+    if workspace:
+        sandbox_config['workspace'] = workspace
+    
+    return sandbox_config
+
+
+def get_browser_config() -> IBrowserConfig:
+    """Gets browser-specific configuration.
+    
+    Returns:
+        IBrowserConfig: Browser configuration object.
+    """
+    return IBrowserConfig(
+        cdpPort=int(os.getenv('GRASP_CDP_PORT', '9222')),
+        args=[
+            '--no-sandbox',
+            '--disable-setuid-sandbox',
+            '--disable-dev-shm-usage',
+            '--disable-gpu',
+            '--remote-debugging-port=9222',
+            '--remote-debugging-address=0.0.0.0',
+        ],
+        headless=os.getenv('GRASP_HEADLESS', 'true').lower() == 'true',
+        launchTimeout=int(os.getenv('GRASP_LAUNCH_TIMEOUT', '30000')),
+        envs={
+            'PLAYWRIGHT_BROWSERS_PATH': '0',
+            'DISPLAY': ':99',
+        },
+    )
+
+
+# Default configuration constants
+DEFAULT_CONFIG = {
+    'PLAYWRIGHT_BROWSERS_PATH': '0',
+    'WORKING_DIRECTORY': '/home/user',
+    'SCREENSHOT_PATH': '/home/user',
+    'DEFAULT_VIEWPORT': {
+        'width': 1280,
+        'height': 720,
+    },
+}
+
+
+# Environment variable names for easy reference
+ENV_VARS = {
+    'GRASP_KEY': 'GRASP_KEY',
+    'GRASP_WORKSPACE': 'GRASP_WORKSPACE',
+    'GRASP_SERVICE_TIMEOUT': 'GRASP_SERVICE_TIMEOUT',
+    'GRASP_DEBUG': 'GRASP_DEBUG',
+    'GRASP_LOG_LEVEL': 'GRASP_LOG_LEVEL',
+    'GRASP_LOG_FILE': 'GRASP_LOG_FILE',
+    'GRASP_CDP_PORT': 'GRASP_CDP_PORT',
+    'GRASP_HEADLESS': 'GRASP_HEADLESS',
+    'GRASP_LAUNCH_TIMEOUT': 'GRASP_LAUNCH_TIMEOUT',
+}
+
+
+def validate_config() -> bool:
+    """Validates that required configuration is present.
+    
+    Returns:
+        bool: True if configuration is valid, False otherwise.
+    """
+    config = get_config()
+    
+    # Check required fields
+    if not config['sandbox']['key']:
+        return False
+        
+    # Validate timeout values
+    if config['sandbox']['timeout'] <= 0:
+        return False
+        
+    return True
+
+
+def get_env_var(key: str, default: Optional[str] = None) -> Optional[str]:
+    """Gets an environment variable with optional default.
+    
+    Args:
+        key: Environment variable name
+        default: Default value if not found
+        
+    Returns:
+        str or None: Environment variable value or default
+    """
+    return os.getenv(key, default)
+
+
+def set_env_var(key: str, value: str) -> None:
+    """Sets an environment variable.
+    
+    Args:
+        key: Environment variable name
+        value: Environment variable value
+    """
+    os.environ[key] = value

grasp_sdk/utils/logger.py

@@ -0,0 +1,233 @@
+"""Logging utilities for Grasp SDK Python implementation.
+
+This module provides a structured logging system with support for
+different log levels, console output, and file logging.
+"""
+
+import json
+import logging
+import sys
+from datetime import datetime
+from typing import Any, Dict, Optional, Union
+from enum import IntEnum
+
+
+class LogLevel(IntEnum):
+    """Log levels with numeric values for comparison."""
+    DEBUG = 0
+    INFO = 1
+    WARN = 2
+    ERROR = 3
+
+
+class Logger:
+    """Logger class for structured logging."""
+    
+    def __init__(self, config: Dict[str, Any]):
+        """Initialize logger with configuration.
+        
+        Args:
+            config: Logger configuration dictionary containing:
+                   - level: Log level ('debug', 'info', 'warn', 'error')
+                   - console: Whether to output to console
+                   - file: Optional file path for logging
+        """
+        self.config = config
+        self.current_level = LogLevel[config['level'].upper()]
+        self._setup_file_logger()
+    
+    def _setup_file_logger(self) -> None:
+        """Setup file logging if configured."""
+        if self.config.get('file'):
+            # Configure Python's built-in logging for file output
+            logging.basicConfig(
+                filename=self.config['file'],
+                level=getattr(logging, self.config['level'].upper()),
+                format='%(asctime)s [%(levelname)s] %(message)s',
+                datefmt='%Y-%m-%dT%H:%M:%S.%fZ'
+            )
+            self.file_logger = logging.getLogger('grasp_file')
+        else:
+            self.file_logger = None
+    
+    def _format_message(self, level: str, message: str, data: Optional[Any] = None) -> str:
+        """Formats log message with timestamp and level.
+        
+        Args:
+            level: Log level string
+            message: Log message
+            data: Additional data to log
+            
+        Returns:
+            str: Formatted log string
+        """
+        timestamp = datetime.utcnow().isoformat() + 'Z'
+        data_str = f' {json.dumps(data)}' if data is not None else ''
+        return f'[{timestamp}] [{level.upper()}] {message}{data_str}'
+    
+    def _log(self, level: str, message: str, data: Optional[Any] = None) -> None:
+        """Logs a message if the level is enabled.
+        
+        Args:
+            level: Log level string
+            message: Log message
+            data: Additional data to log
+        """
+        level_enum = LogLevel[level.upper()]
+        if level_enum < self.current_level:
+            return
+        
+        formatted_message = self._format_message(level, message, data)
+        
+        # Console output
+        if self.config['console']:
+            if level == 'debug':
+                print(formatted_message, file=sys.stdout)
+            elif level == 'info':
+                print(formatted_message, file=sys.stdout)
+            elif level == 'warn':
+                print(formatted_message, file=sys.stderr)
+            elif level == 'error':
+                print(formatted_message, file=sys.stderr)
+        
+        # File output
+        if self.file_logger:
+            if level == 'debug':
+                self.file_logger.debug(message, extra={'data': data} if data else None)
+            elif level == 'info':
+                self.file_logger.info(message, extra={'data': data} if data else None)
+            elif level == 'warn':
+                self.file_logger.warning(message, extra={'data': data} if data else None)
+            elif level == 'error':
+                self.file_logger.error(message, extra={'data': data} if data else None)
+    
+    def debug(self, message: str, data: Optional[Any] = None) -> None:
+        """Logs debug message.
+        
+        Args:
+            message: Debug message
+            data: Additional data
+        """
+        self._log('debug', message, data)
+    
+    def info(self, message: str, data: Optional[Any] = None) -> None:
+        """Logs info message.
+        
+        Args:
+            message: Info message
+            data: Additional data
+        """
+        self._log('info', message, data)
+    
+    def warn(self, message: str, data: Optional[Any] = None) -> None:
+        """Logs warning message.
+        
+        Args:
+            message: Warning message
+            data: Additional data
+        """
+        self._log('warn', message, data)
+    
+    def error(self, message: str, data: Optional[Any] = None) -> None:
+        """Logs error message.
+        
+        Args:
+            message: Error message
+            data: Additional data
+        """
+        self._log('error', message, data)
+    
+    def child(self, context: str) -> 'Logger':
+        """Creates a child logger with additional context.
+        
+        Args:
+            context: Context to add to all log messages
+            
+        Returns:
+            Logger: New logger instance with context
+        """
+        child_logger = Logger(self.config)
+        
+        # Override the _log method to add context
+        original_log = child_logger._log
+        
+        def contextual_log(level: str, message: str, data: Optional[Any] = None) -> None:
+            original_log(level, f'[{context}] {message}', data)
+        
+        child_logger._log = contextual_log
+        return child_logger
+
+
+# Global logger instance
+_default_logger: Optional[Logger] = None
+
+
+def init_logger(config: Dict[str, Any]) -> None:
+    """Initializes the default logger.
+    
+    Args:
+        config: Logger configuration dictionary
+    """
+    global _default_logger
+    _default_logger = Logger(config)
+
+
+def get_logger() -> Logger:
+    """Gets the default logger instance.
+    
+    Returns:
+        Logger: Default logger instance
+        
+    Raises:
+        RuntimeError: If logger is not initialized
+    """
+    if _default_logger is None:
+        raise RuntimeError('Logger not initialized. Call init_logger() first.')
+    return _default_logger
+
+
+def get_default_logger() -> Logger:
+    """Gets a default logger with basic configuration.
+    
+    Returns:
+        Logger: Logger with default configuration
+    """
+    default_config = {
+        'level': 'info',
+        'console': True,
+        'file': None,
+    }
+    return Logger(default_config)
+
+
+# Convenience functions for quick logging
+def debug(message: str, data: Optional[Any] = None) -> None:
+    """Quick debug logging function."""
+    try:
+        get_logger().debug(message, data)
+    except RuntimeError:
+        get_default_logger().debug(message, data)
+
+
+def info(message: str, data: Optional[Any] = None) -> None:
+    """Quick info logging function."""
+    try:
+        get_logger().info(message, data)
+    except RuntimeError:
+        get_default_logger().info(message, data)
+
+
+def warn(message: str, data: Optional[Any] = None) -> None:
+    """Quick warning logging function."""
+    try:
+        get_logger().warn(message, data)
+    except RuntimeError:
+        get_default_logger().warn(message, data)
+
+
+def error(message: str, data: Optional[Any] = None) -> None:
+    """Quick error logging function."""
+    try:
+        get_logger().error(message, data)
+    except RuntimeError:
+        get_default_logger().error(message, data)