Set CloseClientOnQueueFull to false by default

This PR changes the default flag for CloseClientOnQueueFull to set it to false.

false should be the sensible default for this library especially after teh recent refatcoring allowing for a very fast message delivery.

Applications have to check the status when sending and queue status to check if they need to decrease the sending rate or close the client.

Ref: #433

Author: mathieucarbou

src/AsyncWebSocket.cpp

@@ -467,7 +467,7 @@ bool AsyncWebSocketClient::_queueMessage(AsyncWebSocketSharedBuffer buffer, uint
   }
 
   if (_messageQueue.size() >= WS_MAX_QUEUED_MESSAGES) {
-    if (closeWhenFull) {
+    if (_closeWhenFull) {
       _status = WS_DISCONNECTED;
 
       async_ws_log_w("[%s][%" PRIu32 "] Too many messages queued: closing connection", _server->url(), _clientId);

src/AsyncWebSocket.h

@@ -225,7 +225,7 @@ class AsyncWebSocketClient {
   mutable asyncsrv::mutex_type _queue_lock;
   std::deque<AsyncWebSocketControl> _controlQueue;
   std::deque<AsyncWebSocketMessage> _messageQueue;
-  bool closeWhenFull = true;
+  bool _closeWhenFull = false;
 
   AwsFrameInfo _pinfo;
 
@@ -274,29 +274,40 @@ class AsyncWebSocketClient {
     return _pinfo;
   }
 
-  //  - If "true" (default), the connection will be closed if the message queue is full.
+  // CloseClientOnQueueFull:
+  // 
+  // - If "true", the client will be closed if the message queue becomes full.
   // This is the default behavior in yubox-node-org, which is not silently discarding messages but instead closes the connection.
   // The big issue with this behavior is  that is can cause the UI to automatically re-create a new WS connection, which can be filled again,
-  // and so on, causing a resource exhaustion.
+  // and so on, causing a resource exhaustion. 
+  // Also this can lead to a crash as explained in this issue: https://github.com/ESP32Async/ESPAsyncWebServer/issues/433
   //
-  // - If "false", the incoming message will be discarded if the queue is full.
+  // - If "false" (default in this library), the incoming message will be discarded if the queue is full.
   // This is the default behavior in the original ESPAsyncWebServer library from me-no-dev.
   // This behavior allows the best performance at the expense of unreliable message delivery in case the queue is full (some messages may be lost).
   //
-  // - In any case, when the queue is full, a message is logged.
-  // - IT is recommended to use the methods queueIsFull(), availableForWriteAll(), availableForWrite(clientId) to check if the queue is full before sending a message.
+  // With recent refactorings of the library, the queue is barely used and the library supports a fast sending rate of messages. So if the queue is growing:
+  //  - either the server is sending messages at an insane fast rate, faster than what the client can acknowledge, which can be the case if the client is slow or if the messages are big and the network is slow
+  //  - or there is a network issue causing the client to not receive messages, or network is broken. In that case, if the network is broken, the queue will fill temporarily until the connection is closed and client removed.
+  // 
+  // In case your application requires a fast and high frequency message sending and you forsee some queue usage, you can:
+  //  - increase the queue side to allow some room
+  //  - check some functions status before or when sending in order to decrease your sending rate to let the queue drain, or take action by closing this client if necessary.
+  // 
+  // This has to be an application-specific deicison that the library cannot take for you.
+  // Here are a list of some functions that you can use and check the boolean value returned:
+  // - the send methods
+  // - queueIsFull()
+  // - availableForWriteAll()
+  // - availableForWrite(clientId)
   //
-  // Usage:
-  //  - can be set in the onEvent listener when connecting (event type is: WS_EVT_CONNECT)
+  // When the queue is full, a message is logged in case it is discarded.
   //
-  // Use cases:,
-  // - if using websocket to send logging messages, maybe some loss is acceptable.
-  // - But if using websocket to send UI update messages, maybe the connection should be closed and the UI redrawn.
   void setCloseClientOnQueueFull(bool close) {
-    closeWhenFull = close;
+    _closeWhenFull = close;
   }
   bool willCloseClientOnQueueFull() const {
-    return closeWhenFull;
+    return _closeWhenFull;
   }
 
   IPAddress remoteIP() const;
@@ -319,8 +330,8 @@ class AsyncWebSocketClient {
   }
 
   // data packets
-  void message(AsyncWebSocketSharedBuffer buffer, uint8_t opcode = WS_TEXT, bool mask = false) {
-    _queueMessage(buffer, opcode, mask);
+  bool message(AsyncWebSocketSharedBuffer buffer, uint8_t opcode = WS_TEXT, bool mask = false) {
+    return _queueMessage(buffer, opcode, mask);
   }
   bool queueIsFull() const;
   size_t queueLen() const;