Calendar Server Extension C. Daboo Apple May 3, 2007 Calendar Collection Entity Tag (CTag) in CalDAV caldav-ctag-02 Abstract This specification defines an extension to CalDAV that provides a fast way for a client to determine whether the contents of a calendar collection may have changed. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Conventions Used in This Document . . . . . . . . . . . . . . . 2 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3.1. Server . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3.2. Client . . . . . . . . . . . . . . . . . . . . . . . . . . 3 4. New features in CalDAV . . . . . . . . . . . . . . . . . . . . 3 4.1. getctag WebDAV Property . . . . . . . . . . . . . . . . . . 4 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 4 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 5 7. Normative References . . . . . . . . . . . . . . . . . . . . . 5 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 5 Appendix B. Change History . . . . . . . . . . . . . . . . . . . . 5 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 6 Daboo [Page 1] CalDAV Proxy May 2007 1. Introduction In CalDAV [RFC4791] calendar data is stored in calendar collection resources. Clients need to "poll" calendar collections in order to find out what has changed since the last time they examined it. Currently that involves having to do a PROPFIND Depth:1 HTTP request, or a CALDAV:calendar-query REPORT request. When a calendar collection contains a large number of calendar resources those operations become expensive on the server. Calendar users often configure their clients to poll at short time intervals. So polling traffic to the server will be high, even though the frequency at which changes actually occur to a calendar is typically low. To improve on performance, this specification defines a new "calendar collection entity tag" (CTag) WebDAV property that is defined on calendar collections. When the calendar collection changes, the CTag value changes. Thus a client can cache the CTag at some point in time, then poll the collection only (i.e. PROPFIND Depth:0 HTTP requests) and determine if a change has happened based on the returned CTag value. If there is a change, it can then fall back to doing the full (Depth:1) poll of the collection to actually determine which resources in the collection changed. This extension also defines CTag's on CalDAV scheduling [I-D.desruisseaux-caldav-sched] Inbox and Outbox collections. 2. Conventions Used in This Document The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. When XML element types in the namespaces "DAV:" and "urn:ietf:params:xml:ns:caldav" are referenced in this document outside of the context of an XML fragment, the string "DAV:" and "CALDAV:" will be prefixed to the element type names respectively. The namespace "http://calendarserver.org/ns/" is used for XML elements defined in this specification. When XML element types in this namespace are referenced in this document outside of the context of an XML fragment, the string "CS:" will be prefixed to the element type names respectively. Daboo [Page 2] CalDAV Proxy May 2007 3. Overview 3.1. Server For each calendar or scheduling Inbox or Outbox collection on the server, a new CS:getctag WebDAV property is present. The property value is an "opaque" token whose value is guaranteed to be unique over the lifetime of any calendar or scheduling Inbox or Outbox collection at a specific URI. Whenever a calendar resource is added to, modified or deleted from the calendar collection, the value of the CS:getctag property MUST change. Typically this change will occur when the DAV:getetag property on a child resource changes due to some protocol action. It could be the result of a change to the body or properties of the resource. 3.2. Client The client starts off with an empty string as the initial value for the cached CTag of a calendar or scheduling Inbox or Outbox collection that it intends to synchronize with. When polling a calendar or scheduling Inbox or Outbox collection, the client issues a PROPFIND Depth:0 HTTP request, asking for the CS: getctag property to be returned. If the returned value of CS:getctag property matches the one currently cached for the calendar or scheduling Inbox or Outbox collection, then the collection contents have not changed and no further action is required until the next poll. If the returned value of CS:getctag property does not match the one found previously, then the contents of the calendar or scheduling Inbox or Outbox collection have changed. At that point the client should re-issue the PROPFIND Depth:1 request to get the collection changes in detail and the CS:getctag property value corresponding to the new state. The new CSgetctag property value should replace the one currently cached for that calendar or scheduling Inbox or Outbox collection. 4. New features in CalDAV Daboo [Page 3] CalDAV Proxy May 2007 4.1. getctag WebDAV Property Name: getctag Namespace: http://calendarserver.org/ns/ Purpose: Specifies a "synchronization" token used to indicate when the contents of a calendar or scheduling Inbox or Outbox collection have changed. Conformance: This property MUST be defined on a calendar or scheduling Inbox or Outbox collection resource. It MUST be protected and SHOULD be returned by a PROPFIND DAV:allprop request (as defined in Section 12.14.1 of [RFC2518]). Description: The CS:getctag property allows clients to quickly determine if the contents of a calendar or scheduling Inbox or Outbox collection have changed since the last time a "synchronization" operation was done. The CS:getctag property value MUST change each time the contents of the calendar or scheduling Inbox or Outbox collection change, and each change MUST result in a value that is different from any other used with that collection URI. Definition: Example: ABCD-GUID-IN-THIS-COLLECTION-20070228T122324010340 5. Security Considerations The CS:getctag property value changes whenever any resource in the collection or scheduling Inbox or Outbox changes. Thus a change to a resource that a user does not have read access to will result in a change in the CTag and the user will know that a change occurred. However, that user will not able to get additional details about exactly what changed as WebDAV ACLs [RFC3744] will prevent that. So this does expose the fact that there are potentially "hidden" resources in a calendar collection, but it does not expose any details about them. Daboo [Page 4] CalDAV Proxy May 2007 6. IANA Considerations This document does not require any actions on the part of IANA. 7. Normative References [I-D.desruisseaux-caldav-sched] Desruisseaux, B., "Scheduling Extensions to CalDAV", draft-desruisseaux-caldav-sched-03 (work in progress), January 2007. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D. Jensen, "HTTP Extensions for Distributed Authoring -- WEBDAV", RFC 2518, February 1999. [RFC3744] Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, "Web Distributed Authoring and Versioning (WebDAV) Access Control Protocol", RFC 3744, May 2004. [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, March 2007. Appendix A. Acknowledgments This specification is the result of discussions between the Apple calendar server and client teams. Appendix B. Change History Changes from -01: 1. Updated to RFC4791 reference. 2. Added text indicating that ctag applies to schedule Inbox and Outbox as well. Changes from -00: 1. Relaxed requirement so that any type of change to a child resource can trigger a CTag change (similar behavior to ETag). Daboo [Page 5] CalDAV Proxy May 2007 Author's Address Cyrus Daboo Apple Inc. 1 Infinite Loop Cupertino, CA 95014 USA Email: cyrus@daboo.name URI: http://www.apple.com/ Daboo [Page 6]