Maestro Orchestration Protocol

Introduction

The Maestro Orchestration Protocol is a lightweight orchestration protocol used to set test parameters, orchestrate test execution and share testing status among the members of the testing cluster. It is a publish/subscribe based protocol that is implemented on top of the MQTT version 3.1.1 messaging protocol.

The current version of the protocol is 1.1.0 and is the version used for Maestro 1.5.x.

Establishing the connection

The peers MUST perform an authentication-less connection to a MQTT 3.1.1 compliant message broker.

Terminology

The MQTT 3.1.1 compliant message broker used for the purpose of exchanging data between Maestro components is referred as the Maestro Broker.

A Maestro-compliant component, connected to the Maestro Broker, is referred to as a Maestro Peer (or simply peer).

The set of Maestro Peers connected to the same Maestro Broker is collectively described as Testing Cluster or Maestro Test Cluster.

Roles

The peers on the testing cluster are further divided according to the kind of activity they will execute during the test. This is defined as their role on the testing cluster. The assignment of roles for the peers can be dynamic or static.

Static Roles

Peers with static roles perform one and only one type of activity throughout the lifetime of their execution. The static roles are:

Client
Agent
Exporter
Inspector
Reports Server

Notes: The client is a special type of peer that is responsible for orchestrating the test work. The reports server is a special type of peer that collects the test reports once the test is completed.

Dynamic Roles

Peers with dynamic roles can be have their role on the testing cluster determined during the execution of the test. The dynamic roles are:

Other
Receiver
Sender

Note: until the role assignment occurs, a peer with dynamic role allocation capability MUST report its role as 0 (Other).

Terminology

A peer capable of dynamic role assignment is known as a Maestro Worker. A client peer is a peer that issues requests and reads responses and notifications. A receiving peer is a type of peer that receives requests and notifications and acts upon it. The client peers are: client and exporter. The receiving peers are: agent, inspector, reports server, sender and receiver.

Data Exchange

The data exchange between peers on the testing cluster is performed using a set of predefined topics. The topics to which a peer connects to is determined by their role, name and unique identification generated prior to or at the moment of the connection.

Peer Name

The peer name is used as a friendly identification of the peer on the test cluster. Maestro peers MUST set a name prior to the connection to the Maestro broker. The peer name MUST be static and MUST NOT change during the lifetime of the connection of the peer with the Maestro Broker.

The peer name MAY be used, in part or in full, by the test client as part of the test orchestration logic. The peer name SHOULD be be unique.

Unique Peer Identification

The unique peer identification (or simply, peer id) is cluster-wide unique ID that identifies the peer in the test cluster. The peer ID MUST be unique within the test cluster. The peer ID MUST be static and MUST NOT change during the lifetime of the connection of the peer with the Maestro Broker.

The peer ID MAY be used, in part or in full, by the test client as part of the test orchestration logic.

Subscription

Upon successful connection, the peers MUST subscribe to a collection of topics according to their role, name and peer ID (unique identification). The subscription to the topics MUST use the MQTT QoS level AT LEAST ONCE.

Client Subscriptions

The a Maestro Client, connecting with the purpose of orchestrating the test execution, MUST subscribe to the following topics:

Topic	Description
`/mpt/maestro`	this topic is used to publish replies to requests sent by a peer
`/mpt/notifications`	this topic is used to publish notifications raised by any peer
`/mpt/logs`	this topic is used to publish log files as a response to a log request

Agent peer

Topic	Description
`/mpt/maestro`	this topic is used to publish replies to requests sent by a peer
`/mpt/peer/by-role/agent`	this topic is used by a peer to convey requests applicable to an agent peer

Inspector Subscriptions

Topic	Description
`/mpt/maestro`	this topic is used to publish replies to requests sent by a peer
`/mpt/peer/by-role/inspector`	this topic is used by a peer to convey requests applicable to an inspector peer

Reports Server

