evennia.server.portal package

Submodules

evennia.server.portal.amp module

The AMP (Asynchronous Message Protocol)-communication commands and constants used by Evennia.

This module acts as a central place for AMP-servers and -clients to get commands to use.

class evennia.server.portal.amp.AMPMultiConnectionProtocol(*args, **kwargs)

Bases: twisted.protocols.amp.AMP

AMP protocol that safely handle multiple connections to the same server without dropping old ones - new clients will receive all server returns (broadcast). Will also correctly handle erroneous HTTP requests on the port and return a HTTP error response.

__init__(*args, **kwargs)

Initialize protocol with some things that need to be in place already before connecting both on portal and server.

_commandDispatch = {b'FunctionCall': (<class 'evennia.server.portal.amp.FunctionCall'>, <function catch_traceback>), b'StartTLS': (<class 'twisted.protocols.amp.StartTLS'>, <function BinaryBoxProtocol._defaultStartTLSResponder>)}

broadcast(command, sessid, **kwargs)

Send data across the wire to all connections.

Parameters

• command (AMP Command) – A protocol send command.

• sessid (int) – A unique Session id.

Returns

A deferred with an errback.

Return type

deferred (deferred or None)

Notes

Data will be sent across the wire pickled as a tuple (sessid, kwargs).

connectionLost(reason)

We swallow connection errors here. The reason is that during a normal reload/shutdown there will almost always be cases where either the portal or server shuts down before a message has returned its (empty) return, triggering a connectionLost error that is irrelevant. If a true connection error happens, the portal will continuously try to reconnect, showing the problem that way.

connectionMade()

This is called when an AMP connection is (re-)established. AMP calls it on both sides.

dataReceived(data)

Handle non-AMP messages, such as HTTP communication.

data_in(packed_data)

Process incoming packed data.

Parameters

packed_data (bytes) – Pickled data.

Returns

Unpickled package

Return type

unpaced_data (any)

errback(e, info)

Error callback. Handles errors to avoid dropping connections on server tracebacks.

Parameters

• e (Failure) – Deferred error instance.

• info (str) – Error string.

makeConnection(transport)

Swallow connection log message here. Copied from original in the amp protocol.

receive_functioncall()

Helper decorator

send_FunctionCall(modulepath, functionname, *args, **kwargs)

Access method called by either process. This will call an arbitrary function on the other process (On Portal if calling from Server and vice versa).

Inputs:

modulepath (str) - python path to module holding function to call functionname (str) - name of function in given module *args, **kwargs will be used as arguments/keyword args for the

remote function call

Returns

A deferred that fires with the return value of the remote function call

class evennia.server.portal.amp.AdminPortal2Server(**kw)

Bases: twisted.protocols.amp.Command

Administration Portal -> Server

Sent when the portal needs to perform admin operations on the server, such as when a new session connects or resyncs

allErrors = {<class 'Exception'>: b'EXCEPTION'}

arguments = [(b'packed_data', <evennia.server.portal.amp.Compressed object>)]

commandName = b'AdminPortal2Server'

errors = {<class 'Exception'>: b'EXCEPTION'}

key = 'AdminPortal2Server'

response = []

reverseErrors = {b'EXCEPTION': <class 'Exception'>}

class evennia.server.portal.amp.AdminServer2Portal(**kw)

Bases: twisted.protocols.amp.Command

Administration Server -> Portal

Sent when the server needs to perform admin operations on the portal.

allErrors = {<class 'Exception'>: b'EXCEPTION'}

arguments = [(b'packed_data', <evennia.server.portal.amp.Compressed object>)]

commandName = b'AdminServer2Portal'

errors = {<class 'Exception'>: b'EXCEPTION'}

key = 'AdminServer2Portal'

response = []

reverseErrors = {b'EXCEPTION': <class 'Exception'>}

class evennia.server.portal.amp.Compressed(optional=False)

Bases: twisted.protocols.amp.String

This is a custom AMP command Argument that both handles too-long sends as well as uses zlib for compression across the wire. The batch-grouping of too-long sends is borrowed from the “mediumbox” recipy at twisted-hacks’s ~glyph/+junk/amphacks/mediumbox.

fromBox(name, strings, objects, proto)

Converts from box string representation to python. We read back too-long batched data and put it back together here.

fromString(inString)

Convert (decompress) from the string-representation on the wire to Python.

toBox(name, strings, objects, proto)

Convert from python object to string box representation. we break up too-long data snippets into multiple batches here.

toString(inObject)

Convert to send as a bytestring on the wire, with compression.

Note: In Py3 this is really a byte stream.

class evennia.server.portal.amp.FunctionCall(**kw)

Bases: twisted.protocols.amp.Command

Bidirectional Server <-> Portal

Sent when either process needs to call an arbitrary function in the other. This does not use the batch-send functionality.

allErrors = {<class 'Exception'>: b'EXCEPTION'}

arguments = [(b'module', <twisted.protocols.amp.String object>), (b'function', <twisted.protocols.amp.String object>), (b'args', <twisted.protocols.amp.String object>), (b'kwargs', <twisted.protocols.amp.String object>)]

commandName = b'FunctionCall'

errors = {<class 'Exception'>: b'EXCEPTION'}

key = 'FunctionCall'

response = [(b'result', <twisted.protocols.amp.String object>)]

reverseErrors = {b'EXCEPTION': <class 'Exception'>}

class evennia.server.portal.amp.MsgLauncher2Portal(**kw)

Bases: twisted.protocols.amp.Command

Message Launcher -> Portal

allErrors = {<class 'Exception'>: b'EXCEPTION'}

arguments = [(b'operation', <twisted.protocols.amp.String object>), (b'arguments', <twisted.protocols.amp.String object>)]

commandName = b'MsgLauncher2Portal'

errors = {<class 'Exception'>: b'EXCEPTION'}

key = 'MsgLauncher2Portal'

response = []

reverseErrors = {b'EXCEPTION': <class 'Exception'>}

class evennia.server.portal.amp.MsgPortal2Server(**kw)

Bases: twisted.protocols.amp.Command

Message Portal -> Server

allErrors = {<class 'Exception'>: b'EXCEPTION'}

arguments = [(b'packed_data', <evennia.server.portal.amp.Compressed object>)]

commandName = b'MsgPortal2Server'

errors = {<class 'Exception'>: b'EXCEPTION'}

key = b'MsgPortal2Server'

response = []

reverseErrors = {b'EXCEPTION': <class 'Exception'>}

class evennia.server.portal.amp.MsgServer2Portal(**kw)

Bases: twisted.protocols.amp.Command

Message Server -> Portal

allErrors = {<class 'Exception'>: b'EXCEPTION'}

arguments = [(b'packed_data', <evennia.server.portal.amp.Compressed object>)]

commandName = b'MsgServer2Portal'

errors = {<class 'Exception'>: b'EXCEPTION'}

key = 'MsgServer2Portal'

response = []

reverseErrors = {b'EXCEPTION': <class 'Exception'>}

