httpClient Namespace Reference

wilton/httpClient
HTTP client. More...

Functions
Undefined	closeQueue (Function|Undefined callback)
	Close requests queue for this thread.
Object	enqueueRequest (String url, Object options, Function|Undefined callback)
	Submit request to queue.
Undefined	initQueue (Object options, Function|Undefined callback)
	Initialize requests queue for this thread.
Array	pollQueue (Object options, Function|Undefined callback)
	Poll requests queue.
Object	sendFile (String url, Object options, Function|Undefined callback)
	Send specified file to server.
Object	sendFileByParts (String url, Object options, Function|Undefined callback)
	Send specified file to server by parts.
Object	sendRequest (String url, Object options, Function|Undefined callback)
	Send HTTP request to server.

Detailed Description

This module allows to send HTTP requests.

By default HTTP connections are cached into the single process-wide connection pool and can be reused from different threads.

This module supports HTTPS and request with X.509 client certificates.

Usage example:

// send GET request
var resp1 = http.sendRequest("https://google.com");

// send POST request
var resp2 = http.sendRequest(url, {
    data: "foo",
    meta: {
        method: "POST"
    }
});


// send file
var resp3 = http.sendFile(url, {
    filePath: "path/to/file.txt"
});

Function Documentation

Undefined httpClient::closeQueue

(

Function|Undefined

callback

)

Closes requests queue and de-allocates system resources used. If not called - resources cleanup will be done automatically on shutdown.

Must be called from the same thread queue was initialized from.

Parameters

callback

Function|Undefined callback to receive result or error

Returns

Undefined

Object httpClient::enqueueRequest	(	String	url,
		Object	options,
		Function|Undefined	callback
	)

Submits specified request to the queue for execution. initQueue must be called in the same thread before using this function.

Parameters

url	String URL of the HTTP server
options	Object configuration object, see supported options in sendRequest() function doc
callback	Function|Undefined callback to receive result or error

Returns

Object enqueued request, requestId is unique for the given queue

Undefined httpClient::initQueue	(	Object	options,
		Function|Undefined	callback
	)

Initializes HTTP requests queue allowing to use enqueueRequest and pollQueue operations. Queue is bound to the thread it is initialized from and can be used only from it.

closeQueue must be called from the same thread to de-allocate resources, alternatively resources cleanup will be done automatically on shutdown.

Parameters

options	Object configuration object, see possible options below.
callback	Function|Undefined callback to receive result or error

Returns

Undefined

options

• fdsetTimeoutMillis Number max allowed number of milliseconds to wait for activity on one of running requests, default value: 100
• maxHostConnections Number max number of connections to a single host, default value: 0 (unlimited)
• maxTotalConnections Number max number of simultaneously open connections, default value: 0 (unlimited)
• maxconnects Number max number of simultaneously open connections may be kept in connection cache after completed use, default value: 4 times the number of simultaneously run requests

Array httpClient::pollQueue	(	Object	options,
		Function|Undefined	callback
	)

Polls requests queue allowing enqued requests to perform the work. initQueue must be called in the same thread before using this function.

Parameters

options	Object currently not supported
callback	Function|Undefined callback to receive result or error

Returns

Array list of the responses for requests, that finished execution, see details on the structure of each response in sendRequest() function

Object httpClient::sendFile	(	String	url,
		Object	options,
		Function|Undefined	callback
	)

Sends specified file to server using POST request method by default.

Specified file is read in streaming mode without loading the whole file into memory.

Parameters

url	String URL of the HTTP server
options	Object configuration object, see file-specific options below; see other supported options in sendRequest() function doc
callback	Function|Undefined callback to receive result or error

Returns

Object response object, see details in sendRequest() function

Options

• filePath String path to file to send
• remove Boolean|Undefined whether to delete the file after sending, default value: false

Object httpClient::sendFileByParts	(	String	url,
		Object	options,
		Function|Undefined	callback
	)

Sends specified file to server using POST request method by default. File splitted into parts.

Specified file is read in streaming mode without loading the whole file into memory.

Parameters

url	String URL of the HTTP server
options	Object configuration object, see details in sendRequest() function and also sendOptions Object configuration object, see possible options below.
callback	Function|Undefined callback to receive result or error

Returns

Object response object, see details below

0 Array Array of response objects, see details insendRequest()function | strings with error messages 1 Array ... 2 Array ... ...

sendOptions

