Fork me on GitHub

Protocol

Eve defines an interaction protocol between agents. This protocol consists of a common RPC language and some expected behavioral patterns. In this section of the documentation this interaction protocol is described:

Communication Protocol

Eve agents communicate with each other using the JSON-RPC protocol. This is a simple and readable protocol, using JSON to format requests and responses. JSON (JavaScript Object Notation) is a lightweight, flexible data-interchange format. It is easy for humans to read and write, and easy for machines to parse and generate. JSON-RPC version 2.0 is the minimally required version, because Eve uses named parameters.

A request from Agent X to agent Y can look as follows:
Agent X addresses method add from agent Y, and provides two values as parameters. Agent Y executes the method with the provided parameters, and returns the result.

Url
http://myserver.com/agents/agent_y
Request
{
    "jsonrpc":"2.0",
    "id": 1,
    "method": "add",
    "params": {
        "a": 2.2,
        "b": 4.5
    }
}
Response
{
    "jsonrpc":"2.0",
    "id": 1,
    "result": 6.7,
    "error": null
}

Required methods

Method Parameters Result Description
getId none String id Retrieve the agents id. An agent can have multiple urls, but always has one unique id. The id of the agent is not globally unique, agents running on different platforms may have the same id.
getUrls none String[ ] urls Retrieve an array with the agents urls. An agent can have multiple urls for different transport services such as HTTP and XMPP.
getMethods none MethodDescription[ ] methods Retrieve a list with all the available methods.

MethodDescription

The method getMethods of Eve agents returns an array with method descriptions. The method descriptions have the following structure:

Field Type Description
method String Method name
params[ ] Array Array with parameters
params[ ].name String Parameter name
params[ ].type String Parameter type
params[ ].required Boolean True if the parameter is required, else false.
result.type String Method return type.

For example a method add(a,b) can be described as:

{
        "result": {
            "type": "Double"
        },
        "method": "add",
        "params": [
            {
                "name": "a",
                "required": true,
                "type": "Double"
            },
            {
                "name": "b",
                "required": true,
                "type": "Double"
            }
        ]
    }

Management methods

Interaction patterns

This part of the protocol description defines expected capabilities of Eve agents. These capabilities are optional, but are highly advisable as they offer better system-wide robustness and usability. It may be expected from the various Eve implementations to provide these out-of-the-box. Currently the following patterns are described: - Publish-subscribe model - Result monitor model

Publish-subscribe model

Description

An event is identified as a label. The set of events that an agent can trigger is part of the application that is written, Eve does not define any specific events. Subscribing to an event does not guarantee the existence of such an event, nor if the event will ever be triggered by the agent.

Through the event subscription model, agents can request to be informed when a certain event is triggered. The two agents involved (subscriber and publisher) should share a common list of events. When the publisher triggers the event, it will call the provided callback method of the subscriber.

Public methods

Method Parameters Result Description
onSubscribe String event,
String callbackUrl,
String callbackMethod
String subscriptionId Subscribe to an event of this Agent. The provided callback url and method will be invoked when the event is triggered. The callback method is called with the following parameters:
Parameters Description
String subscriptionId The id of the subscription
String event Name of the triggered event
String agent Url of the triggered agent
Object params Event specific parameters
onUnsubscribe String subscriptionId (optional),
String event (optional),
String callbackUrl (optional),
String callbackMethod (optional)
none Unsubscribe from one of this agents events. All parameters are optional:
  • If subscriptionId is provided, the subscription with this id will be deleted. All other parameters are ignored.
  • If callbackUrl is provided, all subscriptions with matching parameters will be deleted. If the parameters event and/or callbackMethod are provided, subscriptions will be filtered by these parameters, else, all subscriptions from this agent will be deleted.

Result monitor model

Description

The result monitor model offers robust, unidirectional synchronization of data. It basically allows an agent to keep up-to-date with the result value of a remote method. Traditionally this is achieved through an event subscription, indicating changed data, followed by a call to the specific method. Care must be taken to make sure the event is delivered to the agent, even in potentially unreliable network environments. A more robust, but less efficient solution would be to poll the method at a fixed interval. The result monitor model combines these solutions into one framework: it allows polling, event subscription and requesting a remote agent to push the result value at a fixed interval. Effectively it makes use of the time autonomy of the agents, making each responsible for trying to keep the data synchronized.

Agent behavior

To participate in the result monitor model, the agent should be able to repetitive request a remote method (poll), repetitively push the result of the method to another agent, push the result at a specific event (see publish-subscribe model) and potentially cache the result locally for future reference. Implementations are advised to bundle these three elements in one monitor API. As the polling and caching are locally organized, the only public methods are related to requesting the push behavior. The internal interface of this model will be documented in the implementation specific sections.

Public methods

Method Parameters Result Description
monitor.registerPush String pushId,
PushConfig config
none Request the agent to start pushing the result of the method call, as described by the provided push configuration. This data should be delivered through a specified callback method.
The given pushId is used as a key to facilitate the communication, it is chosen by the requesting agent. It can be assumed to be unique per requester. Multiple calls with the same pushId may replace the old push.
monitor.unregisterPush String pushId none This method is called to teardown all setup regarding the push.

Push configuration

The function monitor.registerPush requires a push configuration object PushConfig to configure a push monitor. The PushConfig object contains the following parameters:

Field Description
String method The method to use for obtaining the data to push
Object params The parameters for the method call used for obtaining the data to push
String callback The method where the data should be pushed to. This method should at least have the following parameters:
Parameters Description
String pushId The original pushId
Object result The result data
Specific implementations can choose to send back more information, like for example the original pushParams and/or event trigger params.
Number interval Interval in milliseconds at which the data should be pushed
String event When set, the agent should subscribe this push to the given event. If the event is triggered, the method is called and the result send to the callback.
Boolean onChange When true, the agent should organize some way to only push when the data changes, e.g. through a event or by locally polling and comparing.

Documentation

Documentation on the JSON-RPC protocol can be found via the following links:

Site last rendered 30 March 2015