Client design

The client is designed to be resilent against connection failures. The key part for this is to implement XEP-0198 (Stream Management), which supports resuming a previous session without losing messages.

Queues

The client features multiple queues:

Active queue

The active queue is the queue where stanzas are stored which are about to be submitted to the XMPP server. This queue should be empty most of the time, but messages may aggregate while connection issues are taking place. The active queue cannot be introspected from outside the client.

Hold queue

Stanzas cannot be placed into the hold queue directly; however, if resumption of a stream fails (e.g. because the server doesn’t support stream management), the stanzas from the active queue are moved into the hold queue, for manual review by the user (it might make sense to not re-send some messages, e.g. if they’re 10 hours old).

Events

The client inherently has some events, directly related to the state of the underlying stream:

connecting(nattempt)

A connection attempt is currently being made. It is not known yet whether it will succeed. It is the nattemptth attempt to establish the connection since the last successful connection.

connection_failed()

The connection failed during establishment of the connection.

connection_made()

The connection was successfully established.

connection_lost()

The connection has been lost. Automatic reconnect will take place (unless max_reconnect_attempts is 0; in that case, the closed event is fired next).

closed()

The maximum amount of reconnects has been surpassed, or the user has explicitly closed the client by calling Client.close().