Servers¶
Server Tutorial¶
This page goes into the details of creating a WebSocket server. Let’s start by revisiting the Server Example.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | import trio
from trio_websocket import serve_websocket, ConnectionClosed
async def echo_server(request):
ws = await request.accept()
while True:
try:
message = await ws.get_message()
await ws.send_message(message)
except ConnectionClosed:
break
async def main():
await serve_websocket(echo_server, '127.0.0.1', 8000, ssl_context=None)
trio.run(main)
|
Note
A more complete example is included in the repository.
As explained in the tutorial, a WebSocket server needs a handler function and a
host/port to bind to. The handler function receives a
WebSocketRequest
object, and it calls the request’s
accept()
method to finish the handshake and obtain a
WebSocketConnection
object. When the handler function exits, the
connection is automatically closed. If the handler function raises an
exception, the server will silently close the connection and cancel the
tasks belonging to it.
-
await
trio_websocket.
serve_websocket
(handler, host, port, ssl_context, *, handler_nursery=None, message_queue_size=1, max_message_size=1048576, connect_timeout=60, disconnect_timeout=60, task_status=TASK_STATUS_IGNORED)¶ Serve a WebSocket over TCP.
This function supports the Trio nursery start protocol:
server = await nursery.start(serve_websocket, …)
. It will block until the server is accepting connections and then return aWebSocketServer
object.Note that if
host
isNone
andport
is zero, then you may get multiple listeners that have different port numbers!Parameters: - handler – An async function that is invoked with a request for each new connection.
- host (str, bytes, or None) – The host interface to bind. This can be an address of an
interface, a name that resolves to an interface address (e.g.
localhost
), or a wildcard address like0.0.0.0
for IPv4 or::
for IPv6. IfNone
, then all local interfaces are bound. - port (int) – The port to bind to.
- ssl_context (ssl.SSLContext or None) – The SSL context to use for encrypted connections, or
None
for unencrypted connection. - handler_nursery – An optional nursery to spawn handlers and background tasks in. If not specified, a new nursery will be created internally.
- message_queue_size (int) – The maximum number of messages that will be buffered in the library’s internal message queue.
- max_message_size (int) – The maximum message size as measured by
len()
. If a message is received that is larger than this size, then the connection is closed with code 1009 (Message Too Big). - connect_timeout (float) – The number of seconds to wait for a client to finish connection handshake before timing out.
- disconnect_timeout (float) – The number of seconds to wait for a client to finish the closing handshake before timing out.
- task_status – Part of Trio nursery start protocol.
Returns: This function runs until cancelled.
Custom Stream¶
The WebSocket protocol is defined as an application layer protocol that runs on top of TCP, and the convenience functions described above automatically create those TCP connections. In more obscure use cases, you might want to run the WebSocket protocol on top of some other type of transport protocol. The library includes a convenience function that allows you to wrap any arbitrary Trio stream with a server WebSocket.
-
await
trio_websocket.
wrap_server_stream
(nursery, stream, message_queue_size=1, max_message_size=1048576)¶ Wrap an arbitrary stream in a server-side WebSocket.
This is a low-level function only needed in rare cases. In most cases, you should use
serve_websocket()
.Parameters: - nursery – A nursery to run background tasks in.
- stream (trio.abc.Stream) – A stream to be wrapped.
- message_queue_size (int) – The maximum number of messages that will be buffered in the library’s internal message queue.
- max_message_size (int) – The maximum message size as measured by
len()
. If a message is received that is larger than this size, then the connection is closed with code 1009 (Message Too Big).
Return type: