XEP-0280: Message Carbons

Abstract:In order to keep all IM clients for a user engaged in a conversation, outbound messages are carbon-copied to all interested resources.
Authors:Joe Hildebrand, Matthew Miller
Copyright:© 1999 - 2011 XMPP Standards Foundation. SEE LEGAL NOTICES.
Status:Experimental
Type:Standards Track
Version:0.2
Last Updated:2011-07-10

WARNING: This Standards-Track document is Experimental. Publication as an XMPP Extension Protocol does not imply approval of this proposal by the XMPP Standards Foundation. Implementation of the protocol described herein is encouraged in exploratory implementations, but production systems are advised to carefully consider whether it is appropriate to deploy implementations of this protocol before it advances to a status of Draft.

Table of Contents


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. Receiving Messages
    3.6. Sending Messages
    3.7. 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

1. Introduction

At the time of original writing of this XEP, many XMPP servers handle message stanzas sent to a user@host (or "bare") JID with no resource by delivering that message only to the resource with the highest priority for the target user. Some server implementations, however, have chosen to send these messages to all of the online resources for the target user. If the target user is online with multiple resources when the original message is sent, a conversation ensues on one of the user's devices; if the user subsequently switches devices, parts of the conversation may end up on the alternate device, causing the user to be confused, misled, or annoyed.

This XEP defines an approach for ensuring that all of my devices get both sides of all conversations in order to avoid user confusion. As a pleasant side-effect, information about the current state of a conversation is shared between all of a user's clients that implement this protocol.

2. Requirements

3. Use Cases

3.1 Discovering Support

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

Example 1. Client requests information about its own server

<iq xmlns='jabber:client'
    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 xmlns='jabber:client'
    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:1'/>
...
  </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 xmlns='jabber:client'
    type='set'
    id='enable1'>
  <enable var='urn:xmpp:carbons:1'/>
</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 xmlns='jabber:client'
    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 xmlns='jabber:client'
    type='set'
    id='disable1'>
  <disable var='urn:xmpp:carbons:1'/>
</iq>

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

Example 6. Server acknowledges Carbons enablement

<iq xmlns='jabber:client'
    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.

3.4.1 bad-request

The sender has sent a stanza containing XML that does not conform to the appropriate schema or that cannot be processed. One example is an IQ stanza that includes an unrecognized value of the 'type' attribute. Another is changing to the state that is already in effect (enabling Carbons a second time).

Example 7. Error: bad-request

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

3.4.2 feature-not-implemented

The sender has sent an enable or disable request to a server that does not support the protocol. This SHOULD NOT happen in practice, because clients MUST check for server support before sending their request.

Example 8. Error: feature-not-implemented

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

3.4.3 forbidden

The sender does is forbidden by policy from enabling or disabling Carbons.

Example 9. Error: forbidden

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

3.4.4 not-allowed

The receiver does not allow any entity to turn on Carbons. This might occur in a multi-domain deployment, where administrators of one domain allow Carbons, but another does not.

Example 10. Error: not-allowed

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

3.5 Receiving 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."

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

<message xmlns='jabber:client'
         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.

The copies sent to the Carbon-enabled resources are wrapped using Message Forwarding [3]. The wrapping message SHOULD maintain the same 'type', 'from', and 'id' attribute values (if any), while the 'to' attribute SHOULD be the full JID of the resource receiving the copy. The content of the wrapping message MUST contain a <forwarded xmlns='urn:xmpp:forward:0'/> which contains the original message (properly namespaced as "jabber:client") and a <received xmlns='urn:xmpp:carbons:1'/> element:

Example 12. Juliet sends Romeo a directed message

<message xmlns='jabber:client'
         from='juliet@example.com/balcony'
         to='romeo@example.net/garden'
         type='chat'>
  <body>What man art thou that, thus bescreen'd in night, so stumblest on my counsel?</body>
  <thread>0e3141cd80894871a68e6fe6b1ec56fa</thread>
</message>

Example 13. Server sends carbon to Romeo's other clients

<message xmlns='jabber:client'
         from='juliet@example.com/balcony'
         to='romeo@example.net/home'
         type='chat'>
  <forwarded xmlns='urn:xmpp:forward:0'>
    <received xmlns='urn:xmpp:carbons:1'/>
    <message xmlns='jabber:client'
             from='juliet@example.com/balcony'
             to='romeo@example.net/garden'
             type='chat'>
      <body>What man art thou that, thus bescreen'd in night, so stumblest on my counsel?</body>
      <thread>0e3141cd80894871a68e6fe6b1ec56fa</thread>
    </message>
  </forwarded>
