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

omnibase_infra/services/registry_api/main.py

@@ -0,0 +1,243 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Registry API FastAPI Application.
+
+Creates and configures the FastAPI application for the Registry API.
+Provides factory function for flexible instantiation with different
+backend configurations.
+
+Usage:
+    # Create app with default settings (no backends)
+    app = create_app()
+
+    # Create app with full backends
+    app = create_app(
+        projection_reader=reader,
+        consul_handler=handler,
+    )
+
+    # Run with uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+
+Related Tickets:
+    - OMN-1278: Contract-Driven Dashboard - Registry Discovery
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from omnibase_infra.enums import EnumInfraTransportType
+from omnibase_infra.errors import ModelInfraErrorContext, ProtocolConfigurationError
+from omnibase_infra.services.registry_api.routes import router
+from omnibase_infra.services.registry_api.service import ServiceRegistryDiscovery
+
+if TYPE_CHECKING:
+    from omnibase_infra.handlers.service_discovery import HandlerServiceDiscoveryConsul
+    from omnibase_infra.projectors import ProjectionReaderRegistration
+
+logger = logging.getLogger(__name__)
+
+# API metadata
+API_TITLE = "ONEX Registry API"
+API_DESCRIPTION = """
+Registry Discovery API for ONEX Dashboard Integration.
+
+This API provides access to node registrations and live service instances
+for dashboard consumption. It combines data from:
+
+- **PostgreSQL Projections**: Node registration state, capabilities, and metadata
+- **Consul Service Discovery**: Live service instances with health status
+
+## Key Features
+
+- **Full Dashboard Payload**: Single endpoint for all dashboard data
+- **Partial Success**: Returns data even when one backend fails
+- **Widget Mapping**: Configuration for capability-to-widget rendering
+- **Health Monitoring**: Component-level health status
+
+## Related Tickets
+
+- OMN-1278: Contract-Driven Dashboard - Registry Discovery
+"""
+API_VERSION = "1.0.0"
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+    """Application lifespan handler for startup/shutdown.
+
+    Initializes backend connections on startup and cleans up on shutdown.
+
+    Args:
+        app: FastAPI application instance.
+
+    Yields:
+        None (context manager pattern).
+    """
+    logger.info("Registry API starting up")
+
+    # Log configuration
+    service: ServiceRegistryDiscovery | None = getattr(
+        app.state, "registry_service", None
+    )
+    if service is not None:
+        logger.info(
+            "Registry service configured",
+            extra={
+                "has_projection_reader": service.has_projection_reader,
+                "has_consul_handler": service.has_consul_handler,
+            },
+        )
+    else:
+        logger.warning("Registry service not configured - API will return limited data")
+
+    yield
+
+    logger.info("Registry API shutting down")
+
+    # Cleanup Consul handler if we own it
+    if service is not None and service.consul_handler is not None:
+        try:
+            await service.consul_handler.shutdown()
+            logger.info("Consul handler shutdown complete")
+        except Exception as e:
+            logger.exception(
+                "Error during Consul handler shutdown",
+                extra={"error_type": type(e).__name__},
+            )
+
+
+def create_app(
+    projection_reader: ProjectionReaderRegistration | None = None,
+    consul_handler: HandlerServiceDiscoveryConsul | None = None,
+    widget_mapping_path: Path | None = None,
+    cors_origins: list[str] | None = None,
+) -> FastAPI:
+    """Create and configure the Registry API FastAPI application.
+
+    Factory function that creates a FastAPI app with the specified
+    backend configurations. All backends are optional - the API will
+    return partial data with warnings when backends are unavailable.
+
+    Args:
+        projection_reader: Optional projection reader for node registrations.
+        consul_handler: Optional Consul handler for live instances.
+        widget_mapping_path: Optional path to widget mapping YAML.
+        cors_origins: Optional list of allowed CORS origins.
+            If not provided, reads from CORS_ORIGINS environment variable.
+            Raises ProtocolConfigurationError if neither is configured (fail-fast).
+
+    Returns:
+        Configured FastAPI application.
+
+    Raises:
+        ProtocolConfigurationError: If CORS origins not configured via parameter
+            or CORS_ORIGINS environment variable.
+
+    Example:
+        >>> from omnibase_infra.services.registry_api import create_app
+        >>> app = create_app()
+        >>> # Run with: uvicorn module:app --host 0.0.0.0 --port 8000
+    """
+    app = FastAPI(
+        title=API_TITLE,
+        description=API_DESCRIPTION,
+        version=API_VERSION,
+        lifespan=lifespan,
+        docs_url="/docs",
+        redoc_url="/redoc",
+        openapi_url="/openapi.json",
+    )
+
+    # Configure CORS - fail-fast if not configured
+    if cors_origins is not None:
+        origins = cors_origins
+    else:
+        env_origins = os.environ.get("CORS_ORIGINS")
+        if env_origins is None:
+            context = ModelInfraErrorContext.with_correlation(
+                transport_type=EnumInfraTransportType.HTTP,
+                operation="configure_cors",
+            )
+            raise ProtocolConfigurationError(
+                "CORS_ORIGINS must be configured. "
+                "Set the CORS_ORIGINS environment variable (comma-separated list of allowed origins) "
+                "or pass cors_origins parameter to create_app(). "
+                "Example: CORS_ORIGINS=http://localhost:3000,https://dashboard.example.com",
+                context=context,
+            )
+        origins = env_origins.split(",")
+
+    # Warn about wildcard CORS - only when explicitly configured
+    if "*" in origins:
+        logger.warning(
+            "CORS explicitly configured with wildcard origin '*'. "
+            "This is acceptable for development but should be restricted in production.",
+            extra={"origins": origins},
+        )
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=origins,
+        allow_credentials=True,
+        allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"],
+        allow_headers=["*"],
+    )
+
+    # Create and attach service
+    service = ServiceRegistryDiscovery(
+        projection_reader=projection_reader,
+        consul_handler=consul_handler,
+        widget_mapping_path=widget_mapping_path,
+    )
+    app.state.registry_service = service
+
+    # Include routes
+    app.include_router(router)
+
+    # Root endpoint
+    @app.get("/", include_in_schema=False)
+    async def root() -> dict[str, str]:
+        """Root endpoint with API info."""
+        return {
+            "service": API_TITLE,
+            "version": API_VERSION,
+            "docs": "/docs",
+            "health": "/registry/health",
+        }
+
+    logger.info(
+        "Registry API created",
+        extra={
+            "version": API_VERSION,
+            "cors_origins": origins,
+        },
+    )
+
+    return app
+
+
+# Default app instance for direct uvicorn usage
+# Example: uvicorn omnibase_infra.services.registry_api.main:app --host 0.0.0.0 --port 8000
+# Note: This creates an app with no backends configured. For production,
+# use create_app() directly with proper backend configuration (projection_reader,
+# consul_handler). Tests should also use create_app() for controlled app creation.
+#
+# IMPORTANT: CORS_ORIGINS environment variable MUST be set for module-level app creation.
+# If CORS_ORIGINS is not set, the module can still be imported but `app` will be None.
+# Use create_app(cors_origins=["..."]) directly for programmatic usage.
+app: FastAPI | None = None
+if os.environ.get("CORS_ORIGINS") is not None:
+    app = create_app()
+
+
+__all__ = ["app", "create_app"]

