XEP-0376: Pubsub Account Management

This specification describes a new model for handling remote pubsub services and a protocol for doing so.
Dave Cridland
© 2016 – 2017 XMPP Standards Foundation. SEE LEGAL NOTICES.


WARNING: This document has been automatically Deferred after 12 months of inactivity in its previous Experimental state. Implementation of the protocol described herein is not recommended for production systems. However, exploratory implementations are encouraged to resume the standards process.
Standards Track
0.2 (2017-09-11)
Document Lifecycle
  1. Experimental
  2. Deferred
  3. Proposed
  4. Stable
  5. Final

1. Introduction

The XMPP way is to have "disposable", or at least easily substituted, clients, maintaining long-term state on the server, and allowing it to be synchronized between clients. In particular, this can be seen on how the roster and presence fan-out operate - clients defer the operation of such things to the server, which manages the shared state and allows servers to access and manipulate it.

Historically, however, we have not done this for some more recently designed services, including Multi User Chat and PubSub. In both cases, different clients may be unaware of what chatrooms (etc) are joined (etc) by which other clients. This causes practical difficulty in seamlessly switching between devices and/or clients.

2. User Stories

2.1 Device Agility

2.2 New Devices

2.3 Offline Capability

2.4 PEP

3. Protocol

3.1 Advertising Support

3.1.1 Clients

Clients advertise support for this protocol via Service Discovery (XEP-0030) [1] using a Disco Feature of 'urn:xmpp:pam:0'. This is required for local servers to detect support.

3.1.2 Servers

Servers advertise this support via Service Discovery (XEP-0030) [1] on the user account (eg, <localpart@domain.tld>), using the same feature of 'urn:xmpp:pam:0'. This is used both by the local user and also remote pubsub services.

3.2 Subscribing

When a client wishes to subscribe to a node, either on the local server or remotely, using this protocol it does so by sending an <iq/> of type "set" to its own account, containing a pam element, which in turn has a service attribute (the target service jid) and a payload of a Publish-Subscribe (XEP-0060) [2] subscribe element (as described in Publish-Subscribe (XEP-0060) [2] §6.1). Example 32 from Publish-Subscribe (XEP-0060) [2] is thus performed in this protocol as follows:

Example 1. Client subscribes to a node
      <iq type='set' id='sub1'>
        <pam xmln='urn:xmpp:pam:0' jid='pubsub.shakespeare.lit'>
          <subscribe xmlns='http://jabber.org/protocol/pubsub'


Note that because the Publish-Subscribe (XEP-0060) [2] operation is intact within the pam element, local servers MAY interpret the operation, or MAY forward it verbatim. Note that the client SHALL always use its own bare jid (eg, <localpart@domain.tld>) within a subscribe, servers MUST verify this.

Such a request SHALL cause the local server to send a traditional Publish-Subscribe (XEP-0060) [2] request, from the account bare jid, to the remote service.

