• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# socks examples
2
3## Example for SOCKS 'connect' command
4
5The connect command is the most common use-case for a SOCKS proxy. This establishes a direct connection to a destination host through a proxy server. The destination host only has knowledge of the proxy server connecting to it and does not know about the origin client (you).
6
7**Origin Client (you) <-> Proxy Server <-> Destination Server**
8
9In this example, we are connecting to a web server on port 80, and sending a very basic HTTP request to receive a response. It's worth noting that there are many socks-http-agents that can be used with the node http module (and libraries such as request.js) to make this easier. This HTTP request is used as a simple example.
10
11The 'connect' command can be used via the SocksClient.createConnection() factory function as well as by creating a SocksClient instance and using event handlers.
12
13### Using createConnection with async/await
14
15Since SocksClient.createConnection returns a Promise, we can easily use async/await for flow control.
16
17```typescript
18import { SocksClient, SocksClientOptions } from 'socks';
19
20const options: SocksClientOptions = {
21  proxy: {
22    host: '104.131.124.203',
23    port: 1081,
24    type: 5
25  },
26
27  destination: {
28    host: 'ip-api.com', // host names are supported with SOCKS v4a and SOCKS v5.
29    port: 80
30  },
31
32  command: 'connect'
33};
34
35async function start() {
36  try {
37    const info = await SocksClient.createConnection(options);
38
39    console.log(info.socket);
40    // <Socket ...>  (this is a raw net.Socket that is established to the destination host through the given proxy servers)
41
42    info.socket.write('GET /json HTTP/1.1\nHost: ip-api.com\n\n');
43    info.socket.on('data', (data) => {
44      console.log(data.toString()); // ip-api.com sees that the last proxy (104.131.124.203) is connected to it and not the origin client (you).
45      /*
46        HTTP/1.1 200 OK
47        Access-Control-Allow-Origin: *
48        Content-Type: application/json; charset=utf-8
49        Date: Sun, 24 Dec 2017 03:47:51 GMT
50        Content-Length: 300
51
52        {
53          "as":"AS14061 Digital Ocean, Inc.",
54          "city":"Clifton",
55          "country":"United States",
56          "countryCode":"US",
57          "isp":"Digital Ocean",
58          "lat":40.8326,
59          "lon":-74.1307,
60          "org":"Digital Ocean",
61          "query":"104.131.124.203",
62          "region":"NJ",
63          "regionName":"New Jersey",
64          "status":"success",
65          "timezone":"America/New_York",
66          "zip":"07014"
67        }
68      */
69    });
70  } catch (err) {
71    // Handle errors
72  }
73}
74
75start();
76```
77
78### Using createConnection with Promises
79
80```typescript
81import { SocksClient, SocksClientOptions } from 'socks';
82
83const options: SocksClientOptions = {
84  proxy: {
85    ipaddress: '104.131.124.203',
86    port: 1081,
87    type: 5
88  },
89
90  destination: {
91    host: 'ip-api.com', // host names are supported with SOCKS v4a and SOCKS v5.
92    port: 80
93  },
94
95  command: 'connect'
96};
97
98SocksClient.createConnection(options)
99.then(info => {
100  console.log(info.socket);
101  // <Socket ...>  (this is a raw net.Socket that is established to the destination host through the given proxy servers)
102
103  info.socket.write('GET /json HTTP/1.1\nHost: ip-api.com\n\n');
104  info.socket.on('data', (data) => {
105    console.log(data.toString()); // ip-api.com sees that the last proxy (104.131.124.203) is connected to it and not the origin client (you).
106    /*
107      HTTP/1.1 200 OK
108      Access-Control-Allow-Origin: *
109      Content-Type: application/json; charset=utf-8
110      Date: Sun, 24 Dec 2017 03:47:51 GMT
111      Content-Length: 300
112
113      {
114        "as":"AS14061 Digital Ocean, Inc.",
115        "city":"Clifton",
116        "country":"United States",
117        "countryCode":"US",
118        "isp":"Digital Ocean",
119        "lat":40.8326,
120        "lon":-74.1307,
121        "org":"Digital Ocean",
122        "query":"104.131.124.203",
123        "region":"NJ",
124        "regionName":"New Jersey",
125        "status":"success",
126        "timezone":"America/New_York",
127        "zip":"07014"
128      }
129    */
130  });
131})
132.catch(err => {
133  // handle errors
134});
135```
136
137### Using createConnection with callbacks
138
139SocksClient.createConnection() optionally accepts a callback function as a second parameter.
140
141**Note:** If a callback function is provided, a Promise is still returned from the function, but the promise will always resolve regardless of if there was en error. (tldr: Do not mix callbacks and Promises).
142
143```typescript
144import { SocksClient, SocksClientOptions } from 'socks';
145
146const options: SocksClientOptions = {
147  proxy: {
148    ipaddress: '104.131.124.203',
149    port: 1081,
150    type: 5
151  },
152
153  destination: {
154    host: 'ip-api.com', // host names are supported with SOCKS v4a and SOCKS v5.
155    port: 80
156  },
157
158  command: 'connect'
159};
160
161SocksClient.createConnection(options, (err, info) => {
162  if (err) {
163    // handle errors
164  } else {
165    console.log(info.socket);
166    // <Socket ...>  (this is a raw net.Socket that is established to the destination host through the given proxy servers)
167
168    info.socket.write('GET /json HTTP/1.1\nHost: ip-api.com\n\n');
169    info.socket.on('data', (data) => {
170      console.log(data.toString()); // ip-api.com sees that the last proxy (104.131.124.203) is connected to it and not the origin client (you).
171      /*
172        HTTP/1.1 200 OK
173        Access-Control-Allow-Origin: *
174        Content-Type: application/json; charset=utf-8
175        Date: Sun, 24 Dec 2017 03:47:51 GMT
176        Content-Length: 300
177
178        {
179          "as":"AS14061 Digital Ocean, Inc.",
180          "city":"Clifton",
181          "country":"United States",
182          "countryCode":"US",
183          "isp":"Digital Ocean",
184          "lat":40.8326,
185          "lon":-74.1307,
186          "org":"Digital Ocean",
187          "query":"104.131.124.203",
188          "region":"NJ",
189          "regionName":"New Jersey",
190          "status":"success",
191          "timezone":"America/New_York",
192          "zip":"07014"
193        }
194      */
195    });
196  }
197})
198```
199
200### Using event handlers
201
202SocksClient also supports instance creation of a SocksClient. This allows for event based flow control.
203
204```typescript
205import { SocksClient, SocksClientOptions } from 'socks';
206
207const options: SocksClientOptions = {
208  proxy: {
209    ipaddress: '104.131.124.203',
210    port: 1081,
211    type: 5
212  },
213
214  destination: {
215    host: 'ip-api.com', // host names are supported with SOCKS v4a and SOCKS v5.
216    port: 80
217  },
218
219  command: 'connect'
220};
221
222const client = new SocksClient(options);
223
224client.on('established', (info) => {
225  console.log(info.socket);
226  // <Socket ...>  (this is a raw net.Socket that is established to the destination host through the given proxy servers)
227
228  info.socket.write('GET /json HTTP/1.1\nHost: ip-api.com\n\n');
229  info.socket.on('data', (data) => {
230    console.log(data.toString()); // ip-api.com sees that the last proxy (104.131.124.203) is connected to it and not the origin client (you).
231    /*
232      HTTP/1.1 200 OK
233      Access-Control-Allow-Origin: *
234      Content-Type: application/json; charset=utf-8
235      Date: Sun, 24 Dec 2017 03:47:51 GMT
236      Content-Length: 300
237
238      {
239        "as":"AS14061 Digital Ocean, Inc.",
240        "city":"Clifton",
241        "country":"United States",
242        "countryCode":"US",
243        "isp":"Digital Ocean",
244        "lat":40.8326,
245        "lon":-74.1307,
246        "org":"Digital Ocean",
247        "query":"104.131.124.203",
248        "region":"NJ",
249        "regionName":"New Jersey",
250        "status":"success",
251        "timezone":"America/New_York",
252        "zip":"07014"
253      }
254    */
255  });
256});
257
258// Failed to establish proxy connection to destination.
259client.on('error', () => {
260  // Handle errors
261});
262
263// Start connection
264client.connect();
265```