omnibase_infra/services/registry_api/models/__init__.py

@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Registry API Response Models.
+
+Pydantic models for the Registry API HTTP responses. These models define
+the JSON shape returned by each endpoint for dashboard consumption.
+
+Design Principles:
+    - Flat, dashboard-friendly structures (no deep nesting)
+    - Explicit field descriptions for API documentation
+    - Immutable (frozen) for thread safety
+    - Strict validation (extra="forbid")
+
+Related Tickets:
+    - OMN-1278: Contract-Driven Dashboard - Registry Discovery
+"""
+
+from omnibase_infra.services.registry_api.models.model_capability_widget_mapping import (
+    ModelCapabilityWidgetMapping,
+)
+from omnibase_infra.services.registry_api.models.model_pagination_info import (
+    ModelPaginationInfo,
+)
+from omnibase_infra.services.registry_api.models.model_registry_discovery_response import (
+    ModelRegistryDiscoveryResponse,
+)
+from omnibase_infra.services.registry_api.models.model_registry_health_response import (
+    ModelRegistryHealthResponse,
+)
+from omnibase_infra.services.registry_api.models.model_registry_instance_view import (
+    ModelRegistryInstanceView,
+)
+from omnibase_infra.services.registry_api.models.model_registry_node_view import (
+    ModelRegistryNodeView,
+)
+from omnibase_infra.services.registry_api.models.model_registry_summary import (
+    ModelRegistrySummary,
+)
+from omnibase_infra.services.registry_api.models.model_response_list_instances import (
+    ModelResponseListInstances,
+)
+from omnibase_infra.services.registry_api.models.model_response_list_nodes import (
+    ModelResponseListNodes,
+)
+from omnibase_infra.services.registry_api.models.model_warning import ModelWarning
+from omnibase_infra.services.registry_api.models.model_widget_defaults import (
+    ModelWidgetDefaults,
+)
+from omnibase_infra.services.registry_api.models.model_widget_mapping import (
+    ModelWidgetMapping,
+)
+
+__all__ = [
+    "ModelCapabilityWidgetMapping",
+    "ModelPaginationInfo",
+    "ModelRegistryDiscoveryResponse",
+    "ModelRegistryHealthResponse",
+    "ModelRegistryInstanceView",
+    "ModelRegistryNodeView",
+    "ModelRegistrySummary",
+    "ModelResponseListInstances",
+    "ModelResponseListNodes",
+    "ModelWarning",
+    "ModelWidgetDefaults",
+    "ModelWidgetMapping",
+]

omnibase_infra/services/registry_api/models/model_capability_widget_mapping.py

@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Capability widget mapping model for dashboard configuration.
+
+Related Tickets:
+    - OMN-1278: Contract-Driven Dashboard - Registry Discovery
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.services.registry_api.models.model_widget_defaults import (
+    ModelWidgetDefaults,
+)
+
+
+class ModelCapabilityWidgetMapping(BaseModel):
+    """Mapping from a capability to its widget configuration.
+
+    Attributes:
+        widget_type: Type of widget to render
+        defaults: Default widget configuration
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    widget_type: str = Field(
+        ...,
+        description="Type of widget to render",
+    )
+    defaults: ModelWidgetDefaults = Field(
+        default_factory=ModelWidgetDefaults,
+        description="Default widget configuration",
+    )
+
+
+__all__ = ["ModelCapabilityWidgetMapping"]

