XEP-0280: Message Carbons

1. Introduction
2. Requirements
3. Use Cases
    3.1. Discovering Support
    3.2. Enabling Carbons
    3.3. Disabling Carbons
    3.4. Error Cases
       3.4.1. bad-request
       3.4.2. feature-not-implemented
       3.4.3. forbidden
       3.4.4. not-allowed
    3.5. Inbound Messages
    3.6. Sending Messages
    3.7. Outbound Message Carbon Copies
    3.8. Avoiding Carbons for a single message
4. Business Rules
    4.1. Interaction with Chat States
    4.2. Handling of errors
    4.3. Auto-responses
    4.4. Mobile Considerations
5. Security Considerations
6. IANA Considerations
7. XMPP Registrar Considerations
    7.1. Protocol Namespaces
    7.2. Protocol Versioning
8. XML Schema
9. Acknowledgements

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

3.1 Discovering Support

If a server implements the Message Carbons capability, it MUST specify the 'urn:xmpp:carbons:0' feature in its service discovery information features as specified in Service Discovery [1] or section 6.3 of Entity Capabilities [2]. Clients MUST NOT enable or disable Carbons if their server does not support this feature.

Example 1. Client requests information about its own server

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

Example 2. Server responds with Carbons feature

<iq type='get'
    to='romeo@montague.net/home'
    from='montague.net'
    id='info1'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
...
    <feature var='urn:xmpp:carbons:0'/>
...
  </query>
</iq>

3.2 Enabling Carbons

Servers MUST NOT enable the Carbons protocol for a client by default, since unmodified clients might be confused by the new protocol. When a client wants to participate in the Carbons protocol, it sends an IQ set to enable the protocol.

Example 3. Client enables Carbons

<iq type='set' id='enable1'>
  <carbons var='urn:xmpp:carbons:0' mode='enable'/>
</iq>

Carbons will generally be enabled before the client sends the first undirected presence, to ensure that all inbound messages will be delivered according to the Carbon rules. The server will respond with an IQ result when Carbons are enabled:

Example 4. Server acknowledges Carbons enablement

<iq type='result' id='enable1'/>

3.3 Disabling Carbons

Some clients might want to disable Carbons. An example of this might be a mobile client that wants Carbons when the application is in the foreground, and disabled when it is in the background. To disable Carbons, clients send an IQ set:

Example 5. Client disables Carbons

<iq type='set' id='disable1'>
  <carbons var='urn:xmpp:carbons:0' mode='disable'/>
</iq>

The server will respond with an IQ result when Carbons are disabled:

Example 6. Server acknowledges Carbons enablement

<iq type='result' id='disable1'/>

3.4 Error Cases

Enabling or disabling Carbons may fail in the several ways. If one of these errors is returned, the server MUST keep the previous state, where the initial state is Carbons disabled. For example, if the first enable returns an error, the server MUST NOT enable Carbons.

<iq id='enable1'
    type='error'>
  <error type='modify'>
    <bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>

<iq id='enable1'
    type='error'>
  <error type='cancel'>
    <feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>

<iq id='enable1'
    type='error'>
  <error type='auth'>
    <forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>

<iq id='enable1'
    type='error'>
  <error type='cancel'>
    <not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>

3.5 Inbound Messages

Messages of type chat that are addressed to the bare JID (localpart@domain) MUST be copied by the receiving server to all of the resources for that user that have non-negative presence priority and have not filtered messages through some other means. The process of making copies is known as "forking." The receiving server SHOULD NOT modify the 'to' address of the forked messages.

Example 11. Juliet sends Romeo an undirected message, which is forked

<message
    from='juliet@example.com/balcony'
    to='romeo@example.net'
    type='chat'>
  <body>Wherefore art thou, Romeo?</body>
  <thread>0e3141cd80894871a68e6fe6b1ec56fa</thread>
</message>

... each of romeo@example.net's resources receives this stanza verbatim

Messages of type "chat" that are addressed to a full JID (localpart@domain/resource) MUST be sent by the receiving server to the addressed resource, and MUST also be sent to all of the Carbons-enabled resources for the receiving user. The goal of the copies to Carbons-enabled resources is to allow those clients to have both halves of *all* IM conversations, including messages that are sent from clients that lock in to particular resources.

3.6 Sending Messages

Once most of the clients that are deployed have implemented Carbons, clients MAY choose to always send chat type messages to the bare JID. Until then, traditional resource locking is RECOMMENDED. (Note: another XEP might be written to document traditional resource locking, if the documentation in XMPP IM [3] is not sufficient.)

Also note that Chat State Notifications [4] recommends sending chat state notifications as chat type messages, which means that they will be subject to Carbon-copying. This is intentional.

3.7 Outbound Message Carbon Copies

Carbons clients want to have copies of messages going in both directions for other resources associated with the same user. To that end, messages of type chat that are sent from any resource MUST be copied by the sending server to each of the resources that have enabled Carbons, but are not the sending resource. Note that the 'to' address will be the original target of the message (bare JID, as above), and the 'from' address will contain the full JID (localpart@domain/resource) of the sending resource. The 'to' address not matching the JID of the session is somewhat unprecedented in XMPP, which is why Carbons must be explicitly enabled.

