synapse-sdk 1.0.0b5__py3-none-any.whl → 2025.12.3__py3-none-any.whl

synapse_sdk/plugins/categories/upload/actions/upload/enums.py

@@ -0,0 +1,493 @@
+from enum import Enum
+
+from synapse_sdk.shared.enums import Context
+
+
+class ValidationErrorCode(str, Enum):
+    """Validation error codes for Pydantic validators.
+
+    Used in field validators to provide consistent, type-safe error codes
+    for resource validation failures.
+    """
+
+    MISSING_CONTEXT = 'missing_context'
+    STORAGE_NOT_FOUND = 'storage_not_found'
+    DATA_COLLECTION_NOT_FOUND = 'data_collection_not_found'
+    PROJECT_NOT_FOUND = 'project_not_found'
+
+
+# Validation error message templates
+VALIDATION_ERROR_MESSAGES = {
+    ValidationErrorCode.MISSING_CONTEXT: 'Validation context is required.',
+    ValidationErrorCode.STORAGE_NOT_FOUND: 'Storage with ID {0} does not exist or is not accessible: {1}',
+    ValidationErrorCode.DATA_COLLECTION_NOT_FOUND: 'Data collection with ID {0} does not exist or is not accessible: {1}',
+    ValidationErrorCode.PROJECT_NOT_FOUND: 'Project with ID {0} does not exist or is not accessible: {1}',
+}
+
+
+class UploadStatus(str, Enum):
+    """Upload processing status enumeration.
+
+    Defines the possible states for upload operations, data files, and data units
+    throughout the upload process.
+
+    Attributes:
+        SUCCESS: Upload completed successfully
+        FAILED: Upload failed with errors
+    """
+
+    SUCCESS = 'success'
+    FAILED = 'failed'
+
+
+class LogCode(str, Enum):
+    """Type-safe logging codes for upload operations.
+
+    Enumeration of all possible log events during upload processing. Each code
+    corresponds to a specific event or error state with predefined message
+    templates and log levels.
+
+    The codes are organized by category:
+    - Validation codes (VALIDATION_FAILED, STORAGE_VALIDATION_FAILED, etc.)
+    - File processing codes (NO_FILES_FOUND, FILES_DISCOVERED, etc.)
+    - Excel processing codes (EXCEL_SECURITY_VIOLATION, EXCEL_PARSING_ERROR, etc.)
+    - Progress tracking codes (UPLOADING_DATA_FILES, GENERATING_DATA_UNITS, etc.)
+
+    Each code maps to a configuration in LOG_MESSAGES with message template
+    and appropriate log level.
+    """
+
+    STORAGE_VALIDATION_FAILED = 'STORAGE_VALIDATION_FAILED'
+    COLLECTION_VALIDATION_FAILED = 'COLLECTION_VALIDATION_FAILED'
+    PROJECT_VALIDATION_FAILED = 'PROJECT_VALIDATION_FAILED'
+    VALIDATION_FAILED = 'VALIDATION_FAILED'
+    NO_FILES_FOUND = 'NO_FILES_FOUND'
+    NO_FILES_UPLOADED = 'NO_FILES_UPLOADED'
+    NO_DATA_UNITS_GENERATED = 'NO_DATA_UNITS_GENERATED'
+    NO_TYPE_DIRECTORIES = 'NO_TYPE_DIRECTORIES'
+    EXCEL_SECURITY_VIOLATION = 'EXCEL_SECURITY_VIOLATION'
+    EXCEL_PARSING_ERROR = 'EXCEL_PARSING_ERROR'
+    EXCEL_METADATA_LOADED = 'EXCEL_METADATA_LOADED'
+    UPLOADING_DATA_FILES = 'UPLOADING_DATA_FILES'
+    GENERATING_DATA_UNITS = 'GENERATING_DATA_UNITS'
+    IMPORT_COMPLETED = 'IMPORT_COMPLETED'
+    TYPE_DIRECTORIES_FOUND = 'TYPE_DIRECTORIES_FOUND'
+    TYPE_STRUCTURE_DETECTED = 'TYPE_STRUCTURE_DETECTED'
+    FILES_DISCOVERED = 'FILES_DISCOVERED'
+    NO_FILES_FOUND_WARNING = 'NO_FILES_FOUND_WARNING'
+    FILE_UPLOAD_FAILED = 'FILE_UPLOAD_FAILED'
+    DATA_UNIT_BATCH_FAILED = 'DATA_UNIT_BATCH_FAILED'
+    FILENAME_TOO_LONG = 'FILENAME_TOO_LONG'
+    MISSING_REQUIRED_FILES = 'MISSING_REQUIRED_FILES'
+    EXCEL_FILE_NOT_FOUND = 'EXCEL_FILE_NOT_FOUND'
+    EXCEL_FILE_VALIDATION_STARTED = 'EXCEL_FILE_VALIDATION_STARTED'
+    EXCEL_WORKBOOK_LOADED = 'EXCEL_WORKBOOK_LOADED'
+    FILE_ORGANIZATION_STARTED = 'FILE_ORGANIZATION_STARTED'
+    BATCH_PROCESSING_STARTED = 'BATCH_PROCESSING_STARTED'
+    EXCEL_SECURITY_VALIDATION_STARTED = 'EXCEL_SECURITY_VALIDATION_STARTED'
+    EXCEL_MEMORY_ESTIMATION = 'EXCEL_MEMORY_ESTIMATION'
+    EXCEL_FILE_NOT_FOUND_PATH = 'EXCEL_FILE_NOT_FOUND_PATH'
+    EXCEL_SECURITY_VALIDATION_FAILED = 'EXCEL_SECURITY_VALIDATION_FAILED'
+    EXCEL_PARSING_FAILED = 'EXCEL_PARSING_FAILED'
+    EXCEL_INVALID_FILE_FORMAT = 'EXCEL_INVALID_FILE_FORMAT'
+    EXCEL_FILE_TOO_LARGE = 'EXCEL_FILE_TOO_LARGE'
+    EXCEL_FILE_ACCESS_ERROR = 'EXCEL_FILE_ACCESS_ERROR'
+    EXCEL_UNEXPECTED_ERROR = 'EXCEL_UNEXPECTED_ERROR'
+    # Excel path resolution codes (from HEAD)
+    EXCEL_PATH_RESOLVED_STORAGE = 'EXCEL_PATH_RESOLVED_STORAGE'
+    EXCEL_PATH_RESOLUTION_FAILED = 'EXCEL_PATH_RESOLUTION_FAILED'
+    EXCEL_PATH_RESOLUTION_ERROR = 'EXCEL_PATH_RESOLUTION_ERROR'
+    # Asset path codes
+    ASSET_PATH_ACCESS_ERROR = 'ASSET_PATH_ACCESS_ERROR'
+    ASSET_PATH_NOT_FOUND = 'ASSET_PATH_NOT_FOUND'
+    # Step lifecycle codes
+    STEP_STARTING = 'STEP_STARTING'
+    STEP_COMPLETED = 'STEP_COMPLETED'
+    STEP_SKIPPED = 'STEP_SKIPPED'
+    STEP_ERROR = 'STEP_ERROR'
+    # Rollback codes
+    ROLLBACK_INITIALIZATION = 'ROLLBACK_INITIALIZATION'
+    ROLLBACK_DATA_UNIT_GENERATION = 'ROLLBACK_DATA_UNIT_GENERATION'
+    ROLLBACK_FILE_VALIDATION = 'ROLLBACK_FILE_VALIDATION'
+    ROLLBACK_FILE_UPLOADS = 'ROLLBACK_FILE_UPLOADS'
+    ROLLBACK_COLLECTION_ANALYSIS = 'ROLLBACK_COLLECTION_ANALYSIS'
+    ROLLBACK_FILE_ORGANIZATION = 'ROLLBACK_FILE_ORGANIZATION'
+    ROLLBACK_CLEANUP = 'ROLLBACK_CLEANUP'
+    # Metadata processing codes
+    NO_METADATA_STRATEGY = 'NO_METADATA_STRATEGY'
+    METADATA_FILE_ATTRIBUTE_PROCESSING = 'METADATA_FILE_ATTRIBUTE_PROCESSING'
+    METADATA_TEMP_FILE_CLEANUP = 'METADATA_TEMP_FILE_CLEANUP'
+    METADATA_TEMP_FILE_CLEANUP_FAILED = 'METADATA_TEMP_FILE_CLEANUP_FAILED'
+    METADATA_BASE64_DECODED = 'METADATA_BASE64_DECODED'
+    METADATA_BASE64_DECODE_FAILED = 'METADATA_BASE64_DECODE_FAILED'
+    # Multi-path mode codes
+    MULTI_PATH_MODE_ENABLED = 'MULTI_PATH_MODE_ENABLED'
+    OPTIONAL_SPEC_SKIPPED = 'OPTIONAL_SPEC_SKIPPED'
+    DISCOVERING_FILES_FOR_ASSET = 'DISCOVERING_FILES_FOR_ASSET'
+    NO_FILES_FOUND_FOR_ASSET = 'NO_FILES_FOUND_FOR_ASSET'
+    FILES_FOUND_FOR_ASSET = 'FILES_FOUND_FOR_ASSET'
+    ORGANIZING_FILES_MULTI_PATH = 'ORGANIZING_FILES_MULTI_PATH'
+    TYPE_DIRECTORIES_MULTI_PATH = 'TYPE_DIRECTORIES_MULTI_PATH'
+    DATA_UNITS_CREATED_FROM_FILES = 'DATA_UNITS_CREATED_FROM_FILES'
+    # Cleanup codes
+    CLEANUP_WARNING = 'CLEANUP_WARNING'
+    CLEANUP_TEMP_DIR_SUCCESS = 'CLEANUP_TEMP_DIR_SUCCESS'
+    CLEANUP_TEMP_DIR_FAILED = 'CLEANUP_TEMP_DIR_FAILED'
+    # Workflow error codes
+    UPLOAD_WORKFLOW_FAILED = 'UPLOAD_WORKFLOW_FAILED'
+    UNKNOWN_LOG_CODE = 'UNKNOWN_LOG_CODE'
+    # Orchestrator workflow codes
+    WORKFLOW_STARTING = 'WORKFLOW_STARTING'
+    WORKFLOW_COMPLETED = 'WORKFLOW_COMPLETED'
+    WORKFLOW_FAILED = 'WORKFLOW_FAILED'
+    STEP_FAILED = 'STEP_FAILED'
+    STEP_EXCEPTION = 'STEP_EXCEPTION'
+    STEP_TRACEBACK = 'STEP_TRACEBACK'
+    ROLLBACK_STARTING = 'ROLLBACK_STARTING'
+    ROLLBACK_COMPLETED = 'ROLLBACK_COMPLETED'
+    STEP_ROLLBACK = 'STEP_ROLLBACK'
+    ROLLBACK_ERROR = 'ROLLBACK_ERROR'
+    # Extension filtering codes
+    FILES_FILTERED_BY_EXTENSION = 'FILES_FILTERED_BY_EXTENSION'
+
+
+LOG_MESSAGES = {
+    LogCode.STORAGE_VALIDATION_FAILED: {
+        'message': 'Storage validation failed.',
+        'level': Context.DANGER,
+    },
+    LogCode.COLLECTION_VALIDATION_FAILED: {
+        'message': 'Collection validation failed.',
+        'level': Context.DANGER,
+    },
+    LogCode.PROJECT_VALIDATION_FAILED: {
+        'message': 'Project validation failed.',
+        'level': Context.DANGER,
+    },
+    LogCode.VALIDATION_FAILED: {
+        'message': 'Validation failed.',
+        'level': Context.DANGER,
+    },
+    LogCode.NO_FILES_FOUND: {
+        'message': 'Files not found on the path.',
+        'level': Context.WARNING,
+    },
+    LogCode.NO_FILES_UPLOADED: {
+        'message': 'No files were uploaded.',
+        'level': Context.WARNING,
+    },
+    LogCode.NO_DATA_UNITS_GENERATED: {
+        'message': 'No data units were generated.',
+        'level': Context.WARNING,
+    },
+    LogCode.NO_TYPE_DIRECTORIES: {
+        'message': 'No type-based directory structure found.',
+        'level': Context.INFO,
+    },
+    LogCode.EXCEL_SECURITY_VIOLATION: {
+        'message': 'Excel security validation failed: {}',
+        'level': Context.DANGER,
+    },
+    LogCode.EXCEL_PARSING_ERROR: {
+        'message': 'Excel parsing failed: {}',
+        'level': Context.DANGER,
+    },
+    LogCode.EXCEL_METADATA_LOADED: {
+        'message': 'Excel metadata loaded for {} files',
+        'level': None,
+    },
+    LogCode.UPLOADING_DATA_FILES: {
+        'message': 'Uploading data files...',
+        'level': None,
+    },
+    LogCode.GENERATING_DATA_UNITS: {
+        'message': 'Generating data units...',
+        'level': None,
+    },
+    LogCode.IMPORT_COMPLETED: {
+        'message': 'Import completed.',
+        'level': None,
+    },
+    LogCode.TYPE_DIRECTORIES_FOUND: {
+        'message': 'Found type directories: {}',
+        'level': None,
+    },
+    LogCode.TYPE_STRUCTURE_DETECTED: {
+        'message': 'Detected type-based directory structure',
+        'level': None,
+    },
+    LogCode.FILES_DISCOVERED: {
+        'message': 'Discovered {} files',
+        'level': None,
+    },
+    LogCode.NO_FILES_FOUND_WARNING: {
+        'message': 'No files found.',
+        'level': Context.WARNING,
+    },
+    LogCode.FILE_UPLOAD_FAILED: {
+        'message': 'Failed to upload file: {}',
+        'level': Context.DANGER,
+    },
+    LogCode.DATA_UNIT_BATCH_FAILED: {
+        'message': 'Failed to create data units batch: {}',
+        'level': Context.DANGER,
+    },
+    LogCode.FILENAME_TOO_LONG: {
+        'message': 'Skipping file with overly long name: {}...',
+        'level': Context.WARNING,
+    },
+    LogCode.MISSING_REQUIRED_FILES: {
+        'message': '{} missing required files: {}',
+        'level': Context.WARNING,
+    },
+    LogCode.EXCEL_FILE_NOT_FOUND: {
+        'message': 'Excel metadata file not found: {}',
+        'level': Context.WARNING,
+    },
+    LogCode.EXCEL_FILE_VALIDATION_STARTED: {
+        'message': 'Excel file validation started',
+        'level': Context.INFO,
+    },
+    LogCode.EXCEL_WORKBOOK_LOADED: {
+        'message': 'Excel workbook loaded successfully',
+        'level': Context.INFO,
+    },
+    LogCode.FILE_ORGANIZATION_STARTED: {
+        'message': 'File organization started',
+        'level': Context.INFO,
+    },
+    LogCode.BATCH_PROCESSING_STARTED: {
+        'message': 'Batch processing started: {} batches of {} items each',
+        'level': Context.INFO,
+    },
+    LogCode.EXCEL_SECURITY_VALIDATION_STARTED: {
+        'message': 'Excel security validation started for file size: {} bytes',
+        'level': Context.INFO,
+    },
+    LogCode.EXCEL_MEMORY_ESTIMATION: {
+        'message': 'Excel memory estimation: {} bytes (file) * 3 = {} bytes (estimated)',
+        'level': Context.INFO,
+    },
+    LogCode.EXCEL_FILE_NOT_FOUND_PATH: {
+        'message': 'Excel metadata file not found',
+        'level': Context.WARNING,
+    },
+    LogCode.EXCEL_SECURITY_VALIDATION_FAILED: {
+        'message': 'Excel security validation failed: {}',
+        'level': Context.DANGER,
+    },
+    LogCode.EXCEL_PARSING_FAILED: {
+        'message': 'Excel parsing failed: {}',
+        'level': Context.DANGER,
+    },
+    LogCode.EXCEL_INVALID_FILE_FORMAT: {
+        'message': 'Invalid Excel file format: {}',
+        'level': Context.DANGER,
+    },
+    LogCode.EXCEL_FILE_TOO_LARGE: {
+        'message': 'Excel file too large to process (memory limit exceeded)',
+        'level': Context.DANGER,
+    },
+    LogCode.EXCEL_FILE_ACCESS_ERROR: {
+        'message': 'File access error reading excel metadata: {}',
+        'level': Context.DANGER,
+    },
+    LogCode.EXCEL_UNEXPECTED_ERROR: {
+        'message': 'Unexpected error reading excel metadata: {}',
+        'level': Context.DANGER,
+    },
+    # Excel path resolution messages (from HEAD)
+    LogCode.EXCEL_PATH_RESOLVED_STORAGE: {
+        'message': 'Resolved Excel metadata path relative to storage: {}',
+        'level': Context.INFO,
+    },
+    LogCode.EXCEL_PATH_RESOLUTION_FAILED: {
+        'message': 'Storage path resolution failed ({}): {} - trying other strategies',
+        'level': Context.INFO,
+    },
+    LogCode.EXCEL_PATH_RESOLUTION_ERROR: {
+        'message': 'Unexpected error resolving storage path ({}): {} - trying other strategies',
+        'level': Context.WARNING,
+    },
+    # Asset path messages
+    LogCode.ASSET_PATH_ACCESS_ERROR: {
+        'message': 'Error accessing path for {}: {}',
+        'level': Context.WARNING,
+    },
+    LogCode.ASSET_PATH_NOT_FOUND: {
+        'message': 'Path does not exist for {}: {}',
+        'level': Context.WARNING,
+    },
+    # Step lifecycle messages
+    LogCode.STEP_STARTING: {
+        'message': 'Starting step: {}',
+        'level': Context.INFO,
+    },
+    LogCode.STEP_COMPLETED: {
+        'message': 'Completed step: {}',
+        'level': Context.INFO,
+    },
+    LogCode.STEP_SKIPPED: {
+        'message': 'Skipped step: {}',
+        'level': Context.INFO,
+    },
+    LogCode.STEP_ERROR: {
+        'message': 'Error in step {}: {}',
+        'level': Context.DANGER,
+    },
+    # Rollback messages
+    LogCode.ROLLBACK_INITIALIZATION: {
+        'message': 'Rolling back initialization step',
+        'level': Context.INFO,
+    },
+    LogCode.ROLLBACK_DATA_UNIT_GENERATION: {
+        'message': 'Rolled back data unit generation',
+        'level': Context.INFO,
+    },
+    LogCode.ROLLBACK_FILE_VALIDATION: {
+        'message': 'Rolled back file validation',
+        'level': Context.INFO,
+    },
+    LogCode.ROLLBACK_FILE_UPLOADS: {
+        'message': 'Rolled back file uploads',
+        'level': Context.INFO,
+    },
+    LogCode.ROLLBACK_COLLECTION_ANALYSIS: {
+        'message': 'Rolled back collection analysis',
+        'level': Context.INFO,
+    },
+    LogCode.ROLLBACK_FILE_ORGANIZATION: {
+        'message': 'Rolled back file organization',
+        'level': Context.INFO,
+    },
+    LogCode.ROLLBACK_CLEANUP: {
+        'message': 'Cleanup step rollback - no action needed',
+        'level': Context.INFO,
+    },
+    # Metadata processing messages
+    LogCode.NO_METADATA_STRATEGY: {
+        'message': 'No metadata strategy configured - skipping metadata processing',
+        'level': Context.INFO,
+    },
+    LogCode.METADATA_FILE_ATTRIBUTE_PROCESSING: {
+        'message': 'Processing metadata for file attribute: {}',
+        'level': Context.INFO,
+    },
+    LogCode.METADATA_TEMP_FILE_CLEANUP: {
+        'message': 'Cleaned up temporary Excel file: {}',
+        'level': Context.INFO,
+    },
+    LogCode.METADATA_TEMP_FILE_CLEANUP_FAILED: {
+        'message': 'Failed to clean up temporary file {}: {}',
+        'level': Context.WARNING,
+    },
+    LogCode.METADATA_BASE64_DECODED: {
+        'message': 'Decoded base64 Excel metadata to temporary file: {}',
+        'level': Context.INFO,
+    },
+    LogCode.METADATA_BASE64_DECODE_FAILED: {
+        'message': 'Failed to decode base64 Excel metadata: {}',
+        'level': Context.DANGER,
+    },
+    # Multi-path mode messages
+    LogCode.MULTI_PATH_MODE_ENABLED: {
+        'message': 'Using multi-path mode with {} asset configurations',
+        'level': Context.INFO,
+    },
+    LogCode.OPTIONAL_SPEC_SKIPPED: {
+        'message': 'Skipping optional spec {}: no asset path configured',
+        'level': Context.INFO,
+    },
+    LogCode.DISCOVERING_FILES_FOR_ASSET: {
+        'message': 'Discovering files for {} (recursive={})',
+        'level': Context.INFO,
+    },
+    LogCode.NO_FILES_FOUND_FOR_ASSET: {
+        'message': 'No files found for {}',
+        'level': Context.WARNING,
+    },
+    LogCode.FILES_FOUND_FOR_ASSET: {
+        'message': 'Found {} files for {}',
+        'level': Context.INFO,
+    },
+    LogCode.ORGANIZING_FILES_MULTI_PATH: {
+        'message': 'Organizing {} files across {} specs',
+        'level': Context.INFO,
+    },
+    LogCode.TYPE_DIRECTORIES_MULTI_PATH: {
+        'message': 'Type directories: {}',
+        'level': Context.INFO,
+    },
+    LogCode.DATA_UNITS_CREATED_FROM_FILES: {
+        'message': 'Created {} data units from {} files',
+        'level': Context.INFO,
+    },
+    # Cleanup messages
+    LogCode.CLEANUP_WARNING: {
+        'message': 'Cleanup warning: {}',
+        'level': Context.WARNING,
+    },
+    LogCode.CLEANUP_TEMP_DIR_SUCCESS: {
+        'message': 'Cleaned up temporary directory: {}',
+        'level': Context.INFO,
+    },
+    LogCode.CLEANUP_TEMP_DIR_FAILED: {
+        'message': 'Failed to cleanup temporary directory: {}',
+        'level': Context.WARNING,
+    },
+    # Workflow error messages
+    LogCode.UPLOAD_WORKFLOW_FAILED: {
+        'message': 'Upload workflow failed: {}',
+        'level': Context.DANGER,
+    },
+    LogCode.UNKNOWN_LOG_CODE: {
+        'message': 'Unknown log code: {}',
+        'level': Context.WARNING,
+    },
+    # Orchestrator workflow messages
+    LogCode.WORKFLOW_STARTING: {
+        'message': 'Starting upload workflow with {} steps: {}',
+        'level': Context.INFO,
+    },
+    LogCode.WORKFLOW_COMPLETED: {
+        'message': 'Upload workflow completed successfully',
+        'level': Context.INFO,
+    },
+    LogCode.WORKFLOW_FAILED: {
+        'message': 'Upload workflow failed: {}',
+        'level': Context.DANGER,
+    },
+    LogCode.STEP_FAILED: {
+        'message': "Step '{}' failed: {}",
+        'level': Context.DANGER,
+    },
+    LogCode.STEP_EXCEPTION: {
+        'message': "Exception in step '{}': {}",
+        'level': Context.DANGER,
+    },
+    LogCode.STEP_TRACEBACK: {
+        'message': 'Traceback: {}',
+        'level': Context.DANGER,
+    },
+    LogCode.ROLLBACK_STARTING: {
+        'message': 'Starting rollback of {} executed steps',
+        'level': Context.WARNING,
+    },
+    LogCode.ROLLBACK_COMPLETED: {
+        'message': 'Rollback completed',
+        'level': Context.INFO,
+    },
+    LogCode.STEP_ROLLBACK: {
+        'message': 'Rolling back step: {}',
+        'level': Context.INFO,
+    },
+    LogCode.ROLLBACK_ERROR: {
+        'message': "Error rolling back step '{}': {}",
+        'level': Context.WARNING,
+    },
+    # Extension filtering messages
+    LogCode.FILES_FILTERED_BY_EXTENSION: {
+        'message': 'Filtered {} {} files with unavailable extensions: {} (allowed: {})',
+        'level': Context.WARNING,
+    },
+}

