"""Interface for creating payload events generated by Sources.

EventProviders define what events a Source generates at each tick.
Implementations create domain-specific events (e.g., HTTP requests,
messages) with appropriate targets and payloads.
"""

from abc import ABC, abstractmethod
from typing import List, Union

from happysimulator.core.event import Event
from happysimulator.core.temporal import Instant


class EventProvider(ABC):
    """Abstract factory for creating payload events at specified times.

    Implement this interface to define what events a Source generates.
    Called by Source.handle_event() at each tick.
    """

    @abstractmethod
    def get_events(self, time: Instant) -> Union[Event, List[Event]]:
        """Create one or more events to be scheduled at the given time.

        Args:
            time: The simulation time when these events should occur.

        Returns:
            A single Event or list of Events to schedule.
        """
        pass