class evennia.server.portal.amp.MsgStatus(**kw)

Bases: twisted.protocols.amp.Command

Check Status between AMP services

allErrors = {<class 'Exception'>: b'EXCEPTION'}

arguments = [(b'status', <twisted.protocols.amp.String object>)]

commandName = b'MsgStatus'

errors = {<class 'Exception'>: b'EXCEPTION'}

key = 'MsgStatus'

response = [(b'status', <twisted.protocols.amp.String object>)]

reverseErrors = {b'EXCEPTION': <class 'Exception'>}

evennia.server.portal.amp._get_logger()

Delay import of logger until absolutely necessary

evennia.server.portal.amp.dumps(data)

evennia.server.portal.amp.loads(data)

evennia.server.portal.amp_server module

The Evennia Portal service acts as an AMP-server, handling AMP communication to the AMP clients connecting to it (by default these are the Evennia Server and the evennia launcher).

class evennia.server.portal.amp_server.AMPServerFactory(portal)

Bases: twisted.internet.protocol.ServerFactory

This factory creates AMP Server connection. This acts as the ‘Portal’-side communication to the ‘Server’ process.

__init__(portal)

Initialize the factory. This is called as the Portal service starts.

Parameters

• portal (Portal) – The Evennia Portal service instance.

• protocol (Protocol) – The protocol the factory creates instances of.

buildProtocol(addr)

Start a new connection, and store it on the service object.

Parameters

addr (str) – Connection address. Not used.

Returns

The created protocol.

Return type

protocol (Protocol)

logPrefix()

How this is named in logs

noisy = False

class evennia.server.portal.amp_server.AMPServerProtocol(*args, **kwargs)

Bases: evennia.server.portal.amp.AMPMultiConnectionProtocol

Protocol subclass for the AMP-server run by the Portal.

_commandDispatch = {b'AdminServer2Portal': (<class 'evennia.server.portal.amp.AdminServer2Portal'>, <function catch_traceback>), b'FunctionCall': (<class 'evennia.server.portal.amp.FunctionCall'>, <function catch_traceback>), b'MsgLauncher2Portal': (<class 'evennia.server.portal.amp.MsgLauncher2Portal'>, <function catch_traceback>), b'MsgServer2Portal': (<class 'evennia.server.portal.amp.MsgServer2Portal'>, <function catch_traceback>), b'MsgStatus': (<class 'evennia.server.portal.amp.MsgStatus'>, <function catch_traceback>), b'StartTLS': (<class 'twisted.protocols.amp.StartTLS'>, <function BinaryBoxProtocol._defaultStartTLSResponder>)}

connectionLost(reason)

Set up a simple callback mechanism to let the amp-server wait for a connection to close.

data_to_server(command, sessid, **kwargs)

Send data across the wire to the Server.

Parameters

• command (AMP Command) – A protocol send command.

• sessid (int) – A unique Session id.

• kwargs (any) – Data to send. This will be pickled.

Returns

A deferred with an errback.

Return type

deferred (deferred or None)

Notes

Data will be sent across the wire pickled as a tuple (sessid, kwargs).

get_status()

Return status for the Evennia infrastructure.

Returns

The portal/server status and pids

(portal_live, server_live, portal_PID, server_PID).

Return type

status (tuple)

portal_receive_adminserver2portal()

Helper decorator

portal_receive_launcher2portal()

Helper decorator

portal_receive_server2portal()

Helper decorator

portal_receive_status()

Helper decorator

send_AdminPortal2Server(session, operation='', **kwargs)

Send Admin instructions from the Portal to the Server. Executed on the Portal.

Parameters

• session (Session) – Session.

• operation (char, optional) – Identifier for the server operation, as defined by the global variables in evennia/server/amp.py.

• data (str or dict, optional) – Data used in the administrative operation.

send_MsgPortal2Server(session, **kwargs)

Access method called by the Portal and executed on the Portal.

Parameters

• session (session) – Session

• kwargs (any, optional) – Optional data.

Returns

Asynchronous return.

Return type

deferred (Deferred)

send_Status2Launcher()

Send a status stanza to the launcher.

start_server(server_twistd_cmd)

(Re-)Launch the Evennia server.

Parameters

server_twisted_cmd (list) – The server start instruction to pass to POpen to start the server.

stop_server(mode='shutdown')

Shut down server in one or more modes.

Parameters

mode (str) – One of ‘shutdown’, ‘reload’ or ‘reset’.

wait_for_disconnect(callback, *args, **kwargs)

Add a callback for when this connection is lost.

Parameters

callback (callable) – Will be called with *args, **kwargs once this protocol is disconnected.

wait_for_server_connect(callback, *args, **kwargs)

Add a callback for when the Server is sure to have connected.

Parameters

callback (callable) – Will be called with *args, **kwargs once the Server handshake with Portal is complete.

evennia.server.portal.amp_server._is_windows()

evennia.server.portal.amp_server.getenv()

Get current environment and add PYTHONPATH.

Returns

Environment global dict.

Return type

env (dict)

evennia.server.portal.grapevine module

Grapevine network connection

This is an implementation of the Grapevine Websocket protocol v 1.0.0 as outlined here: https://grapevine.haus/docs

This will allow the linked game to transfer status as well as connects the grapevine client to in-game channels.

class evennia.server.portal.grapevine.GrapevineClient

Bases: autobahn.twisted.websocket.WebSocketClientProtocol, evennia.server.session.Session

Implements the grapevine client

__init__()

Initialize self. See help(type(self)) for accurate signature.

_send_json(data)

Send (json-) data to client.

Parameters

data (str) – Text to send.

at_login()

data_in(data, **kwargs)

Send data grapevine -> Evennia

Kwargs:

data (dict): Converted json data.

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.

Parameters

• payload (bytes) – The WebSocket message received.

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

onOpen()

Called when connection is established.

send_authenticate(*args, **kwargs)

Send grapevine authentication. This should be send immediately upon connection.

send_channel(text, channel, sender, *args, **kwargs)

Send text type Evennia -> grapevine

This is the channels/send message type

Use with session.msg(channel=(message, channel, sender))

send_default(*args, **kwargs)

Ignore other outputfuncs

send_heartbeat(*args, **kwargs)

Send heartbeat to remote grapevine server.

send_subscribe(channelname, *args, **kwargs)

Subscribe to new grapevine channel

Use with session.msg(subscribe=”channelname”)

send_unsubscribe(channelname, *args, **kwargs)

Un-subscribe to a grapevine channel

Use with session.msg(unsubscribe=”channelname”)

class evennia.server.portal.grapevine.RestartingWebsocketServerFactory(sessionhandler, *args, **kwargs)

Bases: autobahn.twisted.websocket.WebSocketClientFactory, twisted.internet.protocol.ReconnectingClientFactory

A variant of the websocket-factory that auto-reconnects.

__init__(sessionhandler, *args, **kwargs)

In addition to all arguments to the constructor of autobahn.websocket.interfaces.IWebSocketClientChannelFactory(), you can supply a reactor keyword argument to specify the Twisted reactor to be used.