Messages that have carbon copies sent back to Carbons-enabled resources MUST NOT be copied back to the originating client. The copies MUST have the full JID (localpart@domain/resource) of the sender as the 'from' address. The copies MUST include a sent element in the urn:xmpp:carbons:0 namespace.

Example 12. Romeo responds to Juliet, which is Carboned

<message
    to='juliet@example.com/balcony'
    from='romeo@example.net/home'
    type='chat'>
  <body>Neither, fair saint, if either thee dislike.</body>
  <thread>0e3141cd80894871a68e6fe6b1ec56fa</thread>
</message>

Example 13. Romeo's OTHER Carbons-enabled clients receive a copy

<message
    to='juliet@example.com/balcony'
    from='romeo@example.net/home'
    type='chat'>
  <body>Neither, fair saint, if either thee dislike.</body>
  <thread>0e3141cd80894871a68e6fe6b1ec56fa</thread>
  <sent xmlns='urn:xmpp:carbons:0'/>
</message>

3.8 Avoiding Carbons for a single message

Some clients might want to avoid carbons on a single message, while still keeping all of the other semantics of Carbon support. This might be useful for clients sending end-to-end encrypted messages, for example.

To avoid a message being Carbon-copied to its other resources, the sending client MUST add a private element in the urn:xmpp:carbons:0 namespace. When the sending server receives the message, it MUST NOT make carbon copies to the other Carbons-enabled resources, and MUST remove the private element before forwarding the message to the intended recipient.

Note: use of the private mechanism will lead to partial conversations on other devices. This is the intended effect.

Example 14. Romeo sends to Juliet, avoiding Carbon copies

<message
    to='juliet@example.com'
    from='romeo@example.net/home'
    type='chat'>
  <body>Neither, fair saint, if either thee dislike.</body>
  <thread>0e3141cd80894871a68e6fe6b1ec56fa</thread>
  <private xmlns='urn:xmpp:carbons:0'/>
</message>

Example 15. Romeo's server removes the private tag before forwarding, and does NOT send carbon copies to Romeo's other resources

<message
    to='juliet@example.com'
    from='romeo@example.net/home'
    type='chat'>
  <body>Neither, fair saint, if either thee dislike.</body>
  <thread>0e3141cd80894871a68e6fe6b1ec56fa</thread>
</message>

4.1 Interaction with Chat States

Clients that implement Carbons MAY take special use of Chat State Notifications [5] notifications.

It is RECOMMENDED that upon receiving an outbound gone chat state (as a carbon copy) for a given conversation, that conversation be removed from user display as if the user on the copied client had terminated the conversation. In order to prevent unwanted termination of conversations on other resources, clients SHOULD NOT send gone chat states on logout, but instead SHOULD count on the unavailable presence to convey the change in attention.

Upon receiving an outbound notification of any chat state other than gone, the copied client MAY conclude that the sending client has taken responsibility for the conversation, and make appropriate user interface modifications. For example, notifications could be muted on non-primary devices.

4.2 Handling of errors

When a receiving server attempts to deliver a forked message, and that message bounces with an error for any reason, the receiving server MUST NOT forward that error back to the original sender. The receiving server SHOULD use the sent element in the bounce to determine that an error is from a forked message.

This rule is used to prevent some of the half-failure modes that have been an issue in other prototocols.

4.3 Auto-responses

Clients that automatically respond to messages for any reason (e.g. when in DND presence state) MUST take adequate care when enabling Carbons in order to prevent storms or loops. Carbon copies of outbound messages MUST NOT be auto-replied to under any circumstances. Forked inbound messages SHOULD NOT be auto-replied to, unless the client has some way of knowing that the receiver will not receive more than one auto-reply from other similar clients for the same user.

4.4 Mobile Considerations

Since mobile devices often must pay for network traffic based on usage, the enablement of Carbons for such devices should be undertaken advisedly. More complicated mechanisms for controlling the Carbon-copying or forking of individual conversations may need to be added to deal with mobile clients in the future.

7.1 Protocol Namespaces

This specification defines the following XML namespace:

• urn:xmpp:carbons:0

Upon advancement of this specification from a status of Experimental to a status of Draft, the XMPP Registrar [7] 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 [8].

7.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:carbons:0'
    xmlns='urn:xmpp:carbons:0'
    elementFormDefault='qualified'>

  <xs:element name='carbons'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='mode' use='required'>
            <xs:simpleType>
              <xs:restriction base="xs:string">
                <xs:enumeration value="enable"/>
                <xs:enumeration value="disable"/>
              </xs:restriction>
            </xs:simpleType>
          </xs:attribute>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

  <xs:element name='sent' type='empty'/>

  <xs:element name='private' type='empty'/>

  <xs:simpleType name='empty'>
    <xs:restriction base='xs:string'>
      <xs:enumeration value=''/>
    </xs:restriction>
  </xs:simpleType>

</xs:schema>
  

Joe Hildebrand

Email: jhildebr@cisco.com
JabberID: jhildebr@cisco.com

Copyright

Permissions

Disclaimer of Warranty

Limitation of Liability

IPR Conformance

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

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

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

4. XEP-0085: Chat State Notifications <http://xmpp.org/extensions/xep-0085.html>.

5. XEP-0085: Chat State Notifications <http://xmpp.org/extensions/xep-0085.html>.

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

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

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

Version 0.1 (2010-05-03)

Version 0.0.2 (2010-04-21)

Version 0.0.1 (2010-02-25)