idnits 2.17.1 draft-reschke-http-etag-on-write-09.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.ii or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. See https://trustee.ietf.org/license-info/.) 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 and authors 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 (March 2, 2009) is 5527 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) -- Obsolete informational reference (is this intentional?): RFC 2518 (Obsoleted by RFC 4918) Summary: 3 errors (**), 0 flaws (~~), 2 warnings (==), 5 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) March 2, 2009 5 Intended status: Experimental 6 Expires: September 3, 2009 8 The Hypertext Transfer Protocol (HTTP) Entity Tag ("ETag") 9 Response Header in Write Operations 10 draft-reschke-http-etag-on-write-09 12 Status of this Memo 14 This Internet-Draft is submitted to IETF in full conformance with the 15 provisions of BCP 78 and BCP 79. 17 Internet-Drafts are working documents of the Internet Engineering 18 Task Force (IETF), its areas, and its working groups. Note that 19 other groups may also distribute working documents as Internet- 20 Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six months 23 and may be updated, replaced, or obsoleted by other documents at any 24 time. It is inappropriate to use Internet-Drafts as reference 25 material or to cite them other than as "work in progress." 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.txt. 30 The list of Internet-Draft Shadow Directories can be accessed at 31 http://www.ietf.org/shadow.html. 33 This Internet-Draft will expire on September 3, 2009. 35 Copyright Notice 37 Copyright (c) 2009 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents in effect on the date of 42 publication of this document (http://trustee.ietf.org/license-info). 43 Please review these documents carefully, as they describe your rights 44 and restrictions with respect to this document. 46 Abstract 48 The Hypertext Transfer Protocol (HTTP) specifies a state identifier, 49 called "Entity Tag", to be returned in the "ETag" response header. 50 However, the description of this header for write operations such as 51 PUT is incomplete, and has caused confusion among developers and 52 protocol designers, and potentially interoperability problems. 54 This document explains the problem in detail and suggests both a 55 clarification for a revision to the HTTP/1.1 specification (RFC2616) 56 and a new header for use in responses, making HTTP entity tags more 57 useful for user agents that want to avoid round-trips to the server 58 after modifying a resource. 60 Editorial Note (To be removed by RFC Editor before publication) 62 Distribution of this document is unlimited. Please send comments to 63 the Hypertext Transfer Protocol (HTTP) mailing list at 64 ietf-http-wg@w3.org [1], which may be joined by sending a message 65 with subject "subscribe" to ietf-http-wg-request@w3.org [2]. 67 Discussions of the HTTP working group are archived at 68 . 70 XML versions, latest edits and the issues list for this document are 71 available from 72 . 74 Table of Contents 76 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 77 1.1. Questions out of Scope . . . . . . . . . . . . . . . . . . 4 78 1.2. The Interoperability Problem . . . . . . . . . . . . . . . 4 79 1.3. Analysis of RFC2616's Definitions . . . . . . . . . . . . 6 80 1.4. Prior Work . . . . . . . . . . . . . . . . . . . . . . . . 7 81 2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 8 82 3. Clarifications on the Behavior of the 'ETag' Response 83 Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 84 4. The 'Entity-Transform' Header . . . . . . . . . . . . . . . . 9 85 4.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 10 86 5. How This Helps . . . . . . . . . . . . . . . . . . . . . . . . 10 87 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 88 7. Security Considerations . . . . . . . . . . . . . . . . . . . 11 89 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 90 8.1. Normative References . . . . . . . . . . . . . . . . . . . 11 91 8.2. Informative References . . . . . . . . . . . . . . . . . . 11 92 Appendix A. Use Cases . . . . . . . . . . . . . . . . . . . . . . 12 93 A.1. Simple Authoring . . . . . . . . . . . . . . . . . . . . . 12 94 A.2. Simple Authoring, with Entity-Transform header . . . . . . 14 95 A.3. Setting both Content and Metadata . . . . . . . . . . . . 15 96 A.4. Setting both Content and Metadata, new style . . . . . . . 17 97 Appendix B. Change Log (to be removed by RFC Editor before 98 publication) . . . . . . . . . . . . . . . . . . . . 18 99 B.1. Since draft-reschke-http-etag-on-write-00 . . . . . . . . 18 100 B.2. Since draft-reschke-http-etag-on-write-01 . . . . . . . . 18 101 B.3. Since draft-reschke-http-etag-on-write-02 . . . . . . . . 19 102 B.4. Since draft-reschke-http-etag-on-write-03 . . . . . . . . 19 103 B.5. Since draft-reschke-http-etag-on-write-04 . . . . . . . . 19 104 B.6. Since draft-reschke-http-etag-on-write-05 . . . . . . . . 19 105 B.7. Since draft-reschke-http-etag-on-write-06 . . . . . . . . 19 106 B.8. Since draft-reschke-http-etag-on-write-07 . . . . . . . . 19 107 B.9. Since draft-reschke-http-etag-on-write-08 . . . . . . . . 19 108 Appendix C. Open issues (to be removed by RFC Editor prior to 109 publication) . . . . . . . . . . . . . . . . . . . . 19 110 C.1. edit . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 111 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 20 113 1. Introduction 115 The Hypertext Transfer Protocol (HTTP) specifies a state identifier, 116 called "Entity Tag", to be returned in the "ETag" response header 117 (see [RFC2616], Section 14.19). However, the description of this 118 header for write operations such as PUT is incomplete, and has caused 119 confusion among developers and protocol designers, and potentially 120 interoperability problems. 122 This document explains the problem in detail and suggests both a 123 clarification for a revision to [RFC2616] and a new header for use in 124 responses, making HTTP entity tags more useful for user agents that 125 want to avoid round-trips to the server after modifying a resource. 127 1.1. Questions out of Scope 129 Note that there is a related problem: modifying content-negotiated 130 resources. Here the consensus seems to be simply not to do it. 131 Instead, the origin server should reveal specific URIs of content 132 that is not content-negotiated in the Content-Location response 133 header ([RFC2616], Section 14.14), and user agents should use this 134 more specific URI for authoring. Thus, the remainder of this 135 document will focus on resources for which no content negotiation 136 takes place. 138 Another related question is the usability of the weak entity tags for 139 authoring (see [RFC2616], Section 13.3.3). Although this document 140 focuses on the usage of strong entity tags, it is believed that the 141 changes suggested in this document could be applied to weak entity 142 tags as well. 144 1.2. The Interoperability Problem 146 For a long time, nobody realized that there was a problem at all, or 147 those who realized preferred to ignore it. 149 Server implementers added code that would return the new value of the 150 "ETag" header in a response to a successful PUT request. After all, 151 the client could be interested in it. 153 User agent developers in turn were happy to get a new "ETag" value, 154 saving a subsequent HEAD request to retrieve the new entity tag. 156 However, at some point of time, potentially during a Web Distributed 157 Authoring and Versioning (WebDAV, [RFC2518], obsoleted by [RFC4918]) 158 interoperability event, client programmers asked server programmers 159 to always return "ETag" headers upon PUT, never ever to change the 160 entity tag without "good reason", and - by the way - always to 161 guarantee that the server stores the new content octet-by-octet. 163 From the perspective of client software that wants to treat an HTTP 164 server as a file system replacement, this makes a lot of sense. 165 After all, when one writes to a file one usually expects the file 166 system to store what was written, and not to unexpectedly change the 167 contents. 169 However, in general, an HTTP server is not a file system replacement. 170 There may be some that have been designed that way, and some that 171 expose some parts of their namespace that have this quality. But in 172 general, HTTP server implementers have a lot of freedom in how 173 resources are implemented. Indeed, this flexibility is one of the 174 reasons for HTTP's success, allowing it to be used for a wide range 175 of tasks, of which replacing file systems is just one (and not 176 necessarily the most interesting one). 178 In particular: 180 o A server may not store a resource as a binary object - in this 181 case, the representation returned in a subsequent GET request may 182 just be similar, but not identical to what was written. Good 183 examples are servers that use HTTP to access XML data ([RFC4825]), 184 Calendaring data ([RFC4791]) or newsfeed data ([RFC5023]). 186 o A server may change the data being written on purpose, while it is 187 being written. Examples that immediately come to mind are keyword 188 substitution in a source control system, or filters that remove 189 potentially insecure parts out of HTML pages. 191 Furthermore: 193 o An "unrelated" method such as WebDAV's PROPPATCH (see [RFC4918], 194 Section 9.2) may affect the entity body and therefore the entity 195 tag in an unexpected way, because the server stores some or all of 196 the WebDAV properties inside the entity body (for instance, GPS 197 information inside a JPG image file). 199 As long as servers store the content octet-by-octet, and return 200 exactly what the client wrote, there is no problem at all. 202 Things get more interesting when a server does change the content, 203 such as in the "simple authoring" example given in Appendix A.1. 204 Here, the server does change the content upon writing to the 205 resource, yet no harm is done, because the final state of the 206 resource on the server does not depend on the client being aware of 207 that. 209 All of the content rewriting examples mentioned above have this 210 quality: the client can safely continue to edit the entity it sent, 211 because the result of the transformation done by the server will be 212 the same in the end. Formally, if we call the server-side 213 transformation "t", the initial content "c", and the client-side 214 editing steps "e1" and "e2", then 216 t(e2(e1(c))) = t(e2(t(e1(c)))) 218 e.g., it is irrelevant whether the client obtained the current entity 219 body before doing its second edit. 221 [[example.for.non.safe.rewrite: Question: does anybody know a real- 222 world example for server-side content rewriting where the above is 223 not true? --julian.reschke@greenbytes.de]] 225 Problems will only occur if the client uses the entity body it sent, 226 and the entity tag it obtained in return, in subsequent requests that 227 only transfer part of the entity body, such as GET or PUT requests 228 using the "Range" request header (see [RFC2616], Section 14.35). 230 Furthermore, some clients need to expose the actual contents to the 231 end user. These clients will have to ensure that they really have 232 the current representation. 234 Entity bodies (and thus entity tags) changing due to side effects of 235 seemingly unrelated requests are indeed a problem, as demonstrated in 236 Appendix A.3, and this specification proposes a way to resolve this 237 in Section 3. 239 1.3. Analysis of RFC2616's Definitions 241 There are several places in the HTTP/1.1 specification ([RFC2616]) 242 mentioning the "ETag" response header. 244 Let us start with the header definition in Section 14.19: 246 The ETag response-header field provides the current value of the 247 entity tag for the requested variant. Sections 14.24, 14.26 and 248 14.44 describe the headers used with entity tags. The entity tag 249 MAY be used for comparison with other entities from the same 250 resource (see Section 13.3.3). 252 The meaning of a "response-header" in turn is defined in Section 6.2: 254 The response-header fields allow the server to pass additional 255 information about the response which cannot be placed in the 256 Status-Line. These header fields give information about the 257 server and about further access to the resource identified by the 258 Request-URI. 260 The "ETag" response header itself is mentioned mainly in the context 261 of cache validation, such as in Section 13.3.2. What is missing is a 262 coherent description on how the origin server can notify the user- 263 agent when the entity tag changes as result of a write operation, 264 such as PUT. 266 Indeed, the definition of the 201 Created status code mentions entity 267 tags (Section 10.2.2): 269 A 201 response MAY contain an ETag response header field 270 indicating the current value of the entity tag for the requested 271 variant just created, see Section 14.19. 273 The "ETag" response header is mentioned again in the definition of 274 206 Partial Content (Section 10.2.7) and 304 Not Modified (Section 275 10.3.5), but notably missing are statements about other 2xx series 276 status codes that can occur upon a successful PUT operation, such as 277 200 OK (Section 10.2.1) and 204 No Content (Section 10.2.5). 279 Summarizing, the specification is a bit vague about what an ETag 280 response header upon a write operation means, but this problem is 281 somewhat mitigated by the precise definition of a response header. A 282 proposal for enhancing [RFC2616] in this regard is made in Section 3 283 below. 285 1.4. Prior Work 287 While working on the revision of [RFC2518], the IETF WebDAV working 288 group realized that this is a generic problem that needs attention 289 independently of WebDAV. An initial attempt was made with 290 [draft-whitehead-http-etag] in February 2006, but no progress was 291 made since. 293 Since then, two specifications based on HTTP were just published by 294 the RFC Editor, taking two opposite approaches: 296 o Section 8.5 of [RFC4825] makes it a MUST-level requirement to 297 return an entity tag upon PUT, even though the very nature of an 298 XCAP server will cause it to rewrite contents (due to its XML- 299 based storage). 301 o Section 5.3.4 of [RFC4791] explicitly forbids ("MUST NOT") 302 returning an entity tag upon PUT if the content was rewritten. 304 In essence, this makes it impossible to implement an HTTP resource 305 that conforms to both specifications. Due to the differing use cases 306 of XCAP and CalDAV, this may not be a problem in practice, but the 307 disagreement in itself is scary. Publication of these specifications 308 on the standards track will make it much harder for future protocols 309 to deal with this topic in a meaningful way (comments were sent 310 during IETF Last Call for CalDAV, see 311 ). 313 2. Notational Conventions 315 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL-NOT", 316 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 317 document are to be interpreted as described in [RFC2119]. 319 The terminology used here follows and extends that in the HTTP 320 specification [RFC2616], notably the augmented Backus-Naur Form (BNF) 321 defined in Section 2.1 of that document. 323 3. Clarifications on the Behavior of the 'ETag' Response Header 325 This section describes a minimal change to [RFC2616], proposed in . 328 At the end of Section 10.2 of [RFC2616], add: 330 The response MAY contain an ETag response header field indicating 331 the current value of the entity tag (Section 14.19) for the 332 requested variant. The value SHOULD be the same as the one 333 returned upon a subsequent HEAD request addressing the same 334 variant. 336 In Section 10.2.1 of [RFC2616], remove: 338 A 201 response MAY contain an ETag response header field 339 indicating the current value of the entity tag for the requested 340 variant just created, see Section 14.19. 342 In essence, this moves the statement about entity tags in write 343 operations from the specific case of status 201 Created into the more 344 generic description of the 2xx series status codes. 346 Note that the term "requested variant" is somewhat misleading, in 347 particular in the context of write operations (see 348 on the 349 RFC2616bis issues list). 351 4. The 'Entity-Transform' Header 353 The 'Entity-Transform' entity header provides information about 354 whether a transformation has been applied to an entity body. 356 When used in an HTTP request, its meaning is undefined. In an HTTP 357 response, it provides information whether the server has applied a 358 transformation when the entity was stored last. 360 In general, entity headers may be stored in intermediates. The main 361 use of this header however applies to the HTTP PUT method, of which 362 by default the results are not cacheable (see [RFC2616], Section 363 9.6). In addition, the value format is defined so that a client can 364 reliably detect whether the information is fresh. 366 Format: 368 Entity-Transform = "Entity-Transform" ":" entity-transform-spec 369 entity-transform-spec = entity-transform-keyword SP entity-tag 370 entity-transform-keyword = "identity" | "unspecified"| token 372 entity-tag = 373 token = 375 The entity-tag specifies the entity body to which this information 376 applies. 378 An entity-transform-keyword of "identity" specifies that the origin 379 server has stored the entity octet-by-octet, thus the user agent MAY 380 use a local copy of the entity body with the given entity-tag for 381 subsequent requests that rely on octet-by-octet identity (such as a 382 PUT with "Range" request header). 384 Both the absence of this response header and any entity-transform- 385 keyword value other than "identity" specify that the origin server 386 may have transformed the entity before storage, thus a subsequent 387 retrieval will not necessarily return an exact copy of the submitted 388 entity. 390 Note: usage of keywords other than "identity" or "unspecified" is 391 reserved for future revisisions of this specification. 393 Further note that the definition of the "identity" keyword is 394 independant of the type of entity-tag. Thus, when "identity" is 395 returned with a weak entity-tag, the client can indeed rely on 396 octet-by-octet identity. 398 4.1. Examples 400 Content was stored octet-by-octet: 402 HTTP/1.1 200 OK 403 ETag: "1" 404 Entity-Transform: identity "1" 406 Content was transformed: 408 HTTP/1.1 200 OK 409 ETag: "2" 410 Entity-Transform: unspecified "2" 412 Response containing a stale "Entity-Transform" header: 414 HTTP/1.1 200 OK 415 ETag: "3" 416 Entity-Transform: unspecified "2" 418 Note that in this case the newly assigned entity tag and the entity 419 tag returned in "Entity-Transform" do not match, thus the client is 420 aware that the header value is stale and can't be used. 422 5. How This Helps 424 The clarification of [RFC2616] (see Section 3) makes it clear that 425 user agents can use "ETag" headers obtained in write operations, as 426 long as they do not require octet-by-octet identity. In particular, 427 a new entity tag can be returned for any method, such as a WebDAV 428 PROPPATCH (see [RFC4918], Section 9.2). This helps dealing with the 429 problem described in Appendix A.3. See Appendix A.4 for details. 431 The addition of the "Entity-Transform" header (see Section 4) enables 432 origin servers to signal that they stored an exact copy of the 433 content, thus allowing clients not to refetch the content. Note that 434 by default (in absence of the response header), a client can not make 435 any assumptions about the server's behavior in this regard. Thus 436 clients will only benefit from new servers explicitly setting the new 437 header. 439 6. IANA Considerations 441 This document specifies the new HTTP header listed below. 443 Header field name: Entity-Transform 445 Applicable protocol: http 447 Status: informational 449 Author/Change controller: IETF 451 Specification document: Section 4 of this specification 453 7. Security Considerations 455 This specification introduces no new security considerations beyond 456 those discussed in Section 15 of [RFC2616]. 458 8. References 460 8.1. Normative References 462 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 463 Requirement Levels", BCP 14, RFC 2119, March 1997. 465 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 466 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 467 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 469 8.2. Informative References 471 [HTML] Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01 472 Specification", W3C REC-html401-19991224, December 1999, 473 . 475 [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D. 476 Jensen, "HTTP Extensions for Distributed Authoring -- 477 WEBDAV", RFC 2518, February 1999. 479 [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, 480 "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, 481 March 2007. 483 [RFC4825] Rosenberg, J., "The Extensible Markup Language (XML) 484 Configuration Access Protocol (XCAP)", RFC 4825, May 2007. 486 [RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed 487 Authoring and Versioning (WebDAV)", RFC 4918, June 2007. 489 [RFC5023] Gregorio, J., Ed. and B. de hOra, Ed., "The Atom 490 Publishing Protocol", RFC 5023, October 2007. 492 [draft-whitehead-http-etag] 493 Whitehead, J., "Design Considerations for State 494 Identifiers in HTTP and WebDAV", 495 draft-whitehead-http-etag-00 (work in progress), 496 February 2006. 498 (Not updated since.) 500 URIs 502 [1] 504 [2] 506 Appendix A. Use Cases 508 A.1. Simple Authoring 510 Let us consider a server not having the quality of preserving octet- 511 by-octet identity, for instance because of SVN-style keyword 512 expansion in text content (). 515 In this case, the client has previously retrieved the representation 516 for , and the server has returned the ETag 517 "1": 519 >> Request (1) 521 GET /test HTTP/1.1 522 Host: example.com 524 >> Response (1) 526 HTTP/1.1 200 OK 527 Content-Type: text/plain 528 ETag: "1" 530 # $Revision: 1 $ 531 Sample text. 533 The client now wants to update the resource. To avoid overwriting 534 somebody else's changes, it submits the PUT request with the HTTP 535 "If-Match" request header (see [RFC2616], Section 14.24): 537 >> Request (2) 539 PUT /test HTTP/1.1 540 Host: example.com 541 If-Match: "1" 543 # $Revision: 1 $ 544 New sample text. 546 If the resource was modified in the meantime, the server will reject 547 the request with a 412 Precondition Failed status: 549 >> Response (2a) 551 HTTP/1.1 412 Precondition Failed 552 Content-Type: text/plain 554 Precondition Failed: entity tag supplied in If-Match request header 555 did not match current. 557 In this case, the client usually has take care of merging the changes 558 made locally with those made on the server ("Merge Conflict"). 560 If there was no overlapping update, the server will execute the 561 request and return a new entity tag: 563 >> Response (2b) 565 HTTP/1.1 200 OK 566 Content-Type: text/plain 567 ETag: "2" 569 Note however, that at this point the client knows the new entity tag, 570 but doesn not know the current representation, which will have been 571 updated by the server to: 573 # $Revision: 2 $ 574 New sample text. 576 What seems to be a problem at first may not be a real problem in 577 practice. Let us assume that the client continues editing the 578 resource, using the entity tag obtained from the previous request, 579 but editing the entity it last sent: 581 >> Request (3) 583 PUT /test HTTP/1.1 584 Host: example.com 585 If-Match: "2" 587 # $Revision: 1 $ 588 A third attempt. 590 Assuming there was no overlapping update, the PUT request will 591 succeed: 593 >> Response (3) 595 HTTP/1.1 200 OK 596 Content-Type: text/plain 597 ETag: "3" 599 Note that the only problem here is that the client doesn't have an 600 exact copy of the entity it is editing. However, from the server's 601 point of view this is entirely irrelevant, because the "Revision" 602 keyword will be automatically updated upon every write anyway. 604 In any case, the final contents will be: 606 # $Revision: 3 $ 607 A third attempt. 609 A.2. Simple Authoring, with Entity-Transform header 611 In the example above (Appendix A.1, Response 2b), the server returns 612 an ETag response header upon PUT, although the content actually was 613 rewritten due to keyword substitution. 615 A server implementing this specification would instead respond with: 617 >> Response (2c) 619 HTTP/1.1 200 OK 620 Content-Type: text/plain 621 ETag: "2" 622 Entity-Transform: unspecified "2" 624 This indicates that the content that was sent is not octet-by-octet 625 identical to what a subsequent GET request would retrieve. It is 626 then up to the client to decide whether it wants to re-fetch the 627 content before continuing edits. 629 A.3. Setting both Content and Metadata 631 In this example, the server exposes data extracted from the HTML 632 element ([HTML], Section 7.4.2) as a custom WebDAV property 633 ([RFC4918], Section 4), allowing both read and write access. 635 In the first step, the client obtains the current representation for 636 <http://example.com/test.html>: 638 >> Request (1) 640 GET /test.html HTTP/1.1 641 Host: example.com 643 >> Response (1) 645 HTTP/1.1 200 OK 646 Content-Type: text/html 647 ETag: "A" 649 <html> 650 <head> 651 </head> 652 <body> 653 </body> 654 </html> 656 Next, it adds one paragraph to the <body> element, and gets back a 657 new entity tag: 659 >> Request (2) 661 PUT /test.html HTTP/1.1 662 Host: example.com 663 If-Match: "A" 665 <html> 666 <head> 667 </head> 668 <body> 669 <p>First paragraph.</p> 670 </body> 671 </html> 673 >> Response (2) 675 HTTP/1.1 200 OK 676 ETag: "B" 677 Next, the client sets a custom "title" property (see [RFC4918], 678 Section 9.2): 680 >> Request (3) 682 PROPPATCH /test.html HTTP/1.1 683 Host: example.com 684 Content-Type: application/xml 686 <proppatch xmlns="DAV:"> 687 <set> 688 <prop> 689 <title xmlns="http://ns.example.org/" 690 >A sample document 691 692 693 695 >> Response (3) 697 HTTP/1.1 207 Multi-Status 698 Content-Type: application/xml 700 701 702 /test.html 703 704 705 706 </prop> 707 <status>HTTP/1.1 2OO OK</status> 708 </propstat> 709 </response> 710 </multistatus> 712 The server knows how to propagate property changes into the HTML 713 content, so it updates the entity by adding an HTML title document 714 accordingly. This causes the entity tag changing to "C". 716 The new entity body is shown below, but the client does not realize 717 that it did change at all. 719 <html> 720 <head> 721 <title>A sample document 722 723 724

