Peler

: / opt / cpanel-ccs / doc / Extensions /
Filename : caldav-ctag.xml
back
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc SYSTEM 'rfc2629.dtd' [
<!ENTITY rfc2119 PUBLIC '' 'bibxml/reference.RFC.2119.xml'>
<!ENTITY rfc2518 PUBLIC '' 'bibxml/reference.RFC.2518.xml'>
<!ENTITY rfc3744 PUBLIC '' 'bibxml/reference.RFC.3744.xml'>
<!ENTITY rfc4791 PUBLIC '' 'bibxml/reference.RFC.4791.xml'>
<!ENTITY rfc6578 PUBLIC '' 'bibxml/reference.RFC.6578.xml'>
<!ENTITY rfc6638 PUBLIC '' 'bibxml/reference.RFC.6638.xml'>
]> 
<?rfc toc="yes"?>
<?rfc tocdepth="4"?>
<?rfc strict="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<?rfc private="Calendar Server Extension"?>
<rfc ipr="none" docName='caldav-ctag-03'>
    <front>
        <title abbrev="CalDAV CTag">Calendar Collection Entity Tag (CTag) in CalDAV</title> 
        <author initials="C." surname="Daboo" fullname="Cyrus Daboo">
            <organization abbrev="Apple">
                Apple Inc.
            </organization>
            <address>
                <postal>
                    <street>1 Infinite Loop</street>
                    <city>Cupertino</city>
                    <region>CA</region>
                    <code>95014</code> 
                    <country>USA</country>
                </postal>
                <email>cyrus@daboo.name</email>
                <uri>http://www.apple.com/</uri>
            </address>
        </author>
        <date />
        <abstract>
            <t>
              IMPORTANT: The feature defined by this specification is now deprecated in favor of support for the WebDAV Sync REPORT as defined by <xref target="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.
            </t>
            <t>
                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.
            </t>
        </abstract>
    </front>
    <middle>
        <section title='Introduction'>
            <t>
                In <xref target="RFC4791">CalDAV</xref> 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.
            </t>
            <t>
                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.
            </t>
            <t>
                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.
            </t>
            <t>
            	This extension also defines CTag's on <xref target="RFC6638">CalDAV scheduling</xref> Inbox and Outbox collections.
            </t>
        </section>
        <section title='Conventions Used in This Document'>
            <t>
                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 <xref target='RFC2119' />. 
            </t>
            <t>
                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. 
            </t>
            <t>
                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. 
            </t>
        </section>
         
        <section title='Overview' anchor='overview'>
            <section title='Server'>
                <t>
                    For each calendar or scheduling Inbox or Outbox collection on the server, a new CS:getctag WebDAV property is present.
                </t>
                <t>
                    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.
                </t>
                <t>
                    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.
                </t>
            </section>
            <section title='Client'>
                <t>
                    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.
                </t>
                <t>
                    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.
                </t>
                <t>
                    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.
                </t>
                <t>
                    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.
                </t>
            </section>
        </section>

        <section title='New features in CalDAV' anchor='changes'>
            <section title='getctag WebDAV Property'>
                <t>
                    <list style="hanging">
                        <t hangText="Name:">
                            getctag
                        </t>
                        <t hangText="Namespace:">
                            http://calendarserver.org/ns/
                        </t>
                        <t hangText="Purpose:">
                            Specifies a "synchronization" token used to indicate when the contents of a calendar or scheduling Inbox or Outbox collection have changed. 
                        </t>
                        <t hangText="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 <xref target="RFC2518" />). 
                        </t>
                        <t hangText="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.
                        </t>
                        <t hangText="Definition:">
                            <figure>
                                <artwork><![CDATA[
    <!ELEMENT getctag #PCDATA>
                                ]]></artwork>
                            </figure>
                        </t>
                        <t hangText="Example:">
                            <figure>
                                <artwork><![CDATA[
    <T:getctag xmlns:T="http://calendarserver.org/ns/"
    >ABCD-GUID-IN-THIS-COLLECTION-20070228T122324010340</T:getctag>
                                ]]></artwork>
                            </figure>
                        </t>
                    </list>
                </t>
            </section>
        </section>

        <section title='Security Considerations'>
            <t>
                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 <xref target='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.
            </t>
        </section>
        <section title='IANA Considerations'>
            <t>
                This document does not require any actions on the part of IANA.
            </t>
        </section>
    </middle>
    <back>
        <references title='Normative References'>
            &rfc2119;
            &rfc2518;
            &rfc3744;
            &rfc4791;
            &rfc6578;
            &rfc6638;
        </references>
<!--
<references title='Informative References'>
</references>
-->
        <section title='Acknowledgments'>
            <t>
                This specification is the result of discussions between the Apple calendar server and client teams.
            </t>
        </section>
        <section title='Change History'>
            <t>Changes in -03:
                <list style='numbers'>
                    <t>Added deprecation warning.</t>
                    <t>Updated references.</t>
                </list>
            </t>
            <t>Changes in -02:
                <list style='numbers'>
                    <t>Updated to RFC4791 reference.</t>
                    <t>Added text indicating that ctag applies to schedule Inbox and Outbox as well.</t>
                </list>
            </t>
            <t>Changes in -01:
                <list style='numbers'>
                    <t>Relaxed requirement so that any type of change to a child resource can trigger a CTag change (similar behavior to ETag).</t>
                </list>
            </t>
        </section>
    </back>
</rfc>