4.0.0

The 4.0.0 release fixes compression support with a couple small compatibility breaks from 3.x.

Users of 2.x should upgrade directly to 4.0.0.

Users of 3.x can upgrade directly to 4.0.0 if compression is not being used. If a custom WebsocketAcceptor was created to support compression, this custom implementation may be dropped, instead passing an instance of WebsocketCompressionContextFactory to each Websocket request handler.

Backward Compatibility Breaks

• The WebsocketCompressionContextFactory constructor parameter of Rfc6455ClientFactory has been removed and is instead a constructor parameter of the Websocket class.
• A nullable WebsocketCompressionContext parameter was added to WebsocketClientFactory::createClient().

4.0.0 Beta 1

The 4.0.0 Beta 1 release fixes compression support with a couple small compatibility breaks from 3.x.

• The WebsocketCompressionContextFactory constructor parameter of Rfc6455ClientFactory has been removed and is instead a constructor parameter of the Websocket class.
• A nullable WebsocketCompressionContext parameter was added to WebsocketClientFactory::createClient().

3.0.1

Disables support for WebSocket compression.

An unfortunate last-minute API design decision in the 3.x branch broke support for WebSocket compression. While it would be possible to fix this by introducing some new interfaces and classes and deprecating the old interfaces in the 3.x branch, we decided the more elegant solution would be to release a 4.x with a minor BC break. Further details will be provided in the 4.x releases.

This release marks the WebsocketCompressionContextFactory constructor parameter of Rfc6455ClientFactory as deprecated and unused. Passing a compression context factory will not enable compression on the server.

3.0.0

Stable release compatible with AMPHP v3 and fibers! 🎉

This release is compatible with amphp/http-server@^3 and amphp/websocket@^2.

As with other libraries compatible with AMPHP v3, most cases of parameters or returns of Promise<ResolutionType> have been replaced with ResolutionType.

Similar to v2, a Websocket is created by creating an instance of Websocket and using it as a request handler on an HTTP server. However, the constructor arguments have changed to reflect the changes below and the removal of the Options object from amphp/websocket.

A gateway object is no longer provided automatically to a client handler. A client handler may create one or more WebsocketClientGateway objects to hold a collection of clients and asynchronously broadcast messages to all (or only some) clients within a gateway.

• Renamed most classes and interfaces to add Websocket as a prefix to avoid name collisions with similarly named classes in other packages which are frequently used together. For example, ClientHandler is now WebsocketClientHandler, ClientFactory is now WebsocketClientFactory.
• The handshake accepting functionality of ClientHandler has been split into a separate interface, WebsocketAcceptor. In general, most applications will want to use AllowOriginAcceptor. For more flexibility, create your own implementation by delegating to Rfc6455Acceptor and adding your own logic in handleHandshake().
• WebsocketServerObserver has been removed. Use the onStart() and onStop() methods of HttpServer if an action is needed when starting or stopping the HTTP server.

3.0.0 Beta 2

• Updated for compatibility with amphp/socket@v2 and amphp/[email protected]
• Altered Rfc6455ClientFactory constructor to use an instance of WebsocketParserFactory, moving some configuration options to Rfc6455ParserFactory

3.0.0 Beta 1

Initial release compatible with AMPHP v3.

As with other libraries compatible with AMPHP v3, most cases of parameters or returns of Promise<ResolutionType> have been replaced with ResolutionType.

• Added Websocket as a prefix to several classes:
  • ClientFactory renamed to WebsocketClientFactory
  • ClientHandler renamed to WebsocketClientHander
  • Gateway renamed to WebsocketGateway
• Split ClientHandler into two interfaces: WebsocketClientHandler and WebsocketHandshakeHandler
  • WebsocketHandshakeHandler handles inspecting incoming requests to upgrade to a websocket connection. Two simple implementations are provided, EmptyWebsocketHandshakeHandler and OriginWebsocketHandshakeHandler which will cover the needs of many users
  • WebsocketClientHandler handles connected websocket clients. Your application logic will be invoked by an object implementing this interface
• Added Rfc6455UpgradeHandler that is used by Websocket as the default RequestHandler constructor argument handle the client handshake request. Generally there is no reason to override this behavior, but this version provides that opportunity if desired