synapse_sdk/plugins/categories/upload/actions/upload/exceptions.py

@@ -0,0 +1,36 @@
+class ExcelSecurityError(Exception):
+    """Exception raised when Excel file security validation fails.
+
+    This exception is raised when an Excel file violates security constraints
+    such as file size limits, memory usage limits, or contains potentially
+    dangerous content.
+
+    Used during Excel metadata processing to enforce security policies
+    and prevent processing of files that could pose security risks.
+
+    Example:
+        >>> if file_size > max_size:
+        ...     raise ExcelSecurityError(f"File size {file_size} exceeds limit {max_size}")
+    """
+
+    pass
+
+
+class ExcelParsingError(Exception):
+    """Exception raised when Excel file parsing encounters errors.
+
+    This exception is raised when an Excel file cannot be parsed due to
+    format issues, corruption, or other parsing-related problems that
+    prevent successful metadata extraction.
+
+    Used during Excel metadata loading to distinguish parsing errors
+    from security violations or other types of errors.
+
+    Example:
+        >>> try:
+        ...     workbook = load_workbook(excel_file)
+        ... except InvalidFileException as e:
+        ...     raise ExcelParsingError(f"Failed to parse Excel file: {e}")
+    """
+
+    pass

synapse_sdk/plugins/categories/upload/actions/upload/factory.py

