ArcLink Server, Request Handler protocol

As explained on the ArcLink server documentation the server distributed with seiscomp3 does not know nothing about how to prepare the data products. Instead it uses the request-handler program to generate the products and just deliver the results prepared to the user. The server when started will start a couple of request-handlers (programs) that will communicate to the server using file descriptors. The server uses the file descriptor 62 to send requests to a request handler and reads status responses from file descriptor 63.

The communication between the server and the request handler is governed by an asynchronous protocol that is described in this documment.

Request handler protocol

The ArcLink server sends a request to a request handler in the following format:

USER <username> <password>
[INSTITUTION <any string>]
[LABEL <label>]
REQUEST <request_type> <req_id> <optional_attributes>
[one or more request lines...]
END

After receiving the request, the request handler can send responses to the server. The following responses are defined:

STATUS LINE <n> PROCESSING <vol_id>

add request line number n (0-based) to volume vol id. The volume is created if it does not already exist.

STATUS <ref> <status>

set line or volume status, where ref is "LINE n" or "VOLUME vol id" and status is one of the following:[[br]][[br]]

Status	Description
OK	request successfully processed, data available
NODATA	no processing errors, but data not available
WARN	processing errors, some downloadable data available
ERROR	processing errors, no downloadable data available
RETRY	temporarily no data available
DENIED	access to data denied for the user
CANCEL	processing cancelled (eg., by operator)

MESSAGE

any string error message in case of WARN or ERROR, but can be used regardless of the status (the last message is shown in the STATUS response)

SIZE <n>

data size; in case of a volume, it must be the exact size of downloadable product.

MESSAGE <any_string>

send a general processing (error) message. The last message is shown in the STATUS response.

ERROR

the request handler could not process the request due to an error (e.g., got an unhandled Python exception). This terminates the request and normally the request handler quits. If the request handler does not quit, it should be ready to handle the next request. Note that if the request handler quits (crashes) without sending ERROR, then the request will be repeated (sent to another request handler instance) by the server. This behavior might be changed in future server versions to avoid loops, e.g., by implying ERROR if the request handler quits.

END

request processing finished normally. The request handler is ready for the next request.

Session example

Since the communication from the request handler to the ArcLink server is performed by file descriptors it is possible to test a request handler (provided on the seiscomp3 distribution) interactively by running a command similar to following:

python reqhandler -vvv 62>&0 63<&1 >reqhandler.log 2>&1

Now the program "reqhandler" waits for input from terminal and writes output to terminal as well. Additionally a logfile is written.

Let's type the following request:

USER somebody@gfz-potsdam.de
REQUEST WAVEFORM 123 format=MSEED
2008,2,21,2,50,0 2008,2,21,3,10,0 EE MTSE BHZ .
2008,2,21,2,50,0 2008,2,21,3,10,0 GE WLF BHZ .
END

The log might look similar to following:

01 [None] > USER somebody@gfz-potsdam.de
02 [None] > REQUEST WAVEFORM 123 format=MSEED
03 [123] new WAVEFORM request from somebody@gfz-potsdam.de, None
04 [123] > 2008,2,21,2,50,0 2008,2,21,3,10,0 EE MTSE BHZ .
05 [123] < STATUS LINE 0 PROCESSING GFZ
06 [123] > 2008,2,21,2,50,0 2008,2,21,3,10,0 GE WLF BHZ .
07 [123] < STATUS LINE 0 SIZE 43008
08 [123] > END
09 [123] < STATUS LINE 1 PROCESSING GFZ
10 [123] < STATUS LINE 0 OK
11 [123] < STATUS LINE 1 MESSAGE size not known
12 [123] < STATUS LINE 1 OK
13 [123] < STATUS VOLUME GFZ SIZE 73728
14 [123] < STATUS VOLUME GFZ OK
15 [123] < END

Note that the status responses are asynchronous.

02

request ID "123" is chosen by the server (not user)

05

the first request line is associated with volume ID "GFZ" (chosen by the request handler)

07

request handler tells the size of data that is related to the first request line (optional)

09

the second request line is associated with volume ID "GFZ"

10

processing of the first line completed without error

11

send optional message regarding the second line

12

processing of the second line completed without error

13

request handler tells the size of volume (mandatory)

14

volume completed without error

15

request processing finished

Minimal status response when data is available:

STATUS LINE 0 PROCESSING GFZ
STATUS LINE 1 PROCESSING GFZ
STATUS LINE 0 OK
STATUS LINE 1 OK
STATUS VOLUME GFZ SIZE 73728
STATUS VOLUME GFZ OK
END

Minimal status response (and an optional error message) when data is not available:

STATUS LINE 0 PROCESSING GFZ
STATUS LINE 1 PROCESSING GFZ
STATUS LINE 0 NODATA
STATUS LINE 1 NODATA
STATUS VOLUME GFZ NODATA
MESSAGE optional error message
END