Merge pull request #284 from clue-labs/server-streaming

jsor · web-flow · commit 0f0d2930b016 · 2017-12-12T12:57:46.000+01:00
Documentation to recommend Server by default instead of advanced StreamingServer
diff --git a/README.md b/README.md
diff --git a/examples/01-hello-world.php b/examples/01-hello-world.php
@@ -3,13 +3,13 @@
 use Psr\Http\Message\ServerRequestInterface;
 use React\EventLoop\Factory;
 use React\Http\Response;
-use React\Http\StreamingServer;
+use React\Http\Server;
 
 require __DIR__ . '/../vendor/autoload.php';
 
 $loop = Factory::create();
 
-$server = new StreamingServer(function (ServerRequestInterface $request) {
+$server = new Server(function (ServerRequestInterface $request) {
     return new Response(
         200,
         array(
diff --git a/examples/02-count-visitors.php b/examples/02-count-visitors.php
@@ -3,17 +3,19 @@
 use Psr\Http\Message\ServerRequestInterface;
 use React\EventLoop\Factory;
 use React\Http\Response;
-use React\Http\StreamingServer;
+use React\Http\Server;
 
 require __DIR__ . '/../vendor/autoload.php';
 
 $loop = Factory::create();
 
 $counter = 0;
-$server = new StreamingServer(function (ServerRequestInterface $request) use (&$counter) {
+$server = new Server(function (ServerRequestInterface $request) use (&$counter) {
     return new Response(
         200,
-        array('Content-Type' => 'text/plain'),
+        array(
+            'Content-Type' => 'text/plain'
+        ),
         "Welcome number " . ++$counter . "!\n"
     );
 });
diff --git a/examples/03-client-ip.php b/examples/03-client-ip.php
@@ -3,18 +3,20 @@
 use Psr\Http\Message\ServerRequestInterface;
 use React\EventLoop\Factory;
 use React\Http\Response;
-use React\Http\StreamingServer;
+use React\Http\Server;
 
 require __DIR__ . '/../vendor/autoload.php';
 
 $loop = Factory::create();
 
-$server = new StreamingServer(function (ServerRequestInterface $request) {
+$server = new Server(function (ServerRequestInterface $request) {
     $body = "Your IP is: " . $request->getServerParams()['REMOTE_ADDR'];
 
     return new Response(
         200,
-        array('Content-Type' => 'text/plain'),
+        array(
+            'Content-Type' => 'text/plain'
+        ),
         $body
     );
 });
diff --git a/examples/04-query-parameter.php b/examples/04-query-parameter.php
@@ -3,13 +3,13 @@
 use Psr\Http\Message\ServerRequestInterface;
 use React\EventLoop\Factory;
 use React\Http\Response;
-use React\Http\StreamingServer;
+use React\Http\Server;
 
 require __DIR__ . '/../vendor/autoload.php';
 
 $loop = Factory::create();
 
-$server = new StreamingServer(function (ServerRequestInterface $request) {
+$server = new Server(function (ServerRequestInterface $request) {
     $queryParams = $request->getQueryParams();
 
     $body = 'The query parameter "foo" is not set. Click the following link ';
@@ -21,7 +21,9 @@
 
     return new Response(
         200,
-        array('Content-Type' => 'text/html'),
+        array(
+            'Content-Type' => 'text/html'
+        ),
         $body
     );
 });
diff --git a/examples/05-cookie-handling.php b/examples/05-cookie-handling.php
@@ -3,21 +3,23 @@
 use Psr\Http\Message\ServerRequestInterface;
 use React\EventLoop\Factory;
 use React\Http\Response;
-use React\Http\StreamingServer;
+use React\Http\Server;
 
 require __DIR__ . '/../vendor/autoload.php';
 
 $loop = Factory::create();
 
-$server = new StreamingServer(function (ServerRequestInterface $request) {
+$server = new Server(function (ServerRequestInterface $request) {
     $key = 'react\php';
 
     if (isset($request->getCookieParams()[$key])) {
         $body = "Your cookie value is: " . $request->getCookieParams()[$key];
 
         return new Response(
             200,
-            array('Content-Type' => 'text/plain'),
+            array(
+                'Content-Type' => 'text/plain'
+            ),
             $body
         );
     }
diff --git a/examples/06-sleep.php b/examples/06-sleep.php
@@ -3,19 +3,21 @@
 use Psr\Http\Message\ServerRequestInterface;
 use React\EventLoop\Factory;
 use React\Http\Response;
-use React\Http\StreamingServer;
+use React\Http\Server;
 use React\Promise\Promise;
 
 require __DIR__ . '/../vendor/autoload.php';
 
 $loop = Factory::create();
 
-$server = new StreamingServer(function (ServerRequestInterface $request) use ($loop) {
+$server = new Server(function (ServerRequestInterface $request) use ($loop) {
     return new Promise(function ($resolve, $reject) use ($request, $loop) {
         $loop->addTimer(1.5, function() use ($loop, $resolve) {
             $response = new Response(
                 200,
-                array('Content-Type' => 'text/plain'),
+                array(
+                    'Content-Type' => 'text/plain'
+                ),
                 "Hello world"
             );
             $resolve($response);
diff --git a/examples/07-error-handling.php b/examples/07-error-handling.php
@@ -3,15 +3,15 @@
 use Psr\Http\Message\ServerRequestInterface;
 use React\EventLoop\Factory;
 use React\Http\Response;
-use React\Http\StreamingServer;
+use React\Http\Server;
 use React\Promise\Promise;
 
 require __DIR__ . '/../vendor/autoload.php';
 
 $loop = Factory::create();
 
 $count = 0;
-$server = new StreamingServer(function (ServerRequestInterface $request) use (&$count) {
+$server = new Server(function (ServerRequestInterface $request) use (&$count) {
     return new Promise(function ($resolve, $reject) use (&$count) {
         $count++;
 
@@ -21,7 +21,9 @@
 
         $response = new Response(
             200,
-            array('Content-Type' => 'text/plain'),
+            array(
+                'Content-Type' => 'text/plain'
+            ),
             "Hello World!\n"
         );
 
diff --git a/examples/08-stream-response.php b/examples/08-stream-response.php
@@ -3,14 +3,16 @@
 use Psr\Http\Message\ServerRequestInterface;
 use React\EventLoop\Factory;
 use React\Http\Response;
-use React\Http\StreamingServer;
+use React\Http\Server;
 use React\Stream\ThroughStream;
 
 require __DIR__ . '/../vendor/autoload.php';
 
 $loop = Factory::create();
 
-$server = new StreamingServer($loop,function (ServerRequestInterface $request) use ($loop) {
+// Note how this example still uses `Server` instead of `StreamingServer`.
+// The `StreamingServer` is only required for streaming *incoming* requests.
+$server = new Server($loop,function (ServerRequestInterface $request) use ($loop) {
     if ($request->getMethod() !== 'GET' || $request->getUri()->getPath() !== '/') {
         return new Response(404);
     }
@@ -28,7 +30,9 @@
 
     return new Response(
         200,
-        array('Content-Type' => 'text/plain'),
+        array(
+            'Content-Type' => 'text/plain'
+        ),
         $stream
     );
 });
diff --git a/examples/09-stream-request.php b/examples/09-stream-request.php
@@ -10,6 +10,9 @@
 
 $loop = Factory::create();
 
+// Note how this example uses the advanced `StreamingServer` to allow streaming
+// the incoming HTTP request. This very simple example merely counts the size
+// of the streaming body, it does not otherwise buffer its contents in memory.
 $server = new StreamingServer(function (ServerRequestInterface $request) {
     return new Promise(function ($resolve, $reject) use ($request) {
         $contentLength = 0;
@@ -20,7 +23,9 @@
         $request->getBody()->on('end', function () use ($resolve, &$contentLength){
             $response = new Response(
                 200,
-                array('Content-Type' => 'text/plain'),
+                array(
+                    'Content-Type' => 'text/plain'
+                ),
                 "The length of the submitted request body is: " . $contentLength
             );
             $resolve($response);
@@ -30,7 +35,9 @@
         $request->getBody()->on('error', function (\Exception $exception) use ($resolve, &$contentLength) {
             $response = new Response(
                 400,
-                array('Content-Type' => 'text/plain'),
+                array(
+                    'Content-Type' => 'text/plain'
+                ),
                 "An error occured while reading at length: " . $contentLength
             );
             $resolve($response);
diff --git a/examples/11-hello-world-https.php b/examples/11-hello-world-https.php
@@ -3,16 +3,18 @@
 use Psr\Http\Message\ServerRequestInterface;
 use React\EventLoop\Factory;
 use React\Http\Response;
-use React\Http\StreamingServer;
+use React\Http\Server;
 
 require __DIR__ . '/../vendor/autoload.php';
 
 $loop = Factory::create();
 
-$server = new StreamingServer(function (ServerRequestInterface $request) {
+$server = new Server(function (ServerRequestInterface $request) {
     return new Response(
         200,
-        array('Content-Type' => 'text/plain'),
+        array(
+            'Content-Type' => 'text/plain'
+        ),
         "Hello world!\n"
     );
 });
diff --git a/examples/12-upload.php b/examples/12-upload.php
@@ -114,12 +114,15 @@
 
     return new Response(
         200,
-        array('Content-Type' => 'text/html; charset=UTF-8'),
+        array(
+            'Content-Type' => 'text/html; charset=UTF-8'
+        ),
         $html
     );
 };
 
-// buffer and parse HTTP request body before running our request handler
+// Note how this example explicitly uses the advanced `StreamingServer` to apply
+// custom request buffering limits below before running our request handler.
 $server = new StreamingServer(array(
     new LimitConcurrentRequestsMiddleware(100), // 100 concurrent buffering handlers, queue otherwise
     new RequestBodyBufferMiddleware(8 * 1024 * 1024), // 8 MiB max, ignore body otherwise
diff --git a/examples/21-http-proxy.php b/examples/21-http-proxy.php
@@ -3,18 +3,24 @@
 use Psr\Http\Message\RequestInterface;
 use React\EventLoop\Factory;
 use React\Http\Response;
-use React\Http\StreamingServer;
+use React\Http\Server;
 use RingCentral\Psr7;
 
 require __DIR__ . '/../vendor/autoload.php';
 
 $loop = Factory::create();
 
-$server = new StreamingServer(function (RequestInterface $request) {
+// Note how this example uses the `Server` instead of `StreamingServer`.
+// This means that this proxy buffers the whole request before "processing" it.
+// As such, this is store-and-forward proxy. This could also use the advanced
+// `StreamingServer` to forward the incoming request as it comes in.
+$server = new Server(function (RequestInterface $request) {
     if (strpos($request->getRequestTarget(), '://') === false) {
         return new Response(
             400,
-            array('Content-Type' => 'text/plain'),
+            array(
+                'Content-Type' => 'text/plain'
+            ),
             'This is a plain HTTP proxy'
         );
     }
@@ -32,7 +38,9 @@
     // and forward the incoming response to the original client request
     return new Response(
         200,
-        array('Content-Type' => 'text/plain'),
+        array(
+            'Content-Type' => 'text/plain'
+        ),
         Psr7\str($outgoing)
     );
 });
diff --git a/examples/22-connect-proxy.php b/examples/22-connect-proxy.php
@@ -3,7 +3,7 @@
 use Psr\Http\Message\ServerRequestInterface;
 use React\EventLoop\Factory;
 use React\Http\Response;
-use React\Http\StreamingServer;
+use React\Http\Server;
 use React\Socket\Connector;
 use React\Socket\ConnectionInterface;
 
@@ -12,11 +12,18 @@
 $loop = Factory::create();
 $connector = new Connector($loop);
 
-$server = new StreamingServer(function (ServerRequestInterface $request) use ($connector) {
+// Note how this example uses the `Server` instead of `StreamingServer`.
+// Unlike the plain HTTP proxy, the CONNECT method does not contain a body
+// and we establish an end-to-end connection over the stream object, so this
+// doesn't have to store any payload data in memory at all.
+$server = new Server(function (ServerRequestInterface $request) use ($connector) {
     if ($request->getMethod() !== 'CONNECT') {
         return new Response(
             405,
-            array('Content-Type' => 'text/plain', 'Allow' => 'CONNECT'),
+            array(
+                'Content-Type' => 'text/plain',
+                'Allow' => 'CONNECT'
+            ),
             'This is a HTTP CONNECT (secure HTTPS) proxy'
         );
     }
@@ -34,7 +41,9 @@ function (ConnectionInterface $remote) {
         function ($e) {
             return new Response(
                 502,
-                array('Content-Type' => 'text/plain'),
+                array(
+                    'Content-Type' => 'text/plain'
+                ),
                 'Unable to connect: ' . $e->getMessage()
             );
         }
diff --git a/examples/31-upgrade-echo.php b/examples/31-upgrade-echo.php
@@ -20,16 +20,25 @@
 use Psr\Http\Message\ServerRequestInterface;
 use React\EventLoop\Factory;
 use React\Http\Response;
-use React\Http\StreamingServer;
+use React\Http\Server;
 use React\Stream\ThroughStream;
 
 require __DIR__ . '/../vendor/autoload.php';
 
 $loop = Factory::create();
 
-$server = new StreamingServer(function (ServerRequestInterface $request) use ($loop) {
+// Note how this example uses the `Server` instead of `StreamingServer`.
+// The initial incoming request does not contain a body and we upgrade to a
+// stream object below.
+$server = new Server(function (ServerRequestInterface $request) use ($loop) {
     if ($request->getHeaderLine('Upgrade') !== 'echo' || $request->getProtocolVersion() === '1.0') {
-        return new Response(426, array('Upgrade' => 'echo'), '"Upgrade: echo" required');
+        return new Response(
+            426,
+            array(
+                'Upgrade' => 'echo'
+            ),
+            '"Upgrade: echo" required'
+        );
     }
 
     // simply return a duplex ThroughStream here
diff --git a/examples/32-upgrade-chat.php b/examples/32-upgrade-chat.php
diff --git a/examples/99-benchmark-download.php b/examples/99-benchmark-download.php