buildProtocol(addr)

Build new instance of protocol

Parameters

addr (str) – Not used, using factory/settings data

clientConnectionFailed(connector, reason)

Called when Client failed to connect.

Parameters

• connector (Connection) – Represents the connection.

• reason (str) – The reason for the failure.

clientConnectionLost(connector, reason)

Called when Client loses connection.

Parameters

• connector (Connection) – Represents the connection.

• reason (str) – The reason for the failure.

factor = 1.5

initialDelay = 1

maxDelay = 60

reconnect()

Force a reconnection of the bot protocol. This requires de-registering the session and then reattaching a new one, otherwise you end up with an ever growing number of bot sessions.

start()

Connect protocol to remote server

startedConnecting(connector)

Tracks reconnections for debugging.

Parameters

connector (Connector) – Represents the connection.

evennia.server.portal.irc module

This connects to an IRC network/channel and launches an ‘bot’ onto it. The bot then pipes what is being said between the IRC channel and one or more Evennia channels.

class evennia.server.portal.irc.IRCBot

Bases: twisted.words.protocols.irc.IRCClient, evennia.server.session.Session

An IRC bot that tracks activity in a channel as well as sends text to it when prompted

action(user, channel, msg)

Called when an action is detected in channel.

Parameters

• user (str) – User name sending the message.

• channel (str) – Channel name seeing the message.

• msg (str) – The message arriving from channel.

at_login()

channel = None

data_in(text=None, **kwargs)

Data IRC -> Server.

Kwargs:

text (str): Ingoing text. kwargs (any): Other data from protocol.

disconnect(reason='')

Called by sessionhandler to disconnect this protocol.

Parameters

reason (str) – Motivation for the disconnect.

factory = None

get_nicklist()

Retrieve name list from the channel. The return is handled by the catch methods below.

irc_RPL_ENDOFNAMES(prefix, params)

Called when the nicklist has finished being returned.

irc_RPL_NAMREPLY(prefix, params)

“Handles IRC NAME request returns (nicklist)

lineRate = 1

logger = None

nickname = None

pong(user, time)

Called with the return timing from a PING.

Parameters

• user (str) – Name of user

• time (float) – Ping time in secs.

privmsg(user, channel, msg)

Called when the connected channel receives a message.

Parameters

• user (str) – User name sending the message.

• channel (str) – Channel name seeing the message.

• msg (str) – The message arriving from channel.

send_channel(*args, **kwargs)

Send channel text to IRC channel (visible to all). Note that we don’t handle the “text” send (it’s rerouted to send_default which does nothing) - this is because the IRC bot is a normal session and would otherwise report anything that happens to it to the IRC channel (such as it seeing server reload messages).

Parameters

text (str) – Outgoing text

send_default(*args, **kwargs)

Ignore other types of sends.

send_ping(*args, **kwargs)

Send a ping. The return (handled by self.pong) will be sent back as a message of type ‘ping’.

send_privmsg(*args, **kwargs)

Send message only to specific user.

Parameters

text (str) – Outgoing text.

Kwargs:

user (str): the nick to send

privately to.

send_reconnect(*args, **kwargs)

The server instructs us to rebuild the connection by force, probably because the client silently lost connection.

send_request_nicklist(*args, **kwargs)

