omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/types/typed_dict/__init__.py

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""TypedDict definitions for omnibase_infra.
+
+This package contains TypedDict definitions that represent JSON-serialized
+forms of Pydantic models, enabling proper type checking for cache operations
+and JSON serialization/deserialization without requiring type: ignore comments.
+
+Available TypedDicts:
+    - TypedDictEnvelopeBuildParams: Parameters for building ModelEventEnvelope
+    - TypedDictIntrospectionCache: JSON-serialized ModelNodeIntrospectionEvent
+    - TypedDictPerformanceMetricsCache: JSON-serialized introspection performance metrics
+"""
+
+from omnibase_infra.types.typed_dict.typed_dict_envelope_build_params import (
+    TypedDictEnvelopeBuildParams,
+)
+from omnibase_infra.types.typed_dict.typed_dict_introspection_cache import (
+    TypedDictIntrospectionCache,
+)
+from omnibase_infra.types.typed_dict.typed_dict_performance_metrics_cache import (
+    TypedDictPerformanceMetricsCache,
+)
+
+__all__ = [
+    "TypedDictEnvelopeBuildParams",
+    "TypedDictIntrospectionCache",
+    "TypedDictPerformanceMetricsCache",
+]

omnibase_infra/types/typed_dict/typed_dict_envelope_build_params.py

@@ -0,0 +1,115 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""TypedDict definition for envelope build parameters.
+
+This module provides a TypedDict that represents the parameters passed to the
+_build_envelope method in AdapterProtocolEventPublisherInmemory, replacing the
+loose dict[str, object] typing with proper type safety.
+
+The TypedDictEnvelopeBuildParams ensures type-checked access to envelope
+construction parameters without requiring type: ignore comments or unsafe casts.
+
+Key Features:
+    - Full type annotations for all envelope build parameters
+    - Proper handling of nullable fields (correlation_id, causation_id, metadata)
+    - Integration with JsonType for payload typing
+    - Uses TYPE_CHECKING import for ContextValue to avoid circular imports
+
+Usage:
+    This TypedDict is primarily used for:
+    - Type-safe parameter passing to envelope builder methods
+    - Eliminating dict[str, object] loose typing
+    - Enabling mypy verification of parameter access
+
+Example:
+    ```python
+    from omnibase_infra.types.typed_dict import TypedDictEnvelopeBuildParams
+
+    def build_envelope(params: TypedDictEnvelopeBuildParams) -> ModelEventEnvelope:
+        # Type-safe access to all fields
+        event_type = params["event_type"]
+        payload = params["payload"]
+        correlation_id = params.get("correlation_id")
+        return ...
+    ```
+
+See Also:
+    - AdapterProtocolEventPublisherInmemory: Primary consumer of this TypedDict
+    - ModelEventEnvelope: Target envelope model constructed from these params
+    - ProtocolEventPublisher: SPI protocol defining publish interface
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, NotRequired, TypedDict
+
+from omnibase_core.types import JsonType
+
+if TYPE_CHECKING:
+    from omnibase_spi.protocols.types.protocol_core_types import ContextValue
+
+__all__ = ["TypedDictEnvelopeBuildParams"]
+
+
+class TypedDictEnvelopeBuildParams(TypedDict):
+    """TypedDict representing parameters for building a ModelEventEnvelope.
+
+    This type provides a type-safe alternative to dict[str, object] for passing
+    envelope construction parameters. It enables proper type checking when
+    building event envelopes in publisher adapters.
+
+    Required fields (event_type, payload) are enforced by TypedDict's default
+    total=True behavior. Optional fields use NotRequired[] to allow omission
+    while maintaining type safety.
+
+    Attributes:
+        event_type: Fully-qualified event type identifier
+            (e.g., "omninode.user.event.created.v1"). Required field - must
+            always be provided when constructing the TypedDict.
+        payload: Event payload data as JSON-compatible types. Required field -
+            must always be provided. Can be dict, list, str, int, float, bool,
+            or None.
+        correlation_id: Optional correlation ID for request tracing.
+            Used to link related events across service boundaries.
+            May be omitted or set to None.
+        causation_id: Optional causation ID for event sourcing chains.
+            Links this event to the event that caused it.
+            May be omitted or set to None.
+        metadata: Optional additional context values for the envelope.
+            Keys are string identifiers, values are ContextValue protocol
+            implementations (e.g., ProtocolContextStringValue).
+            May be omitted or set to None.
+
+    Note:
+        The metadata field uses ContextValue from omnibase_spi which is imported
+        under TYPE_CHECKING to avoid runtime circular import issues. At runtime,
+        the dict values are duck-typed protocol implementations.
+
+    Example:
+        ```python
+        # Minimal valid TypedDict (only required fields)
+        params: TypedDictEnvelopeBuildParams = {
+            "event_type": "user.created.v1",
+            "payload": {"user_id": "123", "email": "user@example.com"},
+        }
+
+        # Full TypedDict with all fields
+        params_full: TypedDictEnvelopeBuildParams = {
+            "event_type": "user.created.v1",
+            "payload": {"user_id": "123", "email": "user@example.com"},
+            "correlation_id": "corr-abc-123",
+            "causation_id": None,
+            "metadata": {"trace_id": trace_value},
+        }
+
+        # Safe field access
+        event_type: str = params["event_type"]  # Always present
+        correlation_id: str | None = params.get("correlation_id")  # May be absent
+        ```
+    """
+
+    event_type: str
+    payload: JsonType
+    correlation_id: NotRequired[str | None]
+    causation_id: NotRequired[str | None]
+    metadata: NotRequired[dict[str, ContextValue] | None]

omnibase_infra/types/typed_dict/typed_dict_introspection_cache.py

@@ -0,0 +1,128 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""TypedDict definition for JSON-serialized introspection cache data.
+
+This module provides a TypedDict that represents the JSON-serialized form of
+ModelNodeIntrospectionEvent, enabling proper type checking for cache operations
+without requiring type: ignore comments.
+
+The TypedDictIntrospectionCache matches the output of
+ModelNodeIntrospectionEvent.model_dump(mode="json"), providing a typed interface
+for working with cached introspection data.
+
+Key Features:
+    - Full type annotations for all introspection event fields
+    - Proper handling of serialized datetime (ISO string format)
+    - Proper handling of serialized UUID (string format)
+    - Integration with TypedDictCapabilities for nested capabilities structure
+    - Integration with TypedDictPerformanceMetricsCache for performance metrics
+
+Usage:
+    This TypedDict is primarily used for:
+    - Typing cache storage for introspection data
+    - Type-safe JSON deserialization of introspection events
+    - Avoiding type: ignore comments in cache operations
+
+Example:
+    ```python
+    from omnibase_infra.types.typed_dict import TypedDictIntrospectionCache
+
+    # Cache storage with proper typing
+    cache: TypedDictIntrospectionCache | None = None
+
+    def store_introspection(event: ModelNodeIntrospectionEvent) -> None:
+        global cache
+        # model_dump(mode="json") returns data matching TypedDictIntrospectionCache
+        cache = event.model_dump(mode="json")
+
+    def get_cached_node_id() -> str | None:
+        if cache is not None:
+            return cache["node_id"]  # Type-safe access
+        return None
+    ```
+
+See Also:
+    - TypedDictCapabilities: Nested structure for capability information
+    - TypedDictPerformanceMetricsCache: Nested structure for performance metrics
+    - ModelNodeIntrospectionEvent: Source Pydantic model for introspection events
+    - MixinNodeIntrospection: Primary consumer of this TypedDict
+"""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+from omnibase_infra.types.typed_dict.typed_dict_performance_metrics_cache import (
+    TypedDictPerformanceMetricsCache,
+)
+from omnibase_infra.types.typed_dict_capabilities import TypedDictCapabilities
+
+__all__ = ["TypedDictIntrospectionCache"]
+
+
+class TypedDictIntrospectionCache(TypedDict):
+    """TypedDict representing the JSON-serialized ModelNodeIntrospectionEvent.
+
+    This type matches the output of ModelNodeIntrospectionEvent.model_dump(mode="json"),
+    enabling proper type checking for cache operations without requiring type: ignore
+    comments.
+
+    The TypedDict provides a typed interface for working with introspection cache data,
+    ensuring type safety when accessing fields from cached introspection events.
+
+    Attributes:
+        node_id: Unique identifier for the node (UUID serialized to string).
+        node_type: The type classification of the node (e.g., "EFFECT", "COMPUTE").
+        capabilities: Nested structure containing node capabilities information.
+            Uses TypedDictCapabilities which includes operations, protocols,
+            has_fsm flag, and method_signatures.
+        endpoints: Dictionary mapping endpoint names to their URLs.
+            Common keys include "health", "api", and "metrics".
+        current_state: Current FSM state if applicable, None otherwise.
+            Represents the node's finite state machine state.
+        version: Semantic version string of the node.
+        reason: The reason for the introspection event (e.g., "startup", "shutdown",
+            "heartbeat", "request").
+        correlation_id: Optional correlation ID for request tracing.
+            UUID serializes to string in JSON mode, may be None.
+        timestamp: ISO 8601 formatted datetime string indicating when the
+            introspection event was created.
+        performance_metrics: Optional performance metrics from the introspection
+            operation. Contains timing information for capability discovery,
+            endpoint gathering, and state retrieval. May be None if metrics
+            were not captured.
+
+    Note:
+        The capabilities field uses TypedDictCapabilities for type safety.
+        When serialized to JSON, the structure is:
+        - operations (list[str]): Discovered operation method names
+        - protocols (list[str]): Implemented protocol names
+        - has_fsm (bool): Whether the node has FSM capabilities
+        - method_signatures (dict[str, str]): Method name to signature mapping
+
+    Example:
+        ```python
+        # Type-safe cache access
+        cache: TypedDictIntrospectionCache = event.model_dump(mode="json")
+
+        # All field access is type-checked
+        node_id: str = cache["node_id"]
+        capabilities: TypedDictCapabilities = cache["capabilities"]
+        operations: list[str] = capabilities["operations"]
+
+        # Nullable fields properly typed
+        state: str | None = cache["current_state"]
+        metrics: TypedDictPerformanceMetricsCache | None = cache["performance_metrics"]
+        ```
+    """
+
+    node_id: str
+    node_type: str
+    capabilities: TypedDictCapabilities
+    endpoints: dict[str, str]
+    current_state: str | None
+    version: str
+    reason: str
+    correlation_id: str | None  # UUID serializes to string in JSON mode
+    timestamp: str  # datetime serializes to ISO string in JSON mode
+    performance_metrics: TypedDictPerformanceMetricsCache | None

