0.1.0 • Public • Published


HTTP Duplex Streams2 client. By default it behaves identically to Node's Core http.request method.

Each additional feature must be enabled explicitly via option. Some options requires additional dependencies.




  • String
  • url.Url


  • Object
  • String



  • Object
  • String pass URL encoded string if you want it to be RFC3986 encoded prior sending


  • Object


  • Stream
  • Buffer
  • String
  • Array

multipart - requires @request/multipart

Pass Object for multipart/form-data body:

// set item
multipart: {photo: fs.createReadStream('cat.png')}
// pass additional info about the uploaded item
multipart: {
  photo: {
    value: fs.createReadStream('cat.png'),
    options: {filename: 'cat.png', contentType: 'image/png', knownLength: 22025}
// pass array of values for this item
multipart: {attachments: [fs.createReadStream('cat.png'), fs.createReadStream('dog.png')]}

The item's value can be either: Stream, Request, Buffer or String.

Pass Array for any other multipart/[TYPE], defaults to multipart/related:

// Example: Upload image to Google Drive
multipart: [
    'Content-Type': 'application/json',
    body: JSON.stringify({title: 'cat.png'})
    'Content-Type': 'image/png',
    body: fs.createReadStream('cat.png')

The body key is required and reserved for setting up the item's body. It can be either: Stream, Request, Buffer or String.

Additionally you can set preambleCRLF and/or postambleCRLF to true.


auth - digest auth requires @request/digest

  • {user: '', pass: '', sendImmediately: false}
    • Sets the Authorization: Basic ... header.
    • The sendImmediately option default to true if omitted.
    • The sendImmediately: false options requires the redirect option to be enabled.
    • Digest authentication requires the @request/digest module.
  • {bearer: '', sendImmediately: false}
    • Alternatively the Authorization: Bearer ... header can be set if using the bearer option.
    • The rules for the sendImmediately option from above applies here.

oauth - requires @request/oauth

hawk - requires hawk

httpSignature - requires http-signature

aws - requires aws-sign2



  • gzip: true
    • Pipes the response body to zlib Inflate or Gunzip stream based on the compression method specified in the content-encoding response header.
  • gzip: 'gzip' | gzip: 'deflate'
    • Explicitly specify which decompression method to use.

encoding - requires iconv-lite

  • encoding: true
    • Pipes the response body to iconv-lite stream, defaults to utf8.
  • encoding: 'ISO-8859-1' | encoding: 'win1251' | ...
    • Specific encoding to use.
  • encoding: 'binary'
    • Set encoding to 'binary' when expecting binary response.


cookie - requires tough-cookie

  • true
  • new require('tough-cookie).CookieJar(store, options)


  • true defaults to false if omitted


buffers the response body

  • function(err, res, body) by default the response buffer is decoded into string using utf8. Set the encoding property to binary if you expect binary data, or any other specific encoding


  • true follow redirects for GET, HEAD, OPTIONS and TRACE requests
  • Object
    • all follow all redirects
    • max maximum redirects allowed
    • removeReferer remove the referer header on redirect
    • allow function (res) user defined function to check if the redirect should be allowed


  • Number integer containing the number of milliseconds to wait for a server to send response headers (and start the response body) before aborting the request. Note that if the underlying TCP connection cannot be established, the OS-wide TCP connection timeout will overrule the timeout option


  • String
  • url.Url
  • Object
  proxy: 'http://localhost:6767'
  proxy: url.parse('http://localhost:6767')
  proxy: {
    url: 'http://localhost:6767',
    headers: {
      allow: ['header-name'],
      exclusive: ['header-name']

tunnel - requires tunnel-agent

  • true


  • {json: true}
    • sets the accept: application/json header for the request
    • parses JSON or JSONP response bodies (only if the server responds with the approprite headers)
  • {json: function () {}}
    • same as above but additionally passes a user defined reviver function to the JSON.parse method
  • {qs: {sep:';', eq:':'}}
    • qs.parse options to use
  • {querystring: {sep:';', eq:':', options: {}}} use the [querystring][node-querystring] module instead
    • querystring.parse options to use


  • {qs: {sep:';', eq:':'}}
    • qs.stringify options to use
  • {querystring: {sep:';', eq:':', options: {}}} use the [querystring][node-querystring] module instead
    • querystring.stringify options to use


  • true tries to automatically end the request on nextTick


Private Flags and State
  • _initialized set when the outgoing HTTP request is fully initialized
  • _started set after first write/end
  • _req http.ClientRequest created in HTTPDuplex
  • _res http.IncomingMessage created in HTTPDuplex
  • _client http or https module
  • _redirect boolean indicating that the client is going to be redirected
  • _redirected boolean indicating that the client is been redirected at least once
  • _src the input read stream, usually from pipe
  • _chunks Array - the first chunk read from the input read stream
  • _ended whether the outgoing request has ended
  • _auth whether basic auth is being used
  • _timeout timeout timer instance
Public Methods
  • init
  • abort



  • Request the HTTPDuplex child class


  • init should be private I guess
  • request req, options
  • onresponse res - internal event to execute options response logic
  • redirect res
  • response res
  • options emit @request/core options
  • body emit raw response body, either Buffer or String (the callback option is required)
  • json emit parsed JSON response body (the callback and the parse:{json:true} options are required)


Generated Options

  • url contains the parsed URL
  • redirect is converted to object containing all possible options including the followed state variable, containing the followed redirects count
  • auth containes sent state variable indicating whether the Basic auth is sent already
  • cookie is converted to object and containes the initial cookie header as a property
  • jar the internal tough-cookie jar


Requires @request/log

  • req prints out the request method, url, and headers
  • res prints out the response statusCode, statusMessage, and headers
  • http prints out the options object passed to the underlying http.request method
  • raw prints out the raw @request/core options object right before sending the request
  • body prints out the raw request and response bodies (the response body is available only when the callback option is being used)
  • json prints out the parsed JSON response body (only if the response body is a JSON one, and if the callback and parse.json options are being used)
$ DEBUG=req,res node app.js


  • oauth: transport_method: body requires method: POST and content-type: application/x-www-form-urlencoded
  • oauth: signature_method: PLAINTEXT not supported with body_hash signing


This module may contain code snippets initially implemented in request by request contributors.

Package Sidebar


Weekly Downloads






Last publish


  • request
  • simov