Reference

Broker

Classes in this section are the API for building server/broker applications…

Broker

class messidge.broker.broker.Broker(keys: messidge.KeyPair, model, node_type, session_type, controller, *, base_port: int = 2020, identity_type=<class 'messidge.broker.identity.Identity'>, auth_type=<class 'messidge.broker.auth.Authenticate'>, account_confirm_type=<class 'messidge.broker.identity.AccountConfirmationServer'>, pre_run_callback=None, node_create_callback=None, node_destroy_callback=None, session_recovered_callback=None, session_destroy_callback=None, forwarding_insert_callback=None, forwarding_evict_callback=None)

The broker is the top level object for creating a server/broker.

__init__(keys: messidge.KeyPair, model, node_type, session_type, controller, *, base_port: int = 2020, identity_type=<class 'messidge.broker.identity.Identity'>, auth_type=<class 'messidge.broker.auth.Authenticate'>, account_confirm_type=<class 'messidge.broker.identity.AccountConfirmationServer'>, pre_run_callback=None, node_create_callback=None, node_destroy_callback=None, session_recovered_callback=None, session_destroy_callback=None, forwarding_insert_callback=None, forwarding_evict_callback=None)
Parameters:
  • keys – Server public/secret keys.
  • model – Model object (derived from ModelMinimal).
  • node_type – Class to construct node objects with (derived from NodeMinimal).
  • session_type – Class to construct session objects with (derived from SessionMinimal).
  • controller – Controller object (derived from ControllerMinimal).
  • base_port – TCP port to use plus the next one (so default is 2020 and 2021).
  • identity_type – Potentially custom class to construct an identity server (see identity.py).
  • auth_type – Class to authenticate with.
  • account_confirm_type – Class to use for confirming client accounts.
  • pre_run_callback – Fired last thing before the message loop starts. …signature ()
  • node_create_callback – Fired once a new node has been created. ..signature (pk)
  • node_destroy_callback – Fired last thing before a node is destroyed (was disconnected, say). …signature (pk)
  • session_recovered_callback – Fired with the new rid when a session reconnects. …signature (session, old_rid, new_rid)
  • session_destroy_callback – Fired last thing before a session is destroyed. …signature (rid)
  • forwarding_insert_callback – Called when a new entry is made into the forwarding map. …signature (key, value)
  • forwarding_evict_callback – Called when an entry is removed from the forwarding map. …signature (key, value)

The eviction of an entry from the map is not to be used as an indication that an object has been destroyed, it may be considerably after destruction or not at all.

run()

Call on the main thread, creates the background thread that actually does all the work.

stop()

Stop background threads. Must be called to allow garbage collection and for a clean exit.

send_cmd(rid, command: bytes, params: dict, *, bulk: bytes = b'', uuid: bytes = b'')

Send command to either a node or user

Parameters:
  • rid – the routing identifier to send the message to.
  • command – a byte string of the command to send.
  • params – A {‘key’: ‘value’} dictionary of parameters to send.
  • bulk – An optional piece of bulk data to transport.
  • uuid – A uuid to attach to this command (so it can reply).
set_next_rid()

Set the routing id for the next socket that connects.

disconnect_for_rid(rid)

Disconnect a client.

Parameters:rid – routing id for the client to disconnect.
messidge.broker.broker.cmd(required_params, *, needs_reply=False, node_only=False)

Create the internal structure describing a command

Parameters:
  • required_params – A list of parameters that must be included with the command.
  • needs_reply – The message needs to be replied to (and must have a uuid).
  • node_only – The message can only have originated from a node.

Model

class messidge.broker.bases.ModelMinimal

Stores the nodes and user sessions attached to this broker.

__init__()

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

resources(pk)

Overload this method to return a resource offer to a newly connected client.

Parameters:pk – the public key of the connecting user.

Identity

class messidge.broker.identity.Identity(directory='~')

A default provider of identity and configuration

__init__(directory='~')

Construct the identity database if it’s not there.

Parameters:directory – The directory in which to place the database (identity.sqlite3)
stop()

Stop the background (SqlCache) thread before closing

create_pending_user(email) → str

Registers the intention for someone to become a registered user

Parameters:email – email address of the user.
Returns:confirmation token to give to the user.
pending_users_for_token(token) → []

Return the pending users for the given token (may well be zero).

Parameters:token – the token a user was given in order to be able to confirm their account.
Returns:The list of pending users for that token.
register_user(pk_b64: str, email: str, config: str)

Registers a user as being valid.

Parameters:
  • pk_b64 – The user’s primary key - base64 encoded string.
  • email – The user’s email address.
  • config – A json description of any configuration to be associated with the user.
user_config_from_db(pk_b64: str) -> (<class 'str'>, <class 'str'>)

Returns the json configuration for a user.

Parameters:pk_b64 – The user’s primary key - base64 encoded string.
Returns:A tuple of email address and the json configuration.
raise_for_no_user(email: str)

Raises an error if this email address does not have an account.

Parameters:email – email address of the user.
register_node(pk_b64: str, config: str)

Writes a node’s configuration into the database.

Parameters:
  • pk_b64 – The node’s primary key - base64 encoded string.
  • config – A json description of any configuration to be associated with the node.
node_config_from_db(pk_b64: str) → str

Returns the json configuration of a node.

Parameters:pk_b64 – The node’s primary key - base64 encoded string.
Returns:The json configuration for the node.

Loop

The same message loop is used by both the broker and the client.

class messidge.loop.Loop(skt=None, message_type=<class 'messidge.client.message.Message'>, *, exit_on_exception=False)
__init__(skt=None, message_type=<class 'messidge.client.message.Message'>, *, exit_on_exception=False)

