Working with Handlers » History » Version 29

« Previous - Version 29/97 (diff) - Next » - Current version
Mike Stults, 05/19/2016 09:27 AM

Working with Handler Programs

Requirements of a Handler Program

There are few requirements on a handler program. Essentially a handler should:
  • return data or error message within the time allotted by the WSS (configured via the endpoint handlerTimeout parameter),
  • write data to stdout and write error messages to stderr
  • exit with respective exit status codes described below.

Invocation, Exit Status 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 exit status code (usually indicating an error)
  2. Data on stdout (interpreted as 'SUCCESS')

or, if the handler fails to write anything or to return an exit status code, a timeout occurs and WSS kills the handler process and returns an error response to the WSS client.

If the handler starts writing data, Stage 2 commences. At this point, the WSS immediatly returns an 'OK' HTTP 200 response to the WSS client and begins streaming data received from the handler.

Command Line Arguments

WSS invokes a handler and provides command line arguments to the handler corresponding to respective query (parameter name, value) pairs. Only parameters configured in param.cfg are allowed. Any other query parameters will cause an error response from WSS. Each query (parameter name, value) pair e.g. &quality=B will be translated into a command line form of --quality B.

The double hyphen '--' command line standard is always used.

Query parameter syntax is not translated, i.e. each parameter on the URL is translated into a respective command line form, e.g. &network=IU on the URL becomes --network IU on the command line.

Only parameters configured via param.cfg are passed to the handler [with the following exceptions]

  1. Except --username USER is added by WSS when a user has been successfully authenticated.
  2. Except --STDIN is added by WSS if a client request uses HTTP POST rather than HTTP GET. A handler should use this parameter to indicate it needs to read stdin to get the post data.
  3. Except &nodata does not need to be defined in the param.cfg file, is always available for a query, but is never passed to the handler by WSS.

Exit Status Codes

WSS translates the following exit status codes from a handler into the respective HTTP Status for the WSS client. Additionally for errors, a handler should write a short, user oriented error message to stderr.

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: For exit status code 2, query parameter nodata can be used to have WSS return a 404 to the WSS client if desired.

Timing out.

Timeouts can occur at any point after the handler program is invoked. WSS will terminate the handler program if no data or exit status code is received within the configured timeout period. Once data flow starts, WSS returns an HTTP 200 OK status to the client, but the client will continue to receive data as long as the connection is maintained. Because HTTP protocol requires an HTTP status to be returned to a client before data starts downloading, it is possible for the the connection to drop or the handler to fail before all the data is sent to the client. Therefor, the client must check that all the expected data was received.

Error Text

If the handler program writes text to 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

WSS should be configured for all of the media types that a handler program produces. WSS uses the format parameter to
  • a) Tell the HTTP client what media type the data is [i.e. HTTP header item Content-Type] and
  • b) to suggested a file name [i.e. HTTP header item Content-Disposition].

A conflict between the configuration and the handler's output will not cause any harm, but will confuse clients.

The data format can be specified on a request by using the &format=formatType query parameter. The possible options should be defined with the formatTypes parameter in the service.cfg file, a typical list might be:

formatType Media type
xml application/xml
mseed application/vnd.fdsn.mseed
text text/plain
texttree text/plain
json application/json

By default without configuration, WSS defines formatType "binary" corresponding to media type "application/octet-stream".

Environment Variables Set by the WSS

The WSS sets certain environment variables for use (if needed) by a handler program. The general intention of these variables are to allow the handler program to know about the HTTP request and the version of the WSS used with any eye towards logging. I.e. if a handler program wished to perform its own 'per request' logging, this information would be vital. Below is a table with the environment variables.

Varible name Value
REQUESTURL The URL of the incoming request
USERAGENT User agent string supplied in the HTTP header for this request
IPADDRESS IP Address of the request's client
APPNAME Application name supplied via the appName parameter from the service configuration
VERSION Application version supplied via the version parameter from the service configuration
CLIENTNAME not currently in use
HOSTNAME host name of WSS server
AUTHENTICATEDUSERNAME Authenticated user name, only present if a user was authenticated

Handling Network Interruptions

It is somewhate common for the network connection from the client to the WSS to be interrupted. This can occur due to the network connection being dropped, or the client closing the connection while a transfer is ongoing. One common example is if the client is a browser, the user requests a SEED file, and then dismisses the File Save dialog via 'Cancel'.

A handler program should gracefully handle a network disconnection, clean up and exit. These disconnections may be detected via an IO Exception when the stdout connection to which the handler had been writing goes away. Defensive programming is always preferred, but, in general, nothing untoward happens with regard to WSS if the handler behaves badly. If the handler stops sending data for a long enough time, WSS will terminate it. If the interruption is upstream from WSS, i.e the client appears to disconnect, the current invocation of the WSS will attempt to terminate its handler. This prevents zombie handler processes.