Request Namespace Reference

wilton/Request
HTTP requests handling for wilton/Server. More...

Functions
Undefined	closeWebSocket (Function|Undefined callback)
	Close WebSocket connection.
String	data (Function|Undefined callback)
	Access request body.
String	dataFilename (Function|Undefined callback)
	Get the name of the temporary file with request data.
String	form (Function|Undefined callback)
	Access application/x-www-form-urlencoded request body.
Undefined	getWebSocketId (Function|Undefined callback)
	Return the ID of the WebSocket connection.
Object	headers (Function|Undefined callback)
	Access request headers.
Object	json (Function|Undefined callback)
	Access request body as JSON.
Object	meta (Function|Undefined callback)
	Access request's metadata.
Object	queries (Function|Undefined callback)
	Access request query string parameters.
String	query (String name, String defaultValue, Function|Undefined callback)
	Access request quesry string parameter by name.
Number	retainWebSocket (Function|Undefined callback)
	Retain WebSocket connection to use it from another thread.
Undefined	sendMustache (String filePath, Object values, Object|Undefined options, Function|Undefined callback)
	Send rendered mustache template to client.
Undefined	sendRedirect (String location, Function|Undefined callback)
	Redirect client to the specified URL.
Undefined	sendResponse (String|Object data, Object|Undefined options, Function|Undefined callback)
	Send string or JSON response to client.
Number	sendResponseLater (Function|Undefined callback)
	Delay sending the response.
Undefined	sendTempFile (String filePath, Object|Undefined options, Function|Undefined callback)
	Send contents of temporary file to client.
Undefined	sendWebSocket (String|Object data, Object|Undefined options, Function|Undefined callback)
	Send string or JSON response to client over WebSocket.

Detailed Description

This module provides a Request "class", which instances are passed to handler functions registered with wilton/Server.

Each handler function receives Request instance as an only parameter and must use sendResponse(), sendTempFile(), sendMustache() or sendWebSocket() methods to return the response to client

Usage example:

// handler function for GET requests
GET: function(req) {

    // return JSON response including some request details into it
    // and specified custom status code and message
    req.sendResponse({
        msg: "hello from GET handler",
        receivedQueries: req.queries(),
        hostnameClientSpecified: req.headers()["Host"]
    }, {
        meta: {
            statusCode: 451,
            statusMessage: "Unavailable For Legal Reasons"
        }
    });
}

Function Documentation

Undefined Request::closeWebSocket

(

Function|Undefined

callback

)

Closed WebSocket sending close frame to client and closing the underlying TCP connection

Parameters

callback

Function|Undefined callback to receive result or error

Returns

Undefined

String Request::data

(

Function|Undefined

callback

)

Returns request body as a String. Empty string is returned for GET requests.

If input request data was saved into temporary file (due to requestPayload.memoryLimitBytes server config parameter exceeded), that file will be read into memory on the first call to this method.

Data is fetched once using a native call and is cached locally inside Request object after that.

Parameters

callback

Function|Undefined callback to receive result or error

Returns

String request body

String Request::dataFilename

(

Function|Undefined

callback

)

Returns a path to the temporary file that was used to store request data.

If input request data was not saved into temporary file (processed in memory due to requestPayload.memoryLimitBytes Server configuration parameter was not exceeded),request data will be written into temporary file on the first call to this method.

requestPayload.tmpDirPath Server configuration parameter must be specified for this method to work.

Path to temporary file fetched once using a native call and is cached locally inside Request object after that.

Parameters

callback

Function|Undefined callback to receive result or error

Returns

String path to temporary file with request body

String Request::form

(

Function|Undefined

callback

)

Returns request body as a JSON object.

If input request data was saved into temporary file (due to requestPayload.memoryLimitBytes server config parameter exceeded), that file will be read into memory on the first call to this method.

Form data is fetched once using a native call and is cached locally inside Request object after that.

Parameters

callback

Function|Undefined callback to receive result or error

Returns

String request body

Undefined Request::getWebSocketId

(

Function|Undefined

callback

)

Returns the ID of the current WebSocket connection. This ID can be used to filter Server.broadcastWebSocket messages.

For HTTP requests returns empty string.

Parameters

callback

Function|Undefined callback to receive result or error

Returns

Undefined

Object Request::headers

(

Function|Undefined

callback

)

Returns dictionary of request headers. The same as meta().headers.

Parameters

callback

Function|Undefined callback to receive result or error

Returns

Object dictionary of request parameters parsed from URL query fields

Object Request::json

(

Function|Undefined

callback

)

Returns request body parsed as a JSON object.

If input request data was saved into temporary file (due to requestPayload.memoryLimitBytes Server configuration parameter was exceeded), that file will be read into memory on the first call to this method.

JSON body is fetched once using a native call and is cached locally inside Request object after that.

Parameters

callback

Function|Undefined callback to receive result or error

Returns

Object request body as JSON object

Object Request::meta

