CalDAV in Cosmo

This document describes the implementation of CalDAV (RFC 4791) in Cosmo as of version 0.15.

General Notes

CalDAV access is enabled at all points within a user's home collection (see CosmoWebdav for a definition of home collection). There is no separate collection for calendars. The home collection functions as a CalDAV calendar home collection.

MKCALENDAR may be used to create a calendar collection at any depth within a user's home collection, except that a calendar collection may not be created at any depth within another calendar collection. Only calendar resources (those with media type text/calendar) may be PUT into a calendar collection, although a regular collection may be created with MKCOL inside a calendar collection, and arbitrary resources may be placed into that sub-collection. This gives calendar clients a logical place to store attachments for calendar resources.

There is no restriction against nesting collections and calendar collections to arbitrary depths, but best practice is to keep a simple, shallow hierarchy of collections. This keeps URLs short and readable, and there is no performance penalty for "wide" hierarchies as opposed to "deep" ones.

A Cosmo item is exposed in CalDAV as a calendar object resource. The type of iCalendar component contained within the resource is determined as follows:

1. If the item is stamped as an event, it is exposed as a VEVENT
2. Otherwise the item is exposed as a VTODO

iCalendar components are translated as follows:

1. VEVENT translates to an event-stamped note
2. VTODO translates to note
3. VJOURNAL translates to note

Other calendar resources (for example VFREEBUSY) can be stored in a calendar collection, but they are stored as raw iCalendar files and are not visible in the Cosmo web UI or in Chandler Desktop.

Notes:

• a PUT of a VJOURNAL will result in a VTODO stored on the server.
• the server currently does not support changing a component type once its established. For example, if a resource (1.ics) contains a VEVENT, it must always contain a VEVENT until the resource is removed.

Calendar Collection Properties

C:calendar-description is supported on every calendar collection and is not protected. The calendar description and language can be initialized by the client with MKCALENDAR; if this is not done, then the calendar description defaults to the name of the resource, and no language is stored for the calendar.

C:calendar-timezone is supported on every calendar collection and is not protected. There is no default value for the calendar timezone.

C:supported-calendar-component-set is provided for every calendar collection. For all collections, this property specifies VEVENT, VTODO, VJOURNAL, VFREEBUSY and VAVAILABILITY. This property cannot be initialized with MKCALENDAR.

C:supported-calendar-data is provided for every calendar collection and specifies and specifies that the server only accepts iCalendar 2.0 resources with the text/calendar media type.

C:max-resource-size is provided for every calendar collection and specifies a max size of 10 MB.

C:min-date-time, C:max-date-time, C:max-instances, and C:max-attendees-per-instance are not provided for any calendar collection.

Methods

MKCALENDAR

The server does not guarantee to process the properties listed within the DAV:set in document order. (Bug 10846)

When more than one property cannot be set or removed, the server reports the error message for only one of the failed properties (in the DAV:responsedescription element). All other properties report a 424 Dependency Failed status. (Bug 10847)

When a client attempts to set a protected property, the server does not include the precondition code cannot-modify-protected-property in the response body; the status is 403 and the response description is something like Property {DAV:}displayname is protected. (Bug 10849)

PUT

When a calendar resource is PUT into a calendar collection, the server includes a weak ETag in the response rather than a strong one. This is because the iCalendar object provided in the request may be transformed into a slightly different but semantically equivalent object for storage. When in doubt, a client should GET the resource immediately after the PUT in order to receive the potentially different iCalendar object and the corresponding strong ETag.

Access Control

C:read-free-busy Privilege

The server does not support the setting of privileges through the ACL method (see CosmoWebdavAcl for more details on setting privileges). It does however support a free-busy ticket type which serves the same purpose - allowing access to free-busy information via REPORT while denying access to any other methods. And, as always, a user has complete access to any resource in his home collection.

Principal Properties

C:calendar-home-set is provided on user principal resources and is protected. It specifies the URL of the associated user account's home collection.

Reports

The server does not support the DAV:expand-property report. (Bug 10892)

All CalDAV reports are supported on both regular and calendar collections and on calendar resources. C:free-busy-query and C:calendar-query are not supported on non-calendar resources, but C:calendar-multiget is.

The server does not take VAVAILABILITY components into account when calculating the response to a C:free-busy-query report. (Bug 7952)

The server fully supports non-standard component, property and parameter names in the C:filter report element.

Attachments

A client may choose to place external attachments to a calendar resource into one or more sub-collections of the calendar collection of which the resource is a member. There are no limits on the number of sub-collections that can be created within a calendar collection. The same credentials (Basic or ticket) that are used to access the calendar collection can be used to access the sub-collection and attachment resources.

The server does not keep track of the relationships between calendar resources, sub-collections, and attachment resources. It is the client's responsibility to create, update and delete sub-collections and attachments and to maintain references between calendar resources and attachment resources.

Alarms

The server does not attempt to execute alarms on events or tasks.