M. Sagen
Apple
October 30, 2014
Discovery of CalDAV Push-Notification Settings
caldav-pubsubdiscovery-02
Abstract
This specification defines new WebDAV properties that allow clients
to discover and subscribe to change notifications, eliminating the
need for polling.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 1
2. Conventions Used in This Document . . . . . . . . . . . . . . 2
3. New Properties . . . . . . . . . . . . . . . . . . . . . . . 2
3.1. Push Transports Property . . . . . . . . . . . . . . . . 2
3.2. Push Key Property . . . . . . . . . . . . . . . . . . . . 3
4. Subscription Process . . . . . . . . . . . . . . . . . . . . 4
4.1. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 4
4.2. Subscription . . . . . . . . . . . . . . . . . . . . . . 4
4.3. Payload . . . . . . . . . . . . . . . . . . . . . . . . . 5
5. Normative References . . . . . . . . . . . . . . . . . . . . 5
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 5
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.
The Apple Push Notification Service [APPLE.APNS] (APNs for short) is
a service for propagating information to iOS and OS X devices in an
efficient manner.
A push-notification-capable CalDAV/CardDAV server advertises the
capability via a DAV property ("push-transports") on calendar and
addressbook home resources. Each calendar and addressbook collection
resource has another DAV property ("pushkey") which is an opaque
token a client can use to subscribe to change notifications for that
collection. When the client receives such a notification, the client
Sagen Expires May 3, 2015 [Page 1]
CalDAV PubSub Discovery October 2014
queries the CalDAV/CardDAV server to see which resources have
changed.
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.
3. New Properties
3.1. Push Transports Property
Name: push-transports
Namespace: http://calendarserver.org/ns/
Purpose: Advertises the list of push transports supported by the
server.
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 or
addressbook home collection and MUST NOT be defined on a calendar
or addressbook collection. Its value is an XML element whose
child elements each represent a supported push transport protocol.
Definition:
Sagen Expires May 3, 2015 [Page 2]
CalDAV PubSub Discovery October 2014
Example: This example indicates the CalDAV/CardDAV server is using
the production APNs service and clients should send their
subscription requests to https://server.example.com:8443/apns at
least every 172800 seconds (2 days).
https://server.example.com:8443/apns
com.apple.calendar.XServer.934668ca-125e-4246-afee-8cf2df37aab8
PRODUCTION
172800
3.2. Push Key Property
Name: pushkey
Namespace: http://calendarserver.org/ns/
Purpose: Provides the push key to subscribe to in order to receive a
notification whenever a resource within this collection has
changed.
Protected: This property MUST be protected and SHOULD NOT be
returned by a PROPFIND allprop request (as defined in Section 14.2
of [RFC4918]).
Sagen Expires May 3, 2015 [Page 3]
CalDAV PubSub Discovery October 2014
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 calendar and
addressbook home collections as well as calendar and addressbook
collections. Its value is a server-generated string associated
with a collection. The client must send a subscription request
containing the "push key" string to subscribe to change
notifications for the collection. The push key for a calendar or
addressbook collection will normally be the same value as the
containing home collection. However, there are circumstances
(such as shared collections) where the push keys for collections
are not the same as the containing home, and thus clients should
subscribe to the push keys for the home collection and each
contained collection.
Definition:
Example: This example indicates the push key for a collection is the
UUID '6D6241DC-5981-4D87-9B71-672203E81ACB'.
6D6241DC-5981-4D87-9B71-672203E81ACB/
4. Subscription Process
4.1. Discovery
To subscribe to change notifications, the client must first fetch the
"push-transports" property for the principal's calendar or
addressbook home. The "transport" child element with type set to
"APSD" identifies the APNs configuration. The "subscription-url"
element identifies the URL clients will need to send subscription
requests to. Next, for each home and collection the client is
interested in receiving change notifications for, the client should
fetch the "pushkey" property. Some collections' push keys will be
the same as their parent collection, but not always. Each unique
push key the client finds should be subscribed to at least every
"refresh-interval" seconds.
4.2. Subscription
As per the APNs documentation, the client must acquire a "device
token" identifying the device to the APNs servers. Next, for each
unique push key the client wants to subscribe to, the client must
send an authenticated HTTP request including the device token and
Sagen Expires May 3, 2015 [Page 4]
CalDAV PubSub Discovery October 2014
push key values to the URL identified by subscription-url. The field
names to use are "token" and "key", respectively. If the client uses
GET, the token and key can be passed as query string parameters; if
using POST they can be sent as form fields. The server will return
an HTTP status code OK (200) if the subscription was successful, or
BAD_REQUEST (400) with an explanation message in the response body
otherwise.
4.3. Payload
The payload of each push notification will contain:
"key" - the push key of the collection
"dataChangedTimestamp" - the unix epoch time (in seconds) when the
change that triggered this notification took place
"pushRequestSubmittedTimestamp" - the unix epoch time (in seconds)
when the CalDAV/CardDAV server sent the notification to the APNs
servers
5. Normative References
[APPLE.APNS]
Apple Inc., "Apple Push Notification Service", Apple Inc
iOS Developer Library, October 2014, < https://developer.a
pple.com/library/ios/documentation/NetworkingInternet/Conc
eptual/RemoteNotificationsPG/Chapters/
ApplePushService.html>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[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.
Author's Address
Sagen Expires May 3, 2015 [Page 5]
CalDAV PubSub Discovery October 2014
Morgen Sagen
Apple Inc.
1 Infinite Loop
Cupertino, CA 95014
USA
Email: sagen@apple.com
URI: http://www.apple.com/
Sagen Expires May 3, 2015 [Page 6]