


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:

       <!ELEMENT getctag #PCDATA>

   Example:

       <T:getctag xmlns:T="http://calendarserver.org/ns/"
       >ABCD-GUID-IN-THIS-COLLECTION-20070228T122324010340</T:getctag>


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]

