"""Definition of QueueRepositoryInterface protocol."""

from abc import abstractmethod
from datetime import datetime
from typing import Any, Protocol, runtime_checkable


@runtime_checkable
class QueueRepositoryInterface(Protocol):
    """Interface that defines buffered queue enqueue/dequeue methods."""

    @abstractmethod
    def enqueue(self, items: list[dict[str, Any]]) -> None:
        """Append items to the queue.

        Duplicates may be skipped when the implementation is configured with
        dedup keys. An empty list is a no-op.
        """
        ...

    @abstractmethod
    def dequeue_batch(self, *, max_items: int = 1000) -> list[dict[str, Any]]:
        """Remove and return up to ``max_items`` items in FIFO order.

        Returns an empty list when the queue is empty.
        """
        ...

    @abstractmethod
    def size(self) -> int:
        """Return the number of items currently in the queue."""
        ...

    @abstractmethod
    def evict_older_than(self, cutoff: datetime) -> int:
        """Remove items older than ``cutoff`` and return how many were removed.

        Age is determined by an implementation-specific item field. When no age
        field is configured, this is a no-op that returns ``0``.
        """
        ...