| Internet-Draft | Enhanced Synchronization for Calendaring | February 2017 |
| Daboo & Murchison | Expires 16 August 2017 | [Page] |
This document defines new protocol features for CalDAV (RFC 4791) to improve the efficiency of synchronizing data changes between a client and server.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 16 August 2017.¶
Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
Thanks to the following for feedback: Mike Douglass, Bron Gondwana.¶
This specification originated from work at the Calendaring and Scheduling Consortium, which has helped with the development and testing of implementations.¶
The CalDAV [RFC4791] protocol is a client/server protocol that supports the exchange of iCalendar [RFC5545] data between a server and clients, as well as supporting scheduling operations on the server (using [RFC6638]). To exchange data, clients and servers use a combination of HTTP PUT, GET and REPORT requests. The REPORT requests include CalDAV "multiget" and "time-range" queries, as well as WebDAV-based synchronization [RFC6578]. Whilst these have proved adequate to date, there is a need to improve the efficiency of data synchronization to lower network I/O requirements, and thus reduce power consumption requirements on mobile devices (which are now frequently used to manage calendars).¶
The iCalendar patch [draft-patch] specification defines a way for clients to incrementally update servers using the HTTP PATCH [RFC5789] method and a new iCalendar-based patch format. This allows a client to only send the pieces of an iCalendar object that have changed, rather than send the entire resource. This can significantly reduce the amount of data sent from the client to the server, particularly in enterprise environments where long-lived recurring events, with many attendees, and many recurrence exceptions are common. However, when data changes on the server, clients are still required to download the entire calendar resource, even when only a small change has taken place. Since many users now have multiple devices that are actively synchronizing with a server (e.g., desktop, laptop, mobile phone, tablet, etc) a small change made on one device will result in large data transfers on the others as they synchronize their local caches.¶
This specification defines new protocol features in CalDAV to support incremental updates to data stored in a client's cache, by sending calendar patch data from the server to the client. These features are intended to be data format agnostic, and can be used with iCalendar patch, and future patch formats whether they be for existing (e.g. jCal [RFC7265], xCal [RFC6321]) or new calendar data formats.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].¶
The notation used in this memo is the ABNF notation of [RFC5234]. Any syntax elements shown below that are not explicitly defined in this specification come from HTTP and CalDAV.¶
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.¶
Synchronization of CalDAV data on a client is nowadays typically accomplished using the WebDAV sync REPORT to detect changes to individual calendar object resources in a calendar collection. Those can be retrieved by the WebDAV sync request itself, or a subsequent series of CalDAV multiget requests can be made to retrieve the changed data. WebDAV sync defines a DAV:sync-token property on collections that support synchronization. The value of that property is an opaque token that serves as a "sync anchor" for retrieval of changes on the server. Each client that maintains a local cache of the data stores the last value of DAV:sync-token for a fully synchronized calendar collection, and then presents that token to the server the next time changes need to be fetched. The server then uses that token to determine what has changed since the client last synchronized, and can return those changes. Since the DAV:sync-token is already being used to track changes on a collection level, it can also be used as a "sync anchor" for the retrieval of incremental changes to the resources within that collection.¶
This specification makes the following changes to CalDAV (with details of each described in subsequent sections):¶
GET and REPORTs which include the CALDAV:calendar-data "property" in the XML body) can include a Prefer request header field [RFC7240] with the "calendar-patch" preference. The client sets the value of the "since" parameter of this preference to a DAV:sync-token value. When such a request is received by the server, if the "since" value represents a valid "sync anchor", the server MAY use calendar patch documents in the HTTP response. Those documents represent the difference between each calendar resource as it was at the time the client-provided "sync anchor" was in effect, and the current state of the resource.¶
MAY use a 304 (Not Modified) status code inside a DAV:propstat element containing a CALDAV:calendar-data element to indicate that there is no difference between the current state of the resource and the state indicated by the "sync anchor".¶
The "calendar-patch" preference indicates that the client wishes for the server to use calendar patch documents in the HTTP response rather than entire calendar resources. The value of the "since" parameter, which MUST be the value of a previously returned DAV:sync-token property, provides the "sync anchor" from which the server should generate the patch documents.¶
ABNF:¶
calendar-patch = "calendar-patch" OWS ";" OWS "since=" sync-token sync-token = DQUOTE absolute-URI DQUOTE¶
GET requests
A client can signal to a server that it is willing and able to receive a calendar patch document rather than an entire calendar resource by including a Prefer header field with the "calendar-patch" preference in a GET request.¶
If a server receives a "calendar-patch" preference, recognizes the supplied sync-token, and is able to create a patch document for the resource in a format compatible with one of the media types supplied in the Accept [RFC7230] request header field, the server MAY respond to the request with the patch document in lieu of the entire resource.¶
EXAMPLE¶
>> Request << GET /events/abcd.ics HTTP/1.1 Host: cal.example.com Prefer: calendar-patch; since="http://example.com/ns/sync/1234" Accept: text/calendar; component=VPATCH >> Response << HTTP/1.1 200 OK Date: Sat, 11 Feb 2017 09:32:12 GMT Content-Type: text/calendar; component=VPATCH; charset="utf-8" Content-Length: yyyy BEGIN:VCALENDAR VERSION:2.0 PRODID:-//Example Corp.//CalDAV Server//EN BEGIN:VPATCH UID:wxyz DTSTAMP:20170201T000000Z BEGIN:PATCH PATCH-TARGET:/VCALENDAR/VEVENT[UID=abcd] BEGIN:VALARM UID:hijk ACTION:DISPLAY TRIGGER:-PT30M DESCRIPTION:Time to leave END:VALARM END:PATCH END:VPATCH END:VCALENDAR¶
A client fetching the CALDAV:calendar-data "property" in a CALDAV:calendar-query or CALDAV:calendar-multiget REPORT can signal to a server that it is willing and able to receive calendar patch documents rather than entire calendar resources by including a Prefer header field with the "calendar-patch" preference in the REPORT request.¶
If a server receives a "calendar-patch" preference, recognizes the supplied sync-token, and is able to create patch documents for resources in a format compatible with the "content-type" attribute of the CALDAV:calendar-data element, the server MAY respond to the request with patch documents in lieu of entire resources. If a resource has not changed since the state indicated by the sync-token, the server MAY respond with a 304 (Not Modified) status code in the DAV:propstat element containing the CALDAV:calendar-data element in lieu of an empty calendar patch document.¶
EXAMPLE¶
>> Request <<
REPORT /events/work/ HTTP/1.1
Host: cal.example.com
Content-Type: application/xml; charset="utf-8"
Content-Length: xxxx
Prefer: calendar-patch; since="http://example.com/ns/sync/1234"
<?xml version="1.0" encoding="utf-8" ?>
<C:calendar-multiget xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:caldav">
<D:prop>
<D:getetag/>
<C:calendar-data content-type="text/calendar; component=VPATCH"/>
</D:prop>
<D:href>/events/work/abcd1.ics</D:href>
<D:href>/events/work/mtg1.ics</D:href>
</C:calendar-multiget>
>> Response <<
HTTP/1.1 207 Multi-Status
Date: Sat, 11 Feb 2017 09:32:12 GMT
Content-Type: application/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:caldav">
<D:response>
<D:href>http://cal.example.com/events/work/abcd1.ics</D:href>
<D:propstat>
<D:prop>
<D:getetag>"fffff-abcd1"</D:getetag>
<C:calendar-data>BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example Corp.//CalDAV Client//EN
BEGIN:VPATCH
UID:qrst
DTSTAMP:20170201T000000Z
BEGIN:PATCH
PATCH-TARGET:/VCALENDAR/VEVENT[UID=abcd1]
ATTENDEE;PATCH-ACTION=BYVALUE;PARTSTAT=ACCEPTED:
mailto:cyrus@example.com
END:PATCH
END:VPATCH
END:VCALENDAR
</C:calendar-data>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>http://cal.example.com/events/work/mtg1.ics</D:href>
<D:propstat>
<D:prop>
<D:getetag>"fffff-wxyz"</D:getetag>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
<D:propstat>
<D:prop>
<C:calendar-data/>
</D:prop>
<D:status>HTTP/1.1 304 Not Modified</D:status>
</D:propstat>
</D:response>
</D:multistatus>¶
REPORT requests
A client fetching the CALDAV:calendar-data "property" in a DAV:sync-collection REPORT can signal to a server that it is willing and able to receive calendar patch documents rather than entire calendar resources by including a Prefer header field with the "calendar-patch" preference in the REPORT request. The value of the sync-token specified in the Prefer request header field MUST match that of the DAV:sync-token element in the REPORT body.¶
If a server receives a "calendar-patch" preference, recognizes the supplied sync-token, and is able to create patch documents for resources in a format compatible with the "content-type" attribute of the CALDAV:calendar-data element, the server MAY respond to the request with patch documents in lieu of entire resources. If a resource has not changed since the state indicated by the sync-token, the server MAY respond with a 304 (Not Modified) status code in the DAV:propstat element containing the CALDAV:calendar-data element in lieu of an empty calendar patch document.¶
EXAMPLE¶
>> Request <<
REPORT /events/work/ HTTP/1.1
Host: cal.example.com
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
Prefer: calendar-patch; since="http://example.com/ns/sync/1234"
<?xml version="1.0" encoding="utf-8" ?>
<D:sync-collection xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:caldav">
<D:sync-token>http://example.com/ns/sync/1234</D:sync-token>
<D:sync-level>1</D:sync-level>
<D:prop>
<D:getetag/>
<C:calendar-data content-type="text/calendar; component=VPATCH"/>
</D:prop>
</D:sync-collection>
>> Response <<
HTTP/1.1 207 Multi-Status
Date: Sat, 11 Feb 2017 09:32:12 GMT
Content-Type: application/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:caldav">
<D:response>
<D:href>http://cal.example.com/events/work/abcd1.ics</D:href>
<D:propstat>
<D:prop>
<D:getetag>"fffff-abcd1"</D:getetag>
<C:calendar-data>BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example Corp.//CalDAV Client//EN
BEGIN:VPATCH
UID:qrst
DTSTAMP:20170201T000000Z
BEGIN:PATCH
PATCH-TARGET:/VCALENDAR/VEVENT[UID=abcd1]
ATTENDEE;PATCH-ACTION=BYVALUE;PARTSTAT=ACCEPTED:
mailto:cyrus@example.com
END:PATCH
END:VPATCH
END:VCALENDAR
</C:calendar-data>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:sync-token>http://example.com/ns/sync/1238</D:sync-token>
</D:multistatus>¶
The following preference is to be added to the HTTP Preferences Registry defined in Section 5.1 of [RFC7240].¶
calendar-patch¶
since = <sync-token>¶
The "calendar-patch" preference indicates that the client wishes for the server to use calendar patch documents in the HTTP response rather than entire calendar resources. The value of the "since" parameter provides the anchor point from which the server should generate the patch documents.¶
This preference is only intended to be used with CalDAV requests that expect calendar data to be included in the response. Furthermore, the "since" parameter is REQUIRED with this preference.¶