|
| 1 | +from __future__ import annotations |
| 2 | + |
| 3 | +import http |
| 4 | +import ssl as ssl_module |
| 5 | +import urllib.parse |
| 6 | +from typing import Any, Awaitable, Callable, Literal |
| 7 | + |
| 8 | +from werkzeug.exceptions import NotFound |
| 9 | +from werkzeug.routing import Map, RequestRedirect |
| 10 | + |
| 11 | +from ..http11 import Request, Response |
| 12 | +from .server import Server, ServerConnection, serve |
| 13 | + |
| 14 | + |
| 15 | +__all__ = ["route", "unix_route", "Router"] |
| 16 | + |
| 17 | + |
| 18 | +class Router: |
| 19 | + """WebSocket router supporting :func:`route`.""" |
| 20 | + |
| 21 | + def __init__( |
| 22 | + self, |
| 23 | + url_map: Map, |
| 24 | + server_name: str | None = None, |
| 25 | + url_scheme: str = "ws", |
| 26 | + ) -> None: |
| 27 | + self.url_map = url_map |
| 28 | + self.server_name = server_name |
| 29 | + self.url_scheme = url_scheme |
| 30 | + for rule in self.url_map.iter_rules(): |
| 31 | + rule.websocket = True |
| 32 | + |
| 33 | + def get_server_name(self, connection: ServerConnection, request: Request) -> str: |
| 34 | + if self.server_name is None: |
| 35 | + return request.headers["Host"] |
| 36 | + else: |
| 37 | + return self.server_name |
| 38 | + |
| 39 | + def redirect(self, connection: ServerConnection, url: str) -> Response: |
| 40 | + response = connection.respond(http.HTTPStatus.FOUND, f"Found at {url}") |
| 41 | + response.headers["Location"] = url |
| 42 | + return response |
| 43 | + |
| 44 | + def not_found(self, connection: ServerConnection) -> Response: |
| 45 | + return connection.respond(http.HTTPStatus.NOT_FOUND, "Not Found") |
| 46 | + |
| 47 | + def route_request( |
| 48 | + self, connection: ServerConnection, request: Request |
| 49 | + ) -> Response | None: |
| 50 | + """Route incoming request.""" |
| 51 | + url_map_adapter = self.url_map.bind( |
| 52 | + server_name=self.get_server_name(connection, request), |
| 53 | + url_scheme=self.url_scheme, |
| 54 | + ) |
| 55 | + try: |
| 56 | + parsed = urllib.parse.urlparse(request.path) |
| 57 | + handler, kwargs = url_map_adapter.match( |
| 58 | + path_info=parsed.path, |
| 59 | + query_args=parsed.query, |
| 60 | + ) |
| 61 | + except RequestRedirect as redirect: |
| 62 | + return self.redirect(connection, redirect.new_url) |
| 63 | + except NotFound: |
| 64 | + return self.not_found(connection) |
| 65 | + connection.handler, connection.handler_kwargs = handler, kwargs |
| 66 | + return None |
| 67 | + |
| 68 | + async def handler(self, connection: ServerConnection) -> None: |
| 69 | + """Handle a connection.""" |
| 70 | + return await connection.handler(connection, **connection.handler_kwargs) |
| 71 | + |
| 72 | + |
| 73 | +def route( |
| 74 | + url_map: Map, |
| 75 | + *args: Any, |
| 76 | + server_name: str | None = None, |
| 77 | + ssl: ssl_module.SSLContext | Literal[True] | None = None, |
| 78 | + create_router: type[Router] | None = None, |
| 79 | + **kwargs: Any, |
| 80 | +) -> Awaitable[Server]: |
| 81 | + """ |
| 82 | + Create a WebSocket server dispatching connections to different handlers. |
| 83 | +
|
| 84 | + This feature requires the third-party library `werkzeug`_:: |
| 85 | +
|
| 86 | + $ pip install werkzeug |
| 87 | +
|
| 88 | + .. _werkzeug: https://werkzeug.palletsprojects.com/ |
| 89 | +
|
| 90 | + :func:`route` accepts the same arguments as |
| 91 | + :func:`~websockets.sync.server.serve`, except as described below. |
| 92 | +
|
| 93 | + The first argument is a :class:`werkzeug.routing.Map` that maps URL patterns |
| 94 | + to connection handlers. In addition to the connection, handlers receive |
| 95 | + parameters captured in the URL as keyword arguments. |
| 96 | +
|
| 97 | + Here's an example:: |
| 98 | +
|
| 99 | +
|
| 100 | + from websockets.asyncio.router import route |
| 101 | + from werkzeug.routing import Map, Rule |
| 102 | +
|
| 103 | + async def channel_handler(websocket, channel_id): |
| 104 | + ... |
| 105 | +
|
| 106 | + url_map = Map([ |
| 107 | + Rule("/channel/<uuid:channel_id>", endpoint=channel_handler), |
| 108 | + ... |
| 109 | + ]) |
| 110 | +
|
| 111 | + # set this future to exit the server |
| 112 | + stop = asyncio.get_running_loop().create_future() |
| 113 | +
|
| 114 | + async with route(url_map, ...) as server: |
| 115 | + await stop |
| 116 | +
|
| 117 | +
|
| 118 | + Refer to the documentation of :mod:`werkzeug.routing` for details. |
| 119 | +
|
| 120 | + If you define redirects with ``Rule(..., redirect_to=...)`` in the URL map, |
| 121 | + when the server runs behind a reverse proxy that modifies the ``Host`` |
| 122 | + header or terminates TLS, you need additional configuration: |
| 123 | +
|
| 124 | + * Set ``server_name`` to the name of the server as seen by clients. When not |
| 125 | + provided, websockets uses the value of the ``Host`` header. |
| 126 | +
|
| 127 | + * Set ``ssl=True`` to generate ``wss://`` URIs without actually enabling |
| 128 | + TLS. Under the hood, this bind the URL map with a ``url_scheme`` of |
| 129 | + ``wss://`` instead of ``ws://``. |
| 130 | +
|
| 131 | + There is no need to specify ``websocket=True`` in each rule. It is added |
| 132 | + automatically. |
| 133 | +
|
| 134 | + Args: |
| 135 | + url_map: Mapping of URL patterns to connection handlers. |
| 136 | + server_name: Name of the server as seen by clients. If :obj:`None`, |
| 137 | + websockets uses the value of the ``Host`` header. |
| 138 | + ssl: Configuration for enabling TLS on the connection. Set it to |
| 139 | + :obj:`True` if a reverse proxy terminates TLS connections. |
| 140 | + create_router: Factory for the :class:`Router` dispatching requests to |
| 141 | + handlers. Set it to a wrapper or a subclass to customize routing. |
| 142 | +
|
| 143 | + """ |
| 144 | + url_scheme = "ws" if ssl is None else "wss" |
| 145 | + if ssl is not True and ssl is not None: |
| 146 | + kwargs["ssl"] = ssl |
| 147 | + |
| 148 | + if create_router is None: |
| 149 | + create_router = Router |
| 150 | + |
| 151 | + router = create_router(url_map, server_name, url_scheme) |
| 152 | + |
| 153 | + _process_request: ( |
| 154 | + Callable[ |
| 155 | + [ServerConnection, Request], |
| 156 | + Awaitable[Response | None] | Response | None, |
| 157 | + ] |
| 158 | + | None |
| 159 | + ) = kwargs.pop("process_request", None) |
| 160 | + if _process_request is None: |
| 161 | + process_request: Callable[ |
| 162 | + [ServerConnection, Request], |
| 163 | + Awaitable[Response | None] | Response | None, |
| 164 | + ] = router.route_request |
| 165 | + else: |
| 166 | + |
| 167 | + async def process_request( |
| 168 | + connection: ServerConnection, request: Request |
| 169 | + ) -> Response | None: |
| 170 | + response = _process_request(connection, request) |
| 171 | + if isinstance(response, Awaitable): |
| 172 | + response = await response |
| 173 | + if response is not None: |
| 174 | + return response |
| 175 | + return router.route_request(connection, request) |
| 176 | + |
| 177 | + return serve(router.handler, *args, process_request=process_request, **kwargs) |
| 178 | + |
| 179 | + |
| 180 | +def unix_route( |
| 181 | + url_map: Map, |
| 182 | + path: str | None = None, |
| 183 | + **kwargs: Any, |
| 184 | +) -> Awaitable[Server]: |
| 185 | + """ |
| 186 | + Create a WebSocket Unix server dispatching connections to different handlers. |
| 187 | +
|
| 188 | + :func:`unix_route` combines the behaviors of :func:`route` and |
| 189 | + :func:`~websockets.asyncio.server.unix_serve`. |
| 190 | +
|
| 191 | + Args: |
| 192 | + url_map: Mapping of URL patterns to connection handlers. |
| 193 | + path: File system path to the Unix socket. |
| 194 | +
|
| 195 | + """ |
| 196 | + return route(url_map, unix=True, path=path, **kwargs) |
0 commit comments