@@ -0,0 +1,138 @@
+from typing import Any, Dict
+
+from .strategies.base import (
+    DataUnitStrategy,
+    FileDiscoveryStrategy,
+    MetadataStrategy,
+    UploadStrategy,
+    ValidationStrategy,
+)
+
+
+class StrategyFactory:
+    """Factory for creating strategy instances based on configuration."""
+
+    def __init__(self):
+        self._validation_strategies = {}
+        self._file_discovery_strategies = {}
+        self._metadata_strategies = {}
+        self._upload_strategies = {}
+        self._data_unit_strategies = {}
+
+    def register_validation_strategy(self, name: str, strategy_class: type) -> None:
+        """Register a validation strategy class."""
+        self._validation_strategies[name] = strategy_class
+
+    def register_file_discovery_strategy(self, name: str, strategy_class: type) -> None:
+        """Register a file discovery strategy class."""
+        self._file_discovery_strategies[name] = strategy_class
+
+    def register_metadata_strategy(self, name: str, strategy_class: type) -> None:
+        """Register a metadata strategy class."""
+        self._metadata_strategies[name] = strategy_class
+
+    def register_upload_strategy(self, name: str, strategy_class: type) -> None:
+        """Register an upload strategy class."""
+        self._upload_strategies[name] = strategy_class
+
+    def register_data_unit_strategy(self, name: str, strategy_class: type) -> None:
+        """Register a data unit strategy class."""
+        self._data_unit_strategies[name] = strategy_class
+
+    def create_validation_strategy(self, params: Dict[str, Any], context=None) -> ValidationStrategy:
+        """Create validation strategy based on parameters."""
+        strategy_name = params.get('validation_strategy', 'default')
+
+        if strategy_name not in self._validation_strategies:
+            # Import default strategy if not registered
+            from .strategies.validation.default import DefaultValidationStrategy
+
+            self.register_validation_strategy('default', DefaultValidationStrategy)
+            strategy_name = 'default'
+
+        strategy_class = self._validation_strategies[strategy_name]
+        return strategy_class()
+
+    def create_file_discovery_strategy(self, params: Dict[str, Any], context=None) -> FileDiscoveryStrategy:
+        """Create file discovery strategy based on parameters."""
+        is_recursive = params.get('is_recursive', True)
+        strategy_name = 'recursive' if is_recursive else 'flat'
+
+        if strategy_name not in self._file_discovery_strategies:
+            # Import default strategies if not registered
+            if strategy_name == 'recursive':
+                from .strategies.file_discovery.recursive import RecursiveFileDiscoveryStrategy
+
+                self.register_file_discovery_strategy('recursive', RecursiveFileDiscoveryStrategy)
+            else:
+                from .strategies.file_discovery.flat import FlatFileDiscoveryStrategy
+
+                self.register_file_discovery_strategy('flat', FlatFileDiscoveryStrategy)
+
+        strategy_class = self._file_discovery_strategies[strategy_name]
+        return strategy_class()
+
+    def create_metadata_strategy(self, params: Dict[str, Any], context=None) -> MetadataStrategy:
+        """Create metadata strategy based on parameters."""
+        # Always use Excel strategy for metadata processing
+        # It will handle both specified paths and default meta.xlsx/meta.xls files
+        strategy_name = 'excel'
+
+        if strategy_name not in self._metadata_strategies:
+            from .strategies.metadata.excel import ExcelMetadataStrategy
+
+            self.register_metadata_strategy('excel', ExcelMetadataStrategy)
+
+        strategy_class = self._metadata_strategies[strategy_name]
+        return strategy_class()
+
+    def create_upload_strategy(self, params: Dict[str, Any], context=None) -> UploadStrategy:
+        """Create upload strategy (always uses synchronous upload for guaranteed ordering)."""
+        if context is None:
+            raise ValueError('Upload strategies require context parameter')
+
+        # Always use sync upload to guarantee file order
+        # This is critical for video frame extraction and PDF page extraction
+        strategy_name = 'sync'
+
+        if strategy_name not in self._upload_strategies:
+            from .strategies.upload.sync import SyncUploadStrategy
+
+            self.register_upload_strategy('sync', SyncUploadStrategy)
+
+        strategy_class = self._upload_strategies[strategy_name]
+        # Upload strategies always need context for client access
+        return strategy_class(context)
+
+    def create_data_unit_strategy(self, params: Dict[str, Any], context=None) -> DataUnitStrategy:
+        """Create data unit strategy based on parameters."""
+        if context is None:
+            raise ValueError('Data unit strategies require context parameter')
+
+        batch_size = params.get('creating_data_unit_batch_size', 1)
+        strategy_name = 'batch' if batch_size > 1 else 'single'
+
+        if strategy_name not in self._data_unit_strategies:
+            # Import default strategies if not registered
+            if strategy_name == 'batch':
+                from .strategies.data_unit.batch import BatchDataUnitStrategy
+
+                self.register_data_unit_strategy('batch', BatchDataUnitStrategy)
+            else:
+                from .strategies.data_unit.single import SingleDataUnitStrategy
+
+                self.register_data_unit_strategy('single', SingleDataUnitStrategy)
+
+        strategy_class = self._data_unit_strategies[strategy_name]
+        # Data unit strategies always need context for client access
+        return strategy_class(context)
+
+    def get_available_strategies(self) -> Dict[str, list]:
+        """Get all available strategy types and their registered names."""
+        return {
+            'validation': list(self._validation_strategies.keys()),
+            'file_discovery': list(self._file_discovery_strategies.keys()),
+            'metadata': list(self._metadata_strategies.keys()),
+            'upload': list(self._upload_strategies.keys()),
+            'data_unit': list(self._data_unit_strategies.keys()),
+        }