omnibase_infra 0.3.1__py3-none-any.whl → 0.4.0__py3-none-any.whl

omnibase_infra/nodes/node_contract_persistence_effect/registry/registry_infra_contract_persistence_effect.py

@@ -0,0 +1,251 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Registry for NodeContractPersistenceEffect infrastructure dependencies.
+
+This registry provides factory methods for creating NodeContractPersistenceEffect
+instances with their required dependencies resolved from the container.
+
+Following ONEX naming conventions:
+    - File: registry_infra_<node_name>.py
+    - Class: RegistryInfra<NodeName>
+
+The registry serves as the entry point for creating properly configured
+effect node instances, documenting required protocols, and providing
+node metadata for introspection.
+
+Related:
+    - contract.yaml: Node contract defining operations and dependencies
+    - node.py: Declarative node implementation
+    - handlers/: PostgreSQL operation handlers
+    - OMN-1845: Implementation ticket
+
+.. versionadded:: 0.5.0
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from omnibase_core.models.container.model_onex_container import ModelONEXContainer
+    from omnibase_infra.models.runtime.model_resolved_dependencies import (
+        ModelResolvedDependencies,
+    )
+    from omnibase_infra.nodes.node_contract_persistence_effect.node import (
+        NodeContractPersistenceEffect,
+    )
+
+
+class RegistryInfraContractPersistenceEffect:
+    """Infrastructure registry for NodeContractPersistenceEffect.
+
+    Provides dependency resolution and factory methods for creating
+    properly configured NodeContractPersistenceEffect instances.
+
+    This registry follows the ONEX infrastructure registry pattern:
+        - Factory method for node creation with container injection
+        - Protocol requirements documentation for container validation
+        - Node type classification for routing decisions
+        - Capability listing for service discovery
+
+    Example:
+        >>> from omnibase_core.models.container import ModelONEXContainer
+        >>> from omnibase_infra.nodes.node_contract_persistence_effect.registry import (
+        ...     RegistryInfraContractPersistenceEffect,
+        ... )
+        >>>
+        >>> # Create container with required protocols registered
+        >>> container = ModelONEXContainer()
+        >>> # ... register protocols ...
+        >>>
+        >>> # Create node instance via registry
+        >>> effect = RegistryInfraContractPersistenceEffect.create(container)
+
+    .. versionadded:: 0.5.0
+    """
+
+    @staticmethod
+    def create(
+        container: ModelONEXContainer,
+        dependencies: ModelResolvedDependencies | None = None,
+    ) -> NodeContractPersistenceEffect:
+        """Create a NodeContractPersistenceEffect instance with resolved dependencies.
+
+        Factory method that creates a fully configured NodeContractPersistenceEffect
+        using the provided ONEX container for dependency injection.
+
+        Args:
+            container: ONEX dependency injection container. Must have the
+                following protocols registered:
+                - ProtocolPostgresAdapter: PostgreSQL database operations
+                - ProtocolCircuitBreakerAware: Backend circuit breaker protection
+            dependencies: Optional pre-resolved protocol dependencies from
+                ContractDependencyResolver. If provided, the node uses these
+                instead of resolving from container. Part of OMN-1732 runtime
+                dependency injection.
+
+        Returns:
+            Configured NodeContractPersistenceEffect instance ready for operation.
+
+        Raises:
+            OnexError: If required protocols are not registered in container.
+
+        Example:
+            >>> container = ModelONEXContainer()
+            >>> container.register(ProtocolPostgresAdapter, postgres_adapter)
+            >>> effect = RegistryInfraContractPersistenceEffect.create(container)
+            >>>
+            >>> # With pre-resolved dependencies (OMN-1732)
+            >>> resolved = resolver.resolve(contract)
+            >>> effect = RegistryInfraContractPersistenceEffect.create(
+            ...     container, dependencies=resolved
+            ... )
+
+        .. versionadded:: 0.5.0
+        .. versionchanged:: 0.6.0
+            Added optional ``dependencies`` parameter for constructor injection (OMN-1732).
+        """
+        from omnibase_infra.nodes.node_contract_persistence_effect.node import (
+            NodeContractPersistenceEffect,
+        )
+
+        return NodeContractPersistenceEffect(container, dependencies=dependencies)
+
+    @staticmethod
+    def get_required_protocols() -> list[str]:
+        """Get list of protocols required by this node.
+
+        Returns the protocol class names that must be registered in the
+        container before creating a NodeContractPersistenceEffect instance.
+
+        .. deprecated:: 0.6.0
+            Use contract.yaml dependencies field instead. This method will be
+            removed in a future version. The contract is now the single source
+            of truth for protocol requirements (OMN-1732).
+
+        Returns:
+            List of protocol class names required for node operation.
+
+        Example:
+            >>> protocols = RegistryInfraContractPersistenceEffect.get_required_protocols()
+            >>> for proto in protocols:
+            ...     if not container.has(proto):
+            ...         raise ConfigurationError(f"Missing: {proto}")
+
+        .. versionadded:: 0.5.0
+        """
+        warnings.warn(
+            "get_required_protocols() is deprecated. Use contract.yaml dependencies "
+            "field instead. The contract is the single source of truth for protocol "
+            "requirements (OMN-1732).",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return [
+            "ProtocolPostgresAdapter",
+            "ProtocolCircuitBreakerAware",
+        ]
+
+    @staticmethod
+    def get_node_type() -> str:
+        """Get the node type classification.
+
+        Returns the ONEX node archetype for this node, used for
+        routing decisions and execution context selection.
+
+        Returns:
+            Node type string ("EFFECT").
+
+        Note:
+            EFFECT nodes perform external I/O operations and should
+            be treated as side-effecting by the runtime.
+
+        .. versionadded:: 0.5.0
+        """
+        return "EFFECT"
+
+    @staticmethod
+    def get_node_name() -> str:
+        """Get the canonical node name.
+
+        Returns:
+            The node name as defined in contract.yaml.
+
+        .. versionadded:: 0.5.0
+        """
+        return "node_contract_persistence_effect"
+
+    @staticmethod
+    def get_capabilities() -> list[str]:
+        """Get list of capabilities provided by this node.
+
+        Returns capability identifiers that can be used for service
+        discovery and feature detection.
+
+        Returns:
+            List of capability identifiers.
+
+        .. versionadded:: 0.5.0
+        """
+        return [
+            "contract_persistence",
+            "topic_routing",
+            "staleness_detection",
+            "heartbeat_tracking",
+            "soft_delete",
+            "circuit_breaker_protection",
+        ]
+
+    @staticmethod
+    def get_supported_operations() -> list[str]:
+        """Get list of operations supported by this node.
+
+        Returns:
+            List of operation identifiers as defined in contract.yaml.
+
+        .. versionadded:: 0.5.0
+        """
+        return [
+            "upsert_contract",
+            "update_topic",
+            "mark_stale",
+            "update_heartbeat",
+            "deactivate_contract",
+            "cleanup_topic_references",
+        ]
+
+    @staticmethod
+    def get_supported_intent_types() -> list[str]:
+        """Get list of intent types routed by this node.
+
+        Returns the payload.intent_type values that this effect node
+        can handle, matching ContractRegistryReducer output.
+
+        Returns:
+            List of intent type strings.
+
+        .. versionadded:: 0.5.0
+        """
+        return [
+            "postgres.upsert_contract",
+            "postgres.update_topic",
+            "postgres.mark_stale",
+            "postgres.update_heartbeat",
+            "postgres.deactivate_contract",
+            "postgres.cleanup_topic_references",
+        ]
+
+    @staticmethod
+    def get_backends() -> list[str]:
+        """Get list of backend types this node interacts with.
+
+        Returns:
+            List of backend identifiers.
+
+        .. versionadded:: 0.5.0
+        """
+        return ["postgres"]
+
+
+__all__ = ["RegistryInfraContractPersistenceEffect"]

omnibase_infra/nodes/node_registration_orchestrator/models/model_postgres_intent_payload.py

@@ -26,7 +26,7 @@ Thread Safety:
 Edge Case Behavior:
     The ``endpoints`` field validator explicitly handles the following cases:
     - ``None``: Raises ValueError (invalid input, not silently ignored)
-    - Empty Mapping ``{}``: Logs warning and converts to empty tuple
+    - Empty Mapping ``{}``: Raises ValueError (use default=() for no endpoints)
     - Invalid types (int, str, list, etc.): Raises ValueError
     - Tuple: Passed through as-is
     - Non-empty Mapping: Converted to tuple of (key, value) pairs
@@ -36,7 +36,6 @@ Edge Case Behavior:
 from __future__ import annotations
 
 import logging
-import warnings
 from collections.abc import Mapping
 from types import MappingProxyType
 from uuid import UUID
@@ -153,7 +152,7 @@ class ModelPostgresIntentPayload(BaseModel):
 
         Edge Cases:
             - ``None``: Raises ValueError (explicit rejection)
-            - Empty Mapping ``{}``: Logs warning, returns empty tuple
+            - Empty Mapping ``{}``: Raises ValueError (use default=() for no endpoints)
             - Empty tuple ``()``: Passed through (same as default)
             - Invalid types (list, int, str): Raises ValueError
             - Non-string keys/values: Raises ValueError (strict mode)
@@ -192,16 +191,13 @@ class ModelPostgresIntentPayload(BaseModel):
             return v  # type: ignore[return-value]  # NOTE: runtime type validated by Pydantic
         if isinstance(v, Mapping):
             if len(v) == 0:
-                # Log warning for empty Mapping to help detect potentially missing data.
-                # This is different from the default empty tuple - it's an explicit
-                # empty Mapping input that gets coerced.
-                warning_msg = (
-                    "Empty Mapping provided for endpoints, coercing to empty tuple. "
-                    "If this is intentional, consider using default=() instead."
+                # Explicit empty Mapping is rejected - use default=() instead.
+                # This prevents silent coercion that could mask invalid input.
+                raise ValueError(
+                    "Empty Mapping provided for endpoints. "
+                    "If no endpoints are needed, omit the field to use default=() "
+                    "rather than passing an explicit empty Mapping."
                 )
-                logger.warning(warning_msg)
-                warnings.warn(warning_msg, UserWarning, stacklevel=2)
-                return ()
             # Validate and convert to tuple - strict mode requires string keys/values
             result: list[tuple[str, str]] = []
             for key, val in v.items():

omnibase_infra/nodes/node_registry_effect/models/__init__.py

@@ -21,9 +21,9 @@ Related:
 
 from __future__ import annotations
 
-# Re-export shared effect models for convenience
+# Re-export shared models for convenience
+from omnibase_infra.models import ModelBackendResult
 from omnibase_infra.nodes.effects.models import (
-    ModelBackendResult,
     ModelEffectIdempotencyConfig,
     ModelRegistryRequest,
     ModelRegistryResponse,

omnibase_infra/nodes/node_slack_alerter_effect/__init__.py

@@ -0,0 +1,33 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Slack Alerter Effect Node - Declarative Slack webhook alerting.
+
+This module exports the declarative NodeSlackAlerterEffect for sending
+infrastructure alerts to Slack via webhooks.
+
+Architecture:
+    This node follows the ONEX declarative pattern:
+    - DECLARATIVE effect driven by contract.yaml
+    - Zero custom routing logic - all behavior from handler_routing
+    - Lightweight shell that delegates to HandlerSlackWebhook
+    - Pattern: "Contract-driven, handlers wired externally"
+
+Example:
+    >>> from omnibase_core.models.container import ModelONEXContainer
+    >>> from omnibase_infra.nodes.node_slack_alerter_effect import NodeSlackAlerterEffect
+    >>> from omnibase_infra.handlers import HandlerSlackWebhook
+    >>>
+    >>> container = ModelONEXContainer()
+    >>> node = NodeSlackAlerterEffect(container)
+    >>>
+    >>> # Handler receives dependencies via constructor
+    >>> handler = HandlerSlackWebhook()
+    >>> # result = await handler.handle(alert)
+
+Related Tickets:
+    - OMN-1905: Add declarative Slack webhook handler to omnibase_infra
+"""
+
+from omnibase_infra.nodes.node_slack_alerter_effect.node import NodeSlackAlerterEffect
+
+__all__ = ["NodeSlackAlerterEffect"]

omnibase_infra/nodes/node_slack_alerter_effect/contract.yaml

@@ -0,0 +1,291 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+#
+# ONEX Node Contract
+# Node: NodeSlackAlerterEffect
+#
+# This contract defines the interface for the Slack Alerter Effect node,
+# which sends infrastructure alerts to Slack via webhooks. The node uses
+# declarative operation routing to dispatch operations to the handler.
+#
+# Related Tickets:
+#   - OMN-1905: Add declarative Slack webhook handler to omnibase_infra
+# Contract identifiers
+name: "node_slack_alerter_effect"
+contract_name: "node_slack_alerter_effect"
+node_name: "node_slack_alerter_effect"
+contract_version:
+  major: 1
+  minor: 0
+  patch: 0
+node_version:
+  major: 1
+  minor: 0
+  patch: 0
+# Node type
+node_type: "EFFECT_GENERIC"
+# Description
+description: >
+  Effect node for Slack webhook alerting. Sends infrastructure alerts to Slack channels using incoming webhooks with Block Kit formatting, retry with exponential backoff, and rate limit handling. Uses declarative operation routing to dispatch to the HandlerSlackWebhook.
+
+# Strongly typed I/O models
+input_model:
+  name: "ModelSlackAlert"
+  module: "omnibase_infra.handlers.models.model_slack_alert"
+  description: "Input model containing alert severity, message, and optional details."
+output_model:
+  name: "ModelSlackAlertResult"
+  module: "omnibase_infra.handlers.models.model_slack_alert"
+  description: "Output model containing delivery status, timing, and error information."
+# =============================================================================
+# HANDLER ROUTING (Declarative Handler Dispatch)
+# =============================================================================
+# This section defines how operations are routed to the Slack webhook handler.
+# The routing strategy determines handler selection based on operation type.
+#
+# Design Rationale:
+#   - Single handler for all Slack operations
+#   - Block Kit formatting for rich messages
+#   - Retry with exponential backoff for resilience
+#   - Rate limit handling for graceful degradation
+#
+# Execution Flow:
+#   1. Receive ModelSlackAlert with operation type
+#   2. Route to HandlerSlackWebhook based on operation
+#   3. Execute webhook delivery with retry logic
+#   4. Return ModelSlackAlertResult with delivery status
+# =============================================================================
+handler_routing:
+  routing_strategy: "operation_match"
+  handlers:
+    # Send Alert - Formatted Block Kit message
+    # Sends a rich formatted alert with severity, message, and details.
+    - operation: "send_alert"
+      handler:
+        name: "HandlerSlackWebhook"
+        module: "omnibase_infra.handlers.handler_slack_webhook"
+      description: "Send formatted alert to Slack with Block Kit formatting"
+      output_fields:
+        - success
+        - duration_ms
+        - retry_count
+    # Send Message - Plain text message
+    # Sends a simple text message (uses same handler, alert formatting applied)
+    - operation: "send_message"
+      handler:
+        name: "HandlerSlackWebhook"
+        module: "omnibase_infra.handlers.handler_slack_webhook"
+      description: "Send message to Slack channel"
+      output_fields:
+        - success
+        - duration_ms
+        - retry_count
+# =============================================================================
+# ERROR HANDLING (Retry + Rate Limiting)
+# =============================================================================
+# Error handling configuration for Slack webhook operations.
+# Uses retry with exponential backoff and handles rate limiting gracefully.
+#
+# Note: The handler implements its own retry logic internally rather than
+# relying on external retry orchestration. This ensures consistent behavior
+# and proper rate limit handling.
+# =============================================================================
+error_handling:
+  # Retry policy with exponential backoff
+  retry_policy:
+    max_retries: 3
+    initial_delay_ms: 1000
+    max_delay_ms: 4000
+    exponential_base: 2
+    retry_on:
+      - "SLACK_RATE_LIMITED"
+      - "SLACK_TIMEOUT"
+      - "SLACK_CONNECTION_ERROR"
+      - "SLACK_CLIENT_ERROR"
+  # Error type definitions
+  error_types:
+    - name: "SLACK_NOT_CONFIGURED"
+      description: "SLACK_WEBHOOK_URL environment variable not set"
+      recoverable: false
+      retry_strategy: "none"
+    - name: "SLACK_RATE_LIMITED"
+      description: "Slack returned HTTP 429 rate limit"
+      recoverable: true
+      retry_strategy: "exponential_backoff"
+    - name: "SLACK_TIMEOUT"
+      description: "Webhook request timed out"
+      recoverable: true
+      retry_strategy: "exponential_backoff"
+    - name: "SLACK_CONNECTION_ERROR"
+      description: "Failed to connect to Slack webhook"
+      recoverable: true
+      retry_strategy: "exponential_backoff"
+    - name: "SLACK_CLIENT_ERROR"
+      description: "HTTP client error during request"
+      recoverable: true
+      retry_strategy: "exponential_backoff"
+    - name: "SLACK_HTTP_4XX"
+      description: "Slack returned HTTP 4xx error (non-429)"
+      recoverable: false
+      retry_strategy: "none"
+    - name: "SLACK_HTTP_5XX"
+      description: "Slack returned HTTP 5xx error"
+      recoverable: true
+      retry_strategy: "exponential_backoff"
+# IO operations (EFFECT node specific)
+io_operations:
+  - operation: "send_alert"
+    description: "Send a formatted alert to Slack with Block Kit formatting"
+    input_fields:
+      - severity
+      - message
+      - title
+      - details
+      - channel
+      - correlation_id
+    output_fields:
+      - success
+      - duration_ms
+      - correlation_id
+      - error
+      - error_code
+      - retry_count
+  - operation: "send_message"
+    description: "Send a plain text message to Slack"
+    input_fields:
+      - message
+      - channel
+      - correlation_id
+    output_fields:
+      - success
+      - duration_ms
+      - correlation_id
+      - error
+      - error_code
+      - retry_count
+# Dependencies (protocols this node requires)
+dependencies:
+  - name: "http_client"
+    type: "library"
+    library: "aiohttp"
+    description: "Async HTTP client for webhook requests"
+  - name: "slack_webhook_url"
+    type: "environment"
+    env_var: "SLACK_WEBHOOK_URL"
+    description: "Slack incoming webhook URL"
+    required: true
+# Capabilities provided by this node
+capabilities:
+  - name: "slack_alerting"
+    description: "Send infrastructure alerts to Slack channels"
+  - name: "block_kit_formatting"
+    description: "Format messages using Slack Block Kit for rich display"
+  - name: "retry_with_backoff"
+    description: "Retry failed requests with exponential backoff"
+  - name: "rate_limit_handling"
+    description: "Handle Slack rate limiting gracefully"
+# Model definitions
+definitions:
+  ModelSlackAlert:
+    type: object
+    description: "Input payload for Slack alert operations"
+    frozen: true
+    extra: "forbid"
+    properties:
+      severity:
+        type: enum
+        enum_class: "EnumAlertSeverity"
+        module: "omnibase_infra.handlers.models.model_slack_alert"
+        description: "Alert severity level for visual formatting"
+        default: "info"
+        enum:
+          - "critical"
+          - "error"
+          - "warning"
+          - "info"
+      message:
+        type: string
+        description: "Main alert message content"
+        min_length: 1
+        max_length: 3000
+      title:
+        type: string
+        nullable: true
+        default: null
+        max_length: 150
+        description: "Optional alert title"
+      details:
+        type: object
+        key_type: string
+        value_type: any
+        description: "Additional key-value details"
+        default_factory: "dict"
+      channel:
+        type: string
+        nullable: true
+        default: null
+        description: "Optional channel override"
+      correlation_id:
+        type: uuid
+        description: "UUID for distributed tracing"
+        default_factory: "uuid4"
+    required:
+      - message
+  ModelSlackAlertResult:
+    type: object
+    description: "Response from Slack webhook operations"
+    frozen: true
+    extra: "forbid"
+    properties:
+      success:
+        type: boolean
+        description: "Whether the alert was delivered successfully"
+      duration_ms:
+        type: float
+        description: "Time taken for the operation in milliseconds"
+        default: 0.0
+        ge: 0.0
+      correlation_id:
+        type: uuid
+        description: "UUID from the original request"
+      error:
+        type: string
+        nullable: true
+        default: null
+        description: "Sanitized error message if success is False"
+      error_code:
+        type: string
+        nullable: true
+        default: null
+        description: "Error code for programmatic handling"
+      retry_count:
+        type: integer
+        description: "Number of retry attempts made"
+        default: 0
+        ge: 0
+    required:
+      - success
+      - correlation_id
+# Health check configuration
+health_check:
+  enabled: true
+  endpoint: "/health"
+  interval_seconds: 30
+  checks:
+    - name: "webhook_configured"
+      check_type: "environment"
+      env_var: "SLACK_WEBHOOK_URL"
+      description: "Verify SLACK_WEBHOOK_URL is configured"
+# Metadata
+metadata:
+  author: "OmniNode Team"
+  license: "MIT"
+  created: "2026-02-04"
+  updated: "2026-02-04"
+  tags:
+    - effect
+    - slack
+    - alerting
+    - webhook
+    - infrastructure
+    - block-kit