Merge branch 'master' into SimulateMultipartFile#1010

docs/user/faq.rst

@@ -1233,6 +1233,55 @@ the tutorial in the docs provides an excellent introduction to
 
 (See also: `Testing <http://falcon.readthedocs.io/en/stable/api/testing.html>`_)
 
+Can I shut my server down cleanly from the app?
+-----------------------------------------------
+
+Normally, the lifetime of an app server is controlled by other means than from
+inside the running app, and there is no standardized way for a WSGI or ASGI
+framework to shut down the server programmatically.
+
+However, if you need to spin up a real server for testing purposes (such as for
+collecting coverage while interacting with other services over the network),
+your app server of choice may offer a Python API or hooks that you can
+integrate into your app.
+
+For instance, the stdlib's :mod:`wsgiref` server inherits from
+:class:`~socketserver.TCPServer`, which can be stopped by calling its
+``shutdown()`` method. Just make sure to perform the call from a different
+thread (otherwise it may deadlock):
+
+.. code:: python
+
+    import http
+    import threading
+    import wsgiref.simple_server
+
+    import falcon
+
+
+    class Shutdown:
+        def __init__(self, httpd):
+            self._httpd = httpd
+
+        def on_post(self, req, resp):
+            thread = threading.Thread(target=self._httpd.shutdown, daemon=True)
+            thread.start()
+
+            resp.content_type = falcon.MEDIA_TEXT
+            resp.text = 'Shutting down...\n'
+            resp.status = http.HTTPStatus.ACCEPTED
+
+
+    with wsgiref.simple_server.make_server('', 8000, app := falcon.App()) as httpd:
+        app.add_route('/shutdown', Shutdown(httpd))
+        print('Serving on port 8000, POST to /shutdown to stop...')
+        httpd.serve_forever()
+
+.. warning::
+   While ``wsgiref.simple_server`` is handy for integration testing, it builds
+   upon :mod:`http.server`, which is not recommended for production. (See
+   :ref:`install` on how to install a production-ready WSGI or ASGI server.)
+
 How can I set cookies when simulating requests?
 -----------------------------------------------
 

docs/user/tutorial-asgi.rst

@@ -685,10 +685,10 @@ small files littering our storage, it consumes CPU resources, and we would
 soon find our application crumbling under load.
 
 Let's mitigate this problem with response caching. We'll use Redis, taking
-advantage of `aioredis <https://github.com/aio-libs/aioredis>`_ for async
+advantage of `redis <https://redis.readthedocs.io/en/stable/examples/asyncio_examples.html>`_ for async
 support::
 
-  pip install aioredis
+  pip install redis
 
 We will also need to serialize response data (the ``Content-Type`` header and
 the body in the first version); ``msgpack`` should do::
@@ -700,7 +700,7 @@ installing Redis server on your machine, one could also:
 
 * Spin up Redis in Docker, eg::
 
-    docker run -p 6379:6379 redis
+    docker run -p 6379:6379 redis/redis-stack:latest
 
 * Assuming Redis is installed on the machine, one could also try
   `pifpaf <https://github.com/jd/pifpaf>`_ for spinning up Redis just
@@ -747,9 +747,8 @@ implementations for production and testing.
     ``self.redis_host``. Such a design might prove helpful for apps that
     need to create client connections in more than one place.
 
-Assuming we call our new :ref:`configuration <asgi_tutorial_config>` items
-``redis_host`` and ``redis_from_url()``, respectively, the final version of
-``config.py`` now reads:
+Assuming we call our new :ref:`configuration <asgi_tutorial_config>` item
+``redis_host`` the final version of ``config.py`` now reads:
 
 .. literalinclude:: ../../examples/asgilook/asgilook/config.py
     :language: python
@@ -860,7 +859,7 @@ any problems with importing local utility modules or checking code coverage::
   $ mkdir -p tests
   $ touch tests/__init__.py
 
-Next, let's implement fixtures to replace ``uuid`` and ``aioredis``, and inject them
+Next, let's implement fixtures to replace ``uuid`` and ``redis``, and inject them
 into our tests via ``conftest.py`` (place your code in the newly created ``tests``
 directory):
 

examples/asgilook/asgilook/cache.py

@@ -1,4 +1,5 @@
 import msgpack
+import redis.asyncio as redis
 
 
 class RedisCache:
@@ -24,7 +25,7 @@ async def process_startup(self, scope, event):
         await self._redis.ping()
 
     async def process_shutdown(self, scope, event):
-        await self._redis.close()
+        await self._redis.aclose()
 
     async def process_request(self, req, resp):
         resp.context.cached = False

examples/asgilook/asgilook/config.py

@@ -1,15 +1,14 @@
 import os
 import pathlib
+import redis.asyncio
 import uuid
 
-import aioredis
-
 
 class Config:
     DEFAULT_CONFIG_PATH = '/tmp/asgilook'
     DEFAULT_MIN_THUMB_SIZE = 64
+    DEFAULT_REDIS_FROM_URL = redis.asyncio.from_url
     DEFAULT_REDIS_HOST = 'redis://localhost'
-    DEFAULT_REDIS_FROM_URL = aioredis.from_url
     DEFAULT_UUID_GENERATOR = uuid.uuid4
 
     def __init__(self):
@@ -18,7 +17,7 @@ def __init__(self):
         )
         self.storage_path.mkdir(parents=True, exist_ok=True)
 
-        self.redis_from_url = Config.DEFAULT_REDIS_FROM_URL
         self.min_thumb_size = self.DEFAULT_MIN_THUMB_SIZE
+        self.redis_from_url = Config.DEFAULT_REDIS_FROM_URL
         self.redis_host = self.DEFAULT_REDIS_HOST
         self.uuid_generator = Config.DEFAULT_UUID_GENERATOR

examples/asgilook/requirements/asgilook

@@ -1,4 +1,4 @@
 aiofiles>=0.4.0
-aioredis>=2.0
+redis>=5.0
 msgpack
 Pillow>=6.0.0