Skip to content

YounGoat/nodejs.htp

Repository files navigation

htp

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

coverage status of github.com/YounGoat/nodejs.htp

total downloads of htp htp's License latest version of htp coverage status of github.com/YounGoat/nodejs.htp dependencies of github.com/YounGoat/nodejs.htp devDependencies of github.com/YounGoat/nodejs.htp build status of github.com/YounGoat/nodejs.htp star github.com/YounGoat/nodejs.htp

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

Table of Contents

Description

Another choice for you to finish HTTP or HTTPS request.

htp.logo

ToC

Links

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.

Recommendations