When the remote service replies, the local server SHALL first notify all joined clients of the new subscription (described more in #sublist)...

Example 2. Server notifies about new subscription
        <notify ver='aocolb' service='pubsub.shakespeare.lit' xmlns='urn:xmpp:pam:0'>
          <subscription xmlns='http://jabber.org/protocol/pubsub'


... and then MUST respond to the original <iq/>. Since the subscription has already been notified, this is an empty result <iq/>.

If the local server detects an error, it MUST NOT forward the request, and MUST respond with an <iq/> stanza of type error, which contains an error element which MAY be stamped with the local server as generator. Thus Example 34 from Publish-Subscribe (XEP-0060) [2] would be very similar:

Example 3. An error generated remotely
      <iq type='error' id='sub1'>
        <error type='modify' by='francisco@denmark.lit'>
          <bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
          <invalid-jid xmlns='http://jabber.org/protocol/pubsub#errors'/>


If the remote service rejects the subscription request, the local server simply forwards the response back as an <iq/> of type error, with the remote error copied through. The generator MUST be set to the remote service if missing. Thus Example 35 from Publish-Subscribe (XEP-0060) [2] might look as follows:

Example 4. An error generated remotely
  <iq type='error' id='sub1'>
    <error type='auth' by='pubsub.shakespeare.lit'>
      <not-authorized xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
      <presence-subscription-required xmlns='http://jabber.org/protocol/pubsub#errors'/>


Clients MAY assume that if the generator is missing, the error is generated by the local server and not a remote service.

3.3 Unsubscribing

As above.

3.4 Listing Subscriptions

Clients obtain a current listing of the subscriptions, for example on initial connection, by sending a subscriptions request qualified by the pam namespace. If a client already has the opaque version identifier cached, it MAY include it within a "ver" attribute:

Example 5. Client requests all current subscriptions
      <iq type='get' id='subscriptions1'>
        <subscriptions xml='urn:xmpp:pam:0' ver='asdvcjkasdjb'>


The local server responds with either a response containing a subscription list (such as this, similar to Publish-Subscribe (XEP-0060) [2] Example 21):

Example 6. Complete subscription list
      <iq type='result' id='subscription1'>
        <subscriptions xml='urn:xmpp:pam:0' ver='kjlsadhfsd'>
          <subscription service='pubsub.shakespeare.lit' node='node1' jid='francisco@denmark.lit' subscription='subscribed'/>
          <subscription service='pubsub.marlowe.lit' node='node2' jid='francisco@denmark.lit' subscription='subscribed'/>
          <subscription service='pubsub.marlowe.lit' node='node5' jid='francisco@denmark.lit' subscription='unconfigured'/>
          <subscription service='pubsub.shakespeare.lit' node='node6' jid='francisco@denmark.lit' subscription='subscribed' subid='123-abc'/>
          <subscription service='pubsub.shakespeare.lit' node='node6' jid='francisco@denmark.lit' subscription='subscribed' subid='004-yyy'/>


Alternately, a server MAY - if the client has supplied an opaque version identifier - send a sequence of <notify> elements followed by an empty <iq/> result.

Clients MAY persistently store the last "ver" attribute seen from either the <subscriptions> response or the last <notify>, whichever is later. This can then be used to minimize the volume of subscription data transferred during resync.

3.5 Auto Subscriptions

Servers need to subscribe to remote PEP services explicitly those nodes which are of interest. Interest needs to be detirmined by the client issuing a request; but this implies that servers would gradually acrue any node type which the user has had a capable client at any time.

Perhaps timing out node types which have not been requested for over a certain period?

Clients can use +notify to handle auto-subscriptions between clients and their server.

Servers receiving +notify from accounts known to support this protocol ignore them.

3.6 Filtering

Clients filter subscriptions using a specific stanza (iq, probably), containing a list of node names. This can be used instead of the odler +notify (which is broadcast).

3.7 Interaction with MAM

We probably want to say that events are now archived by MAM, but this may imply that clients need to filter out such events (or explicitly include them). Maybe the mask above affects MAM queries?

4. Security Considerations

I have literally no idea. I don't think anything new is introduced that couldn't be discovered by traffic monitoring, although it collects and collates information that previously would not have been so readily available.

5. XMPP Registrar Considerations

On publication of this specification, the XMPP Registrar will dance a little jig to the tune of the traditional hornpipe with a tea-cosy upon his or her head.

6. IANA Considerations

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


Appendix A: Document Information

XMPP Standards Foundation
Standards Track
Last Updated
Approving Body
XMPP Council
XMPP Core, XEP-0060
Superseded By
Short Name
Source Control

This document in other formats: XML  PDF

Appendix B: Author Information

Dave Cridland


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.

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 <https://xmpp.org/about/xsf/ipr-policy> or obtained by writing to XMPP Standards Foundation, P.O. Box 787, Parker, CO 80134 USA).

Visual Presentation

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.

Appendix D: Relation to XMPP

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.

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 <https://xmpp.org/community/> 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 <https://xmpp.org/extensions/xep-0030.html>.

2. XEP-0060: Publish-Subscribe <https://xmpp.org/extensions/xep-0060.html>.

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

Appendix H: Revision History

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

  1. Version 0.2 (2017-09-11)
    Defer due to lack of activity.
    XEP Editor (jwi)
  2. Version 0.1.1 (2016-07-20)

    Added some concrete protocol around subscription tracking.

  3. Version 0.1.0 (2016-05-20)

    Initial version approved by the Council.

    XEP Editor: ssw
  4. Version 0.0.1 (2016-01-28)

    Initial Version


Appendix I: Bib(La)TeX Entry

  title = {Pubsub Account Management},
  author = {Cridland, Dave},
  type = {XEP},
  number = {0376},
  version = {0.2},
  institution = {XMPP Standards Foundation},
  url = {https://xmpp.org/extensions/xep-0376.html},
  date = {2016-01-28/2017-09-11},