subversion/libsvn_ra_svn/protocol

   1 This file documents version 2 of the svn protocol.
   2
   3 1. Syntactic structure
   4 ----------------------
   5
   6 The Subversion protocol is specified in terms of the following
   7 syntactic elements, specified using ABNF [RFC 2234]:
   8
   9   item   = word / number / string / list
  10   word   = ALPHA *(ALPHA / DIGIT / "-") space
  11   number = 1*DIGIT space
  12   string = 1*DIGIT ":" *OCTET space
  13          ; digits give the byte count of the *OCTET portion
  14   list   = "(" space *item ")" space
  15   space  = 1*(SP / LF)
  16
  17 Here is an example item showing each of the syntactic elements:
  18
  19   ( word 22 6:string ( sublist ) )
  20
  21 All items end with mandatory whitespace.  (In the above example, a
  22 newline provides the terminating whitespace for the outer list.)  It
  23 is possible to parse an item without knowing its type in advance.
  24
  25 Lists are not constrained to contain items of the same type.  Lists
  26 can be used for tuples, optional tuples, or arrays.  A tuple is a list
  27 expected to contain a fixed number of items, generally of differing
  28 types.  An optional tuple is a list containing either zero or a fixed
  29 number of items (thus "optional" here does not refer to the list's
  30 presence or absence, but to the presence or absence of its contents).
  31 An array is a list containing zero or more items of the same type.
  32
  33 Words are used for enumerated protocol values, while strings are used
  34 for text or binary data of interest to the Subversion client or
  35 server.  Words are case-sensitive.
  36
  37 For convenience, this specification will define prototypes for data
  38 items using a syntax like:
  39
  40   example: ( literal ( data:string ... ) )
  41
  42 A simple word such as "literal", with no colon, denotes a literal
  43 word.  A choice of words may be given with "|" separating the choices.
  44 "name:type" specifies a parameter with the given type.
  45
  46 A type is "word", "number", "string", "list", or the name of another
  47 prototype.  Parentheses denote a tuple, unless the parentheses contain
  48 ellipses, in which case the parentheses denote an array containing
  49 zero or more elements matching the prototype preceding the ellipses.
  50
  51 If a tuple has an optional part after the fixed part, a '?' marks
  52 places where the tuple is allowed to end.  The following tuple could
  53 contain one, three, or four or more items:
  54
  55   example: ( fixed:string ? opt1:number opt2:string ? opt3:number )
  56
  57 Brackets denote an optional tuple; they are equivalent to parentheses
  58 and a leading '?'.  For example, this:
  59
  60   example: ( literal (? rev:number ) ( data:string ... ) )
  61
  62 can be written more compactly like this:
  63
  64   example: ( literal [ rev:number ] ( data:string ... ) )
  65
  66 For extensibility, implementations must treat a list as matching a
  67 prototype's tuple even if the list contains extra elements.  The extra
  68 elements must be ignored.
  69
  70 In some cases, a prototype may need to match two different kinds of
  71 data items.  This case will be written using "|" to separate the
  72 alternatives; for example:
  73
  74   example: ( first-kind rev:number )
  75          | second-kind
  76
  77 The "command response" prototype is used in several contexts of this
  78 specification to indicate the success or failure of an operation.  It
  79 is defined as follows:
  80
  81   command-response: ( success params:list )
  82                   | ( failure ( err:error ... ) )
  83   error: ( apr-err:number message:string file:string line:number )
  84
  85 The interpretation of parameters in a successful command response is
  86 context-dependent.
  87
  88 URLs and repository paths are represented as strings.  They should be in
  89 canonical form when sent over the protocol.  However, as a matter of input
  90 validation, an implementation should always canonicalize received paths if it
  91 needs them in canonicalized form.
  92
  93 2. Connection establishment and protocol setup
  94 ----------------------------------------------
  95
  96 By default, the client connects to the server on port 3690.
  97
  98 Upon receiving a connection, the server sends a greeting, using a
  99 command response whose parameters match the prototype:
 100
 101   greeting: ( minver:number maxver:number mechs:list ( cap:word ... ) )
 102
 103 minver and maxver give the minimum and maximum Subversion protocol
 104 versions supported by the server.  mechs is present for historical
 105 reasons, and is ignored by the client.  The cap values give a list of
 106 server capabilities (see section 2.1).
 107
 108 If the client does not support a protocol version within the specified
 109 range, it closes the connection.  Otherwise, the client responds to
 110 the greeting with an item matching the prototype:
 111
 112   response: ( version:number ( cap:word ... ) url:string )
 113
 114 version gives the protocol version selected by the client.  The cap
 115 values give a list of client capabilities (see section 2.1).  url
 116 gives the URL the client is accessing.
 117
 118 Upon receiving the client's response to the greeting, the server sends
 119 an authentication request, which is a command response whose arguments
 120 match the prototype:
 121
 122   auth-request: ( ( mech:word ... ) realm:string )
 123
 124 The mech values give a list of SASL mechanisms supported by the
 125 server.  The realm string is similar to an HTTP authentication realm
 126 as defined in [RFC 2617]; it allows the server to indicate which of
 127 several protection spaces the server wishes to authenticate in.  If
 128 the mechanism list is empty, then no authentication is required and no
 129 further action takes place as part of the authentication challenge;
 130 otherwise, the client responds with a tuple matching the prototype:
 131
 132   auth-response: ( mech:word [ token:string ] )
 133
 134 mech specifies the SASL mechanism and token, if present, gives the
 135 "initial response" of the authentication exchange.  The client may
 136 specify an empty mechanism to decline authentication; otherwise, upon
 137 receiving the client's auth-response, the server sends a series of
 138 challenges, each a tuple matching the prototype:
 139
 140   challenge: ( step ( token:string ) )
 141            | ( failure ( message:string ) )
 142            | ( success [ token:string ] )
 143
 144 If the first word of the challenge is "step", then the token is
 145 interpreted by the authentication mechanism, and the response token
 146 transmitted to the server as a string.  The server then proceeds with
 147 another challenge.  If the client wishes to abort the authentication
 148 exchange, it may do so by closing the connection.
 149
 150 If the first word of the challenge is "success", the authentication is
 151 successful.  If a token is provided, it should be interpreted by the
 152 authentication mechanism, but there is no response.
 153
 154 If the first word of the challenge is "failure", the authentication
 155 exchange is unsuccessful.  The client may then give up, or make
 156 another auth-response and restart the authentication process.
 157
 158 RFC 2222 requires that a protocol profile define a service name for
 159 the sake of the GSSAPI mechanism.  The service name for this protocol
 160 is "svn".
 161
 162 After a successful authentication exchange, the server sends a command
 163 response whose parameters match the prototype:
 164
 165   repos-info: ( uuid:string repos-url:string )
 166
 167 uuid gives the universal unique identifier of the repository, and
 168 repos-url gives the URL of the repository's root directory.  The
 169 client can now begin sending commands from the main command set.
 170
 171 2.1 Capabilities
 172
 173 The following capabilities are currently defined (S indicates a server
 174 capability and C indicates a client capability):
 175
 176 [CS] edit-pipeline     Every released version of Subversion since 1.0
 177                        announces the edit-pipeline capability; starting
 178                        in Subversion 1.5, both client and server
 179                        *require* the other side to announce edit-pipeline.
 180 [CS] svndiff1          If both the client and server support svndiff version
 181                        1, this will be used as the on-the-wire format for
 182                        svndiff instead of svndiff version 0.
 183 [CS] absent-entries    If the remote end announces support for this capability,
 184                        it will accept the absent-dir and absent-file editor
 185                        commands.
 186 [S]  commit-revprops   If the server presents this capability, it supports the
 187                        rev-props parameter of the commit command.
 188                        See section 3.1.1.
 189 [S]  mergeinfo         If the server presents this capability, it supports the
 190                        get-mergeinfo command.  See section 3.1.1.
 191 [S]  depth             If the server presents this capability, it understands
 192                        requested operational depth (see section 3.1.1) and
 193                        per-path ambient depth (see section 3.1.3).
 194
 195 3. Commands
 196 -----------
 197
 198 Commands match the prototypes:
 199
 200   command: ( command-name:word params:list )
 201
 202 The interpretation of command parameters is different from command to
 203 command.
 204
 205 Initially, the client initiates commands from the main command set,
 206 and the server responds.  Some commands in the main command set can
 207 temporarily change the set of commands which may be issued, or change
 208 the flow of control so that the server issues commands and the client
 209 responds.
 210
 211 Here are some miscellaneous prototypes used by the command sets:
 212
 213   proplist:  ( ( name:string value:string ) ... )
 214   propdelta: ( ( name:string [ value:string ] ) ... )
 215   node-kind: none|file|dir|unknown
 216   bool:      true|false
 217   lockdesc:  ( path:string token:string owner:string [ comment:string ]
 218                created:string [ expires:string ] )
 219
 220 3.1. Command Sets
 221
 222 There are three command sets: the main command set, the editor command
 223 set, and the report command set.  Initially, the protocol begins in
 224 the main command set with the client sending commands; some commands
 225 can change the command set and possibly the direction of control.
 226
 227 3.1.1. Main Command Set
 228
 229 The main command set corresponds to the svn_ra interfaces.  After each
 230 main command is issued by the client, the server sends an auth-request
 231 as described in section 2.  (If no new authentication is required, the
 232 auth-request contains an empty mechanism list, and the server proceeds
 233 immediately to sending the command response.)  Some commands include a
 234 second place for auth-request point as noted below.
 235
 236   reparent
 237     params:   ( url:string )
 238     response: ( )
 239
 240   get-latest-rev
 241     params:   ( )
 242     response: ( rev:number )
 243
 244   get-dated-rev
 245     params:   ( date:string )
 246     response: ( rev:number )
 247
 248   change-rev-prop
 249     params:   ( rev:number name:string ? value:string )
 250     response: ( )
 251     If value is not specified, the rev-prop is removed.
 252     (Originally the value was required; for minimum impact, it was
 253      changed to be optional without creating an optional tuple for
 254      that one parameter as we normally do.)
 255
 256   rev-proplist
 257     params:   ( rev:number )
 258     response: ( props:proplist )
 259
 260   rev-prop
 261     params:   ( rev:number name:string )
 262     response: ( [ value:string ] )
 263
 264   commit
 265     params:   ( logmsg:string ? ( ( lock-path:string lock-token:string ) ... )
 266                 keep-locks:bool ? rev-props:proplist )
 267     response: ( )
 268     Upon receiving response, client switches to editor command set.
 269     Upon successful completion of edit, server sends auth-request.
 270     After auth exchange completes, server sends commit-info.
 271     commit-info: ( new-rev:number date:string author:string
 272                    ? ( post-commit-err:string ) )
 273
 274   get-file
 275     params:   ( path:string [ rev:number ] want-props:bool want-contents:bool )
 276     response: ( [ checksum:string ] rev:number props:proplist )
 277     If want-contents is specified, then after sending response, server
 278      sends file contents as a series of strings, terminated by the empty
 279      string, followed by a second empty command response to indicate
 280      whether an error occurred during the sending of the file.
 281
 282   get-dir
 283     params:   ( path:string [ rev:number ] want-props:bool want-contents:bool
 284                 ? ( field:dirent-field ... ) )
 285     response: ( rev:number props:proplist ( entry:dirent ... ) )]
 286     dirent:   ( name:string kind:node-kind size:number has-props:bool
 287                 created-rev:number [ created-date:string ]
 288                 [ last-author:string ] )
 289     dirent-field: kind | size | has-props | created-rev | time | last-author
 290                   | word
 291
 292   check-path
 293     params:   ( path:string [ rev:number ] )
 294     response: ( kind:node-kind )
 295     If path is non-existent, 'svn_node_none' kind is returned.
 296
 297   stat
 298     params:   ( path:string [ rev:number ] )
 299     response: ( ? entry:dirent )
 300     dirent:   ( name:string kind:node-kind size:number has-props:bool
 301                 created-rev:number [ created-date:string ]
 302                 [ last-author:string ] )
 303     New in svn 1.2.  If path is non-existent, an empty response is returned.
 304
 305   get-mergeinfo
 306     params:   ( ( path:string ... ) [ rev:number ] inherit:word )
 307     response: ( ( ( path:string merge-info:string ) ... ) )
 308     New in svn 1.5.  If no paths are specified, an empty response is
 309     returned.  If rev is not specified, the youngest revision is used.
 310
 311   update
 312     params:   ( [ rev:number ] target:string recurse:bool
 313                 ? depth:word send_copyfrom_param:bool )
 314     Client switches to report command set.
 315     Upon finish-report, server sends auth-request.
 316     After auth exchange completes, server switches to editor command set.
 317     After edit completes, server sends response.
 318     response: ( )
 319
 320   switch
 321     params:   ( [ rev:number ] target:string recurse:bool url:string
 322                 ? depth:word)
 323     Client switches to report command set.
 324     Upon finish-report, server sends auth-request.
 325     After auth exchange completes, server switches to editor command set.
 326     After edit completes, server sends response.
 327     response: ( )
 328
 329   status
 330     params:   ( target:string recurse:bool ? [ rev:number ] ? depth:word )
 331     Client switches to report command set.
 332     Upon finish-report, server sends auth-request.
 333     After auth exchange completes, server switches to editor command set.
 334     After edit completes, server sends response.
 335     response: ( )
 336
 337   diff
 338     params:   ( [ rev:number ] target:string recurse:bool ignore-ancestry:bool
 339                 url:string ? text-deltas:bool ? depth:word )
 340     Client switches to report command set.
 341     Upon finish-report, server sends auth-request.
 342     After auth exchange completes, server switches to editor command set.
 343     After edit completes, server sends response.
 344     response: ( )
 345
 346   log
 347     params:   ( ( target-path:string ... ) [ start-rev:number ]
 348                 [ end-rev:number ] changed-paths:bool strict-node:bool
 349                 ? limit:number
 350                 ? include-merged-revisions:bool
 351                 all-revprops | revprops
 352                 ? ( revprop:string ... ) )
 353     Before sending response, server sends log entries, ending with "done".
 354     If a client does not want to specify a limit, it should send 0 as the
 355     limit parameter.  rev-props excludes author, date, and log; they are
 356     sent separately for backwards-compatibility.
 357     log-entry: ( ( change:changed-path-entry ... ) rev:number
 358                  [ author:string ] [ date:string ] [ message:string ]
 359                  ? has-children:bool invalid-revnum:bool
 360                  revprop-count:number rev-props:proplist )
 361              | done
 362     changed-path-entry: ( path:string A|D|R|M [ copy-path:string ]
 363                           [ copy-rev:number ] )
 364     response: ( )
 365
 366   get-locations
 367     params:   ( path:string peg-rev:number ( rev:number ... ) )
 368     Before sending response, server sends location entries, ending with "done".
 369     location-entry: ( rev:number abs-path:number ) | done
 370     response: ( )
 371
 372   get-location-segments
 373     params:   ( path:string [ start-rev:number ] [ end-rev:number ] )
 374     Before sending response, server sends location entries, ending with "done".
 375     location-entry: ( range-start:number range-end:number [ abs-path:string ] ) | done
 376     response: ( )
 377
 378   get-file-revs
 379     params:   ( path:string [ start-rev:number ] [ end-rev:number ]
 380                 ? include-merged-revisions:bool )
 381     Before sending response, server sends file-rev entries, ending with "done".
 382     file-rev: ( path:string rev:number rev-props:proplist
 383                 file-props:propdelta ? merged-revision:bool )
 384               | done
 385     After each file-rev, the file delta is sent as one or more strings,
 386     terminated by the empty string.  If there is no delta, server just sends
 387     the terminator.
 388     response: ( )
 389
 390   lock
 391     params:    ( path:string [ comment:string ] steal-lock:bool
 392                  [ current-rev:number ] )
 393     response:  ( lock:lockdesc )
 394
 395   lock-many
 396     params:    ( [ comment:string ] steal-lock:bool ( ( path:string
 397                  [ current-rev:number ] ) ... ) )
 398     Before sending response, server sends lock cmd status and descriptions,
 399     ending with "done".
 400     lock-info: ( success ( lock:lockdesc ) ) | ( failure ( err:error ) )
 401                 | done
 402     response: ( )
 403
 404   unlock
 405     params:    ( path:string [ token:string ] break-lock:bool )
 406     response:  ( )
 407
 408   unlock-many
 409     params:    ( break-lock:bool ( ( path:string [ token:string ] ) ... ) )
 410     Before sending response, server sends unlocked paths, ending with "done".
 411     pre-response: ( success ( path:string ) ) | ( failure ( err:error ) )
 412                   | done
 413     response:  ( )
 414
 415   get-lock
 416     params:    ( path:string )
 417     response:  ( [ lock:lockdesc ] )
 418
 419   get-locks
 420     params:    ( path:string )
 421     response   ( ( lock:lockdesc ... ) )
 422
 423   replay
 424     params:    ( revision:number low-water-mark:number send-deltas:bool )
 425     After auth exchange completes, server switches to editor command set.
 426     After edit completes, server sends response.
 427     response   ( )
 428
 429   replay-range
 430     params:    ( start-rev:number end-rev:number low-water-mark:number
 431                  send-deltas:bool )
 432     After auth exchange completes, server sends each revision
 433     from start-rev to end-rev, alternating between sending 'revprops'
 434     entries and sending the revision in the editor command set.
 435     After all revisions are complete, server sends response.
 436     revprops:  ( props:proplist )
 437     response   ( )
 438
 439 3.1.2. Editor Command Set
 440
 441 An edit operation produces only one response, at close-edit or
 442 abort-edit time.  However, the consumer may write an error response at
 443 any time during the edit in order to terminate the edit operation
 444 early; the driver must notice that input is waiting on the connection,
 445 read the error, and send an abort-edit operation.  After an error is
 446 returned, the consumer must read and discard editing operations until
 447 the abort-edit.  In order to prevent TCP deadlock, the consumer must
 448 use non-blocking I/O to send an early error response; if writing
 449 blocks, the consumer must read and discard edit operations until
 450 writing unblocks or it reads an abort-edit.
 451
 452   target-rev
 453     params:   ( rev:number )
 454
 455   open-root
 456     params:   ( [ rev:number ] root-token:string )
 457
 458   delete-entry
 459     params:   ( path:string rev:number dir-token:string )
 460
 461   add-dir
 462     params:   ( path:string parent-token:string child-token:string
 463                 [ copy-path:string copy-rev:number ] )
 464
 465   open-dir
 466     params:   ( path:string parent-token:string child-token:string rev:number )
 467
 468   change-dir-prop
 469     params:   ( dir-token:string name:string [ value:string ] )
 470
 471   close-dir
 472     params:   ( dir-token:string )
 473
 474   absent-dir
 475     params:   ( path:string parent-token:string )
 476
 477   add-file
 478     params:   ( path:string dir-token:string file-token:string
 479                 [ copy-path:string copy-rev:number ] )
 480
 481   open-file
 482     params:   ( path:string dir-token:string file-token:string rev:number )
 483
 484   apply-textdelta
 485     params:   ( file-token:string [ base-checksum:string ] )
 486
 487   textdelta-chunk
 488     params: ( file-token:string chunk:string )
 489
 490   textdelta-end
 491     params: ( file-token:string )
 492
 493   change-file-prop
 494     params:   ( file-token:string name:string [ value:string ] )
 495
 496   close-file
 497     params:   ( file-token:string [ text-checksum:string ] )
 498
 499   absent-file
 500     params:   ( path:string parent-token:string )
 501
 502   close-edit
 503     params:   ( )
 504     response: ( )
 505
 506   abort-edit
 507     params:   ( )
 508     response: ( )
 509
 510   finish-replay
 511     params:   ( )
 512     Only delivered from server to client, at the end of a replay.
 513
 514 3.1.3. Report Command Set
 515
 516 To reduce round-trip delays, report commands do not return responses.
 517 Any errors resulting from a report call will be returned to the client
 518 by the command which invoked the report (following an abort-edit
 519 call).  Errors resulting from an abort-report call are ignored.
 520
 521   set-path:
 522     params: ( path:string rev:number start-empty:bool
 523               ? [ lock-token:string ] ? depth:word )
 524
 525   delete-path:
 526     params: ( path:string )
 527
 528   link-path:
 529     params: ( path:string url:string rev:number start-empty:bool
 530               ? [ lock-token:string ] ? depth:word )
 531
 532   finish-report:
 533     params: ( )
 534
 535   abort-report
 536     params: ( )
 537
 538 4. Extensibility
 539 ----------------
 540
 541 This protocol may be extended in three ways, in decreasing order of
 542 desirability:
 543
 544   * Items may be added to any tuple.  An old implementation will
 545     ignore the extra items.
 546
 547   * Named extensions may be expressed at connection initiation time
 548     by the client or server.
 549
 550   * The protocol version may be bumped.  Clients and servers can then
 551     choose to any range of protocol versions.
 552
 553 4.1. Extending existing commands
 554
 555 Extending an existing command is normally done by indicating that its
 556 tuple is allowed to end where it currently ends, for backwards
 557 compatibility, and then tacking on a new, possibly optional, item.
 558
 559 For example, diff was extended to include a new mandatory text-deltas
 560 parameter like this:
 561
 562   /* OLD */ diff:
 563     params:   ( [ rev:number ] target:string recurse:bool ignore-ancestry:bool
 564                 url:string )
 565   /* NEW */ diff:
 566     params:   ( [ rev:number ] target:string recurse:bool ignore-ancestry:bool
 567                 url:string ? text-deltas:bool )
 568
 569 The "?" says that the tuple is allowed to end here, because an old
 570 client or server wouldn't know to send the new item.
 571
 572 For optional parameters, a slightly different approach must be used.
 573 set-path was extended to include lock-tokens like this:
 574
 575   /* OLD */ set-path:
 576     params: ( path:string rev:number start-empty:bool )
 577
 578   /* NEW */ set-path:
 579     params: ( path:string rev:number start-empty:bool ? [ lock-token:string ] )
 580
 581 The new item appears in brackets because, even in the new protocol,
 582 the lock-token is still optional.  However, if there's no lock-token
 583 to send, an empty tuple must still be transmitted so that future
 584 extensions to this command remain possible.