$

node_modules/socks/docs/examples/javascript/associateExample.md

@@ -0,0 +1,90 @@
+# socks examples
+
+## Example for SOCKS 'associate' command
+
+The associate command tells the SOCKS proxy server to establish a UDP relay. The server binds to a new UDP port and communicates the newly opened port back to the origin client. From here, any SOCKS UDP frame packets sent to this special UDP port on the Proxy server will be forwarded to the desired destination, and any responses will be forwarded back to the origin client (you).
+
+This can be used for things such as DNS queries, and other UDP communicates.
+
+**Connection Steps**
+
+1. Client -(associate)-> Proxy (Tells the proxy to create a UDP relay and bind on a new port)
+2. Client <-(port)- Proxy (Tells the origin client which port it opened and is accepting UDP frame packets on)
+
+At this point the proxy is accepting UDP frames on the specified port.
+
+3. Client --(udp frame) -> Proxy -> Destination (The origin client sends a UDP frame to the proxy on the UDP port, and the proxy then forwards it to the destination specified in the UDP frame.)
+4. Client <--(udp frame) <-- Proxy <-- Destination (The destination client responds to the udp packet sent in #3)
+
+## Usage
+
+The 'associate' command can only be used by creating a new SocksClient instance and listening for the 'established' event.
+
+**Note:** UDP packets relayed through the proxy servers are encompassed in a special Socks UDP frame format. SocksClient.createUDPFrame() and SocksClient.parseUDPFrame() create and parse these special UDP packets.
+
+```typescript
+const dgram = require('dgram');
+const SocksClient = require('socks').SocksClient;
+
+// Create a local UDP socket for sending/receiving packets to/from the proxy.
+const udpSocket = dgram.createSocket('udp4');
+udpSocket.bind();
+
+// Listen for incoming UDP packets from the proxy server.
+udpSocket.on('message', (message, rinfo) => {
+  console.log(SocksClient.parseUDPFrame(message));
+  /*
+  { frameNumber: 0,
+    remoteHost: { host: '8.8.8.8', port: 53 }, // The remote host that replied with a UDP packet
+    data: <Buffer 74 65 73 74 0a> // The data
+  }
+  */
+});
+
+const options = {
+  proxy: {
+    host: '104.131.124.203',
+    port: 1081,
+    type: 5
+  },
+
+  // This should be the ip and port of the expected client that will be sending UDP frames to the newly opened UDP port on the server.
+  // Most SOCKS servers accept 0.0.0.0 as a wildcard address to accept UDP frames from any source.
+  destination: {
+    host: '0.0.0.0',
+    port: 0
+  },
+
+  command: 'associate'
+};
+
+const client = new SocksClient(options);
+
+// This event is fired when the SOCKS server has started listening on a new UDP port for UDP relaying.
+client.on('established', info => {
+  console.log(info);
+  /*
+  {
+    socket: <Socket ...>,
+    remoteHost: { // This is the remote port on the SOCKS proxy server to send UDP frame packets to.
+      host: '104.131.124.203',
+      port: 58232
+    }
+  }
+  */
+
+  // Send a udp frame to 8.8.8.8 on port 53 through the proxy.
+  const packet = SocksClient.createUDPFrame({
+    remoteHost: { host: '8.8.8.8', port: 53 },
+    data: Buffer.from('hello') // A DNS lookup in the real world.
+  });
+
+  // Send packet.
+  udpSocket.send(packet, info.remoteHost.port, info.remoteHost.host);
+});
+
+// SOCKS proxy failed to bind.
+client.on('error', () => {
+  // Handle errors
+});
+```

node_modules/socks/docs/examples/javascript/bindExample.md

@@ -0,0 +1,83 @@
+# socks examples
+
+## Example for SOCKS 'bind' command
+
+The bind command tells the SOCKS proxy server to bind and listen on a new TCP port for an incoming connection. It communicates the newly opened port back to the origin client. Once a incoming connection is accepted by the SOCKS proxy server it then communicates the remote host that connected to the SOCKS proxy back through the same initial connection via the origin client.
+
+This can be used for things such as FTP clients which require incoming TCP connections, etc.
+
+**Connection Steps**
+
+1. Client -(bind)-> Proxy    (Tells the proxy to bind to a new port)
+2. Client <-(port)- Proxy    (Tells the origin client which port it opened)
+3. Client2 --> Proxy    (Other client connects to the proxy on this port)
+4. Client <--(client2's host info)  (Proxy tells the origin client who connected to it)
+5. Original connection to the proxy is now a full TCP stream between client (you) and client2.
+6. Client <--> Proxy <--> Client2
+
+
+## Usage
+
+The 'bind' command can only be used by creating a new SocksClient instance and listening for 'bound' and 'established' events.
+
+
+```typescript
+const SocksClient = require('socks').SocksClient;
+
+const options = {
+  proxy: {
+    host: '104.131.124.203',
+    port: 1081,
+    type: 5
+  },
+
+  // This should be the ip and port of the expected client that will connect to the SOCKS proxy server on the newly bound port.
+  // Most SOCKS servers accept 0.0.0.0 as a wildcard address to accept any client.
+  destination: {
+    host: '0.0.0.0',
+    port: 0
+  },
+
+  command: 'bind'
+};
+
+const client = new SocksClient(options);
+
+// This event is fired when the SOCKS server has started listening on a new port for incoming connections.
+client.on('bound', (info) => {
+  console.log(info);
+  /*
+  {
+    socket: <Socket ...>,
+    remoteHost: { // This is the remote ip and port of the SOCKS proxy that is now accepting incoming connections.
+      host: '104.131.124.203',
+      port: 49928
+    }
+  }
+  */
+});
+
+// This event is fired when the SOCKS server has accepted an incoming connection on the newly bound port.
+client.on('established', (info) => {
+  console.log(info);
+  /*
+  {
+    socket: <Socket ...>,
+    remoteHost: { // This is the remote ip and port that connected to the SOCKS proxy on the newly bound port.
+      host: '1.2.3.4',
+      port: 58232
+    }
+  }
+  */
+
+  // At this point info.socket is a regular net.Socket TCP connection between client and client2 (1.2.3.4) (the client which connected to the proxy on the newly bound port.)
+
+  console.log(info.socket);
+  // <Socket ...>  (this is a raw net.Socket that is established to the destination host through the given proxy servers)
+});
+
+// SOCKS proxy failed to bind.
+client.on('error', () => {
+  // Handle errors
+});
+```

node_modules/socks/docs/examples/javascript/connectExample.md

@@ -0,0 +1,258 @@
+# socks examples
+
+## Example for SOCKS 'connect' command
+
+The 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).
+
+**Origin Client (you) <-> Proxy Server <-> Destination Server**
+
+In 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.
+
+The 'connect' command can be used via the SocksClient.createConnection() factory function as well as by creating a SocksClient instance and using event handlers.
+
+### Using createConnection with async/await
+
+Since SocksClient.createConnection returns a Promise, we can easily use async/await for flow control.
+
+```typescript
+const SocksClient = require('socks').SocksClient;
+
+const options  = {
+  proxy: {
+    host: '104.131.124.203',
+    port: 1081,
+    type: 5
+  },
+
+  destination: {
+    host: 'ip-api.com', // host names are supported with SOCKS v4a and SOCKS v5.
+    port: 80
+  },
+
+  command: 'connect'
+};
+
+async function start() {
+  try {
+    const info = await SocksClient.createConnection(options);
+
+    console.log(info.socket);
+    // <Socket ...>  (this is a raw net.Socket that is established to the destination host through the given proxy servers)
+
+    info.socket.write('GET /json HTTP/1.1\nHost: ip-api.com\n\n');
+    info.socket.on('data', (data) => {
+      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).
+      /*
+        HTTP/1.1 200 OK
+        Access-Control-Allow-Origin: *
+        Content-Type: application/json; charset=utf-8
+        Date: Sun, 24 Dec 2017 03:47:51 GMT
+        Content-Length: 300
+
+        {
+          "as":"AS14061 Digital Ocean, Inc.",
+          "city":"Clifton",
+          "country":"United States",
+          "countryCode":"US",
+          "isp":"Digital Ocean",
+          "lat":40.8326,
+          "lon":-74.1307,
+          "org":"Digital Ocean",
+          "query":"104.131.124.203",
+          "region":"NJ",
+          "regionName":"New Jersey",
+          "status":"success",
+          "timezone":"America/New_York",
+          "zip":"07014"
+        }
+      */
+  } catch (err) {
+    // Handle errors
+  }
+}
+
+start();
+```
+
+### Using createConnection with Promises
+
+```typescript
+const SocksClient = require('socks').SocksClient;
+
+const options  = {
+  proxy: {
+    ipaddress: '104.131.124.203',
+    port: 1081,
+    type: 5
+  },
+
+  destination: {
+    host: 'ip-api.com', // host names are supported with SOCKS v4a and SOCKS v5.
+    port: 80
+  },
+
+  command: 'connect'
+};
+
+SocksClient.createConnection(options)
+.then(info => {
+  console.log(info.socket);
+  // <Socket ...>  (this is a raw net.Socket that is established to the destination host through the given proxy servers)
+
+  info.socket.write('GET /json HTTP/1.1\nHost: ip-api.com\n\n');
+  info.socket.on('data', (data) => {
+    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).
+    /*
+      HTTP/1.1 200 OK
+      Access-Control-Allow-Origin: *
+      Content-Type: application/json; charset=utf-8
+      Date: Sun, 24 Dec 2017 03:47:51 GMT
+      Content-Length: 300
+
+      {
+        "as":"AS14061 Digital Ocean, Inc.",
+        "city":"Clifton",
+        "country":"United States",
+        "countryCode":"US",
+        "isp":"Digital Ocean",
+        "lat":40.8326,
+        "lon":-74.1307,
+        "org":"Digital Ocean",
+        "query":"104.131.124.203",
+        "region":"NJ",
+        "regionName":"New Jersey",
+        "status":"success",
+        "timezone":"America/New_York",
+        "zip":"07014"
+      }
+    */
+})
+.catch(err => {
+  // handle errors
+});
+```
+
+### Using createConnection with callbacks
+
+SocksClient.createConnection() optionally accepts a callback function as a second parameter.
+
+**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).
+
+```typescript
+const SocksClient = require('socks').SocksClient;
+
+const options  = {
+  proxy: {
+    ipaddress: '104.131.124.203',
+    port: 1081,
+    type: 5
+  },
+
+  destination: {
+    host: 'ip-api.com', // host names are supported with SOCKS v4a and SOCKS v5.
+    port: 80
+  },
+
+  command: 'connect'
+};
+
+SocksClient.createConnection(options, (err, info) => {
+  if (err) {
+    // handle errors
+  } else {
+    console.log(info.socket);
+    // <Socket ...>  (this is a raw net.Socket that is established to the destination host through the given proxy servers)
+
+    info.socket.write('GET /json HTTP/1.1\nHost: ip-api.com\n\n');
+    info.socket.on('data', (data) => {
+      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).
+      /*
+        HTTP/1.1 200 OK
+        Access-Control-Allow-Origin: *
+        Content-Type: application/json; charset=utf-8
+        Date: Sun, 24 Dec 2017 03:47:51 GMT
+        Content-Length: 300
+
+        {
+          "as":"AS14061 Digital Ocean, Inc.",
+          "city":"Clifton",
+          "country":"United States",
+          "countryCode":"US",
+          "isp":"Digital Ocean",
+          "lat":40.8326,
+          "lon":-74.1307,
+          "org":"Digital Ocean",
+          "query":"104.131.124.203",
+          "region":"NJ",
+          "regionName":"New Jersey",
+          "status":"success",
+          "timezone":"America/New_York",
+          "zip":"07014"
+        }
+      */
+  }
+})
+```
+
+### Using event handlers
+
+SocksClient also supports instance creation of a SocksClient. This allows for event based flow control.
+
+```typescript
+const SocksClient = require('socks').SocksClient;
+
+const options  = {
+  proxy: {
+    ipaddress: '104.131.124.203',
+    port: 1081,
+    type: 5
+  },
+
+  destination: {
+    host: 'ip-api.com', // host names are supported with SOCKS v4a and SOCKS v5.
+    port: 80
+  },
+
+  command: 'connect'
+};
+
+const client = new SocksClient(options);
+
+client.on('established', (info) => {
+  console.log(info.socket);
+  // <Socket ...>  (this is a raw net.Socket that is established to the destination host through the given proxy servers)
+
+  info.socket.write('GET /json HTTP/1.1\nHost: ip-api.com\n\n');
+  info.socket.on('data', (data) => {
+    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).
+    /*
+      HTTP/1.1 200 OK
+      Access-Control-Allow-Origin: *
+      Content-Type: application/json; charset=utf-8
+      Date: Sun, 24 Dec 2017 03:47:51 GMT
+      Content-Length: 300
+
+      {
+        "as":"AS14061 Digital Ocean, Inc.",
+        "city":"Clifton",
+        "country":"United States",
+        "countryCode":"US",
+        "isp":"Digital Ocean",
+        "lat":40.8326,
+        "lon":-74.1307,
+        "org":"Digital Ocean",
+        "query":"104.131.124.203",
+        "region":"NJ",
+        "regionName":"New Jersey",
+        "status":"success",
+        "timezone":"America/New_York",
+        "zip":"07014"
+      }
+    */
+});
+
+// Failed to establish proxy connection to destination.
+client.on('error', () => {
+  // Handle errors
+});
+```