omnibase_infra/services/registry_api/models/model_pagination_info.py

@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Pagination info model for list endpoints.
+
+Related Tickets:
+    - OMN-1278: Contract-Driven Dashboard - Registry Discovery
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelPaginationInfo(BaseModel):
+    """Pagination information for list endpoints.
+
+    Attributes:
+        total: Total number of items matching the query
+        limit: Maximum items per page
+        offset: Current offset (0-based)
+        has_more: Whether more items exist beyond current page
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    total: int = Field(
+        ...,
+        ge=0,
+        description="Total number of items",
+    )
+    limit: int = Field(
+        ...,
+        ge=1,
+        le=1000,
+        description="Maximum items per page",
+    )
+    offset: int = Field(
+        ...,
+        ge=0,
+        description="Current offset (0-based)",
+    )
+    has_more: bool = Field(
+        ...,
+        description="Whether more items exist",
+    )
+
+
+__all__ = ["ModelPaginationInfo"]

omnibase_infra/services/registry_api/models/model_registry_discovery_response.py

@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Registry discovery response model for dashboard payload.
+
+Related Tickets:
+    - OMN-1278: Contract-Driven Dashboard - Registry Discovery
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.services.registry_api.models.model_pagination_info import (
+    ModelPaginationInfo,
+)
+from omnibase_infra.services.registry_api.models.model_registry_instance_view import (
+    ModelRegistryInstanceView,
+)
+from omnibase_infra.services.registry_api.models.model_registry_node_view import (
+    ModelRegistryNodeView,
+)
+from omnibase_infra.services.registry_api.models.model_registry_summary import (
+    ModelRegistrySummary,
+)
+from omnibase_infra.services.registry_api.models.model_warning import ModelWarning
+
+
+class ModelRegistryDiscoveryResponse(BaseModel):
+    """Full dashboard payload combining nodes, instances, and summary.
+
+    The primary response model for the GET /registry/discovery endpoint,
+    providing everything a dashboard needs in a single request.
+
+    Attributes:
+        timestamp: When this response was generated
+        warnings: List of warnings for partial success scenarios
+        summary: Aggregate statistics
+        nodes: List of registered nodes
+        live_instances: List of live Consul instances
+        pagination: Pagination info for nodes list
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    timestamp: datetime = Field(
+        ...,
+        description="When this response was generated",
+    )
+    warnings: list[ModelWarning] = Field(
+        default_factory=list,
+        description="Warnings for partial success scenarios",
+    )
+    summary: ModelRegistrySummary = Field(
+        ...,
+        description="Aggregate statistics",
+    )
+    nodes: list[ModelRegistryNodeView] = Field(
+        default_factory=list,
+        description="List of registered nodes",
+    )
+    live_instances: list[ModelRegistryInstanceView] = Field(
+        default_factory=list,
+        description="List of live Consul instances",
+    )
+    pagination: ModelPaginationInfo = Field(
+        ...,
+        description="Pagination info for nodes list",
+    )
+
+
+__all__ = ["ModelRegistryDiscoveryResponse"]

