Calendar subscription upgradesmdouglass@bedework.com
Internet
This specification updates RFC5545 to add the value DELETED to the
STATUS property.This specification also updates RFC7240 to add the subscribe-
enhanced-get and limit preferences.AcknowledgementsThe author would also like to thank the members of the CalConnect
Calendar Sharing technical committee and the following individuals
for contributing their ideas and support:Marten Gajda, Ken Murchison, Garry ShutlerThe authors would also like to thank CalConnect, the Calendaring and
Scheduling Consortium, for advice with this specification.IntroductionCurrently clients subscribe to calendar feeds as an iCalendar file which is
often published as a resource accessible using the unofficial
'webcal' scheme.The only available option for updating that resource is the usual
HTTP polling of cached resources using Etags or Last-Modified.There is the usual tension between clients wishing to see a timely
response to changes and servers not wishing to be overloaded by
frequent requests for possibly large amounts of data.This specification introduces an approach whereby clients can
discover a more performant access method. Given the location of the
resource as an iCalendar file, the client can perfom a HEAD request on the
resource and inspect the returned headers which will offer a number
of alternative access methods.Given that many clients and servers already support CalDAV this provides an easy
upgrade path for those clients. Additionally an enhanced GET protocol is specified
here to allow a light weight implementation.The use of subscription upgrade may help reduce load on servers, but perhaps
more importantly it allows mobile devices to use a more efficient update
mechanism reducing data transferred and presumably improving battery life.Terms and DefinitionsThe key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
"SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",
"NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
interpreted as described in BCP 14 when, and
only when, they appear in all capitals, as shown here.Additionally, the rule for URI is included from .Discovering alternative access methodsThe advertising of other access points is achieved through the use of
the LINK header as defined in . New link relation types are
defined in this specification - each being associated with a protocol
or protocol subset.These LINK headers will be delivered when a client carries out a HEAD
request targeting the URL of the resource.EXAMPLEThis is an example of a HEAD request and the response from a server
that supports the enhanced GET method.> Request <<
HEAD /caldata/events.ics HTTP/1.1
Host: example.com
Accept: text/calendar
>> Response <<
HTTP/1.1 200 OK
Content-Length: xxxx
Link: ;
rel="subscribe-enhanced-get"]]>Note that the target for an upgraded service may be the same as
for the initial resource.Enhanced GETGeneralThis is a lightweight protocol which allows simple clients to
efficiently discover and download changes in the targeted resource.It has many similarities to WebDAV sync and for a server could be
implemented as an extension of the specification.In this protocol the client MUST include the Prefer header field
preference "subscribe-enhanced-get". If a sync token is available it
is passed as a Sync-Token header field.The resource is treated as a set of individual events each of which
may be updated or deleted separately. The client will first fetch
the entire iCalendar file. On subsequent requests it uses the Prefer
header field and a Sync-Token header field to indicate that it wants a set
of changes since the last fetch.If no Sync-Token header field is supplied the server SHOULD
respond with a full set of data. Otherwise, if the token is valid, it SHOULD return with a set of changed entities.In both cases the server should set the Preference-Applied header field and a new Sync-Token header field value.DeletionsWhen an entity (VEVENT, VTODO or other valid top-level component) is
deleted from the source data the server needs to be able to inform a
client of the deletion. This specification introduces a new value
for the STATUS property of DELETED.On the first enhanced GET after the entity has been deleted a
skeleton, but valid, entity will be returned with STATUS: DELETED.
The receiving client is free to remove the entity or update its
STATUS property.On subsequent fetches the entity will not be returned.Handling of invalid sync tokensWhen a server receives an invalid token it MUST return a 409 status (Conflict). The server MAY choose to return an error
message in the body.The client SHOULD respond to this error by restarting the interaction
from scratch, i.e. retrieve the full set of data then poll for
updates.Paging the responseA client may explicitly request a limit on the size of the response
by specifying the Prefer header field preference "limit=n" where n is
the number of components.When a server receives a request specifying such a limit it SHOULD
limit the response to that number of components. If the limit causes
a truncation in the response the server should respond with a
Preference-Applied header specifying the limit that was applied
and return a sync token which may be used to retrieve the next batch of data.This allows the client to immediately resubmit a
request for the next batch using the updated token.A server MAY choose to limit the response size. The behavior SHOULD
be as if the client had provided a preference for that size -
allowing the client to retrieve the full set of data in batches.Caching of responsesTo enable proper caching of responses the server SHOULD provide a
VARY header field in responses that names the Prefer and Sync-Token header fields
along with any other that are appropriate.Clients should order the preferences as following so that
identical responses can be identified:
subscribe-enhanced-get
limit
ExamplesEXAMPLE 1This is an example of the initial request and response from a server
that supports the enhanced GET method. Note the use of the Vary header so a caching proxy can key off the client's Sync-Token and preference.> Request <<
GET /events.ics HTTP/1.1
Host: example.com
Accept: text/calendar
Prefer: subscribe-enhanced-get
>> Response <<
HTTP/1.1 200 OK
Content-Length: xxxx
Sync-Token: "data:,1234567"
Preference-Applied: subscribe-enhanced-get
Vary: Prefer, Sync-Token
BEGIN:VCALENDAR:
? /* full feed */
END:VCALENDAR]]>EXAMPLE 2This is an example of the subsequent request and response when no
changes have occurred.> Request <<
GET /events.ics HTTP/1.1
Host: example.com
Accept: text/calendar
Prefer: subscribe-enhanced-get
Sync-Token: "data:,1234567"
>> Response <<
HTTP/1.1 304 Not Modified
Content-Length: 0
Sync-Token: "data:,1234567"
Preference-Applied: subscribe-enhanced-get
Vary: Prefer, Sync-Token]]>EXAMPLE 3This is an example of the subsequent request and response for
an old or invalid token.> Request <<
GET /events.ics HTTP/1.1
Host: example.com
Accept: text/calendar
Sync-Token: "data:,1234567"
Prefer: subscribe-enhanced-get
>> Response <<
HTTP/1.1 409 Conflict
Content-Length: xxxx
Preference-Applied: subscribe-enhanced-get]]>EXAMPLE 4This is an example of the subsequent request and response when
changes have occurred.> Request <<
GET /events.ics HTTP/1.1
Host: example.com
Accept: text/calendar
Sync-Token: "data:,1234567"
Prefer: subscribe-enhanced-get
>> Response <<
HTTP/1.1 200 OK
Content-Type: text/calendar
Vary: Prefer, Sync-Token
Sync-Token: "data:,4567890"
Preference-Applied: subscribe-enhanced-get
BEGIN:VCALENDAR:
... only new/changed events
... deleted events have STATUS:DELETED
END:VCALENDAR]]>Changes to the iCalendar specificationsThis specification updates to add the value DELETED to the
STATUS property.Redefined Status property
Property name
STATUS
Purpose
This property defines the overall status or confirmation
for the calendar component.
Value Type
TEXT
Property Parameters
IANA and non-standard property parameters can
be specified on this property.
Conformance
This property can be specified once in "VEVENT",
"VTODO", or "VJOURNAL" calendar components.
Description
In a group-scheduled calendar component, the property
is used by the "Organizer" to provide a confirmation of the event
to the "Attendees". For example in a "VEVENT" calendar component,
the "Organizer" can indicate that a meeting is tentative,
confirmed, or cancelled. In a "VTODO" calendar component, the
"Organizer" can indicate that an action item needs action, is
completed, is in process or being worked on, or has been
cancelled. In a "VJOURNAL" calendar component, the "Organizer"
can indicate that a journal entry is draft, final, or has been
cancelled or removed.
Format Definition
This property is defined by the following notation:
Example
EXAMPLE 1The following is an example of this property for a "VEVENT"
calendar component:EXAMPLE 2The following is an example of this property for a "VTODO" calendar
component:EXAMPLE 3The following is an example of this property for a "VJOURNAL"
calendar component:Header Field: Sync-TokenThis specification defines a new header field Sync-Token for use by
the enhanced GET method.The value MUST be a URI. This will generally be a data URI
representing an opaque token. Client MUST not attempt to interpret
the data URI value.EXAMPLEThis is an example of the Sync-Token header field:New Prefer header field preferencesPreference subscribe-enhanced-getThis indicates that the client expects the server to handle the GET
method according to the specifications for enhanced get.Preference limitThis preference parameter provides a limit on the number of components returned for enhanced get.Link relationsGeneralThis clause defines a number of new link relations required to
facilitate subscription upgrades.subscribe-caldavThis specifies an access point which is a full implementation of
caldav but requires no authentication. The end point allows the full
range of reports as defined by the CalDAV specification.The client MUST follow the specification to determine exactly what
operations are allowed on the access point - for example to determine
if DAV:sync-collection is supported.The URL MAY include some form of token to allow write access to the
targeted collection. The client must check its permissions to
determine whether or not it has been granted write access.subscribe-caldav-authThis specifies an access point which is a full implementation of
caldav and requires authentication. This may allow read-write access
to the resource.The client MUST follow the specification to determine exactly what
operations are allowed on the access point - for example to determine
if DAV:sync-collection is supported.subscribe-webdav-syncThis specifies an access point which supports only webdav sync.This allows the client to issue a DAV:sync-collection report on the resource to
obtain updates.The client MUST follow that specification.subscribe-enhanced-getThis specifies an access point which supports something new.The client MUST follow that specification.Security ConsiderationsApplications using these properties need to be aware of the risks
entailed in using the URIs provided as values. See for a
discussion of the security considerations relating to URIs.
== Privacy ConsiderationsProperties with a "URI" value type can expose their users to privacy
leaks as any network access of the URI data can be tracked. Clients
SHOULD NOT automatically download data referenced by the URI without
explicit instruction from users. This specification does not
introduce any additional privacy concerns beyond those described in
.IANA ConsiderationsSync-Token HTTP Header Field RegistrationThis specification updates the "Message Headers" registry entry for "Sync-Token" in to refer to this document.Preference RegistrationsThe following preferences have been added to the HTTP Preferences
Registry defined in
Preference
subscribe-enhanced-get
Value
None.
Description
Marks the interaction as enhanced get and provides the
optional sync-token and page size.
Reference
this document
Preference
limit
Value
An integer page size.
Description
Provide a limit on the number of components in the response.
Reference
this document
Link Relation RegistrationsThis document defines the following new iCalendar properties to be
added to the registry defined in :
Relation Name
Description
Reference
subscribe-caldav
Current
subscribe-caldav_auth
Current
subscribe-webdav-sync
Current
subscribe-enhanced_get
Current
Normative ReferencesKey words for use in RFCs to Indicate Requirement LevelsIn many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.RFC 2119Registration Procedures for Message Header FieldsThis specification defines registration procedures for the message header fields used by Internet mail, HTTP, Netnews and other applications. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.RFC 3864Uniform Resource Identifier (URI): Generic SyntaxA Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. [STANDARDS-TRACK]RFC 3986Internet Calendaring and Scheduling Core Object Specification (iCalendar)This document defines the iCalendar data format for representing and exchanging calendaring and scheduling information such as events, to-dos, journal entries, and free/busy information, independent of any particular calendar service or protocol. [STANDARDS-TRACK]RFC 5545Web LinkingThis document specifies relation types for Web links, and defines a registry for them. It also defines the use of such links in HTTP headers with the Link header field. [STANDARDS-TRACK]RFC 5988Prefer Header for HTTPThis specification defines an HTTP header field that can be used by a client to request that certain behaviors be employed by a server while processing a request.RFC 7240Ambiguity of Uppercase vs Lowercase in RFC 2119 Key WordsRFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings.RFC 8174Open issues
Vary
Ensure we get that right.
Change logcalext00 2019-06-05 MD
First calext version
Use Sync-Token header rather than parameter
v04 2019-03-07 MD
Reference to RFC 6538 - WebDAV sync and RFC 7240 Prefer