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: Example: This example indicates that the CalDAV server is using host notifications.example.com for sending push notifications. notifications.example.com 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: 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. xmpp:pubsub.notifications.example.com?pubsub; node=/Public/CalDAV/notifications.example.com/443/ calendars/users/sagen/ 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: Example: xmlns:CS="http://calendarserver.org/ns/"> xmpp:pubsub.notifications.example.com?pubsub; node=/Public/CalDAV/notifications.example.com/443/ 30 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]