From 6a2463cc21e56dfac27f63832d2510a3e1467634 Mon Sep 17 00:00:00 2001
From: Miguel Grinberg <miguel.grinberg@gmail.com>
Date: Sat, 15 May 2021 14:59:14 +0100
Subject: [PATCH] Document the use of simple-websocket with the development web
 server

---
 docs/index.rst             | 38 ++++++++++++++++++++++++++------------
 flask_socketio/__init__.py |  3 +--
 2 files changed, 27 insertions(+), 14 deletions(-)

diff --git a/docs/index.rst b/docs/index.rst
index d6aba491..151148c6 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -37,9 +37,9 @@ this package relies on can be selected among three choices:
   comes with WebSocket functionality. The use of gevent is also a performant
   option, but slightly lower than eventlet.
 - The Flask development server based on Werkzeug can be used as well, with the
-  caveat that it lacks the performance of the other two options, so it should
-  only be used to simplify the development workflow. This option only supports
-  the long-polling transport.
+  caveat that this web server is intended only for development use, so it
+  should only be used to simplify the development workflow and not for
+  production.
 
 The extension automatically detects which asynchronous framework to use based
 on what is installed. Preference is given to eventlet, followed by gevent.
@@ -569,15 +569,16 @@ described.
 Embedded Server
 ~~~~~~~~~~~~~~~
 
-The simplest deployment strategy is to have eventlet or gevent installed, and
-start the web server by calling ``socketio.run(app)`` as shown in examples
-above. This will run the application on the eventlet or gevent web servers,
-whichever is installed.
+The simplest deployment strategy is to start the web server by calling
+``socketio.run(app)`` as shown in examples above. This will look through the
+packages that are installed for the best available web server start the
+application on it. The current web server choices that are evaluated are
+``eventlet``, ``gevent`` and the Flask development server.
 
-Note that ``socketio.run(app)`` runs a production ready server when eventlet
-or gevent are installed. If neither of these are installed, then the
-application runs on Flask's development web server, which is not appropriate
-for production use.
+If eventlet or gevent are available, ``socketio.run(app)`` starts a
+production-ready server using one of these frameworks. If neither of these are
+installed, then the Flask development web server is used, and in this case the
+server is not intended to be used in a production deployment.
 
 Unfortunately this option is not available when using gevent with uWSGI. See
 the uWSGI section below for information on this option.
@@ -603,6 +604,15 @@ modified command is::
 
     gunicorn -k geventwebsocket.gunicorn.workers.GeventWebSocketWorker -w 1 module:app
 
+A third option with Gunicorn is to use the threaded worker, along with the
+`simple-websocket <https://github.com/miguelgrinberg/simple-websocket`_
+package for WebSocket support. This is a particularly good solution for
+applications that are CPU heavy or are otherwise incompatible with eventlet
+and gevent use of green threads. The command to start a threaded web server
+is::
+
+    gunicorn -w 1 --threads 100 module:app
+
 In all these commands, ``module`` is the Python module or package that defines
 the application instance, and ``app`` is the application instance itself.
 
@@ -610,6 +620,10 @@ Due to the limited load balancing algorithm used by gunicorn, it is not possible
 to use more than one worker process when using this web server. For that reason,
 all the examples above include the ``-w 1`` option.
 
+The workaround to use multiple worker processes with gunicorn is to launch
+several single-worker instances and put them behind a more capable load
+balancer such as `nginx <https://www.nginx.com/>`_.
+
 uWSGI Web Server
 ~~~~~~~~~~~~~~~~
 
@@ -695,7 +709,7 @@ servers::
 
 While the above examples can work as an initial configuration, be aware that a
 production install of nginx will need a more complete configuration covering
-other deployment aspects such as serving static file assets and SSL support.
+other deployment aspects such as SSL support.
 
 Using Multiple Workers
 ~~~~~~~~~~~~~~~~~~~~~~
diff --git a/flask_socketio/__init__.py b/flask_socketio/__init__.py
index 599afd29..8dbc03e6 100644
--- a/flask_socketio/__init__.py
+++ b/flask_socketio/__init__.py
@@ -584,8 +584,7 @@ def run(self, app, host=None, port=None, **kwargs):
         if self.server.eio.async_mode == 'threading':
             from werkzeug._internal import _log
             _log('warning', 'WebSocket transport not available. Install '
-                            'eventlet or gevent and gevent-websocket for '
-                            'improved performance.')
+                            'simple-websocket for improved performance.')
             app.run(host=host, port=port, threaded=True,
                     use_reloader=use_reloader, **kwargs)
         elif self.server.eio.async_mode == 'eventlet':