Diogo Cordeiro 96c4e57ac0 Add gs-wsRealtime by Chimo | пре 5 година | |
---|---|---|
.. | ||
examples | пре 5 година | |
src | пре 5 година | |
tests | пре 5 година | |
.gitignore | пре 5 година | |
.travis.yml | пре 5 година | |
CHANGELOG.md | пре 5 година | |
LICENSE | пре 5 година | |
README.md | пре 5 година | |
composer.json | пре 5 година | |
phpunit.xml.dist | пре 5 година |
Async, streaming plaintext TCP/IP and secure TLS socket server for React PHP
The socket component provides a more usable interface for a socket-layer
server based on the EventLoop
and Stream
components.
Table of Contents
Here is a server that closes the connection if you send it anything:
$loop = React\EventLoop\Factory::create();
$socket = new React\Socket\Server($loop);
$socket->on('connection', function (ConnectionInterface $conn) {
$conn->write("Hello " . $conn->getRemoteAddress() . "!\n");
$conn->write("Welcome to this amazing server!\n");
$conn->write("Here's a tip: don't say anything.\n");
$conn->on('data', function ($data) use ($conn) {
$conn->close();
});
});
$socket->listen(1337);
$loop->run();
See also the examples.
Here's a client that outputs the output of said server and then attempts to
send it a string.
For anything more complex, consider using the
SocketClient
component instead.
$loop = React\EventLoop\Factory::create();
$client = stream_socket_client('tcp://127.0.0.1:1337');
$conn = new React\Stream\Stream($client, $loop);
$conn->pipe(new React\Stream\Stream(STDOUT, $loop));
$conn->write("Hello World!\n");
$loop->run();
The ServerInterface
is responsible for providing an interface for accepting
incoming streaming connections, such as a normal TCP/IP connection.
Most higher-level components (such as a HTTP server) accept an instance implementing this interface to accept incoming streaming connections. This is usually done via dependency injection, so it's fairly simple to actually swap this implementation against any other implementation of this interface. This means that you SHOULD typehint against this interface instead of a concrete implementation of this interface.
Besides defining a few methods, this interface also implements the
EventEmitterInterface
which allows you to react to certain events.
The connection
event will be emitted whenever a new connection has been
established, i.e. a new client connects to this server socket:
$server->on('connection', function (ConnectionInterface $connection) {
echo 'new connection' . PHP_EOL;
});
See also the ConnectionInterface
for more details
about handling the incoming connection.
The error
event will be emitted whenever there's an error accepting a new
connection from a client.
$server->on('error', function (Exception $e) {
echo 'error: ' . $e->getMessage() . PHP_EOL;
});
Note that this is not a fatal error event, i.e. the server keeps listening for new connections even after this event.
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 for more details.
$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:
$socket->listen(1337, '192.168.0.1');
This method MUST NOT be called more than once on the same instance.
The getPort(): int
method can be used to
return the port this server is currently listening on.
$port = $server->getPort();
echo 'Server listening on port ' . $port . PHP_EOL;
This method MUST NOT be called before calling listen()
.
This method MUST NOT be called after calling shutdown()
.
The shutdown(): void
method can be used to
shut down this listening socket.
This will stop listening for new incoming connections on this socket.
echo 'Shutting down server socket' . PHP_EOL;
$server->shutdown();
This method MUST NOT be called before calling listen()
.
This method MUST NOT be called after calling shutdown()
.
The Server
class implements the ServerInterface
and
is responsible for accepting plaintext TCP/IP connections.
$server = new Server($loop);
$server->listen(8080);
Optionally, you can specify socket context options for the underlying stream socket resource like this:
$server = new Server($loop, array(
'backlog' => 200,
'so_reuseport' => true,
'ipv6_v6only' => true
));
$server->listen(8080, '::1');
Note that available socket context options, 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
:
$server->on('connection', function (ConnectionInterface $connection) {
echo 'Plaintext connection from ' . $connection->getRemoteAddress() . PHP_EOL;
$connection->write('hello there!' . PHP_EOL);
…
});
See also the 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
instead.
The SecureServer
class implements the ServerInterface
and is responsible for providing a secure TLS (formerly known as SSL) server.
It does so by wrapping a Server
instance which waits for plaintext
TCP/IP connections and then performs a TLS handshake for each connection.
It thus requires valid TLS context options,
which in its most basic form may look something like this if you're using a
PEM encoded certificate file:
$server = new Server($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 incoming connection initializes its TLS context. This implies that any invalid certificate file paths or contents will only cause an
error
event at a later time.
If your private key is encrypted with a passphrase, you have to specify it like this:
$server = new SecureServer($server, $loop, array(
'local_cert' => 'server.pem',
'passphrase' => 'secret'
));
Whenever a client completes the TLS handshake, it will emit a connection
event
with a connection instance implementing ConnectionInterface
:
$server->on('connection', function (ConnectionInterface $connection) {
echo 'Secure connection from' . $connection->getRemoteAddress() . PHP_EOL;
$connection->write('hello there!' . PHP_EOL);
…
});
Whenever a client fails to perform a successful TLS handshake, it will emit an
error
event and then close the underlying TCP/IP connection:
$server->on('error', function (Exception $e) {
echo 'Error' . $e->getMessage() . PHP_EOL;
});
See also the ServerInterface
for more details.
The ConnectionInterface
is used to represent any incoming connection.
An incoming connection is a duplex stream (both readable and writable) that
implements React's
DuplexStreamInterface
and contains only a single additional property, the remote address (client IP)
where this connection has been established from.
Note that this interface is only to be used to represent the server-side end of an incoming connection. It MUST NOT be used to represent an outgoing connection in a client-side context. If you want to establish an outgoing connection, use the
SocketClient
component instead.
Because the ConnectionInterface
implements the underlying
DuplexStreamInterface
you can use any of its events and methods as usual:
$connection->on('data', function ($chunk) {
echo $data;
});
$conenction->on('close', function () {
echo 'closed';
});
$connection->write($data);
$connection->end($data = null);
$connection->close();
// …
For more details, see the
DuplexStreamInterface
.
The getRemoteAddress(): ?string
method returns the remote address
(client IP) where this connection has been established from.
$ip = $connection->getRemoteAddress();
It will return the remote address as a string value.
If the remote address can not be determined or is unknown at this time (such as
after the connection has been closed), it MAY return a NULL
value instead.
The recommended way to install this library is through Composer. New to Composer?
This will install the latest supported version:
$ composer require react/socket:^0.4.6
More details about version upgrades can be found in the CHANGELOG.
To run the test suite, you first need to clone this repo and then install all dependencies through Composer. Because the test suite contains some circular dependencies, you may have to manually specify the root package version like this:
$ COMPOSER_ROOT_VERSION=`git describe --abbrev=0` composer install
To run the test suite, go to the project root and run:
$ php vendor/bin/phpunit
MIT, see LICENSE file.