idnits 2.17.1 draft-ietf-webdav-depth-00.txt: ** The Abstract section seems to be numbered Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-19) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 4 longer pages, the longest (page 4) being 60 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 111: '... Clients MUST NOT rely upon the thre...' RFC 2119 keyword, line 134: '...hree new methods MUST be applied to al...' RFC 2119 keyword, line 153: '... resource MUST be submitted with the...' RFC 2119 keyword, line 161: '... the DELETE-TREE MUST be treated as a ...' RFC 2119 keyword, line 167: '...with DELETE-TREE MUST be applied in pr...' (10 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- -- 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.) -- Couldn't find a document date in the document -- date freshness check skipped. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? 'RFC2068' on line 437 looks like a reference Summary: 10 errors (**), 0 flaws (~~), 2 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 INTERNET-DRAFT Yaron Y. Goland 2 Expires: March 1998 Saveen Reddy 3 Microsoft Corporation 4 Oct. 8, 1997 6 WebDAV Tree Operations 7 draft-ietf-webdav-depth-00.txt 9 1. Status of this Memo 11 This document is an Internet-Draft. Internet-Drafts are 12 working documents of the Internet Engineering Task Force (IETF), its 13 areas, and its working groups. Note that other groups may also 14 distribute working documents as Internet-Drafts. 16 Internet-Drafts are draft documents valid for a maximum of six 17 months and may be updated, replaced, or obsoleted by other documents 18 at any time. It is inappropriate to use Internet-Drafts as 19 reference material or to cite them other than as "work in progress." 21 To view the entire list of current Internet-Drafts, please check the 22 "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow 23 Directories on ftp.is.co.za (Africa), ftp.nordu.net (Europe), 24 munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or 25 ftp.isi.edu (US West Coast). 27 2. Abstract 29 The WebDAV protocol specification [Goland et al., 1997] defines the 30 DELETE, COPY and MOVE methods. However these methods have a scope of 31 a single source resource. It is common for principals to wish to 32 perform a DELETE, COPY or MOVE on a collection and all its internal 33 members. This specification defines the DELETE-TREE, COPY-TREE and 34 MOVE-TREE methods that perform the equivalent of DELETE, COPY and 35 MOVE across a collection and all its progeny. 37 3. Contents 39 1. Status of this Memo.............................................1 40 2. Abstract........................................................1 41 3. Contents........................................................2 42 4. Problem Definition..............................................2 43 5. Proposed Solution...............................................3 44 6. Levels of Recursion.............................................3 45 7. Message Headers and Recursion...................................3 46 8. Lock Tokens and *-TREE Methods..................................4 47 9. DELETE-TREE Method..............................................4 48 10.COPY-TREE Method................................................6 49 11.MOVE-TREE Method................................................7 50 12.102 "Processing" Response Code..................................9 51 13.Status-URI Response Header......................................9 52 14.Author's Address...............................................10 53 15.Bibliography...................................................10 55 4. Problem Definition 57 HTTP is designed such that a single message causes a single action 58 on a single resource. This has proven to be a simple, interoperable, 59 robust mechanism for delivering methods. In addition, in a world 60 where the majority of requests are GETS, it is also a 'fair' 61 arbitrator of server resources. Specifically, as load increases each 62 client suffers degradation in service proportional to the number of 63 requests made. 65 However clients often wish to perform actions against all internal 66 members of a collection. Currently a client has no choice but to 67 execute each method individually on each member of the collection, 68 in other words, there is no way to instruct a server to recurse 69 through a namespace on behalf of a client. 71 In many cases forcing the client to perform their own recursive 72 calls is a desirable situation as it maintains the fairness of load 73 distribution. The average HTTP editing server, which handles mostly 74 GETs and PUTs with the occasional COPY or MOVE, is probably better 75 off using non-recursive operations. 77 However some servers routinely deal with operations on collection, 78 so routinely in fact that they have developed a number of 79 optimizations to allow them to quickly execute an operation against 80 a hierarchy. 82 A typical example is a copy on write system which can copy an entire 83 hierarchy by putting a single pointer into the server's internal 84 namespace and then tracking when one of the original resources is 85 changed, thus performing the copy only when required. These servers 86 are unable to take advantage of their optimizations because DAV does 87 not provide a way for a client to tell the server that it intends to 88 execute the copy against an entire hierarchy. 90 In addition, in some circumstances, it is too expensive for clients 91 to handle recursion themselves. For example, a hand held unit with 92 limited memory, power, and bandwidth, would not be able to deal very 93 well with a simple operation such as deleting a collection. The hand 94 held unit would be required to execute a large number of methods and 95 potentially record a large number of index entries as it recurses 96 through the hierarchy. In such cases fairness takes second place to 97 access. 99 As such a means is needed for a client to efficiently indicate to a 100 server its desire to execute a single method against a hierarchy. 102 5. Proposed Solution 104 The proposed solution is the introduction of three new methods: 105 DELETE-TREE, COPY-TREE, and MOVE-TREE. 107 The three new methods are not the same as their root methods, 108 DELETE, COPY, and MOVE. For example, a MOVE on a collection has 109 different semantics then MOVE on a single resource. 111 Clients MUST NOT rely upon the three new methods executing on 112 members of their hierarchies in any particular order and the three 113 new methods are not atomic. 115 Upon executing the three new methods will perform as much of their 116 assigned task as possible and then return a response specifying what 117 they were able to accomplish and what they failed to do. 119 So, for example, an attempt to COPY a hierarchy may result in some 120 of the members being copied and some not. 122 6. Levels of Recursion 124 As currently defined, all three new methods apply to the full length 125 of the hierarchy. It has been suggested that the number of levels to 126 be recursed should be an option. However no compelling case has been 127 presented for why allowing the depth of recursion to be controlled 128 is a desirable feature. As such this specification errs on the side 129 of simplicity and declares that all three new methods apply to the 130 full hierarchy. 132 7. Message Headers and Recursion 134 Any headers on the three new methods MUST be applied to all 135 resources in the scope of the method. For example, an if-match 136 header will have its value applied against every resource in the 137 method's scope and will cause the method to fail if the header fails 138 to match properly. 140 [Ed. Note: No, this isn't an error. Think about it, if you put an 141 'if-match: *' what are you after? I think that putting propagation 142 rules are just going to complicate things beyond reason. Look at the 143 typical case 'I only want to copy this collection if its membership 144 has changed or if the value of its members have changed.' The best 145 an e-tag could give you is detection of membership change, not if 146 the member's values have changed. I say leave well enough alone and 147 just propagate everything.] 149 8. Lock Tokens and *-TREE Methods 150 If a resource, source or destination, within scope of the *-TREE 151 method is locked in such a way as to prevent the successful 152 execution of the *-TREE method, then the lock token for that 153 resource MUST be submitted with the *-TREE request in the State- 154 Token request header. 156 9. DELETE-TREE Method 158 9.1. Request 160 The DELETE-TREE method is only meaningful on a collection. If used 161 on a non-collection the DELETE-TREE MUST be treated as a DELETE. 163 DELETE-TREE instructs that the collection specified in the request- 164 URI, the records of its external member resources, and all its 165 internal member resources, are to be deleted. 167 Any headers included with DELETE-TREE MUST be applied in processing 168 every resource to be deleted. In this case, a header of special 169 interest is the DESTROY header which specifies the method to be used 170 to delete all resources in the scope of the DELETE-TREE. 172 When the DELETE-TREE method has completed processing it MUST return 173 a consistent namespace. Please refer to [Goland et al., 1997] for a 174 full definition of a consistent namespace. 176 9.2. Response 178 The response SHOULD be a multi-status response that describes the 179 result of the DELETE-TREE on each effected resource. 181 [Editor's Note: The response to a TREE method could potentially be 182 huge, larger than a client may want or need to deal with. It has 183 been suggested that clients be given the ability to tell the server 184 they only want to get back a response code, not a response body. 185 Thoughts?] 187 9.3. Response Codes 189 415 Conflict - This can be used to indicate that some unspecified 190 problem has occurred which makes it impossible to delete a 191 particular resource. The most common scenario is that a new internal 192 member was added to a collection while a DELETE-TREE was running and 193 thus the collection can not be deleted. 195 9.4. Example 197 DELETE-TREE /container/ HTTP/1.1 198 Host: www.foo.bar 199 Destroy: 201 HTTP/1.1 207 Multi-Response 202 Content-Type: text/xml 203 Content-Length: xxxxx 205 207 208 209 http://www.foo.bar/container/resource1 210 http://www.foo.bar/container/resource2 211 http://www.foo.bar/container/ 212 HTTP/1.1 200 Success 213 214 215 http://www.foo.bar/container/resource3 216 HTTP/1.1 412 Precondition Failed 217 218 220 In this example the attempt to delete 221 http://www.foo.bar/container/resource3 failed. Given that there is 222 only one precondition, one can figure out that the failure was 223 caused the inability of the system to meet the requirement of the 224 Destroy header. Normally however, the client will not know exactly 225 what precondition caused the failure. 227 The result is that www.foo.bar/container/ is created in order to 228 maintain namespace integrity. 230 [Ed-Note: To state the obvious, do we want to provide information on 231 which precondition actually failed? This is not the panacea it might 232 seem as the failure may have occurred for multiple reasons and 233 listing a bunch of headers may or may not be useful. Besides, the 234 reality is, nobody every pays attention to error codes. There are 235 really only two error codes in the world "It worked" or "Something 236 Went Wrong."] 238 10. COPY-TREE Method 240 10.1. Request 242 The COPY-TREE method is only meaningful on a collection. If used on 243 a non-collection the COPY-TREE MUST be treated as a COPY. 245 COPY-TREE instructs that the collection specified in the Request- 246 URI, the records of its external member resources, and all its 247 internal member resources, are to be copied to a location relative 248 to the Destination header. 250 Any headers included with COPY-TREE are to be applied in processing 251 every resource to be copied. 253 The exception to this rule is the Destination header. This header 254 only specifies the destination for the Request-URI. When applied to 255 members of the collection specified in the request-URI the value of 256 Destination is to be modified to reflect the current location in the 257 hierarchy. So, if the request-URI is "a" and the destination is "b" 258 then when a/c/d is processed it MUST use a destination of b/c/d. 260 When the COPY-TREE method has completed processing it MUST have 261 created a consistent namespace at the destination. Thus if it is not 262 possible to COPY a collection with internal members, the internal 263 members may still be copied but a collection will have to be created 264 at the destination to contain them. 266 Please refer to the definition of COPY in section XYZ of [Goland et 267 Al., 1997] for the rules on merging members and properties of source 268 collections with pre-existing collections at the destination. 270 10.2. Response 272 The response is a multi-status response that describes the result of 273 the COPY-TREE on each effected resource. The response is given for 274 the resource that was to be copied, not the resource that was 275 created as a result of the copy. In other words, each entry 276 indicates if the copy on the resource specified in the HREF 277 succeeded or failed and why. 279 The exception to this rule is for errors that occurred on the 280 destination. For example, if the destination was locked the response 281 would indicate the destination URL and a 416 "Locked" error. 283 10.3. Example 285 COPY-TREE /container/ HTTP/1.1 286 Host: www.foo.bar 287 Destination: http://www.foo.bar/othercontainer/ 288 Enforce-Live-Properties: * 290 HTTP/1.1 207 Multiresponse 291 Content-Type: text/xml 292 Content-Length: xxxxx 294 296 297 298 http://www.foo.bar/container/resource1 299 http://www.foo.bar/container/resource2 300 http://www.foo.bar/container/ 301 http://www.foo.bar/container/R2/D2 302 HTTP/1.1 201 Created 303 304 305 http://www.foo.bar/container/R2/ 306 HTTP/1.1 415 Precondition Failed 307 308 310 In this example most of the resources, along with the container, 311 were copied successfully. However the container R2 failed, most 312 likely due to a problem with enforcing live properties. R2's member 313 D3 was successfully copied. As a result a collection was created at 314 www.foo.bar/othercontainer/R2 to contain D2. 316 11. MOVE-TREE Method 318 11.1. Request 320 The MOVE-TREE method is only meaningful on a collection. If used on 321 a non-collection the MOVE-TREE MUST be treated as a MOVE. 323 MOVE-TREE instructs that the collection specified in the Request- 324 URI, the records of its external member resources, and all its 325 internal member resources, are to be moved to a location relative to 326 the Destination header. 328 Any headers included with MOVE-TREE are to be applied in processing 329 every resource to be moved. 331 The exception to this rule is the Destination header. The behavior 332 of this header is the same as given for COPY-TREE. 334 When the MOVE-TREE method has completed processing it MUST have 335 created a consistent namespace on both the source and destination, 336 creating collections at the source or destination as necessary. 338 As specified in the definition of MOVE, a MOVE of a collection over 339 another collection causes the destination collection and all its 340 members to be deleted. 342 11.2. Response 344 The response is a multi-status response that describes the result of 345 the MOVE-TREE on each effected resource. The response is given for 346 the resource that was to be moved, not the resource that was created 347 as a result of the move. In other words, each entry indicates if the 348 move on the resource specified in the HREF succeeded or failed and 349 why. 351 The exception to this rule is for errors that occurred on the 352 destination. For example, if the destination was locked the response 353 would indicate the destination URL and a 416 "Locked" error. 355 11.3. Example 357 MOVE-TREE /container/ HTTP/1.1 358 Host: www.foo.bar 359 Destination: http://www.foo.bar/othercontainer/ 360 Enforce-Live-Properties: * 361 Overwrite: False 362 State-Token: 364 HTTP/1.1 207 Multiresponse 365 Content-Type: text/xml 366 Content-Length: xxxxx 368 370 371 372 http://www.foo.bar/container/resource1 373 http://www.foo.bar/container/resource2 374 http://www.foo.bar/container/ 375 http://www.foo.bar/container/C2/R2 376 HTTP/1.1 201 Created 377 379 380 http://www.foo.bar/othercontainer/C2 381 HTTP/1.1 416 Locked 382 383 384 In this example the client has submitted a number of lock tokens 385 with the request. A lock token will need to be submitted for every 386 resource, both source and destination, anywhere in the scope of the 387 method, that is locked. In this case the proper lock token was not 388 submitted for the destination http://www.foo.bar/othercontainer/C2. 389 However C2's child, R2, was successfully copied. 391 12. 102 "Processing" Response Code 392 The *-Tree methods can potentially take a long period of time to 393 process. In such cases the client may time-out the connection while 394 waiting for a response. To prevent this the server MAY return a 102 395 response code to indicate to the client that the server is still 396 processing the method. 398 If a method is taking longer than [INSERT NUMBER HERE] seconds to 399 process the server SHOULD return a 102 "Processing" response. 401 13. Status-URI Response Header 403 The Status-URI response header MAY be used with the 102 "Processing" 404 response code to inform the client as to the status of a method. 406 Status-URI = "Status-URI" ":" *(Status-Code "<" URI ">") ; Status- 407 Code is defined in 6.1.1 of [RFC2068] 409 The URIs listed in the header are source resources which have been 410 effected by the outstanding method. The status code indicates the 411 resolution of the method on the identified resource. So, for 412 example, if a COPY-TREE method is outstanding and a 102 "Processing" 413 response with a Status-URI response header is returned, the included 414 URIs will indicate resources that have had copy attempted on them 415 and what the result was. Note that including the URI does not 416 indicate the result of applying the method. 418 14. Author's Address 420 Yaron Y. Goland 421 Saveen Reddy 422 Microsoft Corporation 423 1 Microsoft Way 424 Redmond, WA. 98053 425 USA 427 e-mail: {yarong, saveenr}@microsoft.com 429 15. Bibliography 431 [Goland et al., 1997] Y. Goland, E. J. Whitehead, Jr., Asad Faizi, 432 Stephen R. Carter, Del Jensen 'Extensions for Distributed Authoring 433 and Versioning on the World Wide Web -- WEBDAV', March 1997, 437 [RFC2068] R. Fielding, J. Gettys, J. Mogul, H. Frystyk, T. Berners- 438 Lee, 'Hypertext Transfer Protocol -- HTTP/1.1', RFC 2068, January 439 1997,