Module xmlstream

RFC 6120 XML Streams

Note: The XML stream is a low-level API which you should probably not use directly. You may be looking for StanzaStream instead.

Establishing an XML stream is always a multi-stage process due to how stream negotiation works. Based on the values sent by the initiator in the stream header, the responder may choose to offer different features.

In order to allow this, the following multi-step processes are defined.

Initiating an XML stream

To initiate an XML stream, you need to:

1. Call initiate_stream to obtain the PendingFeaturesRecv object. That object holds the stream header sent by the peer for inspection.
2. Call PendingFeaturesRecv::recv_features if you are content with the content of the stream header to obtain the XmlStream object and the features sent by the peer.

Accepting an XML stream connection

To accept an XML stream, you need to:

1. Call accept_stream to obtain the AcceptedStream object. That object holds the stream header sent by the peer for inspection.
2. Call AcceptedStream::send_header if you are content with the content of the stream header to obtain the PendingFeaturesSend object.
3. Call PendingFeaturesSend::send_features to send the stream features to the peer and obtain the XmlStream object.

Mid-stream resets

RFC 6120 describes a couple of situations where stream resets are executed during stream negotiation. During a stream reset, both parties drop their parser state and the stream is started from the beginning, with a new stream header sent by the initiator and received by the responder.

Stream resets are inherently prone to race conditions. If the responder executes a read from the underlying transport between sending the element which triggers the stream reset and discarding its parser state, it may accidentally read the initiator’s stream header into the old parser state instead of the post-reset parser state.

Stream resets are executed with the XmlStream::initiate_reset and XmlStream::accept_reset functions, for initiator and responder, respectively. In order to avoid the race condition, XmlStream::accept_reset handles sending the last pre-reset element and resetting the stream in a single step.

Structs

AcceptedStream

Type state for a responder stream which has received a stream header

InitiatingStream

Type state for an initiator stream which has not yet sent its stream header.

PendingFeaturesRecv

Type state for an initiator stream which has sent and received the stream header.

PendingFeaturesSend

Type state for a responder stream which has received and sent the stream header.

Shutdown

Future implementing XmlStream::shutdown using XmlStream::poll_shutdown.

StreamHeader

Contains metadata from an XML stream header

Timeouts

Configuration for timeouts on an XML stream.

XmlStream

XML stream

Enums

ReadError

A non-success state which may occur while reading an XSO from a XmlStream

XmppStreamElement

Any valid XMPP stream-level element.

Functions

accept_stream

Accept a new XML stream as responder

initiate_stream

Initiate a new stream

Type Aliases

XmppStream

Convenience alias for an XML stream using XmppStreamElement.