forked from friendica/deprecated-addons
337 lines
9.7 KiB
Plaintext
337 lines
9.7 KiB
Plaintext
|
||
|
||
|
||
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]
|
||
|