view release on metacpan or  search on metacpan

src/subversion/subversion/libsvn_ra_svn/protocol  view on Meta::CPAN

  example: ( fixed:string ? opt1:number opt2:string ? opt3:number )

Brackets denote an optional tuple; they are equivalent to parentheses
and a leading '?'.  For example, this:

  example: ( literal (? rev:number ) ( data:string ... ) )

can be written more compactly like this:

  example: ( literal [ rev:number ] ( data:string ... ) )

For extensibility, implementations must treat a list as matching a
prototype's tuple even if the list contains extra elements.  The extra
elements must be ignored.

In some cases, a prototype may need to match two different kinds of
data items.  This case will be written using "|" to separate the
alternatives; for example:

  example: ( first-kind rev:number )
         | second-kind

The "command response" prototype is used in several contexts of this
specification to indicate the success or failure of an operation.  It
is defined as follows:

  command-response: ( success params:list )
                  | ( failure ( err:error ... ) )
  error: ( apr-err:number message:string file:string line:number )

The interpretation of parameters in a successful command response is
context-dependent.

URLs and repository paths are represented as strings.  They should be in
canonical form when sent over the protocol.  However, as a matter of input
validation, an implementation should always canonicalize received paths if it
needs them in canonicalized form.

2. Connection establishment and protocol setup
----------------------------------------------

By default, the client connects to the server on port 3690.

Upon receiving a connection, the server sends a greeting, using a
command response whose parameters match the prototype:

  greeting: ( minver:number maxver:number mechs:list ( cap:word ... ) )

minver and maxver give the minimum and maximum Subversion protocol
versions supported by the server.  mechs is present for historical
reasons, and is ignored by the client.  The cap values give a list of
server capabilities (see section 2.1).

If the client does not support a protocol version within the specified
range, it closes the connection.  Otherwise, the client responds to
the greeting with an item matching the prototype:

  response: ( version:number ( cap:word ... ) url:string
              ? ra-client:string ( ? client:string ) )

version gives the protocol version selected by the client.  The cap
values give a list of client capabilities (see section 2.1).  url
gives the URL the client is accessing.  ra-client is a string
identifying the RA implementation, e.g. "SVN/1.6.0" or "SVNKit 1.1.4".
client is the string returned by svn_ra_callbacks2_t.get_client_string;
that callback may not be implemented, so this is optional.

Upon receiving the client's response to the greeting, the server sends
an authentication request, which is a command response whose arguments
match the prototype:

  auth-request: ( ( mech:word ... ) realm:string )

The mech values give a list of SASL mechanisms supported by the
server.  The realm string is similar to an HTTP authentication realm
as defined in [RFC 2617]; it allows the server to indicate which of
several protection spaces the server wishes to authenticate in.  If
the mechanism list is empty, then no authentication is required and no
further action takes place as part of the authentication challenge;
otherwise, the client responds with a tuple matching the prototype:

  auth-response: ( mech:word [ token:string ] )

mech specifies the SASL mechanism and token, if present, gives the
"initial response" of the authentication exchange.  The client may
specify an empty mechanism to decline authentication; otherwise, upon
receiving the client's auth-response, the server sends a series of
challenges, each a tuple matching the prototype:

  challenge: ( step ( token:string ) )
           | ( failure ( message:string ) )
           | ( success [ token:string ] )

If the first word of the challenge is "step", then the token is
interpreted by the authentication mechanism, and the response token
transmitted to the server as a string.  The server then proceeds with
another challenge.  If the client wishes to abort the authentication
exchange, it may do so by closing the connection.

If the first word of the challenge is "success", the authentication is
successful.  If a token is provided, it should be interpreted by the
authentication mechanism, but there is no response.

If the first word of the challenge is "failure", the authentication
exchange is unsuccessful.  The client may then give up, or make
another auth-response and restart the authentication process.

RFC 2222 requires that a protocol profile define a service name for
the sake of the GSSAPI mechanism.  The service name for this protocol
is "svn".

After a successful authentication exchange, the server sends a command
response whose parameters match the prototype:

  repos-info: ( uuid:string repos-url:string ( cap:word ... ) )

uuid gives the universal unique identifier of the repository,
repos-url gives the URL of the repository's root directory, and the
cap values list the repository capabilities (that is, capabilities
that require both server and repository support before the server can
claim them as capabilities, e.g., SVN_RA_SVN_CAP_MERGEINFO).