XEP-0354: Customizable Message Routing

1. Introduction
2. Requirements
3. Glossary
4. Use Cases
    4.1. Non-balancing Message Routing Algorithms
    4.2. Balancing Message Routing Algorithms
    4.3. Non-Use Cases
5. Protocol
    5.1. Discovering Support
    5.2. Quering the current active and available message routing algorithms
    5.3. Changing the active message routing algorithm
    5.4. Message Routing Hints
       5.4.1. Determing support
       5.4.2. Determing available message routing algorithms of a (remote) server
       5.4.3. Sending a message with routing hint
6. Business Rules
    6.1. General Rules
    6.2. Routing Algorithm Specification
       6.2.1. Deliver to all
       6.2.2. Deliver to most active resource
       6.2.3. Load balance using round robin
       6.2.4. Weighted load balancing
7. Implementation Notes
8. Security Considerations
9. IANA Considerations
10. XMPP Registrar Considerations
    10.1. Protocol Namespaces
    10.2. Protocol Versioning
11. XML Schema

Appendices
    A: Document Information
    B: Author Information
    C: Legal Notices
    D: Relation to XMPP
    E: Discussion Venue
    F: Requirements Conformance
    G: Notes
    H: Revision History

Customizable Message Routing (CMR)

The name of this XEP and the protocol defined by it.

Message Routing Algorithm

An algorithm that defines how a server processes message stanzas send to a server-local bare JID of type 'message' or 'chat', with at least one available or connected resource of the receiver (RFC 6121 § 8.5.2.1.1).

4.1 Non-balancing Message Routing Algorithms

Non-balancing message algorithms consists of the traditional algorithms that are widely used by XMPP implementations as defined in RFC 6121 § 8.5.2.1.1 and RFC 3921 [3]. They usually try to send a message either to the all resources or try to determine the best resource based on some heuristic. They where designed with human-to-human interaction in mind.

Examples for non-balancing algorithms include:

• Deliver to all ('urn:xmpp:cmr:all')

• Deliver to most active resource ('urn:xmpp:cmr:mostactive')

4.2 Balancing Message Routing Algorithms

Balanced message routing algorithms try to distribute messages between the available resources of the receiver. They are ideal for use with the Internet of Things (IoT) and especially machine to machine (M2M) technologies.

Consider a large deployment of sensor nodes send their data to a cluster for further processing. Every cluster node establishes a connection using the same bare JID but a different resource for receiving the sensor data. Furthermore, after a cluster connection is authenticated, it queries the XMPP service for the CMR status, and enables a balancing message routing algorithm.

The sensor nodes can now send their data as payload of a message stanza to the cluster. The server will evenly distributed the data between the cluster nodes by using a round-robin scheme.

Since CMR balances message stanzas of type 'normal' or 'chat', PubSub notifications will also be evenly distributed between the connected resources of an connection where CMR is active.

Examples for balancing algorithms include:

• Load balance using round robin ('urn:xmpp:cmr:roundrobin')

• Weighted load balancing ('urn:xmpp:cmr:weighted')

4.3 Non-Use Cases

CMR is not suitable for scenarios where the routing behavior should also consider resources with negative priority. This would violate RFC 6121 § 8.5.2.1.1. A suitable specification for such use cases may already exists. For example a proper solution that involves forking of messages even to resources with negatives priorities is explained in Section 6 of Message Carbons (XEP-0280) [4].

5.1 Discovering Support

Example 1. Service discovery information request

<iq xmlns='jabber:client'
    from='romeo@montague.example/garden'
    id='info1'
    to='montague.example'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>

Example 2. Service discovery information response

<iq xmlns='jabber:client'
    from='montague.example'
    id='info1'
    to='romeo@montague.example/garden'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    ...
    <feature var='urn:xmpp:cmr:0'/>
    ...
  </query>
</iq>

5.2 Quering the current active and available message routing algorithms

Clients are able to query the server for the currently active and available message routing algorithms.

Example 3. Client requests the current CMR state

<iq xmlns='jabber:client'
    from='romeo@montague.example/garden'
    id='state1'
    type='get'>
  <query xmlns='urn:xmpp:cmr:0'/>
</iq>

The result IQ, must include exactly one <active/> element and at least one <available/> element. Both elements must posses a 'algorithm' attribute, which contains the name of the available or active algorithm.

Example 4. Server returns information about the CMR state

<iq xmlns='jabber:client'
  from='romeo@montague.example'
  id='state1'
  to='romeo@montague.example/garden'
  type='result'>
<query xmlns='xmlns='urn:xmpp:cmr:0'>
  <active algorithm='urn:xmpp:cmr:all' />
  <available algorithm='urn:xmpp:cmr:all'/>
  <available algorithm='urn:xmpp:cmr:mostactive'/>
  <available algorithm='urn:xmpp:cmr:roundrobin'/>
  <available algorithm='urn:xmpp:cmr:weighted'/>
</iq>

5.3 Changing the active message routing algorithm

To change the active message routing algorithm, the client sends an <iq/> of type 'set' containing a 'cmr' child element which contains the desired algorithm as value of the 'algorithm' attribute.

Example 5. Client requests to change the active message routing algorithm

<iq xmlns='jabber:client'
    from='romeo@montague.example/garden'
    id='change1'
    type='set'>
  <cmr xmlns='urn:xmpp:cmr:0'
       algorithm='urn:xmpp:cmr:roundrobin' />
