Skip to content

Commit a5aaa23

Browse files
TooTallNateTooTallNate
committed
README updates
1 parent d3cfb13 commit a5aaa23

12 files changed

Lines changed: 84 additions & 362 deletions

File tree

‎packages/agent-base/README.md‎

Lines changed: 29 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,20 @@ agent-base
22
==========
33
### Turn a function into an [`http.Agent`][http.Agent] instance
44

5-
This module provides an `http.Agent` generator. That is, you pass it an async
6-
callback function, and it returns a new `http.Agent` instance that will invoke the
7-
given callback function when sending outbound HTTP requests.
5+
This module is a thin wrapper around the base `http.Agent` class.
6+
7+
It provides an absract class that must define a `connect()` function,
8+
which is responsible for creating the underlying socket that the HTTP
9+
client requests will use.
10+
11+
The `connect()` function may return an arbitrary `Duplex` stream, or
12+
another `http.Agent` instance to delegate the request to, and may be
13+
asynchronous (by defining an `async` function).
14+
15+
Instances of this agent can be used with the `http` and `https`
16+
modules. To differentiate, the options parameter in the `connect()`
17+
function includes a `secureEndpoint` property, which can be checked
18+
to determine what type of socket should be returned.
819

920
#### Some subclasses:
1021

@@ -16,96 +27,41 @@ Send a pull request to list yours!
1627
* [`pac-proxy-agent`][pac-proxy-agent]: A PAC file proxy `http.Agent` implementation for HTTP and HTTPS
1728
* [`socks-proxy-agent`][socks-proxy-agent]: A SOCKS proxy `http.Agent` implementation for HTTP and HTTPS
1829

19-
20-
Installation
21-
------------
22-
23-
Install with `npm`:
24-
25-
``` bash
26-
$ npm install agent-base
27-
```
28-
29-
3030
Example
3131
-------
3232

33-
Here's a minimal example that creates a new `net.Socket` connection to the server
34-
for every HTTP request (i.e. the equivalent of `agent: false` option):
33+
Here's a minimal example that creates a new `net.Socket` or `tls.Socket`
34+
based on the `secureEndpoint` property. This agent can be used with both
35+
the `http` and `https` modules.
3536

3637
```ts
3738
import * as net from 'net';
3839
import * as tls from 'tls';
3940
import * as http from 'http';
4041
import { Agent } from 'agent-base';
4142

42-
const agent = new Agent(function (req, opts) {
43-
var socket;
44-
// `secureEndpoint` is true when using the "https" module
45-
if (opts.secureEndpoint) {
46-
socket = tls.connect(opts);
47-
} else {
48-
socket = net.connect(opts);
43+
class MyAgent extends Agent {
44+
connect(req, opts) {
45+
// `secureEndpoint` is true when using the "https" module
46+
if (opts.secureEndpoint) {
47+
return tls.connect(opts);
48+
} else {
49+
return net.connect(opts);
50+
}
4951
}
50-
return socket;
5152
});
5253

54+
// Keep alive enabled means that `connect()` will only be
55+
// invoked when a new connection needs to be created
56+
const agent = new MyAgent({ keepAlive: true });
57+
5358
// Pass the `agent` option when creating the HTTP request
5459
http.get('http://nodejs.org/api/', { agent }, (res) => {
5560
console.log('"response" event!', res.headers);
5661
res.pipe(process.stdout);
5762
});
5863
```
5964

60-
Returning a Promise or using an `async` function is also supported:
61-
62-
```ts
63-
new Agent(async (req, opts) => {
64-
await sleep(1000);
65-
// etc…
66-
});
67-
```
68-
69-
Return another `http.Agent` instance to "pass through" the responsibility
70-
for that HTTP request to that agent:
71-
72-
```ts
73-
new Agent((req, opts) => {
74-
return opts.secureEndpoint ? https.globalAgent : http.globalAgent;
75-
});
76-
```
77-
78-
79-
API
80-
---
81-
82-
## Agent(Function callback[, Object options]) → [http.Agent][]
83-
84-
Creates a base `http.Agent` that will execute the callback function `callback`
85-
for every HTTP request that it is used as the `agent` for. The callback function
86-
is responsible for creating a `stream.Duplex` instance of some kind that will be
87-
used as the underlying socket in the HTTP request.
88-
89-
The `options` object accepts the following properties:
90-
91-
* `timeout` - Number - Timeout for the `callback()` function in milliseconds. Defaults to Infinity (optional).
92-
93-
The callback function should have the following signature:
94-
95-
### callback(http.ClientRequest req, Object options, Function cb) → undefined
96-
97-
The ClientRequest `req` can be accessed to read request headers and
98-
and the path, etc. The `options` object contains the options passed
99-
to the `http.request()`/`https.request()` function call, and is formatted
100-
to be directly passed to `net.connect()`/`tls.connect()`, or however
101-
else you want a Socket to be created. Pass the created socket to
102-
the callback function `cb` once created, and the HTTP request will
103-
continue to proceed.
104-
105-
If the `https` module is used to invoke the HTTP request, then the
106-
`secureEndpoint` property on `options` _will be set to `true`_.
107-
108-
10965
License
11066
-------
11167

