truthound-dashboard 1.3.1__py3-none-any.whl → 1.4.0__py3-none-any.whl

truthound_dashboard/api/versioning.py

@@ -0,0 +1,309 @@
+"""Versioning API endpoints.
+
+Provides endpoints for validation result version management:
+- List versions for a source
+- Get specific version details
+- Compare two versions
+- Get version history chain
+- Create new versions
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Annotated
+
+from fastapi import APIRouter, HTTPException, Path, Query
+
+from truthound_dashboard.core.versioning import (
+    VersioningStrategy,
+    get_version_manager,
+)
+from truthound_dashboard.schemas.versioning import (
+    CreateVersionRequest,
+    CreateVersionResponse,
+    RollbackAvailabilityResponse,
+    RollbackRequest,
+    RollbackResponse,
+    VersionCompareRequest,
+    VersionDiffResponse,
+    VersionHistoryResponse,
+    VersionInfoResponse,
+    VersionListResponse,
+)
+from truthound_dashboard.api.deps import ValidationServiceDep
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/versions", tags=["versioning"])
+
+
+def _version_info_to_response(version_info) -> VersionInfoResponse:
+    """Convert VersionInfo dataclass to response model."""
+    return VersionInfoResponse(
+        version_id=version_info.version_id,
+        version_number=version_info.version_number,
+        validation_id=version_info.validation_id,
+        source_id=version_info.source_id,
+        strategy=version_info.strategy.value,
+        created_at=version_info.created_at,
+        parent_version_id=version_info.parent_version_id,
+        metadata=version_info.metadata,
+        content_hash=version_info.content_hash,
+    )
+
+
+@router.get(
+    "/sources/{source_id}",
+    response_model=VersionListResponse,
+    summary="List versions for a source",
+    description="Get all validation result versions for a data source, ordered by creation time (newest first).",
+)
+async def list_source_versions(
+    source_id: Annotated[str, Path(description="Source ID")],
+    limit: Annotated[int, Query(ge=1, le=100, description="Maximum versions to return")] = 20,
+) -> VersionListResponse:
+    """List all versions for a source."""
+    manager = get_version_manager()
+    versions = await manager.list_versions(source_id=source_id, limit=limit)
+
+    return VersionListResponse(
+        success=True,
+        data=[_version_info_to_response(v) for v in versions],
+        total=len(versions),
+        source_id=source_id,
+    )
+
+
+@router.get(
+    "/{version_id}",
+    response_model=VersionInfoResponse,
+    summary="Get version details",
+    description="Get detailed information about a specific version.",
+)
+async def get_version(
+    version_id: Annotated[str, Path(description="Version ID")],
+) -> VersionInfoResponse:
+    """Get a specific version by ID."""
+    manager = get_version_manager()
+    version = await manager.get_version(version_id)
+
+    if not version:
+        raise HTTPException(status_code=404, detail=f"Version not found: {version_id}")
+
+    return _version_info_to_response(version)
+
+
+@router.get(
+    "/sources/{source_id}/latest",
+    response_model=VersionInfoResponse,
+    summary="Get latest version",
+    description="Get the most recent version for a data source.",
+)
+async def get_latest_version(
+    source_id: Annotated[str, Path(description="Source ID")],
+) -> VersionInfoResponse:
+    """Get the latest version for a source."""
+    manager = get_version_manager()
+    version = await manager.get_latest_version(source_id)
+
+    if not version:
+        raise HTTPException(
+            status_code=404,
+            detail=f"No versions found for source: {source_id}"
+        )
+
+    return _version_info_to_response(version)
+
+
+@router.post(
+    "/compare",
+    response_model=VersionDiffResponse,
+    summary="Compare two versions",
+    description="Compare two validation result versions and get detailed differences.",
+)
+async def compare_versions(
+    request: VersionCompareRequest,
+    validation_service: ValidationServiceDep,
+) -> VersionDiffResponse:
+    """Compare two versions and return differences."""
+    manager = get_version_manager()
+
+    # Get versions first to check they exist
+    from_version = await manager.get_version(request.from_version_id)
+    to_version = await manager.get_version(request.to_version_id)
+
+    if not from_version:
+        raise HTTPException(
+            status_code=404,
+            detail=f"From version not found: {request.from_version_id}"
+        )
+    if not to_version:
+        raise HTTPException(
+            status_code=404,
+            detail=f"To version not found: {request.to_version_id}"
+        )
+
+    # Try to get validation results for comparison
+    from_result = None
+    to_result = None
+
+    try:
+        from_validation = await validation_service.get_validation(from_version.validation_id)
+        if from_validation and from_validation.result_json:
+            from_result = from_validation.result_json
+    except Exception:
+        pass
+
+    try:
+        to_validation = await validation_service.get_validation(to_version.validation_id)
+        if to_validation and to_validation.result_json:
+            to_result = to_validation.result_json
+    except Exception:
+        pass
+
+    # Compare versions
+    diff = await manager.compare_versions(
+        from_version_id=request.from_version_id,
+        to_version_id=request.to_version_id,
+        from_result=from_result,
+        to_result=to_result,
+    )
+
+    return VersionDiffResponse(
+        from_version=_version_info_to_response(diff.from_version),
+        to_version=_version_info_to_response(diff.to_version),
+        issues_added=diff.issues_added,
+        issues_removed=diff.issues_removed,
+        issues_changed=diff.issues_changed,
+        summary_changes=diff.summary_changes,
+        has_changes=diff.has_changes,
+    )
+
+
+@router.get(
+    "/{version_id}/history",
+    response_model=VersionHistoryResponse,
+    summary="Get version history",
+    description="Get the version history chain starting from a specific version.",
+)
+async def get_version_history(
+    version_id: Annotated[str, Path(description="Starting version ID")],
+    depth: Annotated[int, Query(ge=1, le=50, description="Maximum history depth")] = 10,
+) -> VersionHistoryResponse:
+    """Get version history chain."""
+    manager = get_version_manager()
+
+    # Check version exists
+    version = await manager.get_version(version_id)
+    if not version:
+        raise HTTPException(status_code=404, detail=f"Version not found: {version_id}")
+
+    history = await manager.get_version_history(version_id=version_id, depth=depth)
+
+    return VersionHistoryResponse(
+        success=True,
+        data=[_version_info_to_response(v) for v in history],
+        depth=len(history),
+    )
+
+
+@router.post(
+    "/",
+    response_model=CreateVersionResponse,
+    summary="Create a version",
+    description="Create a new version for a validation result.",
+)
+async def create_version(
+    request: CreateVersionRequest,
+    validation_service: ValidationServiceDep,
+) -> CreateVersionResponse:
+    """Create a new version for a validation."""
+    # Get validation to verify it exists
+    validation = await validation_service.get_validation(request.validation_id)
+    if not validation:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Validation not found: {request.validation_id}"
+        )
+
+    manager = get_version_manager()
+
+    # Parse strategy
+    strategy = None
+    if request.strategy:
+        strategy = VersioningStrategy(request.strategy)
+
+    # Create version
+    version = await manager.create_version(
+        validation_id=request.validation_id,
+        source_id=validation.source_id,
+        result_json=validation.result_json,
+        strategy=strategy,
+        metadata=request.metadata,
+    )
+
+    return CreateVersionResponse(
+        success=True,
+        data=_version_info_to_response(version),
+        message=f"Created version {version.version_number} for validation {request.validation_id}",
+    )
+
+
+@router.get(
+    "/sources/{source_id}/rollback-availability",
+    response_model=RollbackAvailabilityResponse,
+    summary="Check rollback availability",
+    description="Check if rollback is available for a source and list available targets.",
+)
+async def check_rollback_availability(
+    source_id: Annotated[str, Path(description="Source ID")],
+) -> RollbackAvailabilityResponse:
+    """Check if rollback is available for a source."""
+    manager = get_version_manager()
+    availability = await manager.can_rollback(source_id)
+
+    return RollbackAvailabilityResponse(
+        success=True,
+        can_rollback=availability["can_rollback"],
+        current_version_id=availability["current_version_id"],
+        available_versions=availability["available_versions"],
+        rollback_targets=availability["rollback_targets"],
+    )
+
+
+@router.post(
+    "/sources/{source_id}/rollback",
+    response_model=RollbackResponse,
+    summary="Rollback to a previous version",
+    description="Rollback a source to a previous validation result version.",
+)
+async def rollback_to_version(
+    source_id: Annotated[str, Path(description="Source ID")],
+    request: RollbackRequest,
+) -> RollbackResponse:
+    """Rollback to a previous version."""
+    manager = get_version_manager()
+
+    # Perform rollback
+    result = await manager.rollback_to_version(
+        source_id=source_id,
+        target_version_id=request.target_version_id,
+        create_new_validation=request.create_new_validation,
+    )
+
+    if not result.success:
+        raise HTTPException(
+            status_code=400,
+            detail=result.message,
+        )
+
+    return RollbackResponse(
+        success=result.success,
+        source_id=result.source_id,
+        from_version=_version_info_to_response(result.from_version) if result.from_version else None,
+        to_version=_version_info_to_response(result.to_version) if result.to_version else None,
+        new_validation_id=result.new_validation_id,
+        message=result.message,
+        rolled_back_at=result.rolled_back_at,
+    )

truthound_dashboard/api/websocket.py

@@ -0,0 +1,301 @@
+"""WebSocket API endpoints.
+
+This module provides WebSocket endpoints for real-time updates.
+
+Endpoints:
+    WebSocket /ws/notifications/incidents - Real-time escalation incident updates
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import uuid
+from typing import Any
+
+from fastapi import APIRouter, Query, WebSocket, WebSocketDisconnect
+
+from ..core.websocket import (
+    WebSocketManager,
+    WebSocketMessage,
+    WebSocketMessageType,
+    get_websocket_manager,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+# Room name for incident updates
+INCIDENTS_ROOM = "incidents"
+
+
+@router.websocket("/ws/notifications/incidents")
+async def websocket_incidents(
+    websocket: WebSocket,
+    token: str | None = Query(default=None, description="Optional authentication token"),
+) -> None:
+    """WebSocket endpoint for real-time escalation incident updates.
+
+    This endpoint allows clients to receive real-time updates about escalation
+    incidents, including creation, state changes, and resolution.
+
+    Query Parameters:
+        token: Optional authentication token for secure connections.
+
+    Message Types Received:
+        - ping: Client heartbeat, server responds with pong
+        - pong: Response to server ping
+
+    Message Types Sent:
+        - connected: Sent when connection is established
+        - ping: Server heartbeat
+        - pong: Response to client ping
+        - incident_created: New incident created
+        - incident_updated: Incident updated
+        - incident_state_changed: Incident state changed
+        - incident_acknowledged: Incident acknowledged
+        - incident_escalated: Incident escalated to next level
+        - incident_resolved: Incident resolved
+
+    Example Client Connection (JavaScript):
+        const ws = new WebSocket('ws://localhost:8765/api/v1/ws/notifications/incidents');
+
+        ws.onmessage = (event) => {
+            const message = JSON.parse(event.data);
+            switch (message.type) {
+                case 'incident_created':
+                    handleNewIncident(message.data);
+                    break;
+                case 'incident_state_changed':
+                    handleStateChange(message.data);
+                    break;
+                // ... handle other message types
+            }
+        };
+
+        // Send ping to keep connection alive
+        setInterval(() => {
+            ws.send(JSON.stringify({ type: 'ping' }));
+        }, 30000);
+    """
+    manager = get_websocket_manager()
+    connection_id = str(uuid.uuid4())
+
+    # Optional: Validate token if provided
+    # In production, implement proper authentication
+    if token:
+        logger.debug(f"WebSocket connection with token: {token[:8]}...")
+
+    try:
+        # Accept connection and register
+        connection = await manager.connect(
+            websocket=websocket,
+            connection_id=connection_id,
+            token=token,
+        )
+
+        # Join the incidents room for broadcast updates
+        await manager.join_room(connection, INCIDENTS_ROOM)
+
+        logger.info(
+            f"Client connected to incidents WebSocket: {connection_id}"
+        )
+
+        # Handle incoming messages
+        while True:
+            try:
+                data = await websocket.receive_json()
+                await manager.handle_client_message(connection, data)
+            except WebSocketDisconnect:
+                break
+            except Exception as e:
+                logger.warning(
+                    f"Error receiving message from {connection_id}: {e}"
+                )
+                # Send error message
+                await connection.send_message(
+                    WebSocketMessage(
+                        type=WebSocketMessageType.ERROR,
+                        data={"error": str(e)},
+                    )
+                )
+
+    except WebSocketDisconnect:
+        logger.info(f"Client disconnected from incidents WebSocket: {connection_id}")
+    except Exception as e:
+        logger.error(f"WebSocket error for {connection_id}: {e}")
+    finally:
+        await manager.disconnect(connection_id, reason="Connection closed")
+
+
+async def broadcast_incident_event(
+    event_type: WebSocketMessageType,
+    incident_data: dict[str, Any],
+) -> int:
+    """Broadcast an incident event to all connected clients.
+
+    Args:
+        event_type: Type of the event.
+        incident_data: Incident data to broadcast.
+
+    Returns:
+        Number of clients that received the message.
+    """
+    manager = get_websocket_manager()
+
+    message = WebSocketMessage(
+        type=event_type,
+        data=incident_data,
+    )
+
+    return await manager.broadcast_to_room(INCIDENTS_ROOM, message)
+
+
+async def notify_incident_created(
+    incident_id: str,
+    incident_ref: str,
+    policy_id: str,
+    state: str,
+    current_level: int,
+    context: dict[str, Any] | None = None,
+) -> int:
+    """Notify clients about a new incident.
+
+    Args:
+        incident_id: ID of the new incident.
+        incident_ref: External reference.
+        policy_id: Associated policy ID.
+        state: Initial state.
+        current_level: Initial escalation level.
+        context: Optional incident context.
+
+    Returns:
+        Number of clients notified.
+    """
+    return await broadcast_incident_event(
+        WebSocketMessageType.INCIDENT_CREATED,
+        {
+            "incident_id": incident_id,
+            "incident_ref": incident_ref,
+            "policy_id": policy_id,
+            "state": state,
+            "current_level": current_level,
+            "context": context or {},
+        },
+    )
+
+
+async def notify_incident_state_changed(
+    incident_id: str,
+    incident_ref: str,
+    policy_id: str,
+    from_state: str,
+    to_state: str,
+    current_level: int,
+    actor: str | None = None,
+    message: str | None = None,
+) -> int:
+    """Notify clients about an incident state change.
+
+    Args:
+        incident_id: ID of the incident.
+        incident_ref: External reference.
+        policy_id: Associated policy ID.
+        from_state: Previous state.
+        to_state: New state.
+        current_level: Current escalation level.
+        actor: Who triggered the change.
+        message: Optional message.
+
+    Returns:
+        Number of clients notified.
+    """
+    # Determine specific event type based on new state
+    if to_state == "acknowledged":
+        event_type = WebSocketMessageType.INCIDENT_ACKNOWLEDGED
+    elif to_state == "resolved":
+        event_type = WebSocketMessageType.INCIDENT_RESOLVED
+    elif to_state == "escalated":
+        event_type = WebSocketMessageType.INCIDENT_ESCALATED
+    else:
+        event_type = WebSocketMessageType.INCIDENT_STATE_CHANGED
+
+    return await broadcast_incident_event(
+        event_type,
+        {
+            "incident_id": incident_id,
+            "incident_ref": incident_ref,
+            "policy_id": policy_id,
+            "from_state": from_state,
+            "to_state": to_state,
+            "current_level": current_level,
+            "actor": actor,
+            "message": message,
+        },
+    )
+
+
+async def notify_incident_updated(
+    incident_id: str,
+    incident_ref: str,
+    policy_id: str,
+    state: str,
+    current_level: int,
+    changes: dict[str, Any] | None = None,
+) -> int:
+    """Notify clients about an incident update.
+
+    Args:
+        incident_id: ID of the incident.
+        incident_ref: External reference.
+        policy_id: Associated policy ID.
+        state: Current state.
+        current_level: Current escalation level.
+        changes: Optional dictionary of changed fields.
+
+    Returns:
+        Number of clients notified.
+    """
+    return await broadcast_incident_event(
+        WebSocketMessageType.INCIDENT_UPDATED,
+        {
+            "incident_id": incident_id,
+            "incident_ref": incident_ref,
+            "policy_id": policy_id,
+            "state": state,
+            "current_level": current_level,
+            "changes": changes or {},
+        },
+    )
+
+
+async def notify_incident_resolved(
+    incident_id: str,
+    incident_ref: str,
+    policy_id: str,
+    resolved_by: str | None = None,
+    message: str | None = None,
+) -> int:
+    """Notify clients about an incident resolution.
+
+    Args:
+        incident_id: ID of the incident.
+        incident_ref: External reference.
+        policy_id: Associated policy ID.
+        resolved_by: Who resolved it.
+        message: Resolution message.
+
+    Returns:
+        Number of clients notified.
+    """
+    return await broadcast_incident_event(
+        WebSocketMessageType.INCIDENT_RESOLVED,
+        {
+            "incident_id": incident_id,
+            "incident_ref": incident_ref,
+            "policy_id": policy_id,
+            "resolved_by": resolved_by,
+            "message": message,
+        },
+    )

truthound_dashboard/core/__init__.py

@@ -117,6 +117,20 @@ from .sampling import (
     get_sampler,
     reset_sampler,
 )
+from .validation_limits import (
+    DeduplicationLimits,
+    EscalationLimits,
+    ThrottlingLimits,
+    TimeWindowLimits,
+    ValidationLimitError,
+    clear_limits_cache,
+    get_deduplication_limits,
+    get_escalation_limits,
+    get_throttling_limits,
+    get_time_window_limits,
+    validate_positive_float,
+    validate_positive_int,
+)
 from .scheduler import (
     ValidationScheduler,
     get_scheduler,
@@ -281,4 +295,17 @@ __all__ = [
     "CatalogService",
     "CollaborationService",
     "ActivityLogger",
+    # Validation Limits (DoS Prevention)
+    "ValidationLimitError",
+    "DeduplicationLimits",
+    "ThrottlingLimits",
+    "EscalationLimits",
+    "TimeWindowLimits",
+    "get_deduplication_limits",
+    "get_throttling_limits",
+    "get_escalation_limits",
+    "get_time_window_limits",
+    "clear_limits_cache",
+    "validate_positive_int",
+    "validate_positive_float",
 ]