@request/core v0.1.0

@request/core

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.

Options

URL

url/uri

• String
• url.Url

qs

• Object
• String

Body

form

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

json

• Object

body

• 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.

Authentication

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

Modifiers

gzip

• 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.

Misc

cookie - requires tough-cookie

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

length

• true defaults to false if omitted

callback

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

redirect

• 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

timeout

• 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

proxy

• 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

parse

• {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 module instead
  • querystring.parse options to use

stringify

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

end

• true tries to automatically end the request on nextTick

HTTPDuplex

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

Methods

• Request the HTTPDuplex child class

Events

• 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)

req/res

• headers is instance of the @request/headers module

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

Logger

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

Errors

oauth

• 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

Notice

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