


Calendar Server Extension                                       M. Sagen
                                                                   Apple
                                                            June 5, 2009


             Discovery of CalDAV Push-Notification Settings

Abstract

   This specification defines three new WebDAV properties that allow
   clients to discover push-notification subscription information,
   eliminating the need for polling.


Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . . . 2
   2.  Conventions Used in This Document . . . . . . . . . . . . . . . 2
   3.  New Properties  . . . . . . . . . . . . . . . . . . . . . . . . 3
     3.1.  XMPP Server Property  . . . . . . . . . . . . . . . . . . . 3
     3.2.  XMPP URI Property . . . . . . . . . . . . . . . . . . . . . 3
     3.3.  XMPP Heartbeat Property . . . . . . . . . . . . . . . . . . 4
   4.  Normative References  . . . . . . . . . . . . . . . . . . . . . 6
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . . . 7



























Sagen                                                           [Page 1]

                         CalDAV PubSub Discovery               June 2009


1.  Introduction

   The CalDAV [RFC4791] standard defines a way to access calendar data
   stored on a server.  Clients typically poll the server for changes,
   which leads to unnecessary traffic and delays in propagating calendar
   updates.  Having clients instead subscribe to calendar change
   notifications would allow near real time propagation of updates and
   potentially reduce the number of requests.

   XMPP [RFC3920], the Extensible Messaging and Presence Protocol,
   allows close to real time exchange of structured information.  The
   XEP-0060 specification defines an XMPP protocol extension for
   publish-subscribe ("pubsub") functionality, allowing clients to
   subscribe to "topics" or "nodes" and receive notifications whenever
   another client publishes to those nodes.

   A push-notification-capable CalDAV server can create and advertise a
   pubsub node for each calendar home collection and publish to those
   nodes whenever any resource within a calendar home is modified.  A
   calendar client interested in receiving updates can subscribe using
   XMPP/pubsub to one or more of these nodes.  Upon receiving a
   notification, the client then queries the CalDAV server to determine
   which resources have changed.

   This specification defines three new WebDAV properties on calendar
   home collections: 1) the XMPP server the client should connect to, 2)
   the pubsub node corresponding to the calendar home, and 3) a pubsub
   "heartbeat" node which the CalDAV server publishes to at regular
   intervals so clients know that push notifications are functioning
   properly.


2.  Conventions Used in This Document

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119].

   When XML element types in the namespaces "DAV:" and
   "urn:ietf:params:xml:ns:caldav" are referenced in this document
   outside of the context of an XML fragment, the string "DAV:" and
   "CALDAV:" will be prefixed to the element type names respectively.

   The namespace "http://calendarserver.org/ns/" is used for XML
   elements defined in this specification.  When XML element types in
   this namespace are referenced in this document outside of the context
   of an XML fragment, the string "CS:" will be prefixed to the element
   type names respectively.



Sagen                                                           [Page 2]

                         CalDAV PubSub Discovery               June 2009


3.  New Properties

