SecureServer supports any underlying ServerInterface (advanced)

Author: clue

README.md

@@ -295,14 +295,19 @@ Note that the `SecureServer` class is a concrete implementation for TLS sockets.
 If you want to typehint in your higher-level protocol implementation, you SHOULD
 use the generic [`ServerInterface`](#serverinterface) instead.
 
-> Advanced usage: Internally, the `SecureServer` has to set the required
-context options on the underlying stream resources.
-It should therefor be used with an unmodified `Server` instance as first
-parameter so that it can allocate an empty context resource which this
-class uses to set required TLS context options.
-Failing to do so may result in some hard to trace race conditions,
-because all stream resources will use a single, shared default context
-resource otherwise.
+> Advanced usage: Despite allowing any `ServerInterface` as first parameter,
+you SHOULD pass an unmodified `Server` instance as first parameter, unless you
+know what you're doing.
+Internally, the `SecureServer` has to set the required TLS context options on
+the underlying stream resources.
+These resources are not exposed through any of the interfaces defined in this
+package, but only through the `React\Stream\Stream` class.
+The unmodified `Server` class is guaranteed to emit connections that implement
+the `ConnectionInterface` and also extend the `Stream` class in order to
+expose these underlying resources.
+If you use a custom `ServerInterface` and its `connection` event does not
+meet this requirement, the `SecureServer` will emit an `error` event and
+then close the underlying connection.
 
 ### ConnectionInterface
 

src/SecureServer.php

@@ -95,22 +95,27 @@ class SecureServer extends EventEmitter implements ServerInterface
      * and/or PHP version.
      * Passing unknown context options has no effect.
      *
-     * Advanced usage: Internally, the `SecureServer` has to set the required
-     * context options on the underlying stream resources.
-     * It should therefor be used with an unmodified `Server` instance as first
-     * parameter so that it can allocate an empty context resource which this
-     * class uses to set required TLS context options.
-     * Failing to do so may result in some hard to trace race conditions,
-     * because all stream resources will use a single, shared default context
-     * resource otherwise.
+     * Advanced usage: Despite allowing any `ServerInterface` as first parameter,
+     * you SHOULD pass an unmodified `Server` instance as first parameter, unless you
+     * know what you're doing.
+     * Internally, the `SecureServer` has to set the required TLS context options on
+     * the underlying stream resources.
+     * These resources are not exposed through any of the interfaces defined in this
+     * package, but only through the `React\Stream\Stream` class.
+     * The unmodified `Server` class is guaranteed to emit connections that implement
+     * the `ConnectionInterface` and also extend the `Stream` class in order to
+     * expose these underlying resources.
+     * If you use a custom `ServerInterface` and its `connection` event does not
+     * meet this requirement, the `SecureServer` will emit an `error` event and
+     * then close the underlying connection.
      *
-     * @param Server $tcp
+     * @param ServerInterface|Server $tcp
      * @param LoopInterface $loop
      * @param array $context
      * @see Server
      * @link http://php.net/manual/en/context.ssl.php for TLS context options
      */
-    public function __construct(Server $tcp, LoopInterface $loop, array $context)
+    public function __construct(ServerInterface $tcp, LoopInterface $loop, array $context)
     {
         // default to empty passphrase to surpress blocking passphrase prompt
         $context += array(

tests/SecureServerTest.php

@@ -15,7 +15,7 @@ public function setUp()
 
     public function testGetAddressWillBePassedThroughToTcpServer()
     {
-        $tcp = $this->getMockBuilder('React\Socket\Server')->disableOriginalConstructor()->getMock();
+        $tcp = $this->getMockBuilder('React\Socket\ServerInterface')->getMock();
         $tcp->expects($this->once())->method('getAddress')->willReturn('127.0.0.1:1234');
 
         $loop = $this->getMock('React\EventLoop\LoopInterface');
@@ -27,7 +27,7 @@ public function testGetAddressWillBePassedThroughToTcpServer()
 
     public function testCloseWillBePassedThroughToTcpServer()
     {
-        $tcp = $this->getMockBuilder('React\Socket\Server')->disableOriginalConstructor()->getMock();
+        $tcp = $this->getMockBuilder('React\Socket\ServerInterface')->getMock();
         $tcp->expects($this->once())->method('close');
 
         $loop = $this->getMock('React\EventLoop\LoopInterface');