Add topic guide on routing.

Author: aaugustin

docs/deploy/index.rst

@@ -14,8 +14,8 @@ architecture will almost certainly look like the following diagram:
 The basic unit for scaling a websockets server is "one server process". Each
 blue box in the diagram represents one server process.
 
-There's more variation in routing. While the routing layer is shown as one big
-box, it is likely to involve several subsystems.
+There's more variation in routing connections to processes. While the routing
+layer is shown as one big box, it is likely to involve several subsystems.
 
 As a consequence, when you design a deployment, you must answer two questions:
 
@@ -153,8 +153,8 @@ If you override the default signal handler for SIGINT, which raises
 :exc:`KeyboardInterrupt`, be aware that you won't be able to interrupt a
 program with Ctrl-C anymore when it's stuck in a loop.
 
-Routing connections
--------------------
+Routing connections to processes
+--------------------------------
 
 What does routing involve?
 ..........................

docs/faq/server.rst

@@ -208,26 +208,8 @@ How do I access the request path?
 
 It is available in the :attr:`~ServerConnection.request` object.
 
-You may route a connection to different handlers depending on the request path::
-
-    async def handler(websocket):
-        if websocket.request.path == "/blue":
-            await blue_handler(websocket)
-        elif websocket.request.path == "/green":
-            await green_handler(websocket)
-        else:
-            # No handler for this path; close the connection.
-            return
-
-For more complex routing, you may use :func:`~websockets.asyncio.router.route`.
-
-You may also route the connection based on the first message received from the
-client, as shown in the :doc:`tutorial <../intro/tutorial2>`. When you want to
-authenticate the connection before routing it, this is usually more convenient.
-
-Generally speaking, there is far less emphasis on the request path in WebSocket
-servers than in HTTP servers. When a WebSocket server provides a single endpoint,
-it may ignore the request path entirely.
+Refer to the :doc:`routing guide <../topics/routing>` for details on how to
+route connections to different handlers depending on the request path.
 
 How do I access HTTP headers?
 -----------------------------

docs/project/changelog.rst

@@ -43,7 +43,9 @@ Backwards-incompatible changes
     SOCKS proxies require installing the third-party library `python-socks`_.
 
     If you want to disable the proxy, add ``proxy=None`` when calling
-    :func:`~asyncio.client.connect`. See :doc:`../topics/proxies` for details.
+    :func:`~asyncio.client.connect`.
+
+    See :doc:`proxies <../topics/proxies>` for details.
 
     .. _python-socks: https://github.com/romis2012/python-socks
 
@@ -60,7 +62,8 @@ New features
 ............
 
 * Added :func:`~asyncio.router.route` and :func:`~asyncio.router.unix_route` to
-  dispatch connections to different handlers depending on the URL.
+  dispatch connections to handlers based on the request path. Read more about
+  routing in :doc:`routing <../topics/routing>`.
 
 Improvements
 ............

docs/topics/index.rst

@@ -6,12 +6,13 @@ Get a deeper understanding of how websockets is built and why.
 .. toctree::
    :titlesonly:
 
-   logging
    authentication
    broadcast
    compression
    keepalive
+   logging
    memory
    security
    performance
    proxies
+   routing

docs/topics/routing.rst

@@ -0,0 +1,83 @@
+Routing
+=======
+
+.. currentmodule:: websockets
+
+Many WebSocket servers provide just one endpoint. That's why
+:func:`~asyncio.server.serve` accepts a single connection handler as its first
+argument.
+
+This may come as a surprise to you if you're used to HTTP servers. In a standard
+HTTP application, each request gets dispatched to a handler based on the request
+path. Clients know which path to use for which operation.
+
+In a WebSocket application, clients open a persistent connection then they send
+all messages over that unique connection. When different messages correspond to
+different operations, they must be dispatched based on the message content.
+
+Simple routing
+--------------
+
+If you need different handlers for different clients or different use cases, you
+may route each connection to the right handler based on the request path.
+
+Since WebSocket servers typically provide fewer routes than HTTP servers, you
+can keep it simple::
+
+    async def handler(websocket):
+        match websocket.request.path:
+            case "/blue":
+                await blue_handler(websocket)
+            case "/green":
+                await green_handler(websocket)
+            case _:
+                # No handler for this path. Close the connection.
+                return
+
+You may also route connections based on the first message received from the
+client, as demonstrated in the :doc:`tutorial <../intro/tutorial2>`::
+
+    import json
+
+    async def handler(websocket):
+        message = await websocket.recv()
+        settings = json.loads(message)
+        match settings["color"]:
+            case "blue":
+                await blue_handler(websocket)
+            case "green":
+                await green_handler(websocket)
+            case _:
+                # No handler for this message. Close the connection.
+                return
+
+When you need to authenticate the connection before routing it, this pattern is
+more convenient.
+
+Complex routing
+---------------
+
+If you have outgrow these simple patterns, websockets provides full-fledged
+routing based on the request path with :func:`~asyncio.router.route`.
+
+This feature builds upon Flask_'s router. To use it, you must install the
+third-party library `werkzeug`_::
+
+    $ pip install werkzeug
+
+.. _Flask: https://flask.palletsprojects.com/
+.. _werkzeug: https://werkzeug.palletsprojects.com/
+
+:func:`~asyncio.router.route` expects a :class:`werkzeug.routing.Map` as its
+first argument to declare which URL patterns map to which handlers. Review the
+documentation of :mod:`werkzeug.routing` to learn about its functionality.
+
+To give you a sense of what's possible, here's the URL map of the example in
+`example/routing.py`_:
+
+.. _example/routing.py: https://github.com/python-websockets/websockets/blob/main/example/routing.py
+
+.. literalinclude:: ../../example/routing.py
+    :language: python
+    :start-at: url_map = Map(
+    :end-at: await server.serve_forever()