Send a request for the channel nicklist. The return (handled by self.irc_RPL_ENDOFNAMES) will be sent back as a message with type `nicklist’.

signedOn()

This is called when we successfully connect to the network. We make sure to now register with the game as a full session.

sourceURL = 'http://code.evennia.com'

class evennia.server.portal.irc.IRCBotFactory(sessionhandler, uid=None, botname=None, channel=None, network=None, port=None, ssl=None)

Bases: twisted.internet.protocol.ReconnectingClientFactory

Creates instances of IRCBot, connecting with a staggered increase in delay

__init__(sessionhandler, uid=None, botname=None, channel=None, network=None, port=None, ssl=None)

Storing some important protocol properties.

Parameters

sessionhandler (SessionHandler) – Reference to the main Sessionhandler.

Kwargs:

uid (int): Bot user id. botname (str): Bot name (seen in IRC channel). channel (str): IRC channel to connect to. network (str): Network address to connect to. port (str): Port of the network. ssl (bool): Indicates SSL connection.

buildProtocol(addr)

Build the protocol and assign it some properties.

Parameters

addr (str) – Not used; using factory data.

clientConnectionFailed(connector, reason)

Called when Client failed to connect.

Parameters

• connector (Connection) – Represents the connection.

• reason (str) – The reason for the failure.

clientConnectionLost(connector, reason)

Called when Client loses connection.

Parameters

• connector (Connection) – Represents the connection.

• reason (str) – The reason for the failure.

factor = 1.5

initialDelay = 1

maxDelay = 60

reconnect()

Force a reconnection of the bot protocol. This requires de-registering the session and then reattaching a new one, otherwise you end up with an ever growing number of bot sessions.

start()

Connect session to sessionhandler.

startedConnecting(connector)

Tracks reconnections for debugging.

Parameters

connector (Connector) – Represents the connection.

evennia.server.portal.irc.parse_ansi_to_irc(string)

Parse |-type syntax and replace with IRC color markers

Parameters

string (str) – String to parse for ANSI colors.

Returns

String with replaced ANSI colors.

Return type

parsed_string (str)

evennia.server.portal.irc.parse_irc_to_ansi(string)

Parse IRC mIRC color syntax and replace with Evennia ANSI color markers

Parameters

string (str) – String to parse for IRC colors.

Returns

String with replaced IRC colors.

Return type

parsed_string (str)

evennia.server.portal.mccp module

MCCP - Mud Client Compression Protocol

This implements the MCCP v2 telnet protocol as per http://tintin.sourceforge.net/mccp/. MCCP allows for the server to compress data when sending to supporting clients, reducing bandwidth by 70-90%.. The compression is done using Python’s builtin zlib library. If the client doesn’t support MCCP, server sends uncompressed as normal. Note: On modern hardware you are not likely to notice the effect of MCCP unless you have extremely heavy traffic or sits on a terribly slow connection.

This protocol is implemented by the telnet protocol importing mccp_compress and calling it from its write methods.

class evennia.server.portal.mccp.Mccp(protocol)

Bases: object

Implements the MCCP protocol. Add this to a variable on the telnet protocol to set it up.

__init__(protocol)

initialize MCCP by storing protocol on ourselves and calling the client to see if it supports MCCP. Sets callbacks to start zlib compression in that case.

Parameters

protocol (Protocol) – The active protocol instance.

do_mccp(option)

The client supports MCCP. Set things up by creating a zlib compression stream.

Parameters

option (Option) – Option dict (not used).

no_mccp(option)

Called if client doesn’t support mccp or chooses to turn it off.

Parameters

option (Option) – Option dict (not used).

evennia.server.portal.mccp.mccp_compress(protocol, data)

Handles zlib compression, if applicable.

Parameters

data (str) – Incoming data to compress.

Returns

Zlib-compressed data.

Return type

stream (binary)

evennia.server.portal.mssp module

MSSP - Mud Server Status Protocol

This implements the MSSP telnet protocol as per http://tintin.sourceforge.net/mssp/. MSSP allows web portals and listings to have their crawlers find the mud and automatically extract relevant information about it, such as genre, how many active players and so on.

class evennia.server.portal.mssp.Mssp(protocol)

Bases: object

Implements the MSSP protocol. Add this to a variable on the telnet protocol to set it up.

__init__(protocol)

initialize MSSP by storing protocol on ourselves and calling the client to see if it supports MSSP.

Parameters

protocol (Protocol) – The active protocol instance.

do_mssp(option)

Negotiate all the information.

Parameters

option (Option) – Not used.

get_player_count()

Get number of logged-in players.

Returns

The number of players in the MUD.

Return type

count (int)

get_uptime()

Get how long the portal has been online (reloads are not counted).

Returns

Number of seconds of uptime.

Return type

uptime (int)

no_mssp(option)

Called when mssp is not requested. This is the normal operation.

Parameters

option (Option) – Not used.

evennia.server.portal.mxp module

MXP - Mud eXtension Protocol.

Partial implementation of the MXP protocol. The MXP protocol allows more advanced formatting options for telnet clients that supports it (mudlet, zmud, mushclient are a few)

This only implements the SEND tag.

More information can be found on the following links: http://www.zuggsoft.com/zmud/mxp.htm http://www.mushclient.com/mushclient/mxp.htm http://www.gammon.com.au/mushclient/addingservermxp.htm

class evennia.server.portal.mxp.Mxp(protocol)

Bases: object

Implements the MXP protocol.

__init__(protocol)

Initializes the protocol by checking if the client supports it.

Parameters

protocol (Protocol) – The active protocol instance.

do_mxp(option)

Called when the Client reports to support MXP.

Parameters

option (Option) – Not used.

no_mxp(option)

Called when the Client reports to not support MXP.

Parameters

option (Option) – Not used.

evennia.server.portal.mxp.mxp_parse(text)

Replaces links to the correct format for MXP.

Parameters

text (str) – The text to parse.

Returns

The parsed text.

Return type

parsed (str)

evennia.server.portal.naws module

NAWS - Negotiate About Window Size

This implements the NAWS telnet option as per https://www.ietf.org/rfc/rfc1073.txt

NAWS allows telnet clients to report their current window size to the client and update it when the size changes

class evennia.server.portal.naws.Naws(protocol)

Bases: object

Implements the NAWS protocol. Add this to a variable on the telnet protocol to set it up.

__init__(protocol)

initialize NAWS by storing protocol on ourselves and calling the client to see if it supports NAWS.

Parameters

protocol (Protocol) – The active protocol instance.

do_naws(option)

Client wants to negotiate all the NAWS information.

Parameters

option (Option) – Not used.

negotiate_sizes(options)

Step through the NAWS handshake.

Parameters

option (list) – The incoming NAWS options.

no_naws(option)

Called when client is not reporting NAWS. This is the normal operation.

Parameters

option (Option) – Not used.

evennia.server.portal.portal module

This module implements the main Evennia server process, the core of the game engine.

This module should be started with the ‘twistd’ executable since it sets up all the networking features. (this is done automatically by game/evennia.py).

class evennia.server.portal.portal.Portal(application)

Bases: object

The main Portal server handler. This object sets up the database and tracks and interlinks all the twisted network services that make up Portal.

__init__(application)

Setup the server.

Parameters

application (Application) – An instantiated Twisted application

_get_backup_server_twistd_cmd()

For interactive Portal mode there is no way to get the server cmdline from the launcher, so we need to guess it here (it’s very likely to not change)

Returns

An instruction for starting the server, to pass to Popen.

Return type

server_twistd_cmd (list)

get_info_dict()

Return the Portal info, for display.

shutdown(_reactor_stopping=False, _stop_server=False)

Shuts down the server from inside it.

Parameters

• _reactor_stopping (bool, optional) – This is set if server is already in the process of shutting down; in this case we don’t need to stop it again.

• _stop_server (bool, optional) – Only used in portal-interactive mode; makes sure to stop the Server cleanly.

Note that restarting (regardless of the setting) will not work if the Portal is currently running in daemon mode. In that case it always needs to be restarted manually.

class evennia.server.portal.portal.Websocket(*args, **kwargs)

Bases: autobahn.twisted.websocket.WebSocketServerFactory

Only here for better naming in logs

evennia.server.portal.portalsessionhandler module

Sessionhandler for portal sessions

class evennia.server.portal.portalsessionhandler.PortalSessionHandler(*args, **kwargs)

Bases: evennia.server.sessionhandler.SessionHandler

This object holds the sessions connected to the portal at any time. It is synced with the server’s equivalent SessionHandler over the AMP connection.

Sessions register with the handler using the connect() method. This will assign a new unique sessionid to the session and send that sessid to the server using the AMP connection.

__init__(*args, **kwargs)

Init the handler

announce_all(message)

Send message to all connected sessions.

Parameters

message (str) – Message to relay.

Notes

This will create an on-the fly text-type send command.

at_server_connection()

Called when the Portal establishes connection with the Server. At this point, the AMP connection is already established.

connect(session)

Called by protocol at first connect. This adds a not-yet authenticated session using an ever-increasing counter for sessid.

Parameters

session (PortalSession) – The Session connecting.

Notes

We implement a throttling mechanism here to limit the speed at which new connections are accepted - this is both a stop against DoS attacks as well as helps using the Dummyrunner tester with a large number of connector dummies.

count_loggedin(include_unloggedin=False)

Count loggedin connections, alternatively count all connections.

Parameters

• include_unloggedin (bool) – Also count sessions that have

• yet authenticated. (not) –

Returns

Number of sessions.

Return type

count (int)

data_in(session, **kwargs)

Called by portal sessions for relaying data coming in from the protocol to the server.

Parameters

session (PortalSession) – Session receiving data.

Kwargs:

kwargs (any): Other data from protocol.

Notes

Data is serialized before passed on.

data_out(session, **kwargs)

Called by server for having the portal relay messages and data to the correct session protocol.

Parameters

session (Session) – Session sending data.

Kwargs:

kwargs (any): Each key is a command instruction to the protocol on the form key = [[args],{kwargs}]. This will call a method send_<key> on the protocol. If no such method exixts, it sends the data to a method send_default.

disconnect(session)

Called from portal when the connection is closed from the portal side.

Parameters

• session (PortalSession) – Session to disconnect.

• delete (bool, optional) – Delete the session from the handler. Only time to not do this is when this is called from a loop, such as from self.disconnect_all().

disconnect_all()

Disconnect all sessions, informing the Server.

generate_sessid()

Simply generates a sessid that’s guaranteed to be unique for this Portal run.

Returns

sessid

server_connect(protocol_path='', config={})

Called by server to force the initialization of a new protocol instance. Server wants this instance to get a unique sessid and to be connected back as normal. This is used to initiate irc/rss etc connections.

Parameters

• protocol_path (st) – Full python path to the class factory for the protocol used, eg ‘evennia.server.portal.irc.IRCClientFactory’

• config (dict) – Dictionary of configuration options, fed as **kwarg to protocol class’ __init__ method.

Raises

RuntimeError – If The correct factory class is not found.

Notes

The called protocol class must have a method start() that calls the portalsession.connect() as a normal protocol.

server_disconnect(session, reason='')

Called by server to force a disconnect by sessid.

Parameters

• session (portalsession) – Session to disconnect.

• reason (str, optional) – Motivation for disconnect.

server_disconnect_all(reason='')

Called by server when forcing a clean disconnect for everyone.

Parameters

reason (str, optional) – Motivation for disconnect.

server_logged_in(session, data)

The server tells us that the session has been authenticated. Update it. Called by the Server.

Parameters

• session (Session) – Session logging in.

• data (dict) – The session sync data.

server_session_sync(serversessions, clean=True)

Server wants to save data to the portal, maybe because it’s about to shut down. We don’t overwrite any sessions here, just update them in-place.

Parameters

• serversessions (dict) –

  This is a dictionary

  {sessid:{property:value},…} describing the properties to sync on all sessions.

• clean (bool) – If True, remove any Portal sessions that are not included in serversessions.

sessions_from_csessid(csessid)

Given a session id, retrieve the session (this is primarily intended to be called by web clients)

Parameters

csessid (int) – Session id.

Returns

The matching session, if found.

Return type

session (list)

sync(session)

Called by the protocol of an already connected session. This can be used to sync the session info in a delayed manner, such as when negotiation and handshakes are delayed.

Parameters

session (PortalSession) – Session to sync.

evennia.server.portal.portalsessionhandler._PORTAL_SESSION_HANDLER_CLASS

alias of evennia.server.portal.portalsessionhandler.PortalSessionHandler

evennia.server.portal.rss module

RSS parser for Evennia

This connects an RSS feed to an in-game Evennia channel, sending messages to the channel whenever the feed updates.

class evennia.server.portal.rss.RSSBotFactory(sessionhandler, uid=None, url=None, rate=None)

Bases: object

Initializes new bots.

__init__(sessionhandler, uid=None, url=None, rate=None)

Initialize the bot.

Parameters

• sessionhandler (PortalSessionHandler) – The main sessionhandler object.

• uid (int) – User id for the bot.

• url (str) – The RSS URL.

• rate (int) – How often for the RSS to request the latest RSS entries.

start()

Called by portalsessionhandler. Starts the bot.

class evennia.server.portal.rss.RSSReader(factory, url, rate)

Bases: evennia.server.session.Session

A simple RSS reader using the feedparser module.

__init__(factory, url, rate)

Initialize the reader.

Parameters

• factory (RSSFactory) – The protocol factory.

• url (str) – The RSS url.

• rate (int) – The seconds between RSS lookups.

_callback(new_entries, init)

Called when RSS returns.

Parameters

• new_entries (list) – List of new RSS entries since last.

• init (bool) – If this is a startup operation (at which point all entries are considered new).

_errback(fail)

Report error

data_in(text=None, **kwargs)

Data RSS -> Evennia.

Kwargs:

text (str): Incoming text kwargs (any): Options from protocol.

disconnect(reason=None)

Disconnect from feed.

Parameters

reason (str, optional) – Motivation for the disconnect.

get_new()

Returns list of new items.

update(init=False)

Request the latest version of feed.

Parameters

init (bool, optional) – If this is an initialization call or not (during init, all entries are conidered new).

Notes

This call is done in a separate thread to avoid blocking on slow connections.

evennia.server.portal.ssh module

This module implements the ssh (Secure SHell) protocol for encrypted connections.

This depends on a generic session module that implements the actual login procedure of the game, tracks sessions etc.

Using standard ssh client,

class evennia.server.portal.ssh.AccountDBPasswordChecker(factory)

Bases: object

Checks the django db for the correct credentials for username/password otherwise it returns the account or None which is useful for the Realm.

__init__(factory)

Initialize the factory.

Parameters

factory (SSHFactory) – Checker factory.

credentialInterfaces = (<InterfaceClass twisted.cred.credentials.IUsernamePassword>,)

noisy = False

requestAvatarId(c)

Generic credentials.

class evennia.server.portal.ssh.ExtraInfoAuthServer

Bases: twisted.conch.ssh.userauth.SSHUserAuthServer

auth_password(packet)

Password authentication.

Used mostly for setting up the transport so we can query username and password later.

Parameters

packet (Packet) – Auth packet.

noisy = False

class evennia.server.portal.ssh.PassAvatarIdTerminalRealm(transportFactory=None)

Bases: twisted.conch.manhole_ssh.TerminalRealm

Returns an avatar that passes the avatarId through to the protocol. This is probably not the best way to do it.

_getAvatar(avatarId)

noisy = False

class evennia.server.portal.ssh.SSHServerFactory

Bases: twisted.internet.protocol.ServerFactory

This is only to name this better in logs

logPrefix()

Describe this factory for log messages.

noisy = False

class evennia.server.portal.ssh.SshProtocol(starttuple)

Bases: twisted.conch.manhole.Manhole, evennia.server.session.Session

Each account connecting over ssh gets this protocol assigned to them. All communication between game and account goes through here.

__init__(starttuple)

For setting up the account. If account is not None then we’ll login automatically.

Parameters

starttuple (tuple) – A (account, factory) tuple.

at_login()

Called when this session gets authenticated by the server.

connectionLost(reason=None)

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

Parameters

reason (str) – Motivation for loosing connection.

connectionMade()

This is called when the connection is first established.

data_out(**kwargs)

Data Evennia -> User

Kwargs:

kwargs (any): Options to the protocol.

disconnect(reason='Connection closed. Goodbye for now.')

Disconnect from server.

Parameters

reason (str) – Motivation for disconnect.

getClientAddress()

Get client address.

Returns

The client’s address and port in

a tuple. For example (‘127.0.0.1’, 41917).

Return type

address_and_port (tuple)

handle_EOF()

Handles EOF generally used to exit.

handle_FF()

Handle a ‘form feed’ byte - generally used to request a screen refresh/redraw.

handle_INT()

Handle ^C as an interrupt keystroke by resetting the current input variables to their initial state.

handle_QUIT()

Quit, end, and lose the connection.

lineReceived(string)

Communication User -> Evennia. Any line return indicates a command for the purpose of the MUD. So we take the user input and pass it on to the game engine.

Parameters

string (str) – Input text.

noisy = False

sendLine(string)

Communication Evennia -> User. Any string sent should already have been properly formatted and processed before reaching this point.

Parameters

string (str) – Output text.

send_default(*args, **kwargs)

send_prompt(*args, **kwargs)

send_text(*args, **kwargs)

Send text data. This is an in-band telnet operation.

Parameters

text (str) – The first argument is always the text string to send. No other arguments are considered.

Kwargs:

options (dict): Send-option flags

• mxp: Enforce MXP link support.

• ansi: Enforce no ANSI colors.

• xterm256: Enforce xterm256 colors, regardless of TTYPE setting.

• nocolor: Strip all colors.

• raw: Pass string through without any ansi processing

  (i.e. include Evennia ansi markers but do not convert them into ansi tokens)

• echo: Turn on/off line echo on the client. Turn

  off line echo for client, for example for password. Note that it must be actively turned back on again!

terminalSize(width, height)

Initialize the terminal and connect to the new session.

Parameters

• width (int) – Width of terminal.

• height (int) – Height of terminal.

class evennia.server.portal.ssh.TerminalSessionTransport_getPeer(proto, chainedProtocol, avatar, width, height)

Bases: object

Taken from twisted’s TerminalSessionTransport which doesn’t provide getPeer to the transport. This one does.

__init__(proto, chainedProtocol, avatar, width, height)

Initialize self. See help(type(self)) for accurate signature.

noisy = False

evennia.server.portal.ssh.getKeyPair(pubkeyfile, privkeyfile)

This function looks for RSA keypair files in the current directory. If they do not exist, the keypair is created.

evennia.server.portal.ssh.makeFactory(configdict)

Creates the ssh server factory.

evennia.server.portal.ssl module

This is a simple context factory for auto-creating SSL keys and certificates.

class evennia.server.portal.ssl.SSLProtocol(*args, **kwargs)

Bases: evennia.server.portal.telnet.TelnetProtocol

Communication is the same as telnet, except data transfer is done with encryption.

__init__(*args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

evennia.server.portal.ssl.getSSLContext()

This is called by the portal when creating the SSL context server-side.

Returns

A key and certificate that is either

existing previously or or created on the fly.

Return type

ssl_context (tuple)

evennia.server.portal.ssl.verify_SSL_key_and_cert(keyfile, certfile)

This function looks for RSA key and certificate in the current directory. If files ssl.key and ssl.cert does not exist, they are created.

evennia.server.portal.suppress_ga module

SUPPRESS-GO-AHEAD

This supports suppressing or activating Evennia the GO-AHEAD telnet operation after every server reply. If the client sends no explicit DONT SUPRESS GO-AHEAD, Evennia will default to supressing it since many clients will fail to use it and has no knowledge of this standard.

It is set as the NOGOAHEAD protocol_flag option.

http://www.faqs.org/rfcs/rfc858.html

class evennia.server.portal.suppress_ga.SuppressGA(protocol)

Bases: object

Implements the SUPRESS-GO-AHEAD protocol. Add this to a variable on the telnet protocol to set it up.

__init__(protocol)

Initialize suppression of GO-AHEADs.

Parameters

protocol (Protocol) – The active protocol instance.

will_suppress_ga(option)

Client will suppress GA

Parameters

option (Option) – Not used.

wont_suppress_ga(option)

Called when client requests to not suppress GA.

Parameters

option (Option) – Not used.

evennia.server.portal.telnet module

This module implements the telnet protocol.

This depends on a generic session module that implements the actual login procedure of the game, tracks sessions etc.

class evennia.server.portal.telnet.TelnetProtocol(*args, **kwargs)

Bases: twisted.conch.telnet.Telnet, twisted.conch.telnet.StatefulTelnetProtocol, evennia.server.session.Session

Each player connecting over telnet (ie using most traditional mud clients) gets a telnet protocol instance assigned to them. All communication between game and player goes through here.

__init__(*args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

_send_nop_keepalive()

Send NOP keepalive unless flag is set

_wont_linemode(*args)

Client refuses do(linemode). This is common for MUD-specific clients, but we must ask for the sake of raw telnet. We ignore this error.

_write(data)

hook overloading the one used in plain telnet

applicationDataReceived(data)

Telnet method called when non-telnet-command data is coming in over the telnet connection. We pass it on to the game engine directly.

Parameters

data (str) – Incoming data.

at_login()

Called when this session gets authenticated by the server.

connectionLost(reason)

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

Parameters

reason (str) – Motivation for losing connection.

connectionMade()

This is called when the connection is first established.

dataReceived(data)

Unused by default, but a good place to put debug printouts of incoming data.

data_in(**kwargs)

Data User -> Evennia

Kwargs:

kwargs (any): Options from the protocol.

data_out(**kwargs)

Data Evennia -> User

Kwargs:

kwargs (any): Options to the protocol

disableLocal(option)

Disable a given option locally.

Parameters

option (char) – The telnet option to disable locally.

disableRemote(option)

Signal a programming error by raising an exception.

L{enableRemote} must return true for the given value of C{option} in order for this method to be called. If a subclass of L{Telnet} overrides enableRemote to allow certain options to be enabled, it must also override disableRemote tto disable those options.

@raise NotImplementedError: Always raised.

disconnect(reason='')

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

Parameters

reason (str, optional) – Reason for disconnecting.

enableLocal(option)

Call to allow the activation of options for this protocol

Parameters

option (char) – The telnet option to enable locally.

Returns

If this option should be enabled.

Return type

enable (bool)

enableRemote(option)

This sets up the remote-activated options we allow for this protocol.

Parameters

option (char) – The telnet option to enable.

Returns

If this option should be enabled.

Return type

enable (bool)

handshake_done(timeout=False)

This is called by all telnet extensions once they are finished. When all have reported, a sync with the server is performed. The system will force-call this sync after a small time to handle clients that don’t reply to handshakes at all.

sendLine(line)

Hook overloading the one used by linereceiver.

Parameters

line (str) – Line to send.

send_default(cmdname, *args, **kwargs)

Send other oob data

send_prompt(*args, **kwargs)

Send a prompt - a text without a line end. See send_text for argument options.

send_text(*args, **kwargs)

Send text data. This is an in-band telnet operation.

Parameters

text (str) – The first argument is always the text string to send. No other arguments are considered.

Kwargs:

options (dict): Send-option flags

• mxp: Enforce MXP link support.

• ansi: Enforce no ANSI colors.

• xterm256: Enforce xterm256 colors, regardless of TTYPE.

• noxterm256: Enforce no xterm256 color support, regardless of TTYPE.

• nocolor: Strip all Color, regardless of ansi/xterm256 setting.

• raw: Pass string through without any ansi processing

  (i.e. include Evennia ansi markers but do not convert them into ansi tokens)

• echo: Turn on/off line echo on the client. Turn

  off line echo for client, for example for password. Note that it must be actively turned back on again!

toggle_nop_keepalive()

Allow to toggle the NOP keepalive for those sad clients that can’t even handle a NOP instruction. This is turned off by the protocol_flag NOPKEEPALIVE (settable e.g. by the default @option command).

class evennia.server.portal.telnet.TelnetServerFactory

Bases: twisted.internet.protocol.ServerFactory

This is only to name this better in logs

logPrefix()

Describe this factory for log messages.

noisy = False

evennia.server.portal.telnet_oob module

Telnet OOB (Out of band communication)

OOB protocols allow for asynchronous communication between Evennia and compliant telnet clients. The “text” type of send command will always be sent “in-band”, appearing in the client’s main text output. OOB commands, by contrast, can have many forms and it is up to the client how and if they are handled. Examples of OOB instructions could be to instruct the client to play sounds or to update a graphical health bar.

> Note that in Evennia’s Web client, all send commands are “OOB commands”, (including the “text” one), there is no equivalence to MSDP/GMCP for the webclient since it doesn’t need it.

This implements the following telnet OOB communication protocols: - MSDP (Mud Server Data Protocol), as per

http://tintin.sourceforge.net/msdp/

• GMCP (Generic Mud Communication Protocol) as per

  http://www.ironrealms.com/rapture/manual/files/FeatGMCP-txt.html#Generic_MUD_Communication_Protocol%28GMCP%29

Following the lead of KaVir’s protocol snippet, we first check if client supports MSDP and if not, we fallback to GMCP with a MSDP header where applicable.

class evennia.server.portal.telnet_oob.TelnetOOB(protocol)

Bases: object

Implements the MSDP and GMCP protocols.

__init__(protocol)

Initiates by storing the protocol on itself and trying to determine if the client supports MSDP.

Parameters

protocol (Protocol) – The active protocol.

data_out(cmdname, *args, **kwargs)

Return a MSDP- or GMCP-valid subnegotiation across the protocol.

Parameters

• cmdname (str) – OOB-command name.

• kwargs (args,) – Arguments to OOB command.

decode_gmcp(data)

Decodes incoming GMCP data on the form ‘varname <structure>’.

Parameters

data (str or list) – GMCP data.

Notes

Clients send data on the form “Module.Submodule.Cmdname <structure>”. We assume the structure is valid JSON.

The following is parsed into Evennia’s formal structure:

Core.Name -> [name, [], {}] Core.Name string -> [name, [string], {}] Core.Name [arg, arg,…] -> [name, [args], {}] Core.Name {key:arg, key:arg, …} -> [name, [], {kwargs}] Core.Name [[args], {kwargs}] -> [name, [args], {kwargs}]

decode_msdp(data)

Decodes incoming MSDP data.

Parameters

data (str or list) – MSDP data.

Notes

Clients should always send MSDP data on one of the following forms:

cmdname ‘’ -> [cmdname, [], {}] cmdname val -> [cmdname, [val], {}] cmdname array -> [cmdname, [array], {}] cmdname table -> [cmdname, [], {table}] cmdname array cmdname table -> [cmdname, [array], {table}]

Observe that all MSDP_VARS are used to identify cmdnames, so if there are multiple arrays with the same cmdname given, they will be merged into one argument array, same for tables. Different MSDP_VARS (outside tables) will be identified as separate cmdnames.

do_gmcp(option)

Called when client confirms that it can do MSDP or GMCP.

Parameters

option (Option) – Not used.

do_msdp(option)

Client reports that it supports msdp.

Parameters

option (Option) – Not used.

encode_gmcp(cmdname, *args, **kwargs)

Encode into GMCP messages.

Parameters

• cmdname (str) – GMCP OOB command name.

• kwargs (args,) – Arguments to OOB command.

Notes

GMCP messages will be outgoing on the following form (the non-JSON cmdname at the start is what IRE games use, supposedly, and what clients appear to have adopted). A cmdname without Package will end up in the Core package, while Core package names will be stripped on the Evennia side.

[cmd.name, [], {}] -> Cmd.Name [cmd.name, [arg], {}] -> Cmd.Name arg [cmd.name, [args],{}] -> Cmd.Name [args] [cmd.name, [], {kwargs}] -> Cmd.Name {kwargs} [cmdname, [args, {kwargs}] -> Core.Cmdname [[args],{kwargs}]

Notes

There are also a few default mappings between evennia outputcmds and GMCP:

client_options -> Core.Supports.Get get_inputfuncs -> Core.Commands.Get get_value -> Char.Value.Get repeat -> Char.Repeat.Update monitor -> Char.Monitor.Update

encode_msdp(cmdname, *args, **kwargs)

Encode into a valid MSDP command.

Parameters

• cmdname (str) – Name of send instruction.

• kwargs (args,) – Arguments to OOB command.

Notes

The output of this encoding will be MSDP structures on these forms:

[cmdname, [], {}] -> VAR cmdname VAL “” [cmdname, [arg], {}] -> VAR cmdname VAL arg [cmdname, [args],{}] -> VAR cmdname VAL ARRAYOPEN VAL arg VAL arg … ARRAYCLOSE [cmdname, [], {kwargs}] -> VAR cmdname VAL TABLEOPEN VAR key VAL val … TABLECLOSE [cmdname, [args], {kwargs}] -> VAR cmdname VAL ARRAYOPEN VAL arg VAL arg … ARRAYCLOSE

VAR cmdname VAL TABLEOPEN VAR key VAL val … TABLECLOSE

Further nesting is not supported, so if an array argument consists of an array (for example), that array will be json-converted to a string.

no_gmcp(option)

If this is reached, it means neither MSDP nor GMCP is supported.

Parameters

option (Option) – Not used.

no_msdp(option)

Client reports No msdp supported or wanted.

Parameters

option (Option) – Not used.

evennia.server.portal.telnet_ssl module

This allows for running the telnet communication over an encrypted SSL tunnel. To use it, requires a client supporting Telnet SSL.

The protocol will try to automatically create the private key and certificate on the server side when starting and will warn if this was not possible. These will appear as files ssl.key and ssl.cert in mygame/server/.

class evennia.server.portal.telnet_ssl.SSLProtocol(*args, **kwargs)

Bases: evennia.server.portal.telnet.TelnetProtocol

Communication is the same as telnet, except data transfer is done with encryption set up by the portal at start time.

__init__(*args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

evennia.server.portal.telnet_ssl.getSSLContext()

This is called by the portal when creating the SSL context server-side.

Returns

A key and certificate that is either

existing previously or created on the fly.

Return type

ssl_context (tuple)

evennia.server.portal.telnet_ssl.verify_or_create_SSL_key_and_cert(keyfile, certfile)

Verify or create new key/certificate files.

Parameters

• keyfile (str) – Path to ssl.key file.

• certfile (str) – Parth to ssl.cert file.

Notes

If files don’t already exist, they are created.

evennia.server.portal.tests module

class evennia.server.portal.tests.TestAMPServer(methodName='runTest')

Bases: twisted.trial._asynctest.TestCase

Test AMP communication

setUp()

Hook method for setting up the test fixture before exercising it.

test_amp_in()

test_amp_out()

test_large_msg()

Send message larger than AMP_MAXLEN - should be split into several

class evennia.server.portal.tests.TestIRC(methodName='runTest')

Bases: django.test.testcases.TestCase

test_bold()

test_colors()

test_identity()

Test that the composition of the function and its inverse gives the correct string.

test_italic()

test_plain_ansi()

Test that printable characters do not get mangled.

class evennia.server.portal.tests.TestTelnet(methodName='runTest')

Bases: twisted.trial._asynctest.TestCase

setUp()

Hook method for setting up the test fixture before exercising it.

test_mudlet_ttype()

class evennia.server.portal.tests.TestWebSocket(methodName='runTest')

Bases: evennia.utils.test_resources.EvenniaTest

setUp()

Sets up testing environment

tearDown()

Hook method for deconstructing the test fixture after testing it.

test_data_in()

test_data_out()

evennia.server.portal.ttype module

TTYPE (MTTS) - Mud Terminal Type Standard

This module implements the TTYPE telnet protocol as per http://tintin.sourceforge.net/mtts/. It allows the server to ask the client about its capabilities. If the client also supports TTYPE, it will return with information such as its name, if it supports colour etc. If the client does not support TTYPE, this will be ignored.

All data will be stored on the protocol’s protocol_flags dictionary, under the ‘TTYPE’ key.

class evennia.server.portal.ttype.Ttype(protocol)

Bases: object

Handles ttype negotiations. Called and initiated by the telnet protocol.

__init__(protocol)

Initialize ttype by storing protocol on ourselves and calling the client to see if it supporst ttype.

Parameters

protocol (Protocol) – The protocol instance.

Notes

The self.ttype_step indicates how far in the data retrieval we’ve gotten.

will_ttype(option)

Handles negotiation of the ttype protocol once the client has confirmed that it will respond with the ttype protocol.

Parameters

option (Option) – Not used.

Notes

The negotiation proceeds in several steps, each returning a certain piece of information about the client. All data is stored on protocol.protocol_flags under the TTYPE key.

wont_ttype(option)

Callback if ttype is not supported by client.

Parameters

option (Option) – Not used.

evennia.server.portal.webclient module

Webclient based on websockets.

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.

All data coming into the webclient 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: autobahn.twisted.websocket.WebSocketServerProtocol, evennia.server.session.Session

Implements the server-side of the Websocket connection.

__init__(*args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

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.

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.

get_client_session()

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

Returns

This is a django-specific internal representation

of the browser session.

Return type

csession (ClientSession)

nonce = None

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.

Parameters

• payload (bytes) – The WebSocket message received.

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

onOpen()

This is called when the WebSocket connection is fully established.

sendLine(line)

Send data to client.

Parameters

line (str) – Text to send.

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.

Kwargs:

options (dict): These are ignored for oob commands. Use command

arguments (which can hold dicts) to send instructions to the client instead.

send_prompt(*args, **kwargs)

send_text(*args, **kwargs)

Send text data. This will pre-process the text for color-replacement, conversion to html etc.

Parameters

text (str) – Text to send.

Kwargs:

options (dict): Options-dict with the following keys understood:

• raw (bool): No parsing at all (leave ansi-to-html markers unparsed).

• nocolor (bool): Clean out all color.

• screenreader (bool): Use Screenreader mode.

• send_prompt (bool): Send a prompt with parsed html

evennia.server.portal.webclient_ajax module

AJAX/COMET fallback webclient

The AJAX/COMET web client consists of two components running on twisted and django. They are both a part of the Evennia website url tree (so the testing website might be located on http://localhost:4001/, whereas the webclient can be found on http://localhost:4001/webclient.)

/webclient - this url is handled through django’s template

system and serves the html page for the client itself along with its javascript chat program.

/webclientdata - this url is called by the ajax chat using

POST requests (long-polling when necessary) The WebClient resource in this module will handle these requests and act as a gateway to sessions connected over the webclient.

class evennia.server.portal.webclient_ajax.AjaxWebClient

Bases: twisted.web.resource.Resource

An ajax/comet long-polling transport

__init__()

Initialize.

_keepalive()

Callback for checking the connection is still alive.

_responseFailed(failure, csessid, request)

callback if a request is lost/timed out

allowedMethods = ('POST',)

at_login()

Called when this session gets authenticated by the server.

client_disconnect(csessid)

Disconnect session with given csessid.

Parameters

csessid (int) – Session id.

get_client_sessid(request)

Helper to get the client session id out of the request.

Parameters

request (Request) – Incoming request object.

Returns

The client-session id.

Return type

csessid (int)

isLeaf = True

lineSend(csessid, data)

This adds the data to the buffer and/or sends it to the client as soon as possible.

Parameters

• csessid (int) – Session id.

• data (list) – A send structure [cmdname, [args], {kwargs}].

mode_close(request)

This is called by render_POST when the client is signalling that it is about to be closed.

Parameters

request (Request) – Incoming request.

mode_init(request)

This is called by render_POST when the client requests an init mode operation (at startup)

Parameters

request (Request) – Incoming request.

mode_input(request)

This is called by render_POST when the client is sending data to the server.

Parameters

request (Request) – Incoming request.

mode_keepalive(request)

This is called by render_POST when the client is replying to the keepalive.

mode_receive(request)

This is called by render_POST when the client is telling us that it is ready to receive data as soon as it is available. This is the basis of a long-polling (comet) mechanism: the server will wait to reply until data is available.

Parameters

request (Request) – Incoming request.

render_POST(request)

This function is what Twisted calls with POST requests coming in from the ajax client. The requests should be tagged with different modes depending on what needs to be done, such as initializing or sending/receving data through the request. It uses a long-polling mechanism to avoid sending data unless there is actual data available.

Parameters

request (Request) – Incoming request.

class evennia.server.portal.webclient_ajax.AjaxWebClientSession(*args, **kwargs)

Bases: evennia.server.session.Session

This represents a session running in an AjaxWebclient.

__init__(*args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

at_login()

data_in(**kwargs)

Data User -> Evennia

Kwargs:

kwargs (any): Incoming data.

data_out(**kwargs)

Data Evennia -> User

Kwargs:

kwargs (any): Options to the protocol

disconnect(reason='Server disconnected.')

Disconnect from server.

Parameters

reason (str) – Motivation for the disconnect.

get_client_session()

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

Returns

This is a django-specific internal representation

of the browser session.

Return type

csession (ClientSession)

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.

Kwargs:

options (dict): These are ignored for oob commands. Use command

arguments (which can hold dicts) to send instructions to the client instead.

send_prompt(*args, **kwargs)

send_text(*args, **kwargs)

Send text data. This will pre-process the text for color-replacement, conversion to html etc.

Parameters

text (str) – Text to send.

Kwargs:

options (dict): Options-dict with the following keys understood:

• raw (bool): No parsing at all (leave ansi-to-html markers unparsed).

• nocolor (bool): Remove all color.

• screenreader (bool): Use Screenreader mode.

• send_prompt (bool): Send a prompt with parsed html

class evennia.server.portal.webclient_ajax.LazyEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Bases: json.encoder.JSONEncoder

default(obj)

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return JSONEncoder.default(self, o)

evennia.server.portal.webclient_ajax.jsonify(obj)