(

Function|Undefined

callback

)

Returns a metadata object for this request.

Metadata is fetched once using a native call and is cached locally inside Request object after that.

Parameters

callback

Function|Undefined callback to receive result or error

Returns

Object metadata object with the following fields:

• httpVersion String HTTP protocol version
• protocol String protocol name, HTTP or HTTPS
• method String request HTTP method
• url String request URL, as specified by client
• pathname String "path" part of the URL (before the first ?)
• query String "query" part of the URL (after the first ?)
• queries Object dictionary of request parameters parsed from URL query fields
• headers Object request headers in "Header-Name": "value" format, duplicates in client-specified headers are handled in the following ways, depending on the header name: duplicates of age, authorization, content-length, content-type, etag, expires, from, host, if-modified-since, if-unmodified-since, last-modified, location, max-forwards, proxy-authorization, referer, retry-after, or user-agent are discarded; for all other headers, the values are joined together with ,

Object Request::queries

(

Function|Undefined

callback

)

Returns dictionary of request parameters parsed from URL query fields. The same as meta().queries.

Parameters

callback

Function|Undefined callback to receive result or error

Returns

Object dictionary of request parameters parsed from URL query fields

String Request::query	(	String	name,
		String	defaultValue,
		Function|Undefined	callback
	)

Returns the value of the specified parameter from request string, or specified defaultValue if parameter not found.

Parameters

name	String parameter name
defaultValue	String default value
callback	Function|Undefined callback to receive result or error

Returns

String parameter value or default value

Number Request::retainWebSocket

(

Function|Undefined

callback

)

Creates a webSocketHandle, that can be transfered to other thread and used here to create DelayedWebSocket.

While being in delayed state, this WebSocket connection does not process incoming messages (they are buffered meanwhile).

DelayedWebSocket can be used only for a single operation - either sending a message to client or closing the connection.

Parameters

callback

Function|Undefined callback to receive result or error

Returns

Number webSocketHandle that can be used to create a DelayedWebSocket inside another thread

Undefined Request::sendMustache	(	String	filePath,
		Object	values,
		Object|Undefined	options,
		Function|Undefined	callback
	)

Renders mustache template using specified input values and send it to client. Rendered response is sent in streaming mode without holding the whole response in memory.

Mustache partials are loaded automatically from directories, specified using mustache.partialDirs Server configuration parameter.

Parameters

filePath	String path to mustache template file; if specified file ends with .js, this extension will be stripped and .html extension will be appended
values	Object input values to render the template with
options	Object|Undefined configuration object, see possible options below
callback	Function|Undefined callback to receive result or error

Returns

Undefined

Options

• meta Object response metadata
  • statusCode Number HTTP status code
  • statusMessage String HTTP status message
  • headers Object response headers in "Header-Name": "value" format

Undefined Request::sendRedirect	(	String	location,
		Function|Undefined	callback
	)

Sends 303 See Other with the specified location

Parameters

location	String URL to redirect clien to
callback	Function|Undefined callback to receive result or error

Returns

Undefined

Undefined Request::sendResponse	(	String|Object	data,
		Object|Undefined	options,
		Function|Undefined	callback
	)

Sends response to client converting specified object into JSON if necessary (Content-Type is set to application/json in this case).

Parameters

data	String|Object response body, object will be converted to JSON
options	Object|Undefined configuration object, see possible options below
callback	Function|Undefined callback to receive result or error

Returns

Undefined

Options

• meta Object response metadata
  • statusCode Number HTTP status code
  • statusMessage String HTTP status message
  • headers Object response headers in "Header-Name": "value" format

Number Request::sendResponseLater

(

Function|Undefined

callback

)

Creates a responseWriterHandle and releases the current thread without sending the response. Response can be sent to client later from any thread using the DelayedResponse, that must be created with the returned handle as an argument.

Parameters

callback

Function|Undefined callback to receive result or error

Returns

Number responseWriterHandle that can be used to create a DelayedResponse inside another thread

Undefined Request::sendTempFile	(	String	filePath,
		Object|Undefined	options,
		Function|Undefined	callback
	)

Sends to client contents of the specified file. File is deleted after sending the response.

File data is sent in streaming mode without reading the whole contents of the file into memory.

Parameters

filePath	String path to file to send
options	Object|Undefined configuration object, see possible options below
callback	Function|Undefined callback to receive result or error

Returns

Undefined

Options

• meta Object response metadata
  • statusCode Number HTTP status code
  • statusMessage String HTTP status message
  • headers Object response headers in "Header-Name": "value" format

Undefined Request::sendWebSocket	(	String|Object	data,
		Object|Undefined	options,
		Function|Undefined	callback
	)

Sends response to client converting specified object into JSON if necessary over the WebSocket connection

Parameters

data	String|Object response body, object will be converted to JSON
options	Object|Undefined configuration object, currently ignored
callback	Function|Undefined callback to receive result or error

Returns

Undefined