idnits 2.17.1 draft-reschke-http-etag-on-write-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 17. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 852. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 863. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 870. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 876. 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 ([2], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. -- The draft header indicates that this document updates RFC2616, but the abstract doesn't seem to directly say this. It does mention RFC2616 though, so this could be OK. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). (Using the creation date from RFC2616, updated by this document, for RFC5378 checks: 1997-10-16) -- 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 (November 26, 2006) is 6353 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: Experimental ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) == Outdated reference: A later version (-17) exists of draft-ietf-atompub-protocol-11 -- Obsolete informational reference (is this intentional?): RFC 2518 (Obsoleted by RFC 4918) Summary: 3 errors (**), 0 flaws (~~), 3 warnings (==), 10 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Reschke 3 Internet-Draft greenbytes 4 Updates: 2616 (if approved) November 26, 2006 5 Intended status: Experimental 6 Expires: May 30, 2007 8 The Hypertext Transfer Protocol (HTTP) Entity Tag ("ETag") 9 Response Header in Write Operations 10 draft-reschke-http-etag-on-write-04 12 Status of this Memo 14 By submitting this Internet-Draft, each author represents that any 15 applicable patent or other IPR claims of which he or she is aware 16 have been or will be disclosed, and any of which he or she becomes 17 aware will be disclosed, in accordance with Section 6 of BCP 79. 19 Internet-Drafts are working documents of the Internet Engineering 20 Task Force (IETF), its areas, and its working groups. Note that 21 other groups may also distribute working documents as Internet- 22 Drafts. 24 Internet-Drafts are draft documents valid for a maximum of six months 25 and may be updated, replaced, or obsoleted by other documents at any 26 time. It is inappropriate to use Internet-Drafts as reference 27 material or to cite them other than as "work in progress." 29 The list of current Internet-Drafts can be accessed at 30 http://www.ietf.org/ietf/1id-abstracts.txt. 32 The list of Internet-Draft Shadow Directories can be accessed at 33 http://www.ietf.org/shadow.html. 35 This Internet-Draft will expire on May 30, 2007. 37 Copyright Notice 39 Copyright (C) The IETF Trust (2006). 41 Abstract 43 The Hypertext Transfer Protocol (HTTP) specifies a state identifier, 44 called "Entity Tag", to be returned in the "ETag" response header. 45 However, the description of this header for write operations such as 46 PUT is incomplete, and has caused confusion among developers and 47 protocol designers, and potentially interoperability problems. 49 This document explains the problem in detail and suggests both a 50 clarification for a revision to the HTTP/1.1 specification (RFC2616) 51 and a new header for use in responses, making HTTP entity tags more 52 useful for user agents that want to avoid round-trips to the server 53 after modifying a resource. 55 Editorial Note (To be removed by RFC Editor before publication) 57 Distribution of this document is unlimited. Please send comments to 58 the Hypertext Transfer Protocol (HTTP) mailing list at 59 ietf-http-wg@w3.org [1], which may be joined by sending a message 60 with subject "subscribe" to ietf-http-wg-request@w3.org [2]. 62 Discussions of the HTTP working group are archived at 63 . 65 XML versions, latest edits and the issues list for this document are 66 available from . 69 Table of Contents 71 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 72 1.1. Questions out of Scope . . . . . . . . . . . . . . . . . . 4 73 1.2. The Interoperability Problem . . . . . . . . . . . . . . . 4 74 1.3. Analysis of RFC2616's Definitions . . . . . . . . . . . . 6 75 1.4. Prior Work . . . . . . . . . . . . . . . . . . . . . . . . 7 76 2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 8 77 3. Clarifications on the Behavior of the 'ETag' Response 78 Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 79 4. The 'Entity-Transform' Header . . . . . . . . . . . . . . . . 9 80 4.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 10 81 5. How This Helps . . . . . . . . . . . . . . . . . . . . . . . . 10 82 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 83 7. Security Considerations . . . . . . . . . . . . . . . . . . . 11 84 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 85 8.1. Normative References . . . . . . . . . . . . . . . . . . . 11 86 8.2. Informative References . . . . . . . . . . . . . . . . . . 11 87 Appendix A. Use Cases . . . . . . . . . . . . . . . . . . . . . . 12 88 A.1. Simple Authoring . . . . . . . . . . . . . . . . . . . . . 12 89 A.2. Simple Authoring, with Entity-Transform header . . . . . . 14 90 A.3. Setting both Content and Metadata . . . . . . . . . . . . 15 91 A.4. Setting both Content and Metadata, new style . . . . . . . 17 92 Appendix B. Change Log (to be removed by RFC Editor before 93 publication) . . . . . . . . . . . . . . . . . . . . 18 94 B.1. Since draft-reschke-http-etag-on-write-00 . . . . . . . . 18 95 B.2. Since draft-reschke-http-etag-on-write-01 . . . . . . . . 18 96 B.3. Since draft-reschke-http-etag-on-write-02 . . . . . . . . 19 97 B.4. Since draft-reschke-http-etag-on-write-03 . . . . . . . . 19 98 Appendix C. Open issues (to be removed by RFC Editor prior to 99 publication) . . . . . . . . . . . . . . . . . . . . 19 100 C.1. edit . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 101 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 19 102 Intellectual Property and Copyright Statements . . . . . . . . . . 20 104 1. Introduction 106 The Hypertext Transfer Protocol (HTTP) specifies a state identifier, 107 called "Entity Tag", to be returned in the "ETag" response header 108 (see [RFC2616], Section 14.19). However, the description of this 109 header for write operations such as PUT is incomplete, and has caused 110 confusion among developers and protocol designers, and potentially 111 interoperability problems. 113 This document explains the problem in detail and suggests both a 114 clarification for a revision to [RFC2616] and a new header for use in 115 responses, making HTTP entity tags more useful for user agents that 116 want to avoid round-trips to the server after modifying a resource. 118 1.1. Questions out of Scope 120 Note that there is a related problem: modifying content-negotiated 121 resources. Here the consensus seems to be simply not to do it. 122 Instead, the origin server should reveal specific URIs of content 123 that is not content-negotiated in the Content-Location response 124 header ([RFC2616], Section 14.14), and user agents should use this 125 more specific URI for authoring. Thus, the remainder of this 126 document will focus on resources for which no content negotiation 127 takes place. 129 Another related question is the usability of the weak entity tags for 130 authoring (see [RFC2616], Section 13.3.3). Although this document 131 focuses on the usage of strong entity tags, it is believed that the 132 changes suggested in this document could be applied to weak entity 133 tags as well. 135 1.2. The Interoperability Problem 137 For a long time, nobody realized that there was a problem at all, or 138 those who realized preferred to ignore it. 140 Server implementers added code that would return the new value of the 141 "ETag" header in a response to a successful PUT request. After all, 142 the client could be interested in it. 144 User agent developers in turn were happy to get a new "ETag" value, 145 saving a subsequent HEAD request to retrieve the new entity tag. 147 However, at some point of time, potentially during a Web Distributed 148 Authoring and Versioning (WebDAV, [RFC2518]) interoperability event, 149 client programmers asked server programmers to always return "ETag" 150 headers upon PUT, never ever to change the entity tag without "good 151 reason", and - by the way - always to guarantee that the server 152 stores the new content octet-by-octet. 154 From the perspective of client software that wants to treat an HTTP 155 server as a file system replacement, this makes a lot of sense. 156 After all, when one writes to a file one usually expects the file 157 system to store what was written, and not to unexpectedly change the 158 contents. 160 However, in general, an HTTP server is not a file system replacement. 161 There may be some that have been designed that way, and some that 162 expose some parts of their namespace that have this quality. But in 163 general, HTTP server implementers have a lot of freedom in how 164 resources are implemented. Indeed, this flexibility is one of the 165 reasons for HTTP's success, allowing it to be used for a wide range 166 of tasks, of which replacing file systems is just one (and not 167 necessarily the most interesting one). 169 In particular: 171 o A server may not store a resource as a binary object - in this 172 case, the representation returned in a subsequent GET request may 173 just be similar, but not identical to what was written. Good 174 examples are servers that use HTTP to access XML data ([XCAP]), 175 Calendaring data ([CALDAV]) or newsfeed data ([APP]). 177 o A server may change the data being written on purpose, while it is 178 being written. Examples that immediately come to mind are keyword 179 substitution in a source control system, or filters that remove 180 potentially insecure parts out of HTML pages. 182 Furthermore: 184 o An "unrelated" method such as WebDAV's PROPPATCH (see [RFC2518], 185 Section 8.2) may affect the entity body and therefore the entity 186 tag in an unexpected way, because the server stores some or all of 187 the WebDAV properties inside the entity body (for instance, GPS 188 information inside a JPG image file). 190 As long as servers store the content octet-by-octet, and return 191 exactly what the client wrote, there is no problem at all. 193 Things get more interesting when a server does change the content, 194 such as in the "simple authoring" example given in Appendix A.1. 195 Here, the server does change the content upon writing to the 196 resource, yet no harm is done, because the final state of the 197 resource on the server does not depend on the client being aware of 198 that. 200 All of the content rewriting examples mentioned above have this 201 quality: the client can safely continue to edit the entity it sent, 202 because the result of the transformation done by the server will be 203 the same in the end. Formally, if we call the server-side 204 transformation "t", the initial content "c", and the client-side 205 editing steps "e1" and "e2", then 207 t(e2(e1(c))) = t(e2(t(e1(c)))) 209 e.g., it is irrelevant whether the client obtained the current entity 210 body before doing its second edit. 212 [[example.for.non.safe.rewrite: Question: does anybody know a real- 213 world example for server-side content rewriting where the above is 214 not true? --julian.reschke@greenbytes.de]] 216 Problems will only occur if the client uses the entity body it sent, 217 and the entity tag it obtained in return, in subsequent requests that 218 only transfer part of the entity body, such as GET or PUT requests 219 using the "Range" request header (see [RFC2616], Section 14.35). 221 Furthermore, some clients need to expose the actual contents to the 222 end user. These clients will have to ensure that they really have 223 the current representation. 225 Entity bodies (and thus entity tags) changing due to side effects of 226 seemingly unrelated requests are indeed a problem, as demonstrated in 227 Appendix A.3, and this specification proposes a way to resolve this 228 in Section 3. 230 1.3. Analysis of RFC2616's Definitions 232 There are several places in the HTTP/1.1 specification ([RFC2616]) 233 mentioning the "ETag" response header. 235 Let us start with the header definition in Section 14.19: 237 The ETag response-header field provides the current value of the 238 entity tag for the requested variant. Sections 14.24, 14.26 and 239 14.44 describe the headers used with entity tags. The entity tag 240 MAY be used for comparison with other entities from the same 241 resource (see Section 13.3.3). 243 The meaning of a "response-header" in turn is defined in Section 6.2: 245 The response-header fields allow the server to pass additional 246 information about the response which cannot be placed in the 247 Status-Line. These header fields give information about the 248 server and about further access to the resource identified by the 249 Request-URI. 251 The "ETag" response header itself is mentioned mainly in the context 252 of cache validation, such as in Section 13.3.2. What is missing is a 253 coherent description on how the origin server can notify the user- 254 agent when the entity tag changes as result of a write operation, 255 such as PUT. 257 Indeed, the definition of the 201 Created status code mentions entity 258 tags (Section 10.2.2): 260 A 201 response MAY contain an ETag response header field 261 indicating the current value of the entity tag for the requested 262 variant just created, see Section 14.19. 264 The "ETag" response header is mentioned again in the definition of 265 206 Partial Content (Section 10.2.7) and 304 Not Modified (Section 266 10.3.5), but notably missing are statements about other 2xx series 267 status codes that can occur upon a successful PUT operation, such as 268 200 OK (Section 10.2.1) and 204 No Content (Section 10.2.5). 270 Summarizing, the specification is a bit vague about what an ETag 271 response header upon a write operation means, but this problem is 272 somewhat mitigated by the precise definition of a response header. A 273 proposal for enhancing [RFC2616] in this regard is made in Section 3 274 below. 276 1.4. Prior Work 278 While working on the revision of [RFC2518], the IETF WebDAV working 279 group realized that this is a generic problem that needs attention 280 independently of WebDAV. An initial attempt was made with 281 [draft-whitehead-http-etag] in February 2006, but no progress was 282 made since. 284 At the time of this writing in November 2006, two specifications 285 based on HTTP were either under IESG review or just approved by the 286 IESG, taking two opposite approaches: 288 o Section 8.5 of [XCAP] makes it a MUST-level requirement to return 289 an entity tag upon PUT, even though the very nature of an XCAP 290 server will cause it to rewrite contents (due to its XML-based 291 storage). 293 o Section 5.3.4 of [CALDAV] explicitly forbids ("MUST NOT") 294 returning an entity tag upon PUT if the content was rewritten. 296 In essence, this makes it impossible to implement an HTTP resource 297 that conforms to both specifications. Due to the differing use cases 298 of XCAP and CalDAV, this may not be a problem in practice, but the 299 disagreement in itself is scary. Publication of these specifications 300 on the standards track will make it much harder for future protocols 301 to deal with this topic in a meaningful way (comments were sent 302 during IETF Last Call for CalDAV, see 303 ). 305 2. Notational Conventions 307 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL-NOT", 308 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 309 document are to be interpreted as described in [RFC2119]. 311 The terminology used here follows and extends that in the HTTP 312 specification [RFC2616], notably the augmented Backus-Naur Form (BNF) 313 defined in Section 2.1 of that document. 315 3. Clarifications on the Behavior of the 'ETag' Response Header 317 This section describes a minimal change to [RFC2616], proposed in . 320 At the end of Section 10.2 of [RFC2616], add: 322 The response MAY contain an ETag response header field indicating 323 the current value of the entity tag (Section 14.19) for the 324 requested variant. The value SHOULD be the same as the one 325 returned upon a subsequent HEAD request addressing the same 326 variant. 328 In Section 10.2.1 of [RFC2616], remove: 330 A 201 response MAY contain an ETag response header field 331 indicating the current value of the entity tag for the requested 332 variant just created, see Section 14.19. 334 In essence, this moves the statement about entity tags in write 335 operations from the specific case of status 201 Created into the more 336 generic description of the 2xx series status codes. 338 [[rcf2616.enhancements: Should "requested variant" be clarified in 339 the context of write operations? --julian.reschke@greenbytes.de]] 341 4. The 'Entity-Transform' Header 343 The 'Entity-Transform' entity header provides information about 344 whether a transformation has been applied to an entity body. 346 When used in an HTTP request, its meaning is undefined. In an HTTP 347 response, it provides information whether the server has applied a 348 transformation when the entity was stored last. 350 In general, entity headers may be stored in intermediates. The main 351 use of this header however applies to the HTTP PUT method, of which 352 by default the results are not cacheable (see [RFC2616], Section 353 9.6). In addition, the value format is defined so that a client can 354 reliably detect whether the information is fresh. 356 Format: 358 Entity-Transform = "Entity-Transform" ":" entity-transform-spec 359 entity-transform-spec = entity-transform-keyword SP entity-tag 360 entity-transform-keyword = "identity" | "unspecified"| token 362 entity-tag = 363 token = 365 The entity-tag specifies the entity body to which this information 366 applies. 368 An entity-transform-keyword of "identity" specifies that the origin 369 server has stored the entity octet-by-octet, thus the user agent MAY 370 use a local copy of the entity body with the given entity-tag for 371 subsequent requests that rely on octet-by-octet identity (such as a 372 PUT with "Range" request header). 374 Both the absence of this response header and any entity-transform- 375 keyword value other than "identity" specify that the origin server 376 may have transformed the entity before storage, thus a subsequent 377 retrieval will not necessarily return an exact copy of the submitted 378 entity. 380 Note: usage of keywords other than "identity" or "unspecified" is 381 reserved for future revisisions of this specification. 383 Further note that the definition of the "identity" keyword is 384 independant of the type of entity-tag. Thus, when "identity" is 385 returned with a weak entity-tag, the client can indeed rely on 386 octet-by-octet identity. 388 4.1. Examples 390 Content was stored octet-by-octet: 392 HTTP/1.1 200 OK 393 ETag: "1" 394 Entity-Transform: identity "1" 396 Content was transformed: 398 HTTP/1.1 200 OK 399 ETag: "2" 400 Entity-Transform: unspecified "2" 402 Response containing a stale "Entity-Transform" header: 404 HTTP/1.1 200 OK 405 ETag: "3" 406 Entity-Transform: unspecified "2" 408 Note that in this case the newly assigned entity tag and the entity 409 tag returned in "Entity-Transform" do not match, thus the client is 410 aware that the header value is stale and can't be used. 412 5. How This Helps 414 The clarification of [RFC2616] (see Section 3) makes it clear that 415 user agents can use "ETag" headers obtained in write operations, as 416 long as they do not require octet-by-octet identity. In particular, 417 a new entity tag can be returned for any method, such as a WebDAV 418 PROPPATCH (see [RFC2518], Section 8.2). This helps dealing with the 419 problem described in Appendix A.3. See Appendix A.4 for details. 421 The addition of the "Entity-Transform" header (see Section 4) enables 422 origin servers to signal that they stored an exact copy of the 423 content, thus allowing clients not to refetch the content. Note that 424 by default (in absence of the response header), a client can not make 425 any assumptions about the server's behavior in this regard. Thus 426 clients will only benefit from new servers explicitly setting the new 427 header. 429 6. IANA Considerations 431 This document specifies the new HTTP header listed below. 433 Header field name: Entity-Transform 435 Applicable protocol: http 437 Status: informational 439 Author/Change controller: IETF 441 Specification document: Section 4 of this specification 443 7. Security Considerations 445 This specification introduces no new security considerations beyond 446 those discussed in Section 15 of [RFC2616]. 448 8. References 450 8.1. Normative References 452 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 453 Requirement Levels", BCP 14, RFC 2119, March 1997. 455 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 456 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 457 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 459 8.2. Informative References 461 [APP] Gregorio, J., Ed. and B. de hOra, Ed., "The Atom 462 Publishing Protocol", draft-ietf-atompub-protocol-11 (work 463 in progress), October 2006. 465 [CALDAV] Daboo, C., Desruisseaux, B., and L. Dusseault, 466 "Calendaring Extensions to WebDAV (CalDAV)", 467 draft-dusseault-caldav-15 (work in progress), 468 September 2006. 470 [HTML] Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01 471 Specification", W3C REC-html401-19991224, December 1999, 472 . 474 [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D. 475 Jensen, "HTTP Extensions for Distributed Authoring -- 476 WEBDAV", RFC 2518, February 1999. 478 [XCAP] Rosenberg, J., "The Extensible Markup Language (XML) 479 Configuration Access Protocol (XCAP)", 480 draft-ietf-simple-xcap-12 (work in progress), 481 October 2006. 483 [draft-whitehead-http-etag] 484 Whitehead, J., "Design Considerations for State 485 Identifiers in HTTP and WebDAV", 486 draft-whitehead-http-etag-00 (work in progress), 487 February 2006. 489 (As of November 2006, there didn't appear to be any 490 activity related to this draft.) 492 URIs 494 [1] 496 [2] 498 Appendix A. Use Cases 500 A.1. Simple Authoring 502 Let us consider a server not having the quality of preserving octet- 503 by-octet identity, for instance because of SVN-style keyword 504 expansion in text content (). 507 In this case, the client has previously retrieved the representation 508 for , and the server has returned the ETag 509 "1": 511 >> Request (1) 513 GET /test HTTP/1.1 514 Host: example.com 516 >> Response (1) 518 HTTP/1.1 200 OK 519 Content-Type: text/plain 520 ETag: "1" 522 # $Revision: 1 $ 523 Sample text. 525 The client now wants to update the resource. To avoid overwriting 526 somebody else's changes, it submits the PUT request with the HTTP 527 "If-Match" request header (see [RFC2616], Section 14.24): 529 >> Request (2) 531 PUT /test HTTP/1.1 532 Host: example.com 533 If-Match: "1" 535 # $Revision: 1 $ 536 New sample text. 538 If the resource was modified in the meantime, the server will reject 539 the request with a 412 Precondition Failed status: 541 >> Response (2a) 543 HTTP/1.1 412 Precondition Failed 544 Content-Type: text/plain 546 Precondition Failed: entity tag supplied in If-Match request header 547 did not match current. 549 In this case, the client usually has take care of merging the changes 550 made locally with those made on the server ("Merge Conflict"). 552 If there was no overlapping update, the server will execute the 553 request and return a new entity tag: 555 >> Response (2b) 557 HTTP/1.1 200 OK 558 Content-Type: text/plain 559 ETag: "2" 561 Note however, that at this point the client knows the new entity tag, 562 but doesn not know the current representation, which will have been 563 updated by the server to: 565 # $Revision: 2 $ 566 New sample text. 568 What seems to be a problem at first may not be a real problem in 569 practice. Let us assume that the client continues editing the 570 resource, using the entity tag obtained from the previous request, 571 but editing the entity it last sent: 573 >> Request (3) 575 PUT /test HTTP/1.1 576 Host: example.com 577 If-Match: "2" 579 # $Revision: 1 $ 580 A third attempt. 582 Assuming there was no overlapping update, the PUT request will 583 succeed: 585 >> Response (3) 587 HTTP/1.1 200 OK 588 Content-Type: text/plain 589 ETag: "3" 591 Note that the only problem here is that the client doesn't have an 592 exact copy of the entity it is editing. However, from the server's 593 point of view this is entirely irrelevant, because the "Revision" 594 keyword will be automatically updated upon every write anyway. 596 In any case, the final contents will be: 598 # $Revision: 3 $ 599 A third attempt. 601 A.2. Simple Authoring, with Entity-Transform header 603 In the example above (Appendix A.1, Response 2b), the server returns 604 an ETag response header upon PUT, although the content actually was 605 rewritten due to keyword substitution. 607 A server implementing this specification would instead respond with: 609 >> Response (2c) 611 HTTP/1.1 200 OK 612 Content-Type: text/plain 613 ETag: "2" 614 Entity-Transform: unspecified "2" 616 This indicates that the content that was sent is not octet-by-octet 617 identical to what a subsequent GET request would retrieve. It is 618 then up to the client to decide whether it wants to re-fetch the 619 content before continuing edits. 621 A.3. Setting both Content and Metadata 623 In this example, the server exposes data extracted from the HTML 624 element ([HTML], Section 7.4.2) as a custom WebDAV property 625 ([RFC2518], Section 4), allowing both read and write access. 627 In the first step, the client obtains the current representation for 628 <http://example.com/test.html>: 630 >> Request (1) 632 GET /test.html HTTP/1.1 633 Host: example.com 635 >> Response (1) 637 HTTP/1.1 200 OK 638 Content-Type: text/html 639 ETag: "A" 641 <html> 642 <head> 643 </head> 644 <body> 645 </body> 646 </html> 648 Next, it adds one paragraph to the <body> element, and gets back a 649 new entity tag: 651 >> Request (2) 653 PUT /test.html HTTP/1.1 654 Host: example.com 655 If-Match: "A" 657 <html> 658 <head> 659 </head> 660 <body> 661 <p>First paragraph.</p> 662 </body> 663 </html> 665 >> Response (2) 667 HTTP/1.1 200 OK 668 ETag: "B" 669 Next, the client sets a custom "title" property (see [RFC2518], 670 Section 8.2): 672 >> Request (3) 674 PROPPATCH /test.html HTTP/1.1 675 Host: example.com 676 Content-Type: application/xml 678 <proppatch xmlns="DAV:"> 679 <set> 680 <prop> 681 <title xmlns="http://ns.example.org/" 682 >A sample document 683 684 685 687 >> Response (3) 689 HTTP/1.1 207 Multi-Status 690 Content-Type: application/xml 692 693 694 /test.html 695 696 697 698 </prop> 699 <status>HTTP/1.1 2OO OK</status> 700 </propstat> 701 </response> 702 </multistatus> 704 The server knows how to propagate property changes into the HTML 705 content, so it updates the entity by adding an HTML title document 706 accordingly. This causes the entity tag changing to "C". 708 The new entity body is shown below, but the client does not realize 709 that it did change at all. 711 <html> 712 <head> 713 <title>A sample document 714 715 716

