Internals

Agent

The base of both Proxy and Server is the Agent. Each Agent has ZMQ sockets to communicate:

  • a REP socket to receive requests. This is the main endpoint of the Agent.
  • a PUB to emit notifications to other Agents.
  • one SUB to subscribe to notifications from other Agents.
  • one REQ per each Agent that it has to talk to (stored in self.connections)

The REP and PUB endpoint can be specified when the Agent is instantiated. If no endpoint is given, the sockets will bind to a random tcp port.

Protocol

Messages are multipart ZMQ messages. The conten

FRAME 0: Header (utf-8 encoded str)

Used for identification and filtering. It contains 3 string concatenated with a + (plus sign).

  1. The protocol version (currently PZC00).
  2. A unique identifier for the sender.
  3. A string specifying the topic of the message.

example: PZC00+urn:uuid:ad2d9eb0-c5f8-4bfb-a37d-6b7903b041f3+value_changed

FRAME 1: Serialization (utf-8 encoded str)

Indicates the serialization protocol used in FRAME 2. Current valid values are:

  • ‘pickle’: use the highest version available of the pickle format (default).
  • ‘pickleN’: use the N version of the pickle format.
  • ‘json’: use json format.

FRAME 2: Content (binary blob)

The actual content of the message.

FRAME 3: Message ID (utf-8 encoded str)

A unique identifier for the message.

example: urn:uuid:b711f2b8-277d-40df-a283-6269331db251

FRAME 4: Signature (bytes)

HMAC sha1 signature of FRAME 0:4 concatenated with Agent.hmac_key

By default, Agents use an empty signature key (no signature) and the pickle serializer. The simplest way to change these defaults is by using the environmental variables PZC_KEY and PZC_SER. You might want to change the serializer when running different agents on different versions of Python as not all pickle versions are supported in all python versions.

You can also change the protocol settings for an specific Agent by passing a Protocol object when the Agent is created.

Proxy-Server Protocol

Between the Proxy and the Server, the content of the message (Frame 2) is a tuple of three elements, being the first utf-8 str defining the subprotocol (‘PSMessage’). The second and third elements specify the action and the options for that action.