Initialise (but not start) a message loop.

Parameters:
  • skt – the (actually optional) ZMQ socket that connects to the location.
  • message_type – optionally set to use a non-default message class.
  • exit_on_exception – the message loop will exit if an exception makes it to the BaseException handler.
run()

Message loop. Runs single threaded (usually but not necessarily a background thread).

stop()

Causes the thread in ‘run’ to exit cleanly.

set_crypto_params(session_key: bytes)

Sets the cryptographic parameters for this connection.

Parameters:session_key – The session key for this connection.
register_exclusive(obj, handler, *, comment: str = '')

Registers an object and handler called to receive all events received on a ZMQ socket or file descriptor.

Parameters:
  • obj – the object that will receive events.
  • handler – the handler that will be called - passed the zmq socket or file handler (int).
  • comment – an optional comment for clarifying debug logs.
unregister_exclusive(obj)

Unregister an object as an exclusive handler.

Parameters:obj – The object to unregister.
register_commands(skt, obj, commands, *, comment: str = '')

Register command callbacks.

Parameters:
  • skt – ZMQ socket that will receive the events.
  • obj – The object that will handle the events.
  • commands – A dictionary of {b’command’: handler, …}.
  • comment – A string to help clarify debug logs.
register_reply(command_uuid: bytes, callback)

Hooking the reply to a command. Note that this will not override an exclusive socket.

Parameters:
  • command_uuid – the uuid of the command message from which we are expecting a reply.
  • callback – the callback that gets sent the reply message when it arrives.

Note that callback == None calls ‘return’ with the message

unregister_reply(command_uuid: bytes)

Removing the hook for a command reply.

Parameters:command_uuid – the uuid of the command message from which we are no longer expecting a reply.
register_on_idle(obj)

Register an object.method to be called whenever the message loop has idle time.

Parameters:obj – The object.method to be called - no additional parameters are passed.
unregister_on_idle(obj)

Unregister an object.method from the message loop’s idle time.

Parameters:obj – The object.method to be unregistered.
on_value_error(callback)

Register an alternative to raising exceptions for ValueError exceptions coming over the wire.

Parameters:callback – the callback to be fired, gets passed the exception and message that caused the exception.
static check_basic_properties(handler)

Helper utility to ensure messages fulfill certain basic criteria before they are passed to their handlers.

Parameters:
  • msg – the message to be tested.
  • handler – the handler (a return from client.connection.cmd) to be tested for.

Client

Classes in this section are the API for building client applications…

Connection

class messidge.client.connection.Connection(location: str = None, *, prefix='~/.messidge', exit_on_exception=False, reflect_value_errors=False, location_ip: str = None, keys: messidge.KeyPair = None, server_pk: str = None)

Connection onto Messidge broker.

__init__(location: str = None, *, prefix='~/.messidge', exit_on_exception=False, reflect_value_errors=False, location_ip: str = None, keys: messidge.KeyPair = None, server_pk: str = None)

Instantiate a connection.

Parameters:
  • location – The FQDN of the location to connect to.
  • prefix – Directory for the client keys and server public keys.
  • exit_on_exception – Causes the message loop to exit if there’s an uncaught exception.
  • reflect_value_errors – If True, raised ValueErrors will have their source messages replied to.
  • location_ip – An override for the DNS resolution of ‘location’. Useful for LAN and/or test connections.
  • keys – An override for the key pair in the ‘prefix’ directory.
  • server_pk – An override for the server public key in the ‘prefix’ directory.
start()

Start message loop - separate from __init__ so we get a chance to register_exclusive/register_commands

wait_until_complete()

Blocks until the message loop exits

disconnect()

Stop the message loop and disconnect - without this object cannot be garbage collected

send_skt()

Allocates (if necessary) a socket for the calling thread to send messages with.

destroy_send_skt()

Closes and removes the send_skt for the calling thread.

send_cmd(cmd: bytes, params=None, bulk: bytes = b'', uuid=b'', reply_callback=None)

Sends a command to the location, can route replies.

Parameters:
  • cmd – the command.
  • params – A {‘key’: ‘value’} dictionary of parameters or [‘list’].
  • bulk – An optional piece of bulk data to transport.
  • uuid – A uuid to attach to this command (so it can reply).
  • reply_callback – Callback to fire when the command receives a reply - gets passed the message.
send_blocking_cmd(cmd: bytes, params=None, bulk: bytes = b'', timeout: float = 240) → messidge.client.message.Message

Sends a command to the location and blocks waiting for a reply (which is returned). May raise ValueError exceptions.

Parameters:
  • cmd – the command.
  • params – A {‘key’: ‘value’} dictionary of parameters or [‘list’].
  • bulk – An optional piece of bulk data to transport.
  • timeout – In seconds.
Returns:

The reply message.

register_commands(obj, commands)

Register a list of commands to be handled by the loop.

Parameters:
  • obj – The object that will handle the commands.
  • commands – A dict of the form {b’command’: handler, …}.
register_connect_callback(callback)

Register a callback to be fired once the connection is complete.

Parameters:callback – the object.method to call - is passed the connection rid.
unregister_connect_callback(callback)

Unregister a callback to be fired once the connection is complete.

Parameters:callback – the object.method to cancel.
location_name() → str

Outside access to the name/address of this location.

Returns:The FQDN of the location as a string.
messidge.client.connection.cmd(required_params, *, needs_reply=False)

Create the internal structure describing a command

Parameters:
  • required_params – A list of parameters that must be included with the command.
  • needs_reply – The message needs to be replied to (and must have a uuid).