"""Protocole abstrait définissant le contrat des canaux de sortie."""

from __future__ import annotations

from typing import Protocol, runtime_checkable

from pronote_sync.models.xmpp import XmppMessage


@runtime_checkable
class Channel(Protocol):
    """Contrat structurel d'un canal de sortie du pipeline.

    Un canal de sortie reçoit un message final :class:`XmppMessage` et tente de
    l'envoyer vers la destination qu'il représente (CalDAV, XMPP, etc.).

    :ivar send: Envoie un message sur le canal.
    """

    def send(self, message: XmppMessage) -> bool:
        """Envoie un message sur le canal.

        Un canal ne lève jamais :pyexc:`PipelineWarning` ; en cas d'échec, il
        retourne ``False``. Le :pyexc:`PipelineWarning` est créé par l'étape
        pipeline, pas par le canal. Une :pyexc:`PipelineCriticalError` peut
        en revanche être levée en cas de panne critique (ex. : chemin
        CalDAV, non utilisé par le canal XMPP).

        :param message: Message final à transmettre.
        :return: ``True`` si l'envoi a réussi, ``False`` sinon.
        :rtype: bool
        """
        ...