omnibase_infra/types/typed_dict/typed_dict_performance_metrics_cache.py

@@ -0,0 +1,140 @@
+# Copyright 2025 OmniNode Team. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""TypedDict for JSON-serialized performance metrics cache.
+
+This module provides a TypedDict that matches the JSON output of
+ModelIntrospectionPerformanceMetrics.model_dump(mode="json"), enabling
+proper type checking for cached performance metrics without runtime
+validation overhead.
+
+The TypedDict is used for:
+- Type-safe cache operations for performance metrics
+- Avoiding type: ignore comments when working with serialized metrics
+- Static type checking of JSON-structured performance data
+- Documentation of the expected cache entry shape
+
+Related Models:
+    - ModelIntrospectionPerformanceMetrics: The Pydantic source model
+    - MixinNodeIntrospection: Uses this for caching introspection metrics
+
+Example:
+    ```python
+    from omnibase_infra.types.typed_dict import TypedDictPerformanceMetricsCache
+
+    def get_cached_metrics() -> TypedDictPerformanceMetricsCache | None:
+        cache_entry = cache.get("metrics")
+        if cache_entry is not None:
+            # Type checker knows the shape without runtime validation
+            return cache_entry
+        return None
+
+    metrics = get_cached_metrics()
+    if metrics:
+        print(f"Total time: {metrics['total_introspection_ms']}ms")
+        if metrics.get('threshold_exceeded'):
+            print(f"Slow ops: {metrics.get('slow_operations', [])}")
+    ```
+
+Note:
+    This TypedDict uses `total=True` (default) because the source Pydantic
+    model `ModelIntrospectionPerformanceMetrics` has defaults for all fields,
+    ensuring that `model_dump(mode="json")` always produces complete JSON
+    with all fields present. Type checkers will require all fields when
+    constructing dict literals, which matches the actual runtime behavior.
+"""
+
+from typing import TypedDict
+
+
+class TypedDictPerformanceMetricsCache(TypedDict):
+    """TypedDict for JSON-serialized ModelIntrospectionPerformanceMetrics.
+
+    This type matches the output of ModelIntrospectionPerformanceMetrics.model_dump(mode="json"),
+    enabling proper type checking for cached performance metrics.
+
+    All fields are required (total=True, the default) because the source Pydantic
+    model has defaults for all fields, ensuring model_dump() always produces
+    complete JSON output with all fields present.
+
+    Attributes:
+        get_capabilities_ms: Time taken by get_capabilities() in milliseconds.
+            Threshold: <50ms for acceptable performance.
+        discover_capabilities_ms: Time taken by _discover_capabilities() in milliseconds.
+            Threshold: <30ms for acceptable performance.
+        get_endpoints_ms: Time taken by get_endpoints() in milliseconds.
+            This operation is typically fast (<1ms) as it returns static data.
+        get_current_state_ms: Time taken by get_current_state() in milliseconds.
+            This operation is typically fast (<1ms) for simple state retrieval.
+        total_introspection_ms: Total time for get_introspection_data() in milliseconds.
+            Threshold: <50ms for acceptable performance.
+        cache_hit: Whether the result was served from cache.
+            Cache hits should complete in <1ms.
+        method_count: Number of methods discovered during reflection.
+            Higher counts may correlate with longer discover_capabilities_ms times.
+        threshold_exceeded: Whether any operation exceeded performance thresholds.
+            True indicates potential performance degradation.
+        slow_operations: List of operation names that exceeded their thresholds.
+            Possible values: 'get_capabilities', 'discover_capabilities',
+            'total_introspection', 'cache_hit'.
+        captured_at: UTC timestamp when metrics were captured (ISO 8601 string).
+            Datetime serializes to ISO string format in JSON mode.
+
+    Example:
+        ```python
+        from omnibase_infra.types.typed_dict import TypedDictPerformanceMetricsCache
+
+        # Type-safe cache dictionary
+        cache: dict[str, TypedDictPerformanceMetricsCache] = {}
+
+        # Store metrics
+        cache["node-123"] = {
+            "get_capabilities_ms": 12.5,
+            "discover_capabilities_ms": 8.2,
+            "get_endpoints_ms": 0.5,
+            "get_current_state_ms": 0.1,
+            "total_introspection_ms": 21.3,
+            "cache_hit": False,
+            "method_count": 15,
+            "threshold_exceeded": False,
+            "slow_operations": [],
+            "captured_at": "2025-01-15T10:30:00Z",
+        }
+
+        # Retrieve with full type safety
+        if entry := cache.get("node-123"):
+            total_ms = entry.get("total_introspection_ms", 0.0)
+            if entry.get("threshold_exceeded"):
+                slow_ops = entry.get("slow_operations", [])
+                print(f"Performance degradation: {slow_ops}")
+        ```
+
+    Performance Thresholds:
+        The following thresholds are defined as module-level constants in:
+        src/omnibase_infra/mixins/mixin_node_introspection.py
+
+        Constants (SOURCE OF TRUTH - update this docstring if values change):
+        - PERF_THRESHOLD_GET_CAPABILITIES_MS: 50.0ms
+        - PERF_THRESHOLD_DISCOVER_CAPABILITIES_MS: 30.0ms
+        - PERF_THRESHOLD_GET_INTROSPECTION_DATA_MS: 50.0ms
+        - PERF_THRESHOLD_CACHE_HIT_MS: 1.0ms
+
+        Summary:
+        - get_capabilities: <50ms
+        - discover_capabilities: <30ms
+        - total_introspection: <50ms
+        - cache_hit: <1ms
+    """
+
+    get_capabilities_ms: float
+    discover_capabilities_ms: float
+    get_endpoints_ms: float
+    get_current_state_ms: float
+    total_introspection_ms: float
+    cache_hit: bool
+    method_count: int
+    threshold_exceeded: bool
+    slow_operations: list[str]
+    captured_at: str  # datetime serializes to ISO string in JSON mode
+
+
+__all__ = ["TypedDictPerformanceMetricsCache"]

omnibase_infra/types/typed_dict_capabilities.py

@@ -0,0 +1,64 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""TypedDict for node capability structures discovered via reflection.
+
+This module provides a strongly-typed structure for representing node
+capabilities discovered during introspection. Using TypedDict instead of
+generic dict types enables static type checking and IDE support while
+maintaining runtime dict compatibility.
+
+The TypedDictCapabilities structure is used by the MixinNodeIntrospection
+mixin to report discovered capabilities in a type-safe manner, eliminating
+the need for permissive `dict[str, object]` or `Any` types.
+
+Example:
+    >>> from omnibase_infra.types.typed_dict_capabilities import TypedDictCapabilities
+    >>> caps: TypedDictCapabilities = {
+    ...     "operations": ["execute", "query"],
+    ...     "protocols": ["ProtocolDatabaseAdapter"],
+    ...     "has_fsm": False,
+    ...     "method_signatures": {"execute": "(query: str) -> list[dict]"},
+    ... }
+"""
+
+from typing import TypedDict
+
+__all__ = ["TypedDictCapabilities"]
+
+
+class TypedDictCapabilities(TypedDict, total=True):
+    """Type-safe structure for node capabilities discovered via reflection.
+
+    This TypedDict provides explicit typing for capability fields, eliminating
+    the need for permissive `dict[str, object]` or `Any` types.
+
+    All fields are required (total=True is explicitly set). The MixinNodeIntrospection
+    mixin always constructs complete capability dicts with all fields populated.
+
+    Attributes:
+        operations: List of public method names that may be operations.
+            These are methods matching configured operation keywords
+            (e.g., execute, handle, process).
+        protocols: List of protocol/interface names implemented by the node.
+            Discovered from class hierarchy (e.g., ProtocolDatabaseAdapter).
+        has_fsm: Boolean indicating if node has FSM state management.
+            True if state attributes like _state or current_state are found.
+        method_signatures: Dict mapping public method names to their signature
+            strings (e.g., {"execute": "(query: str) -> list[dict]"}).
+
+    Example:
+        >>> capabilities: TypedDictCapabilities = {
+        ...     "operations": ["execute", "query", "batch_execute"],
+        ...     "protocols": ["ProtocolDatabaseAdapter", "MixinNodeIntrospection"],
+        ...     "has_fsm": True,
+        ...     "method_signatures": {
+        ...         "execute": "(query: str) -> list[dict]",
+        ...         "query": "(sql: str, params: dict) -> list[dict]",
+        ...     },
+        ... }
+    """
+
+    operations: list[str]
+    protocols: list[str]
+    has_fsm: bool
+    method_signatures: dict[str, str]