‎packages/data-uri-to-buffer/README.md‎

Lines changed: 1 addition & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -5,22 +5,11 @@ data-uri-to-buffer
55
This module accepts a ["data" URI][rfc] String of data, and returns a
66
node.js `Buffer` instance with the decoded data.
77

8-
9-
Installation
10-
------------
11-
12-
Install with `npm`:
13-
14-
``` bash
15-
$ npm install data-uri-to-buffer
16-
```
17-
18-
198
Example
209
-------
2110

2211
``` js
23-
import dataUriToBuffer from 'data-uri-to-buffer';
12+
import { dataUriToBuffer } from 'data-uri-to-buffer';
2413

2514
// plain-text data is supported
2615
let uri = 'data:,Hello%2C%20World!';

‎packages/data-uri-to-buffer/test/data-uri-to-buffer.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import assert from 'assert';
2-
import dataUriToBuffer from '../src';
2+
import { dataUriToBuffer } from '../src';
33

44
describe('data-uri-to-buffer', function () {
55
it('should decode bare-bones Data URIs', function () {

‎packages/degenerator/README.md‎

Lines changed: 1 addition & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -26,17 +26,6 @@ async function foo() {
2626
With the compiled output code, you can evaluate the code using the `vm` module
2727
in Node.js, or save the code to a file and require it, or whatever.
2828

29-
30-
Installation
31-
------------
32-
33-
Install with `npm`:
34-
35-
```bash
36-
$ npm install degenerator
37-
```
38-
39-
4029
Example
4130
-------
4231

@@ -62,7 +51,7 @@ instance with the `vm` module:
6251

6352
```typescript
6453
import vm from 'vm';
65-
import degenerator from 'degenerator';
54+
import { degenerator } from 'degenerator';
6655