2.0.0

Changes since RC3

• Renamed Endpoint to Gateway. An alias to Endpoint is provided for compatibility.
• Renamed WebsocketObserver to WebsocketServerObserver.

Upgrading from v1.x to v2.0

This library has been refactored to use the new amphp/websocket library containing components that can be shared between server and clients.

Websocket is now a final class that requires an instance of ClientHandler, which has two methods to handle client handshakes and the client connection.

• handleHandshake(): This method is invoked when a WebSocket connection attempt is made. The application may alter the given Response to deny the connection attempt or set application-specific headers.
• handleClient(): This method is invoked upon a successful WebSocket connection. This method should use a loop to receive messages from the WebSocket connection.

use Amp\Http\Server\Request;
use Amp\Http\Server\Response;
use Amp\Http\Status;
use Amp\Success;
use Amp\Websocket\Client;
use Amp\Websocket\Server\ClientHandler;
use Amp\Websocket\Server\Gateway;
use Amp\Websocket\Server\Websocket;

$websocket = new Websocket(new class implements ClientHandler {
    public function handleHandshake(Gateway $gateway, Request $request, Response $response): Promise
    {
        if (!\in_array($request->getHeader('origin'), ['http://localhost:1337', 'http://127.0.0.1:1337', 'http://[::1]:1337'], true)) {
            return $gateway->getErrorHandler()->handleError(Status::FORBIDDEN, 'Origin forbidden', $request);
        }

        return new Success($response);
    }

    public function handleClient(Gateway $gateway, Client $client, Request $request, Response $response): Promise
    {
        return Amp\call(function () use ($gateway, $client) {
            while ($message = yield $client->receive()) {
                \assert($message instanceof Message);
                $gateway->broadcast(\sprintf('%d: %s', $client->getId(), yield $message->buffer()));
            }
        });
    }
});

WebSocket clients are now represented by a Client object. This object contains several methods for getting information about the client and for sending messages to a single client.

Servers can send to multiple clients using Gateway::broadcast() and Gateway::multicast() (plus binary versions, Gateway::broadcastBinary() and Gateway::multicastBinary()). A Gateway instance is provided to ClientHandler::handleHandshake() and ClientHandler::handleClient().

2.0.0 RC3

• Split ClientHandler into two interfaces, adding WebsocketObserver for the onStart() and onStop() methods.
• Added Websocket::attach(WebsocketObserver $observer) method for attaching additional observers. Note that the ClientHandler given to the Websocket constructor is automatically attached, attach() does not need to be called separately.
• Added Endpoint interface. ClientHandler::handleHandshake() and ClientHandler::handleClient() is now given an instance of Endpoint as the first argument. This object is used to broadcast, retrieve connected clients, etc.

2.0.0 RC2

Added ClientHandler interface. Websocket is now a final class, instead accepting an instance of ClientHandler when constructed. ClientHandler uses the methods handleHandshake() and handleClient() to handle client connection requests and client connections.

When the HTTP server is started, ClientHandler::onStart() is invoked for each Websocket endpoint where the instance of ClientHandler was used, providing the instance of Websocket as a parameter. When the server is stopped, ClientHandler::onStop() is invoked in the same way.

2.0.0 RC1

This library has been refactored to use the new amphp/websocket library containing components that can be shared between server and clients.

Note: This is a pre-release, there might be breaking changes in the final stable version.

Websocket now contains only two abstract methods that must be implemented:

• onHandshake(): This method acts as before, being invoked when a WebSocket connection attempt is made. The application may alter the given Response to deny the connection attempt or set application-specific headers.
• onConnect(): This method is invoked upon a successful WebSocket connection. This method should use a loop to receive messages from the WebSocket connection.

protected function onConnect(Client $client, Request $request, Response $response): Promise
{
    return Amp\call(function () use ($client) {
        while ($message = yield $client->receive()) {
            $payload = yield $message->buffer();
            yield $client->send('Message of length ' . \strlen($payload) . 'received');
        }
    });
}

WebSocket clients are now represented by a Client object. This object contains several methods for getting information about the client and for sending messages to a single client.