idnits 2.17.1 draft-ietf-calext-subscription-upgrade-02.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 560 has weird spacing: '...ference subsc...' == Line 567 has weird spacing: '...ference this ...' == Line 569 has weird spacing: '...ference limit...' == Line 576 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 (29 July 2020) is 1364 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 29 July 2020 4 Updates: 5988 (if approved) 5 Intended status: Standards Track 6 Expires: 30 January 2021 8 Calendar subscription upgrades 9 draft-ietf-calext-subscription-upgrade-02 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 30 January 2021. 36 Copyright Notice 38 Copyright (c) 2020 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 . . . . . . . . . . . . . . . . . . . . 11 69 8. Link relations . . . . . . . . . . . . . . . . . . . . . . . 11 70 8.1. General . . . . . . . . . . . . . . . . . . . . . . . . . 11 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 . . . . . . . . . . . . . . . . . 12 75 9. Security Considerations . . . . . . . . . . . . . . . . . . . 12 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 . . . . . . . . . . . . . . 13 80 11. Normative References . . . . . . . . . . . . . . . . . . . . 13 81 Appendix A. Open issues . . . . . . . . . . . . . . . . . . . . 14 82 Appendix B. Change log . . . . . . . . . . . . . . . . . . . . . 14 83 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 15 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. 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. CalDAV and DAV 117 subsets are specified here to allow lighter weight implementations. 119 2.1. Terms and Definitions 121 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 122 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 123 "OPTIONAL" in this document are to be interpreted as described in BCP 124 14 [RFC2119] [RFC8174] when, and only when, they appear in all 125 capitals, as shown here. 127 Additionally, the rule for URI is included from [RFC3986]. 129 3. Discovering alternative access methods 131 The advertising of other access points is achieved through the use of 132 the LINK header as defined in [RFC5988]. New link relation types are 133 defined in this specification - each being associated with a protocol 134 or protocol subset. 136 These LINK headers will be delivered when a client carries out a HEAD 137 request targeting the URL of the resource. 139 EXAMPLE 141 This is an example of a HEAD request and the response from a server 142 that supports the enhanced GET method. 144 >> Request << 146 HEAD /caldata/events.ics HTTP/1.1 147 Host: example.com 148 Accept: text/calendar 150 >> Response << 152 HTTP/1.1 200 OK 153 Content-Length: xxxx 154 Link: <http://example.com/subscribe/events.ics>; 155 rel="subscribe-enhanced-get" 157 Figure 1 159 Note that the target for an upgraded service may be the same as for 160 the initial resource. 162 4. Enhanced GET 164 4.1. General 166 This is a lightweight protocol which allows simple clients to 167 efficiently discover and download changes in the targeted resource. 169 It has many similarities to WebDAV sync and for a server could be 170 implemented as an extension of the specification. 172 In this protocol the client MUST include the Prefer header field 173 preference "subscribe-enhanced-get". If a sync token is available it 174 is passed as a Sync-Token header field. 176 The resource is treated as a set of individual events each of which 177 may be updated or deleted separately. The client will first fetch 178 the entire iCalendar file. On subsequent requests it uses the Prefer 179 header field and a Sync-Token header field to indicate that it wants 180 a set of changes since the last fetch. 182 If no Sync-Token header field is supplied the server SHOULD respond 183 with a full set of data. Otherwise, if the token is valid, it SHOULD 184 return with a set of changed entities. 186 In both cases the server should set the Preference-Applied header 187 field and a new Sync-Token header field value. 189 4.2. Deletions 191 When an entity (VEVENT, VTODO or other valid top-level component) is 192 deleted from the source data the server needs to be able to inform a 193 client of the deletion. This specification introduces a new value 194 for the STATUS property of DELETED. 196 On the first enhanced GET after the entity has been deleted a 197 skeleton, but valid, entity will be returned with STATUS: DELETED. 198 The receiving client is free to remove the entity or update it's 199 STATUS property. 201 On subsequent fetches the entity will not be returned. 203 4.3. Handling of invalid sync tokens 205 When a server receives an invalid token it MUST return a 409 status 206 (Conflict). The server MAY choose to return an error message in the 207 body. 209 The client SHOULD respond to this error by restarting the interaction 210 from scratch, i.e. retrieve the full set of data then poll for 211 updates. 213 4.4. Paging the response 215 A client may explicitly request a limit on the size of the response 216 by specifying the Prefer header field preference "limit=n" where n is 217 the number of components. 219 When a server receives a request specifying such a limit it SHOULD 220 limit the response to that number of components. If the limit causes 221 a truncation in the response the server should respond with a 222 Preference-Applied header specifying the limit that was applied and 223 return a sync token which may be used to retrieve the next batch of 224 data. 226 This allows the client to immediately resubmit a request for the next 227 batch using the updated token. 229 A server MAY choose to limit the response size. The behavior SHOULD 230 be as if the client had provided a preference for that size - 231 allowing the client to retrieve the full set of data in batches. 233 4.5. Caching of responses 235 To enable proper caching of responses the server SHOULD provide a 236 VARY header field in responses that names the Prefer and Sync-Token 237 header fields along with any other that are appropriate. 239 Clients should order the preferences as following so that identical 240 responses can be identified: 242 * subscribe-enhanced-get 244 * limit 246 4.6. Examples 248 EXAMPLE 1 250 This is an example of the initial request and response from a server 251 that supports the enhanced GET method. Note the use of the Vary 252 header so a caching proxy can key off the client's Sync-Token and 253 preference. 255 >> Request << 257 GET /events.ics HTTP/1.1 258 Host: example.com 259 Accept: text/calendar 260 Prefer: subscribe-enhanced-get 262 >> Response << 264 HTTP/1.1 200 OK 265 Content-Length: xxxx 266 Sync-Token: "data:,1234567" 267 Preference-Applied: subscribe-enhanced-get 268 Vary: Prefer, Sync-Token 270 BEGIN:VCALENDAR: 271 ? /* full feed */ 272 END:VCALENDAR 274 Figure 2 276 EXAMPLE 2 278 This is an example of the subsequent request and response when no 279 changes have occurred. 281 >> Request << 283 GET /events.ics HTTP/1.1 284 Host: example.com 285 Accept: text/calendar 286 Prefer: subscribe-enhanced-get 287 Sync-Token: "data:,1234567" 289 >> Response << 291 HTTP/1.1 304 Not Modified 292 Content-Length: 0 293 Sync-Token: "data:,1234567" 294 Preference-Applied: subscribe-enhanced-get 295 Vary: Prefer, Sync-Token 297 Figure 3 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 Figure 4 320 EXAMPLE 4 322 This is an example of the subsequent request and response when 323 changes have occurred. 325 >> Request << 327 GET /events.ics HTTP/1.1 328 Host: example.com 329 Accept: text/calendar 330 Sync-Token: "data:,1234567" 331 Prefer: subscribe-enhanced-get 333 >> Response << 335 HTTP/1.1 200 OK 336 Content-Type: text/calendar 337 Vary: Prefer, Sync-Token 338 Sync-Token: "data:,4567890" 339 Preference-Applied: subscribe-enhanced-get 341 BEGIN:VCALENDAR: 342 ... only new/changed events 343 ... deleted events have STATUS:DELETED 344 END:VCALENDAR 346 Figure 5 348 5. Changes to the iCalendar specifications 350 This specification updates [RFC5545] to add the value DELETED to the 351 STATUS property. 353 5.1. Redefined Status property 355 Property name STATUS 357 Purpose This property defines the overall status or confirmation for 358 the calendar component. 360 Value Type TEXT 362 Property Parameters IANA and non-standard property parameters can be 363 specified on this property. 365 Conformance This property can be specified once in "VEVENT", 366 "VTODO", or "VJOURNAL" calendar components. 368 Description In a group-scheduled calendar component, the property is 369 used by the "Organizer" to provide a confirmation of the event to 370 the "Attendees". For example in a "VEVENT" calendar component, 371 the "Organizer" can indicate that a meeting is tentative, 372 confirmed, or cancelled. In a "VTODO" calendar component, the 373 "Organizer" can indicate that an action item needs action, is 374 completed, is in process or being worked on, or has been 375 cancelled. In a "VJOURNAL" calendar component, the "Organizer" 376 can indicate that a journal entry is draft, final, or has been 377 cancelled or removed. 379 Format Definition 381 This property is defined by the following notation: 383 status = "STATUS" statparam ":" statvalue CRLF 385 statparam = *(";" other-param) 387 statvalue = (statvalue-event 388 / statvalue-todo 389 / statvalue-jour) 391 statvalue-event = "TENTATIVE" ;Indicates event is tentative. 392 / "CONFIRMED" ;Indicates event is definite. 393 / "CANCELLED" ;Indicates event was cancelled. 394 / "DELETED" ;Indicates event was deleted. 395 ;Status values for a "VEVENT" 397 statvalue-todo = "NEEDS-ACTION" ;Indicates to-do needs action. 398 / "COMPLETED" ;Indicates to-do completed. 399 / "IN-PROCESS" ;Indicates to-do in process of. 400 / "CANCELLED" ;Indicates to-do was cancelled. 401 / "DELETED" ;Indicates to-do was deleted. 402 ;Status values for "VTODO". 404 statvalue-jour = "DRAFT" ;Indicates journal is draft. 405 / "FINAL" ;Indicates journal is final. 406 / "CANCELLED" ;Indicates journal is removed. 407 / "DELETED" ;Indicates journal was deleted. 408 ;Status values for "VJOURNAL". 410 Figure 6 412 Example 414 EXAMPLE 1 416 The following is an example of this property for a "VEVENT" calendar 417 component: 419 STATUS:TENTATIVE 420 Figure 7 422 EXAMPLE 2 424 The following is an example of this property for a "VTODO" calendar 425 component: 427 STATUS:NEEDS-ACTION 429 Figure 8 431 EXAMPLE 3 433 The following is an example of this property for a "VJOURNAL" 434 calendar component: 436 STATUS:DRAFT 438 Figure 9 440 6. Header Field: Sync-Token 442 This specification defines a new header field Sync-Token for use by 443 the enhanced GET method. 445 Accept = DQUOTE URI DQUOTE 447 Figure 10 449 The value MUST be a URI. This will generally be a data URI 450 representing an opaque token. Client MUST not attempt to interpret 451 the data URI value. 453 EXAMPLE 455 This is an example of the Sync-Token header field: 457 Sync-Token: "data:,1234567" 459 Figure 11 461 7. New Prefer header field preferences 463 7.1. Preference subscribe-enhanced-get 465 This indicates that the client expects the server to handle the GET 466 method according to the specifications for enhanced get. 468 pref-subscribe-enhanced-get = "subscribe-enhanced-get" 470 Figure 12 472 7.2. Preference limit 474 This preference parameter provides a limit on the number of 475 components returned for enhanced get. 477 pref-limit = "limit" BWS "=" BWS 1*DIGIT 479 Figure 13 481 8. Link relations 483 8.1. General 485 This clause defines a number of new link relations required to 486 facilitate subscription upgrades. 488 8.2. subscribe-caldav 490 This specifies an access point which is a full implementation of 491 caldav but requires no authentication. The end point allows the full 492 range of reports as defined by the CalDAV specification. 494 The client MUST follow the specification to determine exactly what 495 operations are allowed on the access point - for example to determine 496 if sync-report is supported. 498 The URL MAY include some form of token to allow write access to the 499 targeted collection. The client must check it's permissions to 500 determine whether or not it has been granted write access. 502 8.3. subscribe-caldav-auth 504 This specifies an access point which is a full implementation of 505 caldav and requires authentication. This may allow read-write access 506 to the resource. 508 The client MUST follow the specification to determine exactly what 509 operations are allowed on the access point - for example to determine 510 if sync-report is supported. 512 8.4. subscribe-webdav-sync 514 This specifies an access point which supports only webdav sync. 516 This allows the client to issue a sync-report on the resource to 517 obtain updates. 519 The client MUST follow that specification. 521 8.5. subscribe-enhanced-get 523 This specifies an access point which supports something new. 525 The client MUST follow that specification. 527 9. Security Considerations 529 Applications using these properties need to be aware of the risks 530 entailed in using the URIs provided as values. See [RFC3986] for a 531 discussion of the security considerations relating to URIs. == 532 Privacy Considerations 534 Properties with a "URI" value type can expose their users to privacy 535 leaks as any network access of the URI data can be tracked. Clients 536 SHOULD NOT automatically download data referenced by the URI without 537 explicit instruction from users. This specification does not 538 introduce any additional privacy concerns beyond those described in 539 [RFC5545]. 541 10. IANA Considerations 543 10.1. Sync-Token HTTP Header Field Registration 545 This specification updates the "Message Headers" registry entry for 546 "Sync-Token" in [RFC3864] to refer to this document. 548 Header Field Name: Sync-Token 549 Protocol: http 550 Status: standard 551 Reference: 553 Figure 14 555 10.2. Preference Registrations 557 The following preferences have been added to the HTTP Preferences 558 Registry defined in [RFC7240] 560 Preference subscribe-enhanced-get 562 Value None. 564 Description Marks the interaction as enhanced get and provides the 565 optional sync-token and page size. 567 Reference this document 569 Preference limit 571 Value An integer page size. 573 Description Provide a limit on the number of components in the 574 response. 576 Reference this document 578 10.3. Link Relation Registrations 580 This document defines the following new iCalendar properties to be 581 added to the registry defined in [RFC5545]: 583 +========================+=============+=============+ 584 | Relation Name | Description | Reference | 585 +========================+=============+=============+ 586 | subscribe-caldav | Current | Section 8.2 | 587 +------------------------+-------------+-------------+ 588 | subscribe-caldav_auth | Current | Section 8.3 | 589 +------------------------+-------------+-------------+ 590 | subscribe-webdav-sync | Current | Section 8.4 | 591 +------------------------+-------------+-------------+ 592 | subscribe-enhanced_get | Current | Section 8.5 | 593 +------------------------+-------------+-------------+ 595 Table 1 597 11. Normative References 599 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 600 Requirement Levels", IETF RFC 2119, IETF RFC 2119, 601 DOI 10.17487/RFC2119, March 1997, 602 . 604 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 605 Procedures for Message Header Fields", IETF RFC 3864, 606 IETF RFC 3864, DOI 10.17487/RFC3864, September 2004, 607 . 609 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 610 Resource Identifier (URI): Generic Syntax", IETF RFC 3986, 611 IETF RFC 3986, DOI 10.17487/RFC3986, January 2005, 612 . 614 [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and 615 Scheduling Core Object Specification (iCalendar)", IETF 616 RFC 5545, IETF RFC 5545, DOI 10.17487/RFC5545, September 617 2009, . 619 [RFC5988] Nottingham, M., "Web Linking", IETF RFC 5988, IETF RFC 620 5988, DOI 10.17487/RFC5988, October 2010, 621 . 623 [RFC7240] Snell, J., "Prefer Header for HTTP", IETF RFC 7240, 624 IETF RFC 7240, DOI 10.17487/RFC7240, June 2014, 625 . 627 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 628 2119 Key Words", IETF RFC 8174, IETF RFC 8174, 629 DOI 10.17487/RFC8174, May 2017, 630 . 632 Appendix A. Open issues 634 Vary Ensure we get that right. 636 Appendix B. Change log 638 calext00 2019-06-05 MD 640 * First calext version 642 * Use Sync-Token header rather than parameter 644 v04 2019-03-07 MD 646 * Reference to RFC 6538 - WebDAV sync and RFC 7240 Prefer 648 * Go back to HEAD 650 * New Preference and parameters. 652 * Examples 654 * More text for extended get. Talk about deletions. 656 v01 2017-02-17 MD 657 * Add text about OPTIONS 659 * Add text abut read/write CalDAV 661 v00 2017-02-15 MD 663 * First pass 665 Author's Address 667 Michael Douglass 669 Email: mdouglass@bedework.com