From f26e005fc856b582986f9caea164a2e21a2c6699 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Christian=20L=C3=BCck?= <christian@lueck.tv>
Date: Sat, 17 Nov 2018 17:15:37 +0100
Subject: [PATCH] Improve documentation for examples and link to other projects

---
 README.md                                             |  4 ++--
 examples/01-http.php                                  |  8 ++++++++
 examples/02-https.php                                 |  8 ++++++++
 examples/03-proxy-chaining.php                        |  8 ++++++++
 examples/04-local-dns.php                             |  8 ++++++++
 examples/11-server.php                                |  5 +++++
 examples/12-server-with-password.php                  | 11 +++++++++++
 examples/13-server-blacklist.php                      |  8 +++++++-
 examples/21-server-proxy-chaining.php                 |  7 ++++++-
 .../22-server-proxy-chaining-from-random-pool.php     |  7 ++++++-
 examples/31-server-secure.php                         |  5 +++++
 examples/32-http-secure.php                           |  8 ++++++++
 12 files changed, 82 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 5d3331c..df02ca0 100644
--- a/README.md
+++ b/README.md
@@ -237,8 +237,8 @@ HTTP operates on a higher layer than this low-level SOCKS implementation.
 If you want to issue HTTP requests, you can add a dependency for
 [clue/reactphp-buzz](https://github.com/clue/reactphp-buzz).
 It can interact with this library by issuing all
-[http requests through a SOCKS server](https://github.com/clue/reactphp-buzz#socks-proxy).
-This works for both plain HTTP and SSL encrypted HTTPS requests.
+[HTTP requests through a SOCKS proxy server](https://github.com/clue/reactphp-buzz#socks-proxy).
+This works for both plain HTTP and TLS-encrypted HTTPS requests.
 
 #### Protocol version
 
diff --git a/examples/01-http.php b/examples/01-http.php
index 584b6c4..37a88a3 100644
--- a/examples/01-http.php
+++ b/examples/01-http.php
@@ -1,5 +1,13 @@
 <?php
 
+// A simple example which requests http://www.google.com/ through a SOCKS proxy.
+// The proxy can be given as first argument and defaults to localhost:1080 otherwise.
+//
+// Not already running a SOCKS proxy server? See also example #11 or try this: `ssh -D 1080 localhost`
+//
+// For illustration purposes only. If you want to send HTTP requests in a real
+// world project, take a look at https://github.com/clue/reactphp-buzz#socks-proxy
+
 use Clue\React\Socks\Client;
 use React\Socket\Connector;
 use React\Socket\ConnectionInterface;
diff --git a/examples/02-https.php b/examples/02-https.php
index f763fc2..5af865d 100644
--- a/examples/02-https.php
+++ b/examples/02-https.php
@@ -1,5 +1,13 @@
 <?php
 
+// A simple example which requests https://www.google.com/ through a SOCKS proxy.
+// The proxy can be given as first argument and defaults to localhost:1080 otherwise.
+//
+// Not already running a SOCKS proxy server? See also example #11 or try this: `ssh -D 1080 localhost`
+//
+// For illustration purposes only. If you want to send HTTP requests in a real
+// world project, take a look at https://github.com/clue/reactphp-buzz#socks-proxy
+
 use Clue\React\Socks\Client;
 use React\Socket\Connector;
 use React\Socket\ConnectionInterface;
diff --git a/examples/03-proxy-chaining.php b/examples/03-proxy-chaining.php
index 5278d2c..ece6de8 100644
--- a/examples/03-proxy-chaining.php
+++ b/examples/03-proxy-chaining.php
@@ -1,5 +1,13 @@
 <?php
 
+// A more advanced example which requests http://www.google.com/ through a chain of SOCKS proxy servers.
+// The proxy servers can be given as arguments.
+//
+// Not already running a SOCKS proxy server? See also example #11 or try this: `ssh -D 1080 localhost`
+//
+// For illustration purposes only. If you want to send HTTP requests in a real
+// world project, take a look at https://github.com/clue/reactphp-buzz#socks-proxy
+
 use Clue\React\Socks\Client;
 use React\Socket\Connector;
 use React\Socket\ConnectionInterface;
diff --git a/examples/04-local-dns.php b/examples/04-local-dns.php
index 2ea39dd..f876e4e 100644
--- a/examples/04-local-dns.php
+++ b/examples/04-local-dns.php
@@ -1,5 +1,13 @@
 <?php
 
+// A simple example which requests https://www.google.com/ through a SOCKS proxy with local DNS resolution.
+// The proxy can be given as first argument and defaults to localhost:1080 otherwise.
+//
+// Not already running a SOCKS proxy server? See also example #11 or try this: `ssh -D 1080 localhost`
+//
+// For illustration purposes only. If you want to send HTTP requests in a real
+// world project, take a look at https://github.com/clue/reactphp-buzz#socks-proxy
+
 use Clue\React\Socks\Client;
 use React\Socket\Connector;
 use React\Socket\ConnectionInterface;
diff --git a/examples/11-server.php b/examples/11-server.php
index e60e202..0e8dfe3 100644
--- a/examples/11-server.php
+++ b/examples/11-server.php
@@ -1,5 +1,10 @@
 <?php
 
+// A simple example which runs a SOCKS proxy server.
+// The listen address can be given as first argument and defaults to localhost:1080 otherwise.
+//
+// See also examples #01 and #02 for the client side.
+
 use Clue\React\Socks\Server;
 use React\Socket\Server as Socket;
 
diff --git a/examples/12-server-with-password.php b/examples/12-server-with-password.php
index ca9ecc3..88117e7 100644
--- a/examples/12-server-with-password.php
+++ b/examples/12-server-with-password.php
@@ -1,5 +1,16 @@
 <?php
 
+// A simple example which runs a SOCKS proxy server with hard-coded authentication details.
+// The listen address can be given as first argument and defaults to localhost:1080 otherwise.
+//
+// See also examples #01 and #02 for the client side.
+//
+// Note that the client examples do not pass any authentication details by default
+// and as such will fail to authenticate against this example server. You can
+// explicitly pass authentication details to the client example like this:
+//
+// $ php examples/01-http.php tom:god@localhost:1080
+
 use Clue\React\Socks\Server;
 use React\Socket\Server as Socket;
 
diff --git a/examples/13-server-blacklist.php b/examples/13-server-blacklist.php
index 12b475e..3ec0221 100644
--- a/examples/13-server-blacklist.php
+++ b/examples/13-server-blacklist.php
@@ -1,6 +1,12 @@
 <?php
 
-// A SOCKS server that rejects connections to some domains (blacklist / filtering)
+// A more advanced example which runs a SOCKS proxy server that rejects connections
+// to some domains (blacklist /filtering).
+// The listen address can be given as first argument and defaults to localhost:1080 otherwise.
+//
+// See also examples #01 and #02 for the client side.
+// Client example #01 is expected to fail because port 80 is blocked in this server example.
+// Client example #02 is expected to succceed because it is not blacklisted.
 
 use React\EventLoop\Factory as LoopFactory;
 use ConnectionManager\Extra\Multiple\ConnectionManagerSelective;
diff --git a/examples/21-server-proxy-chaining.php b/examples/21-server-proxy-chaining.php
index 7be27ab..1fb757a 100644
--- a/examples/21-server-proxy-chaining.php
+++ b/examples/21-server-proxy-chaining.php
@@ -1,6 +1,11 @@
 <?php
 
-// A SOCKS server that forwards (proxy chaining) to other SOCKS servers
+// A more advanced example which runs a SOCKS proxy server that forwards to
+// other SOCKS servers (proxy chaining).
+// The listen address can be given as first argument.
+// The upstream proxy servers can be given as additional arguments.
+//
+// See also examples #01 and #02 for the client side.
 
 use Clue\React\Socks\Client;
 use Clue\React\Socks\Server;
diff --git a/examples/22-server-proxy-chaining-from-random-pool.php b/examples/22-server-proxy-chaining-from-random-pool.php
index 72016db..99b0796 100644
--- a/examples/22-server-proxy-chaining-from-random-pool.php
+++ b/examples/22-server-proxy-chaining-from-random-pool.php
@@ -1,6 +1,11 @@
 <?php
 
-// A SOCKS server that randomly forwards (proxy chaining) to a pool of SOCKS servers
+// A more advanced example which runs a SOCKS proxy server that randomly forwards
+// to a pool of SOCKS servers (random proxy chaining).
+// The listen address can be given as first argument.
+// The upstream proxy servers can be given as additional arguments.
+//
+// See also examples #01 and #02 for the client side.
 
 use React\EventLoop\Factory as LoopFactory;
 use ConnectionManager\Extra\Multiple\ConnectionManagerRandom;
diff --git a/examples/31-server-secure.php b/examples/31-server-secure.php
index 27653ff..c76adec 100644
--- a/examples/31-server-secure.php
+++ b/examples/31-server-secure.php
@@ -1,5 +1,10 @@
 <?php
 
+// A more advanced example which runs a secure SOCKS over TLS proxy server.
+// The listen address can be given as first argument and defaults to localhost:1080 otherwise.
+//
+// See also example #32 for the client side.
+
 use Clue\React\Socks\Server;
 use React\Socket\Server as Socket;
 
diff --git a/examples/32-http-secure.php b/examples/32-http-secure.php
index d304bd4..0f68054 100644
--- a/examples/32-http-secure.php
+++ b/examples/32-http-secure.php
@@ -1,5 +1,13 @@
 <?php
 
+// A more advanced example which requests http://google.com/ through a secure SOCKS over TLS proxy.
+// The proxy can be given as first argument and defaults to localhost:1080 otherwise.
+//
+// See also example #31 for the server side.
+//
+// For illustration purposes only. If you want to send HTTP requests in a real
+// world project, take a look at https://github.com/clue/reactphp-buzz#socks-proxy
+
 use Clue\React\Socks\Client;
 use React\Socket\Connector;
 use React\Socket\ConnectionInterface;