2. Messages

Turberfield IPC can take the objects used by your application and parcel them up for transmission. The messages get passed around with a header of routing and flow control information.

The format of messages on the wire is UTF-8 encoded RSON, which is a variant of JSON with some extra features.

The message module provides a mechanism by which you can register your own application classes for encapsulation in these messages.

2.1. Defined types

class turberfield.ipc.types.Address

Address(namespace, user, service, application)

A semantically hierarchical address for distributed networking.

namespace
Specifies the domain within which the address names are valid.
user
A unique name of trust within the network.
service
Identifies a currently operating instantiation of the network.
application
The name of the node endpoint.
class turberfield.ipc.message.Message

Message(header, payload)

An Message object holds both protocol control information (PCI) and application data.

header
PCI data necessary for the delivery of the message.
payload
Client data destined for the application endpoint.

2.2. Creating messages

turberfield.ipc.message.parcel(token, *args, dst=None, via=None, hMax=3)[source]
Parameters:
  • token – A DIF token. Just now the function turberfield.ipc.fsdb.token is the source of these.
  • args – Application objects to send in the message.
  • dst – An Address for the destination. If None, will be set to the source address (ie: a loopback message).
  • via – An Address to pass the message on to. If None, the most direct route is selected.
  • hMax – The maximum number of node hops permitted for this message.
Return type:

Message

2.3. Loading messages

turberfield.ipc.message.loads(data, **kwargs) → turberfield.ipc.message.Message[source]

Use this function to parse an RSON string as a message.

The optional types keyword allows you to specify which classes you expect to load. It’s a dictionary mapping the class to its fully-qualified name.

The helper function turberfield.utils.misc.type_dict() can make one of these for you:

types = turberfield.utils.misc.type_dict(
    turberfield.ipc.message.Alert,
    turberfield.ipc.message.Header
)
msg = turberfield.ipc.message.loads(data, types=types)

2.4. Registering custom objects

To customise the way your classes are loaded from a received message, you must register them with this generator:

and optionally with:

For example, here’s how the message module defines its own Alert class:

Alert = namedtuple("Alert", ["ts", "text"])

And this is how it customises the deserialising of these objects so that its ts attribute is itself loaded as Python object:

@load.register(Alert)
def load_alert(obj):
    yield obj._replace(
        ts=datetime.strptime(obj.ts, "%Y-%m-%d %H:%M:%S"),
    )

2.5. Other functions

turberfield.ipc.fsdb.token(connect: str, appName: str)[source]

Generates a token for use with the IPC framework.

Parameters:
  • connect – A connection string in the form of a URL. Just now this must be a file path to a user-writeable directory, eg: ‘file:///home/alice/.turberfield‘.
  • appName – The name of your application.
turberfield.ipc.message.dumps(obj, **kwargs)[source]

This generator takes a single object as its first argument. It dispatches by type to a handler which serialises the object as RSON.

turberfield.ipc.message.load(arg, **kwargs)[source]

This generator function recursively dispatches on the type of its first argument (initially an RSON string). It yields application-specific objects.

turberfield.ipc.message.replace(obj, seq)[source]

Finds in the sequence seq an existing object corresponding to the argument obj. Replaces such an item in the sequence with obj, and returns a 2-tuple of (existing, seq).

The equivalence of objects is application-specific.