@request/core

# @request/core HTTP Duplex Streams2 client. By default it behaves identically to Node's Core [http.request][node-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][request-multipart] Pass `Object` for `multipart/form-data` body: ```js // 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`: ```js // 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][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][redirect-option] to be enabled. - Digest authentication requires the [@request/digest][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][request-oauth] #### hawk - requires [hawk][hawk] #### httpSignature - requires [http-signature][http-signature] #### aws - requires [aws-sign2][aws-sign2] ## Modifiers #### gzip - `gzip: true` - Pipes the response body to [zlib][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][iconv-lite] - `encoding: true` - Pipes the response body to [iconv-lite][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][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` ```js { 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][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][node-querystring] module instead - `querystring.parse` options to use #### stringify - `{qs: {sep:';', eq:':'}}` - `qs.stringify` options to use - `{querystring: {sep:';', eq:':', options: {}}}` use the [querystring][node-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][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][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][tough-cookie] jar --- ## Logger Requires [@request/log][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) ```bash $ 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][request] by [request contributors][request-contributors]. [request]: https://github.com/request/request [request-contributors]: https://github.com/request/request/graphs/contributors [zlib]: https://iojs.org/api/zlib.html [node-http-request]: https://nodejs.org/api/http.html#http_http_request_options_callback [tough-cookie]: https://github.com/SalesforceEng/tough-cookie [iconv-lite]: https://www.npmjs.com/package/iconv-lite [hawk]: https://github.com/hueniverse/hawk [aws-sign2]: https://github.com/request/aws-sign [http-signature]: https://github.com/joyent/node-http-signature [tunnel-agent]: https://github.com/mikeal/tunnel-agent [request-core]: https://github.com/request/core [request-headers]: https://github.com/request/headers [request-digest]: https://github.com/request/digest [request-oauth]: https://github.com/request/oauth [request-multipart]: https://github.com/request/multipart [request-log]: https://github.com/request/log [redirect-option]: #redirect