idnits 2.17.1 draft-ietf-calext-subscription-upgrade-00.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 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 == 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 (June 7, 2019) is 1784 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) == Unused Reference: 'RFC2434' is defined on line 569, but no explicit reference was found in the text == Unused Reference: 'RFC3688' is defined on line 574, but no explicit reference was found in the text == Unused Reference: 'RFC4589' is defined on line 588, but no explicit reference was found in the text == Unused Reference: 'RFC5546' is defined on line 597, but no explicit reference was found in the text == Unused Reference: 'RFC6578' is defined on line 606, but no explicit reference was found in the text == Unused Reference: 'RFC7991' is defined on line 615, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2434 (Obsoleted by RFC 5226) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) ** Downref: Normative reference to an Informational RFC: RFC 7991 Summary: 4 errors (**), 0 flaws (~~), 8 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Douglass 3 Internet-Draft Spherical Cow Group 4 Updates: 5988,7240 (if approved) June 7, 2019 5 Intended status: Standards Track 6 Expires: December 9, 2019 8 Calendar subscription upgrades 9 draft-ietf-calext-subscription-upgrade-00 11 Abstract 13 This specification introduces an approach to allow subscribers to 14 calendar feeds to upgrade to a more performant protocol. 16 This specification updates [RFC5545] to add the value DELETED to the 17 STATUS property. 19 This specification also updates [RFC7240] to add the subscribe- 20 enhanced-get and limit preferences. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at https://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on December 9, 2019. 39 Copyright Notice 41 Copyright (c) 2019 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (https://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 57 1.1. Terms and Definitions . . . . . . . . . . . . . . . . . . 3 58 2. Discovering alternative access methods . . . . . . . . . . . 3 59 3. Enhanced GET . . . . . . . . . . . . . . . . . . . . . . . . 4 60 3.1. General . . . . . . . . . . . . . . . . . . . . . . . . . 4 61 3.2. Deletions . . . . . . . . . . . . . . . . . . . . . . . . 5 62 3.3. Handling of invalid sync tokens . . . . . . . . . . . . . 5 63 3.4. Paging the response . . . . . . . . . . . . . . . . . . . 5 64 3.5. Caching of responses . . . . . . . . . . . . . . . . . . 6 65 3.6. Examples . . . . . . . . . . . . . . . . . . . . . . . . 6 66 4. Changes to the iCalendar specifications . . . . . . . . . . . 8 67 4.1. Redefined Status property . . . . . . . . . . . . . . . . 8 68 5. Header Field: Sync-Token . . . . . . . . . . . . . . . . . . 10 69 6. New Prefer header field preferences . . . . . . . . . . . . . 10 70 6.1. Preference subscribe-enhanced-get . . . . . . . . . . . . 10 71 6.2. Preference limit . . . . . . . . . . . . . . . . . . . . 10 72 7. Link relations . . . . . . . . . . . . . . . . . . . . . . . 10 73 7.1. General . . . . . . . . . . . . . . . . . . . . . . . . . 10 74 7.2. subscribe-caldav . . . . . . . . . . . . . . . . . . . . 11 75 7.3. subscribe-caldav-auth . . . . . . . . . . . . . . . . . . 11 76 7.4. subscribe-webdav-sync . . . . . . . . . . . . . . . . . . 11 77 7.5. subscribe-enhanced-get . . . . . . . . . . . . . . . . . 11 78 8. Security Considerations . . . . . . . . . . . . . . . . . . . 11 79 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 80 9.1. Sync-Token HTTP Header Field Registration . . . . . . . . 12 81 9.2. Preference Registrations . . . . . . . . . . . . . . . . 12 82 9.3. Link Relation Registrations . . . . . . . . . . . . . . . 13 83 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 13 84 11. Normative References . . . . . . . . . . . . . . . . . . . . 13 85 Appendix A. Open issues . . . . . . . . . . . . . . . . . . . . 14 86 Appendix B. Change log . . . . . . . . . . . . . . . . . . . . . 15 87 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 15 89 1. Introduction 91 Currently clients subscribe to calendar feeds as an iCalendar file 92 which is often published as a resource accessible using the 93 unofficial 'webcal' scheme. 95 The only available option for updating that resource is the usual 96 HTTP polling of cached resources using Etags. 98 There is the usual tension between clients wishing to see a timely 99 response to changes and servers not wishing to be overloaded by 100 frequent requests for possibly large amounts of data. 102 This specification introduces an approach whereby clients can 103 discover a more performant access method. Given the location of the 104 resource as an iCalendar file, the client can perfom a HEAD request 105 on the resource and inspect the returned headers which will offer a 106 number of alternative access methods. 108 Given that many clients and servers already support CalDAV this 109 provides an easy upgrade path for those clients. CalDAV and DAV 110 subsets are specified here to allow lighter weight implementations. 112 1.1. Terms and Definitions 114 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 115 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 116 "OPTIONAL" in this document are to be interpreted as described in BCP 117 14 [RFC2119] [RFC8174] when, and only when, they appear in all 118 capitals, as shown here. 120 Additionally, the rule for URI is included from [RFC3986]. 122 2. Discovering alternative access methods 124 The advertising of other access points is achieved through the use of 125 the LINK header as defined in [RFC5988]. New link relation types are 126 defined in this specification - each being associated with a protocol 127 or protocol subset. 129 These LINK headers will be delivered when a client carries out a HEAD 130 request targeting the URL of the resource. 132 This is an example of a HEAD request and the response from a server 133 that supports the enhanced GET method. 135 >> Request << 137 HEAD /caldata/events.ics HTTP/1.1 138 Host: example.com 139 Accept: text/calendar 141 >> Response << 143 HTTP/1.1 200 OK 144 Content-Length: xxxx 145 Link: ; 146 rel="subscribe-enhanced-get" 148 Note that the target for an upgraded service may be the same as for 149 the initial resource. 151 3. Enhanced GET 153 3.1. General 155 This is a lightweight protocol which allows simple clients to 156 efficiently discover and download changes in the targeted resource. 158 It has many similarities to WebDAV sync and for a server could be 159 implemented as an extension of the specification. 161 In this protocol the client MUST include the Prefer header field 162 preference "subscribe-enhanced-get". If a sync token is available it 163 is passed as a Sync-Token header field. 165 The resource is treated as a set of individual events each of which 166 may be updated or deleted separately. The client will first fetch 167 the entire iCalendar file. On subsequent requests it uses the Prefer 168 header field and a Sync-Token header field to indicate that it wants 169 a set of changes since the last fetch. 171 If no Sync-Token header field is supplied the server SHOULD respond 172 with a full set of data. Otherwise, if the token is valid, it SHOULD 173 return with a set of changed entities. 175 In both cases the server should set the Preference-Applied header 176 field and a new Sync-Token header field value. 178 3.2. Deletions 180 When an entity (VEVENT, VTODO or other valid top-level component) is 181 deleted from the source data the server needs to be able to inform a 182 client of the deletion. This specification introduces a new value 183 for the STATUS property of DELETED. 185 On the first enhanced GET after the entity has been deleted a 186 skeleton, but valid, entity will be returned with STATUS: DELETED. 187 The receiving client is free to remove the entity or update it's 188 STATUS property. 190 On subsequent fetches the entity will not be returned. 192 3.3. Handling of invalid sync tokens 194 When a server receives an invalid token it MUST return a 409 status 195 (Conflict). The server MAY choose to return an error message in the 196 body. 198 The client SHOULD respond to this error by restarting the interaction 199 from scratch, i.e. retrieve the full set of data then poll for 200 updates. 202 3.4. Paging the response 204 A client may explicitly request a limit on the size of the response 205 by specifying the Prefer header field preference "limit=n" where n is 206 the number of components. 208 When a server receives a request specifying such a limit it SHOULD 209 limit the response to that number of components. If the limit causes 210 a truncation in the response the server should respond with a 211 Preference-Applied header specifying the limit that was applied and 212 return a sync token which may be used to retrieve the next batch of 213 data. 215 This allows the client to immediately resubmit a request for the next 216 batch using the updated token. 218 A server MAY choose to limit the response size. The behavior SHOULD 219 be as if the client had provided a preference for that size - 220 allowing the client to retrieve the full set of data in batches. 222 3.5. Caching of responses 224 To enable proper caching of responses the server SHOULD provide a 225 VARY header field in responses that names the Prefer and Sync-Token 226 header fields along with any other that are appropriate. 228 Clients should order the preferences as following so that identical 229 responses can be identified: 231 o subscribe-enhanced-get 233 o limit 235 3.6. Examples 237 This is an example of the initial request and response from a server 238 that supports the enhanced GET method. Note the use of the Vary 239 header so a caching proxy can key off the client's Sync-Token and 240 preference. 242 >> Request << 244 GET /events.ics HTTP/1.1 245 Host: example.com 246 Accept: text/calendar 247 Prefer: subscribe-enhanced-get 249 >> Response << 251 HTTP/1.1 200 OK 252 Content-Length: xxxx 253 Sync-Token: "data:,1234567" 254 Preference-Applied: subscribe-enhanced-get 255 Vary: Prefer, Sync-Token 257 BEGIN:VCALENDAR: 258 ? /* full feed */ 259 END:VCALENDAR 261 This is an example of the subsequent request and response when no 262 changes have occurred. 264 >> Request << 266 GET /events.ics HTTP/1.1 267 Host: example.com 268 Accept: text/calendar 269 Prefer: subscribe-enhanced-get 270 Sync-Token: "data:,1234567" 272 >> Response << 274 HTTP/1.1 304 Not Modified 275 Content-Length: 0 276 Sync-Token: "data:,1234567" 277 Preference-Applied: subscribe-enhanced-get 278 Vary: Prefer, Sync-Token 280 This is an example of the subsequent request and response for an old 281 or invalid token. 283 >> Request << 285 GET /events.ics HTTP/1.1 286 Host: example.com 287 Accept: text/calendar 288 Sync-Token: "data:,1234567" 289 Prefer: subscribe-enhanced-get 291 >> Response << 293 HTTP/1.1 409 Conflict 294 Content-Length: xxxx 295 Preference-Applied: subscribe-enhanced-get 297 This is an example of the subsequent request and response when 298 changes have occurred. 300 >> Request << 302 GET /events.ics HTTP/1.1 303 Host: example.com 304 Accept: text/calendar 305 Sync-Token: "data:,1234567" 306 Prefer: subscribe-enhanced-get 308 >> Response << 310 HTTP/1.1 200 OK 311 Content-Type: text/calendar 312 Vary: Prefer, Sync-Token 313 Sync-Token: "data:,4567890" 314 Preference-Applied: subscribe-enhanced-get 316 BEGIN:VCALENDAR: 317 ... only new/changed events 318 ... deleted events have STATUS:DELETED 319 END:VCALENDAR 321 4. Changes to the iCalendar specifications 323 This specification updates [RFC5545] to add the value DELETED to the 324 STATUS property. 326 4.1. Redefined Status property 328 Property name 329 STATUS 331 Purpose 332 This property defines the overall status or confirmation for the 333 calendar component. 335 Value Type 336 TEXT 338 Property Parameters 339 IANA and non-standard property parameters can be specified on this 340 property. 342 Conformance 343 This property can be specified once in "VEVENT", "VTODO", or 344 "VJOURNAL" calendar components. 346 Description 347 In a group-scheduled calendar component, the property is used by 348 the "Organizer" to provide a confirmation of the event to the 349 "Attendees". For example in a "VEVENT" calendar component, the 350 "Organizer" can indicate that a meeting is tentative, confirmed, 351 or cancelled. In a "VTODO" calendar component, the "Organizer" 352 can indicate that an action item needs action, is completed, is in 353 process or being worked on, or has been cancelled. In a 354 "VJOURNAL" calendar component, the "Organizer" can indicate that a 355 journal entry is draft, final, or has been cancelled or removed. 357 Format Definition 359 This property is defined by the following notation: 361 status = "STATUS" statparam ":" statvalue CRLF 363 statparam = *(";" other-param) 365 statvalue = (statvalue-event 366 / statvalue-todo 367 / statvalue-jour) 369 statvalue-event = "TENTATIVE" ;Indicates event is tentative. 370 / "CONFIRMED" ;Indicates event is definite. 371 / "CANCELLED" ;Indicates event was cancelled. 372 / "DELETED" ;Indicates event was deleted. 373 ;Status values for a "VEVENT" 375 statvalue-todo = "NEEDS-ACTION" ;Indicates to-do needs action. 376 / "COMPLETED" ;Indicates to-do completed. 377 / "IN-PROCESS" ;Indicates to-do in process of. 378 / "CANCELLED" ;Indicates to-do was cancelled. 379 / "DELETED" ;Indicates to-do was deleted. 380 ;Status values for "VTODO". 382 statvalue-jour = "DRAFT" ;Indicates journal is draft. 383 / "FINAL" ;Indicates journal is final. 384 / "CANCELLED" ;Indicates journal is removed. 385 / "DELETED" ;Indicates journal was deleted. 386 ;Status values for "VJOURNAL". 388 Example 390 The following is an example of this property for a "VEVENT" calendar 391 component: 393 STATUS:TENTATIVE 394 The following is an example of this property for a "VTODO" calendar 395 component: 397 STATUS:NEEDS-ACTION 399 The following is an example of this property for a "VJOURNAL" 400 calendar component: 402 STATUS:DRAFT 404 5. Header Field: Sync-Token 406 This specification defines a new header field Sync-Token for use by 407 the enhanced GET method. 409 Accept = DQUOTE URI DQUOTE 411 The value MUST be a URI. This will generally be a data URI 412 representing an opaque token. Client MUST not attempt to interpret 413 the data URI value. 415 This is an example of the Sync-Token header field: 417 Sync-Token: "data:,1234567" 419 6. New Prefer header field preferences 421 6.1. Preference subscribe-enhanced-get 423 This indicates that the client expects the server to handle the GET 424 method according to the specifications for enhanced get. 426 pref-subscribe-enhanced-get = "subscribe-enhanced-get" 428 6.2. Preference limit 430 This preference parameter provides a limit on the number of 431 components returned for enhanced get. 433 pref-limit = "limit" BWS "=" BWS 1*DIGIT 435 7. Link relations 437 7.1. General 439 This clause defines a number of new link relations required to 440 facilitate subscription upgrades. 442 7.2. subscribe-caldav 444 This specifies an access point which is a full implementation of 445 caldav but requires no authentication. The end point allows the full 446 range of reports as defined by the CalDAV specification. 448 The client MUST follow the specification to determine exactly what 449 operations are allowed on the access point - for example to determine 450 if sync-report is supported. 452 The URL MAY include some form of token to allow write access to the 453 targeted collection. The client must check it's permissions to 454 determine whether or not it has been granted write access. 456 7.3. subscribe-caldav-auth 458 This specifies an access point which is a full implementation of 459 caldav and requires authentication. This may allow read-write access 460 to the resource. 462 The client MUST follow the specification to determine exactly what 463 operations are allowed on the access point -- for example to 464 determine if sync-report is supported. 466 7.4. subscribe-webdav-sync 468 This specifies an access point which supports only webdav sync. 470 This allows the client to issue a sync-report on the resource to 471 obtain updates. 473 The client MUST follow that specification. 475 7.5. subscribe-enhanced-get 477 This specifies an access point which supports something new. 479 The client MUST follow that specification. 481 8. Security Considerations 483 Applications using these properties need to be aware of the risks 484 entailed in using the URIs provided as values. See [RFC3986] for a 485 discussion of the security considerations relating to URIs. == 486 Privacy Considerations 488 Properties with a "URI" value type can expose their users to privacy 489 leaks as any network access of the URI data can be tracked. Clients 490 SHOULD NOT automatically download data referenced by the URI without 491 explicit instruction from users. This specification does not 492 introduce any additional privacy concerns beyond those described in 493 [RFC5545]. 495 9. IANA Considerations 497 9.1. Sync-Token HTTP Header Field Registration 499 This specification updates the "Message Headers" registry entry for 500 "Sync-Token" in [RFC3864] to refer to this document. 502 Header Field Name: Sync-Token 503 Protocol: http 504 Status: standard 505 Reference: 507 9.2. Preference Registrations 509 The following preferences have been added to the HTTP Preferences 510 Registry defined in [RFC7240] 512 Preference 513 subscribe-enhanced-get 515 Value 516 None. 518 Description 519 Marks the interaction as enhanced get and provides the optional 520 sync-token and page size. 522 Reference 523 this document 525 Preference 526 limit 528 Value 529 An integer page size. 531 Description 532 Provide a limit on the number of components in the response. 534 Reference 535 this document 537 9.3. Link Relation Registrations 539 This document defines the following new iCalendar properties to be 540 added to the registry defined in section=8.2.3 [RFC5545]: 542 +------------------------+-------------+--------------+ 543 | Relation Name | Description | Reference | 544 +------------------------+-------------+--------------+ 545 | subscribe-caldav | Current | Section 7.2 | 546 | subscribe-caldav_auth | Current | Section 7.3 | 547 | subscribe-webdav-sync | Current | Section 7.4 | 548 | subscribe-enhanced_get | Current | Section 7.5 | 549 +------------------------+-------------+--------------+ 551 10. Acknowledgements 553 The author would also like to thank the members of the CalConnect 554 Calendar Sharing technical committee and the following individuals 555 for contributing their ideas and support: 557 Marten Gajda, Ken Murchison, Garry Shutler 559 The authors would also like to thank CalConnect, the Calendaring and 560 Scheduling Consortium, for advice with this specification. 562 11. Normative References 564 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 565 Requirement Levels", BCP 14, RFC 2119, 566 DOI 10.17487/RFC2119, March 1997, 567 . 569 [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an 570 IANA Considerations Section in RFCs", RFC 2434, 571 DOI 10.17487/RFC2434, October 1998, 572 . 574 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 575 DOI 10.17487/RFC3688, January 2004, 576 . 578 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 579 Procedures for Message Header Fields", BCP 90, RFC 3864, 580 DOI 10.17487/RFC3864, September 2004, 581 . 583 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 584 Resource Identifier (URI): Generic Syntax", STD 66, 585 RFC 3986, DOI 10.17487/RFC3986, January 2005, 586 . 588 [RFC4589] Schulzrinne, H. and H. Tschofenig, "Location Types 589 Registry", RFC 4589, DOI 10.17487/RFC4589, July 2006, 590 . 592 [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and 593 Scheduling Core Object Specification (iCalendar)", 594 RFC 5545, DOI 10.17487/RFC5545, September 2009, 595 . 597 [RFC5546] Daboo, C., Ed., "iCalendar Transport-Independent 598 Interoperability Protocol (iTIP)", RFC 5546, 599 DOI 10.17487/RFC5546, December 2009, 600 . 602 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 603 DOI 10.17487/RFC5988, October 2010, 604 . 606 [RFC6578] Daboo, C. and A. Quillaud, "Collection Synchronization for 607 Web Distributed Authoring and Versioning (WebDAV)", 608 RFC 6578, DOI 10.17487/RFC6578, March 2012, 609 . 611 [RFC7240] Snell, J., "Prefer Header for HTTP", RFC 7240, 612 DOI 10.17487/RFC7240, June 2014, 613 . 615 [RFC7991] Hoffman, P., "The "xml2rfc" Version 3 Vocabulary", 616 RFC 7991, DOI 10.17487/RFC7991, December 2016, 617 . 619 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 620 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 621 May 2017, . 623 Appendix A. Open issues 625 Vary 626 Ensure we get that right. 628 Appendix B. Change log 630 calext00 2019-06-05 MD 632 o First calext version 634 o Use Sync-Token header rather than parameter 636 v04 2019-03-07 MD 638 o Reference to RFC 6538 - WebDAV sync and RFC 7240 Prefer 640 o Go back to HEAD 642 o New Preference and parameters. 644 o Examples 646 o More text for extended get. Talk about deletions. 648 v01 2017-02-17 MD 650 o Add text about OPTIONS 652 o Add text abut read/write CalDAV 654 v00 2017-02-15 MD 656 o First pass 658 Author's Address 660 Michael Douglass 661 Spherical Cow Group 662 226 3rd Street 663 Troy 12180 664 United States of America 666 Email: mdouglass@sphericalcowgroup.com 667 URI: http://sphericalcowgroup.com