The SimDB protocol is an HTTP-like network protocol, where the client sends request messages to the server and the server sends response messages to the client. Client and server can also send files to each other. All the messages contains only ASCII characters. The files exchanged between the client and the server are also made of ASCII characters after a base64 encoding. The end of a protocol message is signaled by the ASCII character ETX. The newline character is the octect \n. The string values must be single quoted. (e.g. 'hello' or 'hello world').

Commands

The following are the protocol commands for the client requests:

  • INSERT : insert a new Data Set in the system.
  • REMOVE : remove a Data Set from the system.
  • GET : retrieve a Data Set from the system.
  • SEARCH : execute a query on the system data.
  • SPECLIST : list the DSS currently on the system.

Response codes

The following are the response codes used by the server:

Success code:

  • 0 : Ok

Error codes:

  • 1 : Wrong authentication
  • 2 : Incomplete set
  • 3 : No such specifier
  • 4 : Too much data
  • 5 : No such set
  • 6 : Wrong type
  • 7 : Unknown name
  • 8 : Unknown field
  • 99 : Generic error

Documentation

The protocol commands are documented through request-response diagrams to show the interaction between a client (on the diagram left) and a server (on the diagram right). Please note that the response codes sent by the server must include only the number, not also the description like the diagrams do.

The protocol is currently at the version 1.

INSERT command

Client                                          Server

INSERT
DSS name
SD n
F1.name F1.value
F2.name F2.value
...
Fn.name Fn.value
DIFILES l
DIf1.name filesize1
DIf2.name filesize2
...
DIfl.name filesizel
        --------------------------------------->

                                                0 OK
                                                2 Incomplete set
                                                3 No such specifier
                                                4 Too much data
                                                6 Wrong type
                                                7 Unknown name
                                                8 Unknown field
                                                99 Generic error
        <---------------------------------------
(if OK has been received)
DIf1.name nbytes1
<data_1>
        ---------------------------------------->

                                                0 OK
                                                99 Generic error
        <---------------------------------------
(if OK has been received)
DIf2.name nbytes2
<data_2>
        ---------------------------------------->

                                                0 OK
                                                99 Generic error
        <---------------------------------------
...
(if OK has been received)
DIfl.name nbytesl
<data_l>
        ---------------------------------------->

                                                0 SeqNum
                                                99 Generic error
        <---------------------------------------

If there is an error, the server closes the connection and discards all the received data. The whole Data Set is saved on the server filesystem only when the last Data Item is received without errors. The last response code is followed by the sequence number of the new Data Set. The filesizeX values in the DIFILES section are the original byte sizes of the files, before the base64 encoding, while the following nbytesX values are the byte sizes of the files after the base64 encoding.

REMOVE command

Client                                          Server

REMOVE SeqNum
DSS name
        --------------------------------------->
                                                0 OK
                                                3 No such specifier
                                                5 No such set
                                                99 Generic error
        <---------------------------------------

GET command

Client                                          Server

GET SeqNum
DSS name
        --------------------------------------->
                                                3 No such specifier
                                                5 No such set
                                                99 Generic error
        <---------------------------------------

If the requested DS exists, the server sends the data:

                                                0 OK
                                                SD n
                                                F1.name F1.value
                                                F2.name F2.value
                                                ...
                                                Fn.name Fn.value
                                                DI m
                                                DI1.name DI1.value
                                                DI2.name DI2.value
                                                ...
                                                DIm.name DIn.value
                                                DIFILES l
                                                DIf1.name nbytes1
                                                <data_1>
                                                DIf2.name nbytes2
                                                <data_2>
                                                ...
                                                DIf2.name nbytesl
                                                <data_l>
        <---------------------------------------

The unnecessary files of the Data Set which are not in the server filesystem are not included in the DIFILES section of the response message.

SEARCH command

Client                                          Server

SEARCH
DSS name
SD l
F1.name F1.value
...
Fl.name Fl.value
        --------------------------------------->
                                                3 No such specifier
                                                8 Unknown field
                                                99 Generic error
        <---------------------------------------

If the DSS exists, sends the info for each SD matching the query:

                                                0 OK
                                                FOUND k
                                                SD n      # 1st
                                                F1.name F1.value
                                                F2.name F2.value
                                                ...
                                                Fn.name Fn.value
                                                ...
                                                SD n      # k-th
                                                F1.name F1.value
                                                F2.name F2.value
                                                ...
                                                Fn.name Fn.value
        <---------------------------------------

The l number must be less or equal than the number of the DSS Set Descriptor. If no fields are specified in the query (l=0), the server returns the information of all the Data Set instances of the specified DSS.

SPECLIST command

Client                                          Server

SPECLIST
        --------------------------------------->
                                                99 Generic error
        <---------------------------------------

This commands simply returns the list with all the DSS currently on the system. The format of this list is up to the server.