YounGoathtp
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
Another choice for you to finish HTTP or HTTPS request.
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
undefinedwhile 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.
- 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 tocallback(null, data)orresolve(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.