From 3375063a807a817a47a6a393890c420c7f5014ef Mon Sep 17 00:00:00 2001
From: Vytautas Liuolia <vytautas.liuolia@gmail.com>
Date: Sun, 14 Jan 2024 21:04:24 +0100
Subject: [PATCH 1/2] docs(FAQ): add a FAQ item on shutting down
 `wsgiref.simple_server`

---
 docs/user/faq.rst | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/docs/user/faq.rst b/docs/user/faq.rst
index 21c6a114c..d8f15951f 100644
--- a/docs/user/faq.rst
+++ b/docs/user/faq.rst
@@ -1233,6 +1233,50 @@ 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()
+
 How can I set cookies when simulating requests?
 -----------------------------------------------
 

From 861fa3b2b14b82d03518ca64ae741588181c75d6 Mon Sep 17 00:00:00 2001
From: Vytautas Liuolia <vytautas.liuolia@gmail.com>
Date: Mon, 15 Jan 2024 23:44:10 +0100
Subject: [PATCH 2/2] docs(FAQ): add a note that wsgiref.simple_server is not
 recommended for prod

---
 docs/user/faq.rst | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/docs/user/faq.rst b/docs/user/faq.rst
index d8f15951f..d442c9140 100644
--- a/docs/user/faq.rst
+++ b/docs/user/faq.rst
@@ -1277,6 +1277,11 @@ thread (otherwise it may deadlock):
         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?
 -----------------------------------------------