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

omnibase_infra/services/registry_api/models/model_contract_ref.py

@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Contract reference model for dashboard display.
+
+Related Tickets:
+    - OMN-1845: Contract Registry Persistence
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelContractRef(BaseModel):
+    """Lightweight contract reference.
+
+    Used to reference a contract without including full details,
+    suitable for embedding in topic views.
+
+    Attributes:
+        contract_id: Unique identifier in format node_name:major.minor.patch
+        node_name: Name of the node this contract belongs to
+        version: Semantic version string in format major.minor.patch
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    # ONEX_EXCLUDE: pattern_validator - contract_id is a derived natural key (name:version), not UUID
+    contract_id: str = Field(
+        ...,
+        description="Unique identifier in format node_name:major.minor.patch",
+    )
+    # ONEX_EXCLUDE: pattern_validator - node_name is the contract name, not an entity reference
+    node_name: str = Field(
+        ...,
+        description="Name of the node this contract belongs to",
+    )
+    version: str = Field(
+        ...,
+        description="Semantic version string in format major.minor.patch",
+    )
+
+
+__all__ = ["ModelContractRef"]

omnibase_infra/services/registry_api/models/model_contract_view.py

@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Contract view model for dashboard display.
+
+Related Tickets:
+    - OMN-1845: Contract Registry Persistence
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelContractView(BaseModel):
+    """Contract detail for API responses.
+
+    Represents a registered contract from the contract registry,
+    flattened for dashboard consumption.
+
+    Attributes:
+        contract_id: Unique identifier in format node_name:major.minor.patch
+        node_name: Name of the node this contract belongs to
+        version: Semantic version string in format major.minor.patch
+        contract_hash: SHA-256 hash of contract content for integrity verification
+        is_active: Whether the contract is currently active
+        registered_at: Timestamp of initial registration
+        last_seen_at: Timestamp of last activity (heartbeat or event)
+        deregistered_at: Timestamp when contract was deregistered (None if active)
+        topics_published: List of topic suffixes this contract publishes to
+        topics_subscribed: List of topic suffixes this contract subscribes to
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    # ONEX_EXCLUDE: pattern_validator - contract_id is a derived natural key (name:version), not UUID
+    contract_id: str = Field(
+        ...,
+        description="Unique identifier in format node_name:major.minor.patch",
+    )
+    # ONEX_EXCLUDE: pattern_validator - node_name is the contract name, not an entity reference
+    node_name: str = Field(
+        ...,
+        description="Name of the node this contract belongs to",
+    )
+    version: str = Field(
+        ...,
+        description="Semantic version string in format major.minor.patch",
+    )
+    contract_hash: str = Field(
+        ...,
+        description="SHA-256 hash of contract content for integrity verification",
+    )
+    is_active: bool = Field(
+        ...,
+        description="Whether the contract is currently active",
+    )
+    registered_at: datetime = Field(
+        ...,
+        description="Timestamp of initial registration",
+    )
+    last_seen_at: datetime = Field(
+        ...,
+        description="Timestamp of last activity (heartbeat or event)",
+    )
+    deregistered_at: datetime | None = Field(
+        default=None,
+        description="Timestamp when contract was deregistered (None if active)",
+    )
+    topics_published: tuple[str, ...] = Field(
+        default_factory=tuple,
+        description="List of topic suffixes this contract publishes to",
+    )
+    topics_subscribed: tuple[str, ...] = Field(
+        default_factory=tuple,
+        description="List of topic suffixes this contract subscribes to",
+    )
+
+
+__all__ = ["ModelContractView"]