omnibase_infra/services/registry_api/models/model_registry_health_response.py

@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Registry health response model for API health checks.
+
+Related Tickets:
+    - OMN-1278: Contract-Driven Dashboard - Registry Discovery
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_core.types import JsonType
+
+
+class ModelRegistryHealthResponse(BaseModel):
+    """Health check response for the registry API.
+
+    Attributes:
+        status: Overall health status (healthy, degraded, unhealthy)
+        timestamp: When the health check was performed
+        components: Health status of individual components
+        version: API version string
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    status: Literal["healthy", "degraded", "unhealthy"] = Field(
+        ...,
+        description="Overall health status",
+    )
+    timestamp: datetime = Field(
+        ...,
+        description="When the health check was performed",
+    )
+    components: dict[str, JsonType] = Field(
+        default_factory=dict,
+        description="Health status of individual components",
+    )
+    version: str = Field(
+        default="1.0.0",
+        description="API version string",
+    )
+
+
+__all__ = ["ModelRegistryHealthResponse"]

omnibase_infra/services/registry_api/models/model_registry_instance_view.py

@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Registry instance view model for dashboard display.
+
+Related Tickets:
+    - OMN-1278: Contract-Driven Dashboard - Registry Discovery
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelRegistryInstanceView(BaseModel):
+    """Live service instance view for dashboard display.
+
+    Represents a live Consul service instance, providing real-time
+    health and connectivity information.
+
+    Attributes:
+        node_id: Node UUID (may be derived from service_id if not UUID)
+        service_name: Consul service name
+        service_id: Consul service instance ID
+        instance_id: Unique instance identifier (same as service_id)
+        address: Network address (IP or hostname)
+        port: Service port number
+        health_status: Health check status (passing, warning, critical, unknown)
+        health_output: Health check output message (nullable)
+        last_check_at: Timestamp of last health check (nullable)
+        tags: Consul service tags
+        meta: Consul service metadata
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    node_id: UUID = Field(
+        ...,
+        description="Node UUID (may be derived from service_id)",
+    )
+    service_name: str = Field(  # ONEX_EXCLUDE: pattern - Consul discovery identifier
+        ...,
+        description="Consul service name (external Consul identifier, not entity reference)",
+    )
+    service_id: UUID = Field(
+        ...,
+        description="Consul service instance ID",
+    )
+    instance_id: UUID = Field(
+        ...,
+        description="Unique instance identifier",
+    )
+    address: str = Field(
+        ...,
+        description="Network address (IP or hostname)",
+    )
+    port: int = Field(
+        ...,
+        ge=1,
+        le=65535,
+        description="Service port number",
+    )
+    health_status: Literal["passing", "warning", "critical", "unknown"] = Field(
+        ...,
+        description="Health check status",
+    )
+    health_output: str | None = Field(
+        default=None,
+        description="Health check output message",
+    )
+    last_check_at: datetime | None = Field(
+        default=None,
+        description="Timestamp of last health check",
+    )
+    tags: list[str] = Field(
+        default_factory=list,
+        description="Consul service tags",
+    )
+    meta: dict[str, str] = Field(
+        default_factory=dict,
+        description="Consul service metadata",
+    )
+
+
+__all__ = ["ModelRegistryInstanceView"]

