1  socks-proxy-agent
  2  ================
  3  ### A SOCKS proxy `http.Agent` implementation for HTTP and HTTPS
  4  [![Build Status](https://github.com/TooTallNate/node-socks-proxy-agent/workflows/Node%20CI/badge.svg)](https://github.com/TooTallNate/node-socks-proxy-agent/actions?workflow=Node+CI)
  5  
  6  This module provides an `http.Agent` implementation that connects to a
  7  specified SOCKS proxy server, and can be used with the built-in `http`
  8  and `https` modules.
  9  
 10  It can also be used in conjunction with the `ws` module to establish a WebSocket
 11  connection over a SOCKS proxy. See the "Examples" section below.
 12  
 13  Installation
 14  ------------
 15  
 16  Install with `npm`:
 17  
 18  ``` bash
 19  $ npm install socks-proxy-agent
 20  ```
 21  
 22  
 23  Examples
 24  --------
 25  
 26  #### TypeScript example
 27  
 28  ```ts
 29  import https from 'https';
 30  import { SocksProxyAgent } from 'socks-proxy-agent';
 31  
 32  const info = {
 33  	host: 'br41.nordvpn.com',
 34  	userId: 'your-name@gmail.com',
 35  	password: 'abcdef12345124'
 36  };
 37  const agent = new SocksProxyAgent(info);
 38  
 39  https.get('https://jsonip.org', { agent }, (res) => {
 40  	console.log(res.headers);
 41  	res.pipe(process.stdout);
 42  });
 43  ```
 44  
 45  #### `http` module example
 46  
 47  ```js
 48  var url = require('url');
 49  var http = require('http');
 50  var SocksProxyAgent = require('socks-proxy-agent');
 51  
 52  // SOCKS proxy to connect to
 53  var proxy = process.env.socks_proxy || 'socks://127.0.0.1:1080';
 54  console.log('using proxy server %j', proxy);
 55  
 56  // HTTP endpoint for the proxy to connect to
 57  var endpoint = process.argv[2] || 'http://nodejs.org/api/';
 58  console.log('attempting to GET %j', endpoint);
 59  var opts = url.parse(endpoint);
 60  
 61  // create an instance of the `SocksProxyAgent` class with the proxy server information
 62  var agent = new SocksProxyAgent(proxy);
 63  opts.agent = agent;
 64  
 65  http.get(opts, function (res) {
 66  	console.log('"response" event!', res.headers);
 67  	res.pipe(process.stdout);
 68  });
 69  ```
 70  
 71  #### `https` module example
 72  
 73  ```js
 74  var url = require('url');
 75  var https = require('https');
 76  var SocksProxyAgent = require('socks-proxy-agent');
 77  
 78  // SOCKS proxy to connect to
 79  var proxy = process.env.socks_proxy || 'socks://127.0.0.1:1080';
 80  console.log('using proxy server %j', proxy);
 81  
 82  // HTTP endpoint for the proxy to connect to
 83  var endpoint = process.argv[2] || 'https://encrypted.google.com/';
 84  console.log('attempting to GET %j', endpoint);
 85  var opts = url.parse(endpoint);
 86  
 87  // create an instance of the `SocksProxyAgent` class with the proxy server information
 88  var agent = new SocksProxyAgent(proxy);
 89  opts.agent = agent;
 90  
 91  https.get(opts, function (res) {
 92  	console.log('"response" event!', res.headers);
 93  	res.pipe(process.stdout);
 94  });
 95  ```
 96  
 97  #### `ws` WebSocket connection example
 98  
 99  ``` js
100  var WebSocket = require('ws');
101  var SocksProxyAgent = require('socks-proxy-agent');
102  
103  // SOCKS proxy to connect to
104  var proxy = process.env.socks_proxy || 'socks://127.0.0.1:1080';
105  console.log('using proxy server %j', proxy);
106  
107  // WebSocket endpoint for the proxy to connect to
108  var endpoint = process.argv[2] || 'ws://echo.websocket.org';
109  console.log('attempting to connect to WebSocket %j', endpoint);
110  
111  // create an instance of the `SocksProxyAgent` class with the proxy server information
112  var agent = new SocksProxyAgent(proxy);
113  
114  // initiate the WebSocket connection
115  var socket = new WebSocket(endpoint, { agent: agent });
116  
117  socket.on('open', function () {
118  	console.log('"open" event!');
119  	socket.send('hello world');
120  });
121  
122  socket.on('message', function (data, flags) {
123  	console.log('"message" event! %j %j', data, flags);
124  	socket.close();
125  });
126  ```
127  
128  License
129  -------
130  
131  (The MIT License)
132  
133  Copyright (c) 2013 Nathan Rajlich <nathan@tootallnate.net>
134  
135  Permission is hereby granted, free of charge, to any person obtaining
136  a copy of this software and associated documentation files (the
137  'Software'), to deal in the Software without restriction, including
138  without limitation the rights to use, copy, modify, merge, publish,
139  distribute, sublicense, and/or sell copies of the Software, and to
140  permit persons to whom the Software is furnished to do so, subject to
141  the following conditions:
142  
143  The above copyright notice and this permission notice shall be
144  included in all copies or substantial portions of the Software.
145  
146  THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
147  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
148  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
149  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
150  CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
151  TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
152  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.