3.1.  XMPP Server Property

   Name:  xmpp-server

   Namespace:  http://calendarserver.org/ns/

   Purpose:  Provides the hostname of the XMPP server a client should
      connect to for subscribing to notifications.

   Protected:  This property MUST be protected and SHOULD NOT be
      returned by a PROPFIND allprop request (as defined in Section 14.2
      of [RFC4918]).

   COPY/MOVE behavior:  This property value SHOULD be kept during a MOVE
      operation, but is normally re-initialized when a resource is
      created with a COPY.  It should not be set in a COPY.

   Description:  This property MUST be defined on a calendar home
      collection.  Its value is the hostname of the XMPP server the
      CalDAV server is using to publish change notifications to.
      Clients wanting to receive notifications must make an XMPP
      connection to the host specified in this property.

   Definition:

   <!ELEMENT xmpp-server (#PCDATA) >

   Example:  This example indicates that the CalDAV server is using host
      notifications.example.com for sending push notifications.

   <CS:xmpp-server
        xmlns:CS="http://calendarserver.org/ns/">
        notifications.example.com
   </CS:xmpp-server>

3.2.  XMPP URI Property

   Name:  xmpp-uri

   Namespace:  http://calendarserver.org/ns/

   Purpose:  Provides the URI of the pubsub node to subscribe to in
      order to receive a notification whenever a resource within this
      calendar home has changed.





Sagen                                                           [Page 3]

                         CalDAV PubSub Discovery               June 2009


   Protected:  This property MUST be protected and SHOULD NOT be
      returned by a PROPFIND allprop request (as defined in Section 14.2
      of [RFC4918]).

   COPY/MOVE behavior:  This property value SHOULD be kept during a MOVE
      operation, but is normally re-initialized when a resource is
      created with a COPY.  It should not be set in a COPY.

   Description:  This property MUST be defined on a calendar home
      collection.  Its value is the XMPP URI [RFC4622] of the pubsub
      node the CalDAV server will publish to whenever any change is made
      within the calendar home collection.  Clients wanting to receive
      notifications for this calendar home must subscribe to this node.

   Definition:

   <!ELEMENT xmpp-uri (#PCDATA) >

   Example:  This example describes an XMPP URI which is comprised of
      the CalDAV server's hostname and port, so that multiple CalDAV
      servers can share the same notification server.

   <CS:xmpp-uri
        xmlns:CS="http://calendarserver.org/ns/">
        xmpp:pubsub.notifications.example.com?pubsub;
         node=/Public/CalDAV/notifications.example.com/443/
         calendars/users/sagen/
   </CS:xmpp-uri>

3.3.  XMPP Heartbeat Property

   Name:  xmpp-heartbeat

   Namespace:  http://calendarserver.org/ns/

   Purpose:  Provides the URI of the heartbeat pubsub node and the
      frequency at which it is published.

   Protected:  This property MUST be protected and SHOULD NOT be
      returned by a PROPFIND allprop request (as defined in Section 14.2
      of [RFC4918]).

   COPY/MOVE behavior:  This property value SHOULD be kept during a MOVE
      operation, but is normally re-initialized when a resource is
      created with a COPY.  It should not be set in a COPY.






Sagen                                                           [Page 4]

                         CalDAV PubSub Discovery               June 2009


   Description:  This property MAY be defined on a calendar home
      collection.  If it's not defined, then the server does not support
      heartbeats for this calendar home.  Its value is comprised of two
      elements: the XMPP URI [RFC4622] of the heartbeat pubsub node the
      CalDAV server will publish to periodically, and the frequency (in
      minutes) at which this heartbeat is published.  Clients may
      monitor updates to this heartbeat node to determine whether the
      push notification system is functioning.  If no update is received
      for this node for a period exceeding xmpp-heartbeat-minutes, the
      client can assume that notifications are not working and may fall
      back to polling.

   Definition:

   <!ELEMENT xmpp-hearbeat CS:xmpp-heartbeat-uri,
                           CS:xmpp-heartbeat-minutes>

   <!ELEMENT xmpp-hearbeat-uri (#PCDATA) >

   <!ELEMENT xmpp-hearbeat-minutes (#PCDATA) >


   Example:

   <CS:xmpp-heartbeat>
     <CS:xmpp-heartbeat-uri>
        xmlns:CS="http://calendarserver.org/ns/">
        xmpp:pubsub.notifications.example.com?pubsub;
         node=/Public/CalDAV/notifications.example.com/443/
     </CS:xmpp-heartbeat-uri>
     <CS:xmpp-heartbeat-minutes>30</CS:xmpp-heartbeat-minutes>
   </CS:xmpp-heartbeat>



















Sagen                                                           [Page 5]

                         CalDAV PubSub Discovery               June 2009


4.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC3920]  Saint-Andre, P., Ed., "Extensible Messaging and Presence
              Protocol (XMPP): Core", RFC 3920, October 2004.

   [RFC4622]  Saint-Andre, P., "Internationalized Resource Identifiers
              (IRIs) and Uniform Resource Identifiers (URIs) for the
              Extensible Messaging and Presence Protocol (XMPP)",
              RFC 4622, July 2006.

   [RFC4791]  Daboo, C., Desruisseaux, B., and L. Dusseault,
              "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791,
              March 2007.

   [RFC4918]  Dusseault, L., "HTTP Extensions for Web Distributed
              Authoring and Versioning (WebDAV)", RFC 4918, June 2007.
































Sagen                                                           [Page 6]

                         CalDAV PubSub Discovery               June 2009


Author's Address

   Morgen Sagen
   Apple Inc.
   1 Infinite Loop
   Cupertino, CA  95014
   USA

   Email: sagen@apple.com
   URI:   http://www.apple.com/









































Sagen                                                           [Page 7]

