Usa NPM | npm.io

htp

Maybe the easiest but still strong http client you have ever meet.

Languages / [简体中文](./README.zh_CN.md)  
If links in this document not avaiable, please access [README on GitHub](./README.md) directly.

Description

Another choice for you to finish HTTP or HTTPS request.

Get Started

var htp = requrie('htp');
// OR, since v0.3.0, an alias "usa" is available.
var htp = require('usa');

// GET & callback
htp.get('http://www.example.com/', function(err, response) {
	if (err) {
		// Exception throwed on requesting.
	}
	else {
		// Response received.
		response.statusCode;
		response.statusMessage;
		response.httpVersion;
		response.headers;
		response.body;
		response.bodyBuffer;
		response.bodyDecompressed;
		response.performance;
	}
});

// POST & promise
var data = { username: 'youngoat', password: 'helloworld' };
htp.post('http://www.example.com/login', data).then(function(response) {
	// ...
}).catch(function(err) {
	// ...
});

// Customized settings.
var client = new htp({
	response_timeout: 1000
});
client.request('GET', 'http://www.example.com/', function(err, response) {
	// ...
});

API

The Response Object

If request achieved successfully, a Response object will be passed. The Response object SHOULD contain the following properties:

response.statusCode number
response.statusMessage string
response.httpVersion string
response.headers Object
response.body string | Object(json) | null
response.bodyBuffer Buffer | null
response.bodyDecompressed
response.performance Object

Basic API

// To execute request with default settings.
htp(
	/*string*/ REQUSET_METHOD_NAME,
	/*string*/ URL,
	/*OPTIONAL object*/ HEADERS,
	/*OPTIONAL string | object | stream.Readable*/ BODY,
	/*OPTIONAL function*/ CALLBACK
);

HEADERS, BODY and CALLBACK are all optional.
htp returns undefined while CALLBACK offered, otherwise a promise will be returned.
htp distinguishes arguments by their types and order. However, it may be ambiguous if there is one, but only one object argument offered. What is it regarded as, HEADERS or BODY? If the method is defined with explicit payload, the object will be regarded as BODY, otherwise it will be regarded as HEADERS. See methods-without-payloads.js for details.

Another style maybe many coders prefer to is htp.<lowercase_method_name>( /* ... */ ), e.g.

htp.get('http://www.example.com/', function(error, response) {
	// ...
});

Without CALLBACK offered, htp will return a promise.

htp.get('http://www.example.com/')
	.then(function(response) { /* ... */ })
	.catch(function(error) { /* ... */ })
	;

Piping API

Since v0.1.0, a streamable subset htp.piping is available. Whether or not CALLBACK offered, it will always return a readable stream.

htp.piping
	.get('http://download.example.com/data.json')
	.pipe(fs.createWriteStream('data.json'))
	;

// A property function named with "piping" prefixed (in camelCase) is equivalent.
htp
	.pipingGet('http://download.example.com/data.json')
	.pipe(fs.createWriteStream('data.json'))
	；

The stream returned by htp.piping.<method>() may emit following events:

Event: 'dns'
- { address string, family number }
Event: 'connect'
Event: 'response'
- response Object
  Along with argument response which is a subset of the final response object.
events which a readable stream may emit
See Class: stream.Readable for details.

ATTENTION: Which returned by htp.piping.<method>() and then returned by .pipe() are not the same stream.

Advanced API

// Create a customized user-agent.
var request = new htp({
	hostname: 'www.example.com',
});

request.get('/index.html', function(err, response) {
	// ...
});

Here are options available when creating a customized user agent:

options.protocol ENUM('http', 'https')
Default protocol.
options.hostname string
Default hostname (port excluded).
options.port number Default port.
options.piping boolean
If set true, a readable stream will be returned whether or not CALLBACK is present. Otherwise, a promise will be returned when CALLBACK is absent.
options.pipingOnly boolean
Only effective in piping mode. If set true, reponse data will no longer be staged and returned, and argument response passed to CALLBACK will no longer have properties { body, bodyBuffer, bodyDcompressed }. You can only obtain response data through pipe.
options.proxy string
Proxy, e.g. "http://localhost:8080/".
options.request_timeout number (unit: ms)
Max time to finish the whole request.
options.dns_timeout number (unit: ms)
Max time to resolve hostname.
options.dns_ttl number (unit: seconds)
Time-to-live of DNS resolving result.
options.dnsAgent dns-agent
An instance of dns-agent.
options.plugin_timeout number (unit: ms)
Max time to plug into socket.
options.connect_timeout number (unit: ms)
Max time to shake-hands with target server.
options.response_timeout number (unit: ms)
Max time to recieve the first response from target server.
options.chunk_timeout number (unit: ms)
Max time two data chunks.
options.data_timeout number (unit: ms)
Max time to receive all data.

Some options from tls.connect() are also accepted and will be applied on HTTPs requests:

options.rejectUnauthorized boolean

See settings.js for default values of options.

Class SimpleAgent

By creating an instance of SimpleAgent, developers are able to create a customized and resuable htp.

var Agent = require('htp/SimpleAgent');

// Create an instance.
var agent = new Agent({
	endPoint: 'http://www.example.com/'
});

var p = agent.get('/index.html');
p.then(function(bodyBuffer) {
	console.log(bodyBuffer.toString('utf8'));
}).catch(function(err) {
	// ...
});

Acceptable options accepted by htp/SimpleAgent are:

Function beforeRequest({ method, url, headers, body, callback })
If offered, this function will be invoked with an object passed in before real HTTP request starts. The passed in object is made up five properties. The function SHOULD return void or an object made up all or some of the properties. If an object returned, the properties will be used on requesting.
Function beforeCallback(error, data)
If offered, this function will be invoked before callback invoked. The returned value will be used as real data and passed to callback(null, data) or resolve(data).
string endPoint
object headers
object query
object settings
Settings used to customise the user-agent. See Advanced API.

Timeline

Here is the timeline of an htp request:
HTP request process

About

For convenience, this package has following names (alias):

htp
Because the main business of this package is to execute HTTP/HTTPS requests, I named it htp which looks like http with double t replaced by one.
usa
It is not the United States of America. usa is abbreviation of USerAgent.