omnibase_infra/services/registry_api/models/model_registry_node_view.py

@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Registry node view model for dashboard display.
+
+Related Tickets:
+    - OMN-1278: Contract-Driven Dashboard - Registry Discovery
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_core.models.primitives.model_semver import ModelSemVer
+
+
+class ModelRegistryNodeView(BaseModel):
+    """Node view for dashboard display.
+
+    Represents a registered ONEX node from the registration projection,
+    flattened for dashboard consumption.
+
+    Attributes:
+        node_id: Unique identifier (entity_id from projection)
+        name: Human-readable node name (from service_name or node_type)
+        service_name: Consul service name for discovery
+        namespace: Optional namespace for multi-tenant deployments
+        display_name: Optional human-friendly display name
+        node_type: ONEX node archetype (EFFECT, COMPUTE, REDUCER, ORCHESTRATOR)
+        version: Semantic version (ModelSemVer instance)
+        state: Current FSM registration state
+        capabilities: List of capability tags
+        registered_at: Timestamp of initial registration
+        last_heartbeat_at: Timestamp of last heartbeat (nullable)
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    node_id: UUID = Field(
+        ...,
+        description="Unique node identifier",
+    )
+    name: str = Field(
+        ...,
+        description="Node name (service_name or derived from node_type)",
+    )
+    service_name: str = Field(  # ONEX_EXCLUDE: pattern - Consul discovery identifier
+        ...,
+        description="Consul service name (external Consul identifier, not entity reference)",
+    )
+    namespace: str | None = Field(
+        default=None,
+        description="Optional namespace for multi-tenant deployments",
+    )
+    display_name: str | None = Field(
+        default=None,
+        description="Optional human-friendly display name",
+    )
+    node_type: Literal["EFFECT", "COMPUTE", "REDUCER", "ORCHESTRATOR"] = Field(
+        ...,
+        description="ONEX node archetype",
+    )
+    version: ModelSemVer = Field(
+        ...,
+        description="Semantic version (ONEX standard)",
+    )
+    state: str = Field(
+        ...,
+        description="Current FSM registration state",
+    )
+    capabilities: list[str] = Field(
+        default_factory=list,
+        description="List of capability tags",
+    )
+    registered_at: datetime = Field(
+        ...,
+        description="Timestamp of initial registration",
+    )
+    last_heartbeat_at: datetime | None = Field(
+        default=None,
+        description="Timestamp of last heartbeat",
+    )
+
+
+__all__ = ["ModelRegistryNodeView"]