chore(network,tcp,udp): implement socket server, and socket

docs/component/network.md

@@ -12,8 +12,10 @@
 
 #### `Interfaces`
 
-- [ServerInterface](./../../src/Psl/Network/ServerInterface.php#L10)
+- [ServerInterface](./../../src/Psl/Network/ServerInterface.php#L12)
 - [SocketInterface](./../../src/Psl/Network/SocketInterface.php#L15)
+- [StreamServerInterface](./../../src/Psl/Network/StreamServerInterface.php#L14)
+- [StreamSocketInterface](./../../src/Psl/Network/StreamSocketInterface.php#L17)
 
 #### `Classes`
 

docs/component/tcp.md

@@ -14,10 +14,6 @@
 
 - [connect](./../../src/Psl/TCP/connect.php#L18)
 
-#### `Interfaces`
-
-- [SocketInterface](./../../src/Psl/TCP/SocketInterface.php#L9)
-
 #### `Classes`
 
 - [ConnectOptions](./../../src/Psl/TCP/ConnectOptions.php#L7)

docs/component/unix.md

@@ -14,10 +14,6 @@
 
 - [connect](./../../src/Psl/Unix/connect.php#L17)
 
-#### `Interfaces`
-
-- [SocketInterface](./../../src/Psl/Unix/SocketInterface.php#L9)
-
 #### `Classes`
 
 - [Server](./../../src/Psl/Unix/Server.php#L16)

examples/tcp/basic-http-server.php

@@ -17,7 +17,7 @@
 
     IO\write_error_line('Server is listening on http://localhost:3030');
 
-    $watcher = Async\Scheduler::onSignal(SIGINT, $server->stopListening(...));
+    $watcher = Async\Scheduler::onSignal(SIGINT, $server->close(...));
     Async\Scheduler::unreference($watcher);
 
     try {

examples/tcp/concurrent.php

@@ -33,7 +33,7 @@
 
             IO\write_error_line('< connection closed.');
 
-            $server->stopListening();
+            $server->close();
 
             IO\write_error_line('< server stopped.');
         },

examples/unix/concurrent.php

@@ -43,7 +43,7 @@
 
             IO\write_error_line('< connection closed.');
 
-            $server->stopListening();
+            $server->close();
 
             IO\write_error_line("< server stopped\n");
         },

src/Psl/Internal/Loader.php

@@ -537,9 +537,9 @@ final class Loader
         'Psl\File\ReadWriteHandleInterface',
         'Psl\Network\Exception\ExceptionInterface',
         'Psl\Network\SocketInterface',
+        'Psl\Network\StreamSocketInterface',
         'Psl\Network\ServerInterface',
-        'Psl\TCP\SocketInterface',
-        'Psl\Unix\SocketInterface',
+        'Psl\Network\StreamServerInterface',
         'Psl\Channel\SenderInterface',
         'Psl\Channel\ReceiverInterface',
         'Psl\Channel\Exception\ExceptionInterface',
@@ -669,12 +669,11 @@ final class Loader
         'Psl\Network\Exception\InvalidArgumentException',
         'Psl\Network\Address',
         'Psl\Network\SocketOptions',
+        'Psl\Network\Internal\Socket',
         'Psl\TCP\ConnectOptions',
         'Psl\TCP\ServerOptions',
         'Psl\TCP\Server',
-        'Psl\TCP\Internal\Socket',
         'Psl\Unix\Server',
-        'Psl\Unix\Internal\Socket',
         'Psl\Channel\Internal\ChannelState',
         'Psl\Channel\Internal\Sender',
         'Psl\Channel\Internal\Receiver',

src/Psl/TCP/Internal/Socket.php → src/Psl/Network/Internal/Socket.php

@@ -2,14 +2,13 @@
 
 declare(strict_types=1);
 
-namespace Psl\TCP\Internal;
+namespace Psl\Network\Internal;
 
 use Psl\IO;
 use Psl\IO\Exception;
 use Psl\IO\Internal;
 use Psl\Network;
 use Psl\Network\Address;
-use Psl\TCP;
 
 use function is_resource;
 
@@ -18,7 +17,7 @@
  *
  * @codeCoverageIgnore
  */
-final class Socket implements IO\Stream\CloseReadWriteHandleInterface, TCP\SocketInterface
+final class Socket implements Network\StreamSocketInterface
 {
     use IO\WriteHandleConvenienceMethodsTrait;
     use IO\ReadHandleConvenienceMethodsTrait;

src/Psl/Network/ServerInterface.php

@@ -4,10 +4,12 @@
 
 namespace Psl\Network;
 
+use Psl\IO;
+
 /**
  * Generic interface for a class able to accept socket connections.
  */
-interface ServerInterface
+interface ServerInterface extends IO\CloseHandleInterface
 {
     /**
      * Retrieve the next pending connection.
@@ -30,5 +32,5 @@ public function getLocalAddress(): Address;
     /**
      * Stop listening; open connection are not closed.
      */
-    public function stopListening(): void;
+    public function close(): void;
 }

src/Psl/Network/StreamServerInterface.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Network;
+
+use Psl\IO;
+
+/**
+ * Generic interface for a class able to accept socket connections.
+ *
+ * Unlike {@see ServerInterface}, {@see StreamServerInterface} provides access to the underlying server stream.
+ */
+interface StreamServerInterface extends IO\Stream\CloseHandleInterface, ServerInterface
+{
+    /**
+     * {@inheritDoc}
+     */
+    public function nextConnection(): StreamSocketInterface;
+}

src/Psl/Network/StreamSocketInterface.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Network;
+
+use Psl\IO;
+
+/**
+ * A handle representing a connection between processes.
+ *
+ * It is possible for both ends to be connected to the same process,
+ * and to either be local or across a network.
+ *
+ * Unlike {@see SocketInterface}, {@see StreamSocketInterface} provides access to the underlying socket stream.
+ */
+interface StreamSocketInterface extends IO\Stream\CloseReadWriteHandleInterface, SocketInterface
+{
+}

src/Psl/TCP/Server.php

@@ -14,7 +14,7 @@
 
 use const PHP_OS_FAMILY;
 
-final class Server implements Network\ServerInterface
+final class Server implements Network\StreamServerInterface
 {
     /**
      * @var resource|null $impl
@@ -97,7 +97,7 @@ public static function create(
     /**
      * {@inheritDoc}
      */
-    public function nextConnection(): SocketInterface
+    public function nextConnection(): Network\StreamSocketInterface
     {
         $this->deferred?->getAwaitable()->then(static fn() => null, static fn() => null)->await();
 
@@ -113,7 +113,7 @@ public function nextConnection(): SocketInterface
 
         try {
             /** @psalm-suppress PossiblyNullReference */
-            return new Internal\Socket($this->deferred->getAwaitable()->await());
+            return new Network\Internal\Socket($this->deferred->getAwaitable()->await());
         } finally {
             Async\Scheduler::disable($this->watcher);
             $this->deferred = null;
@@ -134,13 +134,14 @@ public function getLocalAddress(): Network\Address
 
     public function __destruct()
     {
-        $this->stopListening();
+        /** @psalm-suppress MissingThrowsDocblock */
+        $this->close();
     }
 
     /**
      * {@inheritDoc}
      */
-    public function stopListening(): void
+    public function close(): void
     {
         Async\Scheduler::cancel($this->watcher);
 
@@ -156,4 +157,12 @@ public function stopListening(): void
         $this->deferred = null;
         $deferred?->error(new Network\Exception\AlreadyStoppedException('Server socket has already been stopped.'));
     }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getStream(): mixed
+    {
+        return $this->impl;
+    }
 }

src/Psl/TCP/connect.php

@@ -20,7 +20,7 @@ function connect(
     int $port = 0,
     ?ConnectOptions $options = null,
     ?float $timeout = null,
-): SocketInterface {
+): Network\StreamSocketInterface {
     $options ??= ConnectOptions::create();
 
     $context = [
@@ -32,5 +32,5 @@ function connect(
     $socket = Network\Internal\socket_connect("tcp://{$host}:{$port}", $context, $timeout);
 
     /** @psalm-suppress MissingThrowsDocblock */
-    return new Internal\Socket($socket);
+    return new Network\Internal\Socket($socket);
 }