1agent-base 2========== 3### Turn a function into an [`http.Agent`][http.Agent] instance 4[](https://travis-ci.org/TooTallNate/node-agent-base) 5 6This module provides an `http.Agent` generator. That is, you pass it an async 7callback function, and it returns a new `http.Agent` instance that will invoke the 8given callback function when sending outbound HTTP requests. 9 10#### Some subclasses: 11 12Here's some more interesting uses of `agent-base`. 13Send a pull request to list yours! 14 15 * [`http-proxy-agent`][http-proxy-agent]: An HTTP(s) proxy `http.Agent` implementation for HTTP endpoints 16 * [`https-proxy-agent`][https-proxy-agent]: An HTTP(s) proxy `http.Agent` implementation for HTTPS endpoints 17 * [`pac-proxy-agent`][pac-proxy-agent]: A PAC file proxy `http.Agent` implementation for HTTP and HTTPS 18 * [`socks-proxy-agent`][socks-proxy-agent]: A SOCKS (v4a) proxy `http.Agent` implementation for HTTP and HTTPS 19 20 21Installation 22------------ 23 24Install with `npm`: 25 26``` bash 27$ npm install agent-base 28``` 29 30 31Example 32------- 33 34Here's a minimal example that creates a new `net.Socket` connection to the server 35for every HTTP request (i.e. the equivalent of `agent: false` option): 36 37```js 38var net = require('net'); 39var tls = require('tls'); 40var url = require('url'); 41var http = require('http'); 42var agent = require('agent-base'); 43 44var endpoint = 'http://nodejs.org/api/'; 45var parsed = url.parse(endpoint); 46 47// This is the important part! 48parsed.agent = agent(function (req, opts) { 49 var socket; 50 // `secureEndpoint` is true when using the https module 51 if (opts.secureEndpoint) { 52 socket = tls.connect(opts); 53 } else { 54 socket = net.connect(opts); 55 } 56 return socket; 57}); 58 59// Everything else works just like normal... 60http.get(parsed, function (res) { 61 console.log('"response" event!', res.headers); 62 res.pipe(process.stdout); 63}); 64``` 65 66Returning a Promise or using an `async` function is also supported: 67 68```js 69agent(async function (req, opts) { 70 await sleep(1000); 71 // etc… 72}); 73``` 74 75Return another `http.Agent` instance to "pass through" the responsibility 76for that HTTP request to that agent: 77 78```js 79agent(function (req, opts) { 80 return opts.secureEndpoint ? https.globalAgent : http.globalAgent; 81}); 82``` 83 84 85API 86--- 87 88## Agent(Function callback[, Object options]) → [http.Agent][] 89 90Creates a base `http.Agent` that will execute the callback function `callback` 91for every HTTP request that it is used as the `agent` for. The callback function 92is responsible for creating a `stream.Duplex` instance of some kind that will be 93used as the underlying socket in the HTTP request. 94 95The `options` object accepts the following properties: 96 97 * `timeout` - Number - Timeout for the `callback()` function in milliseconds. Defaults to Infinity (optional). 98 99The callback function should have the following signature: 100 101### callback(http.ClientRequest req, Object options, Function cb) → undefined 102 103The ClientRequest `req` can be accessed to read request headers and 104and the path, etc. The `options` object contains the options passed 105to the `http.request()`/`https.request()` function call, and is formatted 106to be directly passed to `net.connect()`/`tls.connect()`, or however 107else you want a Socket to be created. Pass the created socket to 108the callback function `cb` once created, and the HTTP request will 109continue to proceed. 110 111If the `https` module is used to invoke the HTTP request, then the 112`secureEndpoint` property on `options` _will be set to `true`_. 113 114 115License 116------- 117 118(The MIT License) 119 120Copyright (c) 2013 Nathan Rajlich <nathan@tootallnate.net> 121 122Permission is hereby granted, free of charge, to any person obtaining 123a copy of this software and associated documentation files (the 124'Software'), to deal in the Software without restriction, including 125without limitation the rights to use, copy, modify, merge, publish, 126distribute, sublicense, and/or sell copies of the Software, and to 127permit persons to whom the Software is furnished to do so, subject to 128the following conditions: 129 130The above copyright notice and this permission notice shall be 131included in all copies or substantial portions of the Software. 132 133THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, 134EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 135MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 136IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 137CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 138TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 139SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 140 141[http-proxy-agent]: https://github.com/TooTallNate/node-http-proxy-agent 142[https-proxy-agent]: https://github.com/TooTallNate/node-https-proxy-agent 143[pac-proxy-agent]: https://github.com/TooTallNate/node-pac-proxy-agent 144[socks-proxy-agent]: https://github.com/TooTallNate/node-socks-proxy-agent 145[http.Agent]: https://nodejs.org/api/http.html#http_class_http_agent 146
){kind=link}