mirror of
https://git.friendi.ca/friendica/friendica-addons.git
synced 2024-09-17 20:35:13 +00:00
337 lines
9.7 KiB
Text
337 lines
9.7 KiB
Text
|
|
|||
|
|
|||
|
|
|||
|
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]
|
|||
|
|