• fileName String name of file that will be created on server to store sended data
• fullTimeoutMillis Number|Undefinedconsumer threads wakeup timeout, in milliseconds, default value:10000, equal to 10 seconds.
• __maxChunkSize__Numbermaximum size of sent chunk
• __fileSize__Number|Undefinedthe size of the file being sent
• __filePath__String|Undefinedpath to file that will be sent.
• __url__String|Undefined` URL of the HTTP server

Object httpClient::sendRequest	(	String	url,
		Object	options,
		Function|Undefined	callback
	)

Sends HTTP request to server, received response can be stored in-memory or in the specified file (in this case response will be written into the file in streaming mode).

Parameters

url	String URL of the HTTP server
options	Object configuration object, see possible options below
callback	Function|Undefined callback to receive result or error

Returns

Object response object with the following fields:

• connectionSuccess Boolean true if the connection to server was successful, false otherwise
• data String data decoded as a String with invalid UTF-8 code sequences replaced with 0xFFFD
• json Function parses the contents of data field as a JSON, resulting JSON object is cached for this response instance - the same object is returned for the following json() invocations
• headers Object response headers in "Header-Name": "value" format
• effectiveUrl String final URL (after possible redirection) that was used
• responseCode Number HTTP response status code
• totalTimeSecs Number time that request have taken, in seconds
• namelookupTimeSecs Number time spent in DNS lookup, in seconds
• connectTimeSecs Number time spent establishing the connection, in seconds
• appconnectTimeSecs Number time until the SSL handshake is completed, in seconds
• pretransferTimeSecs Number time until the file transfer start, in seconds
• starttransferTimeSecs Number time until the first byte is received, in seconds
• redirectTimeSecs Number time for all redirection steps, in seconds
• redirectCount Number number of redirects
• speedDownloadBytesSecs Number download speed, in bytes per second
• speedUploadBytesSecs Number upload speed, in bytes per second
• headerSizeBytes Number size of response headers, in bytes
• requestSizeBytes Number size of sent request, in bytes
• sslVerifyresult Number result of the certificate verification
• osErrno Number error code returned by OS
• numConnects Number number of created connections
• primaryIp String IP address of last connection
• primaryPort Numbrer TCP port of last connection

Options

• data String|Object|Undefined data to send in request body, specified object will be converted to JSON
• meta: Object|Undefined request metadata
  • headers Object|Undefined request headers in "Header-Name": "value" format
  • method String|Undefined HTTP method to use for this request, default value is GET, if request data is not specified, POST otherwise
  • abortOnConnectError Boolean|Undefined whether to throw an Error on connection fail, default value: true
  • abortOnResponseError Boolean|Undefined whether to throw an Error, if response status code >=400 is returned, default value: true
  • maxNumberOfResponseHeaders Number|Undefined maximum number of response headers to receive, subsequent headers will be ignored, default value: 128
  • consumerThreadWakeupTimeoutMillis Number|Undefined consumer threads wakeup timeout, in milliseconds, default value: 100
  • requestDataFilePath String|Undefined path to file to send, only supported with enqueueRequest
  • responseDataFilePath String|Undefined path to file where to write the response body
  • forceHttp10 Boolean|Undefined whether to use HTTP 1.0 protocol closing the connection after the request, default value: false
  • noprogress Boolean|Undefined whether to swith off the progress meter, default value true
  • nosignal Boolean|Undefined whether to disable OS-signals handling, default value: true
  • failonerror Boolean|Undefined whether to close the connection and throw an Error on response code >=400,default value: false
  • pathAsIs Boolean|Undefined whether to not handle "dot sequences" in request URL, default value: true
  • tcpNodelay Boolean|Undefined whether to set the TCP_NODELAY connection option, default value: false
  • tcpKeepalive Boolean|Undefined whether to use TCK keep-alive probing, default value: false
  • tcpKeepidleSecs Number|Undefined TCP keep-alive idle time wait, in seconds, default value: 300
  • tcpKeepintvlSecs Number|Undefined TCP keep-alive interval, in seconds, default value: 300
  • connecttimeoutMillis Number|Undefined timeout for the connect phase, in milliseconds, default value: 10000
  • timeoutMillis Number|Undefined maximum time the request is allowed to take, in milliseconds, default value: 15000
  • buffersizeBytes Number|Undefined preferred receive buffer size, in bytes, default value: 16384
  • acceptEncoding String|Undefined enables automatic decompression of HTTP downloads, default value: gzip
  • followlocation Boolean|Undefined whether to follow HTTP 3xx redirects, default value: true
  • maxredirs Number|Undefined maximum number of redirects allowed, default value: 32
  • useragent String|Undefined user-agent string to send, default value: empty string
  • maxSentSpeedLargeBytesPerSecond Number|Undefined rate limit data upload speed, in bytes per second, default value: 0 (disabled)
  • maxRecvSpeedLargeBytesPerSecond Number|Undefined rate limit data download speed, in bytes per second, default value: 0 (disabled)
  • sslcertFilename String|Undefined path to SSL client certificate file
  • sslcertype String|Undefined type of the client SSL certificate
  • sslkeyFilename String|Undefined path to private keyfile for TLS and SSL client certificate
  • sslKeyType String|Undefined type of the private key file
  • sslKeypasswd String|Undefined passphrase to private key
  • requireTls Boolean|Undefined whether to require TLS connection rejectin older SSL algorithms, default value: false
  • sslVerifyhost Boolean|Undefined whether to verify the certificate's name against host, default value: false
  • sslVerifypeer Boolean|Undefined whether to verify the peer's SSL certificate, default value: false
  • sslVerifystatus Boolean|Undefined whether to verify the peer certificate's status, default value: false
  • cainfoFilename String|Undefined path to Certificate Authority (CA) bundle
  • crlfileFilename String|Undefined path to CRL file
  • sslCipherList String|Undefined ciphers to use for TLS
• - responseDataHex Boolean|Undefined whether to encode response data into hexadecimal format