Replace listen() call with URIs passed to constructor

This fixes the temporal dependency design flaw for the most part,
because a Server now always represents a listening Socket (which may
possibly be in a closed state)

Author: clue

README.md

@@ -15,7 +15,6 @@ and [`Stream`](https://github.com/reactphp/stream) components.
   * [ServerInterface](#serverinterface)
     * [connection event](#connection-event)
     * [error event](#error-event)
-    * [listen()](#listen)
     * [getPort()](#getport)
     * [shutdown()](#shutdown)
   * [Server](#server)
@@ -33,7 +32,7 @@ Here is a server that closes the connection if you send it anything:
 ```php
 $loop = React\EventLoop\Factory::create();
 
-$socket = new React\Socket\Server($loop);
+$socket = new React\Socket\Server(8080, $loop);
 $socket->on('connection', function (ConnectionInterface $conn) {
     $conn->write("Hello " . $conn->getRemoteAddress() . "!\n");
     $conn->write("Welcome to this amazing server!\n");
@@ -43,7 +42,6 @@ $socket->on('connection', function (ConnectionInterface $conn) {
         $conn->close();
     });
 });
-$socket->listen(1337);
 
 $loop->run();
 ```
@@ -58,7 +56,7 @@ For anything more complex, consider using the
 ```php
 $loop = React\EventLoop\Factory::create();
 
-$client = stream_socket_client('tcp://127.0.0.1:1337');
+$client = stream_socket_client('tcp://127.0.0.1:8080');
 $conn = new React\Stream\Stream($client, $loop);
 $conn->pipe(new React\Stream\Stream(STDOUT, $loop));
 $conn->write("Hello World!\n");
@@ -112,28 +110,6 @@ $server->on('error', function (Exception $e) {
 Note that this is not a fatal error event, i.e. the server keeps listening for
 new connections even after this event.
 
-#### listen()
-
-The `listen(int $port, string $host = '127.0.0.1'): void` method can be used to
-start listening on the given address.
-
-This starts accepting new incoming connections on the given address.
-See also the [connection event](#connection-event) for more details.
-
-```php
-$server->listen(8080);
-```
-
-By default, the server will listen on the localhost address and will not be
-reachable from the outside.
-You can change the host the socket is listening on through a second parameter 
-provided to the listen method:
-
-```php
-$socket->listen(1337, '192.168.0.1');
-```
-
-This method MUST NOT be called more than once on the same instance.
 
 #### getPort()
 
@@ -145,7 +121,6 @@ $port = $server->getPort();
 echo 'Server listening on port ' . $port . PHP_EOL;
 ```
 
-This method MUST NOT be called before calling [`listen()`](#listen).
 This method MUST NOT be called after calling [`shutdown()`](#shutdown).
 
 #### shutdown()
@@ -160,14 +135,26 @@ echo 'Shutting down server socket' . PHP_EOL;
 $server->shutdown();
 ```
 
-This method MUST NOT be called before calling [`listen()`](#listen).
-This method MUST NOT be called after calling [`shutdown()`](#shutdown).
+This method MUST NOT be called more than once on the same instance.
 
 ### Server
 
 The `Server` class implements the [`ServerInterface`](#serverinterface) and
 is responsible for accepting plaintext TCP/IP connections.
 
+```php
+$server = new Server(8080, $loop);
+```
+
+By default, the server will listen on the localhost address and will not be
+reachable from the outside.
+You can change the host the socket is listening on through a first parameter 
+provided to the constructor:
+
+```php
+$server = new Server('192.168.0.1:8080', $loop);
+```
+
 Whenever a client connects, it will emit a `connection` event with a connection
 instance implementing [`ConnectionInterface`](#connectioninterface):
 
@@ -198,13 +185,10 @@ which in its most basic form may look something like this if you're using a
 PEM encoded certificate file:
 
 ```php
-$server = new Server($loop);
-
+$server = new Server(8000, $loop);
 $server = new SecureServer($server, $loop, array(
     'local_cert' => 'server.pem'
 ));
-
-$server->listen(8000);
 ```
 
 > Note that the certificate file will not be loaded on instantiation but when an
@@ -216,6 +200,7 @@ If your private key is encrypted with a passphrase, you have to specify it
 like this:
 
 ```php
+$server = new Server(8000, $loop);
 $server = new SecureServer($server, $loop, array(
     'local_cert' => 'server.pem',
     'passphrase' => 'secret'

examples/01-echo.php

@@ -20,7 +20,7 @@
 
 $loop = Factory::create();
 
-$server = new Server($loop);
+$server = new Server(isset($argv[1]) ? $argv[1] : 0, $loop);
 
 // secure TLS mode if certificate is given as second parameter
 if (isset($argv[2])) {
@@ -29,8 +29,6 @@
     ));
 }
 
-$server->listen(isset($argv[1]) ? $argv[1] : 0);
-
 $server->on('connection', function (ConnectionInterface $conn) use ($loop) {
     echo '[connected]' . PHP_EOL;
     $conn->pipe($conn);

examples/02-chat-server.php

@@ -20,7 +20,7 @@
 
 $loop = Factory::create();
 
-$server = new Server($loop);
+$server = new Server(isset($argv[1]) ? $argv[1] : 0, $loop);
 
 // secure TLS mode if certificate is given as second parameter
 if (isset($argv[2])) {
@@ -29,8 +29,6 @@
     ));
 }
 
-$server->listen(isset($argv[1]) ? $argv[1] : 0, '0.0.0.0');
-
 $clients = array();
 
 $server->on('connection', function (ConnectionInterface $client) use (&$clients) {

examples/03-benchmark.php

@@ -25,7 +25,7 @@
 
 $loop = Factory::create();
 
-$server = new Server($loop);
+$server = new Server(isset($argv[1]) ? $argv[1] : 0, $loop);
 
 // secure TLS mode if certificate is given as second parameter
 if (isset($argv[2])) {
@@ -34,8 +34,6 @@
     ));
 }
 
-$server->listen(isset($argv[1]) ? $argv[1] : 0);
-
 $server->on('connection', function (ConnectionInterface $conn) use ($loop) {
     echo '[connected]' . PHP_EOL;
 

src/SecureServer.php

@@ -39,8 +39,6 @@
 class SecureServer extends EventEmitter implements ServerInterface
 {
     private $tcp;
-    private $context;
-    private $loop;
     private $encryption;
 
     public function __construct(Server $tcp, LoopInterface $loop, array $context)
@@ -50,9 +48,11 @@ public function __construct(Server $tcp, LoopInterface $loop, array $context)
             'passphrase' => ''
         );
 
+        foreach ($context as $name => $value) {
+            stream_context_set_option($tcp->master, 'ssl', $name, $value);
+        }
+
         $this->tcp = $tcp;
-        $this->context = $context;
-        $this->loop = $loop;
         $this->encryption = new StreamEncryption($loop);
 
         $that = $this;
@@ -64,15 +64,6 @@ public function __construct(Server $tcp, LoopInterface $loop, array $context)
         });
     }
 
-    public function listen($port, $host = '127.0.0.1')
-    {
-        $this->tcp->listen($port, $host);
-
-        foreach ($this->context as $name => $value) {
-            stream_context_set_option($this->tcp->master, 'ssl', $name, $value);
-        }
-    }
-
     public function getPort()
     {
         return $this->tcp->getPort();

src/Server.php

@@ -4,11 +4,16 @@
 
 use Evenement\EventEmitter;
 use React\EventLoop\LoopInterface;
+use InvalidArgumentException;
 
 /**
  * The `Server` class implements the `ServerInterface` and
  * is responsible for accepting plaintext TCP/IP connections.
  *
+ * ```php
+ * $server = new Server(8080, $loop);
+ * ```
+ *
  * Whenever a client connects, it will emit a `connection` event with a connection
  * instance implementing `ConnectionInterface`:
  *
@@ -34,27 +39,69 @@ class Server extends EventEmitter implements ServerInterface
     public $master;
     private $loop;
 
-    public function __construct(LoopInterface $loop)
+    /**
+     * Creates a plaintext TCP/IP socket server and starts listening on the given address
+     *
+     * This starts accepting new incoming connections on the given address.
+     * See also the `connection event` documented in the `ServerInterface`
+     * for more details.
+     *
+     * ```php
+     * $server = new Server(8080, $loop);
+     * ```
+     *
+     * By default, the server will listen on the localhost address and will not be
+     * reachable from the outside.
+     * You can change the host the socket is listening on through the first parameter
+     * provided to the constructor.
+     *
+     * ```php
+     * $server = new Server('192.168.0.1:8080', $loop);
+     * ```
+     *
+     * @param string        $uri
+     * @param LoopInterface $loop
+     * @throws InvalidArgumentException if the listening address is invalid
+     * @throws ConnectionException if listening on this address fails (already in use etc.)
+     */
+    public function __construct($uri, LoopInterface $loop)
     {
         $this->loop = $loop;
-    }
 
-    public function listen($port, $host = '127.0.0.1')
-    {
-        if (strpos($host, ':') !== false) {
-            // enclose IPv6 addresses in square brackets before appending port
-            $host = '[' . $host . ']';
+        // a single port has been given => assume localhost
+        if ((string)(int)$uri === (string)$uri) {
+            $uri = '127.0.0.1:' . $uri;
+        }
+
+        // assume default scheme if none has been given
+        if (strpos($uri, '://') === false) {
+            $uri = 'tcp://' . $uri;
+        }
+
+        // parse_url() does not accept null ports (random port assignment) => manually remove
+        if (substr($uri, -2) === ':0') {
+            $parts = parse_url(substr($uri, 0, -2));
+            if ($parts) {
+                $parts['port'] = 0;
+            }
+        } else {
+            $parts = parse_url($uri);
+        }
+
+        // ensure URI contains TCP scheme, host and port
+        if (!$parts || !isset($parts['scheme'], $parts['host'], $parts['port']) || $parts['scheme'] !== 'tcp') {
+            throw new InvalidArgumentException('Invalid URI "' . $uri . '" given');
         }
 
         $this->master = @stream_socket_server(
-            "tcp://$host:$port",
+            $uri,
             $errno,
             $errstr,
             STREAM_SERVER_BIND | STREAM_SERVER_LISTEN,
             stream_context_create()
         );
         if (false === $this->master) {
-            $message = "Could not bind to tcp://$host:$port: $errstr";
+            $message = "Could not bind to $uri: $errstr";
             throw new ConnectionException($message, $errno);
         }
         stream_set_blocking($this->master, 0);

src/ServerInterface.php

@@ -48,30 +48,9 @@
  */
 interface ServerInterface extends EventEmitterInterface
 {
-    /**
-     * Starts listening on the given address
-     *
-     * This starts accepting new incoming connections on the given address.
-     * See also the `connection event` above for more details.
-     *
-     * By default, the server will listen on the localhost address and will not be
-     * reachable from the outside.
-     * You can change the host the socket is listening on through a second parameter
-     * provided to the listen method.
-     *
-     * This method MUST NOT be called more than once on the same instance.
-     *
-     * @param int    $port port to listen on
-     * @param string $host optional host to listen on, defaults to localhost IP
-     * @return void
-     * @throws Exception if listening on this address fails (invalid or already in use etc.)
-     */
-    public function listen($port, $host = '127.0.0.1');
-
     /**
      * Returns the port this server is currently listening on
      *
-     * This method MUST NOT be called before calling listen().
      * This method MUST NOT be called after calling shutdown().
      *
      * @return int the port number
@@ -83,8 +62,7 @@ public function getPort();
      *
      * This will stop listening for new incoming connections on this socket.
      *
-     * This method MUST NOT be called before calling listen().
-     * This method MUST NOT be called after calling shutdown().
+     * This method MUST NOT be called more than once on the same instance.
      *
      * @return void
      */

tests/ConnectionTest.php

@@ -14,8 +14,7 @@ class ConnectionTest extends TestCase
     public function testGetRemoteAddress()
     {
         $loop   = new StreamSelectLoop();
-        $server = new Server($loop);
-        $server->listen(0);
+        $server = new Server(0, $loop);
 
         $class  = new \ReflectionClass('React\\Socket\\Server');
         $master = $class->getProperty('master');