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]