Topic	Description
`/mpt/maestro`	this topic is used to publish replies to requests sent by a peer
`/mpt/peer/by-role/reports-server`	this topic is used by a peer to convey requests applicable to a a reports server peer

Worker peer

Topic	Description
`/mpt/maestro`	this topic is used to publish replies to requests sent by a peer
`/mpt/peer/worker`	this topic is used by a peer to convey requests applicable to a worker peer

Dynamic topics

Certain events in the lifetime of a peer can cause a new subscription to required. Subscriptions whose address cannot be determined before the peer connects to the Maestro broker are said to be dynamic.

Topic	Applicable Roles	Description
`/mpt/peer/by-id/${id}`	All	this topic is used by a peer to convey requests applicable to an specific peer identified by its ID
`/mpt/peer/by-name/${name}`	All	this topic is used by a peer to convey requests applicable to an specific peer identified by its name
`/mpt/peer/by-role/${role}`	Sender or Receiver	transient subscription for Workers peers upon role assignment
`/mpt/peer/by-group/${group}`	All	transient subscription for Workers peers upon group assignment (reserved for future protocol versions

Publication Rules

Notes MAY be published to any topic at the discretion of the client, according to the intention of the test. Receiving peers MUST publish the replies to /mpt/maestro, notifications to /tmp/notifications and logs to /mpt/logs unless specified otherwise by the documentation.

Maestro Protocol

Basic Details

The Maestro protocol is a binary protocol implemented on top of msgpack API version 1.0. The MQTT messaging protocol, version 3.1.1, is used to exchange data between the testing nodes.

Terminology

The messages exchanged between the peers of the testing cluster are called notes.

Notes Format

The notes consists of four sections: type, command, correlation information and payload.

Type	Command	Correlation	Payload

The type, command and correlation information compose the header of the note. The fields composing the header MUST be present on all notes.

Type

Type is a short integer that identifies the purpose of the note. It MUST be present on all messages. The values MUST be one of:

Request (0): a note published by a peer to convey a request.
Response (1): a note published by a peer as a response for a request note.
Notification (2): an asynchronous note published by a peer to notify other peers that a certain event has occurred.
Data (3): a note published by a peer to carry data as a response for a request for data.

Obs.: the values in parenthesis represent the numeric value of the type.

Response Type Format

Id	Peer Info	Body

ID: the ID, represented as a UUID, of the node.
Peer info: a data structure that is used to carry peer information. Please check the Peer Info section below for additional details.
Body: the response body

Data Type Format

Id	Peer Info	Body

ID: the ID, represented as a UUID, of the node.
Peer info: a data structure that is used to carry peer information. Please check the Peer Info section below for additional details.
Body: the response body

Command

The command is a long integer that identifies the action to being requested or being replied to. It MUST be present on all notes.

Some commands are only valid on the context of some note types. Additionally, some commands are only applicable to certain peer roles. The constraints for each command is documented in greater detail further in the specification.

The accepted commands are listed below, along with the numeric value that represent them:

Start Worker (0)
Stop Worker (1)
Start Test (2)
Stop Test (3)
Start Inspector (4)
Stop Inspector (5)
Set (7)
Stats (8)
Halt (9)
Ping (10)
OK (11)
Protocol Error (12)
Internal Error (13)
Abnormal Disconnect (14)
Notify Fail (15)
Notify Success (16)
Get (17)
Start Agent (18)
Stop Agent (19)
Agent Source (21)
User Command 1 (30)
Log (40)
Drain (41)
Notify Drain Complete (42)
Group Join (50)
Group Leave (51)
Role Assign (60)
Role Unassign (61)
Notify Test Started (70)

The following command(s) was(were) used in the past but are not supported in the current version of the protocol:

Flush (6)

When receiving a request for a command that is not supported for the protocol version, a peer MUST reply with an internal error:

Correlation Information

The correlation information carries content that allow notes to be correlated to each other. The contents of the correlation information field allow a response to be related to a request. The correlation information consists of two fields: correlation ID and message ID.

Correlation ID	Message Id

Correlation ID: an arbitrary length, randomly generated, string. Typically, this SHOULD be the string representation a randomly generated https://tools.ietf.org/html/rfc4122.
Message ID: This field is reserved for future use and implementations of the current protocol MUST NOT consider it when correlating messages. The field MUST be present on the notes and implementations of the current protocol version MAY use any string value for this field.

Peer Info

This structure is used to carry peer-specific information and consists of the following fields: group member name, group name, peer role code, peer name, peer host. All fields MUST be present on the structure.

Group Member Name	Group Name	Role	Peer Name	Peer Host

Group member name: the name of the peer within a group as a string. This fields is currently unused and reserved for future versions of the protocol. It MUST be an empty string.
Group name: the name of the group as a string. This fields is currently unused and reserved for future versions of the protocol. It MUST be an string with the value all.
Role: peer role. Check the role documentation in the common data types.
Name: the name of the peer.
Host: the host name or IP address of the host name of the peer. Dynamic host names, such as those generated by containers, MAY be used.

Payload

The payload is the data carried by the note as part of its command. The payload varies according to the note type and command value. The payload is documented separately for each command.

Common Data Types

Test

The test data type is used on some of the notes to carry test-specific information. The test data type consists of the following fields: test number, test iteration, test name, test script name and test details.

Test Number	Test Iteration	Test Name	Test Script Name	Test Details

Test number: carries the test number requested by a client and/or the test number associated with the note carrying the test data. The values are either: an arbitrary integer equal to or greater than zero for an specific test number; -1 to use, represent or refer to the next available test number or ID; or -2 to reuse, represent or refer to the last recorded test.
Test iteration: carries the test iteration requested by a client and/or the test iteration associated with the note carrying the test data. The values are either: an arbitrary integer equal to or greater than zero for an specific test iteration; -1 to use, represent or refer to the next available test iteration or ID; or -2 to reuse, represent or refer to the last recorded test iteration.
Test name: carries an arbitrary length string that names the test.
Test script name: carries an arbitrary length string that matches the test script being run.
Test details: a test detail data type.

Test Details

The test data type is used along with the test data type to carry additional details about the test. The test details data type consists of the following fields: test description and test comments.

Test Description	Test Comments

Test description: an arbitrary length string that can be used to describe the test.
Test comment: an arbitrary length string that can contains a comment about the test data type containing the test details structure.

Role

Type code

Type code: an integer that represents the of the peer role. It must be one of the following values, according to the peer role:
- Other (0): used for peers with dynamic roles that haven't received a request to assign a role and other types of unspecified peers.
- Sender (1): used for sender peers.
- Receiver (2): used for receiver peers.
- Inspector (3): used for inspector peers.
- Agent (4): used for agent peers.
- Exporter (5): used for exporter peers.
- Reports Server (6): used for reports server peers.

Note: Protocol Error

Command value: 12

Request

A protocol error request note is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

Response

This note is published by a peer as a response to an invalid or malformed note. This note MUST NOT contain a payload.

Note: Internal Error

Command value: 13

Request

An internal error request note is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

Response

This note is published by a peer as a response to when failing to comply with a request. The Internal Error note MUST contain a payload that consists of the following fields: error code and error message.

Error Code	Error Message

The description of the payload fields are:

Error code: a integer value representing the error code. Accepted values are:
- Unspecified (0): represents an unspecified error condition.
- Try Again (1): represents a temporary error condition and the requesting peer should try again after some time.
Error message: an arbitrary length string that describes the error condition.

Note: OK

Command value: 11

Request

An OK request note is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

Response

This note is a generic response when the node complies with a request. It MUST NOT contain a payload.

Note: Abnormal Disconnect

Command value: 14

Request

An abnormal disconnect request note is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

Response

An abnormal disconnect response note is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

Notification

This note MAY be sent by a peer as a notification that its connection was terminated abruptly. When set, it MUST be setup as a MQTT last-will message. The payload of the abnormal disconnect note consists of the following fields: message.

Message

The description of the payload fields are:

Message: an arbitrary length string that describes the condition.

Note: Notify Fail

Command value: 15

Request

An notify fail request note is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

Response

An notify fail response note is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

Notification

This note MAY be sent by a peer as a notification that the test terminated unsuccessfully. The payload of the notify fail note consists of the following fields: test, message. Upon receiving a notify fail message, a receiving peer MUST terminate the test execution.

Test	Message

Test: please refer to the test data type documented previously.
Message: an arbitrary length string describing the failure condition and that could be used to convey the reason the test failed.

Note: Notify Success

Command value: 16

Request

An notify success request note is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

Response

An notify success response note is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

Notification

This note MAY be sent by a peer as a notification that the test terminated successfully. The payload of the notify success note consists of the following fields: test, message. Upon receiving a notify success message, a receiving peer MUST terminate the test execution.

Test	Message

Test: please refer to the test data type documented previously.
Message: an arbitrary length string describing the success condition.

Note: Start Test

Command value: 2

Request

This note is sent by a client to the receiving peers to inform that a test is starting. The payload for the request note consists of the following field: test execution info.

Test Execution Info

The test execution info field consists of the following field: worker name.

Test	SUT Details

Test: please refer to the test data type documented previously.
SUT details: an optional structure that MAY carry data related to the Software Under Test instance that is used by the reports server to display useful information about the test. It consists of the following fields: SUT ID, SUT name, SUT version, SUT JVM version, SUT other info, SUT tags, laboratory name and test tags.
- SUT ID: an optional numeric identification for the SUT or -1 if unspecified.
- SUT name: an arbitrary length string containing the name of the SUT or an empty string if unspecified.
- SUT version: an arbitrary length string containing the version of the SUT or an empty string if unspecified.
- SUT JVM version: an arbitrary length string containing the JVM version used by the SUT or an empty string if unspecified.
- SUT other info: an arbitrary length string containing additional information about the SUT or an empty string if unspecified.
- SUT tags: a comma-separated list of strings of arbitrary length used as a tag for the SUT (ie.: tag1,tag2,tag3,etc)
- Laboratory name: an arbitrary length string containing additional information about the location where the test is being run.
- Test tags: a comma-separated list of strings of arbitrary length used as a tag for the test (ie.: tag1,tag2,tag3,etc)

Response

A start test response note is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

The receiving peers processing a Start Test request MUST respond with a OK response note if the request was successful or with a Internal Error response note if the request failed.

Notification

A Start Test notification is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

Note: Stop Test

Command value: 3

Note: this note is reserved for future use and MAY be safely ignored at the current protocol version.

Request

This note is issued by a client to a receiving peer node to inform that a test is stopping. This note does not carry any payload.

Response

A stop test response note is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

Notification

A stop test notification is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

Note: Start Worker

Command value: 0

Request

This note is sent by a client to request it to start the sending or receiving data. The payload for the request note consists of the following field: start worker options.

Options

The options field consists of the following field: worker name.

Worker Name

Worker name: contains the name of the worker that will conduct the test execution generating the synthetic load on the test target. Currently, the following values are supported by Maestro Java: JmsSenderand JmsReceiver. Respectively, they are used to instantiate and start a JMS sender or a JMS receiver.

Response

A start worker response note is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

The receiving peers processing a Start Worker request MUST respond with a OK response note if the request was successful or with a Internal Error response note if the request failed.

Notification

A start worker notification is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

Note: Stop Worker

Command value: 1

Request

This note is issued by a client to a receiving peer node to request it to stop sending or receiving data. This note does not carry any payload.

Response

A stop worker response note is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

The receiving peers processing a Stop Worker request MUST respond with a OK response note if the request was successful or with a Internal Error response note if the request failed.

Notification

A stop worker notification is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

Note: Start Inspector

Command value: 4

Deprecation warning: this note is likely to be replaced by Start Worker in future versions of the protocol.

Request

This note is sent by a client to a inspector to request it to start the introspecting the instance under test. The payload for the request note consists of the following field: start inspector options.

Options

The options field consists of the following field: inspector name.

Inspector Name

Inspector name: contains the name of the inspector that will conduct the introspection on the test target. Currently, the following values are supported by Maestro Java: InterconnectInspectorand ArtemisInspector. Respectively, they are used to instantiate and start a inspector for the QPid Dispatch Router (or Red Hat AMQ Interconnect) or a inspector for Apache Artemis.

Response

A start inspector response note is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

The receiving peers processing a Start Inspector request MUST respond with a OK response note if the request was successful or with a Internal Error response note if the request failed.

Notification

A start inspector notification is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

Note: Stop Inspector

Command value: 5

Deprecation warning: this note is likely to be replaced by Stop Worker in future versions of the protocol.

Request

This note is issued by a client to a receiving peer node to request it to stop introspecting the test target. This note does not carry any payload.

Response

A stop inspector response note is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

The receiving peers processing a Stop Inspector request MUST respond with a OK response note if the request was successful or with a Internal Error response note if the request failed.

Notification

A stop inspector notification is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

Note: Start Agent

Command value: 18

Deprecation warning: this note is likely to be replaced by Start Worker in future versions of the protocol.

Request

This note is sent by a client to an agent peer to request it to start running. This note does not carry a payload.

Response

A start agent response note is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

The receiving peers processing a Start Agent request MUST respond with a OK response note if the request was successful or with a Internal Error response note if the request failed.

Notification

A start agent notification is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

Note: Stop Agent

Command value: 19

Deprecation warning: this note is likely to be replaced by Stop Worker in future versions of the protocol.

Request

This note is issued by a client to an agent peer to request it to stop running. This note does not carry a payload.

Response

A stop agent response note is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

The receiving peers processing a Stop Agent request MUST respond with a OK response note if the request was successful or with a Internal Error response note if the request failed.

Notification

A stop agent notification is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

Note: Set

Command value: 7

Request

This note is sent by a client to the receiving peers to set the testing properties. This note consists of the following fields: option and value. Both fields MUST be present on the note.

Option	Value

Option: a long integer that represents the test option being set.
Value: a string containing the value to be set.

The available options along with their respective values are:

Endpoint (0): used to set a URL that the peers will use to send that to or receive data from.
- Value: a string in the format protocol://<hostname>/<queue name>.
Duration Type (1): sets the duration type and duration of the test.
- Value: it can be either a numeric string that represents the number of messages to exchange or properly formatted string representing days, hours, minutes and/or seconds according to the test duration specification.
  - Example durations: 1d for 1 day; 1d1h for 1 day and 1 hour; 1d1h1m1s for 1 day, 1 hour, 1 minute and 1 second.
Log level (2): used to set the log level on the nodes. This option is deprecated and peers MAY safely ignore it.
- Value: one of trace, debug, info, warning, error or fatal.
Parallel Count (3): sets the number of concurrent connection for the node.
- Value: an integer up to 65535.
Message Size (4):
- Value: a numeric string that represents a fixed message size or a number prefixed with ~ for a variable message size (5% size variation).
  - Example: 256 for 256 bytes or ~256 for 256 bytes with a 5% size variation.
Throttle (5): sets throttling on on the sender. This option is deprecated and peers MAY safely ignore it.
- Value: a numeric value representing the number of messages to be sent per connection.
Rate (6): sets the desired target rate per second for each connection.
- Value: a number that represents the desired number of messages that each connection should try to send per second.
FCL (7): sets "fail condition on latency". If the latency ever exceeds this value, the test fails. Receiving peers MAY implement different mechanism for evaluating the latency threshold.
- Value: the maximum acceptable latency.

Response

A set response note is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

The receiving peers processing a set request MUST respond with a OK response note if the request was successful or with a Internal Error response note if the request failed.

Notification

A set notification is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

Note: Stats

Command value: 8

Request

This note is issued by a client to the receiving peers to request the current performance statistics. This does not carry a payload.

Response

The receiving peers processing a Stop Agent request MUST respond with a Stats response or with a Internal Error response note if the request failed. The stats response consists of the following fields:

Connection count	Role Info	Stats Type	Performance Data

Connection Count: an integer containing the number of connections. In previous versions of the protocol it was named Child Count.
Role Info: an arbitrary length string containing additional information about the peer (ie.: "Maestro Java version 1.5.2")
Stats type: identify the type of statistics being published. This is currently ignored and MUST be set to 0.
Perf data: performance data struture.

Performance Data Format:

Timestamp	Count	Rate	Latency

Timestamp: this is currently ignored and must be set to 0.
Count: and integer containing number of messages exchanged since the test has started or 0 if not available.
Rate: the combined current rate for all connections at the moment of collection of the statistics or 0 if not available.
Latency: a double latency structure containing the mean latency for the interval consisting of the test start time and the current collection time or 0.0 if not available.

Notification

A stats notification is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

Note: Ping

Command value: 10

Request

This note is issued by a client to the receiving peers to verify which peers are alive and the latency between the client and each of them. The note consists of the following fields: seconds and microsends.

Seconds	Microsends

Seconds: a long integer that represents seconds since epoch in the controller node.
Microseconds: a long integer that represents microseconds within the second.

Response

The receiving peers processing a Ping request note MUST respond with a Ping response or with a Internal Error response note if the request failed. The Ping response consists of the following fields: elapsed

Elapsed

Elapsed: a long integer that represents the amount of milliseconds elapsed between the reported time on the ping request and the time of processing the response.

Notification

A ping notification is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

Note: Halt

Command value: 9

Request:

This note is sent by a client to a receiving peer in order to request them to stop running and exit cleanly. This note does not carry a payload. A receiving peer MUST stop running and exit upon receiving such request.

Response

A halt response note is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

The receiving peers processing a halt request MAY respond with a OK response note.

Notification

A halt notification is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

Note: Get

Command value: 17

Request

This note is sent by a client to a receiving peer in order to request an operational parameter from the peers. In previous version of the protocol this note was used to query the address of the data server. Since the data server is deprecated, this note is currently unused and reserved for future versions of the protocol. The note consists of the following fields: option.

Option

option: this is a long integer that contains the option number.The following options are/were available:
- Data server (1): deprecated option to query for the address of the data server.

Response

The receiving peers processing a Get request note MUST respond with a Get response or with a Internal Error response note if the request failed. The Get response consists of the following fields: option and value.

Option	Value

option: this is a long integer that contains the option number as described in the Get request specification.
value: this String field contains the value associated with the requested option.

Notification

A get notification is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

Note: Agent Source

Command value: 21

Request

This note is sent by a client to an agent peer in order to request the agent to download the source code for dynamic execution via agent. The code to be downloaded MUST be hosted in a git repository. This note consists of the following fields: source URL and branch.

Source URL	Branch

Source URL: this string field contains the git URL for the source code to be download
Branch: this OPTIONAL string field contains the branch to be used for the source code to be downloaded. It MAY be null.

Response

An agent source response note is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

The agent peers processing a set request MUST respond with a OK response note if the request was successful or with a Internal Error response note if the request failed.

Notification

An agent source note notification is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

Note: User Command 1

Command value: 30

Request

This note is sent by a client to an agent peer as a void command that can be used by extension scripts at their will. It has no associated action by peers. It MUST be implemented on the agent peer. It MUST NOT be implemented on other types of peers. This note consists of the following fields: option and payload.

Option	Payload

option: an OPTIONAL integer value passed to the extension scripts.
Payload: an OPTIONAL string payload passed to the extension scripts.

Response

The receiving peers processing a user command 1 request note MUST respond with a user command 1 response or with a Internal Error response note if the request failed. The user command 1 response consists of the following fields: status.

Status

status: a string payload containing a status of the execution of the user command 1 request by the extension script. It MUST be present on all responses. It MAY be an empty string if no status can be associated with the execution user command 1 request.

Notification

A user command 1 note notification is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

Note: Log

Command value: 40

Request

This note is sent by a client to the receiving peers in order to request them to send the report files to the reports server. This note consists of the following fields: location type and type name.

Location Type	Type Name

location type: a short integer that represents the location type of the reports within the storage location in the peers deployment. It MUST be one of the following values:
- Any (0): any location
- Last successful (1): represents the storage location for the reports of the last successful test.
- Last failed (2): represents the storage location for the reports of the last failed test.
- Last (3): represents the storage location for the reports of the last test.
Type name: a string that uniquely identifies the location (ie.: path for the reports, an ID that can be used to refer to that location, etc) It MUST be present when using the any location type.

Response

A log response note is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

Notification

A log notification note is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

Data

Receiving peers processing a log request MUST reply with a log data note or with a Internal Error response note if the request failed. It consists of the following fields: location type, location type info, name, index, total, size, hash and data. All fields MUST be present on the note.

A log data note carries the report data collected during a test. The note MAY carry either the file as a whole or a part of it (chunk) if the file size is greater than or equal to the maximum chunk size. Clients receiving file chunks can determine the current chunk index or the number of chunks by querying the respective files in the log data note, therefore receiving peers MUST fill these fields correctly.

Location Type	Location Type Info	Name	Chunk Index	Total Chunks	Size	Hash	Data

location type: a short integer that represents the location type of the reports within the storage location in the peers deployment as described in the log request.
location type info: a structure containing information about the location. It consists of the following fields: count and index.
Name: the file name.
Chunk index: the chunk index.
Total chunks: the total number of chunks.
Size: the size of the chunk or the file size if smaller than the maximum chunk size
Hash: the SHA-1 hash for the file.
Data: the file or a part of the file if the total file size is greater than the maximum chunk size.

Location Type Info

Count	Index

Count: it contains the number of files within the location (ie.: the number of files in the directory).
Index: the current file index within the location.

Note: Drain

Command value: 41

Request

This note is sent by a client to a receiver in order to request it to drain a queue. This note consists of the following fields: duration, endpoint (url), parallel count, worker name. This note is considered EXPERIMENTAL at the current protocol version and MAY be ignored by receiver peers.

Duration	Endpoint	Parallel Count	Worker Name

Duration: the duration type and duration of the test. It can be either a numeric string that represents the number of messages to exchange or properly formatted string representing days, hours, minutes and/or seconds according to the test duration specification.
- Example durations: 1d for 1 day; 1d1h for 1 day and 1 hour; 1d1h1m1s for 1 day, 1 hour, 1 minute and 1 second.
Endpoint (0): used to set a URL that the peers will use to send that to or receive data from. It is a string in the format protocol://<hostname>/<queue name>.
Parallel Count (3): the number of concurrent connection for the node. It can be an integer up to 65535.
Worker name: contains the name of the worker that will conduct the drain execution on the test target. Currently, the following value is supported by Maestro Java: JmsReceiver. It is used to instantiate and start a JMS receiver.

Response

A drain response note is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

The receiving peers processing a drain request MUST respond with a OK response note if the request was successful or with a Internal Error response note if the request failed. Upon drain completion, the receiving peers must publish a Notify Drain Complete note to the notifications topic.

Notification

A drain notification note is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

Note: Notify Drain Complete

Command value: 42

Request

A notify drain complete request note is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

Response

A notify drain complete response note is invalid and MUST be replied with a protocol error response by a receiving peer or MAY be discarded by a client peer.

Notification

This note MAY be sent by a receiver upon completing the draining the queues on the SUT, by request or automatically. The payload of the notify success note consists of the following fields: successful and message.

Successful	Message

Successful: a boolean flag indicating whether the drain completed successfully or not.
Message: an arbitrary length string describing the success condition.