omnibase_infra 0.2.1__py3-none-any.whl → 0.2.2__py3-none-any.whl

omnibase_infra/handlers/mixins/mixin_consul_kv.py

@@ -94,7 +94,7 @@ class MixinConsulKV:
         correlation_id: UUID,
     ) -> T:
         """Execute operation with retry logic - provided by host class."""
-        raise NotImplementedError("Must be provided by implementing class")
+        raise NotImplementedError("Must be provided by implementing class")  # type: ignore[return-value]
 
     def _build_response(
         self,
@@ -103,6 +103,7 @@ class MixinConsulKV:
         input_envelope_id: UUID,
     ) -> ModelHandlerOutput[ModelConsulHandlerResponse]:
         """Build standardized response - provided by host class."""
+        raise NotImplementedError("Must be provided by implementing class")  # type: ignore[return-value]
 
     async def _kv_get(
         self,
@@ -176,7 +177,7 @@ class MixinConsulKV:
             get_func,
             correlation_id,
         )
-        index, data = cast(KVGetResult, result)
+        index, data = cast("KVGetResult", result)
 
         # Handle response - data can be None if key doesn't exist
         if data is None:
@@ -325,7 +326,7 @@ class MixinConsulKV:
             put_func,
             correlation_id,
         )
-        success = cast(bool, result)
+        success = cast("bool", result)
 
         typed_payload = ModelConsulKVPutPayload(
             success=success,

omnibase_infra/handlers/mixins/mixin_consul_service.py

@@ -91,7 +91,7 @@ class MixinConsulService:
         correlation_id: UUID,
     ) -> T:
         """Execute operation with retry logic - provided by host class."""
-        raise NotImplementedError("Must be provided by implementing class")
+        raise NotImplementedError("Must be provided by implementing class")  # type: ignore[return-value]
 
     def _build_response(
         self,
@@ -100,6 +100,7 @@ class MixinConsulService:
         input_envelope_id: UUID,
     ) -> ModelHandlerOutput[ModelConsulHandlerResponse]:
         """Build standardized response - provided by host class."""
+        raise NotImplementedError("Must be provided by implementing class")  # type: ignore[return-value]
 
     async def _register_service(
         self,

omnibase_infra/handlers/service_discovery/handler_service_discovery_consul.py

@@ -567,15 +567,15 @@ class HandlerServiceDiscoveryConsul(MixinAsyncCircuitBreaker):
             service_infos: list[ModelServiceInfo] = []
             for svc in services:
                 # Cast nested dicts for type safety
-                svc_data = cast(dict[str, object], svc.get("Service", {}))
-                node_data = cast(dict[str, object], svc.get("Node", {}))
+                svc_data = cast("dict[str, object]", svc.get("Service", {}))
+                node_data = cast("dict[str, object]", svc.get("Node", {}))
                 svc_id_str = str(svc_data.get("ID", ""))
                 svc_name = svc_data.get("Service", "")
                 address = svc_data.get("Address", "") or node_data.get("Address", "")
                 port_raw = svc_data.get("Port", 0)
                 port = int(port_raw) if isinstance(port_raw, int | float | str) else 0
-                svc_tags = cast(list[str], svc_data.get("Tags", []))
-                svc_meta = cast(dict[str, str], svc_data.get("Meta", {}))
+                svc_tags = cast("list[str]", svc_data.get("Tags", []))
+                svc_meta = cast("dict[str, str]", svc_data.get("Meta", {}))
 
                 if svc_id_str and svc_name and address and port:
                     # Convert Consul service ID string to UUID
@@ -664,6 +664,303 @@ class HandlerServiceDiscoveryConsul(MixinAsyncCircuitBreaker):
                 context=context,
             ) from e
 
