Exceptions, docu

.github/ISSUE_TEMPLATE/bug_report.md

@@ -14,7 +14,7 @@ Please provide a clear and concise description of the suspected issue.
 If possible, provide information - possibly including code snippets - on how to reproduce the issue.
 
 **Logs**
-If possible, provide logs that indicate the issue. See https://github.com/Textalk/websocket-php/blob/master/docs/Examples.md#logger on how to use a logger.
+If possible, provide logs that indicate the issue. See [logger example](../../docs/Examples.md#logger) on how to use a logger.
 
 **Versions**
 * Version of this library

docs/Changelog.md

@@ -10,6 +10,7 @@
 
  * Shared stream observer, sharable across multiple cients and servers (@sirn-se)
  * Configuration class for various settings (@sirn-se)
+ * MessageEncodingException when compression fails (@sirn-se)
  * Many class local configuration setters removed (@sirn-se)
  * Remove deprecated code (@sirn-se)
 

docs/Client.md

@@ -4,9 +4,33 @@
 
 The client can read and write on a WebSocket stream.
 
+
+## Subscribe operation
+
+If you want to subscribe to messages sent by server at any point, use the listener functions.
+
+```php
+$client = new WebSocket\Client("wss://echo.websocket.org/");
+$client
+    // Add standard middlewares
+    ->addMiddleware(new WebSocket\Middleware\CloseHandler())
+    ->addMiddleware(new WebSocket\Middleware\PingResponder())
+    // Listen to incoming Text messages
+    ->onText(function (WebSocket\Client $client, WebSocket\Connection $connection, WebSocket\Message\Message $message) {
+        // Act on incoming message
+        echo "Got message: {$message->getContent()} \n";
+        // Possibly respond to server
+        $client->text("I got your your message");
+    })
+    ->start();
+```
+Optionally, `start()` can take timeout argument as int or float.
+
+
 ## Basic operation
 
 Set up a WebSocket client for request/response strategy.
+Manually pulling messages using `receive()` method is not recommended.
 
 ```php
 $client = new WebSocket\Client("wss://echo.websocket.org/");
@@ -27,26 +51,6 @@ echo "Got message: {$message->getContent()} \n";
 $client->close();
 ```
 
-## Subscribe operation
-
-If you want to subscribe to messages sent by server at any point, use the listener functions.
-
-```php
-$client = new WebSocket\Client("wss://echo.websocket.org/");
-$client
-    // Add standard middlewares
-    ->addMiddleware(new WebSocket\Middleware\CloseHandler())
-    ->addMiddleware(new WebSocket\Middleware\PingResponder())
-    // Listen to incoming Text messages
-    ->onText(function (WebSocket\Client $client, WebSocket\Connection $connection, WebSocket\Message\Message $message) {
-        // Act on incoming message
-        echo "Got message: {$message->getContent()} \n";
-        // Possibly respond to server
-        $client->text("I got your your message");
-    })
-    ->start();
-```
-Optionally, `start()` can take timeout argument as int or float.
 
 ## Middlewares
 
@@ -137,66 +141,16 @@ $client->close(1000, "Closing now");
 
 The Client takes one argument: [URI](http://tools.ietf.org/html/rfc3986) as a class implementing [UriInterface](https://www.php-fig.org/psr/psr-7/#35-psrhttpmessageuriinterface) or as string.
 The client support `ws` (`tcp`) and `wss` (`ssl`) schemas, depending on SSL configuration.
-Other options are available runtime by calling configuration methods.
-
-### Logger
-
-Client support adding any [PSR-4 compatible](https://www.php-fig.org/psr/psr-3/) logger.
-
-```php
-$client->setLogger(Psr\Log\LoggerInterface $logger);
-```
-
-### Timeout
 
-Timeout for various operations can be specified in seconds.
-This affects how long Client will wait for connection, read and write operations, and listener scope.
-Default is `60` seconds. Minimum is `0` seconds. Accepts int or float value.
-Avoid setting very low values as it will cause a read loop to use all
-available processing power even when there's nothing to read.
+Other options are available using the Configuration class.
 
-```php
-$client->setTimeout(300); // set timeout in seconds
-$client->getTimeout(); // => current timeout in seconds
-```
-
-### Frame size
-
-Defines the maximum payload per frame size in bytes.
-Default is `4096` bytes. Minimum is `1` byte.
-Do not change unless you have a strong reason to do so.
-
-```php
-$client->setFrameSize(1024); // set maximum payload frame size in bytes
-$client->getFrameSize(); // => current maximum payload frame size in bytes
-```
-
-### Persistent connection
+- Logger
+- Context
+- Timeout
+- Frame size
+- Persistency
 
-If set to true, the underlying connection will be kept open if possible.
-This means that if Client closes and is then restarted, it may use the same connection.
-Do not change unless you have a strong reason to do so.
-
-```php
-$client->setPersistent(true);
-```
-
-### Context
-
-Client support adding [context options and parameters](https://www.php.net/manual/en/context.php)
-using the [Phrity\Net\Context](https://github.com/sirn-se/phrity-net-stream?tab=readme-ov-file#context-class) class.
-
-```php
-$context = new Phrity\Net\Context();
-$context->setOptions([
-    "ssl" => [
-        "verify_peer" => false,
-        "verify_peer_name" => false,
-    ],
-]);
-$client->setContext($context); // set context
-$client->getContext(); // => currently used Phrity\Net\Context
-```
+Read more on [Configuration](Configuration.md).
 
 ### HTTP factories
 

docs/Configuration.md

@@ -0,0 +1,217 @@
+[Documentation](Index.md) / Configuration
+
+# Websocket: Configuration
+
+The Configuration class is used to configure Client, Server and various worker classes.
+It is delegated throughout class hierarchy unless explicitly set.
+
+## Using Configuration instance
+
+When creating a Configuration, all constructor arguments are optional.
+```php
+$configuration = new WebSocket\Configuration(
+    Psr\Log\LoggerInterface $logger,
+    Phrity\Net\Context $context,
+    int|float $timeout,
+    int $frameSize,
+    bool $persistent,
+    int $maxConnections,
+);
+```
+
+Provide Configuration in constructor;
+```php
+$client = new WebSocket\Client(
+    uri: $uri,
+    configuration: $configuration,
+);
+$server = new WebSocket\Server(
+    port: $port,
+    ssl: $ssl,
+    configuration: $configuration,
+);
+```
+
+Get and set Configuration;
+```php
+$configuration = $client->getConfiguration();
+$client->setConfiguration($configuration);
+$configuration = $server->getConfiguration();
+$server->setConfiguration($configuration);
+```
+
+
+## Configuration options
+
+### Logger
+
+```
+type: Psr\Log\LoggerInterface
+default: Psr\Log\NullLogger
+```
+
+Attach any [PSR-4 compatible](https://www.php-fig.org/psr/psr-3/) logger.
+
+```php
+// Configuration instance
+$configuration = new WebSocket\Configuration(logger: $logger);
+$configuration->setLogger($logger);
+$logger = $configuration->getLogger();
+
+// Convenience setters
+$client->setLogger($logger);
+$server->setLogger($logger);
+```
+
+### Context
+
+```
+type: Phrity\Net\Context
+default: Phrity\Net\Context // Empty context
+```
+
+Client and server support adding [context options and parameters](https://www.php.net/manual/en/context.php)
+using the [Phrity\Net\Context](https://github.com/sirn-se/phrity-net-stream?tab=readme-ov-file#context-class) class.
+
+```php
+// Create and configure Context
+$context = new Phrity\Net\Context();
+$context->setOptions([
+    "ssl" => [
+        "verify_peer" => false,
+        "verify_peer_name" => false,
+    ],
+]);
+
+// Configuration instance
+$configuration = new WebSocket\Configuration(context: $context);
+$configuration->setContext($context);
+$context = $configuration->getContext();
+
+// Convenience getters/setters
+$context = $client->getContext();
+$client->setContext($context);
+$context = $server->getContext();
+$server->setContext($context);
+```
+
+### Timeout
+
+```
+type: int<0, max>|float<0, max>
+default: 60
+```
+
+Timeout for various operations can be specified in seconds.
+This affects how long Client and Server will wait for connection, read and write operations, and listener scope.
+Default is `60` seconds. Minimum is `0` seconds. Accepts int or float value.
+Avoid setting very low values as it will cause a read loop to use all
+available processing power even when there's nothing to read.
+
+```php
+// Configuration instance
+$configuration = new WebSocket\Configuration(timeout: $timeout);
+$configuration->setTimeout($timeout);
+$timeout = $configuration->getTimeout();
+
+// Convenience getters/setters
+$timeout = $client->getTimeout();
+$client->setTimeout($timeout);
+$timeout = $server->getTimeout();
+$server->setTimeout($timeout);
+```
+
+### Frame size
+
+```
+type: int<1, max>
+default: 4096
+```
+
+Defines the maximum payload per frame size in bytes.
+Default is `4096` bytes. Minimum is `1` byte.
+Do not change unless you have a strong reason to do so.
+
+```php
+// Configuration instance
+$configuration = new WebSocket\Configuration(frameSize: $frameSize);
+$configuration->setFrameSize($frameSize);
+$frameSize = $configuration->getFrameSize();
+
+// Convenience getters/setters
+$frameSize = $client->getFrameSize();
+$client->setFrameSize($frameSize);
+$frameSize = $server->getFrameSize();
+$server->setFrameSize($frameSize);
+```
+
+### Persistent connection (Client only)
+
+```
+type: bool
+default: false
+```
+
+If set to true, the underlying connection will be kept open if possible.
+This means that if Client closes and is then restarted, it may use the same connection.
+Do not change unless you have a strong reason to do so.
+
+```php
+// Configuration instance
+$configuration = new WebSocket\Configuration(persistent: $persistent);
+$configuration->setPersistent($persistent);
+$persistent = $configuration->isPersistent();
+
+// Convenience setter
+$client->setPersistent($persistent);
+```
+
+### Max connections (Server only)
+
+```
+type: int<1, max>|null
+default: null // Unlimited
+```
+
+Limit maximum number of connections served. Any additional connection attempts will fail.
+By default Server support unlimited number of connections.
+
+```php
+// Configuration instance
+$configuration = new WebSocket\Configuration(maxConnections: $maxConnections);
+$configuration->setMaxConnections($maxConnections);
+$maxConnections = $configuration->getMaxConnections();
+
+// Convenience setter
+$server->setMaxConnections($maxConnections);
+```
+
+## Other configurable classes
+
+```php
+// Connection class
+$connection = new WebSocket\Connection(..., configuration: $configuration);
+$configuration = $connection->getConfiguration();
+$connection->setConfiguration($configuration);
+
+// FrameHandler class
+$frameHandler = new WebSocket\Frame\FrameHandler(..., configuration: $configuration);
+$configuration = $frameHandler->getConfiguration();
+$frameHandler->setConfiguration($configuration);
+
+// MessageHandler class
+$messageHandler = new WebSocket\Message\MessageHandler(..., configuration: $configuration);
+$configuration = $messageHandler->getConfiguration();
+$messageHandler->setConfiguration($configuration);
+```
+
+If you need to set configuration on internal classes, best way is to clone the original;
+
+```php
+$clonedConfiguration = clone $source->getConfiguration();
+$clonedConfiguration->setLogger(...);
+$clonedConfiguration->setTimeout(...);
+$clonedConfiguration->setFrameSize(...);
+$source->setConfiguration($clonedConfiguration);
+```
+