omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/protocols/protocol_message_type_registry.py

@@ -0,0 +1,306 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""
+Protocol definition for the Message Type Registry.
+
+Defines the interface contract for message type registry implementations.
+Enables duck typing and test mocking while ensuring consistent API.
+
+Design Principles:
+    - Protocol-based interface for flexibility and testability
+    - Runtime-checkable for isinstance() validation
+    - Comprehensive API covering registration, query, and validation
+    - Thread-safety documented in implementation requirements
+
+Related:
+    - OMN-937: Central Message Type Registry implementation
+    - RegistryMessageType: Primary implementation of this protocol
+
+.. versionadded:: 0.5.0
+"""
+
+from typing import Protocol, runtime_checkable
+
+from omnibase_infra.enums import EnumMessageCategory
+from omnibase_infra.models.registry.model_message_type_entry import (
+    ModelMessageTypeEntry,
+)
+
+
+@runtime_checkable
+class ProtocolMessageTypeRegistry(Protocol):
+    """
+    Protocol for message type registry implementations.
+
+    Defines the interface contract for registries that map message types
+    to handler implementations with category and domain constraints.
+
+    Implementations must follow the freeze-after-init pattern:
+    1. Registration phase: All register_* methods available
+    2. Freeze: Call freeze() to lock the registry
+    3. Query phase: Only lookup methods available
+
+    Thread Safety Requirements:
+        - Registration methods must be thread-safe during registration phase
+        - After freeze(), all query methods must be safe for concurrent access
+        - Implementations should use appropriate locking strategies
+
+    Example Implementation:
+        .. code-block:: python
+
+            class MyRegistry:
+                '''Custom registry implementation.'''
+
+                def register_message_type(
+                    self,
+                    entry: ModelMessageTypeEntry,
+                ) -> None:
+                    ...
+
+                def get_handlers(
+                    self,
+                    message_type: str,
+                    topic_category: EnumMessageCategory,
+                    topic_domain: str,
+                ) -> list[str]:
+                    ...
+
+                # ... implement all protocol methods
+
+            # Verify protocol compliance
+            registry: ProtocolMessageTypeRegistry = MyRegistry()
+
+    See Also:
+        - :class:`RegistryMessageType`: Primary implementation
+
+    .. versionadded:: 0.5.0
+    """
+
+    # =========================================================================
+    # Registration Methods (available before freeze)
+    # =========================================================================
+
+    def register_message_type(
+        self,
+        entry: ModelMessageTypeEntry,
+    ) -> None:
+        """
+        Register a message type with its handler mappings.
+
+        Associates a message type with handler(s) and defines constraints
+        for valid usage. Supports fan-out by registering multiple handlers
+        for the same message type.
+
+        Args:
+            entry: The message type entry containing handler mappings
+                and constraints.
+
+        Raises:
+            ModelOnexError: If registry is frozen (INVALID_STATE)
+            ModelOnexError: If entry validation fails (VALIDATION_ERROR)
+
+        Thread Safety:
+            Must be thread-safe during registration phase.
+
+        .. versionadded:: 0.5.0
+        """
+        ...
+
+    def freeze(self) -> None:
+        """
+        Freeze the registry to prevent further modifications.
+
+        Once frozen, registration methods will raise ModelOnexError.
+        This enables thread-safe concurrent access during query phase.
+
+        Idempotent: Calling freeze() multiple times has no additional effect.
+
+        Raises:
+            ModelOnexError: If validation fails during freeze (e.g., missing
+                handler references)
+
+        Thread Safety:
+            Must be thread-safe.
+
+        .. versionadded:: 0.5.0
+        """
+        ...
+
+    # =========================================================================
+    # Query Methods (available after freeze)
+    # =========================================================================
+
+    def get_handlers(
+        self,
+        message_type: str,
+        topic_category: EnumMessageCategory,
+        topic_domain: str,
+    ) -> list[str]:
+        """
+        Get handler IDs for a message type with validation.
+
+        Validates that the message type is allowed in the given category
+        and that the topic domain matches domain constraints.
+
+        Args:
+            message_type: The message type to look up.
+            topic_category: The category inferred from the topic.
+            topic_domain: The domain extracted from the topic.
+
+        Returns:
+            List of handler IDs that can process this message type.
+            Empty list if no handlers registered.
+
+        Raises:
+            ModelOnexError: If registry is not frozen (INVALID_STATE)
+            ModelOnexError: If category constraint violated (VALIDATION_ERROR)
+            ModelOnexError: If domain constraint violated (VALIDATION_ERROR)
+
+        Thread Safety:
+            Must be safe for concurrent access after freeze().
+
+        .. versionadded:: 0.5.0
+        """
+        ...
+
+    def get_entry(self, message_type: str) -> ModelMessageTypeEntry | None:
+        """
+        Get the registry entry for a message type.
+
+        Args:
+            message_type: The message type to look up.
+
+        Returns:
+            The registry entry if found, None otherwise.
+
+        Raises:
+            ModelOnexError: If registry is not frozen (INVALID_STATE)
+
+        Thread Safety:
+            Must be safe for concurrent access after freeze().
+
+        .. versionadded:: 0.5.0
+        """
+        ...
+
+    def has_message_type(self, message_type: str) -> bool:
+        """
+        Check if a message type is registered.
+
+        Args:
+            message_type: The message type to check.
+
+        Returns:
+            True if registered, False otherwise.
+
+        Raises:
+            ModelOnexError: If registry is not frozen (INVALID_STATE)
+
+        Thread Safety:
+            Must be safe for concurrent access after freeze().
+
+        .. versionadded:: 0.5.0
+        """
+        ...
+
+    def list_message_types(
+        self,
+        category: EnumMessageCategory | None = None,
+        domain: str | None = None,
+    ) -> list[str]:
+        """
+        List registered message types with optional filtering.
+
+        Args:
+            category: Optional filter by allowed category.
+            domain: Optional filter by owning domain.
+
+        Returns:
+            List of message type names matching the filters.
+
+        Raises:
+            ModelOnexError: If registry is not frozen (INVALID_STATE)
+
+        Thread Safety:
+            Must be safe for concurrent access after freeze().
+
+        .. versionadded:: 0.5.0
+        """
+        ...
+
+    def list_domains(self) -> list[str]:
+        """
+        List all domains that have registered message types.
+
+        Returns:
+            List of unique domain names, sorted alphabetically.
+
+        Raises:
+            ModelOnexError: If registry is not frozen (INVALID_STATE)
+
+        Thread Safety:
+            Must be safe for concurrent access after freeze().
+
+        .. versionadded:: 0.5.0
+        """
+        ...
+
+    # =========================================================================
+    # Validation Methods
+    # =========================================================================
+
+    def validate_startup(self) -> list[str]:
+        """
+        Perform startup-time validation and return any errors.
+
+        Validates registry consistency:
+        - All handler references are valid
+        - No conflicting category constraints
+        - Domain constraints are properly configured
+
+        This method should be called after freeze() to ensure fail-fast
+        behavior before consumers start processing messages.
+
+        Returns:
+            List of validation error messages. Empty list if valid.
+
+        Raises:
+            ModelOnexError: If registry is not frozen (INVALID_STATE)
+
+        Thread Safety:
+            Must be safe for concurrent access after freeze().
+
+        .. versionadded:: 0.5.0
+        """
+        ...
+
+    # =========================================================================
+    # Properties
+    # =========================================================================
+
+    @property
+    def is_frozen(self) -> bool:
+        """
+        Check if the registry is frozen.
+
+        Returns:
+            True if frozen and registration is disabled.
+
+        .. versionadded:: 0.5.0
+        """
+        ...
+
+    @property
+    def entry_count(self) -> int:
+        """
+        Get the number of registered message type entries.
+
+        Returns:
+            Number of registered message types.
+
+        .. versionadded:: 0.5.0
+        """
+        ...
+
+
+__all__ = ["ProtocolMessageTypeRegistry"]

omnibase_infra/protocols/protocol_plugin_compute.py

@@ -0,0 +1,368 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Protocol definition for deterministic compute plugins.
+
+This module defines the ProtocolPluginCompute interface for plugins that perform
+pure data transformations without side effects. This protocol is designed for use
+with ONEX Compute nodes that require deterministic, reproducible operations.
+
+Protocol Contract:
+    Compute plugins MUST guarantee deterministic behavior:
+    - Same inputs ALWAYS produce the same outputs
+    - No dependency on external state or randomness
+    - No side effects (no I/O, no state mutation)
+    - No access to current time unless explicitly provided as input
+
+What Plugins MUST NOT Do:
+    ❌ Network operations (HTTP requests, API calls, socket connections)
+    ❌ Filesystem operations (file read/write, directory access)
+    ❌ Database operations (queries, transactions, connection pooling)
+    ❌ Random number generation (unless deterministic with provided seed)
+    ❌ Current time access (unless time is passed as input parameter)
+    ❌ Mutable shared state (global variables, class-level state)
+    ❌ External service calls (Kafka, Redis, Consul, Vault)
+    ❌ Environment variable access (unless explicitly allowed)
+    ❌ Process/thread creation or management
+    ❌ Signal handling or system calls
+
+What Plugins CAN Do:
+    ✅ Pure data transformations (mapping, filtering, aggregation)
+    ✅ Mathematical computations (arithmetic, statistics, algorithms)
+    ✅ String processing (parsing, formatting, validation)
+    ✅ Data structure operations (sorting, searching, grouping)
+    ✅ Validation and schema checking (Pydantic models, type checking)
+    ✅ Deterministic hashing (with consistent input ordering)
+    ✅ Deterministic randomness (with seed from input_data or context)
+
+Integration with ONEX Compute Nodes:
+    Compute nodes follow the 4-node architecture pattern:
+    - EFFECT: External I/O (database, network, filesystem)
+    - COMPUTE: Pure transformations (THIS PROTOCOL)
+    - REDUCER: State aggregation and consolidation
+    - ORCHESTRATOR: Workflow coordination
+
+    Compute plugins integrate with NodeComputeService to provide deterministic
+    processing capabilities. The node is responsible for I/O and state management,
+    while plugins focus purely on data transformation logic.
+
+Example Usage:
+    ```python
+    from omnibase_infra.protocols import ProtocolPluginCompute
+    from typing import Protocol, runtime_checkable
+
+    @runtime_checkable
+    class ProtocolPluginCompute(Protocol):
+        def execute(self, input_data: ModelPluginInputData, context: ModelPluginContext) -> ModelPluginOutputData:
+            '''Execute deterministic computation.'''
+            ...
+
+    # Example plugin implementation
+    class JsonSchemaValidator:
+        def execute(self, input_data: ModelPluginInputData, context: ModelPluginContext) -> ModelPluginOutputData:
+            '''Validate JSON data against schema.'''
+            schema = context.get("schema", {})
+            data = input_data.get("data", {})
+
+            # Pure validation logic (no I/O)
+            is_valid = self._validate_schema(data, schema)
+
+            return {
+                "valid": is_valid,
+                "data": data,
+                "errors": [] if is_valid else self._get_errors(data, schema),
+            }
+
+        def _validate_schema(self, data: dict[str, object], schema: dict[str, object]) -> bool:
+            # Pure computation - deterministic validation
+            ...
+
+        def _get_errors(self, data: dict[str, object], schema: dict[str, object]) -> list[dict[str, object]]:
+            # Pure computation - deterministic error extraction
+            ...
+    ```
+
+Protocol Verification:
+    Per ONEX conventions, protocol compliance is verified via duck typing rather
+    than isinstance checks. Verify the required method exists and is callable:
+
+    ```python
+    plugin = JsonSchemaValidator()
+
+    # Duck typing verification (preferred)
+    assert hasattr(plugin, 'execute') and callable(plugin.execute)
+
+    # Or use hasattr with getattr for cleaner pattern
+    execute_method = getattr(plugin, 'execute', None)
+    assert execute_method is not None and callable(execute_method)
+    ```
+
+See Also:
+    - src/omnibase_infra/plugins/plugin_compute_base.py for base implementation
+    - ONEX 4-node architecture documentation
+    - OMN-813 for complete compute plugin design
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+# Import directly from submodules to avoid circular import through plugins/__init__.py
+# (plugins/__init__.py imports plugin_compute_base which imports this module)
+from omnibase_infra.plugins.models.model_plugin_context import ModelPluginContext
+from omnibase_infra.plugins.models.model_plugin_input_data import ModelPluginInputData
+from omnibase_infra.plugins.models.model_plugin_output_data import ModelPluginOutputData
+
+__all__ = [
+    "ModelPluginContext",
+    "ModelPluginInputData",
+    "ModelPluginOutputData",
+    "ProtocolPluginCompute",
+]
+
+
+@runtime_checkable
+class ProtocolPluginCompute(Protocol):
+    """Protocol for deterministic compute plugins.
+
+    This protocol defines the interface for plugins that perform pure data
+    transformations without side effects. Implementations must guarantee
+    deterministic behavior where the same inputs always produce the same outputs.
+
+    Methods:
+        execute: Perform deterministic computation on input data.
+
+    Thread Safety:
+        Plugin implementations should be thread-safe and stateless. All required
+        state should be passed through input_data or context parameters.
+
+    Performance:
+        Plugins should be optimized for performance as they may be called
+        frequently in high-throughput data processing pipelines.
+
+    Example:
+        ```python
+        class DataNormalizer:
+            def execute(self, input_data: ModelPluginInputData, context: ModelPluginContext) -> ModelPluginOutputData:
+                '''Normalize numeric data to [0, 1] range.'''
+                values: list[float] = input_data.get("values", [])
+                min_val: float = context.get("min_value", 0.0)
+                max_val: float = context.get("max_value", 1.0)
+
+                # Pure computation - deterministic normalization
+                normalized: list[float] = [
+                    (v - min_val) / (max_val - min_val)
+                    for v in values
+                ]
+
+                return {
+                    "normalized_values": normalized,
+                    "min": min_val,
+                    "max": max_val,
+                }
+        ```
+    """
+
+    def execute(
+        self, input_data: ModelPluginInputData, context: ModelPluginContext
+    ) -> ModelPluginOutputData:
+        """Execute deterministic computation on input data.
+
+        This method must be deterministic: given the same input_data and context,
+        it must always produce the same output. No side effects are allowed.
+
+        Args:
+            input_data: Input data dictionary containing values to process.
+                Structure depends on plugin implementation.
+            context: Context dictionary providing configuration and metadata.
+                Should contain any external parameters needed for computation.
+
+        Returns:
+            Result dictionary containing computed output values.
+            Structure depends on plugin implementation.
+
+        Raises:
+            OnexError: For all computation failures (with proper error chaining).
+                Plugin implementations must convert all exceptions to OnexError.
+            ValueError: For invalid input_data or context (should be caught and wrapped).
+            TypeError: For incorrect input types (should be caught and wrapped).
+
+        Error Handling:
+            All plugin implementations MUST follow ONEX error handling standards:
+
+            1. **OnexError Chaining**: Convert all exceptions to OnexError with proper chaining
+               using `raise OnexError(...) from original_exception`.
+
+            2. **Correlation ID Propagation**: Always include correlation_id from context
+               in error details for distributed tracing.
+
+            3. **Never Suppress Errors**: All errors must be logged, handled, or escalated.
+               Silent failures are strictly prohibited.
+
+            4. **Context Preservation**: Maintain full error context for debugging.
+
+            Example - Input Validation Error:
+                ```python
+                def execute(self, input_data: ModelPluginInputData, context: ModelPluginContext) -> ModelPluginOutputData:
+                    from omnibase_core.errors import OnexError
+                    from omnibase_core.enums import CoreErrorCode
+
+                    correlation_id = context.get("correlation_id", "unknown")
+
+                    try:
+                        # Validate required fields
+                        if "required_field" not in input_data:
+                            raise ValueError("Missing required field: required_field")
+
+                        # Perform computation
+                        result = self._compute(input_data)
+                        return {"result": result}
+
+                    except ValueError as e:
+                        raise OnexError(
+                            message=f"Invalid input data: {e}",
+                            error_code=CoreErrorCode.INVALID_INPUT,
+                            correlation_id=correlation_id,
+                            plugin_name=self.__class__.__name__,
+                        ) from e
+                ```
+
+            Example - Computation Error with Context:
+                ```python
+                def execute(self, input_data: ModelPluginInputData, context: ModelPluginContext) -> ModelPluginOutputData:
+                    from omnibase_core.errors import OnexError
+                    from omnibase_core.enums import CoreErrorCode
+
+                    correlation_id = context.get("correlation_id", "unknown")
+
+                    try:
+                        # Perform complex computation
+                        values: list[float] = input_data.get("values", [])
+                        result: float = sum(values) / len(values)  # May raise ZeroDivisionError
+
+                        return {
+                            "average": result,
+                            "count": len(values),
+                            "correlation_id": correlation_id,
+                        }
+
+                    except ZeroDivisionError as e:
+                        raise OnexError(
+                            message="Cannot compute average: empty values list",
+                            error_code=CoreErrorCode.INVALID_INPUT,
+                            correlation_id=correlation_id,
+                            plugin_name=self.__class__.__name__,
+                            input_size=len(input_data.get("values", [])),
+                        ) from e
+
+                    except Exception as e:
+                        # Catch-all for unexpected errors
+                        raise OnexError(
+                            message=f"Computation failed: {e}",
+                            error_code=CoreErrorCode.INTERNAL_ERROR,
+                            correlation_id=correlation_id,
+                            plugin_name=self.__class__.__name__,
+                        ) from e
+                ```
+
+            Example - Type Validation Error:
+                ```python
+                def execute(self, input_data: ModelPluginInputData, context: ModelPluginContext) -> ModelPluginOutputData:
+                    from omnibase_core.errors import OnexError
+                    from omnibase_core.enums import CoreErrorCode
+
+                    correlation_id = context.get("correlation_id", "unknown")
+
+                    try:
+                        values = input_data.get("values")
+
+                        # Validate type
+                        if not isinstance(values, list):
+                            raise TypeError(f"Expected list for 'values', got {type(values).__name__}")
+
+                        # Compute result
+                        return {"processed": [v * 2 for v in values]}
+
+                    except TypeError as e:
+                        raise OnexError(
+                            message=f"Type validation failed: {e}",
+                            error_code=CoreErrorCode.INVALID_INPUT,
+                            correlation_id=correlation_id,
+                            plugin_name=self.__class__.__name__,
+                            expected_type="list",
+                            actual_type=type(input_data.get("values")).__name__,
+                        ) from e
+                ```
+
+        Error Recovery Patterns:
+            Plugins should implement graceful degradation where appropriate:
+
+            Example - Fallback Values:
+                ```python
+                def execute(self, input_data: ModelPluginInputData, context: ModelPluginContext) -> ModelPluginOutputData:
+                    from omnibase_core.errors import OnexError
+                    from omnibase_core.enums import CoreErrorCode
+
+                    correlation_id = context.get("correlation_id", "unknown")
+
+                    try:
+                        # Attempt primary computation
+                        result = self._complex_computation(input_data)
+
+                        return {
+                            "result": result,
+                            "fallback_used": False,
+                            "correlation_id": correlation_id,
+                        }
+
+                    except Exception as e:
+                        # Try fallback strategy
+                        try:
+                            fallback_result = self._simple_fallback(input_data)
+
+                            return {
+                                "result": fallback_result,
+                                "fallback_used": True,
+                                "warning": f"Primary computation failed: {e}",
+                                "correlation_id": correlation_id,
+                            }
+
+                        except Exception as fallback_error:
+                            # Both strategies failed - raise with full context
+                            raise OnexError(
+                                message="Both primary and fallback computations failed",
+                                error_code=CoreErrorCode.INTERNAL_ERROR,
+                                correlation_id=correlation_id,
+                                plugin_name=self.__class__.__name__,
+                                primary_error=str(e),
+                                fallback_error=str(fallback_error),
+                            ) from fallback_error
+                ```
+
+        Notes:
+            - Must be deterministic (same inputs → same outputs)
+            - Must not perform I/O operations
+            - Must not access external state
+            - Must not modify input_data or context
+            - Should validate inputs before processing
+            - Should include relevant metadata in output
+            - MUST include correlation_id in all error contexts
+            - MUST use proper OnexError chaining for all exceptions
+
+        Example:
+            ```python
+            # Input
+            input_data = {"values": [1, 2, 3, 4, 5]}
+            context = {"operation": "sum"}
+
+            # Execution
+            result = plugin.execute(input_data, context)
+
+            # Output
+            {
+                "result": 15,
+                "operation": "sum",
+                "count": 5
+            }
+            ```
+        """
+        ...