6756
// The `get()` function is Promise-based (error handling omitted for brevity)
6857
function get(endpoint: string) {

‎packages/get-uri/README.md‎

Lines changed: 0 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -14,17 +14,6 @@ easily extensible with more:
1414
| `http` | [HTTP URIs][http] | `http://www.example.com/path/to/name`
1515
| `https` | [HTTPS URIs][https] | `https://www.example.com/path/to/name`
1616

17-
18-
Installation
19-
------------
20-
21-
Install with `npm`:
22-
23-
``` bash
24-
$ npm install get-uri
25-
```
26-
27-
2817
Example
2918
-------
3019

‎packages/http-proxy-agent/README.md‎

Lines changed: 6 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -6,46 +6,24 @@ This module provides an `http.Agent` implementation that connects to a specified
66
HTTP or HTTPS proxy server, and can be used with the built-in `http` module.
77

88
__Note:__ For HTTP proxy usage with the `https` module, check out
9-
[`node-https-proxy-agent`](https://github.com/TooTallNate/node-https-proxy-agent).
10-
11-
Installation
12-
------------
13-
14-
Install with `npm`:
15-
16-
``` bash
17-
$ npm install http-proxy-agent
18-
```
9+
[`https-proxy-agent`](../https-proxy-agent).
1910

2011

2112
Example
2213
-------
2314

24-
``` js
25-
var url = require('url');
26-
var http = require('http');
27-
var HttpProxyAgent = require('http-proxy-agent');
15+
```ts
16+
import * as http from 'http';
17+
import { HttpProxyAgent } from 'http-proxy-agent';
2818

29-
// HTTP/HTTPS proxy to connect to
30-
var proxy = process.env.http_proxy || 'http://168.63.76.32:3128';
31-
console.log('using proxy server %j', proxy);
19+
const agent = new HttpProxyAgent('http://168.63.76.32:3128');
3220

33-
// HTTP endpoint for the proxy to connect to
34-
var endpoint = process.argv[2] || 'http://nodejs.org/api/';
35-
console.log('attempting to GET %j', endpoint);
36-
var opts = url.parse(endpoint);
37-
38-
// create an instance of the `HttpProxyAgent` class with the proxy server information
39-
var agent = new HttpProxyAgent(proxy);
40-
opts.agent = agent;
41-
42-
http.get(opts, function (res) {
21+
http.get('http://nodejs.org/api/', { agent }, (res) => {
4322
console.log('"response" event!', res.headers);
4423
res.pipe(process.stdout);
4524
});
4625
```
4726

48-
4927
License
5028
-------
5129

‎packages/https-proxy-agent/README.md‎

Lines changed: 17 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -13,69 +13,31 @@ Since this agent implements the CONNECT HTTP method, it also works with other
1313
protocols that use this method when connecting over proxies (i.e. WebSockets).
1414
See the "Examples" section below for more.
1515

16-
17-
Installation
18-
------------
19-
20-
Install with `npm`:
21-
22-
``` bash
23-
$ npm install https-proxy-agent
24-
```
25-
26-
2716
Examples
2817
--------
2918

3019
#### `https` module example
3120

32-
``` js
33-
var url = require('url');
34-
var https = require('https');
35-
var HttpsProxyAgent = require('https-proxy-agent');
36-
37-
// HTTP/HTTPS proxy to connect to
38-
var proxy = process.env.http_proxy || 'http://168.63.76.32:3128';
39-
console.log('using proxy server %j', proxy);
21+
```ts
22+
import * as https from 'https';
23+
import { HttpsProxyAgent } from 'https-proxy-agent';
4024

41-
// HTTPS endpoint for the proxy to connect to
42-
var endpoint = process.argv[2] || 'https://graph.facebook.com/tootallnate';
43-
console.log('attempting to GET %j', endpoint);
44-
var options = url.parse(endpoint);
25+
const agent = new HttpsProxyAgent('http://168.63.76.32:3128');
4526

46-
// create an instance of the `HttpsProxyAgent` class with the proxy server information
47-
var agent = new HttpsProxyAgent(proxy);
48-
options.agent = agent;
49-
50-
https.get(options, function (res) {
27+
https.get('https://example.com', { agent }, (res) => {
5128
console.log('"response" event!', res.headers);
5229
res.pipe(process.stdout);
5330
});
5431
```
5532

5633
#### `ws` WebSocket connection example
5734

58-
``` js
59-
var url = require('url');
60-
var WebSocket = require('ws');
61-
var HttpsProxyAgent = require('https-proxy-agent');
62-
63-
// HTTP/HTTPS proxy to connect to
64-
var proxy = process.env.http_proxy || 'http://168.63.76.32:3128';
65-
console.log('using proxy server %j', proxy);
66-
67-
// WebSocket endpoint for the proxy to connect to
68-
var endpoint = process.argv[2] || 'ws://echo.websocket.org';
69-
var parsed = url.parse(endpoint);
70-
console.log('attempting to connect to WebSocket %j', endpoint);
35+
```ts
36+
import WebSocket from 'ws';
37+
import { HttpsProxyAgent } from 'https-proxy-agent';
7138

72-
// create an instance of the `HttpsProxyAgent` class with the proxy server information
73-
var options = url.parse(proxy);
74-
75-
var agent = new HttpsProxyAgent(options);
76-
77-
// finally, initiate the WebSocket connection
78-
var socket = new WebSocket(endpoint, { agent: agent });
39+
const agent = new HttpsProxyAgent('http://168.63.76.32:3128');
40+
const socket = new WebSocket('ws://echo.websocket.org', { agent });
7941

8042
socket.on('open', function () {
8143
console.log('"open" event!');
@@ -91,20 +53,19 @@ socket.on('message', function (data, flags) {
9153
API
9254
---
9355

94-
### new HttpsProxyAgent(Object options)
56+
### new HttpsProxyAgent(proxy: string | URL, options?: HttpsProxyAgentOptions)
9557

9658
The `HttpsProxyAgent` class implements an `http.Agent` subclass that connects
9759
to the specified "HTTP(s) proxy server" in order to proxy HTTPS and/or WebSocket
9860
requests. This is achieved by using the [HTTP `CONNECT` method][CONNECT].
9961

100-
The `options` argument may either be a string URI of the proxy server to use, or an
101-
"options" object with more specific properties:
62+
The `proxy` argument is the URL for the proxy server.
63+
64+
The `options` argument accepts the usual `http.Agent` constructor options, and
65+
some additional properties:
10266

103-
* `host` - String - Proxy host to connect to (may use `hostname` as well). Required.
104-
* `port` - Number - Proxy port to connect to. Required.
105-
* `protocol` - String - If `https:`, then use TLS to connect to the proxy.
106-
* `headers` - Object - Additional HTTP headers to be sent on the HTTP CONNECT method.
107-
* Any other options given are passed to the `net.connect()`/`tls.connect()` functions.
67+
* `headers` - Object containing additional headers to send to the proxy server
68+
in the `CONNECT` request.
10869

10970

11071
License

0 commit comments

Comments
 (0)