htp

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

Languages / 简体中文
If links in this document not avaiable, please access README on GitHub directly.

Table of Contents

• Description
• ToC
• Links
• Get Started
• API
  • The Response Object
  • Basic API
  • Piping API
  • Advanced API
  • Class SimpleAgent
  • Timeline
• About
• Recommendations

Description

Another choice for you to finish HTTP or HTTPS request.

ToC

• Get Started
• API
  • Basic API
  • Piping API
  • Advanced API
  • Class SimpleAgent
  • Timeline
• About
• Recommendations

Links

• CHANGE LOG
• Homepage

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:

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.

Recommendations

• osapi or ceph
• urx
• proksy