This repository has been archived by the owner on Feb 13, 2020. It is now read-only.
/
caldav-ctag.txt
280 lines (185 loc) · 10.3 KB
/
caldav-ctag.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
C. Daboo
Apple
May 27, 2015
Calendar Collection Entity Tag (CTag) in CalDAV
caldav-ctag-03
Abstract
IMPORTANT: The feature defined by this specification is now
deprecated in favor of support for the WebDAV Sync REPORT as defined
by [RFC6578]. Clients MUST NOT rely on this feature to detect
changes to collections, instead they MUST support the WebDAV Sync
REPORT. Servers MUST support the WebDAV Sync REPORT to allow clients
to efficiently synchronize calendar collections. Whilst most modern
clients do support the WebDAV Sync REPORT, servers MAY continue to
support this specification by simply using the DAV:sync-token
property value for the getctag property value, in order to provide
backwards compatibility with old clients.
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 . . . . . . . . . . . . . . . . . . . . . . . . 1
2. Conventions Used in This Document . . . . . . . . . . . . . . 2
3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 2
3.1. Server . . . . . . . . . . . . . . . . . . . . . . . . . 2
3.2. Client . . . . . . . . . . . . . . . . . . . . . . . . . 3
4. New features in CalDAV . . . . . . . . . . . . . . . . . . . 3
4.1. getctag WebDAV Property . . . . . . . . . . . . . . . . . 3
5. Security Considerations . . . . . . . . . . . . . . . . . . . 4
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4
7. Normative References . . . . . . . . . . . . . . . . . . . . 4
Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 5
Appendix B. Change History . . . . . . . . . . . . . . . . . . . 5
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 5
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
Daboo Expires November 28, 2015 [Page 1]
CalDAV CTag May 2015
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 [RFC6638]
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.
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.
Daboo Expires November 28, 2015 [Page 2]
CalDAV CTag May 2015
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 CS:getctag property value should replace the
one currently cached for that calendar or scheduling Inbox or Outbox
collection.
4. New features in CalDAV
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]).
Daboo Expires November 28, 2015 [Page 3]
CalDAV CTag May 2015
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.
6. IANA Considerations
This document does not require any actions on the part of IANA.
7. Normative References
[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.
Daboo Expires November 28, 2015 [Page 4]
CalDAV CTag May 2015
[RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault,
"Calendaring Extensions to WebDAV (CalDAV)", RFC 4791,
March 2007.
[RFC6578] Daboo, C. and A. Quillaud, "Collection Synchronization for
Web Distributed Authoring and Versioning (WebDAV)", RFC
6578, March 2012.
[RFC6638] Daboo, C. and B. Desruisseaux, "Scheduling Extensions to
CalDAV", RFC 6638, June 2012.
Appendix A. Acknowledgments
This specification is the result of discussions between the Apple
calendar server and client teams.
Appendix B. Change History
Changes in -03:
1. Added deprecation warning.
2. Updated references.
Changes in -02:
1. Updated to RFC4791 reference.
2. Added text indicating that ctag applies to schedule Inbox and
Outbox as well.
Changes in -01:
1. Relaxed requirement so that any type of change to a child
resource can trigger a CTag change (similar behavior to ETag).
Author's Address
Cyrus Daboo
Apple Inc.
1 Infinite Loop
Cupertino, CA 95014
USA
Email: cyrus@daboo.name
URI: http://www.apple.com/
Daboo Expires November 28, 2015 [Page 5]