Server (asyncio) - websockets 12.0 documentation
Description: Starting a server: Stopping a server: Using a connection: Basic authentication: websockets supports HTTP Basic Authentication according to RFC 7235 and RFC 7617. Broadcast:

Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# Server (`asyncio`)

## Starting a server

await websockets.server.serve(ws_handler, host=None, port=None, *, create_protocol=None, logger=None, compression='deflate', origins=None, extensions=None, subprotocols=None, extra_headers=None, server_header='Python/x.y.z websockets/X.Y', process_request=None, select_subprotocol=None, ping_interval=20, ping_timeout=20, close_timeout=10, max_size=2**20, max_queue=2**5, read_limit=2**16, write_limit=2**16, **kwds)

  Start a WebSocket server listening on `host` and `port`.

  Whenever a client connects, the server creates a `WebSocketServerProtocol`, performs the opening handshake, and delegates to the connection handler, `ws_handler`.

  The handler receives the `WebSocketServerProtocol` and uses it to send and receive messages.

  Once the handler completes, either normally or with an exception, the server performs the closing handshake and closes the connection.

  Awaiting `serve()` yields a `WebSocketServer`. This object provides a `close()` method to shut down the server:

      stop = asyncio.Future()  # set this future to exit the server

      server = await serve(...)
      await stop
      await server.close()

  `serve()` can be used as an asynchronous context manager. Then, the server is shut down automatically when exiting the context:

      stop = asyncio.Future()  # set this future to exit the server

      async with serve(...):
          await stop

  Parameters:

    - ws_handler (Union[Callable[[WebSocketServerProtocol], Awaitable[Any]], Callable[[WebSocketServerProtocol, str], Awaitable[Any]]]) – Connection handler. It receives the WebSocket connection, which is a `WebSocketServerProtocol`, in argument.

    - host (Optional[Union[str, Sequence[str]]]) – Network interfaces the server binds to. See `create_server()` for details.

    - port (Optional[int]) – TCP port the server listens on. See `create_server()` for details.

    - create_protocol (Optional[Callable[..., WebSocketServerProtocol]]) – Factory for the `asyncio.Protocol` managing the connection. It defaults to `WebSocketServerProtocol`. Set it to a wrapper or a subclass to customize connection handling.

    - logger (Optional[LoggerLike]) – Logger for this server. It defaults to `logging.getLogger("websockets.server")`. See the logging guide for details.

    - compression (Optional[str]) – The “permessage-deflate” extension is enabled by default. Set `compression` to `None` to disable it. See the compression guide for details.

    - origins (Optional[Sequence[Optional[Origin]]]) – Acceptable values of the `Origin` header, for defending against Cross-Site WebSocket Hijacking attacks. Include `None` in the list if the lack of an origin is acceptable.

    - extensions (Optional[Sequence[ServerExtensionFactory]]) – List of supported extensions, in order in which they should be negotiated and run.

    - subprotocols (Optional[Sequence[Subprotocol]]) – List of supported subprotocols, in order of decreasing preference.

    - extra_headers (Union[HeadersLike, Callable[[str, Headers], HeadersLike]]) – Arbitrary HTTP headers to add to the response. This can be a `HeadersLike` or a callable taking the request path and headers in arguments and returning a `HeadersLike`.

    - server_header (Optional[str]) – Value of the `Server` response header. It defaults to `"Python/x.y.z websockets/X.Y"`. Setting it to `None` removes the header.

    - process_request (Optional[Callable[[str, Headers], Awaitable[Optional[Tuple[StatusLike, HeadersLike, bytes]]]]]) – Intercept HTTP request before the opening handshake. See `process_request()` for details.

    - select_subprotocol (Optional[Callable[[Sequence[Subprotocol], Sequence[Subprotocol]], Subprotocol]]) – Select a subprotocol supported by the client. See `select_subprotocol()` for details.

    - open_timeout (Optional[float]) – Timeout for opening connections in seconds. `None` disables the timeout.

  See `WebSocketCommonProtocol` for the documentation of `ping_interval`, `ping_timeout`, `close_timeout`, `max_size`, `max_queue`, `read_limit`, and `write_limit`.

  Any other keyword arguments are passed the event loop’s `create_server()` method.

  For example:

  - You can set `ssl` to a `SSLContext` to enable TLS.

  - You can set `sock` to a `socket` that you created outside of websockets.

  Returns:

    WebSocket server.

  Return type:

    WebSocketServer

