Working with Handlers » History » Version 94

Mike Stults, 08/17/2016 02:50 PM

1 5 Rich Karstens
h1. Working with Handler Programs
2 1 Rich Karstens
3 13 Rich Karstens
h2. Requirements of a _Handler_ Program
4 1 Rich Karstens
5 19 Mike Stults
There are few requirements on a handler program.  Essentially a handler should:
6 19 Mike Stults
* return data or error message within the time allotted by the WSS (configured via the endpoint @handlerTimeout@ parameter),
7 19 Mike Stults
* write data to @stdout@ and write error messages to @stderr@
8 33 Mike Stults
* read arguments from command line, additionally, if WSS is configured for POST, then read POST data from stdin
9 19 Mike Stults
* exit with respective exit status codes described below.
10 1 Rich Karstens
11 70 Mike Stults
h2. Concept of Operation
12 1 Rich Karstens
13 38 Mike Stults
WSS manages command-line programs in two distinct phases:
14 38 Mike Stults
# Phase 1
15 84 Mike Stults
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 handler is expected to:
16 88 Mike Stults
** may write HTTP header information to @stdout@
17 82 Mike Stults
*** The CmdProcessor saves header information.
18 85 Mike Stults
** write data to @stdout@
19 83 Mike Stults
*** 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.
20 86 Mike Stults
** exit with, or without, a *NIX exit status code
21 81 Mike Stults
*** The CmdProcessor returns a respective error code and error message to the client.
22 84 Mike Stults
** do nothing
23 87 Mike Stults
*** The CmdProcessor will timeout the handler process, kill the handler, and return a respective error message to the client
24 40 Mike Stults
# Phase 2
25 41 Mike Stults
Once a handler starts writing data to stdout, the Tomcat framework starts streaming the data to a client.
26 42 Mike Stults
** If the handler exits, log messages are written out and the process ends.
27 48 Mike Stults
** 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:
28 48 Mike Stults
29 47 Mike Stults
30 1 Rich Karstens
This data stream was interrupted and is likely incomplete.     \n
31 1 Rich Karstens
32 48 Mike Stults
33 48 Mike Stults
34 46 Mike Stults
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.
35 13 Rich Karstens
36 66 Mike Stults
h2. Query Parameters and Command-line Arguments
37 29 Mike Stults
38 51 Mike Stults
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@.  
39 20 Mike Stults
40 1 Rich Karstens
The double hyphen '--' command line standard is always used.
41 20 Mike Stults
42 1 Rich Karstens
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.
43 20 Mike Stults
44 52 Mike Stults
*Only* parameters configured via @param.cfg@ are passed to the handler, but WSS may add the following parameters
45 52 Mike Stults
# @--username USER@ is added by WSS when a user has been successfully authenticated.
46 52 Mike Stults
# @--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.
47 52 Mike Stults
48 54 Mike Stults
For the URL query parameters, WSS will accept by default: 
49 89 Mike Stults
# @&nodata=404 or &nodata=204@, setting 404 will instruct WSS to explicitly return an error message and HTTP 404 Not Found when there is no data, rather than the HTTP default of 204 No Content and no message to the client.
50 90 Mike Stults
# @&format=formatType@ may be used to select a formatType, however, only BINARY is available unless the formatTypes parameter is defined for additional types.
51 21 Mike Stults
52 49 Mike Stults
h2. Exit Status Codes
53 21 Mike Stults
54 1 Rich Karstens
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@.
55 1 Rich Karstens
56 1 Rich Karstens
|_.Exit Status|_.HTTP STATUS|_.Description|
57 1 Rich Karstens
|0|200|Successfully processed request, data returned via stdout|
58 6 Rich Karstens
|1|500|General error.  An error description may be provided on stderr|
59 7 Rich Karstens
|2|204|No data.  Request was successful but results in no data|
60 1 Rich Karstens
|3|400|Invalid or unsupported argument/parameter|
61 7 Rich Karstens
|4|413|Too much data requested|
62 21 Mike Stults
63 91 Mike Stults
Note: For exit status code 2, query parameter @nodata@ can be used to have WSS return a 404 to the WSS client rather than 204.
64 1 Rich Karstens
65 69 Mike Stults
h2. Timing out and Network Interruptions
66 30 Mike Stults
67 93 Mike Stults
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 after the HTTP 200 OK is returned to the client, but before all the data is sent.  Therefore, the client should check that all the expected data was received, see the "STREAMERROR" message described above in the Phase 2 operations above.
68 13 Rich Karstens
69 67 Mike Stults
h3. Handling Network Interruptions
70 67 Mike Stults
71 67 Mike Stults
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'.  
72 67 Mike Stults
73 94 Mike Stults
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, WSS will attempt to terminate its handler.  This prevents zombie handler processes.
74 68 Mike Stults
75 56 Mike Stults
h2. Error Text
76 22 Mike Stults
77 56 Mike Stults
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.
78 1 Rich Karstens
79 56 Mike Stults
h2. Output Formats
80 31 Mike Stults
81 31 Mike Stults
Each WSS endpoint should be configured for all of the media types that a handler program produces.  WSS uses the @format@ parameter to
82 31 Mike Stults
* a) indicate to the HTTP client what media type the data is represented in [i.e. HTTP header item @Content-Type@] and
83 1 Rich Karstens
* b) to suggested a file name [i.e. HTTP header item @Content-Disposition@] if the data is downloaded to a file. 
84 22 Mike Stults
85 61 Mike Stults
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:
86 22 Mike Stults
87 1 Rich Karstens
|_. formatType |_.Media type|
88 16 Chad Trabant
89 1 Rich Karstens
90 10 Chad Trabant
91 1 Rich Karstens
92 10 Chad Trabant
93 11 Chad Trabant
94 62 Mike Stults
By default without configuration, WSS defines one formatType, "binary" corresponding to media type "application/octet-stream".
95 62 Mike Stults
96 62 Mike Stults
97 62 Mike Stults
* The first item on the list is the default format used when none is specified.
98 62 Mike Stults
* 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.
99 18 Rich Karstens
100 61 Mike Stults
h2. Environment Variables Set by the WSS
101 31 Mike Stults
102 65 Mike Stults
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.
103 18 Rich Karstens
104 18 Rich Karstens
|_.Varible name|_.Value|
105 18 Rich Karstens
|REQUESTURL|The URL of the incoming request|
106 18 Rich Karstens
|USERAGENT|User agent string supplied in the HTTP header for this request|
107 18 Rich Karstens
|IPADDRESS|IP Address of the request's client|
108 1 Rich Karstens
|APPNAME|Application name supplied via the @appName@ parameter from the service configuration|
109 1 Rich Karstens
|VERSION|Application version supplied via the @version@ parameter from the service configuration|
110 23 Mike Stults
|CLIENTNAME|not currently in use|
111 23 Mike Stults
|HOSTNAME|host name of WSS server|
112 1 Rich Karstens
|AUTHENTICATEDUSERNAME |Authenticated user name, only present if a user was authenticated|