Server (Sans-I/O)

class websockets.server.ServerProtocol(origins=None, extensions=None, subprotocols=None, state=State.CONNECTING, max_size=2**20, logger=None)

Sans-I/O implementation of a WebSocket server connection.

Parameters:

• origins (Optional[Sequence[Optional[Origin]]]) – acceptable values of the Origin header; include None in the list if the lack of an origin is acceptable. This is useful for defending against Cross-Site WebSocket Hijacking attacks.

• extensions (List[Extension]) – list of supported extensions, in order in which they should be tried.

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

• select_subprotocol (Optional[Callable[[ServerProtocol, Sequence[Subprotocol]], Optional[Subprotocol]]]) – Callback for selecting a subprotocol among those supported by the client and the server. It has the same signature as the select_subprotocol() method, including a ServerProtocol instance as first argument.

• state (State) – initial state of the WebSocket connection.

• max_size (Optional[int]) – maximum size of incoming messages in bytes; None disables the limit.

• logger (Logger | LoggerAdapter) – logger for this connection; defaults to logging.getLogger("websockets.client"); see the logging guide for details.

receive_data(data)

Receive data from the network.

After calling this method:

• You must call data_to_send() and send this data to the network.

• You should call events_received() and process resulting events.

Raises:

EOFError – if receive_eof() was called earlier.

receive_eof()

Receive the end of the data stream from the network.

After calling this method:

• You must call data_to_send() and send this data to the network; it will return [b""], signaling the end of the stream, or [].

• You aren’t expected to call events_received(); it won’t return any new events.

Raises:

EOFError – if receive_eof() was called earlier.

accept(request)

Create a handshake response to accept the connection.

If the connection cannot be established, the handshake response actually rejects the handshake.

You must send the handshake response with send_response().

You may modify it before sending it, for example to add HTTP headers.

Parameters:

request (Request) – WebSocket handshake request event received from the client.

Returns:

WebSocket handshake response event to send to the client.

Return type:

Response

select_subprotocol(subprotocols)

Pick a subprotocol among those offered by the client.

If several subprotocols are supported by both the client and the server, pick the first one in the list declared the server.

If the server doesn’t support any subprotocols, continue without a subprotocol, regardless of what the client offers.

If the server supports at least one subprotocol and the client doesn’t offer any, abort the handshake with an HTTP 400 error.

You provide a select_subprotocol argument to ServerProtocol to override this logic. For example, you could accept the connection even if client doesn’t offer a subprotocol, rather than reject it.

Here’s how to negotiate the chat subprotocol if the client supports it and continue without a subprotocol otherwise:

def select_subprotocol(protocol, subprotocols):
    if "chat" in subprotocols:
        return "chat"

Parameters:

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

Returns:

Selected subprotocol, if a common subprotocol was found.

None to continue without a subprotocol.

Return type:

Optional[Subprotocol]

Raises:

NegotiationError – custom implementations may raise this exception to abort the handshake with an HTTP 400 error.

reject(status, text)

Create a handshake response to reject the connection.

A short plain text response is the best fallback when failing to establish a WebSocket connection.

You must send the handshake response with send_response().

You can modify it before sending it, for example to alter HTTP headers.

Parameters:

• status (HTTPStatus | int) – HTTP status code.

• text (str) – HTTP response body; will be encoded to UTF-8.

Returns:

WebSocket handshake response event to send to the client.

Return type:

Response

send_response(response)

Send a handshake response to the client.

Parameters:

response (Response) – WebSocket handshake response event to send.

send_continuation(data, fin)

Send a Continuation frame.

Parameters:

• data (bytes) – payload containing the same kind of data as the initial frame.

• fin (bool) – FIN bit; set it to True if this is the last frame of a fragmented message and to False otherwise.

Raises:

ProtocolError – if a fragmented message isn’t in progress.

send_text(data, fin=True)

Send a Text frame.

Parameters:

• data (bytes) – payload containing text encoded with UTF-8.

• fin (bool) – FIN bit; set it to False if this is the first frame of a fragmented message.

Raises:

ProtocolError – if a fragmented message is in progress.

send_binary(data, fin=True)

Send a Binary frame.

Parameters:

• data (bytes) – payload containing arbitrary binary data.

• fin (bool) – FIN bit; set it to False if this is the first frame of a fragmented message.

Raises:

ProtocolError – if a fragmented message is in progress.

send_close(code=None, reason='')

Send a Close frame.

Parameters:

• code (int | None) – close code.

• reason (str) – close reason.

Raises:

ProtocolError – if a fragmented message is being sent, if the code isn’t valid, or if a reason is provided without a code

send_ping(data)

Send a Ping frame.

Parameters:

data (bytes) – payload containing arbitrary binary data.

send_pong(data)

Send a Pong frame.

Parameters:

data (bytes) – payload containing arbitrary binary data.

fail(code, reason='')

Fail the WebSocket connection.

Parameters:

• code (int) – close code

• reason (str) – close reason

Raises:

ProtocolError – if the code isn’t valid.

events_received()

Fetch events generated from data received from the network.

Call this method immediately after any of the receive_*() methods.

Process resulting events, likely by passing them to the application.

Returns:

Events read from the connection.

Return type:

List[Event]

data_to_send()

Obtain data to send to the network.

Call this method immediately after any of the receive_*(), send_*(), or fail() methods.

Write resulting data to the connection.

The empty bytestring SEND_EOF signals the end of the data stream. When you receive it, half-close the TCP connection.

Returns:

Data to write to the connection.

Return type:

List[bytes]

close_expected()

Tell if the TCP connection is expected to close soon.

Call this method immediately after any of the receive_*(), send_close(), or fail() methods.

If it returns True, schedule closing the TCP connection after a short timeout if the other side hasn’t already closed it.

Returns:

Whether the TCP connection is expected to close soon.

Return type:

bool

WebSocket protocol objects also provide these attributes:

id: uuid.UUID

Unique identifier of the connection. Useful in logs.

logger: LoggerLike

Logger for this connection.

property state: State

WebSocket connection state.

Defined in 4.1, 4.2, 7.1.3, and 7.1.4 of RFC 6455.

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

handshake_exc: Exception | None

Exception to raise if the opening handshake failed.

None if the opening handshake succeeded.

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

property close_code: int | None

WebSocket close code.

None if the connection isn’t closed yet.

property close_reason: str | None

WebSocket close reason.

None if the connection isn’t closed yet.

property close_exc: ConnectionClosed

Exception to raise when trying to interact with a closed connection.

Don’t raise this exception while the connection state is CLOSING; wait until it’s CLOSED.

Indeed, the exception includes the close code and reason, which are known only once the connection is closed.

Raises:

AssertionError – if the connection isn’t closed yet.