Update readme

README.md

@@ -17,53 +17,91 @@ composer require amphp/websocket-client
 
 ## Requirements
 
-* PHP 8.1+
+- PHP 8.1+
 
+## Usage
 
-## Connecting
+### Connecting
 
-You can create new WebSocket connections using `Amp\Websocket\connect()`.
-It accepts a string as first argument, which must use the `ws` or `wss` (WebSocket over TLS) scheme.
-Options can be specified by passing a `WebsocketHandshake` object instead of a string as first argument, which can also be used to pass additional headers with the initial handshake.
-The second argument is an optional `Cancellation`.
+You can create new WebSocket connections using `Amp\Websocket\connect()` or calling `connect()` on an instance of `WebsocketConnector`.
+The `connect()` function accepts a string, PSR-7 `UriInterface` instance, or a `WebsocketHandshake` as first argument. URIs must use the `ws` or `wss` (WebSocket over TLS) scheme.
+
+Custom connection parameters can be specified by passing a `WebsocketHandshake` object instead of a string as first argument, which can also be used to pass additional headers with the initial handshake. The second argument is an optional `Cancellation` which may be used to cancel the connection attempt.
 
 ```php
 <?php
 
 require 'vendor/autoload.php';
 
-use Amp\Websocket\Client;
+use function Amp\Websocket\Client\connect;
 
-$connection = Client\connect('ws://localhost:1337/ws');
+// Amp\Websocket\Client\connect() uses the WebsocketConnection instance
+// defined by Amp\Websocket\Client\websocketConnector()
+$connection = connect('ws://localhost:1337/websocket');
 
-// do something
+foreach ($connection as $message) {
+    // $message is an instance of Amp\Websocket\WebsocketMessage
+}
 ```
 
-## Sending Data
+#### Custom Connection Parameters
+
+If necessary, a variety of connection parameters and behaviors may be altered by providing a customized instance of `WebsocketConnectionFactory` to the `WebsocketConnector` used to establish a WebSocket connection.
+
+```php
+use Amp\Websocket\Client\Rfc6455ConnectionFactory;
+use Amp\Websocket\Client\Rfc6455Connector;
+use Amp\Websocket\Client\WebsocketHandshake;
+use Amp\Websocket\ConstantRateLimit;
+use Amp\Websocket\Parser\Rfc6455ParserFactory;
+use Amp\Websocket\PeriodicHeartbeatQueue;
+
+$connectionFactory = new Rfc6455ConnectionFactory(
+    heartbeatQueue: new PeriodicHeartbeatQueue(
+        heartbeatPeriod: 5, // 5 seconds
+    ),
+    rateLimit: new ConstantRateLimit(
+        bytesPerSecondLimit: 2 ** 17, // 128 KiB
+        framesPerSecondLimit: 10,
+    ),
+    parserFactory: new Rfc6455ParserFactory(
+        messageSizeLimit: 2 ** 20, // 1 MiB
+    ),
+    frameSplitThreshold: 2 ** 14, // 16 KiB
+    closePeriod: 0.5, // 0.5 seconds
+);
+
+$connector = new Rfc6455Connector($connectionFactory);
+
+$handshake = new WebsocketHandshake('wss://example.com/websocket')
+$connection = $connector->connect($handshake);
+```
 
-WebSocket messages can be sent using the `sendText()` and `sendBinary()` methods.
-Text messages sent with `sendText()` must be valid UTF-8.
-Binary messages send with `sendBinary()` can be arbitrary data.
+### Sending Data
 
-Both methods return as soon as the message has been fully written to the send buffer. This doesn't mean that the message has been received by the other party or that the message even left the local system's send buffer, yet.
+WebSocket messages can be sent using the `Connection::sendText()` and `Connection::sendBinary()` methods.
+Text messages sent with `Connection::sendText()` must be valid UTF-8.
+Binary messages send with `Connection::sendBinary()` can be arbitrary data.
 
-## Receiving Data
+Both methods return as soon as the message has been fully written to the send buffer. This does not mean that the message is guaranteed to have been received by the other party.
 
-WebSocket messages can be received using the `receive()` method. `receive()` returns once the client has started to receive a message. This allows streaming WebSocket messages, which might be pretty large. In practice, most messages are rather small, and it's fine buffering them completely. `receive()` returns to a `WebsocketMessage`, which allows easy buffered and streamed consumption.
+### Receiving Data
 
-## Example
+WebSocket messages can be received using the `Connection::receive()` method. `Connection::receive()` returns a `WebsocketMessage` instance once the client has started to receive a message. This allows streaming WebSocket messages, which might be pretty large. In practice, most messages are rather small, and it's fine buffering them completely by either calling `WebsocketMessage::buffer()` or casting the object to a string. The maximum length of a message is defined by the option given to the `WebsocketParserFactory` instance provided to the `WebsocketConnectionFactory` (10 MiB by default).
 
 ```php
 use Amp\Websocket\Client\WebsocketHandshake;
+use Amp\Websocket\WebsocketCloseCode;
 use function Amp\Websocket\Client\connect;
 
-// Connects to the websocket endpoint at libwebsockets.org which sends a message every 50ms.
+// Connects to the websocket endpoint at libwebsockets.org
+// which sends a message every 50ms.
 $handshake = (new WebsocketHandshake('wss://libwebsockets.org'))
     ->withHeader('Sec-WebSocket-Protocol', 'dumb-increment-protocol');
 
 $connection = connect($handshake);
 
-while ($message = $connection->receive()) {
+foreach ($connection as $message) {
     $payload = $message->buffer();
 
     printf("Received: %s\n", $payload);