Network Working Group C. Daboo
Internet-Draft Apple Inc.
Updates: 4791 (if approved) K. Murchison
Intended status: Standards Track Carnegie Mellon University
Expires: August 16, 2017 February 12, 2017
Enhanced Synchronization for Calendaring Extensions to WebDAV (CalDAV)
draft-daboo-caldav-sync-00
Abstract
This document defines new protocol features for CalDAV (RFC 4791) to
improve the efficiency of synchronizing data changes between a client
and server.
Open Issues
o Should the "since" parameter to the "calendar-patch" preference be
optional when used with DAV:sync-collection REPORT?
Status of This Memo
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 August 16, 2017.
Copyright Notice
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
Daboo & Murchison Expires August 16, 2017 [Page 1]
Internet-Draft CalDAV Enhanced Synchronization February 2017
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Conventions Used in This Document . . . . . . . . . . . . . . 3
3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 3
4. The "calendar-patch" Preference . . . . . . . . . . . . . . . 4
5. Changes to GET requests . . . . . . . . . . . . . . . . . . . 4
6. Changes to CalDAV REPORT requests . . . . . . . . . . . . . . 5
7. Changes to WebDAV Sync Collection REPORT requests . . . . . . 8
8. Security Considerations . . . . . . . . . . . . . . . . . . . 9
9. Privacy Considerations . . . . . . . . . . . . . . . . . . . 9
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 10
12. Normative References . . . . . . . . . . . . . . . . . . . . 10
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11
1. Introduction
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
Daboo & Murchison Expires August 16, 2017 [Page 2]
Internet-Draft CalDAV Enhanced Synchronization February 2017
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.
2. Conventions Used in This Document
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 [RFC7230] and CalDAV [RFC4791].
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.
3. Overview
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.
Daboo & Murchison Expires August 16, 2017 [Page 3]
Internet-Draft CalDAV Enhanced Synchronization February 2017
This specification makes the following changes to CalDAV (with
details of each described in subsequent sections):
o HTTP requests that expect calendar data to be included in the
response (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.
o HTTP multi-status responses that include calendar patch documents
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".
4. The "calendar-patch" Preference
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
5. Changes to 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
Daboo & Murchison Expires August 16, 2017 [Page 4]
Internet-Draft CalDAV Enhanced Synchronization February 2017
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
6. Changes to CalDAV REPORT requests
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.
Daboo & Murchison Expires August 16, 2017 [Page 5]
Internet-Draft CalDAV Enhanced Synchronization February 2017
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"
/events/work/abcd1.ics
/events/work/mtg1.ics
>> Response <<
Daboo & Murchison Expires August 16, 2017 [Page 6]
Internet-Draft CalDAV Enhanced Synchronization February 2017
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
http://cal.example.com/events/work/abcd1.ics
"fffff-abcd1"
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
HTTP/1.1 200 OK
http://cal.example.com/events/work/mtg1.ics
"fffff-wxyz"
HTTP/1.1 200 OK
HTTP/1.1 304 Not Modified
Daboo & Murchison Expires August 16, 2017 [Page 7]
Internet-Draft CalDAV Enhanced Synchronization February 2017
7. Changes to WebDAV Sync Collection 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"
http://example.com/ns/sync/1234
1
Daboo & Murchison Expires August 16, 2017 [Page 8]
Internet-Draft CalDAV Enhanced Synchronization February 2017
>> 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
http://cal.example.com/events/work/abcd1.ics
"fffff-abcd1"
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
HTTP/1.1 200 OK
http://example.com/ns/sync/1238
8. Security Considerations
Security considerations described in [RFC5545], [RFC5789], and
[RFC4791] MUST be adhered to.
9. Privacy Considerations
Privacy considerations described in [RFC5545], [RFC5789], and
[RFC4791] MUST be adhered to.
Daboo & Murchison Expires August 16, 2017 [Page 9]
Internet-Draft CalDAV Enhanced Synchronization February 2017
10. IANA Considerations
The following preference is to be added to the HTTP Preferences
Registry defined in Section 5.1 of [RFC7240].
Preference: calendar-patch
Parameters: since =
Description: 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.
Reference: RFCXXXX, Section 4
Notes: 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.
11. Acknowledgments
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.
12. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
.
[RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault,
"Calendaring Extensions to WebDAV (CalDAV)", RFC 4791,
DOI 10.17487/RFC4791, March 2007,
.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234,
DOI 10.17487/RFC5234, January 2008,
.
Daboo & Murchison Expires August 16, 2017 [Page 10]
Internet-Draft CalDAV Enhanced Synchronization February 2017
[RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and
Scheduling Core Object Specification (iCalendar)",
RFC 5545, DOI 10.17487/RFC5545, September 2009,
.
[RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP",
RFC 5789, DOI 10.17487/RFC5789, March 2010,
.
[RFC6321] Daboo, C., Douglass, M., and S. Lees, "xCal: The XML
Format for iCalendar", RFC 6321, DOI 10.17487/RFC6321,
August 2011, .
[RFC6578] Daboo, C. and A. Quillaud, "Collection Synchronization for
Web Distributed Authoring and Versioning (WebDAV)",
RFC 6578, DOI 10.17487/RFC6578, March 2012,
.
[RFC6638] Daboo, C. and B. Desruisseaux, "Scheduling Extensions to
CalDAV", RFC 6638, DOI 10.17487/RFC6638, June 2012,
.
[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Message Syntax and Routing",
RFC 7230, DOI 10.17487/RFC7230, June 2014,
.
[RFC7240] Snell, J., "Prefer Header for HTTP", RFC 7240,
DOI 10.17487/RFC7240, June 2014,
.
[RFC7265] Kewisch, P., Daboo, C., and M. Douglass, "jCal: The JSON
Format for iCalendar", RFC 7265, DOI 10.17487/RFC7265, May
2014, .
Authors' Addresses
Cyrus Daboo
Apple Inc.
1 Infinite Loop
Cupertino, CA 95014
USA
Email: cyrus@daboo.name
URI: http://www.apple.com/
Daboo & Murchison Expires August 16, 2017 [Page 11]
Internet-Draft CalDAV Enhanced Synchronization February 2017
Kenneth Murchison
Carnegie Mellon University
5000 Forbes Avenue
Pittsburgh, PA 15213
USA
Email: murch@andrew.cmu.edu
Daboo & Murchison Expires August 16, 2017 [Page 12]