idnits 2.17.1 draft-ietf-calext-subscription-upgrade-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([RFC5545], [RFC7240]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. -- The draft header indicates that this document updates RFC5988, but the abstract doesn't seem to mention this, which it should. -- The abstract seems to indicate that this document updates RFC7240, but the header doesn't have an 'Updates:' line to match this. -- The abstract seems to indicate that this document updates RFC5545, but the header doesn't have an 'Updates:' line to match this. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 540 has weird spacing: '...ference subsc...' == Line 547 has weird spacing: '...ference this ...' == Line 549 has weird spacing: '...ference limit...' == Line 556 has weird spacing: '...ference this ...' == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: 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. (Using the creation date from RFC5988, updated by this document, for RFC5378 checks: 2006-06-19) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (26 July 2021) is 1003 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) Summary: 2 errors (**), 0 flaws (~~), 6 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Douglass 3 Internet-Draft 26 July 2021 4 Updates: 5988 (if approved) 5 Intended status: Standards Track 6 Expires: 27 January 2022 8 Calendar subscription upgrades 9 draft-ietf-calext-subscription-upgrade-04 11 Abstract 13 This specification updates [RFC5545] to add the value DELETED to the 14 STATUS property. 16 This specification also updates [RFC7240] to add the subscribe- 17 enhanced-get and limit preferences. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at https://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on 27 January 2022. 36 Copyright Notice 38 Copyright (c) 2021 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 43 license-info) in effect on the date of publication of this document. 44 Please review these documents carefully, as they describe your rights 45 and restrictions with respect to this document. Code Components 46 extracted from this document must include Simplified BSD License text 47 as described in Section 4.e of the Trust Legal Provisions and are 48 provided without warranty as described in the Simplified BSD License. 50 Table of Contents 52 1. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 2 53 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 54 2.1. Terms and Definitions . . . . . . . . . . . . . . . . . . 3 55 3. Discovering alternative access methods . . . . . . . . . . . 3 56 4. Enhanced GET . . . . . . . . . . . . . . . . . . . . . . . . 4 57 4.1. General . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 4.2. Deletions . . . . . . . . . . . . . . . . . . . . . . . . 5 59 4.3. Handling of invalid sync tokens . . . . . . . . . . . . . 5 60 4.4. Paging the response . . . . . . . . . . . . . . . . . . . 5 61 4.5. Caching of responses . . . . . . . . . . . . . . . . . . 6 62 4.6. Examples . . . . . . . . . . . . . . . . . . . . . . . . 6 63 5. Changes to the iCalendar specifications . . . . . . . . . . . 8 64 5.1. Redefined Status property . . . . . . . . . . . . . . . . 8 65 6. Header Field: Sync-Token . . . . . . . . . . . . . . . . . . 10 66 7. New Prefer header field preferences . . . . . . . . . . . . . 10 67 7.1. Preference subscribe-enhanced-get . . . . . . . . . . . . 10 68 7.2. Preference limit . . . . . . . . . . . . . . . . . . . . 10 69 8. Link relations . . . . . . . . . . . . . . . . . . . . . . . 10 70 8.1. General . . . . . . . . . . . . . . . . . . . . . . . . . 10 71 8.2. subscribe-caldav . . . . . . . . . . . . . . . . . . . . 11 72 8.3. subscribe-caldav-auth . . . . . . . . . . . . . . . . . . 11 73 8.4. subscribe-webdav-sync . . . . . . . . . . . . . . . . . . 11 74 8.5. subscribe-enhanced-get . . . . . . . . . . . . . . . . . 11 75 9. Security Considerations . . . . . . . . . . . . . . . . . . . 11 76 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 77 10.1. Sync-Token HTTP Header Field Registration . . . . . . . 12 78 10.2. Preference Registrations . . . . . . . . . . . . . . . . 12 79 10.3. Link Relation Registrations . . . . . . . . . . . . . . 12 80 11. Normative References . . . . . . . . . . . . . . . . . . . . 13 81 Appendix A. Open issues . . . . . . . . . . . . . . . . . . . . 14 82 Appendix B. Change log . . . . . . . . . . . . . . . . . . . . . 14 83 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 14 85 1. Acknowledgements 87 The author would also like to thank the members of the CalConnect 88 Calendar Sharing technical committee and the following individuals 89 for contributing their ideas and support: 91 Marten Gajda, Ken Murchison, Garry Shutler 93 The authors would also like to thank CalConnect, the Calendaring and 94 Scheduling Consortium, for advice with this specification. 96 2. Introduction 98 Currently clients subscribe to calendar feeds as an iCalendar file 99 which is often published as a resource accessible using the 100 unofficial 'webcal' scheme. 102 The only available option for updating that resource is the usual 103 HTTP polling of cached resources using Etags or Last-Modified. 105 There is the usual tension between clients wishing to see a timely 106 response to changes and servers not wishing to be overloaded by 107 frequent requests for possibly large amounts of data. 109 This specification introduces an approach whereby clients can 110 discover a more performant access method. Given the location of the 111 resource as an iCalendar file, the client can perfom a HEAD request 112 on the resource and inspect the returned headers which will offer a 113 number of alternative access methods. 115 Given that many clients and servers already support CalDAV this 116 provides an easy upgrade path for those clients. Additionally an 117 enhanced GET protocol is specified here to allow a light weight 118 implementation. 120 The use of subscription upgrade may help reduce load on servers, but 121 perhaps more importantly it allows mobile devices to use a more 122 efficient update mechanism reducing data transferred and presumably 123 improving battery life. 125 2.1. Terms and Definitions 127 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 128 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 129 "OPTIONAL" in this document are to be interpreted as described in BCP 130 14 [RFC2119] [RFC8174] when, and only when, they appear in all 131 capitals, as shown here. 133 Additionally, the rule for URI is included from [RFC3986]. 135 3. Discovering alternative access methods 137 The advertising of other access points is achieved through the use of 138 the LINK header as defined in [RFC5988]. New link relation types are 139 defined in this specification - each being associated with a protocol 140 or protocol subset. 142 These LINK headers will be delivered when a client carries out a HEAD 143 request targeting the URL of the resource. 145 EXAMPLE 147 This is an example of a HEAD request and the response from a server 148 that supports the enhanced GET method. 150 >> Request << 152 HEAD /caldata/events.ics HTTP/1.1 153 Host: example.com 154 Accept: text/calendar 156 >> Response << 158 HTTP/1.1 200 OK 159 Content-Length: xxxx 160 Link: ; 161 rel="subscribe-enhanced-get" 163 Note that the target for an upgraded service may be the same as for 164 the initial resource. 166 4. Enhanced GET 168 4.1. General 170 This is a lightweight protocol which allows simple clients to 171 efficiently discover and download changes in the targeted resource. 173 It has many similarities to WebDAV sync and for a server could be 174 implemented as an extension of the specification. 176 In this protocol the client MUST include the Prefer header field 177 preference "subscribe-enhanced-get". If a sync token is available it 178 is passed as a Sync-Token header field. 180 The resource is treated as a set of individual events each of which 181 may be updated or deleted separately. The client will first fetch 182 the entire iCalendar file. On subsequent requests it uses the Prefer 183 header field and a Sync-Token header field to indicate that it wants 184 a set of changes since the last fetch. 186 If no Sync-Token header field is supplied the server SHOULD respond 187 with a full set of data. Otherwise, if the token is valid, it SHOULD 188 return with a set of changed entities. 190 In both cases the server should set the Preference-Applied header 191 field and a new Sync-Token header field value. 193 4.2. Deletions 195 When an entity (VEVENT, VTODO or other valid top-level component) is 196 deleted from the source data the server needs to be able to inform a 197 client of the deletion. This specification introduces a new value 198 for the STATUS property of DELETED. 200 On the first enhanced GET after the entity has been deleted a 201 skeleton, but valid, entity will be returned with STATUS: DELETED. 202 The receiving client is free to remove the entity or update its 203 STATUS property. 205 On subsequent fetches the entity will not be returned. 207 4.3. Handling of invalid sync tokens 209 When a server receives an invalid token it MUST return a 409 status 210 (Conflict). The server MAY choose to return an error message in the 211 body. 213 The client SHOULD respond to this error by restarting the interaction 214 from scratch, i.e. retrieve the full set of data then poll for 215 updates. 217 4.4. Paging the response 219 A client may explicitly request a limit on the size of the response 220 by specifying the Prefer header field preference "limit=n" where n is 221 the number of components. 223 When a server receives a request specifying such a limit it SHOULD 224 limit the response to that number of components. If the limit causes 225 a truncation in the response the server should respond with a 226 Preference-Applied header specifying the limit that was applied and 227 return a sync token which may be used to retrieve the next batch of 228 data. 230 This allows the client to immediately resubmit a request for the next 231 batch using the updated token. 233 A server MAY choose to limit the response size. The behavior SHOULD 234 be as if the client had provided a preference for that size - 235 allowing the client to retrieve the full set of data in batches. 237 4.5. Caching of responses 239 To enable proper caching of responses the server SHOULD provide a 240 VARY header field in responses that names the Prefer and Sync-Token 241 header fields along with any other that are appropriate. 243 Clients should order the preferences as following so that identical 244 responses can be identified: 246 * subscribe-enhanced-get 248 * limit 250 4.6. Examples 252 EXAMPLE 1 254 This is an example of the initial request and response from a server 255 that supports the enhanced GET method. Note the use of the Vary 256 header so a caching proxy can key off the client's Sync-Token and 257 preference. 259 >> Request << 261 GET /events.ics HTTP/1.1 262 Host: example.com 263 Accept: text/calendar 264 Prefer: subscribe-enhanced-get 266 >> Response << 268 HTTP/1.1 200 OK 269 Content-Length: xxxx 270 Sync-Token: "data:,1234567" 271 Preference-Applied: subscribe-enhanced-get 272 Vary: Prefer, Sync-Token 274 BEGIN:VCALENDAR: 275 ? /* full feed */ 276 END:VCALENDAR 278 EXAMPLE 2 280 This is an example of the subsequent request and response when no 281 changes have occurred. 283 >> Request << 285 GET /events.ics HTTP/1.1 286 Host: example.com 287 Accept: text/calendar 288 Prefer: subscribe-enhanced-get 289 Sync-Token: "data:,1234567" 291 >> Response << 293 HTTP/1.1 304 Not Modified 294 Content-Length: 0 295 Sync-Token: "data:,1234567" 296 Preference-Applied: subscribe-enhanced-get 297 Vary: Prefer, Sync-Token 299 EXAMPLE 3 301 This is an example of the subsequent request and response for an old 302 or invalid token. 304 >> Request << 306 GET /events.ics HTTP/1.1 307 Host: example.com 308 Accept: text/calendar 309 Sync-Token: "data:,1234567" 310 Prefer: subscribe-enhanced-get 312 >> Response << 314 HTTP/1.1 409 Conflict 315 Content-Length: xxxx 316 Preference-Applied: subscribe-enhanced-get 318 EXAMPLE 4 320 This is an example of the subsequent request and response when 321 changes have occurred. 323 >> Request << 325 GET /events.ics HTTP/1.1 326 Host: example.com 327 Accept: text/calendar 328 Sync-Token: "data:,1234567" 329 Prefer: subscribe-enhanced-get 331 >> Response << 333 HTTP/1.1 200 OK 334 Content-Type: text/calendar 335 Vary: Prefer, Sync-Token 336 Sync-Token: "data:,4567890" 337 Preference-Applied: subscribe-enhanced-get 339 BEGIN:VCALENDAR: 340 ... only new/changed events 341 ... deleted events have STATUS:DELETED 342 END:VCALENDAR 344 5. Changes to the iCalendar specifications 346 This specification updates [RFC5545] to add the value DELETED to the 347 STATUS property. 349 5.1. Redefined Status property 351 Property name STATUS 353 Purpose This property defines the overall status or confirmation for 354 the calendar component. 356 Value Type TEXT 358 Property Parameters IANA and non-standard property parameters can be 359 specified on this property. 361 Conformance This property can be specified once in "VEVENT", 362 "VTODO", or "VJOURNAL" calendar components. 364 Description In a group-scheduled calendar component, the property is 365 used by the "Organizer" to provide a confirmation of the event to 366 the "Attendees". For example in a "VEVENT" calendar component, 367 the "Organizer" can indicate that a meeting is tentative, 368 confirmed, or cancelled. In a "VTODO" calendar component, the 369 "Organizer" can indicate that an action item needs action, is 370 completed, is in process or being worked on, or has been 371 cancelled. In a "VJOURNAL" calendar component, the "Organizer" 372 can indicate that a journal entry is draft, final, or has been 373 cancelled or removed. 375 Format Definition 377 This property is defined by the following notation: 379 status = "STATUS" statparam ":" statvalue CRLF 381 statparam = *(";" other-param) 383 statvalue = (statvalue-event 384 / statvalue-todo 385 / statvalue-jour) 387 statvalue-event = "TENTATIVE" ;Indicates event is tentative. 388 / "CONFIRMED" ;Indicates event is definite. 389 / "CANCELLED" ;Indicates event was cancelled. 390 / "DELETED" ;Indicates event was deleted. 391 ;Status values for a "VEVENT" 393 statvalue-todo = "NEEDS-ACTION" ;Indicates to-do needs action. 394 / "COMPLETED" ;Indicates to-do completed. 395 / "IN-PROCESS" ;Indicates to-do in process of. 396 / "CANCELLED" ;Indicates to-do was cancelled. 397 / "DELETED" ;Indicates to-do was deleted. 398 ;Status values for "VTODO". 400 statvalue-jour = "DRAFT" ;Indicates journal is draft. 401 / "FINAL" ;Indicates journal is final. 402 / "CANCELLED" ;Indicates journal is removed. 403 / "DELETED" ;Indicates journal was deleted. 404 ;Status values for "VJOURNAL". 406 Example 408 EXAMPLE 1 410 The following is an example of this property for a "VEVENT" calendar 411 component: 413 STATUS:TENTATIVE 415 EXAMPLE 2 417 The following is an example of this property for a "VTODO" calendar 418 component: 420 STATUS:NEEDS-ACTION 422 EXAMPLE 3 424 The following is an example of this property for a "VJOURNAL" 425 calendar component: 427 STATUS:DRAFT 429 6. Header Field: Sync-Token 431 This specification defines a new header field Sync-Token for use by 432 the enhanced GET method. 434 Accept = DQUOTE URI DQUOTE 436 The value MUST be a URI. This will generally be a data URI 437 representing an opaque token. Client MUST not attempt to interpret 438 the data URI value. 440 EXAMPLE 442 This is an example of the Sync-Token header field: 444 Sync-Token: "data:,1234567" 446 7. New Prefer header field preferences 448 7.1. Preference subscribe-enhanced-get 450 This indicates that the client expects the server to handle the GET 451 method according to the specifications for enhanced get. 453 pref-subscribe-enhanced-get = "subscribe-enhanced-get" 455 7.2. Preference limit 457 This preference parameter provides a limit on the number of 458 components returned for enhanced get. 460 pref-limit = "limit" BWS "=" BWS 1*DIGIT 462 8. Link relations 464 8.1. General 466 This clause defines a number of new link relations required to 467 facilitate subscription upgrades. 469 8.2. subscribe-caldav 471 This specifies an access point which is a full implementation of 472 caldav but requires no authentication. The end point allows the full 473 range of reports as defined by the CalDAV specification. 475 The client MUST follow the specification to determine exactly what 476 operations are allowed on the access point - for example to determine 477 if DAV:sync-collection is supported. 479 The URL MAY include some form of token to allow write access to the 480 targeted collection. The client must check its permissions to 481 determine whether or not it has been granted write access. 483 8.3. subscribe-caldav-auth 485 This specifies an access point which is a full implementation of 486 caldav and requires authentication. This may allow read-write access 487 to the resource. 489 The client MUST follow the specification to determine exactly what 490 operations are allowed on the access point - for example to determine 491 if DAV:sync-collection is supported. 493 8.4. subscribe-webdav-sync 495 This specifies an access point which supports only webdav sync. 497 This allows the client to issue a DAV:sync-collection report on the 498 resource to obtain updates. 500 The client MUST follow that specification. 502 8.5. subscribe-enhanced-get 504 This specifies an access point which supports something new. 506 The client MUST follow that specification. 508 9. Security Considerations 510 Applications using these properties need to be aware of the risks 511 entailed in using the URIs provided as values. See [RFC3986] for a 512 discussion of the security considerations relating to URIs. == 513 Privacy Considerations 514 Properties with a "URI" value type can expose their users to privacy 515 leaks as any network access of the URI data can be tracked. Clients 516 SHOULD NOT automatically download data referenced by the URI without 517 explicit instruction from users. This specification does not 518 introduce any additional privacy concerns beyond those described in 519 [RFC5545]. 521 10. IANA Considerations 523 10.1. Sync-Token HTTP Header Field Registration 525 This specification updates the "Message Headers" registry entry for 526 "Sync-Token" in [RFC3864] to refer to this document. 528 Header Field Name: Sync-Token 529 Protocol: http 530 Status: standard 531 Reference: 533 Figure 1 535 10.2. Preference Registrations 537 The following preferences have been added to the HTTP Preferences 538 Registry defined in [RFC7240] 540 Preference subscribe-enhanced-get 542 Value None. 544 Description Marks the interaction as enhanced get and provides the 545 optional sync-token and page size. 547 Reference this document 549 Preference limit 551 Value An integer page size. 553 Description Provide a limit on the number of components in the 554 response. 556 Reference this document 558 10.3. Link Relation Registrations 560 This document defines the following new iCalendar properties to be 561 added to the registry defined in [RFC5545]: 563 +========================+=============+=============+ 564 | Relation Name | Description | Reference | 565 +========================+=============+=============+ 566 | subscribe-caldav | Current | Section 8.2 | 567 +------------------------+-------------+-------------+ 568 | subscribe-caldav_auth | Current | Section 8.3 | 569 +------------------------+-------------+-------------+ 570 | subscribe-webdav-sync | Current | Section 8.4 | 571 +------------------------+-------------+-------------+ 572 | subscribe-enhanced_get | Current | Section 8.5 | 573 +------------------------+-------------+-------------+ 575 Table 1 577 11. Normative References 579 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 580 Requirement Levels", RFC 2119, IETF RFC 2119, 581 DOI 10.17487/RFC2119, March 1997, 582 . 584 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 585 Procedures for Message Header Fields", RFC 3864, IETF RFC 586 3864, DOI 10.17487/RFC3864, September 2004, 587 . 589 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 590 Resource Identifier (URI): Generic Syntax", RFC 3986, 591 IETF RFC 3986, DOI 10.17487/RFC3986, January 2005, 592 . 594 [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and 595 Scheduling Core Object Specification (iCalendar)", RFC 596 5545, IETF RFC 5545, DOI 10.17487/RFC5545, September 2009, 597 . 599 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, IETF RFC 5988, 600 DOI 10.17487/RFC5988, October 2010, 601 . 603 [RFC7240] Snell, J., "Prefer Header for HTTP", RFC 7240, IETF RFC 604 7240, DOI 10.17487/RFC7240, June 2014, 605 . 607 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 608 2119 Key Words", RFC 8174, IETF RFC 8174, 609 DOI 10.17487/RFC8174, May 2017, 610 . 612 Appendix A. Open issues 614 Vary Ensure we get that right. 616 Appendix B. Change log 618 calext00 2019-06-05 MD 620 * First calext version 622 * Use Sync-Token header rather than parameter 624 v04 2019-03-07 MD 626 * Reference to RFC 6538 - WebDAV sync and RFC 7240 Prefer 628 * Go back to HEAD 630 * New Preference and parameters. 632 * Examples 634 * More text for extended get. Talk about deletions. 636 v01 2017-02-17 MD 638 * Add text about OPTIONS 640 * Add text abut read/write CalDAV 642 v00 2017-02-15 MD 644 * First pass 646 Author's Address 648 Michael Douglass 650 Email: mdouglass@bedework.com