"""
Base Handler ABC — defines the interface for job-type-specific execution logic.

A Handler knows HOW to execute a specific kind of job (transcode, chunk, etc.).
The Executor decides WHERE to run it (local, Lambda, GCP).
"""

from abc import ABC, abstractmethod
from typing import Any, Callable, Dict, Optional


class Handler(ABC):
    """Abstract base class for job handlers."""

    @abstractmethod
    def process(
        self,
        job_id: str,
        payload: Dict[str, Any],
        progress_callback: Optional[Callable[[int, Dict[str, Any]], None]] = None,
    ) -> Dict[str, Any]:
        """
        Execute job-specific logic.

        Args:
            job_id: Unique job identifier
            payload: Job-type-specific configuration
            progress_callback: Called with (percent, details_dict)

        Returns:
            Result dict with at least {"status": "completed"} or raises
        """
        pass