diff --git a/README.md b/README.md index c2d2ea4..304e6b2 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,7 @@ request('http://www.google.com', function (error, response, body) { ## Table of contents - [Forms](#forms) +- [HTTP Authentication](#http-authentication) - [Custom HTTP Headers](#custom-http-headers) - [Unix Domain Sockets](#unix-domain-sockets) - [**All Available Options**](#requestoptions-callback) @@ -100,6 +101,81 @@ form.append('custom_file', fs.createReadStream(__dirname + '/unicycle.jpg'), {fi See the [form-data README](https://github.com/form-data/form-data) for more information & examples. +--- + +## HTTP Authentication + + +```js +request.get('http://some.server.com/', { + 'auth': { + 'user': 'username', + 'pass': 'password', + 'sendImmediately': false + } +}); +// or +request.get('http://some.server.com/', { + 'auth': { + 'bearer': 'bearerToken' + } +}); +``` + +If passed as an option, `auth` should be a hash containing values: + +- `user` || `username` +- `pass` || `password` +- `bearer` (optional) + + + +Note that you can also specify basic authentication using the URL itself, as +detailed in [RFC 1738](http://www.ietf.org/rfc/rfc1738.txt). Simply pass the +`user:password` before the host with an `@` sign: + +```js +var username = 'username', + password = 'password', + url = 'http://' + username + ':' + password + '@some.server.com'; + +request({url: url}, function (error, response, body) { + // Do more stuff with 'body' here +}); +``` + + + +Bearer authentication is supported, and is activated when the `bearer` value is +available. The value may be either a `String` or a `Function` returning a +`String`. Using a function to supply the bearer token is particularly useful if +used in conjunction with `defaults` to allow a single function to supply the +last known token at the time of sending a request, or to compute one on the fly. + +[back to top](#table-of-contents) + +--- + ## Custom HTTP Headers HTTP Headers, such as `User-Agent`, can be set in the `options` object. @@ -241,6 +317,8 @@ These HTTP method convenience functions act just like `request()` but with a def - *request.head()*: Defaults to `method: "HEAD"`. - *request.options()*: Defaults to `method: "OPTIONS"`. +--- + ## Debugging There are at least two ways to debug the operation of `request`: diff --git a/index.js b/index.js index 78287c3..936c9dd 100644 --- a/index.js +++ b/index.js @@ -187,6 +187,22 @@ function setDefaults(defs) { // Transfer-Encoding: Chunked (the default) is generally only well-supported downstream finalOpts.headers['Content-Length'] = _body.byteLength || _body.length; } + if (opts.auth) { + // if opts.uri specifies auth it will be parsed by url.parse and passed directly to the http module + if ('string' !== typeof opts.auth) { + opts.auth = (opts.auth.user||opts.auth.username||'') + ':' + (opts.auth.pass||opts.auth.password||''); + } + if ('string' === typeof opts.auth) { + finalOpts.auth = opts.auth; + } + if (false === opts.sendImmediately) { + console.warn("[Warn] setting `sendImmediately: false` is not yet supported. Please open an issue if this is an important feature that you need."); + } + if (opts.bearer) { + // having a shortcut for base64 encoding makes sense, but this? Eh, whatevs... + finalOpts.header.Authorization = 'Bearer: ' + opts.bearer; + } + } if (opts.formData) { try { MyFormData = opts.FormData || require('form-data'); @@ -384,6 +400,7 @@ module.exports._keys = Object.keys(_defaults).concat([ , 'body' , 'json' , 'form' +, 'auth' , 'formData' , 'FormData' ]);