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:  *     $server->on('connection', function (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:  *     $server->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 (IP and port) this server is currently listening on
 53:      *
 54:      * ```php
 55:      * $address = $server->getAddress();
 56:      * echo 'Server listening on ' . $address . PHP_EOL;
 57:      * ```
 58:      *
 59:      * It will return the full address (IP and port) or `NULL` if it is unknown
 60:      * (not applicable to this server socket or already closed).
 61:      *
 62:      * If this is a TCP/IP based server and you only want the local port, you may
 63:      * use something like this:
 64:      *
 65:      * ```php
 66:      * $address = $server->getAddress();
 67:      * $port = parse_url('tcp://' . $address, PHP_URL_PORT);
 68:      * echo 'Server listening on port ' . $port . PHP_EOL;
 69:      * ```
 70:      *
 71:      * @return ?string the full listening address (IP and port) or NULL if it is unknown (not applicable to this server socket or already closed)
 72:      */
 73:     public function getAddress();
 74: 
 75:     /**
 76:      * Pauses accepting new incoming connections.
 77:      *
 78:      * Removes the socket resource from the EventLoop and thus stop accepting
 79:      * new connections. Note that the listening socket stays active and is not
 80:      * closed.
 81:      *
 82:      * This means that new incoming connections will stay pending in the
 83:      * operating system backlog until its configurable backlog is filled.
 84:      * Once the backlog is filled, the operating system may reject further
 85:      * incoming connections until the backlog is drained again by resuming
 86:      * to accept new connections.
 87:      *
 88:      * Once the server is paused, no futher `connection` events SHOULD
 89:      * be emitted.
 90:      *
 91:      * ```php
 92:      * $server->pause();
 93:      *
 94:      * $server->on('connection', assertShouldNeverCalled());
 95:      * ```
 96:      *
 97:      * This method is advisory-only, though generally not recommended, the
 98:      * server MAY continue emitting `connection` events.
 99:      *
100:      * Unless otherwise noted, a successfully opened server SHOULD NOT start
101:      * in paused state.
102:      *
103:      * You can continue processing events by calling `resume()` again.
104:      *
105:      * Note that both methods can be called any number of times, in particular
106:      * calling `pause()` more than once SHOULD NOT have any effect.
107:      * Similarly, calling this after `close()` is a NO-OP.
108:      *
109:      * @see self::resume()
110:      * @return void
111:      */
112:     public function pause();
113: 
114:     /**
115:      * Resumes accepting new incoming connections.
116:      *
117:      * Re-attach the socket resource to the EventLoop after a previous `pause()`.
118:      *
119:      * ```php
120:      * $server->pause();
121:      *
122:      * $loop->addTimer(1.0, function () use ($server) {
123:      *     $server->resume();
124:      * });
125:      * ```
126:      *
127:      * Note that both methods can be called any number of times, in particular
128:      * calling `resume()` without a prior `pause()` SHOULD NOT have any effect.
129:      * Similarly, calling this after `close()` is a NO-OP.
130:      *
131:      * @see self::pause()
132:      * @return void
133:      */
134:     public function resume();
135: 
136:     /**
137:      * Shuts down this listening socket
138:      *
139:      * This will stop listening for new incoming connections on this socket.
140:      *
141:      * Calling this method more than once on the same instance is a NO-OP.
142:      *
143:      * @return void
144:      */
145:     public function close();
146: }
147: