Universal/Isomorphic HTTP(S) Request for Catberry Framework
Installation
npm install catberry-uhr
Description
Catberry's modules run both at the server and in a browser and it's very important to have a Universal/Isomorphic HTTP(S) Request implementation.
It has the same interface and different implementations at the server and in a browser.
At the server it uses node's http.request or https.request (depends on the specified protocol in URL). In a browser it uses a native XmlHttpRequest.
This module has been developed using HTTP/1.1v2 RFC 2616.
It supports:
gzip
anddeflate
request/response content encodingsapplication/json
andapplication/x-www-form-urlencoded
request/response content types- Request timeout
- Auto stringify/parse request/response data
- HTTP/HTTPS
- Any additional HTTP headers you set
UHR has following methods:
/** * Does a GET request to the HTTP server. * @param * @param {Object?} parameters The request parameters. * @param {Object?} parameters.headers The HTTP headers to send. * @param {(string|Object)?} parameters.data The data to send. * @param {number?} parameters.timeout The request timeout. * @param {boolean?} parameters.unsafeHTTPS If true then requests to servers with * invalid HTTPS certificates are allowed. * @returns */ {} /** * Does a POST request to the HTTP server. * @param * @param {Object?} parameters The request parameters. * @param {Object?} parameters.headers The HTTP headers to send. * @param {(string|Object)?} parameters.data The data to send. * @param {number?} parameters.timeout The request timeout. * @param {boolean?} parameters.unsafeHTTPS If true then requests to servers with * invalid HTTPS certificates are allowed. * @returns */ {} /** * Does a PUT request to the HTTP server. * @param * @param {Object?} parameters The request parameters. * @param {Object?} parameters.headers The HTTP headers to send. * @param {(string|Object)?} parameters.data The data to send. * @param {number?} parameters.timeout The request timeout. * @param {boolean?} parameters.unsafeHTTPS If true then requests to servers with * invalid HTTPS certificates are allowed. * @returns */ {} /** * Does a PATCH request to the HTTP server. * @param * @param {Object?} parameters The request parameters. * @param {Object?} parameters.headers The HTTP headers to send. * @param {(string|Object)?} parameters.data The data to send. * @param {number?} parameters.timeout The request timeout. * @param {boolean?} parameters.unsafeHTTPS If true then requests to servers with * invalid HTTPS certificates are allowed. * @returns */ {} /** * Does a DELETE request to the HTTP server. * @param * @param {Object?} parameters The request parameters. * @param {Object?} parameters.headers The HTTP headers to send. * @param {(string|Object)?} parameters.data The data to send. * @param {number?} parameters.timeout The request timeout. * @param {boolean?} parameters.unsafeHTTPS If true then requests to servers with * invalid HTTPS certificates are allowed. * @returns */ {} /** * Does a request to the HTTP server. * @param * @param {Object?} parameters The request parameters. * @param {string?} parameters.method The HTTP method for the request. * @param {string?} parameters.url The URL for the request. * @param {Object?} parameters.headers The HTTP headers to send. * @param {(string|Object)?} parameters.data The data to send. * @param {number?} parameters.timeout The request timeout. * @param {boolean?} parameters.unsafeHTTPS If true then requests to servers with * invalid HTTPS certificates are allowed. * @returns */ {}
Request options example
method: 'GET' timeout: 30000 // sets value to XMLHttpRequest.withCredentials, works only in a browser withCredentials: false unsafeHTTPS: false // requires valid certificate by default headers: Cookie: 'name=value' data: parameter: 'value' // all parameters will be URL encoded
In case you're doing POST
/PUT
/PATCH
requests, data
object will
be passed as application/x-www-form-urlencoded
via request stream.
If you set a Content-Type
header to application/json
then object will
be sent as JSON.
If data
value is not an object then its string representation will be sent
as text/plain
to the server.
Also, if you put anything to data
object and use
application/x-www-form-urlencoded
then this data will be
automatically percent-encoded.
Returns a promise
All UHR requests return a Promise for request result. Any error during request will reject the promise or it will be rejected by the request timeout.
Request result consists of following:
- The status object with HTTP status
code
, statustext
and responseheaders
- Response
content
as a plain text or an object (depends onContent-Type
in response headers)
For example, request result can be an object like this:
status: code: 200 text: 'OK' headers: 'cache-control': 'no-cache' 'content-length': '1' 'content-type': 'text/html; charset=utf-8' 'date': 'Tue, 08 Apr 2014 05:16:19 GMT' content: 'some content from server'
All header names are always in a lower-case like they are in node.js.
Usage
If you are using Catberry Framework you have to register UHR into Service Locator.
const cat = catberry;const uhr = ; uhr;
Then you can just resolve uhr
from the locator:
{ this_uhr = locator; } { const options = timeout: 3000 data: username: 'some' headers: Authorization: 'Bearer somecrazytoken' ; return this_uhr ; }
Contributing
There are a lot of ways to contribute:
- Give it a star
- Join the Gitter room and leave a feedback or help with answering users' questions
- Submit a bug or a feature request
- Submit a PR
Denis Rechkunov denis.rechkunov@gmail.com