await websockets.server.unix_serve(ws_handler, path=None, *, create_protocol=None, logger=None, compression='deflate', origins=None, extensions=None, subprotocols=None, extra_headers=None, server_header='Python/x.y.z websockets/X.Y', process_request=None, select_subprotocol=None, ping_interval=20, ping_timeout=20, close_timeout=10, max_size=2**20, max_queue=2**5, read_limit=2**16, write_limit=2**16, **kwds)

  Start a WebSocket server listening on a Unix socket.

  This function is identical to `serve()`, except the `host` and `port` arguments are replaced by `path`. It is only available on Unix.

  Unrecognized keyword arguments are passed the event loop’s `create_unix_server()` method.

  It’s useful for deploying a server behind a reverse proxy such as nginx.

  Parameters:

    path (str | None) – File system path to the Unix socket.

## Stopping a server

class websockets.server.WebSocketServer(logger=None)

  WebSocket server returned by `serve()`.

  This class provides the same interface as `Server`, notably the `close()` and `wait_closed()` methods.

  It keeps track of WebSocket connections in order to close them properly when shutting down.

  Parameters:

    logger (Optional[LoggerLike]) – Logger for this server. It defaults to `logging.getLogger("websockets.server")`. See the logging guide for details.

  close(close_connections=True)

    Close the server.

    - Close the underlying `Server`.

    - When `close_connections` is `True`, which is the default, close existing connections. Specifically:

      - Reject opening WebSocket connections with an HTTP 503 (service unavailable) error. This happens when the server accepted the TCP connection but didn’t complete the opening handshake before closing.

      - Close open WebSocket connections with close code 1001 (going away).

    - Wait until all connection handlers terminate.

    `close()` is idempotent.

  await wait_closed()

    Wait until the server is closed.

    When `wait_closed()` returns, all TCP connections are closed and all connection handlers have returned.

    To ensure a fast shutdown, a connection handler should always be awaiting at least one of:

    - `recv()`: when the connection is closed, it raises `ConnectionClosedOK`;

    - `wait_closed()`: when the connection is closed, it returns.

    Then the connection handler is immediately notified of the shutdown; it can clean up and exit.

  get_loop()

    See `asyncio.Server.get_loop()`.

  is_serving()

    See `asyncio.Server.is_serving()`.

  await start_serving()

    See `asyncio.Server.start_serving()`.

    Typical use:

        server = await serve(..., start_serving=False)
        # perform additional setup here...
        # ... then start the server
        await server.start_serving()

  await serve_forever()

    See `asyncio.Server.serve_forever()`.

    Typical use:

        server = await serve(...)
        # this coroutine doesn't return
        # canceling it stops the server
        await server.serve_forever()

    This is an alternative to using `serve()` as an asynchronous context manager. Shutdown is triggered by canceling `serve_forever()` instead of exiting a `serve()` context.

  sockets

    See `asyncio.Server.sockets`.

## Using a connection

