peng3dnet.ext.ping - One-off data retrieval protocol extension

The ping extension was designed to allow a client to check on various values the server provides without much effort. It allows the client to check on metrics such as latency and additional values able to be customized by the server.

This extension is named after the UNIX ping utility, though it can do much more than just check on availability and latency.

class peng3dnet.ext.ping.PingConnectionType(peer)

Connection type to be used by ping connections.

This connection type prevents any synchronization of the registry to allow clients only supporting a subset of the peng3dnet protocol to still ping a server.

Additonally, conventional processing of packets will be disabled by this connection type, making it uneccessary to register packets with the client or server.

getPingData(msg, cid=None)

Overridable method to create a ping response.

msg is the ping query, as received from the client.

cid is the ID of the client.

Called only on the server side.

init(cid)

Called whenever a new ping connection is established.

On the client, this calls PingableClientMixin._ping() and updates the connection state, while on the server only the connection state is updated.

receive(msg, pid, flags, cid)

Called whenever a packet is received via this connection type.

Handles any ping requests and pong answers and always returns True to skip any further processing.

send(msg, pid, cid)

Called whenever a packet is sent via this connection type.

class peng3dnet.ext.ping.PingableClientMixin

Mixin for Client classes enabling support for pinging the server.

Currently automatically adds the ping connection type.

setPingData(d)

Sets the data to add to any ping responses.

Repeated calls of this method will overwrite previous data.

wait_for_pong(timeout=None)

Waits up to timeout seconds for a ping response to arrive.

If a response has already been received, this method returns immediately.

If the ping was successful, the received message is returned.

class peng3dnet.ext.ping.PingableServerMixin

Mixin for Server classes enabling support for pinging the server.

Currently automatically adds the ping connection type.

getPingData(msg, cid)

Overrideable method called to extend the default dictionary returned upon a ping request.

May be overriden to add dynamic data like user count or similiar information.

msg is the original message as received from the client.

cid is the client ID that made this request.

pingdata = {}

Overrideable dictionary used to extend the default dictionary returned upon a ping request.

May be overriden to add static data like server name or similiar information.

peng3dnet.ext.ping.WRITEBACK = True

Constant allowing to configure if the received ping message should be transmitted back to the client.

If there should ever be any security concerns regarding that feature, this flag can simply be flipped.

peng3dnet.ext.ping.pingServer(peng=None, addr=None, cfg=None, data=None, clientcls=<class 'peng3dnet.ext.ping._PingClient'>, timeout=10.0)

Pings the specified server.

Internally, this creates a client that supports pinging and listens for any data received back.

peng may be optionally used to replace the argument of the same name to Client().

addr specifies the address of the server to ping.

cfg may be used to override the configuration for the client, e.g. SSL settings.

data is the data sent to the server. Note that the time key will be overridden for measuring the latency.

clientcls may be used to override the client class used.

timeout is maximum amount of time to wait for a response.

The data returned will be the data received from the server, except for additional information that has been added. Currently, the recvtime key contains the timestamp that the response was received and the delay key contains the total roundtrip time in seconds.