omnibase_infra/utils/__init__.py

@@ -0,0 +1,117 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Utility modules for ONEX infrastructure.
+
+This package provides common utilities used across the infrastructure:
+    - correlation: Correlation ID generation and propagation for distributed tracing
+    - util_atomic_file: Atomic file write primitives using temp-file-rename pattern
+    - util_consumer_group: Kafka consumer group ID generation with deterministic hashing
+    - util_datetime: Datetime validation and timezone normalization
+    - util_db_transaction: Database transaction context manager for asyncpg
+    - util_dsn_validation: PostgreSQL DSN validation and sanitization
+    - util_env_parsing: Type-safe environment variable parsing with validation
+    - util_error_sanitization: Error message sanitization for secure logging and DLQ
+    - util_pydantic_validators: Shared Pydantic field validator utilities
+    - util_retry_optimistic: Optimistic locking retry helper with exponential backoff
+    - util_semver: Semantic versioning validation utilities
+"""
+
+from omnibase_infra.utils.correlation import (
+    CorrelationContext,
+    clear_correlation_id,
+    generate_correlation_id,
+    get_correlation_id,
+    set_correlation_id,
+)
+from omnibase_infra.utils.util_atomic_file import (
+    write_atomic_bytes,
+    write_atomic_bytes_async,
+)
+from omnibase_infra.utils.util_consumer_group import (
+    KAFKA_CONSUMER_GROUP_MAX_LENGTH,
+    compute_consumer_group_id,
+    normalize_kafka_identifier,
+)
+from omnibase_infra.utils.util_datetime import (
+    ensure_timezone_aware,
+    is_timezone_aware,
+    validate_timezone_aware_with_context,
+    warn_if_naive_datetime,
+)
+from omnibase_infra.utils.util_db_transaction import (
+    transaction_context,
+)
+from omnibase_infra.utils.util_dsn_validation import (
+    parse_and_validate_dsn,
+    sanitize_dsn,
+)
+from omnibase_infra.utils.util_env_parsing import (
+    parse_env_float,
+    parse_env_int,
+)
+from omnibase_infra.utils.util_error_sanitization import (
+    SAFE_ERROR_PATTERNS,
+    SENSITIVE_PATTERNS,
+    sanitize_backend_error,
+    sanitize_consul_key,
+    sanitize_error_message,
+    sanitize_error_string,
+    sanitize_secret_path,
+)
+from omnibase_infra.utils.util_pydantic_validators import (
+    validate_contract_type_value,
+    validate_endpoint_urls_dict,
+    validate_policy_type_value,
+    validate_pool_sizes_constraint,
+    validate_timezone_aware_datetime,
+    validate_timezone_aware_datetime_optional,
+)
+from omnibase_infra.utils.util_retry_optimistic import (
+    OptimisticConflictError,
+    retry_on_optimistic_conflict,
+)
+from omnibase_infra.utils.util_semver import (
+    SEMVER_PATTERN,
+    validate_semver,
+    validate_version_lenient,
+)
+
+__all__: list[str] = [
+    "CorrelationContext",
+    "KAFKA_CONSUMER_GROUP_MAX_LENGTH",
+    "OptimisticConflictError",
+    "SAFE_ERROR_PATTERNS",
+    "SEMVER_PATTERN",
+    "SENSITIVE_PATTERNS",
+    "clear_correlation_id",
+    "compute_consumer_group_id",
+    "ensure_timezone_aware",
+    "generate_correlation_id",
+    "get_correlation_id",
+    "is_timezone_aware",
+    "normalize_kafka_identifier",
+    "parse_and_validate_dsn",
+    "parse_env_float",
+    "parse_env_int",
+    "retry_on_optimistic_conflict",
+    "sanitize_backend_error",
+    "sanitize_consul_key",
+    "sanitize_dsn",
+    "sanitize_error_message",
+    "sanitize_error_string",
+    "sanitize_secret_path",
+    "set_correlation_id",
+    "transaction_context",
+    "validate_contract_type_value",
+    "validate_endpoint_urls_dict",
+    "validate_policy_type_value",
+    "validate_pool_sizes_constraint",
+    "validate_semver",
+    "validate_timezone_aware_datetime",
+    "validate_timezone_aware_datetime_optional",
+    "validate_timezone_aware_with_context",
+    "validate_version_lenient",
+    "warn_if_naive_datetime",
+    "write_atomic_bytes",
+    "write_atomic_bytes_async",
+]