class websockets.server.WebSocketServerProtocol(ws_handler, ws_server, *, logger=None, origins=None, extensions=None, subprotocols=None, extra_headers=None, server_header='Python/x.y.z websockets/X.Y', process_request=None, select_subprotocol=None, ping_interval=20, ping_timeout=20, close_timeout=10, max_size=2**20, max_queue=2**5, read_limit=2**16, write_limit=2**16)

  WebSocket server connection.

  `WebSocketServerProtocol` provides `recv()` and `send()` coroutines for receiving and sending messages.

  It supports asynchronous iteration to receive messages:

      async for message in websocket:
          await process(message)

  The iterator exits normally when the connection is closed with close code 1000 (OK) or 1001 (going away) or without a close code. It raises a `ConnectionClosedError` when the connection is closed with any other code.

  You may customize the opening handshake in a subclass by overriding `process_request()` or `select_subprotocol()`.

  Parameters:

    ws_server (WebSocketServer) – WebSocket server that created this connection.

  See `serve()` for the documentation of `ws_handler`, `logger`, `origins`, `extensions`, `subprotocols`, `extra_headers`, and `server_header`.

  See `WebSocketCommonProtocol` for the documentation of `ping_interval`, `ping_timeout`, `close_timeout`, `max_size`, `max_queue`, `read_limit`, and `write_limit`.

  await recv()

    Receive the next message.

    When the connection is closed, `recv()` raises `ConnectionClosed`. Specifically, it raises `ConnectionClosedOK` after a normal connection closure and `ConnectionClosedError` after a protocol error or a network failure. This is how you detect the end of the message stream.

    Canceling `recv()` is safe. There’s no risk of losing the next message. The next invocation of `recv()` will return it.

    This makes it possible to enforce a timeout by wrapping `recv()` in `timeout()` or `wait_for()`.

    Returns:

      A string (`str`) for a Text frame. A bytestring (`bytes`) for a Binary frame.

    Return type:

      Data

    Raises:

      - ConnectionClosed – When the connection is closed.

      - RuntimeError – If two coroutines call `recv()` concurrently.

  await send(message)

    Send a message.

    A string (`str`) is sent as a Text frame. A bytestring or bytes-like object (`bytes`, `bytearray`, or `memoryview`) is sent as a Binary frame.

    `send()` also accepts an iterable or an asynchronous iterable of strings, bytestrings, or bytes-like objects to enable fragmentation. Each item is treated as a message fragment and sent in its own frame. All items must be of the same type, or else `send()` will raise a `TypeError` and the connection will be closed.

    `send()` rejects dict-like objects because this is often an error. (If you want to send the keys of a dict-like object as fragments, call its `keys()` method and pass the result to `send()`.)

    Canceling `send()` is discouraged. Instead, you should close the connection with `close()`. Indeed, there are only two situations where `send()` may yield control to the event loop and then get canceled; in both cases, `close()` has the same effect and is more clear:

    1. The write buffer is full. If you don’t want to wait until enough data is sent, your only alternative is to close the connection. `close()` will likely time out then abort the TCP connection.

    2. `message` is an asynchronous iterator that yields control. Stopping in the middle of a fragmented message will cause a protocol error and the connection will be closed.

    When the connection is closed, `send()` raises `ConnectionClosed`. Specifically, it raises `ConnectionClosedOK` after a normal connection closure and `ConnectionClosedError` after a protocol error or a network failure.

    Parameters:

      message (Union[Data, Iterable[Data], AsyncIterable[Data]) – message to send.

    Raises:

      - ConnectionClosed – When the connection is closed.

      - TypeError – If `message` doesn’t have a supported type.

  await close(code=CloseCode.NORMAL_CLOSURE, reason='')

    Perform the closing handshake.

    `close()` waits for the other end to complete the handshake and for the TCP connection to terminate. As a consequence, there’s no need to await `wait_closed()` after `close()`.

    `close()` is idempotent: it doesn’t do anything once the connection is closed.

    Wrapping `close()` in `create_task()` is safe, given that errors during connection termination aren’t particularly useful.

    Canceling `close()` is discouraged. If it takes too long, you can set a shorter `close_timeout`. If you don’t want to wait, let the Python process exit, then the OS will take care of closing the TCP connection.

    Parameters:

      - code (int) – WebSocket close code.

      - reason (str) – WebSocket close reason.

  await wait_closed()

    Wait until the connection is closed.

    This coroutine is identical to the `closed` attribute, except it can be awaited.

    This can make it easier to detect connection termination, regardless of its cause, in tasks that interact with the WebSocket connection.

  await ping(data=None)

    Send a Ping.

    A ping may serve as a keepalive, as a check that the remote endpoint received all messages up to this point, or to measure `latency`.

    Canceling `ping()` is discouraged. If `ping()` doesn’t return immediately, it means the write buffer is full. If you don’t want to wait, you should close the connection.

    Canceling the `Future` returned by `ping()` has no effect.

    Parameters:

      data (Optional[Data]) – payload of the ping; a string will be encoded to UTF-8; or `None` to generate a payload containing four random bytes.

    Returns:

      A future that will be completed when the corresponding pong is received. You can ignore it if you don’t intend to wait. The result of the future is the latency of the connection in seconds.

          pong_waiter = await ws.ping()
          # only if you want to wait for the corresponding pong
          latency = await pong_waiter

    Return type:

      Future[float]

    Raises:

      - ConnectionClosed – When the connection is closed.

      - RuntimeError – If another ping was sent with the same data and the corresponding pong wasn’t received yet.

  await pong(data=b'')

    Send a Pong.

    An unsolicited pong may serve as a unidirectional heartbeat.

    Canceling `pong()` is discouraged. If `pong()` doesn’t return immediately, it means the write buffer is full. If you don’t want to wait, you should close the connection.

    Parameters:

      data (Data) – Payload of the pong. A string will be encoded to UTF-8.

    Raises:

      ConnectionClosed – When the connection is closed.

  You can customize the opening handshake in a subclass by overriding these methods:

  await process_request(path, request_headers)

    Intercept the HTTP request and return an HTTP response if appropriate.

    You may override this method in a `WebSocketServerProtocol` subclass, for example:

    - to return an HTTP 200 OK response on a given path; then a load balancer can use this path for a health check;

    - to authenticate the request and return an HTTP 401 Unauthorized or an HTTP 403 Forbidden when authentication fails.

    You may also override this method with the `process_request` argument of `serve()` and `WebSocketServerProtocol`. This is equivalent, except `process_request` won’t have access to the protocol instance, so it can’t store information for later use.

    `process_request()` is expected to complete quickly. If it may run for a long time, then it should await `wait_closed()` and exit if `wait_closed()` completes, or else it could prevent the server from shutting down.

    Parameters:

      - path (str) – request path, including optional query string.

      - request_headers (Headers) – request headers.

    Returns:

      `None` to continue the WebSocket handshake normally.

      An HTTP response, represented by a 3-uple of the response status, headers, and body, to abort the WebSocket handshake and return that HTTP response instead.

    Return type:

      Optional[Tuple[StatusLike, HeadersLike, bytes]]

  select_subprotocol(client_subprotocols, server_subprotocols)

    Pick a subprotocol among those supported by the client and the server.

    If several subprotocols are available, select the preferred subprotocol by giving equal weight to the preferences of the client and the server.

    If no subprotocol is available, proceed without a subprotocol.

    You may provide a `select_subprotocol` argument to `serve()` or `WebSocketServerProtocol` to override this logic. For example, you could reject the handshake if the client doesn’t support a particular subprotocol, rather than accept the handshake without that subprotocol.

    Parameters:

      - client_subprotocols (Sequence[Subprotocol]) – list of subprotocols offered by the client.

      - server_subprotocols (Sequence[Subprotocol]) – list of subprotocols available on the server.

    Returns:

      Selected subprotocol, if a common subprotocol was found.

      `None` to continue without a subprotocol.

    Return type:

      Optional[Subprotocol]

  WebSocket connection objects also provide these attributes:

  id: uuid.UUID

    Unique identifier of the connection. Useful in logs.

  logger: LoggerLike

    Logger for this connection.

  property local_address: Any

    Local address of the connection.

    For IPv4 connections, this is a `(host, port)` tuple.

    The format of the address depends on the address family; see `getsockname()`.

    `None` if the TCP connection isn’t established yet.

  property remote_address: Any

    Remote address of the connection.

    For IPv4 connections, this is a `(host, port)` tuple.

    The format of the address depends on the address family; see `getpeername()`.

    `None` if the TCP connection isn’t established yet.

  property open: bool

    `True` when the connection is open; `False` otherwise.

    This attribute may be used to detect disconnections. However, this approach is discouraged per the EAFP principle. Instead, you should handle `ConnectionClosed` exceptions.

  property closed: bool

    `True` when the connection is closed; `False` otherwise.

    Be aware that both `open` and `closed` are `False` during the opening and closing sequences.

  latency: float

    Latency of the connection, in seconds.

    This value is updated after sending a ping frame and receiving a matching pong frame. Before the first ping, `latency` is `0`.

    By default, websockets enables a keepalive mechanism that sends ping frames automatically at regular intervals. You can also send ping frames and measure latency with `ping()`.

  The following attributes are available after the opening handshake, once the WebSocket connection is open:

  path: str

    Path of the opening handshake request.

  request_headers: Headers

    Opening handshake request headers.

  response_headers: Headers

    Opening handshake response headers.

  subprotocol: Subprotocol | None

    Subprotocol, if one was negotiated.

  The following attributes are available after the closing handshake, once the WebSocket connection is closed:

  property close_code: int | None

    WebSocket close code, defined in section 7.1.5 of RFC 6455.

    `None` if the connection isn’t closed yet.

  property close_reason: str | None

    WebSocket close reason, defined in section 7.1.6 of RFC 6455.

    `None` if the connection isn’t closed yet.

## Basic authentication

websockets supports HTTP Basic Authentication according to RFC 7235 and RFC 7617.

websockets.auth.basic_auth_protocol_factory(realm=None, credentials=None, check_credentials=None, create_protocol=None)

  Protocol factory that enforces HTTP Basic Auth.

  `basic_auth_protocol_factory()` is designed to integrate with `serve()` like this:

      websockets.serve(
          ...,
          create_protocol=websockets.basic_auth_protocol_factory(
              realm="my dev server",
              credentials=("hello", "iloveyou"),
          )
      )

  Parameters:

    - realm (str | None) – Scope of protection. It should contain only ASCII characters because the encoding of non-ASCII characters is undefined. Refer to section 2.2 of RFC 7235 for details.

    - credentials (Tuple[str, str] | Iterable[Tuple[str, str]] | None) – Hard coded authorized credentials. It can be a `(username, password)` pair or a list of such pairs.

    - check_credentials (Callable[[str, str], Awaitable[bool]] | None) – Coroutine that verifies credentials. It receives `username` and `password` arguments and returns a `bool`. One of `credentials` or `check_credentials` must be provided but not both.

    - create_protocol (Callable[[...], BasicAuthWebSocketServerProtocol] | None) – Factory that creates the protocol. By default, this is `BasicAuthWebSocketServerProtocol`. It can be replaced by a subclass.

  Raises:

    TypeError – If the `credentials` or `check_credentials` argument is wrong.

class websockets.auth.BasicAuthWebSocketServerProtocol(*args, realm=None, check_credentials=None, **kwargs)

  WebSocket server protocol that enforces HTTP Basic Auth.

  realm: str = ''

    Scope of protection.

    If provided, it should contain only ASCII characters because the encoding of non-ASCII characters is undefined.

  username: str | None = None

    Username of the authenticated user.

  await check_credentials(username, password)

    Check whether credentials are authorized.

    This coroutine may be overridden in a subclass, for example to authenticate against a database or an external service.

    Parameters:

      - username (str) – HTTP Basic Auth username.

      - password (str) – HTTP Basic Auth password.

    Returns:

      `True` if the handshake should continue; `False` if it should fail with an HTTP 401 error.

    Return type:

      bool

## Broadcast

websockets.broadcast(websockets, message, raise_exceptions=False)

  Broadcast a message to several WebSocket connections.

  A string (`str`) is sent as a Text frame. A bytestring or bytes-like object (`bytes`, `bytearray`, or `memoryview`) is sent as a Binary frame.

  `broadcast()` pushes the message synchronously to all connections even if their write buffers are overflowing. There’s no backpressure.

  If you broadcast messages faster than a connection can handle them, messages will pile up in its write buffer until the connection times out. Keep `ping_interval` and `ping_timeout` low to prevent excessive memory usage from slow connections.

  Unlike `send()`, `broadcast()` doesn’t support sending fragmented messages. Indeed, fragmentation is useful for sending large messages without buffering them in memory, while `broadcast()` buffers one copy per connection as fast as possible.

  `broadcast()` skips connections that aren’t open in order to avoid errors on connections where the closing handshake is in progress.

  `broadcast()` ignores failures to write the message on some connections. It continues writing to other connections. On Python 3.11 and above, you may set `raise_exceptions` to `True` to record failures and raise all exceptions in a PEP 654 `ExceptionGroup`.

  Parameters:

    - websockets (Iterable[WebSocketCommonProtocol]) – WebSocket connections to which the message will be sent.

    - message (str | bytes) – Message to send.

    - raise_exceptions (bool) – Whether to raise an exception in case of failures.

  Raises:

    TypeError – If `message` doesn’t have a supported type.