</iq>

The server will respond with an result <iq/> if the routing algorithm was successfully changed.

Example 6. Server acknowledges the change of the active message routing algorithm

<iq xmlns='jabber:client'
    from='romeo@montague.example'
    id='change1'
    to='romeo@montague.example/garden'
    type='result'/>

If the server is unable to change the message routing algorithm, then an error <iq/> is returned to the client.

Example 7. Server informs client that the routing algorithm was not changed

<iq xmlns='jabber:client'
    from='romeo@montague.example'
    id='change1'
    to='romeo@montague.example/garden'
    type='error'>
  <error type='cancel'>
    <not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>

5.4 Message Routing Hints

<iq xmlns='jabber:client'
    from='romeo@montague.example/garden'
    id='info2'
    to='bar.example'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>

  <iq xmlns='jabber:client'
    from='bar.example'
    id='info2'
    to='romeo@montague.example/garden'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    ...
    <feature var='urn:xmpp:cmr:hints:0'/>
    ...
  </query>
</iq>

<iq xmlns='jabber:client'
    from='romeo@montague.example/garden'
    to='bar.example'
    id='state1'
    type='get'>
  <query xmlns='urn:xmpp:cmr:0'/>
</iq>

<iq xmlns='jabber:client'
  from='bar.example'
  id='state1'
  to='romeo@montague.example/garden'
  type='result'>
<query xmlns='xmlns='urn:xmpp:cmr:0'>
  <available algorithm='urn:xmpp:cmr:all'/>
  <available algorithm='urn:xmpp:cmr:mostactive'/>
  <available algorithm='urn:xmpp:cmr:roundrobin'/>
  <available algorithm='urn:xmpp:cmr:weighted'/>
  <available algorithm='urn:xmpp:cmr:forkalways'/>
</iq>

<message xmlns='jabber:client'
    from='romeo@montague.example/garden'
    to='foo@bar.example'>
  <body>Hello everyone</body>
  <cmr xmlns='urn:xmpp:cmr:0'
       algorithm='run:xmpp:cmr:forkalways'/>
</message>

6.1 General Rules

Clients are allowed to change the CMR state at any time. CMR MUST only affect the routing of message stanzas of type 'normal' or 'chat', which are addressed to a bare JID and where the receiving entity has more then one available resource with a non-negative presence priority. That is, it affects the routing decision as described in RFC 6121 § 8.5.2.1.1 for messages of type 'normal' and 'chat'.

The CMR state, ie. the used routing algorithm, is identical for every session of an XMPP client. Therefore implementations MUST NOT allow different CMR states between the resources of the same bare JID.

If an entity advertises support for CMR as described in 3. it MUST support at least one message routing algorithm.

6.2 Routing Algorithm Specification

10.1 Protocol Namespaces

This specification defines the following XML namespace:

• urn:xmpp:cmr:0

Upon advancement of this specification from a status of Experimental to a status of Draft, the XMPP Registrar [8] shall add the foregoing namespace to the registry located at <http://xmpp.org/registrar/namespaces.html>, as described in Section 4 of XMPP Registrar Function (XEP-0053) [9].

10.2 Protocol Versioning

If the protocol defined in this specification undergoes a revision that is not fully backwards-compatible with an older version, the XMPP Registrar shall increment the protocol version number found at the end of the XML namespaces defined herein, as described in Section 4 of XEP-0053.

<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='urn:xmpp:cmr:0'
    xmlns='urn:xmpp:cmr:0'
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-XXXX: http://www.xmpp.org/extensions/xep-xxxx.html
    </xs:documentation>
  </xs:annotation>

  <xs:element name='query'>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref='active'
                    minOccurs='1'
                    maxOccurs='1'/>
        <xs:element ref='available'
                    minOccurs='1'
                    maxOccurs='unbounded'/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:element name='active' type='cmrtype'/>

  <xs:element name='available' type='cmrtype'/>

  <xs:element name='cmr' type='cmrtype'/>

  <xs:complexType name='cmrtype'>
    <xs:complexType>
      <xs:attribute name='algorithm' type='xs:string' use='required'/>
    </xs:complexContent>
  </xs:complexType>

</xs:schema>
  

Florian Schmaus

Email: flo@geekplace.eu
JabberID: flo@geekplace.eu

Copyright

Permissions

Disclaimer of Warranty

Limitation of Liability

IPR Conformance

1. RFC 6121: Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence <http://tools.ietf.org/html/rfc6121>.

2. XEP-0254: PubSub Queueing <http://xmpp.org/extensions/xep-0254.html>.

3. RFC 3921: Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence <http://tools.ietf.org/html/rfc3921>.

4. XEP-0280: Message Carbons <http://xmpp.org/extensions/xep-0280.html>.

5. XEP-0030: Service Discovery <http://xmpp.org/extensions/xep-0030.html>.

6. XEP-0115: Entity Capabilities <http://xmpp.org/extensions/xep-0115.html>.

7. 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/>.

8. The XMPP Registrar maintains a list of reserved protocol namespaces as well as registries of parameters used in the context of XMPP extension protocols approved by the XMPP Standards Foundation. For further information, see <http://xmpp.org/registrar/>.

9. XEP-0053: XMPP Registrar Function <http://xmpp.org/extensions/xep-0053.html>.

Version 0.1 (2014-10-15)

Version 0.0.1 (2014-09-22)