* subversion/libsvn_fs_fs/structure
[svn.git] / www / webdav-usage.html
blob73c7dcb06e4d496c9b64f58ef7eded9420abecc2
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml">
4 <head>
5 <style type="text/css"> /* <![CDATA[ */
6 @import "branding/css/tigris.css";
7 @import "branding/css/inst.css";
8 /* ]]> */</style>
9 <link rel="stylesheet" type="text/css" media="print"
10 href="branding/css/print.css"/>
11 <script type="text/javascript" src="branding/scripts/tigris.js"></script>
12 <title>Use of WebDAV in Subversion</title>
13 </head>
15 <body>
16 <div class="app">
18 <h2>Use of WebDAV in Subversion</h2>
20 <p>
21 This document details how WebDAV is used within the
22 <a href="http://subversion.tigris.org/">Subversion
23 product</a>. Specifically, how the client side interfaces with
24 <a href="http://www.webdav.org/neon/">Neon</a> to generate
25 WebDAV requests over the wire, and what the
26 server must do to map incoming WebDAV requests into operations
27 against the Subversion repository. Note that the server side is
28 implemented as an
29 <a href="http://httpd.apache.org/">Apache 2.0</a> module,
30 operating as a back-end for its mod_dav functionality.
31 </p>
32 <p>
33 This document heavily refers to the
34 <a href="http://subversion.tigris.org/files/documents/15/17/svn-design.html">Subversion
35 design document</a> and the
36 <a href="http://www.webdav.org/deltav/">latest Delta-V protocol
37 draft</a>. Details of those documents will <em>not</em> be
38 replicated here.
39 </p>
41 <table width="70%" border="0" cellspacing="0" cellpadding="10"
42 style="background-color: #ff0000; color: white;
43 margin-left: auto; margin-right: auto">
44 <tr>
45 <td>
46 <strong>NOTE:</strong> Subversion uses DeltaV for its
47 communication, but the Subversion client is
48 <strong>not</strong> a general-purpose DeltaV client. In
49 fact, it expects some custom features from the
50 server. Further, the Subversion server is
51 <strong>not</strong> a general-purpose DeltaV server. It
52 implements a strict <strong>subset</strong> of the
53 DeltaV specification. A WebDAV or DeltaV client may very
54 well be able to interoperate with it, but only if that
55 client operates within the narrow confines of those
56 features the server has implemented.
57 </td>
58 </tr>
59 <tr>
60 <td>
61 Version 2.0 of Subversion will address WebDAV
62 interoperability (Class 1, Class 2, and DeltaV
63 features). Each of the custom features expected by the
64 client actually has an alternate mechanism available in
65 DeltaV, but in a much less efficient form.
66 </td>
67 </tr>
68 <tr>
69 <td>
70 It is expected that Version 1.0 will support read-only,
71 Class 1 WebDAV clients. Any "low-hanging fruit" to
72 increase DeltaV interoperability will be considered.
73 </td>
74 </tr>
75 </table>
77 <p></p>
79 <h3>Basic Concepts</h3>
80 <p>
81 Subversion uses a tree-based format to describe a change set
82 against the repository. This tree is constructed on the client
83 side (by "walking" over the working copy) to describe the
84 change. The tree is marshalled to the server as a linear
85 sequence of changes to be applied to the repository. The
86 repository can accept changes in a random-access manner, so the
87 mapping from a tree to a set of changes works very well for the
88 repository.
89 </p>
90 <p>
91 Subversion provides properties on files, directories, and even
92 the abstract concept of a revision. Each of the operations
93 involving properties are mapped directly to WebDAV properties,
94 which are manipulated with the <span
95 class="method">PROPFIND</span> and <span
96 class="method">PROPPATCH</span> HTTP methods. Revisions are
97 modeled as DeltaV <span class="term">baselines</span>, so
98 revision properties are available through a <span
99 class="method">PROPFIND</span> on the baseline.
100 </p>
102 The Subversion server can efficiently compute deltas between two
103 revisions (these deltas are complete <span class="term">tree
104 deltas</span>, not simple text deltas). DeltaV does not have a
105 direct analogue for the tree delta concept. A client could
106 discover changes by issuing a sequence of <span
107 class="method">PROPFIND</span> requests on the various WebDAV
108 resources, but this would be a time-consuming operation,
109 involving many requests. Instead, Subversion marshals this
110 concept as a custom WebDAV <span
111 class="term">report</span>. Using this report, the client learns
112 which items in the working copy are out of date and can issue
113 <span class="method">GET</span> and <span
114 class="method">PROPFIND</span> methods to fetch the new data.
115 </p>
117 Tags and branches are simple copies in Subversion, which are
118 handled with the WebDAV <span class="method">COPY</span>.
119 </p>
120 <blockquote class="comment">
121 <p>need to talk about copies somewhere. need to discuss how copy
122 history is retained (svn does it automatically, but interop with
123 other servers may require us to set a custom property on those
124 servers.</p>
125 </blockquote>
127 <h3>DeltaV Concepts Used by Subversion</h3>
129 Subversion uses many of the DeltaV concepts, as listed
130 below. Note that many of these concepts are not fully
131 implemented by Subversion; we have implemented enough to meet
132 our needs, but little more.
133 </p>
134 <dl>
135 <dt>Baseline</dt>
136 <dd>
137 <span class="comment">further info to come...</span><p></p>
138 </dd>
140 <dt>Activity</dt>
141 <dd>
142 <span class="comment">further info to come...</span><p></p>
143 </dd>
145 <dt>Version Resource</dt>
146 <dd>
147 <span class="comment">further info to come...</span><p></p>
148 </dd>
150 <dt>Version-Controlled Configuration</dt>
151 <dd>
152 <span class="comment">further info to come...</span><p></p>
153 </dd>
155 <dt>Baseline Collection</dt>
156 <dd>
157 <span class="comment">further info to come...</span><p></p>
158 </dd>
160 <dt>Version-Controlled Resource</dt>
161 <dd>
162 <span class="comment">further info to come...</span><p></p>
163 </dd>
165 <dt>Working Resource (Feature)</dt>
166 <dd>
167 <span class="comment">further info to come...</span><p></p>
168 </dd>
170 <dt>Merge Feature</dt>
171 <dd>
172 <span class="comment">further info to come...</span><p></p>
173 </dd>
175 <dt>Label Feature</dt>
176 <dd>
177 <span class="comment">further info to come...</span><p></p>
178 </dd>
180 <dt>Version-Controlled-Collection Feature</dt>
181 <dd>
182 <span class="comment">further info to come...</span><p></p>
183 </dd>
185 </dl>
187 <h3>Subversion Projects as URLs</h3>
189 The very first concept to define is how a project is exposed to
190 the client. Subversion will expose all projects as URLs on a
191 server. The files and subdirectories under this project will be
192 exposed through the URL namespace.
193 </p>
195 For example, let us assume that we have a project named
196 "example". And let us say that this project will be exposed at
197 the URL:
198 <span class="url">http://subversion.tigris.org/repos/example/</span>.
199 </p>
201 This mapping is set up through a set of configuration
202 parameters for the Apache HTTP Server (which is hosting the
203 Subversion code and the particular project in question). The
204 configuration could look like:
205 </p>
206 <blockquote>
207 <pre>&lt;Location /repos/example&gt;
208 DAV svn
209 SVNPath /home/svn-projects/example
210 &lt;/Location&gt;</pre>
211 </blockquote>
213 Files and directories within the project will be directly mapped
214 into the URL namespace. For example, if the project contains a
215 file "file.c" in a subdirectory "sub", then the URL for that
216 file will be
217 <span class="url">http://subversion.tigris.org/repos/example/sub/file.c</span>.
218 </p>
220 <h3>Initial Checkout</h3>
222 When the user performs the initial checkout of a Subversion
223 project, the client will issue a series of <span
224 class="method">PROPFIND</span> and <span
225 class="method">GET</span> requests. These requests will traverse
226 the repository, pick up some necessary metadata, and then fetch
227 the latest revision.
228 </p>
229 <p class="comment">
230 describe the OPTIONS request for fetching the activity
231 collection set. describe the sequence of PROPFINDs to reach the
232 baseline collection.
233 </p>
234 <p class="comment">
235 <i>(moved here from below; need to rewrite)</i><br/>
236 When the initial checkout was performed, Subversion fetched
237 the <span class="prop">DAV:activity-collection-set</span> value
238 and stored it as a property on each directory in the working copy.
239 property for each
240 collection. This property lists all of the locations on the
241 server where an activity may be created. The first of these
242 locations will be stored on the client for use during the commit
243 process.
244 </p>
245 <p class="comment">
246 Should probably describe the metadata we fetch, and how a
247 checkout of "not the latest" (e.g. by date or revision) will
248 work.
249 </p>
251 <h3>Committing a Change</h3>
253 Subversion commits are modeled using the "activity" concept from
254 DeltaV. An activity can be viewed as a transaction for a set of
255 resources.
256 </p>
258 <h3>Creating the activity</h3>
260 At commit time, the Subversion client will retrieve the stored
261 <span class="prop">DAV:activity-collection-set</span> value to
262 know where it should create the activity. Next,
263 the client will generate a UUID (a unique value) to use for the
264 activity's location. Finally, the client will issue a
265 <span class="method">MKACTIVITY</span> method request, where the Request-URL is
266 composed from the activity location and the UUID. This request
267 will construct an activity to hold all of the changes for the
268 commit.
269 </p>
270 <p>Abbreviated summary:</p>
271 <dl>
272 <dt>At checkout time:</dt>
273 <dd>
274 <div>Request: <span class="method">OPTIONS</span> for
275 <span class="prop">DAV:activity-collection-set</span></div>
276 <div>Response: <span
277 class="url">http://www.example.com/repos/foo/$svn/act/</span></div>
278 </dd>
279 <dt>At commit time:</dt>
280 <dd>
281 <div>Request: <span class="method">MKACTIVITY</span>
282 <span class="url">http://www.example.com/repos/foo/$svn/act/01234567-89ab-cdef-0123-456789abcdef</span></div>
283 <div>Response: 201 (Created)</div>
284 </dd>
285 </dl>
287 The <span class="method">CHECKOUT</span> method can specify an
288 activity to use upon checkout. This feature is used to associate
289 all items with the newly-created activity.
290 </p>
292 <h3>Storing the commit message</h3>
293 <p class="comment">
294 talk about checking out the baseline and applying a PROPPATCH to
295 the working baseline.
296 </p>
298 <h3>Mapping changes to WebDAV</h3>
300 A change set in Subversion is specified with a "tree delta" (see
301 the SVN design for more details on the changes that can be
302 placed into a tree delta). The tree delta will be unravelled
303 into a set of requests. These requests will be one of the
304 following forms:
305 </p>
306 <dl>
307 <dt>Delete file or directory</dt>
308 <dd>
309 These changes are mapped onto a <span
310 class="method">DELETE</span> operation. The version resource
311 of the target's parent collection is checked out using the
312 <span class="method">CHECKOUT</span> method (into the current
313 activity). The target (name) is then deleted from the
314 resulting working collection using the <span
315 class="method">DELETE</span> method.
317 <p></p>
318 </dd>
320 <dt>Add file</dt>
321 <dd>
322 This is modeled by performing a <span
323 class="method">CHECKOUT</span> of the version resource of the
324 target's parent collection. The new file is created within the
325 resulting working collection using a <span
326 class="method">PUT</span> request. Properties are applied
327 using <span class="method">PROPPATCH</span>.
329 <p></p>
330 </dd>
332 <dt>Add directory</dt>
333 <dd>
334 This is modeled by performing a <span
335 class="method">CHECKOUT</span> on the version resource of the
336 target's parent collection. The new directory is created
337 within the resulting working collection with a <span
338 class="method">MKCOL</span> request. Properties are applied
339 using <span class="method">PROPPATCH</span>.
341 <p></p>
342 </dd>
344 <dt>Add file or directory, with previous ancestory (a copy)</dt>
345 <dd>
346 <span class="comment">need to fix this section</span>
349 A tree delta can specify that a file/directory originates as
350 a copy of another file/dir. This copy may be further
351 modified by additional elements the tree delta.
352 </p>
354 This change will be modeled by performing a
355 <code>CHECKOUT</code> on the version resource of the parent
356 collection which will contain the new resource. The
357 <code>VERSION-CONTROL</code> method will create a new
358 version-controlled resource (VCR) within the working
359 collection, with the VCR's <code>DAV:checked-in</code>
360 property referring to the ancestor's version resource.
361 </p>
362 <blockquote>
363 <p><strong>Note:</strong> it appears that we will use
364 <code>COPY</code> to copy the appropriate resource into the
365 working collection. This will create a new version history
366 which is then placed into the working collection. The
367 version history will use the <code>DAV:precursor-set</code>
368 property to specify the version resource of the ancestor.</p>
371 Because a version resource does not specify the revision,
372 it will not be possible to <code>COPY</code> a version
373 resource into the working collection -- it will not tell
374 us what revision was copied. Instead, we will most likely
375 copy a version resource out of the appropriate
376 baseline. This implies the client must be able to map from
377 a URL/revision pair to a baselined version resource URL.
378 </p>
380 The second issue is whether/how we set the
381 <code>DAV:precursor-set</code> property of the version
382 history. Or, more precisely, how we synthesize the value
383 from information stored in the repository. This is still
384 under investigation.
385 </p>
386 </blockquote>
387 </dd>
389 <dt>Replace file/dir by another file/dir</dt>
390 <dd>
391 This change does not have a WebDAV modeling because tree
392 deltas model it as two, sequential operations: a
393 <em>delete</em>, followed by an <em>add</em>.
395 <p></p>
396 </dd>
398 <dt>Moving a file or directory</dt>
399 <dd>
400 This change does not have a WebDAV modeling because tree
401 deltas model it as two, distinct operations: a
402 <em>delete</em>, and an <em>add</em> with previous ancestry.
404 <p></p>
405 </dd>
407 <dt>Replace file</dt>
408 <dd>
409 This is modeled with a <span class="method">CHECKOUT</span> on
410 the target's version resource, followed by a <span
411 class="method">PUT</span> to the resulting working resource.
413 <p></p>
414 </dd>
416 <dt>Replace directory</dt>
417 <dd>
418 In Subversion terms, "replace directory" means that additions,
419 deletions, and other changes will occur <em>within</em> the
420 directory. Each of these changes are modeled individually, and
421 the change to the directory is performed
422 implicitly. Therefore, this "change" has no particular mapping
423 into WebDAV.
425 <p></p>
426 </dd>
428 <dt>Property delta</dt>
429 <dd>
430 A property delta (against a file or directory) maps directly
431 to a <span class="method">PROPPATCH</span> in WebDAV
432 terms. The target's version resource will be checked out using
433 <span class="method">CHECKOUT</span> and the <span
434 class="method">PROPPATCH</span> will be applied to the
435 resulting working resource.
436 </dd>
437 </dl>
439 <h3>Final Commit</h3>
441 The final action of the commit process is to issue a <span
442 class="method">MERGE</span> request to the Subversion server,
443 specifying that the activity (created earlier) be checked in and
444 the corresponding version-controlled resources be updated to
445 refer to the new version resources.
446 </p>
447 <p class="comment">
448 the comment below is not quite right. talk about the working
449 baseline, and how that is used to create a new baseline (with
450 the commit message on it)
451 </p>
453 The version-controlled resources are also baseline-controlled,
454 which means that updates to them will automatically create a new
455 baseline. In essence, the commit will create a new baseline
456 corresponding to the new Subversion revision.
457 </p>
459 <h3>Example</h3>
460 <p class="comment">
461 <strong>Warning:</strong> this section has not been updated to
462 reflect some recent changes to the SVN-to-DAV mapping. Consider
463 it out of date until this warning is removed.
464 </p>
466 Consider the following set of operations and its corresponding
467 tree delta (taken from the SVN design document):
468 </p>
469 <ol>
470 <li>rename <code>/dir1/dir2</code> to <code>/dir1/dir4</code>,</li>
471 <li>rename <code>/dir1/dir3</code> to <code>/dir1/dir2</code>, and</li>
472 <li>move <code>file3</code> from <var>/dir1/dir4</var> to <var>/dir1/dir2</var>.</li>
473 </ol>
474 <pre>&lt;tree-delta&gt;
475 &lt;replace name='dir1'&gt;
476 &lt;directory&gt;
477 &lt;tree-delta&gt;
478 &lt;replace name='dir2'&gt;
479 &lt;directory ancestor='/dir1/dir3'&gt; (1)
480 &lt;tree-delta&gt;
481 &lt;new name='file3'&gt; (2)
482 &lt;file ancestor='/dir1/dir2/file3'/&gt;
483 &lt;/new&gt;
484 &lt;/tree-delta&gt;
485 &lt;/directory&gt;
486 &lt;/replace&gt;
487 &lt;delete name='dir3'/&gt; (3)
488 &lt;new name='dir4'&gt; (4)
489 &lt;directory ancestor='/dir1/dir2'&gt;
490 &lt;tree-delta&gt;
491 &lt;delete name='file3'/&gt; (5)
492 &lt;/tree-delta&gt;
493 &lt;/directory&gt;
494 &lt;/new&gt;
495 &lt;/tree-delta&gt;
496 &lt;/directory&gt;
497 &lt;/replace&gt;
498 &lt;/tree-delta&gt;
499 </pre>
502 Walking through this delta, we map out the WebDAV requests
503 listed below. The numbers in the above delta roughly correspond
504 to the numbered entries below. The correspondence is not exact
505 because a specific, resulting behavior is typically based on a
506 combination of a few elements in the delta.
507 </p>
508 <ol>
509 <li>
510 The <code>&lt;directory ancestor="/dir1/dir3"&gt;</code>
511 specifies that we are overwriting <code>/dir1/dir2</code> with
512 <code>/dir1/dir3</code>.
514 <code>CHECKOUT&nbsp;/dir1/dir2/</code><br/>
515 <i>(returns a working resource URL for the directory)</i>
516 </p>
518 <code>COPY&nbsp;/dir1/dir3/</code><br/>
519 <code>Destination:&nbsp;http://www.example.com/$svn/wrk/.../</code><br/>
520 <code>Overwrite:&nbsp;T</code>
521 </p>
522 </li>
523 <li>
524 <code>/dir1/dir2/file3</code> is new (since we just overwrote
525 the original <code>dir2</code> directory), and originates from
526 <code>/dir1/dir2/file3</code>. Thus, we simply
527 <code>COPY</code> the file into the target directory's working
528 resource:
530 <code>COPY&nbsp;/dir1/dir2/file3</code><br/>
531 <code>Destination:&nbsp;http://www.example.com/$svn/wrk/.../file3</code>
532 </p>
533 </li>
534 <li>
536 <code>CHECKOUT&nbsp;/dir1/dir3/</code><br/>
537 <i>(returns a working resource URL for the directory)</i>
538 </p>
540 <code>DELETE&nbsp;/$svn/wrk/.../</code>
541 </p>
542 </li>
543 <li>
544 We are going to creating a new subdirectory (<code>dir4</code>) in the
545 <code>/dir1</code> directory. Since we don't have
546 <code>/dir1</code> checked out yet, we do so:
548 <code>CHECKOUT&nbsp;/dir1/</code><br/>
549 <i>(returns a working resource URL for the directory)</i>
550 </p>
552 And now we copy the right directory into the new working
553 resource:
554 </p>
556 <code>COPY&nbsp;/dir1/dir2/</code><br/>
557 <code>Destination:&nbsp;http://www.example.com/$svn/wrk/.../dir4/</code>
558 </p>
559 </li>
560 <li>
561 The <code>COPY</code> created a complete set of working
562 resources on the server, so we simply delete the part that we
563 don't want:
565 <code>DELETE:&nbsp;/$svn/wrk/.../dir4/file3</code>
566 </p>
567 </li>
568 </ol>
570 <h3>URL Layout</h3>
572 The Subversion server exposes repositories at user-defined
573 URLs. For example, the "foo" repository might be located at
574 <span
575 class="url">http://www.example.com/repos/foo/</span>. However,
576 the server also requires a number of other resources to be
577 exposed for proper operation. These additional resources will be
578 associated with each repository in a location under the main
579 repository URL. By default, this location is "<span
580 class="url">$svn</span>". It may be changed by using the
581 <code>SVNSpecialURI</code> directive:
582 </p>
583 <blockquote>
584 <pre>&lt;Location /repos/foo&gt;
585 DAV svn
586 SVNPath /home/svn-projects/foo
587 SVNSpecialURI .special
588 &lt;/Location&gt;</pre>
589 </blockquote>
591 Underneath the location specified by <code>SVNSpecialURI</code>,
592 we will expose several collections. Assuming we use the default
593 of "<span class="url">$svn</span>", the collections are:
594 </p>
595 <dl>
596 <dt><span class="url">$svn/act/</span></dt>
597 <dd>
598 This area is where activity resources are created. The client
599 will pick a unique name within this collection and issue a
600 <span class="method">MKACTIVITY</span> for that URL. The client will then use
601 the activity in further interactions.
603 No methods are allowed on the <span class="url">$svn/act/</span>
604 resource.
605 </p>
606 <blockquote>
607 <p>Note: actually, we may want to allow a <code>PROPFIND</code>
608 with a <code>Depth:&nbsp;1</code> header to allow clients to
609 enumerate the current activities.</p>
610 </blockquote>
612 Only a subset of methods are allowed on the activities
613 within the collection. They are: <span class="method">PROPFIND</span>,
614 <span class="method">MERGE</span> (commit the activity), and
615 <span class="method">DELETE</span> (abort the activity).
616 </p>
618 Per the Delta-V specification, all activity resources will
619 have a <span class="prop">DAV:resourcetype</span> of
620 <span class="prop">DAV:activity</span>.
621 </p>
622 </dd>
624 <dt><span class="url">$svn/his/</span></dt>
625 <dd>
626 <span class="comment">do something with this section; we
627 actually don't use version history resources. in the future,
628 they might be modeled like this</span>
631 This collection contains the version history resources for
632 files and directories in a project. Its internal layout is
633 completely server-defined. Clients will receive URLs into
634 this collection (or a subcollection) from various responses.
635 </p>
637 No methods are allowed on the <span class="url">$svn/his/</span>
638 resource.
639 </p>
641 Internally, the URL namespace is laid out with URLs of the
642 following form:
643 </p>
644 <blockquote class="url">
645 <p>$svn/his/<var>node-id</var></p>
646 </blockquote>
648 The <var>node-id</var> is an internal value
649 that Subversion uses to reference individual files and
650 directories. This <var>node-id</var> is a single integer
651 defined by the Subversion repository. Note that this is an
652 undotted node id, which is the base for the entire history
653 of a given node in the repository.
654 </p>
656 The <span class="prop">DAV:resourcetype</span> of the <var>node-id</var>
657 collection is <span class="prop">DAV:version-history</span>.
658 </p>
659 <blockquote class="comment">
660 <p><strong>Note:</strong> the above information is probably not
661 quite correct. The issue of linking one version history to
662 another is still open. Further, I think that node 73 and
663 node 73.4.1 are each version histories (where the latter is
664 linked to the former). 73.x and 73.4.1.x are the versions
665 within the version history.</p>
666 </blockquote>
667 </dd>
669 <dt><span class="url">$svn/ver/</span></dt>
670 <dd>
671 This collection contains the version resources for the
672 project.
675 No methods are allowed on the <span class="url">$svn/ver/</span>
676 resource.
677 </p>
679 The layout of this collection is internal to the server. For
680 reference purposes here (and to describe the
681 implementation), it is laid out as:
682 </p>
683 <blockquote class="url">
684 <p>$svn/ver/<var>node-id</var>/<var>path</var></p>
685 </blockquote>
687 Only read-only methods are allowed against these resources
688 (e.g. <span class="method">GET</span>, <span class="method">PROPFIND</span>,
689 <span class="method">REPORT</span>); all other methods are illegal.
690 </p>
692 The <span class="prop">DAV:resourcetype</span> of a version resource is
693 simply the value of the resource at checkin time
694 (e.g. <code>&lt;D:resourcetype/&gt;</code> or
695 <code>&lt;D:resourcetype&gt;&lt;D:collection/&gt;&lt;/D:resourcetype&gt;</code>).
696 </p>
697 </dd>
699 <dt><span class="url">$svn/wrk/</span></dt>
700 <dd>
701 This collection contains working resources for the resources
702 that have been checked out with the <span class="method">CHECKOUT</span>
703 method. The form and construction of this collection is
704 server-defined, but is also well-defined so that clients may
705 interact properly with collection versions that have been
706 checked out.
708 No methods are allowed on the <span class="method">$svn/wrk/</span>
709 resource.
710 </p>
712 For reference purposes, the working resource URLs are
713 constructed as:
714 </p>
715 <blockquote class="url">
716 <p>$svn/wrk/<var>activity</var>/<var>path</var></p>
717 </blockquote>
719 Any method is allowed on the working resources, but no
720 methods are allowed on any of its parents.
721 </p>
723 The <span class="prop">DAV:resourcetype</span> of the working resources
724 follows normal resource typing:
725 <code>&lt;D:resourcetype/&gt;</code> for regular working
726 resources, and
727 <code>&lt;D:resourcetype&gt;&lt;D:collection/&gt;&lt;/D:resourcetype&gt;</code>
728 for working collections.
729 </p>
730 </dd>
732 <dt><span class="url">$svn/vcc/</span></dt>
733 <dd>
734 <span class="comment">This section is not yet complete.</span>
737 version-controlled configuration...
738 </p>
741 <code>$svn/vcc/root</code> as a singleton.
742 </p>
743 </dd>
745 <dt><code>$svn/bln/</code></dt>
746 <dd>
747 <span class="comment">This section is not yet complete.</span>
750 baselines...
751 </p>
754 <code>$svn/bln/<var>rev</var>/</code>
755 </p>
756 </dd>
758 <dt><code>$svn/wbl/</code></dt>
759 <dd>
760 <span class="comment">This section is not yet complete.</span>
763 working baseline...
764 </p>
765 </dd>
767 <dt><code>$svn/bc/</code></dt>
768 <dd>
769 <span class="comment">This section is not yet complete.</span>
772 baseline collection...
773 </p>
774 </dd>
775 </dl>
777 <h3>Property Management (and History/Log Reporting)</h3>
778 <p class="comment">
779 this section needs to be reworked. the properties occur on the
780 FS revisions (and exposed via baselines).
781 </p>
783 As mentioned before, Subversion properties map onto WebDAV
784 properties. For history/log reporting, the following WebDAV
785 properties will be applied to each baseline (a Subversion
786 revision) and to each version resource created by the
787 revision. Since these resources are all version resources, the
788 properties below are read-only.
789 </p>
790 <dl>
791 <dt><code>DAV:comment</code></dt>
792 <dd>
793 This is the standard (dead) property for specifying a checkin
794 comment.
795 <p></p>
796 </dd>
797 <dt><code>DAV:creator-displayname</code></dt>
798 <dd>
799 This is a (dead) property that is generated from Subversion's
800 concept of the "user" who made a particular change.
801 <p></p>
802 </dd>
803 <dt><code>DAV:creationdate</code></dt>
804 <dd>
805 This is a read-only live property created by the server at
806 commit time.
807 </dd>
808 </dl>
810 The history for a specified file will be generated using the
811 <code>REPORT</code> method and a
812 <code>DAV:property-report</code> report. A typical history will
813 fetch the three properties mentioned above for each version of
814 the file/directory.
815 </p>
817 Based on the client design, it may be important to specify other
818 read-only live properties for information about versions. For
819 example, how many lines were added/removed in a particular
820 checkin for a file? Creating these live properties will be quite
821 straight-forward, and driven by the client design over time.
822 </p>
823 <blockquote>
824 <p>Note: if we do this, however, then we'd end up tying the client
825 to the server. Of course, if the client were run against another
826 DeltaV server which didn't report these properties, then we'd
827 simply not display them in the UI. (e.g. graceful degradation of
828 functionality)</p>
829 </blockquote>
831 <h3>Fetching Status and Updates</h3>
833 After the initial checkout, the client can request a status
834 report (what has been changed on the client, pending a commit;
835 what has been changed on the server, pending an update). The
836 update process is similar, except that we also fetch the changes
837 from the server.
838 </p>
840 The local changes can be handled entirely on the client
841 side. The Working Copy library can easily handle the detection
842 and reporting of these changes. We're concerned with efficiently
843 detecting what has changed on the server.
844 </p>
846 While it would be possible to traverse the repository, fetching
847 the current state, and comparing that to the client state, it
848 would not be efficient. The Subversion design enables the server
849 to easily compute what has changed (relative to the client), if
850 it is given a description of the client state.
851 </p>
853 The core of the <em>status</em> and <em>update</em> commands is
854 based on a custom Subversion-specific WebDAV report. This custom
855 report will transmit the state of the working copy to the
856 server, and the server response will specify which resources
857 will need to be updated (fetched).
858 </p>
860 The request is a standard <code>REPORT</code> request, with a
861 custom XML body. The body will use the standard Subversion
862 technique of reporting a top-level revision number, and then
863 only reporting children that have different revisions. The
864 result of the report will use the same technique of reporting
865 only the resources where a change is found. If a change is
866 found, the server will provide a URL to the version resource to
867 fetch for the changed resource. The server will also report the
868 current revision number.
869 </p>
870 <blockquote class="comment">
871 <p>The XML DTDs for the request and response are TBD.</p>
872 </blockquote>
873 <blockquote>
874 <p><small>
875 The custom report will tie the client to only those servers
876 which support the report, but a future version of the software
877 will contain a fallback codepath, a graceful degradation, to
878 support other DeltaV servers.
879 </small></p>
880 </blockquote>
882 When an updated is performed, the client will fetch each of the
883 URLs (using <code>GET</code> requests) provided in the server
884 response.
885 </p>
887 <code>GET</code> (and <code>PUT</code>) operations will transfer
888 content in a "diff" format when possible. The mechanics of this
889 will follow the Internet Draft, titled
890 <a href="http://www.ietf.org/internet-drafts/draft-mogul-http-delta-10.txt">Delta Encoding in HTTP</a>.
891 </p>
893 <h3>Entity Tags (etags)</h3>
895 Etags are required to be unique across all versions of a
896 resource. Luckily, this
897 is very easy for a version control system. Each etag will be
898 simply be the repository's <em>node-id</em> for the resource.
899 </p>
901 Etags are used to generate diffs, following the guidelines in
902 the aforementioned draft:
903 <a href="http://www.ietf.org/internet-drafts/draft-mogul-http-delta-10.txt">Delta Encoding in HTTP</a>.
904 The problem then becomes how to get the etag for each file
905 stored on the client (we don't need etags for directories since
906 we never fetch them). During a <em>checkout</em> or
907 <em>update</em> process, this is easy: the etag is provided in
908 the HTTP response headers for each file retrieved.
909 </p>
911 The other part of the problem is getting the etag after a
912 <em>commit</em> has occurred. The <code>MERGE</code> response
913 provides a way to request properties from the version resources
914 which are created as part of the checkin of the activity. The
915 etag (and other properties) can be fetched using that mechanism.
916 </p>
918 <h3>Tags and Branches</h3>
920 Tags and branches within Subversion are performed by copying
921 from one area to another. For example:
922 </p>
923 <blockquote>
924 <pre>
925 [.../src/my-project]$ svn cp trunk tags/1.0.3-rc4
926 [.../src/my-project]$ svn commit
927 </pre>
928 </blockquote>
930 In the above example, <code>tags/1.0.3-rc4</code> should now be
931 considered readonly and will always reflect the status of
932 <code>trunk</code>.
933 </p>
935 These copies are handled just like a regular commit. An activity
936 is created with <span class="method">MKACTIVITY</span>, a
937 working resource is created via <span
938 class="method">CHECKOUT</span> (for the target directory;
939 <code>tags/</code> in our example above), and then a <span
940 class="method">COPY</span> is performed. The activity is then
941 merged back into the repository with a <span
942 class="method">MERGE</span> request.
943 </p>
945 <h3>Server Requirements</h3>
946 <p class="comment">
947 <strong>Warning:</strong> this section is out of date. The
948 DeltaV draft has gone through a number of revisions, and our use
949 of DeltaV has changed some.
950 </p>
952 <h3>DAV Methods</h3>
954 The server will need to implement the following WebDAV methods
955 for proper operation:
956 </p>
957 <ul>
958 <li><span class="method">OPTIONS</span></li>
959 <li><span class="method">GET</span></li>
960 <li><span class="method">DELETE</span></li>
961 <li><span class="method">COPY</span></li>
962 <li><span class="method">PROPPATCH</span></li>
963 <li><span class="method">PROPFIND</span></li>
965 <li><span class="method">MKACTIVITY</span></li>
966 <li><span class="method">CHECKOUT</span></li>
967 <li><span class="method">MERGE</span></li>
968 <li><span class="method">REPORT</span></li>
969 </ul>
971 The following methods are not required by Subversion at this
972 time:
973 </p>
974 <ul>
975 <li><span class="method">CHECKIN</span></li>
976 <li><span class="method">UNCHECKOUT</span></li>
977 <li><span class="method">UPDATE</span></li>
978 <li><span class="method">LABEL</span></li>
979 <li><span class="method">VERSION-CONTROL</span></li>
980 <li><span class="method">BASELINE-CONTROL</span></li>
981 <li><span class="method">MKWORKSPACE</span></li>
982 </ul>
984 <h3>DAV Properties</h3>
986 The following DeltaV properties will be implemented:
987 </p>
988 <ul>
989 <!-- resource properties -->
990 <li><span class="prop">DAV:comment</span></li>
991 <li><span class="prop">DAV:creator-displayname</span></li>
992 <li><span class="prop">DAV:supported-method-set</span></li>
993 <li><span class="prop">DAV:supported-live-property-set</span></li>
994 <li><span class="prop">DAV:supported-report-set</span></li>
995 <li><span class="prop">DAV:version-controlled-configuration</span></li>
997 <!-- version-controlled resource properties -->
998 <li><span class="prop">DAV:checked-in</span></li>
999 <li>
1000 <span class="prop">DAV:auto-version</span> is a readonly,
1001 empty element (auto versioning not supported).
1002 </li>
1004 <!-- checked-out resource properties -->
1005 <li><span class="prop">DAV:checked-out</span></li>
1006 <li>
1007 <span class="prop">DAV:predecessor-set</span>
1008 <div><i>
1009 Note: the Subversion design document is not clear on the
1010 mechanics of how multiple predecessors are merged to create
1011 a single, new revision. When this clarifies, then
1012 <code>DAV:predecessor-set</code> may end up containing more
1013 than zero or one predecessor URLs
1014 </i></div>
1015 </li>
1017 <!-- version resource properties -->
1018 <!-- predecessor-set -->
1019 <li>
1020 <span class="prop">DAV:version-name</span> is simply the
1021 (global) revision number.
1022 </li>
1023 <li><span class="prop">DAV:checkout-fork</span></li>
1024 <li><span class="prop">DAV:checkin-fork</span></li>
1026 <!-- checked-out (working resource) properties -->
1027 <!-- checkout-fork, checkin-fork -->
1028 <li><span class="prop">DAV:auto-update</span></li>
1029 <li>
1030 <span class="prop">DAV:subbaseline-set</span> is a readonly,
1031 empty property (sub-baselines not supported).
1032 </li>
1033 <li>
1034 <span class="prop">DAV:unreserved</span> is set to
1035 <code>F</code>.
1036 </li>
1038 <!-- vcc properties -->
1039 <li><span class="prop">DAV:baseline-controlled-collection</span></li>
1041 <!-- baseline properties -->
1042 <!-- subbaseline-set -->
1043 <li><span class="prop">DAV:baseline-collection</span></li>
1045 <!-- activity properties -->
1046 <li>
1047 <span class="prop">DAV:subactivity-set</span> is a readonly,
1048 empty property (sub-activities not supported).
1049 </li>
1051 <!-- version-controlled collection properties -->
1052 <li>
1053 <span class="prop">DAV:eclipsed-set</span> is always empty
1054 (internal members can never be eclipsed).
1055 </li>
1056 </ul>
1059 Contrary to the DeltaV specification, the following required
1060 properties will not be implemented:
1061 </p>
1062 <ul>
1063 <li>
1064 <span class="prop">DAV:successor-set</span> - this may be an
1065 expensive operation to synthesize this value.
1066 </li>
1067 <li>
1068 <span class="prop">DAV:checkout-set</span> - we do not record
1069 what has actually been checked out, but use the working
1070 resource URL to provide the necessary information; thus we
1071 have no record of the data to populate this property.
1072 </li>
1073 <li>
1074 <span class="prop">DAV:merge-set</span> - our <span
1075 class="method">MERGE</span> method is solely to support a
1076 commit. It doesn't really support the arbitrary merging
1077 defined within the spec.
1078 </li>
1079 <li>
1080 <span class="prop">DAV:auto-merge-set</span> - same as for
1081 <span class="prop">DAV:merge-set</span>.
1082 </li>
1083 <li>
1084 <span class="prop">DAV:activity-version-set</span> -
1085 activities are only used for working resources, so versions
1086 cannot be part of an activity.
1087 <div><i>maybe this should be defined as the empty set?</i></div>
1088 </li>
1089 <li>
1090 <span class="prop">DAV:activity-checkout-set</span>
1091 activities are only used for working resources, and we do not
1092 record what working resources "exist".
1093 </li>
1094 <li>
1095 <span class="prop">DAV:activity-set</span> -
1096 activities are only used for working resources, so versions
1097 cannot be part of an activity.
1098 <div><i>maybe this should be defined as the empty set?</i></div>
1099 </li>
1100 <li>
1101 <span class="prop">DAV:version-controlled-binding-set</span> -
1102 we do not have version history resources to include in the
1103 property.
1104 </li>
1105 </ul>
1107 <h3>OPTIONS</h3>
1109 The <span class="method">OPTIONS</span> request will signal that
1110 it supports the following DAV features:
1111 </p>
1112 <ul>
1113 <li><code>1</code></li>
1114 <li><code>2</code></li>
1115 <li><code>version-control</code></li>
1116 <li><code>checkout</code></li>
1117 <li><code>working-resource</code></li>
1118 <li><code>merge</code></li>
1119 <li><code>baseline</code></li>
1120 <li><code>activity</code></li>
1121 <li><code>version-controlled-collection</code></li>
1122 </ul>
1124 <h3>Reports</h3>
1126 The <span class="prop">DAV:supported-report-set</span> property
1127 will signal support for the following reports:
1128 </p>
1129 <ul>
1130 <li>svn:update-report</li>
1131 <li>svn:log-report</li>
1132 </ul>
1134 These reports are available only on the "public" resources (the
1135 VCRs). They are not available on the resources within the
1136 <span class="url">$svn/</span> area.
1137 </p>
1139 <h3>Notes, reminders</h3>
1141 Discuss timeouts and auto-purge of activities (and the related
1142 working resources).
1143 <br/>
1144 Discuss the activity database maintained by mod_dav_svn.
1145 <br/>
1146 Discuss other implementation details of ra_dav and mod_dav_svn.
1147 </p>
1149 <h3><a name="rationale">Appendix A: Rationale</a></h3>
1151 Several times, people have asked, "Why choose
1152 HTTP/WebDAV/DeltaV? That seems awfully bloated and
1153 ill-suited. Why didn't you design a custom, well-tuned protocol?
1154 Or maybe use the CVS protocol?" Listed below are a number of
1155 reasons for our choice of WebDAV as our network protocol.
1156 </p>
1158 <blockquote>
1159 <p><small>
1160 While this list could certainly be expanded with more reasons
1161 (and to be fair, with a list of reasons why WebDAV was a poor
1162 choice), it certainly demonstrates the basic reasons for our
1163 choice.
1164 </small></p>
1165 </blockquote>
1167 <blockquote>
1168 <p><small>
1169 Note: this list came from an email note, so the tone and point
1170 of view might be a bit off. Further word-smithing is
1171 welcome...
1172 </small></p>
1173 </blockquote>
1175 <h3>Builtin web browsing of the repository</h3>
1176 <blockquote>
1177 <p>For example, take a
1178 look at:
1179 <a href="http://svn.collab.net/repos/svn/trunk/README">http://svn.collab.net/repos/svn/trunk/README</a>
1180 (that's the HEAD right there; we also have URLs for every
1181 previous revision of every file)</p>
1182 </blockquote>
1184 <h3>DAV-based browsing</h3>
1185 <blockquote>
1186 <p>Use Web Folders or WebDrive or somesuch on
1187 your Windows box (or Windows XP's native DAV mounts) to browse
1188 the SVN repository with Windows Explorer. Mac OS X has builtin
1189 DAV server mounting. Nautilus has DAV capabilities. Then you
1190 have your Open Source tools such as cadaver, Goliath, etc.</p>
1191 </blockquote>
1193 <h3>People can use existing libraries</h3>
1194 <blockquote>
1195 <p>I couldn't even begin to count the number of HTTP tools and
1196 libraries available. If we had designed our own protocol, then
1197 we would have /none/ of those benefits. Heck, two HTTP library
1198 implementors (Joe Orton of Neon, and Daniel Stenberg of CURL)
1199 are regulars here. we wouldn't get that benefit. I've used
1200 Python's httplib (and a davlib of my own) to do a lot of testing
1201 of our server. No need to go and roll new protocol libraries.</p>
1202 </blockquote>
1204 <h3>Existing tools</h3>
1205 <blockquote>
1206 <p>One word: Ethereal :-) When we capture network traces, Ethereal
1207 already knows about HTTP. It's quite nice, but I know there are
1208 even better ones out there. But we also have other tools like
1209 squid and other (caching) proxies (see the next item).</p>
1210 </blockquote>
1212 <h3>Caching proxies</h3>
1213 <blockquote>
1214 <p>Subversion will work great with caching proxies. There is no
1215 longer a need for specialized tools like "cvsup". Just drop in a
1216 caching proxy, and you've already got your distributed read-only
1217 repository. That European dev team can just drop in the cache
1218 between them and the US server and their checkouts/updates will
1219 get cached for the benefit of the other team members. Commits
1220 will flow through, back to the US-based server.</p>
1221 </blockquote>
1223 <h3>Sophisticated and broad-choice authentication</h3>
1224 <blockquote>
1225 <p>We don't have to reimplement an authentication scheme for a new
1226 protocol. We can use all of the various schemes that have been
1227 defined for HTTP. Ever look at the CVS protocol? Ever see the "I
1228 Love You" or "I Hate You" lines? :-) That is all part of
1229 creating a new authentication scheme. But we get to use SSL and
1230 certificate-based auth if we want. Kerberos. NTLM. or even just
1231 simple Basic or Digest. And our users can come from text files,
1232 database, LDAP, or PAM. We don't have to reinvent the wheel cuz
1233 it is all available for Apache already.</p>
1234 </blockquote>
1236 <h3>Awesome network server</h3>
1237 <blockquote>
1238 <p>We don't have to worry about how to portably set TCP_CORK for
1239 optimal network packets. We don't have to worry about when
1240 sendfile() makes sense, or if it is available. We don't have to
1241 worry about dropped client connections, how to best use threads
1242 and processes to scale, request management, monitoring, logging,
1243 etc. Apache gives us all of that and a ton more. I *really*
1244 would not want to do that through xinetd. I mean... setting
1245 TCP_CORK on stdout? freaky :-)</p>
1246 </blockquote>
1248 <h3>Well-defined on-wire compression</h3>
1249 <blockquote>
1250 <p>We already have on-wire compression, similar to CVS's "-z#"
1251 switch. And we didn't do anything. The client library and server
1252 that we use just support it automatically for us, according to
1253 RFC 2616.</p>
1254 </blockquote>
1256 <h3>Future interoperability</h3>
1257 <blockquote>
1258 <p>In the future, we'll be able to interoperate with a multitude of
1259 IDEs and other WebDAV/DeltaV clients. As DeltaV becomes more
1260 prevalent, IDEs could very well use it for source code
1261 management, and we'll be right there without needing to write
1262 some MS/SCC library to interface to the tool.</p>
1263 </blockquote>
1265 <hr/>
1266 <address><a href="mailto:gstein@lyra.org">Greg Stein</a></address>
1267 <!-- Created: Thu Aug 10 19:14:20 PDT 2000 -->
1268 <!-- hhmts start -->
1269 Last modified: Fri Jan 25 12:54:20 PST 2002
1270 <!-- hhmts end -->
1272 </div>
1273 </body>
1274 </html>