wsproto API¶
This document details the API of wsproto.
Semantic Versioning¶
wsproto follows semantic versioning for its public API. Please note that the guarantees of semantic versioning apply only to the API that is documented here. Simply because a method or data field is not prefaced by an underscore does not make it part of wsproto’s public API. Anything not documented here is subject to change at any time.
Handshake¶
-
class
wsproto.handshake.
H11Handshake
(connection_type)[source]¶ A Hanshake implementation for HTTP/1.1 connections.
-
connection
¶ Return the established connection.
This will either return the connection or raise a LocalProtocolError if the connection has not yet been established.
-
initiate_upgrade_connection
(headers, path)[source]¶ Initiate an upgrade connection.
This should be used if the request has already be received and parsed.
-
Events¶
-
class
wsproto.events.
Request
(**kwargs)[source]¶ The beginning of a Websocket connection, the HTTP Upgrade request
This event is fired when a SERVER connection receives a WebSocket handshake request (HTTP with upgrade header).
Fields:
-
extensions
(Union[List[Extension], List[str]])¶
-
extra_headers
¶ The additional request headers, excluding extensions, host, subprotocols, and version headers.
-
host
(str)¶ The hostname, or host header value.
-
subprotocols
¶ A list of subprotocols ordered by preference.
-
target
(str)¶ A list of the subprotocols proposed in the request, as a list of strings.
-
-
class
wsproto.events.
AcceptConnection
(**kwargs)[source]¶ The acceptance of a Websocket upgrade request.
This event is fired when a CLIENT receives an acceptance response from a server. It is also used to accept an upgrade request when acting as a SERVER.
Fields:
-
class
wsproto.events.
RejectConnection
(**kwargs)[source]¶ The rejection of a Websocket upgrade request, the HTTP response.
This event is fired when a CLIENT receives a rejection response from a server. It can be used to reject a request when sent from as SERVER. If has_body is False the headers must include a content-length or transfer encoding.
Fields:
-
headers
(List[Tuple[bytes, bytes]])¶ The headers to send with the response.
-
has_body
¶ This defaults to False, but set to True if there is a body. See also
RejectData
.
-
status_code
¶ The response status code.
-
-
class
wsproto.events.
RejectData
(**kwargs)[source]¶ The rejection HTTP response body.
Fields:
-
body_finished
¶ True if this is the final chunk of the body data.
-
data
(bytes)¶ The raw body data.
-
-
class
wsproto.events.
CloseConnection
(**kwargs)[source]¶ The end of a Websocket connection, represents a closure frame.
This event is fired after the connection is considered closed.
wsproto automatically emits a CLOSE frame when it receives one, to complete the close-handshake.
Fields:
-
code
¶ The integer close code to indicate why the connection has closed.
-
reason
¶ Additional reasoning for why the connection has closed.
-
-
class
wsproto.events.
Message
(**kwargs)[source]¶ The websocket data message.
Fields:
-
data
¶ The message data as byte string, can be decoded as UTF-8 for TEXT messages. This only represents a single chunk of data and not a full WebSocket message. You need to buffer and reassemble these chunks to get the full message.
-
frame_finished
¶ This has no semantic content, but is provided just in case some weird edge case user wants to be able to reconstruct the fragmentation pattern of the original stream.
-
message_finished
¶ True if this frame is the last one of this message, False if more frames are expected.
-
-
class
wsproto.events.
TextMessage
(**kwargs)[source]¶ This event is fired when a data frame with TEXT payload is received.
-
class
wsproto.events.
BytesMessage
(**kwargs)[source]¶ This event is fired when a data frame with BINARY payload is received.
Frame Protocol¶
-
class
wsproto.frame_protocol.
Opcode
[source]¶ RFC 6455, Section 5.2 - Base Framing Protocol
-
BINARY
= 2¶ Binary message
-
CLOSE
= 8¶ Close frame
-
CONTINUATION
= 0¶ Contiuation frame
-
PING
= 9¶ Ping frame
-
PONG
= 10¶ Pong frame
-
TEXT
= 1¶ Text message
-
-
class
wsproto.frame_protocol.
CloseReason
[source]¶ RFC 6455, Section 7.4.1 - Defined Status Codes
-
ABNORMAL_CLOSURE
= 1006¶ is a reserved value and MUST NOT be set as a status code in a Close control frame by an endpoint. It is designated for use in applications expecting a status code to indicate that the connection was closed abnormally, e.g., without sending or receiving a Close control frame.
-
GOING_AWAY
= 1001¶ indicates that an endpoint is “going away”, such as a server going down or a browser having navigated away from a page.
-
INTERNAL_ERROR
= 1011¶ indicates that a server is terminating the connection because it encountered an unexpected condition that prevented it from fulfilling the request.
-
INVALID_FRAME_PAYLOAD_DATA
= 1007¶ indicates that an endpoint is terminating the connection because it has received data within a message that was not consistent with the type of the message (e.g., non-UTF-8 [RFC3629] data within a text message).
-
MANDATORY_EXT
= 1010¶ indicates that an endpoint (client) is terminating the connection because it has expected the server to negotiate one or more extension, but the server didn’t return them in the response message of the WebSocket handshake. The list of extensions that are needed SHOULD appear in the /reason/ part of the Close frame. Note that this status code is not used by the server, because it can fail the WebSocket handshake instead.
-
MESSAGE_TOO_BIG
= 1009¶ indicates that an endpoint is terminating the connection because it has received a message that is too big for it to process.
-
NORMAL_CLOSURE
= 1000¶ indicates a normal closure, meaning that the purpose for which the connection was established has been fulfilled.
-
NO_STATUS_RCVD
= 1005¶ is a reserved value and MUST NOT be set as a status code in a Close control frame by an endpoint. It is designated for use in applications expecting a status code to indicate that no status code was actually present.
-
POLICY_VIOLATION
= 1008¶ indicates that an endpoint is terminating the connection because it has received a message that violates its policy. This is a generic status code that can be returned when there is no other more suitable status code (e.g., 1003 or 1009) or if there is a need to hide specific details about the policy.
-
PROTOCOL_ERROR
= 1002¶ indicates that an endpoint is terminating the connection due to a protocol error.
-
SERVICE_RESTART
= 1012¶ Server/service is restarting (not part of RFC6455)
-
TLS_HANDSHAKE_FAILED
= 1015¶ is a reserved value and MUST NOT be set as a status code in a Close control frame by an endpoint. It is designated for use in applications expecting a status code to indicate that the connection was closed due to a failure to perform a TLS handshake (e.g., the server certificate can’t be verified).
-
TRY_AGAIN_LATER
= 1013¶ Temporary server condition forced blocking client’s request (not part of RFC6455)
-
UNSUPPORTED_DATA
= 1003¶ indicates that an endpoint is terminating the connection because it has received a type of data it cannot accept (e.g., an endpoint that understands only text data MAY send this if it receives a binary message).
-
Extensions¶
-
wsproto.extensions.
SUPPORTED_EXTENSIONS
= {'permessage-deflate': <class 'wsproto.extensions.PerMessageDeflate'>}¶ SUPPORTED_EXTENSIONS maps all supported extension names to their class. This can be used to iterate all supported extensions of wsproto, instantiate new extensions based on their name, or check if a given extension is supported or not.
Exceptions¶
-
class
wsproto.utilities.
LocalProtocolError
[source]¶ Indicates an error due to local/programming errors.
This is raised when the connection is asked to do something that is either incompatible with the state or the websocket standard.
-
class
wsproto.utilities.
RemoteProtocolError
(message, event_hint=None)[source]¶ Indicates an error due to the remote’s actions.
This is raised when processing the bytes from the remote if the remote has sent data that is incompatible with the websocket standard.
-
event_hint
¶ This is a suggested wsproto Event to send to the client based on the error. It could be None if no hint is available.
-