dav/SabreDAV/docs/caldav-ctag.txt

   1
   2
   3
   4 Calendar Server Extension                                       C. Daboo
   5                                                                    Apple
   6                                                              May 3, 2007
   7
   8
   9             Calendar Collection Entity Tag (CTag) in CalDAV
  10                              caldav-ctag-02
  11
  12 Abstract
  13
  14    This specification defines an extension to CalDAV that provides a
  15    fast way for a client to determine whether the contents of a calendar
  16    collection may have changed.
  17
  18
  19 Table of Contents
  20
  21    1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . . . 2
  22    2.  Conventions Used in This Document . . . . . . . . . . . . . . . 2
  23    3.  Overview  . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
  24      3.1.  Server  . . . . . . . . . . . . . . . . . . . . . . . . . . 3
  25      3.2.  Client  . . . . . . . . . . . . . . . . . . . . . . . . . . 3
  26    4.  New features in CalDAV  . . . . . . . . . . . . . . . . . . . . 3
  27      4.1.  getctag WebDAV Property . . . . . . . . . . . . . . . . . . 4
  28    5.  Security Considerations . . . . . . . . . . . . . . . . . . . . 4
  29    6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 5
  30    7.  Normative References  . . . . . . . . . . . . . . . . . . . . . 5
  31    Appendix A.  Acknowledgments  . . . . . . . . . . . . . . . . . . . 5
  32    Appendix B.  Change History . . . . . . . . . . . . . . . . . . . . 5
  33    Author's Address  . . . . . . . . . . . . . . . . . . . . . . . . . 6
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  44
  45
  46
  47
  48
  49
  50
  51
  52
  53
  54
  55 Daboo                                                           [Page 1]
  56 \f
  57                               CalDAV Proxy                      May 2007
  58
  59
  60 1.  Introduction
  61
  62    In CalDAV [RFC4791] calendar data is stored in calendar collection
  63    resources.  Clients need to "poll" calendar collections in order to
  64    find out what has changed since the last time they examined it.
  65    Currently that involves having to do a PROPFIND Depth:1 HTTP request,
  66    or a CALDAV:calendar-query REPORT request.  When a calendar
  67    collection contains a large number of calendar resources those
  68    operations become expensive on the server.
  69
  70    Calendar users often configure their clients to poll at short time
  71    intervals.  So polling traffic to the server will be high, even
  72    though the frequency at which changes actually occur to a calendar is
  73    typically low.
  74
  75    To improve on performance, this specification defines a new "calendar
  76    collection entity tag" (CTag) WebDAV property that is defined on
  77    calendar collections.  When the calendar collection changes, the CTag
  78    value changes.  Thus a client can cache the CTag at some point in
  79    time, then poll the collection only (i.e.  PROPFIND Depth:0 HTTP
  80    requests) and determine if a change has happened based on the
  81    returned CTag value.  If there is a change, it can then fall back to
  82    doing the full (Depth:1) poll of the collection to actually determine
  83    which resources in the collection changed.
  84
  85    This extension also defines CTag's on CalDAV scheduling
  86    [I-D.desruisseaux-caldav-sched] Inbox and Outbox collections.
  87
  88
  89 2.  Conventions Used in This Document
  90
  91    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
  92    "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
  93    document are to be interpreted as described in [RFC2119].
  94
  95    When XML element types in the namespaces "DAV:" and
  96    "urn:ietf:params:xml:ns:caldav" are referenced in this document
  97    outside of the context of an XML fragment, the string "DAV:" and
  98    "CALDAV:" will be prefixed to the element type names respectively.
  99
 100    The namespace "http://calendarserver.org/ns/" is used for XML
 101    elements defined in this specification.  When XML element types in
 102    this namespace are referenced in this document outside of the context
 103    of an XML fragment, the string "CS:" will be prefixed to the element
 104    type names respectively.
 105
 106
 107
 108
 109
 110
 111 Daboo                                                           [Page 2]
 112 \f
 113                               CalDAV Proxy                      May 2007
 114
 115
 116 3.  Overview
 117
 118 3.1.  Server
 119
 120    For each calendar or scheduling Inbox or Outbox collection on the
 121    server, a new CS:getctag WebDAV property is present.
 122
 123    The property value is an "opaque" token whose value is guaranteed to
 124    be unique over the lifetime of any calendar or scheduling Inbox or
 125    Outbox collection at a specific URI.
 126
 127    Whenever a calendar resource is added to, modified or deleted from
 128    the calendar collection, the value of the CS:getctag property MUST
 129    change.  Typically this change will occur when the DAV:getetag
 130    property on a child resource changes due to some protocol action.  It
 131    could be the result of a change to the body or properties of the
 132    resource.
 133
 134 3.2.  Client
 135
 136    The client starts off with an empty string as the initial value for
 137    the cached CTag of a calendar or scheduling Inbox or Outbox
 138    collection that it intends to synchronize with.
 139
 140    When polling a calendar or scheduling Inbox or Outbox collection, the
 141    client issues a PROPFIND Depth:0 HTTP request, asking for the CS:
 142    getctag property to be returned.
 143
 144    If the returned value of CS:getctag property matches the one
 145    currently cached for the calendar or scheduling Inbox or Outbox
 146    collection, then the collection contents have not changed and no
 147    further action is required until the next poll.
 148
 149    If the returned value of CS:getctag property does not match the one
 150    found previously, then the contents of the calendar or scheduling
 151    Inbox or Outbox collection have changed.  At that point the client
 152    should re-issue the PROPFIND Depth:1 request to get the collection
 153    changes in detail and the CS:getctag property value corresponding to
 154    the new state.  The new CSgetctag property value should replace the
 155    one currently cached for that calendar or scheduling Inbox or Outbox
 156    collection.
 157
 158
 159 4.  New features in CalDAV
 160
 161
 162
 163
 164
 165
 166
 167 Daboo                                                           [Page 3]
 168 \f
 169                               CalDAV Proxy                      May 2007
 170
 171
 172 4.1.  getctag WebDAV Property
 173
 174    Name:  getctag
 175
 176    Namespace:  http://calendarserver.org/ns/
 177
 178    Purpose:  Specifies a "synchronization" token used to indicate when
 179       the contents of a calendar or scheduling Inbox or Outbox
 180       collection have changed.
 181
 182    Conformance:  This property MUST be defined on a calendar or
 183       scheduling Inbox or Outbox collection resource.  It MUST be
 184       protected and SHOULD be returned by a PROPFIND DAV:allprop request
 185       (as defined in Section 12.14.1 of [RFC2518]).
 186
 187    Description:  The CS:getctag property allows clients to quickly
 188       determine if the contents of a calendar or scheduling Inbox or
 189       Outbox collection have changed since the last time a
 190       "synchronization" operation was done.  The CS:getctag property
 191       value MUST change each time the contents of the calendar or
 192       scheduling Inbox or Outbox collection change, and each change MUST
 193       result in a value that is different from any other used with that
 194       collection URI.
 195
 196    Definition:
 197
 198        <!ELEMENT getctag #PCDATA>
 199
 200    Example:
 201
 202        <T:getctag xmlns:T="http://calendarserver.org/ns/"
 203        >ABCD-GUID-IN-THIS-COLLECTION-20070228T122324010340</T:getctag>
 204
 205
 206 5.  Security Considerations
 207
 208    The CS:getctag property value changes whenever any resource in the
 209    collection or scheduling Inbox or Outbox changes.  Thus a change to a
 210    resource that a user does not have read access to will result in a
 211    change in the CTag and the user will know that a change occurred.
 212    However, that user will not able to get additional details about
 213    exactly what changed as WebDAV ACLs [RFC3744] will prevent that.  So
 214    this does expose the fact that there are potentially "hidden"
 215    resources in a calendar collection, but it does not expose any
 216    details about them.
 217
 218
 219
 220
 221
 222
 223 Daboo                                                           [Page 4]
 224 \f
 225                               CalDAV Proxy                      May 2007
 226
 227
 228 6.  IANA Considerations
 229
 230    This document does not require any actions on the part of IANA.
 231
 232
 233 7.  Normative References
 234
 235    [I-D.desruisseaux-caldav-sched]
 236               Desruisseaux, B., "Scheduling Extensions to CalDAV",
 237               draft-desruisseaux-caldav-sched-03 (work in progress),
 238               January 2007.
 239
 240    [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
 241               Requirement Levels", BCP 14, RFC 2119, March 1997.
 242
 243    [RFC2518]  Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D.
 244               Jensen, "HTTP Extensions for Distributed Authoring --
 245               WEBDAV", RFC 2518, February 1999.
 246
 247    [RFC3744]  Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, "Web
 248               Distributed Authoring and Versioning (WebDAV) Access
 249               Control Protocol", RFC 3744, May 2004.
 250
 251    [RFC4791]  Daboo, C., Desruisseaux, B., and L. Dusseault,
 252               "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791,
 253               March 2007.
 254
 255
 256 Appendix A.  Acknowledgments
 257
 258    This specification is the result of discussions between the Apple
 259    calendar server and client teams.
 260
 261
 262 Appendix B.  Change History
 263
 264    Changes from -01:
 265
 266    1.  Updated to RFC4791 reference.
 267
 268    2.  Added text indicating that ctag applies to schedule Inbox and
 269        Outbox as well.
 270
 271    Changes from -00:
 272
 273    1.  Relaxed requirement so that any type of change to a child
 274        resource can trigger a CTag change (similar behavior to ETag).
 275
 276
 277
 278
 279 Daboo                                                           [Page 5]
 280 \f
 281                               CalDAV Proxy                      May 2007
 282
 283
 284 Author's Address
 285
 286    Cyrus Daboo
 287    Apple Inc.
 288    1 Infinite Loop
 289    Cupertino, CA  95014
 290    USA
 291
 292    Email: cyrus@daboo.name
 293    URI:   http://www.apple.com/
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335 Daboo                                                           [Page 6]
 336 \f