.config/coc/extensions/node_modules/coc-json/node_modules/agent-base/README.md

   1 agent-base
   2 ==========
   3 ### Turn a function into an [`http.Agent`][http.Agent] instance
   4 [![Build Status](https://travis-ci.org/TooTallNate/node-agent-base.svg?branch=master)](https://travis-ci.org/TooTallNate/node-agent-base)
   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 (v4a) 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 &lt;nathan@tootallnate.net&gt;
 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