First paragraph.

725 726 728 A subsequent attempt by the client to update the entity body will 729 fail, unless it realizes that changing WebDAV properties may affect 730 the entity as well. In this case, it would have had to get the 731 current entity tag before proceeding. Of course, this introduces an 732 additional round-trip, and a timing window during which overlapping 733 updates by other clients would go unnoticed. 735 Note that a client would be affected by this behaviour even in the 736 presence of an exclusive WebDAV write lock (see [RFC4918], Section 737 7). 739 A.4. Setting both Content and Metadata, new style 741 Below we repeat the example from above (Appendix A.3), but here the 742 origin server returns entity tags for all write operations, and the 743 user agent knows how to deal with them. That is, both take advantage 744 of what [RFC2616] already allows. 746 >> Request (3) 748 PROPPATCH /test.html HTTP/1.1 749 Host: example.com 750 Content-Type: application/xml 752 753 754 755 756 A sample document 757 758 759 760 761 >> Response (3) 763 HTTP/1.1 207 Multi-Status 764 Content-Type: application/xml 765 ETag: "C" 767 768 769 /test.html 770 771 772 773 </prop> 774 <status>HTTP/1.1 2OO OK</status> 775 </propstat> 776 </response> 777 </multistatus> 779 As before, this causes the entity to change, and a new entity tag to 780 be assigned. But in this case, the origin server actually notifies 781 the client of the changed state by including the "ETag" response 782 header. 784 The client now will be aware that the requested entity change, and 785 can use the new entity tag in subsequent requests (potentially after 786 refreshing the local copy). 788 Appendix B. Change Log (to be removed by RFC Editor before publication) 790 B.1. Since draft-reschke-http-etag-on-write-00 792 Add and resolves issues "entity-header" and "extensibility", by 793 removing the extension hooks, and by redefining the header to it can 794 be used as an Entity header. 796 B.2. Since draft-reschke-http-etag-on-write-01 798 Update APP and CALDAV references. Remove RFC3986 reference (not 799 needed anymore after the simplication in draft 01). Fix typo in 800 header description ("submitted entity", not "stored entity"). Remove 801 comparison about how XCAP and CALDAV profile RFC2616: after all, both 802 mandate a behaviour that was legal but optional before. Add 803 "Updates: RFC2616". 805 B.3. Since draft-reschke-http-etag-on-write-02 807 In the references, note that there was no activitiy on 808 draft-whitehead-http-etag-00 anymore. Change intended status to 809 "Experimental". Update APP reference. Update statements about 810 current status of XCAP and CALDAV. Add and resolve "clarify- 811 extension". 813 B.4. Since draft-reschke-http-etag-on-write-03 815 Update XCAP reference. Update header definition to use prose rules 816 rather than comments. Clarify "identity" keyword when appearing with 817 a weak entity-tag. In PROPPATCH/HTML example, fix whitespace so that 818 the HTML title element has exactly the same value as the one that was 819 PROPPATCHed. Mention that ETags changing due to a PROPPATCH could 820 even occur in presence of a WebDAV write lock. Expand keyword 821 substitution example with variant where Entity-Transform is returned. 823 B.5. Since draft-reschke-http-etag-on-write-04 825 Update APP reference. Update CalDAV reference (published as 826 RFC4791). Update "prior work" (RFC4791 being published, XCAP having 827 been approved). 829 B.6. Since draft-reschke-http-etag-on-write-05 831 Update XCAP reference (published as RFC4825). Update "prior work" 832 (RFC4825 being published). 834 B.7. Since draft-reschke-http-etag-on-write-06 836 Replace RFC2518 references with RFC4918 where appropriate. Update 837 APP reference. 839 B.8. Since draft-reschke-http-etag-on-write-07 841 Update APP reference. Reference the "requested variant" issue on the 842 RFC2616bis issues list 843 (<http://www.w3.org/Protocols/HTTP/1.1/rfc2616bis/issues/#i69>). 845 B.9. Since draft-reschke-http-etag-on-write-08 847 Update pointer to RFC2616bis "requested variant" issue. 849 Appendix C. Open issues (to be removed by RFC Editor prior to 850 publication) 852 C.1. edit 854 Type: edit 856 julian.reschke@greenbytes.de (2006-08-10): Umbrella issue for 857 editorial fixes/enhancements. 859 Author's Address 861 Julian F. Reschke 862 greenbytes GmbH 863 Hafenweg 16 864 Muenster, NW 48155 865 Germany 867 Phone: +49 251 2807760 868 Email: julian.reschke@greenbytes.de 869 URI: http://greenbytes.de/tech/webdav/