omnibase_infra/services/registry_api/models/model_response_contracts.py

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Response model for list_contracts endpoint.
+
+Related Tickets:
+    - OMN-1845: Contract Registry Persistence
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.services.registry_api.models.model_contract_view import (
+    ModelContractView,
+)
+from omnibase_infra.services.registry_api.models.model_pagination_info import (
+    ModelPaginationInfo,
+)
+from omnibase_infra.services.registry_api.models.model_warning import ModelWarning
+
+
+class ModelResponseListContracts(BaseModel):
+    """Response model for the GET /registry/contracts endpoint.
+
+    Provides a paginated list of registered contracts with optional warnings
+    for partial success scenarios.
+
+    Attributes:
+        contracts: List of registered contracts matching the query
+        pagination: Pagination information for the result set
+        warnings: List of warnings for partial success scenarios
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    contracts: list[ModelContractView] = Field(
+        default_factory=list,
+        description="List of registered contracts matching the query",
+    )
+    pagination: ModelPaginationInfo = Field(
+        ...,
+        description="Pagination information for the result set",
+    )
+    warnings: list[ModelWarning] = Field(
+        default_factory=list,
+        description="Warnings for partial success scenarios",
+    )
+
+
+__all__ = ["ModelResponseListContracts"]

omnibase_infra/services/registry_api/models/model_response_topics.py

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Response model for list_topics endpoint.
+
+Related Tickets:
+    - OMN-1845: Contract Registry Persistence
+"""
+
+from __future__ import annotations
+
+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_topic_summary import (
+    ModelTopicSummary,
+)
+from omnibase_infra.services.registry_api.models.model_warning import ModelWarning
+
+
+class ModelResponseListTopics(BaseModel):
+    """Response model for the GET /registry/topics endpoint.
+
+    Provides a paginated list of topics with optional warnings
+    for partial success scenarios.
+
+    Attributes:
+        topics: List of topic summaries matching the query
+        pagination: Pagination information for the result set
+        warnings: List of warnings for partial success scenarios
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    topics: list[ModelTopicSummary] = Field(
+        default_factory=list,
+        description="List of topic summaries matching the query",
+    )
+    pagination: ModelPaginationInfo = Field(
+        ...,
+        description="Pagination information for the result set",
+    )
+    warnings: list[ModelWarning] = Field(
+        default_factory=list,
+        description="Warnings for partial success scenarios",
+    )
+
+
+__all__ = ["ModelResponseListTopics"]

omnibase_infra/services/registry_api/models/model_topic_summary.py

@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Topic summary model for dashboard display.
+
+Related Tickets:
+    - OMN-1845: Contract Registry Persistence
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.models.projection.model_topic_projection import TopicDirection
+
+
+class ModelTopicSummary(BaseModel):
+    """Topic summary for list view.
+
+    Provides a compact view of a topic suitable for list endpoints,
+    including direction (publish/subscribe) and contract count.
+
+    Attributes:
+        topic_suffix: Topic suffix (without environment prefix)
+        direction: Relationship direction ('publish' or 'subscribe')
+        contract_count: Number of contracts with this topic relationship
+        last_seen_at: Timestamp of last activity on this topic
+        is_active: Whether the topic has active contracts
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    topic_suffix: str = Field(
+        ...,
+        description="Topic suffix (without environment prefix)",
+    )
+    direction: TopicDirection = Field(
+        ...,
+        description="Relationship direction ('publish' or 'subscribe')",
+    )
+    contract_count: int = Field(
+        ...,
+        ge=0,
+        description="Number of contracts with this topic relationship",
+    )
+    last_seen_at: datetime = Field(
+        ...,
+        description="Timestamp of last activity on this topic",
+    )
+    is_active: bool = Field(
+        ...,
+        description="Whether the topic has active contracts",
+    )
+
+
+__all__ = ["ModelTopicSummary"]

omnibase_infra/services/registry_api/models/model_topic_view.py

