# Source code for aioxmpp.tracking

    ########################################################################
    # File name: tracking.py
    # This file is part of: aioxmpp
    #
    # LICENSE
    #
    # This program is free software: you can redistribute it and/or modify
    # it under the terms of the GNU Lesser General Public License as
    # published by the Free Software Foundation, either version 3 of the
    # License, or (at your option) any later version.
    #
    # This program is distributed in the hope that it will be useful, but
    # WITHOUT ANY WARRANTY; without even the implied warranty of
    # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    # Lesser General Public License for more details.
    #
    # You should have received a copy of the GNU Lesser General Public
    # License along with this program.  If not, see
    # <http://www.gnu.org/licenses/>.
    #
    ########################################################################
    """
    :mod:`~aioxmpp.tracking` --- Interfaces for high-level message tracking
    #######################################################################

    This submodule provides interfaces for tracking messages to the recipient. The
    actual tracking is not implemented here.

    .. versionadded:: 0.5

       This module was added in version 0.5.

    .. versionchanged:: 0.9

       This module was completely rewritten in 0.9.

    .. seealso::

       Method :meth:`~.muc.Room.send_tracked_message`
         implements tracking for messages sent through a MUC.

    .. _api-tracking-memory:

    General Remarks about Tracking and Memory Consumption
    =====================================================

    Tracking stanzas costs memory. There are basically two options on how to
    implement the management of additional information:

    1. Either the tracking stops when the :class:`MessageTracker` is released (i.e.
       the last reference to it gets collected).

    2. Or the tracking is stopped explicitly by the user.

    Option (1) has the appeal that users (applications) do not have to worry about
    properly releasing the tracking objects. However, it has the downside that
    applications have to keep the :class:`MessageeTracker` instance around.
    Remember that connecting to callbacks of an object is *not* enough to keep it
    alive.

    Option (2) is somewhat like file objects work: in theory, you have to close
    them explicitly and manually: if you do not, there is no guarantee when the
    file is actually closed. It is thus a somewhat known Python idiom, and also is
    more explicit. And it doesn’t break callbacks.

    The implementation of :class:`MessageTracker` uses **Option 2**. So you have to
    :meth:`MessageTracker.close` all :class:`MessageTracker` objects to ensure that
    all tracking resources associated with it are released; this stops any tracking
    which is still in progress.

    It is strongly recommended that you close message trackers after a timeout. You
    can use :meth:`MessageTracker.set_timeout` for that, or manually call
    :meth:`MessageTracker.close` as desired.

    Tracking implementations
    ========================

    .. autoclass:: BasicTrackingService

    Interfaces
    ==========

    .. autoclass:: MessageTracker

    .. autoclass:: MessageState

    """
    import asyncio
    import functools

    from datetime import timedelta
    from enum import Enum

    import aioxmpp.callbacks
    import aioxmpp.service

    class MessageState(Enum):
        """
        Enumeration of possible states for :class:`MessageTracker`. These states
        are used to inform using code about the delivery state of a message. See
        :class:`MessageTracker` for details.

        .. versionchanged:: 0.10

            The :attr:`ERROR` state is no longer final. Tracking implementations
            may now trump an error state with another state in some cases.

            An example would be :xep:`184` message delivery receipts which can
            for sure attest an :attr:`DELIVERED_TO_RECIPIENT` state. This is more
            useful than an error reply.

        .. attribute:: ABORTED

           The message has been aborted or dropped in the :class:`~.StanzaStream`
           queues. See :class:`~.StanzaToken` and :attr:`MessageTracker.token`.

           This is a final state.

        .. attribute:: ERROR

           An error reply stanza has been received for the stanza which was sent.

           This is, in most cases, a final state, but transitions to
           :attr:`DELIVERED_TO_RECIPIENT` and :attr:`SEEN_BY_RECIPIENT` are
           allowed.

        .. attribute:: IN_TRANSIT

           The message is still queued for sending or has been sent to the peer
           server without stream management.

           Depending on the tracking implementation, this may be a final state.

        .. attribute:: DELIVERED_TO_SERVER

           The message has been delivered to the server and the server acked the
           delivery using stream management.

           Depending on the tracking implementation, this may be a final state.

        .. attribute:: DELIVERED_TO_RECIPIENT

           The message has been delivered to the recipient.

           Depending on the tracking implementation, this may be a final state.

        .. attribute:: SEEN_BY_RECIPIENT

           The recipient has marked the message as seen or read. This is a final
           state.

        """

        IN_TRANSIT = 0
        ABORTED = 1
        ERROR = 2
        DELIVERED_TO_SERVER = 3
        DELIVERED_TO_RECIPIENT = 4
        SEEN_BY_RECIPIENT = 5

    class MessageTracker:
        """
        This is the high-level equivalent of the :class:`~.StanzaToken`.

        This structure is used by different tracking implementations. The interface
        of this class is split in two parts:

        1. The public interface for use by applications.
        2. The "protected" interface for use by tracking implementations.

        :class:`MessageTracker` objects are designed to be drivable from multiple
        tracking implementations at once. The idea is that different tracking
        implementations can cover different parts of the path a stanza takes: one
        can cover the path to the server (by hooking into the events of a
        :class:`~.StanzaToken`), the other implementation can use e.g. :xep:`184` to
        determine delivery at the target and so on.

        Methods and attributes from the "protected" interface are marked by a
        leading underscore.

        .. autoattribute:: state

        .. autoattribute:: response

        .. autoattribute:: closed

        .. signal:: on_state_changed(new_state, response=None)

           Emits when a new state is entered.

           :param new_state: The new state of the tracker.
           :type new_state: :class:`~.MessageState` member
           :param response: A stanza related to the state.
           :type response: :class:`~.StanzaBase` or :data:`None`

           The is *not* emitted when the tracker is closed.

        .. signal:: on_closed()

           Emits when the tracker is closed.

        .. automethod:: close

        .. automethod:: set_timeout

        "Protected" interface:

        .. automethod:: _set_state

        """

        on_closed = aioxmpp.callbacks.Signal()
        on_state_changed = aioxmpp.callbacks.Signal()

        def __init__(self):
            super().__init__()
            self._state = MessageState.IN_TRANSIT
            self._response = None
            self._closed = False

        @property
        def state(self):
            """
            The current state of the tracking. Read-only.
            """
            return self._state

        @property
        def response(self):
            """
            A stanza which is relevant to the current state. For
            :attr:`.MessageState.ERROR`, this will generally be a
            :class:`.MessageType.ERROR` stanza. For other states, this is either
            :data:`None` or another stanza depending on the tracking
            implementation.
            """
            return self._response

        @property
        def closed(self):
            """
            Boolean indicator whether the tracker is closed.

            .. seealso::

               :meth:`close` for details.
            """
            return self._closed

        def close(self):
            """
            Close the tracking, clear all references to the tracker and release all
            tracking-related resources.

            This operation is idempotent. It does not change the :attr:`state`, but
            :attr:`closed` turns :data:`True`.

            The :meth:`on_closed` event is only fired on the first call to
            :meth:`close`.
            """
            if self._closed:
                return
            self._closed = True
            self.on_closed()

        def set_timeout(self, timeout):
            """
            Automatically close the tracker after `timeout` has elapsed.

            :param timeout: The timeout after which the tracker is closed
                            automatically.
            :type timeout: :class:`numbers.Real` or :class:`datetime.timedelta`

            If the `timeout` is not a :class:`datetime.timedelta` instance, it is
            assumed to be given as seconds.

            The timeout cannot be cancelled after it has been set. It starts at the
            very moment :meth:`set_timeout` is called.
            """
            loop = asyncio.get_event_loop()

            if isinstance(timeout, timedelta):
                timeout = timeout.total_seconds()

            loop.call_later(timeout, self.close)

        # "Protected" Interface

        def _set_state(self, new_state, response=None):
            """
            Set the state of the tracker.

            :param new_state: The new state of the tracker.
            :type new_state: :class:`~.MessageState` member
            :param response: A stanza related to the new state.
            :type response: :class:`~.StanzaBase` or :data:`None`
            :raise ValueError: if a forbidden state transition is attempted.
            :raise RuntimeError: if the tracker is closed.

            The state of the tracker is set to the `new_state`. The
            :attr:`response` is also overriden with the new value, no matter if the
            new or old value is :data:`None` or not. The :meth:`on_state_changed`
            event is emitted.

            The following transitions are forbidden and attempting to perform them
            will raise :class:`ValueError`:

            * any state -> :attr:`~.MessageState.IN_TRANSIT`
            * :attr:`~.MessageState.DELIVERED_TO_RECIPIENT` ->
              :attr:`~.MessageState.DELIVERED_TO_SERVER`
            * :attr:`~.MessageState.SEEN_BY_RECIPIENT` ->
              :attr:`~.MessageState.DELIVERED_TO_RECIPIENT`
            * :attr:`~.MessageState.SEEN_BY_RECIPIENT` ->
              :attr:`~.MessageState.DELIVERED_TO_SERVER`
            * :attr:`~.MessageState.ABORTED` -> any state
            * :attr:`~.MessageState.ERROR` -> any state

            If the tracker is already :meth:`close`\ -d, :class:`RuntimeError` is
            raised. This check happens *before* a test is made whether the
            transition is valid.

            This method is part of the "protected" interface.
            """
            if self._closed:
                raise RuntimeError("message tracker is closed")

            # reject some transitions as documented
            if (self._state == MessageState.ABORTED or
                    new_state == MessageState.IN_TRANSIT or
                    (self._state == MessageState.ERROR and
                     new_state == MessageState.DELIVERED_TO_SERVER) or
                    (self._state == MessageState.ERROR and
                     new_state == MessageState.ABORTED) or
                    (self._state == MessageState.DELIVERED_TO_RECIPIENT and
                     new_state == MessageState.DELIVERED_TO_SERVER) or
                    (self._state == MessageState.SEEN_BY_RECIPIENT and
                     new_state == MessageState.DELIVERED_TO_SERVER) or
                    (self._state == MessageState.SEEN_BY_RECIPIENT and
                     new_state == MessageState.DELIVERED_TO_RECIPIENT)):
                raise ValueError(
                    "message tracker transition from {} to {} not allowed".format(
                        self._state,
                        new_state
                    )
                )

            self._state = new_state
            self._response = response
            self.on_state_changed(self._state, self._response)

    class BasicTrackingService(aioxmpp.service.Service):
        """
        Error handling and :class:`~.StanzaToken`\ -based tracking for messages.

        This service provides the most basic tracking of message stanzas. It can be
        combined with other forms of tracking.

        Specifically, the stanza is tracked using the means of
        :class:`~.StanzaToken`, that is, until it is acknowledged by the server. In
        addition, error stanzas in reply to the message are also tracked (but they
        do not override states occuring after
        :attr:`~.MessageState.DELIVERED_TO_SERVER`).

        Tracking stanzas:

        .. automethod:: send_tracked

        .. automethod:: attach_tracker
        """

        def __init__(self, client, **kwargs):
            super().__init__(client, **kwargs)
            self._trackers = {}

        @aioxmpp.service.inbound_message_filter
        def _inbound_message_filter(self, message):
            try:
                if message.type_ != aioxmpp.MessageType.ERROR:
                    return message
            except AttributeError:
                return message

            try:
                key = message.from_.bare(), message.id_
            except AttributeError:
                return message

            try:
                tracker = self._trackers.pop(key)
            except KeyError:
                return message

            if tracker.state == MessageState.DELIVERED_TO_RECIPIENT:
                return
            if tracker.state == MessageState.SEEN_BY_RECIPIENT:
                return
            tracker._set_state(MessageState.ERROR, message)

        def _tracker_closed(self, key):
            self._trackers.pop(key, None)

        def _stanza_sent(self, tracker, token, fut):
            # FIXME: look into whether this is correct, and if it is, document why:
            #
            # - CancelledError does not lead to ABORTED
            # - why it makes sense to channel all *other* exceptions into
            #   ABORTED state
            try:
                fut.result()
            except asyncio.CancelledError:
                return
            except:
                next_state = MessageState.ABORTED
            else:
                next_state = MessageState.DELIVERED_TO_SERVER
            try:
                tracker._set_state(next_state)
            except ValueError:
                pass

        def send_tracked(self, stanza, tracker):
            """
            Send a message stanza with tracking.

            :param stanza: Message stanza to send.
            :type stanza: :class:`aioxmpp.Message`
            :param tracker: Message tracker to use.
            :type tracker: :class:`~.MessageTracker`
            :rtype: :class:`~.StanzaToken`
            :return: The token used to send the stanza.

            If `tracker` is :data:`None`, a new :class:`~.MessageTracker` is
            created.

            This configures tracking for the stanza as if by calling
            :meth:`attach_tracker` with a `token` and sends the stanza through the
            stream.

            .. seealso::

               :meth:`attach_tracker`
                  can be used if the stanza cannot be sent (e.g. because it is a
                  carbon-copy) or has already been sent.
            """
            token = self.client.enqueue(stanza)
            self.attach_tracker(stanza, tracker, token)
            return token

        def attach_tracker(self, stanza, tracker=None, token=None):
            """
            Configure tracking for a stanza without sending it.

            :param stanza: Message stanza to send.
            :type stanza: :class:`aioxmpp.Message`
            :param tracker: Message tracker to use.
            :type tracker: :class:`~.MessageTracker` or :data:`None`
            :param token: Optional stanza token for more fine-grained tracking.
            :type token: :class:`~.StanzaToken`
            :rtype: :class:`~.MessageTracker`
            :return: The message tracker.

            If `tracker` is :data:`None`, a new :class:`~.MessageTracker` is
            created.

            If `token` is not :data:`None`, updates to the stanza `token` are
            reflected in the `tracker`.

            If an error reply is received, the tracker will enter
            :class:`~.MessageState.ERROR` and the error will be set as
            :attr:`~.MessageTracker.response`.

            You should use :meth:`send_tracked` if possible. This method however is
            very useful if you need to track carbon copies of sent messages, as a
            stanza token is not available here and re-sending the message to obtain
            one is generally not desirable ☺.
            """
            if tracker is None:
                tracker = MessageTracker()
            stanza.autoset_id()
            key = stanza.to.bare(), stanza.id_
            self._trackers[key] = tracker
            tracker.on_closed.connect(
                functools.partial(self._tracker_closed, key)
            )
            if token is not None:
                token.future.add_done_callback(
                    functools.partial(
                        self._stanza_sent,
                        tracker,
                        token,
                    )
                )
            return tracker