</message>

3.6 Sending Messages

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.

The copies sent to the Carbon-enabled resources are wrapped using Message Forwarding. The wrapping message SHOULD maintain the same 'type', 'from', and 'id' attribute values, while the 'to' attribute SHOULD be the full JID of the resource receiving the copy. The content of the wrapping message MUST contain a <forwarded xmlns='urn:xmpp:forward:0'/> which contains the original message (properly namespaced as "jabber:client") and a <sent xmlns='urn:xmpp:carbons:1'/> element:

Example 14. Romeo responds to Juliet

<message xmlns='jabber:client'
         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 15. Romeo's other Carbons-enabled clients receive a copy

<message xmlns='jabber:client'
         from='romeo@example.net/home'
         to='romeo@example.net/garden'
         type='chat'>
  <forwarded xmlns='urn:xmpp:forward:0'>
    <sent xmlns='urn:xmpp:carbons:1'/>
    <message xmlns='jabber:client'
             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>
</message>

3.7 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:1" 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 16. Romeo sends to Juliet, avoiding Carbon copies

<message xmlns='jabber:client'
         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:1'/>
</message>

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

<message xmlns='jabber:client'
         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. Business Rules

4.1 Interaction with Chat States

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.

Additionally, clients that implement Carbons MAY take special use of chat state notifications:

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 the "dnd" presence show state) MUST take adequate care when enabling Carbons in order to prevent storms or loops. Carbon copies of 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 ensuring no more than one auto-reply is sent from all of its user's resources.

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.

5. Security Considerations

The security model assumed by this document is that all of the resources for a single user are in the same trust boundary.

Outbound chat messages that are encrypted end-to-end are not often useful to receive on other resources. As such, they should use the <private/> element specified above to avoid such copying, unless the encryption mechanism is able to accommodate this protocol.

6. IANA Considerations

This document requires no interaction with the Internet Assigned Numbers Authority (IANA) [5].

7. XMPP Registrar Considerations

7.1 Protocol Namespaces

This specification defines the following XML namespace:

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

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.

8. XML Schema

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

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

  <xs:element name='disable' type='empty'/>
  
  <xs:element name='enable' type='empty'/>

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

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

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

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

</xs:schema>

9. Acknowledgements

The authors wish to thank Patrick Barry, Teh Chang, Jack Erwin, Craig Kaes, Kathleen McMurry, Tory Patnoe, Peter Saint-Andre, and Ben Schumacher for their feedback.

Appendices

Appendix A: Document Information

Series: XEP
Number: 0280
Publisher: XMPP Standards Foundation
Status: Experimental
Type: Standards Track
Version: 0.2
Last Updated: 2011-07-10
Approving Body: XMPP Council
Dependencies: XMPP Core, XEP-0001, XEP-0030, XEP-0085, XEP-0296
Supersedes: XEP-0259
Superseded By: None
Short Name: carbons
Source Control: HTML
This document in other formats: XML  PDF

Appendix B: Author Information

Joe Hildebrand

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

Matthew Miller

Email: linuxwolf@outer-planes.net
JabberID: linuxwolf@outer-planes.net

Appendix C: Legal Notices

Copyright

This XMPP Extension Protocol is copyright © 1999 - 2011 by the XMPP Standards Foundation (XSF).

Permissions

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.

Disclaimer of Warranty

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

Limitation of Liability

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.

IPR Conformance

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 <http://xmpp.org/extensions/ipr-policy.shtml> or obtained by writing to XMPP Standards Foundation, 1899 Wynkoop Street, Suite 600, Denver, CO 80202 USA).

Appendix D: Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 3920) and XMPP IM (RFC 3921) 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.

Appendix E: Discussion Venue

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 <http://xmpp.org/about/discuss.shtml> for a complete list.

Errata can be sent to <editor@xmpp.org>.

Appendix F: Requirements Conformance

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

Appendix G: Notes

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. XEP-0297: Message Forwarding <http://xmpp.org/extensions/xep-0297.html>.

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

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

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

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

Appendix H: Revision History

Note: Older versions of this specification might be available at http://xmpp.org/extensions/attic/

Version 0.2 (2011-07-10)

Changed enabling and disabling to use separate elements rather than attributes; ensured all elements in the examples have their namespaces more explicitly defined; used message forwarding for carbon copies.

(mm)

Version 0.1 (2010-05-03)

Initial published version.

(psa)

Version 0.0.2 (2010-04-21)

Updated after further analysis of edge cases.

(jjh)

Version 0.0.1 (2010-02-25)

First draft.

(jjh)

END