AMQP service

The AMQPService is responsible for connecting the agent to the AMQP bus, registers the required queues, listens for commands on that queues and dispatches incoming commands to the clacks.agent.command.CommandRegistry.

Queues

In order to use features like round robin and automatic routing of commands to agents that are capable of handling them, the AMQPService creates a queue structure that addresses these facts.

Queues are named after the configured domain - i.e. if you use the configured default domain, you’ll get org.clacks as the base dot separated string for the queues. The agent registers two core queues:

  • {domain}.command.core (i.e. org.clacks.command.core)

    This is a round robin queue that is shared by all agents joining the domain. The core queue must only handle commands that are provided by all agents.

  • {domain}.command.core.{nodename} (i.e. org.clacks.command.core.node1 if your node is named node1)

    This queue is a private queue that is only used by a specific agent. It is possible to direct a command to exactly the agent identified by nodename.

The same thing which is established for the command.core queues is done for queues registered by certain plugins. This ensures that commands are only delivered to nodes which provide that functionality by listening to these queues:

  • {domain}.command.{plugin} (i.e. org.clacks.command.goto)

    This is a round robin queue that is shared by all agents joining the domain. In the example above, all agents providing the goto plugin will share this queue.

  • {domain}.command.{plugin}.nodename (i.e. org.clacks.command.goto.node1 if your node is named node1)

    Like for the command.core queues, this queue is private for the current agent and makes it possible to direct a command to exactly the agent identified by nodename.

Note

To learn how to specify the plugin’s target queue, please read Plugins for more information.

Last but not least, the AMQPService binds to the queues mentioned above and dispatches command calls to the CommandRegistry.


class clacks.agent.amqp_service.AMQPService

Class to serve all available queues and commands to the AMQP broker. It makes use of a couple of configuration flags provided by the clacks configurations file [amqp] section:

Key Description
url AMQP URL to connect to the broker
id User name to connect with
key Password to connect with
command-worker Number of worker processes

Example:

[amqp]
url = amqps://amqp.intranet.gonicus.de:5671
id = node1
key = secret
commandReceived(ssn, message)

Process incoming commands, coming in with session and message information.

Parameter Description
ssn AMQP session object
message Received AMQP message

Incoming messages are coming from an clacks.common.components.amqp_proxy.AMQPServiceProxy which is providing a reply to queue as a return channel. The command result is written to that queue.

serve()

Start AMQP service for this clacks service provider.

stop()

Stop AMQP service for this clacks service provider.