Command registry

The CommandRegistry is responsible for knowing what kind of commands are available for users. It works together with the clacks.common.components.registry.PluginRegistry and inspects all loaded plugins for methods marked with the clacks.common.components.command.Command() decorator. All available information like method path, command name, target queue, documentation and signature are recorded and are available for users via the clacks.agent.command.CommandRegistry.dispatch() method (or better with the several proxies) and the CLI.

Next to registering commands, the CommandRegistry is also responsible for sending and receiving a couple of important bus events:

Name Direction
NodeCapabilities send/receive
NodeAnnounce send/receive
NodeLeave receive
NodeStatus receive

All mentioned signals maintain an internal list of available nodes, their status and their capabilities - aka collection of supported methods and their signatures. This information is used to locate a willing node for methods that the receiving node is not able to process.

Note

Please take a look at the command index for a list of valid commands.


class clacks.agent.command.CommandRegistry

This class covers the registration and invocation of methods imported thru plugins.

call(func, *arg, **larg)

call can be used to internally call a registered method directly. There’s no access control happening with this method.

Parameter Description
func method to call
args ordinary argument list/dict

Return: return value from the method call

callNeedsQueue(func)

Checks if the provided method requires a queue parameter.

Parameter Description
func method name

Return: success or failure

callNeedsUser(func)

Checks if the provided method requires a user parameter.

Parameter Description
func method name

Return: success or failure

checkQueue(func, queue)

Checks if the provided method was sent to the correct queue.

Parameter Description
func method name
queue queue to compare to

Return: success or failure

dispatch(user, queue, func, *arg, **larg)

The dispatch method will try to call the specified function and checks for user and queue. Additionally, it carries the call to it’s really destination (function types, cumulative results) and does some sanity checks.

Handlers like JSONRPC or AMQP should use this function to dispatch the real calls.

Parameter Description
user the calling users name
queue the queue address where the call originated from
func method to call
args ordinary argument list/dict

Dispatch will...

  • ... forward unknown commands to nodes that are capable of processing them - ordered by load.
  • ... will take care about the modes NORMAL, FIRSTRESULT, CUMULATIVE like defined in the Command decorator.

Return: the real methods result

getBase()

Note

This method will be exported by the CommandRegistry.

Returns the LDAP base used by the agent as string

Return: a string representing the LDAP base

getMethods(queue=None, locale=None)

Note

This method will be exported by the CommandRegistry.

Lists the all methods that are available in the domain.

Parameter Description
queue Ask for methods on special queue, None for all
locale Translate __help__ strings to the desired language

Return: dict describing all methods

getNodes()

Note

This method will be exported by the CommandRegistry.

Returns a list of available nodes.

Return: list of nodes

get_load_sorted_nodes()

Return a node list sorted by node load.

Return: list

hasMethod(func)

Check if the desired method is available.

Parameter Description
func method to check for

Return: flag if available or not

isAvailable(providers)

Check if the list of providers contain at least one node which is available.

Parameter Description
providers list of providers

Return: bool flag if at least one available or not

path2method(path)

Converts the call path (class.method) to the method itself

Parameter Description
path method path including the class

Return: the method name

sendEvent(user, data)

Note

This method will be exported by the CommandRegistry.

Sends an event to the AMQP bus. Data must be in XML format, see Events handling for details.

Parameter Description
data valid event

sendEvent will indirectly validate the event against the bundled “XSD”.

serve()

Start serving the command registry to the outside world. Send hello and register event callbacks.

shutdown(queue, force=False)

Note

This method will be exported by the CommandRegistry.

Shut down the service belonging to the supplied queue. In case of HTTP connections, this command will shut down the node you’re currently logged in.

Parameter Description
force force global shut down

Return: True when shutting down

updateNodes()

Maintain node list. Remove entries that haven’t shown up in the configured interval.