Working with Handlers » History » Version 20

Version 19 (Mike Stults, 05/18/2016 03:34 PM) → Version 20/97 (Mike Stults, 05/18/2016 03:49 PM)

h1. Working with Handler Programs

h2. 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.

h3. 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

# A *NIX exit status code (usually indicating an error)
# 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.

h3. Command Line Arguments

WSS invokes a handler and provides command line arguments to the handler corresponding to respective query parameter name - value pairs. Only those parameters configured in @param.cfg@ will be provided. Any other query parameters will cause an exception to be thrown by the WSS. Each query parameter pair e.g. @&quality=B@ will be translated into a command line form of @--quality B@.

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

Query parameter syntax spelling is *not* translated, i.e. each translated. I.e. the _name_ of the parameter on the URL is translated directly into a respective command line form, 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 [with the following exceptions] [3 exceptions below]

# Except @--username USER@ which is _not_ a query parameter and is added by the WSS when a user needing for authenticated access and is based on the result of the container's authentication has has made a successful authenticated request. procedures.
# Except @--STDIN@ which is _not_ a query parameter. It is added by WSS as a parameter if a client request uses _HTTP POST_ rather is used (rather than _HTTP GET_. A GET_). This indicates to the handler that it should use this parameter to indicate it needs to read @stdin@ to get the post data.
# 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. process stdin.

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

h3. 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=...@.

h3. 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.

h3. 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.

h3. 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|

These are the output types recognized by the WSS and does not imply what any given service or handler must support.

h3. Environment Variables Set by the WSS

The WSS sets certain pre-defined 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|

h3. Handling Network Interruptions

It is somewhate common for the network connection from the client to the handler to be interrupted. This can occur due to the network connection being dropped, some problem in any intermediate network stage, 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 via dataselect and then dismissed the File Save dialog via 'Cancel'.

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