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