Disk Cache Access Protocol specification

dcap-protocol.md

dCache clinet access protocol DCAP

Basic definitions

DCAP client - door protocol:

• is line based. Each line is expected to be sent and received atomicly.
• The line can only contain ASCII characters.
• A line consists of tokens. Tokens are separated by at least one blank character. Tokens containing blanks have to be quoted.
• Client and server can initiate a session.
• Requests and replies of different sessions are not synchronized and can arrive at any point.
• The DCAP specification doesn't define the transport of the information.

The Line Syntax Definition

Each line starts with two numbers and a name. The numbers have to be non negative. They are called the sessionId and the ommandId resp. The third mandatory token is the name of the communication partner who initiated the session.

The last/(4) mandatory token is the request command. All subsequent tokens are called request arguments. The number and type of the request arguments are determined by the type of the request command.

<sessionId> <commandI> <comPartner> <requestCommand> [<requestArguments ...>]

A typical communication would look as follows :

c -> s :  4 0 client open 0000...0034758 snoopy.desy.de 1088 -timeout=30
c <- s :  4 0 client accepted
c -> s :  4 1 client query status
c <- s :  7 0 server ping
c <- s :  4 1 client status waiting
c -> s :  7 0 server alive
c -> s :  4 2 client cancel
c <- s :  4 0 client failed 333 "request was canceled by client"  

The specification of the request command declares an argument as mandatory or optional. Mandatory arguments are position dependent and have to be given in the specified order. Optional arguments may or may not be specified and appear after the request command in any order. They have the form

   -<key>=<value>

Communication Initiation and Termination

The communication is initiated asymetrically by the connector. For communication related messages the sessionId zero has to be taken.

client to server

0 0 client hello <minMajorVersion< <minMinorVersion> <maxMajorVersion> <maxMinorVersion>

server to client

0 0 server welcome <majorVersion> <minorVersion>

or

0 0 server reject <errorCode> <errorMessage>

No other messages can intervene the hello/welcome sequence. Client and server may close the communication by sending

0 0 server|client byebye

If the client initiates the byebye sequence, the server will echo the message. If the server initiates the byebye sequence, the client may simply close the connection.

The open command

Request

<sessionId> 0 client open [options] <path> <openMode> <hostList> <port>

Arguments :

• path: the absolute of the file to open/create
• openMode: the mode the file to open, like "rw", "r" or "w"
• hostList: comma separated list of host names or IP addresses of client's network interface
• port: TCP port number where data server must connect

Response

   <sessionId> 0 client ok  [0  [<additional information>]]

or

   <sessionId> 0 client failed [<reasonNumber> [<reasonMessage>]]