| 1 |
<?php |
| 2 |
|
| 3 |
namespace React\Socket; |
| 4 |
|
| 5 |
use Evenement\EventEmitterInterface; |
| 6 |
|
| 7 |
/** |
| 8 |
* The `ServerInterface` is responsible for providing an interface for accepting |
| 9 |
* incoming streaming connections, such as a normal TCP/IP connection. |
| 10 |
* |
| 11 |
* Most higher-level components (such as a HTTP server) accept an instance |
| 12 |
* implementing this interface to accept incoming streaming connections. |
| 13 |
* This is usually done via dependency injection, so it's fairly simple to actually |
| 14 |
* swap this implementation against any other implementation of this interface. |
| 15 |
* This means that you SHOULD typehint against this interface instead of a concrete |
| 16 |
* implementation of this interface. |
| 17 |
* |
| 18 |
* Besides defining a few methods, this interface also implements the |
| 19 |
* `EventEmitterInterface` which allows you to react to certain events: |
| 20 |
* |
| 21 |
* connection event: |
| 22 |
* The `connection` event will be emitted whenever a new connection has been |
| 23 |
* established, i.e. a new client connects to this server socket: |
| 24 |
* |
| 25 |
* ```php |
| 26 |
* $socket->on('connection', function (React\Socket\ConnectionInterface $connection) { |
| 27 |
* echo 'new connection' . PHP_EOL; |
| 28 |
* }); |
| 29 |
* ``` |
| 30 |
* |
| 31 |
* See also the `ConnectionInterface` for more details about handling the |
| 32 |
* incoming connection. |
| 33 |
* |
| 34 |
* error event: |
| 35 |
* The `error` event will be emitted whenever there's an error accepting a new |
| 36 |
* connection from a client. |
| 37 |
* |
| 38 |
* ```php |
| 39 |
* $socket->on('error', function (Exception $e) { |
| 40 |
* echo 'error: ' . $e->getMessage() . PHP_EOL; |
| 41 |
* }); |
| 42 |
* ``` |
| 43 |
* |
| 44 |
* Note that this is not a fatal error event, i.e. the server keeps listening for |
| 45 |
* new connections even after this event. |
| 46 |
* |
| 47 |
* @see ConnectionInterface |
| 48 |
*/ |
| 49 |
interface ServerInterface extends EventEmitterInterface |
| 50 |
{ |
| 51 |
/** |
| 52 |
* Returns the full address (URI) this server is currently listening on |
| 53 |
* |
| 54 |
* ```php |
| 55 |
* $address = $socket->getAddress(); |
| 56 |
* echo 'Server listening on ' . $address . PHP_EOL; |
| 57 |
* ``` |
| 58 |
* |
| 59 |
* If the address can not be determined or is unknown at this time (such as |
| 60 |
* after the socket has been closed), it MAY return a `NULL` value instead. |
| 61 |
* |
| 62 |
* Otherwise, it will return the full address (URI) as a string value, such |
| 63 |
* as `tcp://127.0.0.1:8080`, `tcp://[::1]:80` or `tls://127.0.0.1:443`. |
| 64 |
* Note that individual URI components are application specific and depend |
| 65 |
* on the underlying transport protocol. |
| 66 |
* |
| 67 |
* If this is a TCP/IP based server and you only want the local port, you may |
| 68 |
* use something like this: |
| 69 |
* |
| 70 |
* ```php |
| 71 |
* $address = $socket->getAddress(); |
| 72 |
* $port = parse_url($address, PHP_URL_PORT); |
| 73 |
* echo 'Server listening on port ' . $port . PHP_EOL; |
| 74 |
* ``` |
| 75 |
* |
| 76 |
* @return ?string the full listening address (URI) or NULL if it is unknown (not applicable to this server socket or already closed) |
| 77 |
*/ |
| 78 |
public function getAddress(); |
| 79 |
|
| 80 |
/** |
| 81 |
* Pauses accepting new incoming connections. |
| 82 |
* |
| 83 |
* Removes the socket resource from the EventLoop and thus stop accepting |
| 84 |
* new connections. Note that the listening socket stays active and is not |
| 85 |
* closed. |
| 86 |
* |
| 87 |
* This means that new incoming connections will stay pending in the |
| 88 |
* operating system backlog until its configurable backlog is filled. |
| 89 |
* Once the backlog is filled, the operating system may reject further |
| 90 |
* incoming connections until the backlog is drained again by resuming |
| 91 |
* to accept new connections. |
| 92 |
* |
| 93 |
* Once the server is paused, no futher `connection` events SHOULD |
| 94 |
* be emitted. |
| 95 |
* |
| 96 |
* ```php |
| 97 |
* $socket->pause(); |
| 98 |
* |
| 99 |
* $socket->on('connection', assertShouldNeverCalled()); |
| 100 |
* ``` |
| 101 |
* |
| 102 |
* This method is advisory-only, though generally not recommended, the |
| 103 |
* server MAY continue emitting `connection` events. |
| 104 |
* |
| 105 |
* Unless otherwise noted, a successfully opened server SHOULD NOT start |
| 106 |
* in paused state. |
| 107 |
* |
| 108 |
* You can continue processing events by calling `resume()` again. |
| 109 |
* |
| 110 |
* Note that both methods can be called any number of times, in particular |
| 111 |
* calling `pause()` more than once SHOULD NOT have any effect. |
| 112 |
* Similarly, calling this after `close()` is a NO-OP. |
| 113 |
* |
| 114 |
* @see self::resume() |
| 115 |
* @return void |
| 116 |
*/ |
| 117 |
public function pause(); |
| 118 |
|
| 119 |
/** |
| 120 |
* Resumes accepting new incoming connections. |
| 121 |
* |
| 122 |
* Re-attach the socket resource to the EventLoop after a previous `pause()`. |
| 123 |
* |
| 124 |
* ```php |
| 125 |
* $socket->pause(); |
| 126 |
* |
| 127 |
* Loop::addTimer(1.0, function () use ($socket) { |
| 128 |
* $socket->resume(); |
| 129 |
* }); |
| 130 |
* ``` |
| 131 |
* |
| 132 |
* Note that both methods can be called any number of times, in particular |
| 133 |
* calling `resume()` without a prior `pause()` SHOULD NOT have any effect. |
| 134 |
* Similarly, calling this after `close()` is a NO-OP. |
| 135 |
* |
| 136 |
* @see self::pause() |
| 137 |
* @return void |
| 138 |
*/ |
| 139 |
public function resume(); |
| 140 |
|
| 141 |
/** |
| 142 |
* Shuts down this listening socket |
| 143 |
* |
| 144 |
* This will stop listening for new incoming connections on this socket. |
| 145 |
* |
| 146 |
* Calling this method more than once on the same instance is a NO-OP. |
| 147 |
* |
| 148 |
* @return void |
| 149 |
*/ |
| 150 |
public function close(); |
| 151 |
} |