@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Topic view model for dashboard display.
+
+Related Tickets:
+    - OMN-1845: Contract Registry Persistence
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.services.registry_api.models.model_contract_ref import (
+    ModelContractRef,
+)
+
+
+class ModelTopicView(BaseModel):
+    """Topic detail for API responses.
+
+    Represents a topic with its publishers and subscribers,
+    providing full detail for topic inspection endpoints.
+
+    Attributes:
+        topic_suffix: Topic suffix (without environment prefix)
+        publishers: List of contracts that publish to this topic
+        subscribers: List of contracts that subscribe to this topic
+        first_seen_at: Timestamp when topic was first observed
+        last_seen_at: Timestamp of last activity on this topic
+        is_active: Whether the topic has active publishers or subscribers
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    topic_suffix: str = Field(
+        ...,
+        description="Topic suffix (without environment prefix)",
+    )
+    publishers: list[ModelContractRef] = Field(
+        default_factory=list,
+        description="List of contracts that publish to this topic",
+    )
+    subscribers: list[ModelContractRef] = Field(
+        default_factory=list,
+        description="List of contracts that subscribe to this topic",
+    )
+    first_seen_at: datetime = Field(
+        ...,
+        description="Timestamp when topic was first observed",
+    )
+    last_seen_at: datetime = Field(
+        ...,
+        description="Timestamp of last activity on this topic",
+    )
+    is_active: bool = Field(
+        ...,
+        description="Whether the topic has active publishers or subscribers",
+    )
+
+
+__all__ = ["ModelTopicView"]

omnibase_infra/services/registry_api/routes.py

@@ -6,15 +6,20 @@ FastAPI route handlers for the Registry API. Routes are defined as an
 APIRouter for easy mounting into the main FastAPI application.
 
 Endpoint Summary:
-    GET /registry/discovery     - Full dashboard payload
-    GET /registry/nodes         - Node list with pagination
-    GET /registry/nodes/{id}    - Single node detail
-    GET /registry/instances     - Live Consul instances
-    GET /registry/widgets/mapping - Widget mapping configuration
-    GET /registry/health        - Service health check
+    GET /registry/discovery           - Full dashboard payload
+    GET /registry/nodes               - Node list with pagination
+    GET /registry/nodes/{id}          - Single node detail
+    GET /registry/instances           - Live Consul instances
+    GET /registry/widgets/mapping     - Widget mapping configuration
+    GET /registry/health              - Service health check
+    GET /registry/contracts           - Contract list with pagination
+    GET /registry/contracts/{id}      - Single contract detail
+    GET /registry/topics              - Topic list with pagination
+    GET /registry/topics/{suffix}     - Single topic detail
 
 Related Tickets:
     - OMN-1278: Contract-Driven Dashboard - Registry Discovery
+    - OMN-1845: Contract Registry Persistence
 """
 
 from __future__ import annotations
@@ -26,11 +31,15 @@ from fastapi import APIRouter, Depends, Header, HTTPException, Query, Request, s
 
 from omnibase_infra.enums import EnumRegistrationState
 from omnibase_infra.services.registry_api.models import (
+    ModelContractView,
     ModelRegistryDiscoveryResponse,
     ModelRegistryHealthResponse,
     ModelRegistryNodeView,
+    ModelResponseListContracts,
     ModelResponseListInstances,
     ModelResponseListNodes,
+    ModelResponseListTopics,
+    ModelTopicView,
     ModelWidgetMapping,
 )
 
