From b35122f7a6ad42756c35bb60ba1f06c3dcd45c77 Mon Sep 17 00:00:00 2001 From: friendica Date: Mon, 21 Oct 2013 15:46:31 -0700 Subject: add sabre (1.8.x) via composer in the !@#$ place it wants to be --- vendor/sabre/dav/docs/caldav-ctag.txt | 336 ++++++++++++++++++++++++++++++++++ 1 file changed, 336 insertions(+) create mode 100644 vendor/sabre/dav/docs/caldav-ctag.txt (limited to 'vendor/sabre/dav/docs/caldav-ctag.txt') diff --git a/vendor/sabre/dav/docs/caldav-ctag.txt b/vendor/sabre/dav/docs/caldav-ctag.txt new file mode 100644 index 000000000..4787ca260 --- /dev/null +++ b/vendor/sabre/dav/docs/caldav-ctag.txt @@ -0,0 +1,336 @@ + + + +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: + + + + Example: + + ABCD-GUID-IN-THIS-COLLECTION-20070228T122324010340 + + +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] + -- cgit v1.2.3