Working with Handler Programs¶

Requirements of a Handler Program¶

There are few requirements on a handler program. Essentially the handler must return data (or a return code) within the time allotted by the WSS (configured via handlerTimeout parameter), it should return data via stdout on success and should return the specific exit codes (described below) on error. An optional error string may be returned via stderr.

Invocation, Return Codes and Data¶

The WSS invokes the handler program via a two stage process. In the Stage 1, the handler program is invoked with all the its attendant arguments. The WSS then waits for a response. This response can be either

1. A *NIX return code (usually indicating an error)
2. Data on stdout (interpreted as 'SUCCESS')

or, if the handler fails to return a return code or data via stdout, a timeout occurs and the handler program is aborted and the web service receives the appropriate error response.

If data appears, Stage 2 commences. At this point, the WSS returns an 'OK' HTTP response to the client and begins streaming whatever data the handler returns directly to the client via HTTP.

Command Line Arguments¶

Command line arguments corresponding to query parameter name / value pairs will be added to the invoking command line of the handler program. Only those parameters configured in param.cfg will be added. All extraneous query parameters will cause an exception to be thrown by the WSS. Each query parameter pair i.e. &quality=B will be translated into --quality B on the command line.

Double hyphen '--' standard always used
Query parameter spelling is not translated. I.e. the name of the parameter on the URL translated directly into the argument to the handler, e.g. &network=IU on the URL becomes --network IU on the command line.

Only parameters configured via param.cfg are passed as parameters to the handler [3 exceptions below]

1. Except &output=FORMAT / --output FORMAT. This is not configured in the param.cfg file, but is always allowed. It is parsed by the WSS and then passed to the handler.
2. Except --username USER which is not a query parameter and is added by the WSS for authenticated access and is based on the result of the container's authentication procedures.
3. Except --STDIN which is not a query parameter. It is added as a parameter if HTTP POST is used (rather than HTTP GET). This indicates to the handler that it should
   process stdin.

Also, the query parameter &nodata=[205|404] is not added to the command line and affects only the WSS response itself.

Errors and Return Codes¶

Handler return codes and their translation into HTTP Status codes should conform to the following specification

Exit Status	HTTP STATUS	Description
0	200	Successfully processed request, data returned via stdout
1	500	General error. An error description may be provided on stderr
2	204	No data. Request was successful but results in no data
3	400	Invalid or unsupported argument/parameter
4	413	Too much data requested

Note that Entry '4' above, HTTP Status 204, can be translated to a 404 based on both an application parameter configuration or overridden by the client with a specific query parameter nodata=....

Timing out.¶

Timeouts can occur at any point after the handler program is invoked. The WSS will terminate the handler program if it fails to return a *NIX return code (or data) within the timeout period during Stage 1 or if it fails to produce data during Stage 2 for a period of time in excess of the timeout period. If a timeout occurs, the handler program is terminated.

If the timeout occurs during Stage 1, an appropriate error response is sent to the client. If it occurs during Stage 2, the transaction is terminated and the connection closed.

Error Text¶

If the handler program writes text via stderr during Stage 1 and an error code is received by the WSS, the WSS will include the error text in the error response sent to the client.

Output Formats¶

The WSS should be configured for the same output format (MIME type) that the handler program produces. The WSS uses the output type to a) Tell the HTTP client in what format the data is [Content-Type] and b) in the suggested file name [Content-Disposition]. A conflict between the configuration and the handler's output will not cause any harm, but will confuse clients.

The output format can be overridden via the URL using the &output=FORMAT query parameter. As in the configuration in the service.cfg file, the allowable values are limited:

||output value||MIME type |xml|application/xml |seed|application/vnd.fdsn.seed |text|text/plain |texttree|text/plain |json|application/json