idnits 2.17.1 draft-ietf-webdav-depth-01.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-23) 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 59 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 154: '... resource MUST be submitted with the...' RFC 2119 keyword, line 162: '... the DELETE-TREE MUST be treated as a ...' RFC 2119 keyword, line 169: '... MUST NOT be deleted, so as to maint...' (11 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.) -- The document date (November 6, 1997) is 9665 days in the past. Is this intentional? 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 445 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: April 1998 Saveen Reddy 3 Microsoft Corporation 4 November 6, 1997 6 WebDAV Tree Operations 7 draft-ietf-webdav-depth-01.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 151 If a resource, source or destination, within scope of the *-TREE 152 method is locked in such a way as to prevent the successful 153 execution of the *-TREE method, then the lock token for that 154 resource MUST be submitted with the *-TREE request in the State- 155 Token request header. 157 9. DELETE-TREE Method 159 9.1. Request 161 The DELETE-TREE method is only meaningful on a collection. If used 162 on a non-collection the DELETE-TREE MUST be treated as a DELETE. 164 DELETE-TREE instructs that the collection specified in the request- 165 URI, the records of its external member resources, and all its 166 internal member resources, are to be deleted. 168 If any member can not be deleted then all of the member's progeny 169 MUST NOT be deleted, so as to maintain the namespace. 171 Any headers included with DELETE-TREE MUST be applied in processing 172 every resource to be deleted. In this case, a header of special 173 interest is the DESTROY header which specifies the method to be used 174 to delete all resources in the scope of the DELETE-TREE. 176 When the DELETE-TREE method has completed processing it MUST return 177 a consistent namespace. Please refer to [Goland et al., 1997] for a 178 full definition of a consistent namespace. 180 9.2. Response 182 The response SHOULD be a multi-status response that describes the 183 result of the DELETE-TREE on each effected resource. 185 [Editor's Note: The response to a TREE method could potentially be 186 huge, larger than a client may want or need to deal with. It has 187 been suggested that clients be given the ability to tell the server 188 they only want to get back a response code, not a response body. 189 Thoughts?] 191 9.3. Response Codes 193 415 Conflict - This can be used to indicate that some unspecified 194 problem has occurred which makes it impossible to delete a 195 particular resource. The most common scenario is that a new internal 196 member was added to a collection while a DELETE-TREE was running and 197 thus the collection can not be deleted. 199 9.4. Example 201 DELETE-TREE /container/ HTTP/1.1 202 Host: www.foo.bar 203 Destroy: 205 HTTP/1.1 207 Multi-Response 206 Content-Type: text/xml 207 Content-Length: xxxxx 209 210 211 212 http://www.foo.bar/container/resource1 213 http://www.foo.bar/container/resource2 214 HTTP/1.1 200 Success 215 216 217 http://www.foo.bar/container/ 218 HTTP/1.1 418 Method Failure 219 220 221 http://www.foo.bar/container/resource3 222 HTTP/1.1 412 Precondition Failed 223 224 226 In this example the attempt to delete 227 http://www.foo.bar/container/resource3 failed. Given that there is 228 only one precondition, one can figure out that the failure was 229 caused the inability of the system to meet the requirement of the 230 Destroy header. Normally however, the client will not know exactly 231 what precondition caused the failure. 233 The result is that container wasn't deleted because of the failure 234 to delete container/resource3. 236 [Ed-Note: To state the obvious, do we want to provide information on 237 which precondition actually failed? This is not the panacea it might 238 seem as the failure may have occurred for multiple reasons and 239 listing a bunch of headers may or may not be useful. Besides, the 240 reality is, nobody every pays attention to error codes. There are 241 really only two error codes in the world "It worked" or "Something 242 Went Wrong."] 244 10. COPY-TREE Method 246 10.1. Request 248 The COPY-TREE method is only meaningful on a collection. If used on 249 a non-collection the COPY-TREE MUST be treated as a COPY. 251 COPY-TREE instructs that the collection specified in the Request- 252 URI, the records of its external member resources, and all its 253 internal member resources, are to be copied to a location relative 254 to the Destination header. 256 Any headers included with COPY-TREE are to be applied in processing 257 every resource to be copied. 259 The exception to this rule is the Destination header. This header 260 only specifies the destination for the Request-URI. When applied to 261 members of the collection specified in the request-URI the value of 262 Destination is to be modified to reflect the current location in the 263 hierarchy. So, if the request-URI is "a" and the destination is "b" 264 then when a/c/d is processed it MUST use a destination of b/c/d. 266 When the COPY-TREE method has completed processing it MUST have 267 created a consistent namespace at the destination. Thus if it is not 268 possible to COPY a collection with internal members, the internal 269 members may still be copied but a collection will have to be created 270 at the destination to contain them. 272 Please refer to the definition of COPY in section XYZ of [Goland et 273 Al., 1997] for the rules on merging members and properties of source 274 collections with pre-existing collections at the destination. 276 10.2. Response 278 The response is a multi-status response that describes the result of 279 the COPY-TREE on each effected resource. The response is given for 280 the resource that was to be copied, not the resource that was 281 created as a result of the copy. In other words, each entry 282 indicates if the copy on the resource specified in the href 283 succeeded or failed and why. 285 The exception to this rule is for errors that occurred on the 286 destination. For example, if the destination was locked the response 287 would indicate the destination URL and a 416 "Locked" error. 289 10.3. Example 291 COPY-TREE /container/ HTTP/1.1 292 Host: www.foo.bar 293 Destination: http://www.foo.bar/othercontainer/ 294 Enforce-Live-Properties: * 296 HTTP/1.1 207 Multiresponse 297 Content-Type: text/xml 298 Content-Length: xxxxx 300 301 302 303 http://www.foo.bar/container/resource1 304 http://www.foo.bar/container/resource2 305 http://www.foo.bar/container/ 306 http://www.foo.bar/container/R2/D2 307 HTTP/1.1 201 Created 308 309 310 http://www.foo.bar/container/R2/ 311 HTTP/1.1 415 Precondition Failed 312 313 315 In this example most of the resources, along with the container, 316 were copied successfully. However the container R2 failed, most 317 likely due to a problem with enforcing live properties. R2's member 318 D3 was successfully copied. As a result a collection was created at 319 www.foo.bar/othercontainer/R2 to contain D2. 321 11. MOVE-TREE Method 323 11.1. Request 325 The MOVE-TREE method is only meaningful on a collection. If used on 326 a non-collection the MOVE-TREE MUST be treated as a MOVE. 328 MOVE-TREE instructs that the collection specified in the Request- 329 URI, the records of its external member resources, and all its 330 internal member resources, are to be moved to a location relative to 331 the Destination header. 333 Any headers included with MOVE-TREE are to be applied in processing 334 every resource to be moved. 336 The exception to this rule is the Destination header. The behavior 337 of this header is the same as given for COPY-TREE. 339 When the MOVE-TREE method has completed processing it MUST have 340 created a consistent namespace on both the source and destination, 341 creating collections at the source or destination as necessary. 343 As specified in the definition of MOVE, a MOVE of a collection over 344 another collection causes the destination collection and all its 345 members to be deleted. 347 11.2. Response 349 The response is a multi-status response that describes the result of 350 the MOVE-TREE on each effected resource. The response is given for 351 the resource that was to be moved, not the resource that was created 352 as a result of the move. In other words, each entry indicates if the 353 move on the resource specified in the href succeeded or failed and 354 why. 356 The exception to this rule is for errors that occurred on the 357 destination. For example, if the destination was locked the response 358 would indicate the destination URL and a 416 "Locked" error. 360 11.3. Example 362 MOVE-TREE /container/ HTTP/1.1 363 Host: www.foo.bar 364 Destination: http://www.foo.bar/othercontainer/ 365 Enforce-Live-Properties: * 366 Overwrite: False 367 State-Token: 369 HTTP/1.1 207 Multiresponse 370 Content-Type: text/xml 371 Content-Length: xxxxx 373 374 375 376 http://www.foo.bar/container/resource1 377 http://www.foo.bar/container/resource2 378 http://www.foo.bar/container/ 379 http://www.foo.bar/container/C2/R2 380 HTTP/1.1 201 Created 381 382 383 http://www.foo.bar/container/C2 384 HTTP/1.1 418 Method Failure 385 386 http://www.foo.bar/othercontainer/C2 387 HTTP/1.1 416 Locked 388 389 390 In this example the client has submitted a number of lock tokens 391 with the request. A lock token will need to be submitted for every 392 resource, both source and destination, anywhere in the scope of the 393 method, that is locked. In this case the proper lock token was not 394 submitted for the destination http://www.foo.bar/othercontainer/C2. 395 This means that the resource continer/c2 could not be copied, 396 although its child container/C2/R2 could be copied. 398 12. 102 "Processing" Response Code 400 The *-Tree methods can potentially take a long period of time to 401 process. In such cases the client may time-out the connection while 402 waiting for a response. To prevent this the server MAY return a 102 403 response code to indicate to the client that the server is still 404 processing the method. 406 If a method is taking longer than [INSERT NUMBER HERE] seconds to 407 process the server SHOULD return a 102 "Processing" response. 409 13. Status-URI Response Header 411 The Status-URI response header MAY be used with the 102 "Processing" 412 response code to inform the client as to the status of a method. 414 Status-URI = "Status-URI" ":" *(Status-Code "<" URI ">") ; Status- 415 Code is defined in 6.1.1 of [RFC2068] 417 The URIs listed in the header are source resources which have been 418 effected by the outstanding method. The status code indicates the 419 resolution of the method on the identified resource. So, for 420 example, if a COPY-TREE method is outstanding and a 102 "Processing" 421 response with a Status-URI response header is returned, the included 422 URIs will indicate resources that have had copy attempted on them 423 and what the result was. Note that including the URI does not 424 indicate the result of applying the method. 426 14. Author's Address 428 Yaron Y. Goland 429 Saveen Reddy 430 Microsoft Corporation 431 1 Microsoft Way 432 Redmond, WA. 98053 433 USA 435 e-mail: {yarong, saveenr}@microsoft.com 437 15. Bibliography 439 [Goland et al., 1997] Y. Goland, E. J. Whitehead, Jr., Asad Faizi, 440 Stephen R. Carter, Del Jensen 'Extensions for Distributed Authoring 441 and Versioning on the World Wide Web -- WEBDAV', March 1997, 445 [RFC2068] R. Fielding, J. Gettys, J. Mogul, H. Frystyk, T. Berners- 446 Lee, 'Hypertext Transfer Protocol -- HTTP/1.1', RFC 2068, January 447 1997,