Working with Handlers » History » Version 67
« Previous -
Version 67/97
(diff) -
Next » -
Current version
Mike Stults, 08/17/2016 01:48 PM
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 tostderr
- read arguments from command line, additionally, if WSS is configured for POST, then read POST data from stdin
- exit with respective exit status codes described below.
Invocation, Exit Status Codes and Data¶
WSS manages command-line programs in two distinct phases:- Phase 1
In this phase, WSS uses the CmdProcessor to create a process for the handler program, then invoke the program with all the its attendant arguments. The expected result is that the handler:- writes data on
stdout
exits
with, or without, a *NIX exit status code- does nothing
When the handler writes data to stdout, the CmdProcessor considers this a success condition and enters Phase 2 by returning 'OK HTTP 200 to the client, and returning control to the Tomcat framework. If the handler exits, the CmdProcessor returns a respective error code and error message to the client. When the handler does nothing, the CmdProcessor will timeout, kill the handler, and return a respective error message to the client
- writes data on
- Phase 2
Once a handler starts writing data to stdout, the Tomcat framework starts streaming the data to a client.- If the handler exits, log messages are written out and the process ends.
- If the handler does not exit, but stops writing data for a time that exceeds the timeout period, the handler process is killed, log messages are written out, and WSS attempts to write this 256 byte error string to the client:
000000##ERROR#######ERROR##STREAMERROR##STREAMERROR#STREAMERROR\n This data stream was interrupted and is likely incomplete. \n #STREAMERROR##STREAMERROR##STREAMERROR##STREAMERROR#STREAMERROR\n #STREAMERROR##STREAMERROR##STREAMERROR##STREAMERROR#STREAMERROR\n
Because the HTTP protocol does not allow a return code to the client at this point (it had to be sent prior to data streaming) it is suggested that clients check for this error string to help detect interrupted data retrievals.
Query Parameters and 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.
param.cfg
are passed to the handler, but WSS may add the following parameters
--username USER
is added by WSS when a user has been successfully authenticated.--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 readstdin
to get the post data.
&nodata=404 or &nodata=204
, setting 404 will instruct WSS to explicitly return an error message indicating no data, rather than the HTTP default of 204, which by definition does not return any information to the client when there is no data.&format=formatType
may be used to select a formatType, however, only BINARY is available unless the formatTypes parameter is defined for respective endpoints in the service.cfg file.
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 rather than the no-response of 204.
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 (i.e. handlerTimeout). 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, but after the client receives an HTTP 200 OK response. Therefore, the client must check that all the expected data was received.
Handling Network Interruptions¶
It is somewhat common for the network connection from the HTTP 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.
Error Text¶
If the handler program writes text to stderr
during Phase 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¶
Each WSS endpoint should be configured for all of the media types that a handler program produces. WSS uses theformat
parameter to
- a) indicate to the HTTP client what media type the data is represented in [i.e. HTTP header item
Content-Type
] and - b) to suggested a file name [i.e. HTTP header item
Content-Disposition
] if the data is downloaded to a file.
The data representation (i.e. media type) 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 one formatType, "binary" corresponding to media type "application/octet-stream".
Note:- The first item on the list is the default format used when none is specified.
- A conflict between the formatType specified (i.e. returned media type), and the handler's streamed output will not cause any harm, but will confuse clients.
Environment Variables Set by the WSS¶
The WSS CmdProcessor sets certain environment variables when starting a handler program. This allows the handler program to know about the HTTP request and the version of the WSS used with any eye towards logging; e.g. 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 somewhat common for the network connection from the HTTP 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.