# `tracking` — Interfaces for high-level message tracking

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

New in version 0.5: This module was added in version 0.5.

Changed in version 0.9: This module was completely rewritten in 0.9.

See also

Method `send_tracked_message()`

  implements tracking for messages sent through a MUC.

## 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 `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 `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 `MessageTracker` uses Option 2. So you have to `MessageTracker.close()` all `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 `MessageTracker.set_timeout()` for that, or manually call `MessageTracker.close()` as desired.

## Tracking implementations

class aioxmpp.tracking.BasicTrackingService(client, **kwargs)

  Error handling and `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 `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 occurring after `DELIVERED_TO_SERVER`).

  Tracking stanzas:

  send_tracked(stanza, tracker)

    Send a message stanza with tracking.

    Parameters:

      - stanza (`aioxmpp.Message`) – Message stanza to send.

      - tracker (`MessageTracker`) – Message tracker to use.

    Return type:

      `StanzaToken`

    Returns:

      The token used to send the stanza.

    If tracker is `None`, a new `MessageTracker` is created.

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

    See also

    `attach_tracker()`

      can be used if the stanza cannot be sent (e.g. because it is a carbon-copy) or has already been sent.

  attach_tracker(stanza, tracker=None, token=None)

    Configure tracking for a stanza without sending it.

    Parameters:

      - stanza (`aioxmpp.Message`) – Message stanza to send.

      - tracker (`MessageTracker` or `None`) – Message tracker to use.

      - token (`StanzaToken`) – Optional stanza token for more fine-grained tracking.

    Return type:

      `MessageTracker`

    Returns:

      The message tracker.

    If tracker is `None`, a new `MessageTracker` is created.

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

    If an error reply is received, the tracker will enter `ERROR` and the error will be set as `response`.

    You should use `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 ☺.

## Interfaces

class aioxmpp.tracking.MessageTracker

  This is the high-level equivalent of the `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.

  `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 `StanzaToken`), the other implementation can use e.g. XEP-0184 to determine delivery at the target and so on.

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

  state

    The current state of the tracking. Read-only.

  response

    A stanza which is relevant to the current state. For `MessageState.ERROR`, this will generally be a `MessageType.ERROR` stanza. For other states, this is either `None` or another stanza depending on the tracking implementation.

  closed

    Boolean indicator whether the tracker is closed.

    See also

    `close()` for details.

  signal on_state_changed(new_state, response=None)

    Emits when a new state is entered.

    Parameters:

      - new_state (`MessageState` member) – The new state of the tracker.

      - response (`StanzaBase` or `None`) – A stanza related to the state.

    The is not emitted when the tracker is closed.

  signal on_closed()

    Emits when the tracker is closed.

  close()

    Close the tracking, clear all references to the tracker and release all tracking-related resources.

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

    The `on_closed()` event is only fired on the first call to `close()`.

  set_timeout(timeout)

    Automatically close the tracker after timeout has elapsed.

    Parameters:

      timeout (`numbers.Real` or `datetime.timedelta`) – The timeout after which the tracker is closed automatically.

    If the timeout is not a `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 `set_timeout()` is called.

  “Protected” interface:

  _set_state(new_state, response=None)

    Set the state of the tracker.

    Parameters:

      - new_state (`MessageState` member) – The new state of the tracker.

      - response (`StanzaBase` or `None`) – A stanza related to the new state.

    Raises:

      - ValueError – if a forbidden state transition is attempted.

      - RuntimeError – if the tracker is closed.

    The state of the tracker is set to the new_state. The `response` is also overridden with the new value, no matter if the new or old value is `None` or not. The `on_state_changed()` event is emitted.

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

    - any state -> `IN_TRANSIT`

    - `DELIVERED_TO_RECIPIENT` -> `DELIVERED_TO_SERVER`

    - `SEEN_BY_RECIPIENT` -> `DELIVERED_TO_RECIPIENT`

    - `SEEN_BY_RECIPIENT` -> `DELIVERED_TO_SERVER`

    - `ABORTED` -> any state

    - `ERROR` -> any state

    If the tracker is already `close()`-d, `RuntimeError` is raised. This check happens before a test is made whether the transition is valid.

    This method is part of the “protected” interface.

class aioxmpp.tracking.MessageState(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

  Enumeration of possible states for `MessageTracker`. These states are used to inform using code about the delivery state of a message. See `MessageTracker` for details.

  Changed in version 0.10: The `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-0184 message delivery receipts which can for sure attest an `DELIVERED_TO_RECIPIENT` state. This is more useful than an error reply.

  ABORTED

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

    This is a final state.

  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 `DELIVERED_TO_RECIPIENT` and `SEEN_BY_RECIPIENT` are allowed.

  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.

  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.

  DELIVERED_TO_RECIPIENT

    The message has been delivered to the recipient.

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

  SEEN_BY_RECIPIENT

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