Module xmlstream

RFC 6120 XML Streams

Note: The XML stream is a low-level API which you should probably not use directly.

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.