Internet DRAFT - draft-ietf-calext-subscription-upgrade
draft-ietf-calext-subscription-upgrade
Network Working Group M. Douglass
Internet-Draft 15 February 2024
Updates: 5545 (if approved)
Intended status: Standards Track
Expires: 18 August 2024
Calendar subscription upgrades
draft-ietf-calext-subscription-upgrade-09
Abstract
This specification updates RFC5545 to add the value DELETED to the
STATUS property.
This specification also adds values to the Preferences Registry
defined in RFC7240 to add the subscribe-enhanced-get and limit
preferences and to the link relations directory defined in RFC8288.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 18 August 2024.
Copyright Notice
Copyright (c) 2024 IETF Trust and the persons identified as the
document authors. All rights reserved.
Douglass Expires 18 August 2024 [Page 1]
Internet-Draft Calendar subscription upgrades February 2024
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components
extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Table of Contents
1. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 3
2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2.1. Terms and Definitions . . . . . . . . . . . . . . . . . . 3
3. Discovering alternative access methods . . . . . . . . . . . 4
4. Enhanced GET . . . . . . . . . . . . . . . . . . . . . . . . 4
4.1. General . . . . . . . . . . . . . . . . . . . . . . . . . 4
4.2. Deletions . . . . . . . . . . . . . . . . . . . . . . . . 5
4.3. Paging the response . . . . . . . . . . . . . . . . . . . 5
4.4. Caching of responses . . . . . . . . . . . . . . . . . . 6
4.5. Examples . . . . . . . . . . . . . . . . . . . . . . . . 6
5. Changes to the iCalendar specifications . . . . . . . . . . . 8
5.1. Redefined Status property . . . . . . . . . . . . . . . . 9
6. Header Field: Sync-Token . . . . . . . . . . . . . . . . . . 11
7. New Prefer header field preferences . . . . . . . . . . . . . 11
7.1. Preference subscribe-enhanced-get . . . . . . . . . . . . 11
7.2. Preference limit . . . . . . . . . . . . . . . . . . . . 11
8. Link relations . . . . . . . . . . . . . . . . . . . . . . . 11
8.1. General . . . . . . . . . . . . . . . . . . . . . . . . . 11
8.2. subscribe-caldav . . . . . . . . . . . . . . . . . . . . 11
8.3. subscribe-caldav-auth . . . . . . . . . . . . . . . . . . 12
8.4. subscribe-webdav-sync . . . . . . . . . . . . . . . . . . 12
8.5. subscribe-enhanced-get . . . . . . . . . . . . . . . . . 12
9. Security Considerations . . . . . . . . . . . . . . . . . . . 12
10. Privacy Considerations . . . . . . . . . . . . . . . . . . . 12
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13
11.1. Sync-Token HTTP Header Field Registration . . . . . . . 13
11.2. Preference Registrations . . . . . . . . . . . . . . . . 13
11.3. Link Relation Registrations . . . . . . . . . . . . . . 13
12. Normative References . . . . . . . . . . . . . . . . . . . . 14
Appendix A. Open issues . . . . . . . . . . . . . . . . . . . . 15
Appendix B. Change log . . . . . . . . . . . . . . . . . . . . . 15
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 15
Douglass Expires 18 August 2024 [Page 2]
Internet-Draft Calendar subscription upgrades February 2024
1. Acknowledgements
The 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 Shutler
The authors would also like to thank CalConnect, the Calendaring and
Scheduling Consortium, for advice with this specification.
2. Introduction
Currently, 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 perform 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 lightweight
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.
2.1. Terms and Definitions
The 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 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
Douglass Expires 18 August 2024 [Page 3]
Internet-Draft Calendar subscription upgrades February 2024
Additionally, the rule for URI is included from [RFC3986].
3. Discovering alternative access methods
The advertising of other access points is achieved through the use of
the LINK header as defined in [RFC8288]. 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.
EXAMPLE
This 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: <https://example.com/subscribe/events.ics>;
rel="subscribe-enhanced-get"
Note that the target for an upgraded service may be the same as for
the initial resource.
4. Enhanced GET
4.1. General
This 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.
Douglass Expires 18 August 2024 [Page 4]
Internet-Draft Calendar subscription upgrades February 2024
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 or thetoken is invalid the
server MUST respond with a full set of data and SHOULD set the
Preference-Applied header field and a new Sync-Token header field
value.
Otherwise, (the token is valid), it SHOULD return with a set of
changed entities and MUST set the Preference-Applied header field and
a new Sync-Token header field value.
When 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 MUST respond to this error by restarting the interaction
from scratch, i.e. retrieve the full set of data then poll for
updates.
4.2. Deletions
When 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.
4.3. Paging the response
A 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.
Douglass Expires 18 August 2024 [Page 5]
Internet-Draft Calendar subscription upgrades February 2024
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 MUST be
as if the client had provided a preference for that size - allowing
the client to retrieve the full set of data in batches.
4.4. Caching of responses
To 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
4.5. Examples
EXAMPLE 1
This 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.
Douglass Expires 18 August 2024 [Page 6]
Internet-Draft Calendar subscription upgrades February 2024
>> 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 2
This 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 3
This is an example of the subsequent request and response for an old
or invalid token.
Douglass Expires 18 August 2024 [Page 7]
Internet-Draft Calendar subscription upgrades February 2024
>> 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 4
This 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
5. Changes to the iCalendar specifications
This specification updates [RFC5545] to add the value DELETED to the
STATUS property.
Douglass Expires 18 August 2024 [Page 8]
Internet-Draft Calendar subscription upgrades February 2024
5.1. 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:
Douglass Expires 18 August 2024 [Page 9]
Internet-Draft Calendar subscription upgrades February 2024
status = "STATUS" statparam ":" statvalue CRLF
statparam = *(";" other-param)
statvalue = (statvalue-event
/ statvalue-todo
/ statvalue-jour)
statvalue-event = "TENTATIVE" ;Indicates event is tentative.
/ "CONFIRMED" ;Indicates event is definite.
/ "CANCELLED" ;Indicates event was cancelled.
/ "DELETED" ;Indicates event was deleted.
;Status values for a "VEVENT"
statvalue-todo = "NEEDS-ACTION" ;Indicates to-do needs action.
/ "COMPLETED" ;Indicates to-do completed.
/ "IN-PROCESS" ;Indicates to-do in process of.
/ "CANCELLED" ;Indicates to-do was cancelled.
/ "DELETED" ;Indicates to-do was deleted.
;Status values for "VTODO".
statvalue-jour = "DRAFT" ;Indicates journal is draft.
/ "FINAL" ;Indicates journal is final.
/ "CANCELLED" ;Indicates journal is removed.
/ "DELETED" ;Indicates journal was deleted.
;Status values for "VJOURNAL".
Example
EXAMPLE 1
The following is an example of this property for a "VEVENT" calendar
component:
STATUS:TENTATIVE
EXAMPLE 2
The following is an example of this property for a "VTODO" calendar
component:
STATUS:NEEDS-ACTION
EXAMPLE 3
The following is an example of this property for a "VJOURNAL"
calendar component:
Douglass Expires 18 August 2024 [Page 10]
Internet-Draft Calendar subscription upgrades February 2024
STATUS:DRAFT
6. Header Field: Sync-Token
This specification defines a new header field Sync-Token for use by
the enhanced GET method.
Sync-Token = DQUOTE URI DQUOTE
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.
EXAMPLE
This is an example of the Sync-Token header field:
Sync-Token: "data:,1234567"
7. New Prefer header field preferences
7.1. Preference subscribe-enhanced-get
This indicates that the client expects the server to handle the GET
method according to the specifications for enhanced get.
pref-subscribe-enhanced-get = "subscribe-enhanced-get"
7.2. Preference limit
This preference parameter provides a limit on the number of
components returned for enhanced get.
pref-limit = "limit" BWS "=" BWS 1*DIGIT
8. Link relations
8.1. General
This clause defines a number of new link relations required to
facilitate subscription upgrades.
8.2. subscribe-caldav
This 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.
Douglass Expires 18 August 2024 [Page 11]
Internet-Draft Calendar subscription upgrades February 2024
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 it has been granted write access.
8.3. subscribe-caldav-auth
This 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.
8.4. subscribe-webdav-sync
This 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.
8.5. subscribe-enhanced-get
This specifies an access point which supports something new.
The client MUST follow that specification.
9. Security Considerations
Applications using these properties need to be aware of the risks
entailed in using the URIs provided as values. See [RFC3986] for a
discussion of the security considerations relating to URIs.
10. Privacy Considerations
Properties 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
[RFC5545].
Douglass Expires 18 August 2024 [Page 12]
Internet-Draft Calendar subscription upgrades February 2024
11. IANA Considerations
11.1. Sync-Token HTTP Header Field Registration
This specification updates the "Message Headers" registry entry for
"Sync-Token" in [RFC3864] to refer to this document.
Header Field Name: Sync-Token
Protocol: http
Status: standard
Reference: <this-document>
Figure 1
11.2. Preference Registrations
The following preferences have been added to the HTTP Preferences
Registry defined in [RFC7240]
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
11.3. Link Relation Registrations
The following link relation values have been added to the Reference
Types Registry defined in Section 6.2.2 of [RFC8288]:
Douglass Expires 18 August 2024 [Page 13]
Internet-Draft Calendar subscription upgrades February 2024
+========================+=============+=============+
| Relation Name | Description | Reference |
+========================+=============+=============+
| subscribe-caldav | Current | Section 8.2 |
+------------------------+-------------+-------------+
| subscribe-caldav_auth | Current | Section 8.3 |
+------------------------+-------------+-------------+
| subscribe-webdav-sync | Current | Section 8.4 |
+------------------------+-------------+-------------+
| subscribe-enhanced_get | Current | Section 8.5 |
+------------------------+-------------+-------------+
Table 1
12. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", RFC 2119, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration
Procedures for Message Header Fields", RFC 3864, RFC 3864,
DOI 10.17487/RFC3864, September 2004,
<https://www.rfc-editor.org/info/rfc3864>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", RFC 3986,
RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/info/rfc3986>.
[RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and
Scheduling Core Object Specification (iCalendar)", RFC
5545, RFC 5545, DOI 10.17487/RFC5545, September 2009,
<https://www.rfc-editor.org/info/rfc5545>.
[RFC7240] Snell, J., "Prefer Header for HTTP", RFC 7240, RFC 7240,
DOI 10.17487/RFC7240, June 2014,
<https://www.rfc-editor.org/info/rfc7240>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", RFC 8174, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8288] Nottingham, M., "Web Linking", RFC 8288, RFC 8288,
DOI 10.17487/RFC8288, October 2017,
<https://www.rfc-editor.org/info/rfc8288>.
Douglass Expires 18 August 2024 [Page 14]
Internet-Draft Calendar subscription upgrades February 2024
Appendix A. Open issues
Vary Ensure we get that right.
Appendix B. Change log
calext00 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
* Go back to HEAD
* New Preference and parameters.
* Examples
* More text for extended get. Talk about deletions.
v01 2017-02-17 MD
* Add text about OPTIONS
* Add text abut read/write CalDAV
v00 2017-02-15 MD
* First pass
Author's Address
Michael Douglass
Email: mdouglass@bedework.com
Douglass Expires 18 August 2024 [Page 15]
