New Server class acts as a facade for underlying TcpServer

Author: clue

README.md

@@ -30,6 +30,7 @@ handle multiple concurrent connections without blocking.
     * [pause()](#pause)
     * [resume()](#resume)
     * [close()](#close)
+  * [Server](#server)
   * [TcpServer](#tcpserver)
   * [SecureServer](#secureserver)
   * [LimitingServer](#limitingserver)
@@ -319,6 +320,101 @@ $server->close();
 
 Calling this method more than once on the same instance is a NO-OP.
 
+### Server
+
+The `Server` class implements the [`ServerInterface`](#serverinterface) and
+is responsible for accepting plaintext TCP/IP connections.
+It acts as a facade for the underlying [`TcpServer`](#tcpserver) and follows
+its exact semantics.
+
+```php
+$server = new Server(8080, $loop);
+```
+
+As above, the `$uri` parameter can consist of only a port, in which case the
+server will default to listening on the localhost address `127.0.0.1`,
+which means it will not be reachable from outside of this system.
+
+In order to use a random port assignment, you can use the port `0`:
+
+```php
+$server = new Server(0, $loop);
+$address = $server->getAddress();
+```
+
+In order to change the host the socket is listening on, you can provide an IP
+address through the first parameter provided to the constructor, optionally
+preceded by the `tcp://` scheme:
+
+```php
+$server = new Server('192.168.0.1:8080', $loop);
+```
+
+If you want to listen on an IPv6 address, you MUST enclose the host in square
+brackets:
+
+```php
+$server = new Server('[::1]:8080', $loop);
+```
+
+If the given URI is invalid, does not contain a port, any other scheme or if it
+contains a hostname, it will throw an `InvalidArgumentException`:
+
+```php
+// throws InvalidArgumentException due to missing port
+$server = new Server('127.0.0.1', $loop);
+```
+
+If the given URI appears to be valid, but listening on it fails (such as if port
+is already in use or port below 1024 may require root access etc.), it will
+throw a `RuntimeException`:
+
+```php
+$first = new Server(8080, $loop);
+
+// throws RuntimeException because port is already in use
+$second = new Server(8080, $loop);
+```
+
+> Note that these error conditions may vary depending on your system and/or
+configuration.
+See the exception message and code for more details about the actual error
+condition.
+
+Optionally, you can specify [socket context options](http://php.net/manual/en/context.socket.php)
+for the underlying stream socket resource like this:
+
+```php
+$server = new Server('[::1]:8080', $loop, array(
+    'backlog' => 200,
+    'so_reuseport' => true,
+    'ipv6_v6only' => true
+));
+```
+
+> Note that available [socket context options](http://php.net/manual/en/context.socket.php),
+their defaults and effects of changing these may vary depending on your system
+and/or PHP version.
+Passing unknown context options has no effect.
+
+Whenever a client connects, it will emit a `connection` event with a connection
+instance implementing [`ConnectionInterface`](#connectioninterface):
+
+```php
+$server->on('connection', function (ConnectionInterface $connection) {
+    echo 'Plaintext connection from ' . $connection->getRemoteAddress() . PHP_EOL;
+    
+    $connection->write('hello there!' . PHP_EOL);
+    …
+});
+```
+
+See also the [`ServerInterface`](#serverinterface) for more details.
+
+> Note that the `Server` class is a concrete implementation for TCP/IP sockets.
+  If you want to typehint in your higher-level protocol implementation, you SHOULD
+  use the generic [`ServerInterface`](#serverinterface) instead.
+
 ### TcpServer
 
 The `TcpServer` class implements the [`ServerInterface`](#serverinterface) and
@@ -408,10 +504,6 @@ $server->on('connection', function (ConnectionInterface $connection) {
 
 See also the [`ServerInterface`](#serverinterface) for more details.
 
-Note that the `TcpServer` class is a concrete implementation for TCP/IP sockets.
-If you want to typehint in your higher-level protocol implementation, you SHOULD
-use the generic [`ServerInterface`](#serverinterface) instead.
-
 ### SecureServer
 
 The `SecureServer` class implements the [`ServerInterface`](#serverinterface)

src/Server.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace React\Socket;
+
+use Evenement\EventEmitter;
+use React\EventLoop\LoopInterface;
+
+final class Server extends EventEmitter implements ServerInterface
+{
+    private $server;
+
+    public function __construct($uri, LoopInterface $loop, array $context = array())
+    {
+        $server = new TcpServer($uri, $loop, $context);
+        $this->server = $server;
+
+        $that = $this;
+        $server->on('connection', function (ConnectionInterface $conn) use ($that) {
+            $that->emit('connection', array($conn));
+        });
+        $server->on('error', function (\Exception $error) use ($that) {
+            $that->emit('error', array($error));
+        });
+    }
+
+    public function getAddress()
+    {
+        return $this->server->getAddress();
+    }
+
+    public function pause()
+    {
+        $this->server->pause();
+    }
+
+    public function resume()
+    {
+        $this->server->resume();
+    }
+
+    public function close()
+    {
+        $this->server->close();
+    }
+}

src/TcpServer.php

@@ -28,10 +28,6 @@
  *
  * See also the `ServerInterface` for more details.
  *
- * Note that the `TcpServer` class is a concrete implementation for TCP/IP sockets.
- * If you want to typehint in your higher-level protocol implementation, you SHOULD
- * use the generic `ServerInterface` instead.
- *
  * @see ServerInterface
  * @see ConnectionInterface
  */

tests/ServerTest.php

@@ -0,0 +1,84 @@
+<?php
+
+namespace React\Tests\Socket;
+
+use React\EventLoop\Factory;
+use React\Socket\Server;
+use Clue\React\Block;
+
+class ServerTest extends TestCase
+{
+    public function testCreateServer()
+    {
+        $loop = Factory::create();
+
+        $server = new Server(0, $loop);
+    }
+
+    /**
+     * @expectedException InvalidArgumentException
+     */
+    public function testConstructorThrowsForInvalidUri()
+    {
+        $loop = $this->getMockBuilder('React\EventLoop\LoopInterface')->getMock();
+
+        $server = new Server('invalid URI', $loop);
+    }
+
+    public function testEmitsConnectionForNewConnection()
+    {
+        $loop = Factory::create();
+
+        $server = new Server(0, $loop);
+        $server->on('connection', $this->expectCallableOnce());
+
+        $client = stream_socket_client($server->getAddress());
+
+        Block\sleep(0.1, $loop);
+    }
+
+    public function testDoesNotEmitConnectionForNewConnectionToPausedServer()
+    {
+        $loop = Factory::create();
+
+        $server = new Server(0, $loop);
+        $server->pause();
+
+
+        $client = stream_socket_client($server->getAddress());
+
+        Block\sleep(0.1, $loop);
+    }
+
+    public function testDoesEmitConnectionForNewConnectionToResumedServer()
+    {
+        $loop = Factory::create();
+
+        $server = new Server(0, $loop);
+        $server->pause();
+        $server->on('connection', $this->expectCallableOnce());
+
+        $client = stream_socket_client($server->getAddress());
+
+        Block\sleep(0.1, $loop);
+
+        $server->resume();
+        Block\sleep(0.1, $loop);
+    }
+
+    public function testDoesNotAllowConnectionToClosedServer()
+    {
+        $loop = Factory::create();
+
+        $server = new Server(0, $loop);
+        $server->on('connection', $this->expectCallableNever());
+        $address = $server->getAddress();
+        $server->close();
+
+        $client = @stream_socket_client($address);
+
+        Block\sleep(0.1, $loop);
+
+        $this->assertFalse($client);
+    }
+}