idnits 2.17.1 draft-ietf-calext-subscription-upgrade-06.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 544 has weird spacing: '...ference subsc...' == Line 551 has weird spacing: '...ference this ...' == Line 553 has weird spacing: '...ference limit...' == Line 560 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 RFC5545, updated by this document, for RFC5378 checks: 2005-10-26) -- 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 (21 March 2022) is 767 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) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 6 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Douglass 3 Internet-Draft 21 March 2022 4 Updates: 5545 (if approved) 5 Intended status: Standards Track 6 Expires: 22 September 2022 8 Calendar subscription upgrades 9 draft-ietf-calext-subscription-upgrade-06 11 Abstract 13 This specification updates RFC5545 to add the value DELETED to the 14 STATUS property. 16 This specification also adds values to the Preferences Registry 17 defined in RFC7240 to add the subscribe-enhanced-get and limit 18 preferences and to the link relations directory defined in RFC8288. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at https://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on 22 September 2022. 37 Copyright Notice 39 Copyright (c) 2022 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 44 license-info) in effect on the date of publication of this document. 45 Please review these documents carefully, as they describe your rights 46 and restrictions with respect to this document. Code Components 47 extracted from this document must include Revised BSD License text as 48 described in Section 4.e of the Trust Legal Provisions and are 49 provided without warranty as described in the Revised BSD License. 51 Table of Contents 53 1. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 3 54 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 55 2.1. Terms and Definitions . . . . . . . . . . . . . . . . . . 3 56 3. Discovering alternative access methods . . . . . . . . . . . 4 57 4. Enhanced GET . . . . . . . . . . . . . . . . . . . . . . . . 4 58 4.1. General . . . . . . . . . . . . . . . . . . . . . . . . . 4 59 4.2. Deletions . . . . . . . . . . . . . . . . . . . . . . . . 5 60 4.3. Handling of invalid sync tokens . . . . . . . . . . . . . 5 61 4.4. Paging the response . . . . . . . . . . . . . . . . . . . 5 62 4.5. Caching of responses . . . . . . . . . . . . . . . . . . 6 63 4.6. Examples . . . . . . . . . . . . . . . . . . . . . . . . 6 64 5. Changes to the iCalendar specifications . . . . . . . . . . . 8 65 5.1. Redefined Status property . . . . . . . . . . . . . . . . 9 66 6. Header Field: Sync-Token . . . . . . . . . . . . . . . . . . 11 67 7. New Prefer header field preferences . . . . . . . . . . . . . 11 68 7.1. Preference subscribe-enhanced-get . . . . . . . . . . . . 11 69 7.2. Preference limit . . . . . . . . . . . . . . . . . . . . 11 70 8. Link relations . . . . . . . . . . . . . . . . . . . . . . . 11 71 8.1. General . . . . . . . . . . . . . . . . . . . . . . . . . 11 72 8.2. subscribe-caldav . . . . . . . . . . . . . . . . . . . . 11 73 8.3. subscribe-caldav-auth . . . . . . . . . . . . . . . . . . 12 74 8.4. subscribe-webdav-sync . . . . . . . . . . . . . . . . . . 12 75 8.5. subscribe-enhanced-get . . . . . . . . . . . . . . . . . 12 76 9. Security Considerations . . . . . . . . . . . . . . . . . . . 12 77 10. Privacy Considerations . . . . . . . . . . . . . . . . . . . 12 78 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 79 11.1. Sync-Token HTTP Header Field Registration . . . . . . . 13 80 11.2. Preference Registrations . . . . . . . . . . . . . . . . 13 81 11.3. Link Relation Registrations . . . . . . . . . . . . . . 13 82 12. Normative References . . . . . . . . . . . . . . . . . . . . 14 83 Appendix A. Open issues . . . . . . . . . . . . . . . . . . . . 15 84 Appendix B. Change log . . . . . . . . . . . . . . . . . . . . . 15 85 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 15 87 1. Acknowledgements 89 The author would also like to thank the members of the CalConnect 90 Calendar Sharing technical committee and the following individuals 91 for contributing their ideas and support: 93 Marten Gajda, Ken Murchison, Garry Shutler 95 The authors would also like to thank CalConnect, the Calendaring and 96 Scheduling Consortium, for advice with this specification. 98 2. Introduction 100 Currently clients subscribe to calendar feeds as an iCalendar file 101 which is often published as a resource accessible using the 102 unofficial 'webcal' scheme. 104 The only available option for updating that resource is the usual 105 HTTP polling of cached resources using Etags or Last-Modified. 107 There is the usual tension between clients wishing to see a timely 108 response to changes and servers not wishing to be overloaded by 109 frequent requests for possibly large amounts of data. 111 This specification introduces an approach whereby clients can 112 discover a more performant access method. Given the location of the 113 resource as an iCalendar file, the client can perfom a HEAD request 114 on the resource and inspect the returned headers which will offer a 115 number of alternative access methods. 117 Given that many clients and servers already support CalDAV this 118 provides an easy upgrade path for those clients. Additionally an 119 enhanced GET protocol is specified here to allow a light weight 120 implementation. 122 The use of subscription upgrade may help reduce load on servers, but 123 perhaps more importantly it allows mobile devices to use a more 124 efficient update mechanism reducing data transferred and presumably 125 improving battery life. 127 2.1. Terms and Definitions 129 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 130 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 131 "OPTIONAL" in this document are to be interpreted as described in BCP 132 14 [RFC2119] [RFC8174] when, and only when, they appear in all 133 capitals, as shown here. 135 Additionally, the rule for URI is included from [RFC3986]. 137 3. Discovering alternative access methods 139 The advertising of other access points is achieved through the use of 140 the LINK header as defined in [RFC8288]. New link relation types are 141 defined in this specification - each being associated with a protocol 142 or protocol subset. 144 These LINK headers will be delivered when a client carries out a HEAD 145 request targeting the URL of the resource. 147 EXAMPLE 149 This is an example of a HEAD request and the response from a server 150 that supports the enhanced GET method. 152 >> Request << 154 HEAD /caldata/events.ics HTTP/1.1 155 Host: example.com 156 Accept: text/calendar 158 >> Response << 160 HTTP/1.1 200 OK 161 Content-Length: xxxx 162 Link: ; 163 rel="subscribe-enhanced-get" 165 Note that the target for an upgraded service may be the same as for 166 the initial resource. 168 4. Enhanced GET 170 4.1. General 172 This is a lightweight protocol which allows simple clients to 173 efficiently discover and download changes in the targeted resource. 175 It has many similarities to WebDAV sync and for a server could be 176 implemented as an extension of the specification. 178 In this protocol the client MUST include the Prefer header field 179 preference "subscribe-enhanced-get". If a sync token is available it 180 is passed as a Sync-Token header field. 182 The resource is treated as a set of individual events each of which 183 may be updated or deleted separately. The client will first fetch 184 the entire iCalendar file. On subsequent requests it uses the Prefer 185 header field and a Sync-Token header field to indicate that it wants 186 a set of changes since the last fetch. 188 If no Sync-Token header field is supplied the server SHOULD respond 189 with a full set of data. Otherwise, if the token is valid, it SHOULD 190 return with a set of changed entities. 192 In both cases the server should set the Preference-Applied header 193 field and a new Sync-Token header field value. 195 4.2. Deletions 197 When an entity (VEVENT, VTODO or other valid top-level component) is 198 deleted from the source data the server needs to be able to inform a 199 client of the deletion. This specification introduces a new value 200 for the STATUS property of DELETED. 202 On the first enhanced GET after the entity has been deleted a 203 skeleton, but valid, entity will be returned with STATUS: DELETED. 204 The receiving client is free to remove the entity or update its 205 STATUS property. 207 On subsequent fetches the entity will not be returned. 209 4.3. Handling of invalid sync tokens 211 When a server receives an invalid token it MUST return a 409 status 212 (Conflict). The server MAY choose to return an error message in the 213 body. 215 The client SHOULD respond to this error by restarting the interaction 216 from scratch, i.e. retrieve the full set of data then poll for 217 updates. 219 4.4. Paging the response 221 A client may explicitly request a limit on the size of the response 222 by specifying the Prefer header field preference "limit=n" where n is 223 the number of components. 225 When a server receives a request specifying such a limit it SHOULD 226 limit the response to that number of components. If the limit causes 227 a truncation in the response the server should respond with a 228 Preference-Applied header specifying the limit that was applied and 229 return a sync token which may be used to retrieve the next batch of 230 data. 232 This allows the client to immediately resubmit a request for the next 233 batch using the updated token. 235 A server MAY choose to limit the response size. The behavior SHOULD 236 be as if the client had provided a preference for that size - 237 allowing the client to retrieve the full set of data in batches. 239 4.5. Caching of responses 241 To enable proper caching of responses the server SHOULD provide a 242 VARY header field in responses that names the Prefer and Sync-Token 243 header fields along with any other that are appropriate. 245 Clients should order the preferences as following so that identical 246 responses can be identified: 248 * subscribe-enhanced-get 250 * limit 252 4.6. Examples 254 EXAMPLE 1 256 This is an example of the initial request and response from a server 257 that supports the enhanced GET method. Note the use of the Vary 258 header so a caching proxy can key off the client's Sync-Token and 259 preference. 261 >> Request << 263 GET /events.ics HTTP/1.1 264 Host: example.com 265 Accept: text/calendar 266 Prefer: subscribe-enhanced-get 268 >> Response << 270 HTTP/1.1 200 OK 271 Content-Length: xxxx 272 Sync-Token: "data:,1234567" 273 Preference-Applied: subscribe-enhanced-get 274 Vary: Prefer, Sync-Token 276 BEGIN:VCALENDAR: 277 ? /* full feed */ 278 END:VCALENDAR 280 EXAMPLE 2 282 This is an example of the subsequent request and response when no 283 changes have occurred. 285 >> Request << 287 GET /events.ics HTTP/1.1 288 Host: example.com 289 Accept: text/calendar 290 Prefer: subscribe-enhanced-get 291 Sync-Token: "data:,1234567" 293 >> Response << 295 HTTP/1.1 304 Not Modified 296 Content-Length: 0 297 Sync-Token: "data:,1234567" 298 Preference-Applied: subscribe-enhanced-get 299 Vary: Prefer, Sync-Token 301 EXAMPLE 3 303 This is an example of the subsequent request and response for an old 304 or invalid token. 306 >> Request << 308 GET /events.ics HTTP/1.1 309 Host: example.com 310 Accept: text/calendar 311 Sync-Token: "data:,1234567" 312 Prefer: subscribe-enhanced-get 314 >> Response << 316 HTTP/1.1 409 Conflict 317 Content-Length: xxxx 318 Preference-Applied: subscribe-enhanced-get 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 5. Changes to the iCalendar specifications 348 This specification updates [RFC5545] to add the value DELETED to the 349 STATUS property. 351 5.1. Redefined Status property 353 Property name STATUS 355 Purpose This property defines the overall status or confirmation for 356 the calendar component. 358 Value Type TEXT 360 Property Parameters IANA and non-standard property parameters can be 361 specified on this property. 363 Conformance This property can be specified once in "VEVENT", 364 "VTODO", or "VJOURNAL" calendar components. 366 Description In a group-scheduled calendar component, the property is 367 used by the "Organizer" to provide a confirmation of the event to 368 the "Attendees". For example in a "VEVENT" calendar component, 369 the "Organizer" can indicate that a meeting is tentative, 370 confirmed, or cancelled. In a "VTODO" calendar component, the 371 "Organizer" can indicate that an action item needs action, is 372 completed, is in process or being worked on, or has been 373 cancelled. In a "VJOURNAL" calendar component, the "Organizer" 374 can indicate that a journal entry is draft, final, or has been 375 cancelled or removed. 377 Format Definition 379 This property is defined by the following notation: 381 status = "STATUS" statparam ":" statvalue CRLF 383 statparam = *(";" other-param) 385 statvalue = (statvalue-event 386 / statvalue-todo 387 / statvalue-jour) 389 statvalue-event = "TENTATIVE" ;Indicates event is tentative. 390 / "CONFIRMED" ;Indicates event is definite. 391 / "CANCELLED" ;Indicates event was cancelled. 392 / "DELETED" ;Indicates event was deleted. 393 ;Status values for a "VEVENT" 395 statvalue-todo = "NEEDS-ACTION" ;Indicates to-do needs action. 396 / "COMPLETED" ;Indicates to-do completed. 397 / "IN-PROCESS" ;Indicates to-do in process of. 398 / "CANCELLED" ;Indicates to-do was cancelled. 399 / "DELETED" ;Indicates to-do was deleted. 400 ;Status values for "VTODO". 402 statvalue-jour = "DRAFT" ;Indicates journal is draft. 403 / "FINAL" ;Indicates journal is final. 404 / "CANCELLED" ;Indicates journal is removed. 405 / "DELETED" ;Indicates journal was deleted. 406 ;Status values for "VJOURNAL". 408 Example 410 EXAMPLE 1 412 The following is an example of this property for a "VEVENT" calendar 413 component: 415 STATUS:TENTATIVE 417 EXAMPLE 2 419 The following is an example of this property for a "VTODO" calendar 420 component: 422 STATUS:NEEDS-ACTION 424 EXAMPLE 3 426 The following is an example of this property for a "VJOURNAL" 427 calendar component: 429 STATUS:DRAFT 431 6. Header Field: Sync-Token 433 This specification defines a new header field Sync-Token for use by 434 the enhanced GET method. 436 Accept = DQUOTE URI DQUOTE 438 The value MUST be a URI. This will generally be a data URI 439 representing an opaque token. Client MUST not attempt to interpret 440 the data URI value. 442 EXAMPLE 444 This is an example of the Sync-Token header field: 446 Sync-Token: "data:,1234567" 448 7. New Prefer header field preferences 450 7.1. Preference subscribe-enhanced-get 452 This indicates that the client expects the server to handle the GET 453 method according to the specifications for enhanced get. 455 pref-subscribe-enhanced-get = "subscribe-enhanced-get" 457 7.2. Preference limit 459 This preference parameter provides a limit on the number of 460 components returned for enhanced get. 462 pref-limit = "limit" BWS "=" BWS 1*DIGIT 464 8. Link relations 466 8.1. General 468 This clause defines a number of new link relations required to 469 facilitate subscription upgrades. 471 8.2. subscribe-caldav 473 This specifies an access point which is a full implementation of 474 caldav but requires no authentication. The end point allows the full 475 range of reports as defined by the CalDAV specification. 477 The client MUST follow the specification to determine exactly what 478 operations are allowed on the access point - for example to determine 479 if DAV:sync-collection is supported. 481 The URL MAY include some form of token to allow write access to the 482 targeted collection. The client must check its permissions to 483 determine whether or not it has been granted write access. 485 8.3. subscribe-caldav-auth 487 This specifies an access point which is a full implementation of 488 caldav and requires authentication. This may allow read-write access 489 to the resource. 491 The client MUST follow the specification to determine exactly what 492 operations are allowed on the access point - for example to determine 493 if DAV:sync-collection is supported. 495 8.4. subscribe-webdav-sync 497 This specifies an access point which supports only webdav sync. 499 This allows the client to issue a DAV:sync-collection report on the 500 resource to obtain updates. 502 The client MUST follow that specification. 504 8.5. subscribe-enhanced-get 506 This specifies an access point which supports something new. 508 The client MUST follow that specification. 510 9. Security Considerations 512 Applications using these properties need to be aware of the risks 513 entailed in using the URIs provided as values. See [RFC3986] for a 514 discussion of the security considerations relating to URIs. 516 10. Privacy Considerations 518 Properties with a "URI" value type can expose their users to privacy 519 leaks as any network access of the URI data can be tracked. Clients 520 SHOULD NOT automatically download data referenced by the URI without 521 explicit instruction from users. This specification does not 522 introduce any additional privacy concerns beyond those described in 523 [RFC5545]. 525 11. IANA Considerations 527 11.1. Sync-Token HTTP Header Field Registration 529 This specification updates the "Message Headers" registry entry for 530 "Sync-Token" in [RFC3864] to refer to this document. 532 Header Field Name: Sync-Token 533 Protocol: http 534 Status: standard 535 Reference: 537 Figure 1 539 11.2. Preference Registrations 541 The following preferences have been added to the HTTP Preferences 542 Registry defined in [RFC7240] 544 Preference subscribe-enhanced-get 546 Value None. 548 Description Marks the interaction as enhanced get and provides the 549 optional sync-token and page size. 551 Reference this document 553 Preference limit 555 Value An integer page size. 557 Description Provide a limit on the number of components in the 558 response. 560 Reference this document 562 11.3. Link Relation Registrations 564 The following link relation values have been added to the Reference 565 Types Registry defined in Section 6.2.2 of [RFC8288]: 567 +========================+=============+=============+ 568 | Relation Name | Description | Reference | 569 +========================+=============+=============+ 570 | subscribe-caldav | Current | Section 8.2 | 571 +------------------------+-------------+-------------+ 572 | subscribe-caldav_auth | Current | Section 8.3 | 573 +------------------------+-------------+-------------+ 574 | subscribe-webdav-sync | Current | Section 8.4 | 575 +------------------------+-------------+-------------+ 576 | subscribe-enhanced_get | Current | Section 8.5 | 577 +------------------------+-------------+-------------+ 579 Table 1 581 12. Normative References 583 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 584 Requirement Levels", RFC 2119, RFC 2119, 585 DOI 10.17487/RFC2119, March 1997, 586 . 588 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 589 Procedures for Message Header Fields", RFC 3864, RFC 3864, 590 DOI 10.17487/RFC3864, September 2004, 591 . 593 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 594 Resource Identifier (URI): Generic Syntax", RFC 3986, 595 RFC 3986, DOI 10.17487/RFC3986, January 2005, 596 . 598 [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and 599 Scheduling Core Object Specification (iCalendar)", RFC 600 5545, RFC 5545, DOI 10.17487/RFC5545, September 2009, 601 . 603 [RFC7240] Snell, J., "Prefer Header for HTTP", RFC 7240, RFC 7240, 604 DOI 10.17487/RFC7240, June 2014, 605 . 607 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 608 2119 Key Words", RFC 8174, RFC 8174, DOI 10.17487/RFC8174, 609 May 2017, . 611 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, RFC 8288, 612 DOI 10.17487/RFC8288, October 2017, 613 . 615 Appendix A. Open issues 617 Vary Ensure we get that right. 619 Appendix B. Change log 621 calext00 2019-06-05 MD 623 * First calext version 625 * Use Sync-Token header rather than parameter 627 v04 2019-03-07 MD 629 * Reference to RFC 6538 - WebDAV sync and RFC 7240 Prefer 631 * Go back to HEAD 633 * New Preference and parameters. 635 * Examples 637 * More text for extended get. Talk about deletions. 639 v01 2017-02-17 MD 641 * Add text about OPTIONS 643 * Add text abut read/write CalDAV 645 v00 2017-02-15 MD 647 * First pass 649 Author's Address 651 Michael Douglass 652 Email: mdouglass@bedework.com