cogent

[![NPM version][npm-image]][npm-url]
[![build status][travis-image]][travis-url]
[![Test coverage][coveralls-image]][coveralls-url]
[![Gittip][gittip-image]][gittip-url]

[npm-image]: https://img.shields.io/npm/v/cogent.svg?style=flat
[npm-url]: https://npmjs.org/package/cogent
[travis-image]: https://img.shields.io/travis/cojs/cogent.svg?style=flat
[travis-url]: https://travis-ci.org/cojs/cogent
[coveralls-image]: https://img.shields.io/coveralls/cojs/cogent.svg?style=flat
[coveralls-url]: https://coveralls.io/r/cojs/cogent?branch=master
[gittip-image]: https://img.shields.io/gittip/jonathanong.svg?style=flat
[gittip-url]: https://www.gittip.com/jonathanong/

A simple HTTP request agent designed primarily for GETing stuff.

Features

- Resolve redirects
- Timeout support
- Automatic gunzipping
- First-class JSON support
- Buffer the response or save it to a file

API

``js
var request = require('cogent')

var uri = 'https://raw.github.com/visionmedia/express/master/package.json'

// Pipe stdout
var res = yield* request(uri)
res.pipe(process.stdout)

// Save to a file
var res = yield* request(uri, require('os').tmpdir() + '/express.package.json')
if (res.destination) console.log('ok')

// Get as JSON
var res = yield* request(uri, true)
var json = res.body
`

You can also use it without generators by wrapping it with co:

`js
var co = require('co')
var request = co(require('cogent'))

request('https://github.com', function (err, res) {
res.pipe(process.stdout)
})
`

$3

url is the URL of the request.
The options are passed to http.request().
Additional options are:

- buffer - buffer the response and save it as res.buffer
- string - buffer the response as a string and save it as res.text
- json - buffer the response as an object and save it as res.body
- destination - cojs/cogent the response to the file destination
- timeout - response header timeout per try, default 5000 milliseconds
- retries - number of retries when request fails due to common server errors, default 0
- redirects - resolve redirects, default 1

If options === true, it defaults to { json: true }.
If typeof options === 'string', it defaults to { destination: string }.

response will have the following properties:

- res.req - the request object
- res.res - the response object, itself if the response was not gzipped
- res.statusCode
- res.headers
- res.destination - populated only if the file was successfully saved on a 200
- res.buffer
- res.text
- res.body - JSON body populated only on a 200

$3

Create a new cogent instance with default options. This allows you to avoid setting the same options every time. See the options listed above.

- retries
- redirects
- timeout
- method
- gunzip
- netrc
- agent


`js
var request = require('cogent').extend({
auth: 'username:password'
})

var res = yield* request('http://localhost/', true)
// will send with auth header
``