notes/webdav-protocol

   1 This file documents Subversion's use of the WebDAV/DeltaV protocol.
   2
   3
   4 IMPORTANT RFCs and LINKS
   5 ========================
   6
   7   * RFC 2518  (WebDAV)
   8
   9   * RFC 3253  (DeltaV)
  10
  11   * Subversion's limited uses of DeltaV, as well as interoperability
  12     issues, are explained in the "WebDAV" appendix of the free
  13     Subversion book (at http://svnbook.red-bean.com)
  14
  15
  16
  17
  18 HTTP METHODS USED, indexed by svn commands that access network
  19 ==============================================================
  20
  21
  22 Read Commands  :  (OPTIONS, PROPFIND, GET, REPORT)
  23 -------------
  24
  25   Most commands have to resolve peg-revisions before starting:
  26
  27   * -r X foo@Y      REPORT                        ('get-locations')
  28
  29        ...if an old server doesn't support 'get-locations' report, the
  30        client traces history using the 'log-report' instead.
  31
  32   And any command which has to convert a date to a revision:
  33
  34   * -r {DATE}       REPORT                        ('dated-rev-report')
  35
  36
  37   The following group of commands all use the custom 'update-report'
  38   request, which is just a fancy way of driving svn_repos_dir_delta():
  39
  40   * svn checkout / svn export / svn update:
  41    (do_update RA interface)
  42
  43      ra_neon:       PROPFIND, REPORT              ('update-report' w/send-all)
  44
  45      ra_serf:       PROPFIND, REPORT              ('update-report')
  46                     ... then many PROPFIND/GETs on many parallel connections
  47
  48     svn update only                               ('merge-info-report')
  49
  50   * svn switch:     OPTIONS, PROPFIND, REPORT     ('update-report',
  51                                                    'merge-info-report')
  52
  53   * svn diff:       OPTIONS, PROPFIND, REPORT     ('update-report')
  54                     ... then many GETs
  55
  56   * svn merge:      OPTIONS, PROPFIND, REPORT     ('update-report',
  57                                                    'merge-info-report')
  58                     ... then many GETs
  59
  60   * svn status -u:  OPTIONS, PROPFIND, REPORT     ('update-report' and
  61                                                    'get-locks-report')
  62
  63   * svn cp URL wc:  OPTIONS, PROPFIND, REPORT     ('update-report')
  64                     (this is just like checkout)
  65
  66
  67   And these guys are left over:
  68
  69   * svn log:        OPTIONS, PROPFIND, REPORT     ('log-report')
  70
  71   * svn blame:      OPTIONS, PROPFIND, REPORT     ('file-revs-report')
  72                     [older clients use GET
  73                      and different REPORT]        ('log-report')
  74
  75   * svn ls:         PROPFIND
  76
  77   * svn ls -v:      PROPFIND, REPORT              ('get-locks-report')
  78
  79   * svn cat:        PROPFIND, GET
  80
  81   * svn info URL:   PROPFIND
  82
  83   * svn plist URL:  PROPFIND
  84
  85   * svn pget URL:   PROPFIND
  86
  87
  88
  89
  90 Write Commands  :  (MKACTIVITY, PROPPATCH, PUT, CHECKOUT, MKCOL, MOVE,
  91 --------------      COPY, DELETE, LOCK, UNLOCK, MERGE)
  92
  93   With the exception of LOCK/UNLOCK, every write command performs some
  94   sort of DeltaV commit operation.  In DeltaV, a commit always starts
  95   by creating a transaction (MKACTIVITY), applies a log message
  96   (PROPPATCH), does some other write methods, and then ends by
  97   committing the transaction (MERGE).  If the MERGE fails, the client
  98   may try to remove the transaction with a DELETE.
  99
 100   * svn commit:
 101      ra_neon:       OPTIONS, PROPFIND, MKACTIVITY,
 102                     {CHECKOUT, COPY, MOVE, DELETE, PROPPATCH, PUT, MKCOL},
 103                     MERGE (DELETE)
 104
 105      ra_serf:       OPTIONS to acquire activity collection set
 106      (no major      MKACTIVITY to a unique UUID relative to activity set
 107       differences)  PROPFIND to get what we think our baseline is
 108                     CHECKOUT of baseline revision into activity
 109                     Setting log: PROPPATCH on root directory
 110                     Delete a file: CHECKOUT file / DELETE
 111                     Add a dir:  MKCOL
 112                     Add a file: CHECKOUT parent dirs / PUT raw-file
 113                     Edit a file: CHECKOUT file / PUT svndiff stream
 114                     End commit: MERGE activity, DELETE activity
 115
 116   * svn import:     OPTIONS, PROPFIND, MKACTIVITY,
 117                     {PROPPATCH, PUT, MKCOL},
 118                     MERGE (DELETE)
 119
 120   * svn lock:       PROPFIND, LOCK
 121
 122   * svn unlock:     PROPFIND, UNLOCK
 123
 124   * svn cp URL URL: OPTIONS, PROPFIND, MKACTIVITY, PROPPATCH,
 125                     COPY, MERGE.  (DELETE)
 126
 127   * svn mv URL URL: OPTIONS, PROPFIND, MKACTIVITY, PROPPATCH,
 128                     COPY, DELETE, MERGE.  (DELETE)
 129
 130   * svn rm URL:     OPTIONS, PROPFIND, MKACTIVITY, PROPPATCH, DELETE, MERGE.
 131
 132   * svn mkdir URL:  OPTIONS, PROPFIND, MKACTIVITY, PROPPATCH, MKCOL, MERGE.
 133
 134   * svn pset --revprop:  PROPPATCH
 135
 136 Remembering Our Location
 137 ========================
 138
 139 For a file in our WC, both ra_serf and ra_neon will store the checked-in href
 140 (where the original text-base and properties can be found) in the
 141 svn:wc:ra_dav:version-url wcprop.
 142
 143 Example property:
 144   svn:wc:ra_dav:version-url -> /repos/test/!svn/ver/2/httpd/configure
 145
 146 GET
 147 ===
 148
 149 ra_serf
 150 -------
 151
 152 For a file that a WC already has when it wants to do an update, ra_serf will
 153 send two extra headers:
 154
 155   X-SVN-VR-Base: <checked-in href of locally-present file>
 156   Accept-Encoding: svndiff1;q=0.9,svndiff;q=0.8
 157
 158 The server may choose not to return svndiff content but return full-text.
 159
 160 (ra_neon has this same functionality, but is largely just dead code.)
 161
 162 Example
 163 -------
 164
 165 Request:
 166
 167   GET /repos/test/!svn/ver/3/httpd/configure HTTP/1.1
 168   X-SVN-VR-Base: /repos/test/!svn/ver/2/httpd/configure
 169   Accept-Encoding: svndiff1;q=0.9,svndiff;q=0.8
 170
 171 Response:
 172
 173   HTTP/1.1 200 OK
 174   ETag: "3//httpd/configure"
 175   Vary: Accept-Encoding
 176   Content-Type: application/vnd.svn-svndiff
 177
 178   ...svn-svndiff stream that can be passed to svn_txdelta_parse_svndiff...
 179
 180 Custom REPORTs
 181 ==============
 182
 183 We use a bunch of custom reports, here's a little info on what they look like.
 184
 185 update-report
 186 -------------
 187
 188 Purpose: Present what we have in our WC to the server and let it tell us what
 189          has changed.  Has an optional 'send-all' attribute that will include
 190          the text-deltas in base64-encoding inline to the XML REPORT response.
 191
 192 Target URL: Base VCC URL
 193             Example: REPORT /repos/test/!svn/vcc/default
 194
 195 Note: ra_serf will not set the send-all attribute to the update-report.  It
 196       will instead take the returned D:checked-in href and do a pipelined
 197       PROPFIND / GET on that resource.
 198
 199 Note: If a client had a previous revision, it would not send the 'start-empty'
 200       attribute to entry.
 201
 202 Request:
 203
 204   <S:update-report send-all="true" xmlns:S="svn:">
 205     <S:src-path>http://localhost:8080/repos/test/httpd/support</S:src-path>
 206     <S:target-revision>2</S:target-revision>
 207     <S:entry rev="2"  start-empty="true"></S:entry>
 208   </S:update-report>
 209
 210 Response:
 211
 212 <S:update-report xmlns:S="svn:" xmlns:V="..." xmlns:D="DAV:" send-all="true">
 213   <S:target-revision rev="2"/>
 214   <S:open-directory rev="2">
 215     <D:checked-in>
 216       <D:href>/repos/test/!svn/ver/2/httpd/support</D:href>
 217     </D:checked-in>
 218     <S:set-prop name="svn:entry:committed-rev">2</S:set-prop>
 219     ... more set props ...
 220     <S:add-file name="ab.c">
 221       <D:checked-in>
 222         <D:href>/repos/test/!svn/ver/2/httpd/support/ab.c</D:href>
 223       </D:checked-in>
 224       <S:set-prop name="svn:entry:committed-rev">2</S:set-prop>
 225       ... more set props for the file ...
 226       <S:txdelta>...base64-encoded file content...</S:txdelta>
 227     </S:add-file>
 228     <S:add-directory name="os" bc-url="/repos/test/!svn/bc/2/httpd/os">
 229       <D:checked-in>
 230         <D:href>/repos/test/!svn/ver/2/httpd/os</D:href>
 231       </D:checked-in>
 232       ...directory contents...
 233     </S:add-directory>
 234   </S:open-directory>
 235 </S:update-report>
 236
 237 dated-rev-report
 238 ----------------
 239
 240 Purpose: Get the revision associated with a particular date.
 241
 242 Target URL: VCC URL for repos.
 243
 244 Request:
 245
 246   <S:dated-rev-report xmlns:S="svn:" xmlns:D="DAV:">
 247     <D:creationdate>2005-12-07T13:06:26.034802Z</D:creationdate>
 248   </S:dated-rev-report>
 249
 250 Response:
 251
 252   <S:dated-rev-report xmlns:S="svn:" xmlns:D="DAV:">
 253     <D:version-name>4747</D:version-name>
 254   </S:dated-rev-report>
 255
 256 get-locks-report
 257 ----------------
 258
 259 Purpose: Get the locks associated with a particular resource.
 260
 261 Target URL: URL of item we're getting the locks for
 262
 263 Request:
 264
 265   <S:get-locks-report xmlns:S="svn">
 266   </S:get-locks-report>
 267
 268 Response:
 269
 270   <S:get-locks-report xmlns:S="svn">
 271     <S:lock>
 272       <S:path>/foo/bar/baz</S:path>
 273       <S:token>opaquelocktoken:706689a6-8cef-0310-9809-fb7545cbd44e</S:token>
 274       <S:owner>fred</S:owner>
 275       <S:comment encoding="base64">ET39IGCB93LL4M</S:comment>
 276       <S:creationdate>2005-02-07T14:17:08Z</S:creationdate>
 277       <S:expirationdate>2005-02-08T14:17:08Z</S:expirationdate>
 278     </S:lock>
 279   </S:get-locks-report>
 280
 281 get-locations
 282 -------------
 283
 284 Purpose: Get the location of a path appearing in a particular revision.
 285
 286 Target URL: Current baseline collection for a directory plus relative paths.
 287             Example: REPORT /repos/test/!svn/bc/5/httpd
 288
 289 Request:
 290
 291   <S:get-locations xmlns:S="svn:">
 292     <S:path></S:path>
 293     <S:peg-revision>5</S:peg-revision>
 294     <S:location-revision>1</S:location-revision>
 295   </S:get-locations>
 296
 297 Response:
 298
 299   <?xml version="1.0" encoding="utf-8"?>
 300   <S:get-locations-report xmlns:S="svn:" xmlns:D="DAV:">
 301     <S:location rev="1" path="/httpd"/>
 302   </S:get-locations-report>
 303
 304 log-report
 305 ----------
 306
 307 Purpose: Retrieve the log for a portion of the repository.
 308
 309 Target URL: Current baseline collection for a directory plus relative paths.
 310             Example: REPORT /repos/test/!svn/bc/5/httpd/support
 311
 312 Request:
 313
 314   <S:log-report xmlns:S="svn:">
 315     <S:start-revision>2</S:start-revision>
 316     <S:end-revision>2</S:end-revision>
 317     <S:limit>1</S:limit> (optional)
 318     <S:discover-changed-paths/> (optional)
 319     <S:strict-node-history/> (optional)
 320     <S:include-merged-revisions/> (optional)
 321     <S:revprop>REVPROP</S:revprop>... | <S:all-revprops/> (optional)
 322     <S:path></S:path>... (optional)
 323   </S:log-report>
 324
 325 Response:
 326
 327   <?xml version="1.0" encoding="utf-8"?>
 328   <S:log-report xmlns:S="svn:" xmlns:D="DAV:">
 329     <S:log-item>
 330       <D:version-name>2</D:version-name>
 331       <S:creator-displayname>bob</S:creator-displayname>
 332       <S:date>2006-02-27T18:44:26.149336Z</S:date>
 333       <D:comment>Add doo-hickey</D:comment>
 334       <S:revprop name="REVPROP">value</S:revprop>... (optional)
 335       <S:has-children/> (optional)
 336       <S:added-path( copyfrom-path="PATH" copyfrom-rev="REVNUM">PATH</S:added-path>... (optional)
 337       <S:replaced-path( copyfrom-path="PATH" copyfrom-rev="REVNUM">PATH</S:replaced-path>... (optional)
 338       <S:deleted-path>PATH</S:deleted-path>... (optional)
 339       <S:modified-path>PATH</S:modified-path>... (optional)
 340     </S:log-item>
 341     ...multiple log-items for each returned revision...
 342   </S:log-report>
 343
 344 mergeinfo-report
 345 ----------------
 346
 347 Purpose: Retrieve the merge history for a portion of the repository
 348 (e.g. a set of paths) at a particular revision.
 349
 350 Target URL: URL of item we're getting merge info for.
 351
 352 Note: <S:inherit> is a representation of the svn_mergeinfo_inheritance_t
 353       struct and can have the values 'explicit', 'inherited', or
 354       'nearest-ancestor'.  The default value is 'explicit' if <S:inherit>
 355       is not present or has any other value than those three.
 356
 357       <S:include-descendants> represents the 'include_descendants'
 358       boolean argument to svn_ra_get_mergeinfo().  It can be 'yes' or
 359       'no'; the default value is 'no' (mapping to FALSE).
 360
 361 Request:
 362
 363   <S:mergeinfo-report xmlns:S="svn:">
 364     <S:revision>1</S:revision>
 365     <S:inherit>inherited</S:inherit>
 366     <S:include-descendants>yes</S:include-descendants>
 367     <S:path>/A/B/E/alpha</S:path>
 368   </S:mergeinfo-report>
 369
 370 Response:
 371
 372   <?xml version="1.0" encoding="utf-8"?>
 373   <S:mergeinfo-report xmlns:S="svn:" xmlns:D="DAV:">
 374     <S:mergeinfo-item>
 375       <S:mergeinfo-path>/A_COPY/B/E</S:mergeinfo-path>
 376       <S:mergeinfo-info>/A/B/E:1,3-4</S:mergeinfo-info>
 377     </S:mergeinfo-item>
 378   </S:mergeinfo-report>