@@ -368,4 +377,194 @@ async def health_check(
     return response
 
 
+# ============================================================
+# Contract Registry Endpoints
+# ============================================================
+
+
+@router.get(
+    "/contracts",
+    response_model=ModelResponseListContracts,
+    summary="List Registered Contracts",
+    description=(
+        "Returns a paginated list of registered contracts from the contract registry. "
+        "Supports filtering by node name and active status."
+    ),
+    responses={
+        400: {"description": "Bad request (e.g., invalid correlation ID format)"},
+        200: {"description": "Successful response with contract list"},
+    },
+)
+async def list_contracts(
+    service: Annotated[ServiceRegistryDiscovery, Depends(get_service)],
+    correlation_id: Annotated[UUID, Depends(get_correlation_id)],
+    limit: Annotated[
+        int,
+        Query(ge=1, le=1000, description="Maximum number of contracts to return"),
+    ] = 100,
+    offset: Annotated[
+        int,
+        Query(ge=0, description="Number of contracts to skip for pagination"),
+    ] = 0,
+    active_only: Annotated[
+        bool,
+        Query(description="If true, return only active contracts"),
+    ] = True,
+    node_name: Annotated[
+        str | None,
+        Query(description="Filter by node name"),
+    ] = None,
+) -> ModelResponseListContracts:
+    """List registered contracts with pagination and optional filtering."""
+    contracts, pagination, warnings = await service.list_contracts(
+        limit=limit,
+        offset=offset,
+        active_only=active_only,
+        node_name=node_name,
+        correlation_id=correlation_id,
+    )
+
+    return ModelResponseListContracts(
+        contracts=contracts,
+        pagination=pagination,
+        warnings=warnings,
+    )
+
+
+@router.get(
+    "/contracts/{contract_id:path}",
+    response_model=ModelContractView,
+    summary="Get Contract Details",
+    description=(
+        "Returns detailed information for a single contract by ID. "
+        "Includes lists of topics the contract publishes to and subscribes from."
+    ),
+    responses={
+        400: {"description": "Bad request (e.g., invalid correlation ID format)"},
+        200: {"description": "Successful response with contract details"},
+        404: {"description": "Contract not found"},
+    },
+)
+async def get_contract(
+    contract_id: str,
+    service: Annotated[ServiceRegistryDiscovery, Depends(get_service)],
+    correlation_id: Annotated[UUID, Depends(get_correlation_id)],
+) -> ModelContractView:
+    """Get a single contract by ID."""
+    contract, warnings = await service.get_contract(
+        contract_id=contract_id,
+        correlation_id=correlation_id,
+    )
+
+    if contract is None:
+        # Check if it was a service error or genuinely not found
+        if warnings:
+            raise HTTPException(
+                status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+                detail=f"Service error: {warnings[0].message}",
+                headers={"X-Correlation-ID": str(correlation_id)},
+            )
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Contract not found: {contract_id}",
+            headers={"X-Correlation-ID": str(correlation_id)},
+        )
+
+    return contract
+
+
+@router.get(
+    "/topics",
+    response_model=ModelResponseListTopics,
+    summary="List Event Topics",
+    description=(
+        "Returns a paginated list of event topics from the contract registry. "
+        "Supports filtering by direction (publish/subscribe)."
+    ),
+    responses={
+        400: {"description": "Bad request (e.g., invalid correlation ID format)"},
+        200: {"description": "Successful response with topic list"},
+    },
+)
+async def list_topics(
+    service: Annotated[ServiceRegistryDiscovery, Depends(get_service)],
+    correlation_id: Annotated[UUID, Depends(get_correlation_id)],
+    direction: Annotated[
+        str | None,
+        Query(description="Filter by direction ('publish' or 'subscribe')"),
+    ] = None,
+    limit: Annotated[
+        int,
+        Query(ge=1, le=1000, description="Maximum number of topics to return"),
+    ] = 100,
+    offset: Annotated[
+        int,
+        Query(ge=0, description="Number of topics to skip for pagination"),
+    ] = 0,
+) -> ModelResponseListTopics:
+    """List event topics with pagination and optional filtering."""
+    # Validate direction if provided
+    if direction is not None and direction not in ("publish", "subscribe"):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Invalid direction: {direction}. Must be 'publish' or 'subscribe'.",
+            headers={"X-Correlation-ID": str(correlation_id)},
+        )
+
+    topics, pagination, warnings = await service.list_topics(
+        direction=direction,
+        limit=limit,
+        offset=offset,
+        correlation_id=correlation_id,
+    )
+
+    return ModelResponseListTopics(
+        topics=topics,
+        pagination=pagination,
+        warnings=warnings,
+    )
+
+
+@router.get(
+    "/topics/{topic_suffix:path}",
+    response_model=ModelTopicView,
+    summary="Get Topic Details",
+    description=(
+        "Returns detailed information for a single topic by suffix. "
+        "Includes lists of publishers and subscribers with contract references."
+    ),
+    responses={
+        400: {"description": "Bad request (e.g., invalid correlation ID format)"},
+        200: {"description": "Successful response with topic details"},
+        404: {"description": "Topic not found"},
+    },
+)
+async def get_topic(
+    topic_suffix: str,
+    service: Annotated[ServiceRegistryDiscovery, Depends(get_service)],
+    correlation_id: Annotated[UUID, Depends(get_correlation_id)],
+) -> ModelTopicView:
+    """Get a single topic by suffix."""
+    topic, warnings = await service.get_topic_detail(
+        topic_suffix=topic_suffix,
+        correlation_id=correlation_id,
+    )
+
+    if topic is None:
+        # Check if it was a service error or genuinely not found
+        if warnings:
+            raise HTTPException(
+                status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+                detail=f"Service error: {warnings[0].message}",
+                headers={"X-Correlation-ID": str(correlation_id)},
+            )
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Topic not found: {topic_suffix}",
+            headers={"X-Correlation-ID": str(correlation_id)},
+        )
+
+    return topic
+
+
 __all__ = ["router", "get_service", "get_correlation_id"]