+    async def list_all_services(
+        self,
+        tag_filter: str | None = None,
+        correlation_id: UUID | None = None,
+    ) -> dict[str, list[str]]:
+        """List all registered service names with their tags.
+
+        Uses Consul catalog API (/v1/catalog/services) to retrieve all
+        service names registered in the Consul catalog, along with their tags.
+
+        Args:
+            tag_filter: Optional tag to filter services by. If provided,
+                only services with this tag will be returned.
+            correlation_id: Optional correlation ID for tracing.
+
+        Returns:
+            Dictionary mapping service names to their list of tags.
+            Example: {"my-service": ["web", "api"], "other-service": ["db"]}
+
+        Raises:
+            InfraConnectionError: If connection to Consul fails.
+            InfraTimeoutError: If operation times out.
+            InfraUnavailableError: If circuit breaker is open.
+        """
+        correlation_id = correlation_id or uuid4()
+        start_time = time.monotonic()
+
+        # Guard against use-after-shutdown
+        self._check_not_shutdown("list_all_services", correlation_id)
+
+        # Check circuit breaker
+        async with self._circuit_breaker_lock:
+            await self._check_circuit_breaker(
+                operation="list_all_services",
+                correlation_id=correlation_id,
+            )
+
+        try:
+            # Query Consul catalog for all services
+            client = self._consul_client
+            executor = await self._ensure_executor()
+            loop = asyncio.get_running_loop()
+
+            def _query_catalog() -> tuple[int, dict[str, list[str]]]:
+                # NOTE: client is duck-typed ProtocolConsulClient; mypy cannot verify
+                # catalog.services exists on Optional[Consul] union type.
+                result: tuple[int, dict[str, list[str]]] = client.catalog.services()  # type: ignore[union-attr]  # NOTE: duck-typed client
+                return result
+
+            _, services = await asyncio.wait_for(
+                loop.run_in_executor(executor, _query_catalog),
+                timeout=self._timeout_seconds,
+            )
+
+            # Reset circuit breaker on success
+            async with self._circuit_breaker_lock:
+                await self._reset_circuit_breaker()
+
+            # Apply tag filter if provided
+            if tag_filter is not None:
+                services = {
+                    name: tags for name, tags in services.items() if tag_filter in tags
+                }
+
+            duration_ms = (time.monotonic() - start_time) * 1000
+
+            logger.info(
+                "Listed all services from Consul catalog",
+                extra={
+                    "service_count": len(services),
+                    "tag_filter": tag_filter,
+                    "duration_ms": duration_ms,
+                    "correlation_id": str(correlation_id),
+                },
+            )
+
+            return services
+
+        except TimeoutError as e:
+            async with self._circuit_breaker_lock:
+                await self._record_circuit_failure(
+                    operation="list_all_services",
+                    correlation_id=correlation_id,
+                )
+            raise InfraTimeoutError(
+                f"Consul catalog query timed out after {self._timeout_seconds}s",
+                context=ModelTimeoutErrorContext(
+                    transport_type=EnumInfraTransportType.CONSUL,
+                    operation="list_all_services",
+                    target_name="consul.discovery",
+                    correlation_id=correlation_id,
+                    timeout_seconds=self._timeout_seconds,
+                ),
+            ) from e
+
+        except consul.ConsulException as e:
+            async with self._circuit_breaker_lock:
+                await self._record_circuit_failure(
+                    operation="list_all_services",
+                    correlation_id=correlation_id,
+                )
+            context = ModelInfraErrorContext(
+                transport_type=EnumInfraTransportType.CONSUL,
+                operation="list_all_services",
+                target_name="consul.discovery",
+                correlation_id=correlation_id,
+            )
+            raise InfraConnectionError(
+                "Consul catalog query failed",
+                context=context,
+            ) from e
+
+    async def get_all_service_instances(
+        self,
+        service_name: str,
+        include_unhealthy: bool = True,
+        correlation_id: UUID | None = None,
+    ) -> list[ModelServiceInfo]:
+        """Get all instances of a service, optionally including unhealthy ones.
+
+        Uses Consul health API (/v1/health/service/<name>) to retrieve all
+        instances of a service with their health status information.
+
+        Args:
+            service_name: Name of the service to query.
+            include_unhealthy: If True, return all instances regardless of health.
+                If False, only return healthy (passing) instances.
+            correlation_id: Optional correlation ID for tracing.
+
+        Returns:
+            List of ModelServiceInfo objects representing service instances,
+            including health status, health output, and last check timestamp.
+
+        Raises:
+            InfraConnectionError: If connection to Consul fails.
+            InfraTimeoutError: If operation times out.
+            InfraUnavailableError: If circuit breaker is open.
+        """
+        correlation_id = correlation_id or uuid4()
+        start_time = time.monotonic()
+
+        # Guard against use-after-shutdown
+        self._check_not_shutdown("get_all_service_instances", correlation_id)
+
+        # Check circuit breaker
+        async with self._circuit_breaker_lock:
+            await self._check_circuit_breaker(
+                operation="get_all_service_instances",
+                correlation_id=correlation_id,
+            )
+
+        try:
+            # Query Consul health API for service instances
+            client = self._consul_client
+            executor = await self._ensure_executor()
+            loop = asyncio.get_running_loop()
+
+            def _query_health() -> tuple[int, list[dict[str, object]]]:
+                # NOTE: client is duck-typed ProtocolConsulClient; mypy cannot verify
+                # health.service exists on Optional[Consul] union type.
+                # When passing=False, we get ALL instances
+                # When passing=True, we only get healthy instances
+                result: tuple[int, list[dict[str, object]]] = client.health.service(  # type: ignore[union-attr]  # NOTE: duck-typed client
+                    service_name,
+                    passing=not include_unhealthy,
+                )
+                return result
+
+            _, services = await asyncio.wait_for(
+                loop.run_in_executor(executor, _query_health),
+                timeout=self._timeout_seconds,
+            )
+
+            # Reset circuit breaker on success
+            async with self._circuit_breaker_lock:
+                await self._reset_circuit_breaker()
+
+            # Convert to ModelServiceInfo list with full health details
+            service_infos: list[ModelServiceInfo] = []
+            for svc in services:
+                # Cast nested dicts for type safety
+                svc_data = cast("dict[str, object]", svc.get("Service", {}))
+                node_data = cast("dict[str, object]", svc.get("Node", {}))
+                checks = cast("list[dict[str, object]]", svc.get("Checks", []))
+
+                svc_id_str = str(svc_data.get("ID", ""))
+                svc_name = svc_data.get("Service", "")
+                address = svc_data.get("Address", "") or node_data.get("Address", "")
+                port_raw = svc_data.get("Port", 0)
+                port = int(port_raw) if isinstance(port_raw, int | float | str) else 0
+                svc_tags = cast("list[str]", svc_data.get("Tags", []))
+                svc_meta = cast("dict[str, str]", svc_data.get("Meta", {}))
+
+                if svc_id_str and svc_name and address and port:
+                    # Convert Consul service ID string to UUID
+                    try:
+                        svc_id = UUID(svc_id_str)
+                    except ValueError:
+                        # Non-UUID service ID from Consul - generate deterministic UUID5
+                        logger.warning(
+                            "Non-UUID service ID from Consul, using deterministic UUID5 conversion",
+                            extra={
+                                "original_id": svc_id_str,
+                                "correlation_id": str(correlation_id),
+                            },
+                        )
+                        svc_id = uuid5(NAMESPACE_ONEX_SERVICE, svc_id_str)
+
+                    # Determine health status from checks
+                    health_status = EnumHealthStatus.UNKNOWN
+                    health_output: str | None = None
+                    last_check_at: datetime | None = None
+
+                    # Find the service-specific health check
+                    for check in checks:
+                        check_service_id = check.get("ServiceID", "")
+                        if check_service_id == svc_id_str or not check_service_id:
+                            status_str = str(check.get("Status", "")).lower()
+                            if status_str == "passing":
+                                health_status = EnumHealthStatus.HEALTHY
+                            elif status_str in ("critical", "warning"):
+                                health_status = EnumHealthStatus.UNHEALTHY
+                            else:
+                                health_status = EnumHealthStatus.UNKNOWN
+
+                            health_output = str(check.get("Output", "")) or None
+
+                            # Parse CreateIndex as a proxy for last check time
+                            # (Consul doesn't directly expose last check time in this API)
+                            # In production, you might use the check's CreateIndex or ModifyIndex
+                            break
+
+                    service_infos.append(
+                        ModelServiceInfo(
+                            service_id=svc_id,
+                            service_name=str(svc_name),
+                            address=str(address),
+                            port=port,
+                            tags=tuple(svc_tags or []),
+                            health_status=health_status,
+                            health_output=health_output,
+                            last_check_at=last_check_at,
+                            metadata=svc_meta or {},
+                            registered_at=datetime.now(UTC),
+                            correlation_id=correlation_id,
+                        )
+                    )
+
+            duration_ms = (time.monotonic() - start_time) * 1000
+
+            logger.info(
+                "Retrieved service instances from Consul",
+                extra={
+                    "service_name": service_name,
+                    "instance_count": len(service_infos),
+                    "include_unhealthy": include_unhealthy,
+                    "duration_ms": duration_ms,
+                    "correlation_id": str(correlation_id),
+                },
+            )
+
+            return service_infos
+
+        except TimeoutError as e:
+            async with self._circuit_breaker_lock:
+                await self._record_circuit_failure(
+                    operation="get_all_service_instances",
+                    correlation_id=correlation_id,
+                )
+            raise InfraTimeoutError(
+                f"Consul health query timed out after {self._timeout_seconds}s",
+                context=ModelTimeoutErrorContext(
+                    transport_type=EnumInfraTransportType.CONSUL,
+                    operation="get_all_service_instances",
+                    target_name="consul.discovery",
+                    correlation_id=correlation_id,
+                    timeout_seconds=self._timeout_seconds,
+                ),
+            ) from e
+
+        except consul.ConsulException as e:
+            async with self._circuit_breaker_lock:
+                await self._record_circuit_failure(
+                    operation="get_all_service_instances",
+                    correlation_id=correlation_id,
+                )
+            context = ModelInfraErrorContext(
+                transport_type=EnumInfraTransportType.CONSUL,
+                operation="get_all_service_instances",
+                target_name="consul.discovery",
+                correlation_id=correlation_id,
+            )
+            raise InfraConnectionError(
+                "Consul health query failed",
+                context=context,
+            ) from e
+
     async def health_check(
         self,
         correlation_id: UUID | None = None,

omnibase_infra/handlers/service_discovery/models/model_service_info.py

@@ -45,6 +45,8 @@ class ModelServiceInfo(BaseModel):
         health_status: Current health status of the service.
         metadata: Additional key-value metadata for the service.
         health_check_url: Optional URL for health checks (handler extension).
+        health_output: Output message from the last health check (handler extension).
+        last_check_at: Timestamp of the last health check (handler extension).
         registered_at: Timestamp when the service was registered (handler extension).
         correlation_id: Correlation ID for tracing (handler extension).
     """
@@ -86,6 +88,14 @@ class ModelServiceInfo(BaseModel):
         default=None,
         description="Optional URL for health checks",
     )
+    health_output: str | None = Field(
+        default=None,
+        description="Output message from the last health check",
+    )
+    last_check_at: datetime | None = Field(
+        default=None,
+        description="Timestamp of the last health check",
+    )
     registered_at: datetime | None = Field(
         default=None,
         description="Timestamp when the service was registered",

omnibase_infra/mixins/mixin_async_circuit_breaker.py

@@ -101,6 +101,7 @@ import logging
 import time
 from uuid import UUID, uuid4
 
+from omnibase_core.types import JsonType
 from omnibase_infra.enums import EnumCircuitState, EnumInfraTransportType
 from omnibase_infra.errors import (
     InfraUnavailableError,
@@ -580,7 +581,7 @@ class MixinAsyncCircuitBreaker:
         self._circuit_breaker_failures = 0
         self._circuit_breaker_open_until = 0.0
 
-    def _get_circuit_breaker_state(self) -> dict[str, object]:
+    def _get_circuit_breaker_state(self) -> dict[str, JsonType]:
         """Return current circuit breaker state for introspection.
 
         This method encapsulates circuit breaker internals for safe access
@@ -638,7 +639,7 @@ class MixinAsyncCircuitBreaker:
             cb_state = "closed"
             seconds_until_half_open = None
 
-        result: dict[str, object] = {
+        result: dict[str, JsonType] = {
             "initialized": cb_initialized,
             "state": cb_state,
             "failures": cb_failures,

omnibase_infra/mixins/mixin_node_introspection.py

@@ -207,6 +207,7 @@ from typing import TYPE_CHECKING, ClassVar, TypedDict, cast
 from uuid import UUID, uuid4
 
 from omnibase_core.enums import EnumNodeKind
+from omnibase_core.models.events.model_event_envelope import ModelEventEnvelope
 from omnibase_core.models.primitives.model_semver import ModelSemVer
 from omnibase_infra.enums import EnumInfraTransportType, EnumIntrospectionReason
 from omnibase_infra.errors import ModelInfraErrorContext, ProtocolConfigurationError
@@ -228,7 +229,9 @@ from omnibase_infra.models.registration.model_node_introspection_event import (
 
 if TYPE_CHECKING:
     from omnibase_core.protocols.event_bus.protocol_event_bus import ProtocolEventBus
-    from omnibase_infra.event_bus.models import ModelEventMessage
+    from omnibase_core.protocols.event_bus.protocol_event_message import (
+        ProtocolEventMessage,
+    )
 
 logger = logging.getLogger(__name__)
 
@@ -1353,7 +1356,7 @@ class MixinNodeIntrospection:
         # Update cache - cast the model_dump output to our typed dict since we know
         # the structure matches (model_dump returns dict[str, Any] by default)
         self._introspection_cache = cast(
-            IntrospectionCacheDict, event.model_dump(mode="json")
+            "IntrospectionCacheDict", event.model_dump(mode="json")
         )
         self._introspection_cached_at = current_time
 
@@ -1489,8 +1492,13 @@ class MixinNodeIntrospection:
                 assert event_bus is not None  # Redundant but helps mypy
                 topic = self._introspection_topic
                 if hasattr(event_bus, "publish_envelope"):
+                    # Wrap event in ModelEventEnvelope for protocol compliance
+                    envelope: ModelEventEnvelope[object] = ModelEventEnvelope(
+                        payload=publish_event,
+                        correlation_id=final_correlation_id,
+                    )
                     await event_bus.publish_envelope(
-                        envelope=publish_event,
+                        envelope=envelope,  # type: ignore[arg-type]
                         topic=topic,
                     )
                 else:
@@ -1604,8 +1612,13 @@ class MixinNodeIntrospection:
             assert event_bus is not None  # Redundant but helps mypy
             topic = self._heartbeat_topic
             if hasattr(event_bus, "publish_envelope"):
+                # Wrap event in ModelEventEnvelope for protocol compliance
+                envelope: ModelEventEnvelope[object] = ModelEventEnvelope(
+                    payload=heartbeat,
+                    correlation_id=heartbeat.correlation_id,
+                )
                 await event_bus.publish_envelope(
-                    envelope=heartbeat,
+                    envelope=envelope,  # type: ignore[arg-type]
                     topic=topic,
                 )
             else:
@@ -1771,7 +1784,9 @@ class MixinNodeIntrospection:
                 )
             self._registry_unsubscribe = None
 
-    async def _handle_introspection_request(self, message: ModelEventMessage) -> None:
+    async def _handle_introspection_request(
+        self, message: ProtocolEventMessage
+    ) -> None:
         """Handle incoming introspection request.
 
         Includes error recovery with rate-limited logging to prevent
@@ -1779,7 +1794,7 @@ class MixinNodeIntrospection:
         non-fatal errors to maintain graceful degradation.
 
         Args:
-            message: The incoming event message
+            message: The incoming event message (implements ProtocolEventMessage protocol)
         """
         try:
             await self._process_introspection_request(message)
@@ -1788,7 +1803,9 @@ class MixinNodeIntrospection:
         except Exception as e:
             self._handle_request_error(e)
 
-    async def _process_introspection_request(self, message: ModelEventMessage) -> None:
+    async def _process_introspection_request(
+        self, message: ProtocolEventMessage
+    ) -> None:
         """Process the introspection request message.
 
         Args:

omnibase_infra/mixins/mixin_retry_execution.py

@@ -196,7 +196,7 @@ class MixinRetryExecution(ABC):
             This should only be called when _circuit_breaker_initialized is True,
             which guarantees the circuit breaker methods are available.
         """
-        return cast(ProtocolCircuitBreakerAware, self)
+        return cast("ProtocolCircuitBreakerAware", self)
 
     async def _record_circuit_failure_if_enabled(
         self, operation: str, correlation_id: UUID

omnibase_infra/models/handlers/__init__.py

@@ -12,6 +12,10 @@ and error reporting in ONEX handlers.
     Added ModelHandlerDescriptor and ModelContractDiscoveryResult for
     OMN-1097 filesystem handler discovery.
 
+.. versionchanged:: 0.6.4
+    Added ModelBootstrapHandlerDescriptor for OMN-1087 bootstrap handler
+    validation with required handler_class field.
+
 Note:
     ModelContractDiscoveryResult uses a forward reference to
     ModelHandlerValidationError to avoid circular imports. The forward
@@ -20,10 +24,14 @@ Note:
     tests/unit/runtime/test_handler_contract_source.py.
 """
 
+from omnibase_infra.models.handlers.model_bootstrap_handler_descriptor import (
+    ModelBootstrapHandlerDescriptor,
+)
 from omnibase_infra.models.handlers.model_contract_discovery_result import (
     ModelContractDiscoveryResult,
 )
 from omnibase_infra.models.handlers.model_handler_descriptor import (
+    LiteralHandlerKind,
     ModelHandlerDescriptor,
 )
 from omnibase_infra.models.handlers.model_handler_identifier import (
@@ -31,6 +39,8 @@ from omnibase_infra.models.handlers.model_handler_identifier import (
 )
 
 __all__ = [
+    "LiteralHandlerKind",
+    "ModelBootstrapHandlerDescriptor",
     "ModelContractDiscoveryResult",
     "ModelHandlerDescriptor",
     "ModelHandlerIdentifier",