<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>[14126] CalendarServer/trunk/doc/Extensions</title>
</head>
<body>
<style type="text/css"><!--
#msg dl.meta { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }
#msg dl.meta dt { float: left; width: 6em; font-weight: bold; }
#msg dt:after { content:':';}
#msg dl, #msg dt, #msg ul, #msg li, #header, #footer, #logmsg { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; }
#msg dl a { font-weight: bold}
#msg dl a:link { color:#fc3; }
#msg dl a:active { color:#ff0; }
#msg dl a:visited { color:#cc6; }
h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; }
#msg pre { overflow: auto; background: #ffc; border: 1px #fa0 solid; padding: 6px; }
#logmsg { background: #ffc; border: 1px #fa0 solid; padding: 1em 1em 0 1em; }
#logmsg p, #logmsg pre, #logmsg blockquote { margin: 0 0 1em 0; }
#logmsg p, #logmsg li, #logmsg dt, #logmsg dd { line-height: 14pt; }
#logmsg h1, #logmsg h2, #logmsg h3, #logmsg h4, #logmsg h5, #logmsg h6 { margin: .5em 0; }
#logmsg h1:first-child, #logmsg h2:first-child, #logmsg h3:first-child, #logmsg h4:first-child, #logmsg h5:first-child, #logmsg h6:first-child { margin-top: 0; }
#logmsg ul, #logmsg ol { padding: 0; list-style-position: inside; margin: 0 0 0 1em; }
#logmsg ul { text-indent: -1em; padding-left: 1em; }#logmsg ol { text-indent: -1.5em; padding-left: 1.5em; }
#logmsg > ul, #logmsg > ol { margin: 0 0 1em 0; }
#logmsg pre { background: #eee; padding: 1em; }
#logmsg blockquote { border: 1px solid #fa0; border-left-width: 10px; padding: 1em 1em 0 1em; background: white;}
#logmsg dl { margin: 0; }
#logmsg dt { font-weight: bold; }
#logmsg dd { margin: 0; padding: 0 0 0.5em 0; }
#logmsg dd:before { content:'\00bb';}
#logmsg table { border-spacing: 0px; border-collapse: collapse; border-top: 4px solid #fa0; border-bottom: 1px solid #fa0; background: #fff; }
#logmsg table th { text-align: left; font-weight: normal; padding: 0.2em 0.5em; border-top: 1px dotted #fa0; }
#logmsg table td { text-align: right; border-top: 1px dotted #fa0; padding: 0.2em 0.5em; }
#logmsg table thead th { text-align: center; border-bottom: 1px solid #fa0; }
#logmsg table th.Corner { text-align: left; }
#logmsg hr { border: none 0; border-top: 2px dashed #fa0; height: 1px; }
#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: 6px; }
#patch { width: 100%; }
#patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}
#patch .propset h4, #patch .binary h4 {margin:0;}
#patch pre {padding:0;line-height:1.2em;margin:0;}
#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}
#patch .propset .diff, #patch .binary .diff {padding:10px 0;}
#patch span {display:block;padding:0 10px;}
#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}
#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}
#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}
#patch .lines, .info {color:#888;background:#fff;}
--></style>
<div id="msg">
<dl class="meta">
<dt>Revision</dt> <dd><a href="http://trac.calendarserver.org//changeset/14126">14126</a></dd>
<dt>Author</dt> <dd>sagen@apple.com</dd>
<dt>Date</dt> <dd>2014-10-30 19:08:53 -0700 (Thu, 30 Oct 2014)</dd>
</dl>
<h3>Log Message</h3>
<pre>Update pubsub spec to describe the push-transports property and APNs</pre>
<h3>Modified Paths</h3>
<ul>
<li><a href="#CalendarServertrunkdocExtensionscaldavpubsubdiscoverytxt">CalendarServer/trunk/doc/Extensions/caldav-pubsubdiscovery.txt</a></li>
<li><a href="#CalendarServertrunkdocExtensionscaldavpubsubdiscoveryxml">CalendarServer/trunk/doc/Extensions/caldav-pubsubdiscovery.xml</a></li>
</ul>
</div>
<div id="patch">
<h3>Diff</h3>
<a id="CalendarServertrunkdocExtensionscaldavpubsubdiscoverytxt"></a>
<div class="modfile"><h4>Modified: CalendarServer/trunk/doc/Extensions/caldav-pubsubdiscovery.txt (14125 => 14126)</h4>
<pre class="diff"><span>
<span class="info">--- CalendarServer/trunk/doc/Extensions/caldav-pubsubdiscovery.txt 2014-10-30 18:29:09 UTC (rev 14125)
+++ CalendarServer/trunk/doc/Extensions/caldav-pubsubdiscovery.txt 2014-10-31 02:08:53 UTC (rev 14126)
</span><span class="lines">@@ -1,62 +1,31 @@
</span><del>-
-
-
-Calendar Server Extension M. Sagen
</del><ins>+ M. Sagen
</ins><span class="cx"> Apple
</span><del>- June 5, 2009
</del><ins>+ October 30, 2014
</ins><span class="cx">
</span><span class="cx">
</span><span class="cx"> Discovery of CalDAV Push-Notification Settings
</span><ins>+ caldav-pubsubdiscovery-02
</ins><span class="cx">
</span><span class="cx"> Abstract
</span><span class="cx">
</span><del>- This specification defines three new WebDAV properties that allow
- clients to discover push-notification subscription information,
- eliminating the need for polling.
</del><ins>+ This specification defines new WebDAV properties that allow clients
+ to discover and subscribe to change notifications, eliminating the
+ need for polling.
</ins><span class="cx">
</span><del>-
</del><span class="cx"> Table of Contents
</span><span class="cx">
</span><del>- 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
</del><ins>+ 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
</ins><span class="cx">
</span><del>-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Sagen [Page 1]
-
- CalDAV PubSub Discovery June 2009
-
-
</del><span class="cx"> 1. Introduction
</span><span class="cx">
</span><span class="cx"> The CalDAV [RFC4791] standard defines a way to access calendar data
</span><span class="lines">@@ -66,29 +35,28 @@
</span><span class="cx"> notifications would allow near real time propagation of updates and
</span><span class="cx"> potentially reduce the number of requests.
</span><span class="cx">
</span><del>- 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.
</del><ins>+ 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.
</ins><span class="cx">
</span><del>- 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.
</del><ins>+ 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
</ins><span class="cx">
</span><del>- 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.
</del><span class="cx">
</span><span class="cx">
</span><ins>+
+Sagen Expires May 3, 2015 [Page 1]
+
+ CalDAV PubSub Discovery October 2014
+
+
+ queries the CalDAV/CardDAV server to see which resources have
+ changed.
+
</ins><span class="cx"> 2. Conventions Used in This Document
</span><span class="cx">
</span><span class="cx"> The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
</span><span class="lines">@@ -106,23 +74,16 @@
</span><span class="cx"> of an XML fragment, the string "CS:" will be prefixed to the element
</span><span class="cx"> type names respectively.
</span><span class="cx">
</span><del>-
-
-Sagen [Page 2]
-
- CalDAV PubSub Discovery June 2009
-
-
</del><span class="cx"> 3. New Properties
</span><span class="cx">
</span><del>-3.1. XMPP Server Property
</del><ins>+3.1. Push Transports Property
</ins><span class="cx">
</span><del>- Name: xmpp-server
</del><ins>+ Name: push-transports
</ins><span class="cx">
</span><span class="cx"> Namespace: http://calendarserver.org/ns/
</span><span class="cx">
</span><del>- Purpose: Provides the hostname of the XMPP server a client should
- connect to for subscribing to notifications.
</del><ins>+ Purpose: Advertises the list of push transports supported by the
+ server.
</ins><span class="cx">
</span><span class="cx"> Protected: This property MUST be protected and SHOULD NOT be
</span><span class="cx"> returned by a PROPFIND allprop request (as defined in Section 14.2
</span><span class="lines">@@ -132,168 +93,168 @@
</span><span class="cx"> operation, but is normally re-initialized when a resource is
</span><span class="cx"> created with a COPY. It should not be set in a COPY.
</span><span class="cx">
</span><del>- 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.
</del><ins>+ 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.
</ins><span class="cx">
</span><span class="cx"> Definition:
</span><span class="cx">
</span><del>- <!ELEMENT xmpp-server (#PCDATA) >
</del><span class="cx">
</span><del>- Example: This example indicates that the CalDAV server is using host
- notifications.example.com for sending push notifications.
</del><span class="cx">
</span><del>- <CS:xmpp-server
- xmlns:CS="http://calendarserver.org/ns/">
- notifications.example.com
- </CS:xmpp-server>
</del><span class="cx">
</span><del>-3.2. XMPP URI Property
</del><span class="cx">
</span><del>- Name: xmpp-uri
</del><span class="cx">
</span><del>- Namespace: http://calendarserver.org/ns/
</del><ins>+Sagen Expires May 3, 2015 [Page 2]
+
+ CalDAV PubSub Discovery October 2014
</ins><span class="cx">
</span><del>- 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.
</del><span class="cx">
</span><ins>+<!ELEMENT push-transports (transport) >
</ins><span class="cx">
</span><ins>+<!ELEMENT transport (subscription-url, apsbundleid, env, refresh-interval) >
+<!-- The transport element must have a 'type' attribute identifying the transport type. For Apple Push the attribute value should be 'APSD'. -->
</ins><span class="cx">
</span><ins>+<!ELEMENT subscription-url (DAV:href) >
+<!-- The URL clients should send their subscription requests to. -->
</ins><span class="cx">
</span><ins>+<!ELEMENT apsbundleid (CDATA) >
+<!-- The Apple Push "topic", which is extracted from the UID portion of the subject of the certificate acquired from Apple. The topic is currently the bundle identifier of the target app. -->
</ins><span class="cx">
</span><del>-Sagen [Page 3]
-
- CalDAV PubSub Discovery June 2009
</del><ins>+<!ELEMENT env (CDATA) >
+<!-- "PRODUCTION" if the clients should talk to the production APNs servers or "SANDBOX" if the clients should talk to the sandbox APNs servers -->
</ins><span class="cx">
</span><ins>+<!ELEMENT refresh-interval (CDATA) >
+<!-- An integer value indicating how often (in seconds) the client should refresh their subscriptions, since the server will remove subscriptions that are not refreshed within this time period -->
</ins><span class="cx">
</span><del>- Protected: This property MUST be protected and SHOULD NOT be
- returned by a PROPFIND allprop request (as defined in Section 14.2
- of [RFC4918]).
</del><span class="cx">
</span><del>- 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.
</del><ins>+ 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).
</ins><span class="cx">
</span><del>- 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.
</del><ins>+<push-transports xmlns='http://calendarserver.org/ns/'>
+ <transport type='APSD'>
+ <subscription-url>
+ <href xmlns='DAV:'>https://server.example.com:8443/apns</href>
+ </subscription-url>
+ <apsbundleid>com.apple.calendar.XServer.934668ca-125e-4246-afee-8cf2df37aab8</apsbundleid>
+ <env>PRODUCTION</env>
+ <refresh-interval>172800</refresh-interval>
+ </transport>
+</push-transports>
</ins><span class="cx">
</span><del>- Definition:
</del><ins>+3.2. Push Key Property
</ins><span class="cx">
</span><del>- <!ELEMENT xmpp-uri (#PCDATA) >
</del><ins>+ Name: pushkey
</ins><span class="cx">
</span><del>- 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
-
</del><span class="cx"> Namespace: http://calendarserver.org/ns/
</span><span class="cx">
</span><del>- Purpose: Provides the URI of the heartbeat pubsub node and the
- frequency at which it is published.
</del><ins>+ Purpose: Provides the push key to subscribe to in order to receive a
+ notification whenever a resource within this collection has
+ changed.
</ins><span class="cx">
</span><span class="cx"> Protected: This property MUST be protected and SHOULD NOT be
</span><span class="cx"> returned by a PROPFIND allprop request (as defined in Section 14.2
</span><span class="cx"> of [RFC4918]).
</span><span class="cx">
</span><del>- 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.
</del><span class="cx">
</span><span class="cx">
</span><span class="cx">
</span><del>-
-
-
-Sagen [Page 4]
</del><ins>+Sagen Expires May 3, 2015 [Page 3]
</ins><span class="cx">
</span><del>- CalDAV PubSub Discovery June 2009
</del><ins>+ CalDAV PubSub Discovery October 2014
</ins><span class="cx">
</span><span class="cx">
</span><del>- 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.
</del><ins>+ 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.
</ins><span class="cx">
</span><ins>+ 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.
+
</ins><span class="cx"> Definition:
</span><span class="cx">
</span><del>- <!ELEMENT xmpp-hearbeat CS:xmpp-heartbeat-uri,
- CS:xmpp-heartbeat-minutes>
</del><ins>+ <!ELEMENT pushkey (CDATA) >
</ins><span class="cx">
</span><del>- <!ELEMENT xmpp-hearbeat-uri (#PCDATA) >
</del><ins>+ Example: This example indicates the push key for a collection is the
+ UUID '6D6241DC-5981-4D87-9B71-672203E81ACB'.
</ins><span class="cx">
</span><del>- <!ELEMENT xmpp-hearbeat-minutes (#PCDATA) >
</del><ins>+<pushkey xmlns='http://calendarserver.org/ns/'>6D6241DC-5981-4D87-9B71-672203E81ACB/</pushkey>
</ins><span class="cx">
</span><ins>+4. Subscription Process
</ins><span class="cx">
</span><del>- Example:
</del><ins>+4.1. Discovery
</ins><span class="cx">
</span><del>- <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>
</del><ins>+ 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.
</ins><span class="cx">
</span><ins>+4.2. Subscription
</ins><span class="cx">
</span><ins>+ 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
</ins><span class="cx">
</span><span class="cx">
</span><span class="cx">
</span><ins>+Sagen Expires May 3, 2015 [Page 4]
+
+ CalDAV PubSub Discovery October 2014
</ins><span class="cx">
</span><span class="cx">
</span><ins>+ 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.
</ins><span class="cx">
</span><ins>+4.3. Payload
</ins><span class="cx">
</span><ins>+ The payload of each push notification will contain:
</ins><span class="cx">
</span><ins>+ "key" - the push key of the collection
</ins><span class="cx">
</span><ins>+ "dataChangedTimestamp" - the unix epoch time (in seconds) when the
+ change that triggered this notification took place
</ins><span class="cx">
</span><ins>+ "pushRequestSubmittedTimestamp" - the unix epoch time (in seconds)
+ when the CalDAV/CardDAV server sent the notification to the APNs
+ servers
</ins><span class="cx">
</span><ins>+5. Normative References
</ins><span class="cx">
</span><ins>+ [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>.
</ins><span class="cx">
</span><del>-
-
-
-
-Sagen [Page 5]
-
- CalDAV PubSub Discovery June 2009
-
-
-4. Normative References
-
</del><span class="cx"> [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
</span><span class="cx"> Requirement Levels", BCP 14, RFC 2119, March 1997.
</span><span class="cx">
</span><del>- [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.
-
</del><span class="cx"> [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault,
</span><span class="cx"> "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791,
</span><span class="cx"> March 2007.
</span><span class="lines">@@ -301,6 +262,7 @@
</span><span class="cx"> [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed
</span><span class="cx"> Authoring and Versioning (WebDAV)", RFC 4918, June 2007.
</span><span class="cx">
</span><ins>+Author's Address
</ins><span class="cx">
</span><span class="cx">
</span><span class="cx">
</span><span class="lines">@@ -311,34 +273,11 @@
</span><span class="cx">
</span><span class="cx">
</span><span class="cx">
</span><del>-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Sagen [Page 6]
</del><ins>+Sagen Expires May 3, 2015 [Page 5]
</ins><span class="cx">
</span><del>- CalDAV PubSub Discovery June 2009
</del><ins>+ CalDAV PubSub Discovery October 2014
</ins><span class="cx">
</span><span class="cx">
</span><del>-Author's Address
-
</del><span class="cx"> Morgen Sagen
</span><span class="cx"> Apple Inc.
</span><span class="cx"> 1 Infinite Loop
</span><span class="lines">@@ -388,5 +327,6 @@
</span><span class="cx">
</span><span class="cx">
</span><span class="cx">
</span><del>-Sagen [Page 7]
-
</del><ins>+
+
+Sagen Expires May 3, 2015 [Page 6]
</ins><span class="cx">\ No newline at end of file
</span></span></pre></div>
<a id="CalendarServertrunkdocExtensionscaldavpubsubdiscoveryxml"></a>
<div class="modfile"><h4>Modified: CalendarServer/trunk/doc/Extensions/caldav-pubsubdiscovery.xml (14125 => 14126)</h4>
<pre class="diff"><span>
<span class="info">--- CalendarServer/trunk/doc/Extensions/caldav-pubsubdiscovery.xml 2014-10-30 18:29:09 UTC (rev 14125)
+++ CalendarServer/trunk/doc/Extensions/caldav-pubsubdiscovery.xml 2014-10-31 02:08:53 UTC (rev 14126)
</span><span class="lines">@@ -1,11 +1,9 @@
</span><span class="cx"> <?xml version="1.0" encoding="UTF-8"?>
</span><span class="cx"> <!DOCTYPE rfc SYSTEM 'rfc2629.dtd' [
</span><span class="cx"> <!ENTITY rfc2119 PUBLIC '' 'bibxml/reference.RFC.2119.xml'>
</span><del>-<!ENTITY rfc3920 PUBLIC '' 'bibxml/reference.RFC.3920.xml'>
-<!ENTITY rfc4622 PUBLIC '' 'bibxml/reference.RFC.4622.xml'>
</del><span class="cx"> <!ENTITY rfc4791 PUBLIC '' 'bibxml/reference.RFC.4791.xml'>
</span><span class="cx"> <!ENTITY rfc4918 PUBLIC '' 'bibxml/reference.RFC.4918.xml'>
</span><del>-]>
</del><ins>+]>
</ins><span class="cx"> <?rfc toc="yes"?>
</span><span class="cx"> <?rfc tocdepth="4"?>
</span><span class="cx"> <?rfc strict="yes"?>
</span><span class="lines">@@ -16,7 +14,7 @@
</span><span class="cx"> <?rfc compact="yes"?>
</span><span class="cx"> <?rfc subcompact="no"?>
</span><span class="cx"> <?rfc private="Calendar Server Extension"?>
</span><del>-<rfc ipr="none" docName='caldav-pubsubdiscovery-01'>
</del><ins>+<rfc ipr="none" docName='caldav-pubsubdiscovery-02'>
</ins><span class="cx"> <front>
</span><span class="cx"> <title abbrev="CalDAV PubSub Discovery">Discovery of CalDAV Push-Notification Settings</title>
</span><span class="cx"> <author initials="M." surname="Sagen" fullname="Morgen Sagen">
</span><span class="lines">@@ -28,7 +26,7 @@
</span><span class="cx"> <street>1 Infinite Loop</street>
</span><span class="cx"> <city>Cupertino</city>
</span><span class="cx"> <region>CA</region>
</span><del>- <code>95014</code>
</del><ins>+ <code>95014</code>
</ins><span class="cx"> <country>USA</country>
</span><span class="cx"> </postal>
</span><span class="cx"> <email>sagen@apple.com</email>
</span><span class="lines">@@ -38,7 +36,7 @@
</span><span class="cx"> <date/>
</span><span class="cx"> <abstract>
</span><span class="cx"> <t>
</span><del>- This specification defines three new WebDAV properties that allow clients to discover push-notification subscription information, eliminating the need for polling.
</del><ins>+ This specification defines new WebDAV properties that allow clients to discover and subscribe to change notifications, eliminating the need for polling.
</ins><span class="cx"> </t>
</span><span class="cx"> </abstract>
</span><span class="cx"> </front>
</span><span class="lines">@@ -48,87 +46,103 @@
</span><span class="cx"> The <xref target="RFC4791">CalDAV</xref> 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.
</span><span class="cx"> </t>
</span><span class="cx"> <t>
</span><del>- <xref target="RFC3920">XMPP</xref>, 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.
</del><ins>+ The <xref target="APPLE.APNS">Apple Push Notification Service</xref> (APNs for short)
+ is a service for propagating information to iOS and OS X devices in
+ an efficient manner.
</ins><span class="cx"> </t>
</span><span class="cx"> <t>
</span><del>- 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.
</del><ins>+ 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 queries the CalDAV/CardDAV server to see which resources have changed.
</ins><span class="cx"> </t>
</span><del>- <t>
- 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.
- </t>
</del><span class="cx"> </section>
</span><span class="cx"> <section title='Conventions Used in This Document'>
</span><span class="cx"> <t>
</span><del>- 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 <xref target='RFC2119' />.
</del><ins>+ 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 <xref target='RFC2119' />.
</ins><span class="cx"> </t>
</span><span class="cx"> <t>
</span><del>- 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.
</del><ins>+ 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.
</ins><span class="cx"> </t>
</span><span class="cx"> <t>
</span><del>- 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.
</del><ins>+ 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.
</ins><span class="cx"> </t>
</span><span class="cx"> </section>
</span><del>-
</del><ins>+
</ins><span class="cx"> <section title='New Properties'>
</span><del>- <section title="XMPP Server Property">
</del><ins>+ <section title="Push Transports Property">
</ins><span class="cx"> <t>
</span><span class="cx"> <?rfc compact="no" ?>
</span><span class="cx"> <list style="hanging">
</span><del>- <t hangText="Name:">xmpp-server</t>
</del><ins>+ <t hangText="Name:">push-transports</t>
</ins><span class="cx"> <t hangText="Namespace:">http://calendarserver.org/ns/</t>
</span><del>- <t hangText="Purpose:">Provides the hostname of the XMPP server a client should connect to for subscribing to notifications.</t>
</del><ins>+ <t hangText="Purpose:">Advertises the list of push transports supported by the server.</t>
</ins><span class="cx"> <t hangText="Protected:">This property MUST be protected and SHOULD NOT be returned by a PROPFIND allprop request (as defined in Section 14.2 of <xref target="RFC4918"/>).</t>
</span><span class="cx"> <t hangText="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.</t>
</span><del>- <t hangText="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.</t>
</del><ins>+ <t hangText="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.</t>
</ins><span class="cx"> <t hangText="Definition:">
</span><span class="cx"> <figure>
</span><span class="cx"> <artwork><![CDATA[
</span><del>-<!ELEMENT xmpp-server (#PCDATA) >
</del><ins>+<!ELEMENT push-transports (transport) >
+
+<!ELEMENT transport (subscription-url, apsbundleid, env, refresh-interval) >
+<!-- The transport element must have a 'type' attribute identifying the transport type. For Apple Push the attribute value should be 'APSD'. -->
+
+<!ELEMENT subscription-url (DAV:href) >
+<!-- The URL clients should send their subscription requests to. -->
+
+<!ELEMENT apsbundleid (CDATA) >
+<!-- The Apple Push "topic", which is extracted from the UID portion of the subject of the certificate acquired from Apple. The topic is currently the bundle identifier of the target app. -->
+
+<!ELEMENT env (CDATA) >
+<!-- "PRODUCTION" if the clients should talk to the production APNs servers or "SANDBOX" if the clients should talk to the sandbox APNs servers -->
+
+<!ELEMENT refresh-interval (CDATA) >
+<!-- An integer value indicating how often (in seconds) the client should refresh their subscriptions, since the server will remove subscriptions that are not refreshed within this time period -->
+
</ins><span class="cx"> ]]></artwork>
</span><ins>+
</ins><span class="cx"> </figure>
</span><span class="cx"> </t>
</span><span class="cx"> <t hangText="Example:">
</span><del>- This example indicates that the CalDAV server is using host notifications.example.com for sending push notifications.
</del><ins>+ 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).
</ins><span class="cx"> <figure>
</span><span class="cx"> <artwork><![CDATA[
</span><del>-<CS:xmpp-server
- xmlns:CS="http://calendarserver.org/ns/">
- notifications.example.com
-</CS:xmpp-server>
- ]]></artwork>
</del><ins>+<push-transports xmlns='http://calendarserver.org/ns/'>
+ <transport type='APSD'>
+ <subscription-url>
+ <href xmlns='DAV:'>https://server.example.com:8443/apns</href>
+ </subscription-url>
+ <apsbundleid>com.apple.calendar.XServer.934668ca-125e-4246-afee-8cf2df37aab8</apsbundleid>
+ <env>PRODUCTION</env>
+ <refresh-interval>172800</refresh-interval>
+ </transport>
+</push-transports> ]]></artwork>
</ins><span class="cx"> </figure>
</span><span class="cx"> </t>
</span><span class="cx"> </list>
</span><span class="cx"> </t>
</span><span class="cx"> </section>
</span><span class="cx">
</span><del>- <section title="XMPP URI Property">
</del><ins>+ <section title="Push Key Property">
</ins><span class="cx"> <t>
</span><span class="cx"> <?rfc compact="no" ?>
</span><span class="cx"> <list style="hanging">
</span><del>- <t hangText="Name:">xmpp-uri</t>
</del><ins>+ <t hangText="Name:">pushkey</t>
</ins><span class="cx"> <t hangText="Namespace:">http://calendarserver.org/ns/</t>
</span><del>- <t hangText="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.</t>
</del><ins>+ <t hangText="Purpose:">Provides the push key to subscribe to in order to receive a notification whenever a resource within this collection has changed.</t>
</ins><span class="cx"> <t hangText="Protected:">This property MUST be protected and SHOULD NOT be returned by a PROPFIND allprop request (as defined in Section 14.2 of <xref target="RFC4918"/>).</t>
</span><span class="cx"> <t hangText="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.</t>
</span><del>- <t hangText="Description:">This property MUST be defined on a calendar home collection. Its value is the <xref target="RFC4622">XMPP URI</xref> 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.</t>
</del><ins>+ <t hangText="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.</t>
</ins><span class="cx"> <t hangText="Definition:">
</span><span class="cx"> <figure>
</span><span class="cx"> <artwork><![CDATA[
</span><del>-<!ELEMENT xmpp-uri (#PCDATA) >
</del><ins>+<!ELEMENT pushkey (CDATA) >
</ins><span class="cx"> ]]></artwork>
</span><span class="cx"> </figure>
</span><span class="cx"> </t>
</span><span class="cx"> <t hangText="Example:">
</span><del>- 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.
</del><ins>+ This example indicates the push key for a collection is the UUID '6D6241DC-5981-4D87-9B71-672203E81ACB'.
</ins><span class="cx"> <figure>
</span><span class="cx"> <artwork><![CDATA[
</span><del>-<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>
</del><ins>+<pushkey xmlns='http://calendarserver.org/ns/'>6D6241DC-5981-4D87-9B71-672203E81ACB/</pushkey>
</ins><span class="cx"> ]]></artwork>
</span><span class="cx"> </figure>
</span><span class="cx"> </t>
</span><span class="lines">@@ -136,56 +150,49 @@
</span><span class="cx"> </t>
</span><span class="cx"> </section>
</span><span class="cx">
</span><del>- <section title="XMPP Heartbeat Property">
</del><ins>+ </section>
+ <section title='Subscription Process'>
+ <section title="Discovery">
</ins><span class="cx"> <t>
</span><del>-<?rfc compact="no" ?>
</del><ins>+ 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.
+ </t>
+ </section>
+ <section title="Subscription">
+ <t>
+ 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 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.
+ </t>
+ </section>
+ <section title="Payload">
+ <t>
+ The payload of each push notification will contain:
</ins><span class="cx"> <list style="hanging">
</span><del>- <t hangText="Name:">xmpp-heartbeat</t>
- <t hangText="Namespace:">http://calendarserver.org/ns/</t>
- <t hangText="Purpose:">Provides the URI of the heartbeat pubsub node and the frequency at which it is published.</t>
- <t hangText="Protected:">This property MUST be protected and SHOULD NOT be returned by a PROPFIND allprop request (as defined in Section 14.2 of <xref target="RFC4918"/>).</t>
- <t hangText="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.</t>
- <t hangText="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 <xref target="RFC4622">XMPP URI</xref> 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.</t>
- <t hangText="Definition:">
- <figure>
- <artwork><![CDATA[
-<!ELEMENT xmpp-hearbeat CS:xmpp-heartbeat-uri,
- CS:xmpp-heartbeat-minutes>
</del><ins>+ <t>"key" - the push key of the collection</t>
+ <t>"dataChangedTimestamp" - the unix epoch time (in seconds) when the change that triggered this notification took place</t>
+ <t>"pushRequestSubmittedTimestamp" - the unix epoch time (in seconds) when the CalDAV/CardDAV server sent the notification to the APNs servers</t>
+ </list>
+ </t>
+ </section>
</ins><span class="cx">
</span><del>-<!ELEMENT xmpp-hearbeat-uri (#PCDATA) >
-
-<!ELEMENT xmpp-hearbeat-minutes (#PCDATA) >
-
-]]></artwork>
- </figure>
- </t>
- <t hangText="Example:">
- <figure>
- <artwork><![CDATA[
-<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>
- ]]></artwork>
- </figure>
- </t>
- </list>
- </t>
- </section>
</del><span class="cx"> </section>
</span><span class="cx">
</span><span class="cx"> </middle>
</span><span class="cx"> <back>
</span><span class="cx"> <references title='Normative References'>
</span><span class="cx"> &rfc2119;
</span><del>- &rfc3920;
- &rfc4622;
</del><span class="cx"> &rfc4791;
</span><span class="cx"> &rfc4918;
</span><ins>+ <reference anchor='APPLE.APNS' target=' https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/ApplePushService.html'>
+ <front>
+ <title>Apple Push Notification Service</title>
+ <author>
+ <organization>Apple Inc.</organization>
+ </author>
+ <date month='October' day='16' year='2014' />
+ </front>
+
+ <seriesInfo name='Apple Inc' value='iOS Developer Library'/>
+ <format type='HTML' target='https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/ApplePushService.html' />
+ </reference>
</ins><span class="cx"> </references>
</span><span class="cx"> </back>
</span><span class="cx"> </rfc>
</span></span></pre>
</div>
</div>
</body>
</html>