First paragraph.

717 718 720 A subsequent attempt by the client to update the entity body will 721 fail, unless it realizes that changing WebDAV properties may affect 722 the entity as well. In this case, it would have had to get the 723 current entity tag before proceeding. Of course, this introduces an 724 additional round-trip, and a timing window during which overlapping 725 updates by other clients would go unnoticed. 727 Note that a client would be affected by this behaviour even in the 728 presence of an exclusive WebDAV write lock (see [RFC2518], Section 729 7). 731 A.4. Setting both Content and Metadata, new style 733 Below we repeat the example from above (Appendix A.3), but here the 734 origin server returns entity tags for all write operations, and the 735 user agent knows how to deal with them. That is, both take advantage 736 of what [RFC2616] already allows. 738 >> Request (3) 740 PROPPATCH /test.html HTTP/1.1 741 Host: example.com 742 Content-Type: application/xml 744 745 746 747 748 A sample document 749 750 751 752 753 >> Response (3) 755 HTTP/1.1 207 Multi-Status 756 Content-Type: application/xml 757 ETag: "C" 759 760 761 /test.html 762 763 764 765 </prop> 766 <status>HTTP/1.1 2OO OK</status> 767 </propstat> 768 </response> 769 </multistatus> 771 As before, this causes the entity to change, and a new entity tag to 772 be assigned. But in this case, the origin server actually notifies 773 the client of the changed state by including the "ETag" response 774 header. 776 The client now will be aware that the requested entity change, and 777 can use the new entity tag in subsequent requests (potentially after 778 refreshing the local copy). 780 Appendix B. Change Log (to be removed by RFC Editor before publication) 782 B.1. Since draft-reschke-http-etag-on-write-00 784 Add and resolves issues "entity-header" and "extensibility", by 785 removing the extension hooks, and by redefining the header to it can 786 be used as an Entity header. 788 B.2. Since draft-reschke-http-etag-on-write-01 790 Update APP and CALDAV references. Remove RFC3986 reference (not 791 needed anymore after the simplication in draft 01). Fix typo in 792 header description ("submitted entity", not "stored entity"). Remove 793 comparison about how XCAP and CALDAV profile RFC2616: after all, both 794 mandate a behaviour that was legal but optional before. Add 795 "Updates: RFC2616". 797 B.3. Since draft-reschke-http-etag-on-write-02 799 In the references, note that there was no activitiy on 800 draft-whitehead-http-etag-00 anymore. Change intended status to 801 "Experimental". Update APP reference. Update statements about 802 current status of XCAP and CALDAV. Add and resolve "clarify- 803 extension". 805 B.4. Since draft-reschke-http-etag-on-write-03 807 Update XCAP reference. Update header definition to use prose rules 808 rather than comments. Clarify "identity" keyword when appearing with 809 a weak entity-tag. In PROPPATCH/HTML example, fix whitespace so that 810 the HTML title element has exactly the same value as the one that was 811 PROPPATCHed. Mention that ETags changing due to a PROPPATCH could 812 even occur in presence of a WebDAV write lock. Expand keyword 813 substitution example with variant where Entity-Transform is returned. 815 Appendix C. Open issues (to be removed by RFC Editor prior to 816 publication) 818 C.1. edit 820 Type: edit 822 julian.reschke@greenbytes.de (2006-08-10): Umbrella issue for 823 editorial fixes/enhancements. 825 Author's Address 827 Julian F. Reschke 828 greenbytes GmbH 829 Hafenweg 16 830 Muenster, NW 48155 831 Germany 833 Phone: +49 251 2807760 834 Fax: +49 251 2807761 835 Email: julian.reschke@greenbytes.de 836 URI: http://greenbytes.de/tech/webdav/ 838 Full Copyright Statement 840 Copyright (C) The IETF Trust (2006). 842 This document is subject to the rights, licenses and restrictions 843 contained in BCP 78, and except as set forth therein, the authors 844 retain all their rights. 846 This document and the information contained herein are provided on an 847 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 848 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 849 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 850 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 851 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 852 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 854 Intellectual Property 856 The IETF takes no position regarding the validity or scope of any 857 Intellectual Property Rights or other rights that might be claimed to 858 pertain to the implementation or use of the technology described in 859 this document or the extent to which any license under such rights 860 might or might not be available; nor does it represent that it has 861 made any independent effort to identify any such rights. Information 862 on the procedures with respect to rights in RFC documents can be 863 found in BCP 78 and BCP 79. 865 Copies of IPR disclosures made to the IETF Secretariat and any 866 assurances of licenses to be made available, or the result of an 867 attempt made to obtain a general license or permission for the use of 868 such proprietary rights by implementers or users of this 869 specification can be obtained from the IETF on-line IPR repository at 870 http://www.ietf.org/ipr. 872 The IETF invites any interested party to bring to its attention any 873 copyrights, patents or patent applications, or other proprietary 874 rights that may cover technology that may be required to implement 875 this standard. Please address the information to the IETF at 876 ietf-ipr@ietf.org. 878 Acknowledgment 880 Funding for the RFC Editor function is provided by the IETF 881 Administrative Support Activity (IASA).