gogo2/COBY/interfaces/replay_manager.py

"""
Interface for historical data replay functionality.
"""

from abc import ABC, abstractmethod
from datetime import datetime
from typing import List, Optional, Callable, Dict, Any
from ..models.core import ReplaySession, ReplayStatus


class ReplayManager(ABC):
    """Provides historical data replay functionality"""
    
    @abstractmethod
    def create_replay_session(self, start_time: datetime, end_time: datetime,
                            speed: float = 1.0, symbols: Optional[List[str]] = None,
                            exchanges: Optional[List[str]] = None) -> str:
        """
        Create a new replay session.
        
        Args:
            start_time: Replay start time
            end_time: Replay end time
            speed: Playback speed multiplier (1.0 = real-time)
            symbols: List of symbols to replay (None = all)
            exchanges: List of exchanges to replay (None = all)
            
        Returns:
            str: Session ID
        """
        pass
    
    @abstractmethod
    async def start_replay(self, session_id: str) -> None:
        """
        Start replay session.
        
        Args:
            session_id: Session ID to start
        """
        pass
    
    @abstractmethod
    async def pause_replay(self, session_id: str) -> None:
        """
        Pause replay session.
        
        Args:
            session_id: Session ID to pause
        """
        pass
    
    @abstractmethod
    async def resume_replay(self, session_id: str) -> None:
        """
        Resume paused replay session.
        
        Args:
            session_id: Session ID to resume
        """
        pass
    
    @abstractmethod
    async def stop_replay(self, session_id: str) -> None:
        """
        Stop replay session.
        
        Args:
            session_id: Session ID to stop
        """
        pass
    
    @abstractmethod
    def get_replay_status(self, session_id: str) -> Optional[ReplaySession]:
        """
        Get replay session status.
        
        Args:
            session_id: Session ID
            
        Returns:
            ReplaySession: Session status or None if not found
        """
        pass
    
    @abstractmethod
    def list_replay_sessions(self) -> List[ReplaySession]:
        """
        List all replay sessions.
        
        Returns:
            List[ReplaySession]: List of all sessions
        """
        pass
    
    @abstractmethod
    def delete_replay_session(self, session_id: str) -> bool:
        """
        Delete replay session.
        
        Args:
            session_id: Session ID to delete
            
        Returns:
            bool: True if deleted successfully, False otherwise
        """
        pass
    
    @abstractmethod
    def set_replay_speed(self, session_id: str, speed: float) -> bool:
        """
        Change replay speed for active session.
        
        Args:
            session_id: Session ID
            speed: New playback speed multiplier
            
        Returns:
            bool: True if speed changed successfully, False otherwise
        """
        pass
    
    @abstractmethod
    def seek_replay(self, session_id: str, timestamp: datetime) -> bool:
        """
        Seek to specific timestamp in replay.
        
        Args:
            session_id: Session ID
            timestamp: Target timestamp
            
        Returns:
            bool: True if seek successful, False otherwise
        """
        pass
    
    @abstractmethod
    def add_data_callback(self, session_id: str, callback: Callable) -> bool:
        """
        Add callback for replay data.
        
        Args:
            session_id: Session ID
            callback: Function to call with replay data
                     Signature: callback(data: Union[OrderBookSnapshot, TradeEvent])
            
        Returns:
            bool: True if callback added successfully, False otherwise
        """
        pass
    
    @abstractmethod
    def remove_data_callback(self, session_id: str, callback: Callable) -> bool:
        """
        Remove data callback from replay session.
        
        Args:
            session_id: Session ID
            callback: Callback function to remove
            
        Returns:
            bool: True if callback removed successfully, False otherwise
        """
        pass
    
    @abstractmethod
    def add_status_callback(self, session_id: str, callback: Callable) -> bool:
        """
        Add callback for replay status changes.
        
        Args:
            session_id: Session ID
            callback: Function to call on status change
                     Signature: callback(session_id: str, status: ReplayStatus)
            
        Returns:
            bool: True if callback added successfully, False otherwise
        """
        pass
    
    @abstractmethod
    async def get_available_data_range(self, symbol: str, 
                                     exchange: Optional[str] = None) -> Optional[Dict[str, datetime]]:
        """
        Get available data time range for replay.
        
        Args:
            symbol: Trading symbol
            exchange: Exchange name (None = all exchanges)
            
        Returns:
            Dict: {'start': datetime, 'end': datetime} or None if no data
        """
        pass
    
    @abstractmethod
    def validate_replay_request(self, start_time: datetime, end_time: datetime,
                              symbols: Optional[List[str]] = None,
                              exchanges: Optional[List[str]] = None) -> List[str]:
        """
        Validate replay request parameters.
        
        Args:
            start_time: Requested start time
            end_time: Requested end time
            symbols: Requested symbols
            exchanges: Requested exchanges
            
        Returns:
            List[str]: List of validation errors (empty if valid)
        """
        pass