evennia.server.portal.webclient

Webclient based on websockets with MUD Standards subprotocol support.

This implements a webclient with WebSockets (http://en.wikipedia.org/wiki/WebSocket) by use of the autobahn-python package’s implementation (https://github.com/crossbario/autobahn-python). It is used together with evennia/web/media/javascript/evennia_websocket_webclient.js.

Subprotocol Negotiation (RFC 6455 Sec-WebSocket-Protocol):

When a client connects, it may offer one or more WebSocket subprotocols via the Sec-WebSocket-Protocol header. This module negotiates the best match from the server’s supported list (configured via settings.WEBSOCKET_SUBPROTOCOLS) and selects the appropriate wire format codec for the connection’s lifetime.

Supported subprotocols (per https://mudstandards.org/websocket/):

• v1.evennia.com: Evennia’s legacy JSON array format

• json.mudstandards.org: MUD Standards JSON envelope format

• gmcp.mudstandards.org: GMCP over WebSocket

• terminal.mudstandards.org: Raw ANSI terminal over WebSocket

If no subprotocol is negotiated (legacy client with no header), the v1.evennia.com format is used as the default.

All data coming into the webclient via the v1.evennia.com format is in the form of valid JSON on the form

[“inputfunc_name”, [args], {kwarg}]

which represents an “inputfunc” to be called on the Evennia side with args, **kwargs. The most common inputfunc is “text”, which takes just the text input from the command line and interprets it as an Evennia Command: **[“text”, [“look”], {}]*

class evennia.server.portal.webclient.WebSocketClient(*args, **kwargs)

Bases: WebSocketServerProtocol, Session

Implements the server-side of the Websocket connection.

Supports multiple wire formats via RFC 6455 subprotocol negotiation. The wire format is selected during the WebSocket handshake in onConnect() and determines how all subsequent messages are encoded and decoded.

wire_format

The selected wire format codec for this connection. Set during onConnect().

Type:

WireFormat

nonce = 0

__init__(*args, **kwargs)

onConnect(request)

Called during the WebSocket opening handshake, before onOpen().

This is where we negotiate the WebSocket subprotocol. The client sends a list of subprotocols it supports via Sec-WebSocket-Protocol. We select the best match from our supported list.

Parameters:

request (ConnectionRequest) – The WebSocket connection request, containing request.protocols (list of offered subprotocols).

Returns:

str or None –

The selected subprotocol name to echo back in the

Sec-WebSocket-Protocol response header, or None if no subprotocol was negotiated (legacy client with no header, or client offered protocols that don’t match).

get_client_session()

Get the Client browser session (used for auto-login based on browser session)

Returns:

csession (ClientSession) –

This is a django-specific internal representation

of the browser session.

onOpen()

This is called when the WebSocket connection is fully established.

disconnect(reason=None)

Generic hook for the engine to call in order to disconnect this protocol.

Parameters:

reason (str or None) – Motivation for the disconnection.

onClose(wasClean, code=None, reason=None)

This is executed when the connection is lost for whatever reason. it can also be called directly, from the disconnect method.

Parameters:

• wasClean (bool) – **True** if the WebSocket was closed cleanly.

• code (int or None) – Close status as sent by the WebSocket peer.

• reason (str or None) – Close reason as sent by the WebSocket peer.

onMessage(payload, isBinary)

Callback fired when a complete WebSocket message was received.

Delegates to the active wire format’s decode_incoming() method to parse the message into kwargs for data_in().

Parameters:

• payload (bytes) – The WebSocket message received.

• isBinary (bool) – Flag indicating whether payload is binary or UTF-8 encoded text.

sendLine(line)

Send data to client.

Parameters:

line (str) – Text to send.

sendEncoded(data, is_binary=False)

Send pre-encoded data to the client.

This is used by wire formats that return raw bytes with a binary/text frame indicator.

Parameters:

• data (bytes) – The encoded data to send.

• is_binary (bool) – If True, send as a BINARY frame. If False, send as a TEXT frame.

at_login()

data_in(**kwargs)

Data User > Evennia.

Parameters:

• text (str) – Incoming text.

• kwargs (any) – Options from protocol.

Notes

At initilization, the client will send the special ‘csessid’ command to identify its browser session hash with the Evennia side.

The websocket client will also pass ‘websocket_close’ command to report that the client has been closed and that the session should be disconnected.

Both those commands are parsed and extracted already at this point.

send_text(*args, **kwargs)

Send text data. Delegates to the active wire format’s encode_text() method, which handles ANSI processing and framing. The exact output depends on the negotiated subprotocol (e.g., HTML for v1.evennia.com, raw ANSI for MUD Standards formats).

Parameters:

text (str) – Text to send.

Keyword Arguments:

options (dict) – Options-dict with the following keys understood: - raw (bool): No parsing at all (leave ansi markers unparsed). - nocolor (bool): Clean out all color. - screenreader (bool): Use Screenreader mode. - send_prompt (bool): Send as a prompt instead of regular text.

send_prompt(*args, **kwargs)

Send a prompt to the client.

Prompts are handled separately from regular text because some wire formats (e.g. json.mudstandards.org) send prompts as a distinct message type that the client can render differently.

Parameters:

*args – Prompt text as first arg.

Keyword Arguments:

options (dict) – Same options as send_text.

send_default(cmdname, *args, **kwargs)

Data Evennia -> User.

Parameters:

• cmdname (str) – The first argument will always be the oob cmd name.

• *args (any) – Remaining args will be arguments for cmd.

Keyword Arguments:

options (dict) – These are ignored for oob commands. Use command arguments (which can hold dicts) to send instructions to the client instead.