Sometimes it is important for the sender of a message to control the Quality of Service level (or QoS level) of the message. In other protocols, such as queueing, such QoS levels are built into the protocol itself. XMPP lacks an intrinsic QoS level management feature, which has left application developers to define proprietary solutions when such have been required. This document however, provides a generic solution and can be combined with any type of message structure defined either proprietarily or in another XEP. The handling of the Quality of Service level is done prior to parsing the contents of the message. It defines three generic Quality of Service levels that can be used regardless of what type of message is being sent:
The message is sent at most once to its destination. The delivery of the message is not guaranteed. This QoS level should only be used of the loss of messages is not critical to the application.
Example: A sensor sending a stream of current values. If a value is lost might not matter much since the next message provides a new current value, overriding any lost value.
The message is sent at least once to its destination. Sending of the message is repeated until message has been acknowledged. It is not guaranteed that the message is delivered only once. Asynchronous conditions may arise where the message is delivered more than once. If an acknowledgement is not received, at least the sender may become aware that the message was not delivered properly. The At least once QoS level requires twice as many messages to be transported in the network as compared to the At most once QoS level.
Example: Any idempotent control action such as setting the light to a certain level. It is important that the control action is received, but not how many of them are received. Any identical control action that follows makes no difference in output or performance.
The message is sent and delivered exactly once to its destination. The delivery of the message is divided into two acknowledged message transfers. First, the message is transferred to the other side, but not parsed. The second operation, the message is requested to be parsed and delivered. Both these steps are idempotent, making sure that the contents of the message is delivered exactly once. If not possible to deliver the message, the sender will be made aware of this fact. The Exactly once QoS level requires four times as many messages to be transported in the network as compared to the At most once QoS level and twice as many messages to be transported as compared to the At least once QoS level.
Example: Any control action or counting operation that is not idempotent, such as sending a control action when a button is pressed, whenever an event has occurred or a transaction. If counting events, transactions, or accumulating consumption, it is vital that messages are not processed twice, since it will change the end result.
To send a message that is received at most once to its destination, a normal message stanza is used, as defined by the XMPP protocol itself. The delivery of the message is not guaranteed. This QoS level should only be used of the loss of messages is not critical to the application.
Example: A sensor sending a stream of current values. If a value is lost might not matter much since the next message provides a new current value, overriding any lost value.
<message
from='temperaturesensor@example.org/34892374'
to='user@example.org/938089023'>
<fields xmlns='urn:xmpp:iot:sensordata' seqnr='1' done='true'>
<node nodeId='Temp01'>
<timestamp value='2015-11-11T22:01:30'>
<numeric name='Temperature' momentary='true' automaticReadout='true' value='23.4' unit='°C'/>
</timestamp>
</node>
</fields>
</message>
To send a message that is received at least once to its destination, an iq stanza of type set is sent containing an acknowledged element from the "urn:xmpp:qos" namespace. The acknowledged element in turn contains the message to be delivered. The iq stanza must have an id attribute that is used to identify if the stanza has been received or not. When an acknowledged message is received, an empty response is returned to acknowledge the receipt. Parsing the message is done after sending the response. If no response is received by the sending side within a given time frame, an number of retries should be made, using an interval or drop-off algorithm. These time frames and number of attempts are implementation specific.
It is not guaranteed that the message is delivered only once. Asynchronous conditions may arise where the message is delivered more than once. If an acknowledgement is not received, at least the sender may become aware that the message was not delivered. The At least once QoS level requires twice as many messages to be transported in the network as compared to the At most once QoS level.
Example: Any idempotent control action such as setting the light to a certain level. It is important that the control action is received, but not how many of them are received. Any identical control action that follows makes no difference in output or performance.
<iq id='123' type='set'
from='controller@example.org/34892374'
to='lightswitch@example.org/938089023'>
<qos:acknowledged xmlns:qos='urn:xmpp:qos'>
<message>
<set xmlns='urn:xmpp:iot:control'>
<int name='Light' value='80'/>
</set>
</message>
</qos:acknowledged>
</iq>
<iq id='123' type='result'
from='lightswitch@example.org/938089023'
to='controller@example.org/34892374'/>
Note: The to and from attributes in the embedded message stanza are left empty.
To send a message that is received exactly once to its destination, an iq stanza of type set is sent containing an assured element from the "urn:xmpp:qos" namespace. The assured element in turn contains the message to be delivered. The iq stanza must have an id attribute that is used to identify if the stanza has been received or not, just as in the acknowledged case. But to keep track of the message begin sent, a msgId attribute has to be provided as well. When an assured message is received, a received response is returned to acknowledge the receipt. This received response echoes the msgId attribute as well. But the message is not parsed and delivered at this point, only temporarily stored on the receiving end. If multiple messages are received using the same msgId from the same sender, they are simply ignored, as one is already held in memory. Still, the received response is returned as normal.
When the sender receives the received response, it sends a new iq set stanza, this time with a deliver payload, to tell the receiving end to parse and deliver the message, if in memory, and remove it from memory. The receiver acknowledges the message by returning an empty iq result stanza. If receiving multiple requests using the same msgId, it will acknowledge each one. But only one message will be parsed and delivered, as it will have been removed from the temporary storage on the receiving end. For both the assured and deliver messages, a retry mechanism similar to the one used for acknowledged service is to be used.
The Exactly once QoS level requires twice as many messages to be transported in the network as compared to the At least once QoS level, and four times the number of messages as compared to the At most once QoS level.
Example: Any control action or counting operation that is not idempotent, such as sending a control action when a button is pressed, or whenever an event has occurred. If counting events, or accumulating consumption, it is vital that messages are not processed twice, since it will change the end result.
<iq id='123' type='set'
from='entrance@example.org/34892374'
to='counter@example.org/938089023'>
<qos:assured xmlns:qos='urn:xmpp:qos' msgId='984232334'>
<message>
<log xmlns='urn:xmpp:eventlog' timestamp='2015-11-12T09:07:12Z' id='Entered'>
<message>Entered.</message>
</buy>
</message>
</qos:assured>
</iq>
<iq id='123' type='result'
from='counter@example.org/938089023'>
to='entrance@example.org/34892374'>
<received msgId='984232334'/>
</iq>
<iq id='124' type='set'
from='entrance@example.org/34892374'
to='counter@example.org/938089023'>
<qos:deliver xmlns:qos='urn:xmpp:qos' msgId='984232334'/>
</iq>
<iq id='124' type='result'
from='counter@example.org/938089023'>
to='entrance@example.org/34892374'/>
</iq>
...
<iq id='456' type='set'
from='exit@example.org/34892374'
to='counter@example.org/938089023'>
<qos:assured xmlns:qos='urn:xmpp:qos' msgId='4645623466'>
<message>
<log xmlns='urn:xmpp:eventlog' timestamp='2015-11-12T11:23:54Z' id='Left'>
<message>Left.</message>
</buy>
</message>
</qos:assured>
</iq>
<iq id='456' type='result'
from='counter@example.org/938089023'>
to='exit@example.org/34892374'>
<received msgId='4645623466'/>
</iq>
<iq id='457' type='set'
from='exit@example.org/34892374'
to='counter@example.org/938089023'>
<qos:deliver xmlns:qos='urn:xmpp:qos' msgId='4645623466'/>
</iq>
<iq id='457' type='result'
from='counter@example.org/938089023'>
to='exit@example.org/34892374'/>
</iq>
Note: The to and from attributes in the embedded message stanza are left empty.
If an entity supports signing forms as specified herein, it MUST advertise that fact by returning a feature of "urn:xmpp:qos" in response to Service Discovery (XEP-0030) [1] information requests.
<iq type='get'
from='example.org'
to='device@example.org'
id='disco1'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
<iq type='result'
from='device@example.org'
to='example.org'
id='disco1'>
<query xmlns='http://jabber.org/protocol/disco#info'>
...
<feature var='urn:xmpp:qos'/>
...
</query>
</iq>
In order for an application to determine whether an entity supports this protocol, where possible it SHOULD use the dynamic, presence-based profile of service discovery defined in Entity Capabilities (XEP-0115) [2]. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead.
When sending messages using unacknowledged service, i.e. using the normal message stanza, it can be subject to offline message storage if the recipient if offline. This might result in delivery of the message at a later time.
Message routing using unacknowledged service might be handled somewhat differently as compared to acknowledged and assured service, since the first uses the message stanza and the latter two the iq stanza, which require a fill JID in order to reach its destination. For consistency, full JIDs should be used also for unacknowledged messaging service, if possible.
If implementing support for this XEP, make sure implementation is generic and put on a lower level than other XEP-specific processing of incoming stanzas. Messages received using this server should be fed into the normal message processing and handling after the QoS level has been ascertained. This makes it possible to use QoS levels for any type of message being sent and received.
One decision each implementation of assured QoS has to make, is where to persist incoming messages between reception of message and the delivery to underlying message processing logic. Should they be persisted in internal memory, persistent Flash/EEProm, as local files or in a database? Such implementation specific concerns are left to the implementor, as this XEP only concerns itself with the communication layer between parties. But the choice of solution might affect to what level a message is ascertained to be delivered: Will delivery be guaranteed, even beyond a system reset at the receiving end? Or a system reset at the sending side? If delivery of the message has to be ascertained even if a system reset at the sending side is allowed, persistance of the request must also be made on the sending side. (To some extent, this latter concern even affects acknowledged service.)
Outstanding message IDs used in assured delivery, must be unique for the sender (counting the Full JID as the sender). If running short on Message IDs, such can be reclaimed after the receipt of a successful delivery of a previous message. Message IDs can be sequence numbers, or hash values of the contents of the message.
The to and from attributes of embedded message elements should be ignored and left out by the sender, except in the case of unacknowledged service, where the message element is the message stanza itself. In the case of acknowledged and assured quality of service levels, the message element MUST have its to and from attributes overwritten by the corresponding attributes of the iq stanza being used. This, to avoid the injection of messages with unauthenticated and unauthorized identities.
As incoming message using the assured quality of service level is temporarily stored on the receiving end, the receiver might become vulnerable to memory attacks if not implementing some basic counter measures:
Do not accept messages using assured service from untrusted sources, for instance from MUC rooms or senders not in the roster. If deemed untrusted, an iq error of type not-allowed should be returned instead of the received element expected in normal flow.
Set a limit on the number and size of assured messages that can be simultaneously received from a single source. If a source sends more than this, the resource-constraint error should be returned instead of accepting the message.
Set a total limit on the number and size of assured messages that can be simultaneously received from all sources. If anybody sends a message that will exceed this amount, the resource-constraint error should be returned instead of accepting the message.
Whenever invalid use of the assured messaging service is detected, wether it be from untrusted sources or spam, an event should be logged using Event Logging over XMPP (XEP-0337) [3] so that the source of the error can be found and appropriate counter measures taken.
This document requires no interaction with the Internet Assigned Numbers Authority (IANA) [4].
The protocol schema needs to be added to the list of XMPP protocol schemas.
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='urn:xmpp:qos'
xmlns='urn:xmpp:qos'
xmlns:jbc='jabber:client'
elementFormDefault='qualified'>
<xs:import namespace='jabber:client'/>
<xs:element name='acknowledged' type='EmbeddedMessage'/>
<xs:element name='assured' type='Assured'/>
<xs:element name='received' type='WithMessageId'/>
<xs:element name='deliver' type='WithMessageId'/>
<xs:complexType name='EmbeddedMessage'>
<xs:sequence minOccurs='1' maxOccurs='1'>
<xs:element ref='jbc:message'/>
</xs:sequence>
</xs:complexType>
<xs:complexType name='Assured'>
<xs:complexContent>
<xs:extension base='EmbeddedMessage'>
<xs:attribute ref='msgId' use='required'/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:attribute name='msgId' type='xs:string'/>
<xs:complexType name='WithMessageId'>
<xs:attribute ref='msgId' use='required'/>
</xs:complexType>
</xs:schema>
This document in other formats: XML PDF
This XMPP Extension Protocol is copyright © 1999 – 2024 by the XMPP Standards Foundation (XSF).
Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.
## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. ##
In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.
This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which can be found at <https://xmpp.org/about/xsf/ipr-policy> or obtained by writing to XMPP Standards Foundation, P.O. Box 787, Parker, CO 80134 USA).
The HTML representation (you are looking at) is maintained by the XSF. It is based on the YAML CSS Framework, which is licensed under the terms of the CC-BY-SA 2.0 license.
The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 6120) and XMPP IM (RFC 6121) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.
The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.
Discussion on other xmpp.org discussion lists might also be appropriate; see <https://xmpp.org/community/> for a complete list.
Errata can be sent to <editor@xmpp.org>.
The following requirements keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".
1. XEP-0030: Service Discovery <https://xmpp.org/extensions/xep-0030.html>.
2. XEP-0115: Entity Capabilities <https://xmpp.org/extensions/xep-0115.html>.
3. XEP-0337: Event Logging over XMPP <https://xmpp.org/extensions/xep-0337.html>.
4. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.
Note: Older versions of this specification might be available at https://xmpp.org/extensions/attic/
First draft.
@report{waher2015qos,
title = {Quality of Service},
author = {Waher, Peter},
type = {XEP},
number = {xxxx},
version = {0.0.1},
institution = {XMPP Standards Foundation},
url = {https://xmpp.org/extensions/xep-xxxx.html},
date = {2015-11-12/2015-11-12},
}END