API Reference

Classes

ConsoleLogger

ExecutionContext

ExecutionDirector

RequestPlayer

RequestGroupPlayer

Rcoil

Request

Typedefs

treeWalkerCallback : function

the process function needs to return an object with 2 properties: a boolean to tell the walker to return and a value to return.

inputCallback : function

the input function generates and returns request bodies for the coil's requests. The callback is triggered by the RequestPlayer before it starts each request. When starting an HTTP request the input callback is triggered with the ExecutionContext and the generated http.ClientRequest object. When invoking a Lambda function the callback simply receives the context.

ConsoleLogger

Kind: global class

• ConsoleLogger
  • new ConsoleLogger()
  • .timestamp() ⇒ String
  • .info(message)
  • .debug(message)
  • .warn(message)
  • .error(message)

new ConsoleLogger()

Logger object that sends output to the stdout (console.log) and uses the colors package to highlight info, debug, warn, and error lines.

consoleLogger.timestamp() ⇒ String

Return a formatted timestamp string for the logs

Kind: instance method of ConsoleLogger
Returns: String - A formatted timestamp string as [YYYY-MM-DD HH:mm:ss.SS]

consoleLogger.info(message)

Logs an info message

Kind: instance method of ConsoleLogger

Param	Type	Description
message	String	The message

consoleLogger.debug(message)

Logs a debug message

Kind: instance method of ConsoleLogger

Param	Type	Description
message	String	The message

consoleLogger.warn(message)

Logs a warn message

Kind: instance method of ConsoleLogger

Param	Type	Description
message	String	The message

consoleLogger.error(message)

Logs an error message

Kind: instance method of ConsoleLogger

Param	Type	Description
message	String	The message

ExecutionContext

Kind: global class

• ExecutionContext
  • new ExecutionContext()
  • ._responses
  • .registerActiveGroup(group)
  • .unregisterActiveGroup(group)
  • .getActiveGroup(groupId) ⇒ Object
  • .getActiveGroups() ⇒ Array.<RequestGroup>
  • .registerActiveRequest(requestConfig)
  • .unregisterActiveRequests(requestConfig)
  • .getActiveRequest(requestName) ⇒ Request
  • .getActiveRequests() ⇒ Array.<Request>
  • .requestData(groupId, requestName) ⇒ Object
  • .setRequestData(groupId, requestName, requestData)
  • .responseData(groupId, requestName)
  • .setResponseData(groupId, requestName, responseData)
  • .getData() ⇒ Object

new ExecutionContext()

The ExecutionContext object saves the state of the symphony execution, this includes all of the active request groups and requests as well as all request and response data. Requests and responses are organized by group id and request name and are accessible through the responseData and requestData.

The ExecutionContext object uses the rwlock module to synchronize access to the internal data structures.

executionContext._responses

Kind: instance property of ExecutionContext

executionContext.registerActiveGroup(group)

Registers a request group as currently being executed with the execution context

Kind: instance method of ExecutionContext

Param	Type	Description
group	Object	The request group object to be registered

executionContext.unregisterActiveGroup(group)

Removes a request group from the list fo groups currently being executed

Kind: instance method of ExecutionContext

Param	Type	Description
group	Object	The request group to be removed from the list

executionContext.getActiveGroup(groupId) ⇒ Object

Looks up an returns a request group from the list of currently active groups.

Kind: instance method of ExecutionContext
Returns: Object - The group object from the active ones, null if it cannot be found

Param	Type	Description
groupId	String	The id of the group to look up

executionContext.getActiveGroups() ⇒ Array.<RequestGroup>

Performs a deep copy of the request group list and returns it.

Kind: instance method of ExecutionContext
Returns: Array.<RequestGroup> - The full list of currently active request groups.

executionContext.registerActiveRequest(requestConfig)

Registers a request as currently being executed

Kind: instance method of ExecutionContext

Param	Type	Description
requestConfig	Request	A valid request object

executionContext.unregisterActiveRequests(requestConfig)

removed a request from the list of active requests

Kind: instance method of ExecutionContext

Param	Type	Description
requestConfig	Request	A request configuration

executionContext.getActiveRequest(requestName) ⇒ Request

Retrieves a request from the list of active requests

Kind: instance method of ExecutionContext
Returns: Request - The request config

Param	Type	Description
requestName	String	The name of the request

executionContext.getActiveRequests() ⇒ Array.<Request>

Performs a deep copy of the list of active requests and return it

Kind: instance method of ExecutionContext
Returns: Array.<Request> - The list of active requests

executionContext.requestData(groupId, requestName) ⇒ Object

Reads the request data generated for a specific request during the execution of the rcoil.

Kind: instance method of ExecutionContext
Returns: Object - the request data sent to the remote server

Param	Type	Description
groupId	String	The request group id
requestName	String	The name of the request

Example

var data = context.requestData("group1", "request1");
console.log(JSON.stringify(data, null, 2));
{
  config: requestConfig,
  headers: requestObject.headers,
  url: requestObject.url,
  method: requestObject.method,
  statusCode: requestObject.statusCode,
  body: requestBodyString,
  startTime: Date.now()
}

executionContext.setRequestData(groupId, requestName, requestData)

Saves a request data to the context. Request data should match this pattern:

Kind: instance method of ExecutionContext

Param	Type	Description
groupId	String	A request group id
requestName	String	A request name
requestData	Object	The request data

Example

{
  config: requestConfig,
  headers: requestObject.headers,
  url: requestObject.url,
  method: requestObject.method,
  statusCode: requestObject.statusCode,
  body: requestBodyString,
  startTime: Date.now()
}

executionContext.responseData(groupId, requestName)

Retrieves the response data for a specific request.

Kind: instance method of ExecutionContext

Param	Type	Description
groupId	String	The request group id
requestName	String	The request name

Example

var data = context.responseData("group1", "request1");
console.log(JSON.stringify(data, null, 2));
{
  headers: resp.headers,
  httpVersion: resp.httpVersion,
  method: resp.method,
  statusCode: resp.statusCode,
  statusMessage: resp.statusMessage,
  body: responseOutputString,
  endTime: Date.now()
}

executionContext.setResponseData(groupId, requestName, responseData)

Saves a response data in the context. Response data should match this pattern:

Kind: instance method of ExecutionContext

Param	Type	Description
groupId	String	The request group id
requestName	String	The request name
responseData	Object	The response data object

Example

{
  headers: resp.headers,
  httpVersion: resp.httpVersion,
  method: resp.method,
  statusCode: resp.statusCode,
  statusMessage: resp.statusMessage,
  body: responseOutputString,
  endTime: Date.now()
}

executionContext.getData() ⇒ Object

Retrieves the full request and response data structure for all requests and groups in a coil.

Kind: instance method of ExecutionContext
Returns: Object - The full list of requests and responses
Example

{
  req: { // all requests
    group1: { // grouped by request group
      request1 : {
        config: requestConfig,
        headers: requestObject.headers,
        url: requestObject.url,
        method: requestObject.method,
        statusCode: requestObject.statusCode,
        body: requestBodyString,
        startTime: Date.now()
      },
      ...
    },
    ...
  },
  res: { // all responses
    group1: { // grouped by request group
      request1: {
        headers: resp.headers,
        httpVersion: resp.httpVersion,
        method: resp.method,
        statusCode: resp.statusCode,
        statusMessage: resp.statusMessage,
        body: responseOutputString,
        endTime: Date.now()
      },
      ...
    },
    ...
  }
}

ExecutionDirector

Kind: global class
Emits: ExecutionDirector#event:end, groupStart, groupEnd, requestStart, requestEnd

• ExecutionDirector
  • new ExecutionDirector(rcoil, options)
  • .rcoil
  • .executionContext
  • .options
  • .start() ⇒ ExecutionContext
  • .abort()
  • "abort"
  • "groupStart"
  • "groupEnd"
  • "requestStart"
  • "requestEnd"

new ExecutionDirector(rcoil, options)

The ExecutionDirector receives and executes an Rcoil tree.

Options available are:

Param	Type	Description
rcoil	Rcoil	An initialized Rcoil object
options	Object	Configuration options for the director

Example

{
  debug: false,
  logger: new ConsoleLogger();
}

executionDirector.rcoil

The Rcoil object

Kind: instance property of ExecutionDirector
Properties

Type
Rcoil

executionDirector.executionContext

The execution context, this is updated during the execution of the Rcoil and passed to all callbacks and events.

Kind: instance property of ExecutionDirector
Properties

Type
ExecutionContext

executionDirector.options

Configuration options for the director. These are passed to the RequestGroup and Request players.

Kind: instance property of ExecutionDirector
Properties

Type
Object

executionDirector.start() ⇒ ExecutionContext

Begins the execution of the Rcoil object

Kind: instance method of ExecutionDirector
Returns: ExecutionContext - The execution context object that the director will keep updating throughout the execution

executionDirector.abort()

Aborts the execution of an Rcoil.

Kind: instance method of ExecutionDirector

"abort"

The abort event is fired whenever the abort method is called on a director and all running requests are completed.

Kind: event emitted by ExecutionDirector
Properties

Name	Type	Description
context	ExecutionContext	The completed execution context

"groupStart"

The groupStart event is fired every time the director starts the execution of a new request group

Kind: event emitted by ExecutionDirector
Properties

Name	Type	Description
group	Object	The request group being started
context	ExecutionContext	The updated execution context

"groupEnd"

The groupEnd event is fired every time the director completes the execution of a request group

Kind: event emitted by ExecutionDirector
Properties

Name	Type	Description
group	Object	The request group being started
context	ExecutionContext	The updated execution context

"requestStart"

The requestStart event is fired every time the director starts the execution of a request

Kind: event emitted by ExecutionDirector
Properties

Name	Type	Description
groupId	String	The request group id the request belongs to
request	Request	The request being started
context	ExecutionContext	The updated execution context

"requestEnd"

The requestEnd event is fired every time the director completes the execution of a request

Kind: event emitted by ExecutionDirector
Properties

Name	Type	Description
groupId	String	The request group id the request belongs to
request	Request	The completed request
context	ExecutionContext	The updated execution context

RequestPlayer

Kind: global class
Emits: start, end, abort

• RequestPlayer
  • new RequestPlayer(request, context, options)
  • .start()
  • .abort()
  • "start"
  • "end"
  • "abort"

new RequestPlayer(request, context, options)

RequestPlayer executes requests configured in a request group. The RequestPlayer can execute both HTTP and Lambda requests. This object is used internally by the RequestGroupPlayer and there should be no need to interact with it from the outside.

RequestPlayer is an EventEmitter.

Param	Type	Description
request	Object	A configured Request object
context	Object	An initialized ExecutionContext object to keep state across multiple executions
options	Object	The options passed to the director

requestPlayer.start()

Starts the execution of the Request

Kind: instance method of RequestPlayer

requestPlayer.abort()

Aborts the execution of the request

Kind: instance method of RequestPlayer

"start"

The start event is fired whenever the RequestPlayer begins executing a request

Kind: event emitted by RequestPlayer
Properties

Name	Type	Description
requestConfig	Object	The original configuration for the request object
request	Object	The initialized http.ClientRequest object
input	*	The input generated by the callback function configured in the request object

"end"

The end event is fired whenever the RequestPlayer completes the execution of a request

Kind: event emitted by RequestPlayer
Properties

Name	Type	Description
requestConfig	Object	The original configuration for the request object
response	Object	The received http.IncomingMessage object
output	String	The response body

"abort"

The abort event is fired whenever the RequestPlayer aborts an HTTP request

Kind: event emitted by RequestPlayer
Properties

Name	Type	Description
requestConfig	Object	The original configuration for the request object

RequestGroupPlayer

Kind: global class
Emits: start, end, requestStart, requestEnd

• RequestGroupPlayer
  • new RequestGroupPlayer(requestGroup, context, options)
  • .start()
  • "start"
  • "end"
  • "requestStart"
  • "requestEnd"

new RequestGroupPlayer(requestGroup, context, options)

The request group player monitors the execution of a groups of requests and reports the status through its events. The ExecutionDirector object receives the notifications from the RequestGroupPlayer and updates the ExecutionContext

Param	Type	Description
requestGroup	Object	The request group object to be executed
context	ExecutionContext	The current execution context
options	Object	Configuration options for the player

requestGroupPlayer.start()

Starts the execution of a request group object from the Rcoil tree.

Kind: instance method of RequestGroupPlayer

"start"

The start event is fired whenever the RequestGroupPlayer begins executing a group

Kind: event emitted by RequestGroupPlayer
Properties

Name	Type	Description
requestGroup	Object	The request group object that is being executed

"end"

The end event is fired whenever the RequestGroupPlayer completes the execution of a group

Kind: event emitted by RequestGroupPlayer
Properties

Name	Type	Description
requestGroup	Object	The completed request group object

"requestStart"

The requestStart event is fired whenever the RequestGroupPlayer sends the start command to a RequestPlayer object

Kind: event emitted by RequestGroupPlayer
Properties

Name	Type	Description
requestGroup	Object	The completed request group object
requestConfig	Request	The request configuration passed to the RequestPlayer
requestObject	http.ClientRequest	The node.js http/s request object
input	*	The input generated for the request by the callback function

"requestEnd"

The requestEnd event is fired whenever the RequestPlayer completes the execution of a request

Kind: event emitted by RequestGroupPlayer
Properties

Name	Type	Description
requestGroup	Object	The completed request group object
requestConfig	Request	The request configuration passed to the RequestPlayer
response	http.IncomingMessage	The response object from the node.js http/s client
output	*	The output returned from the remote server

Rcoil

Kind: global class

• Rcoil
  • new Rcoil()
  • .calls
  • ._tmpPositionId
  • ._totalRequestGroups
  • .startGroup(groupId) ⇒ Object
  • .afterGroup(groupId) ⇒ Object
  • .addRequest(request) ⇒ Object
  • .fromTheBeginning() ⇒ Object
  • .requestGroupsCount() ⇒ int
  • .printCoil()

new Rcoil()

The main Rcoil object. This is a tree structure made of request groups and requests. Multiple requests and request groups can be executed simulatneously.

An Rcoil is meant to be interacted with in a more "human" way using the startGroup, afterGroup, and addRequest methods.

rcoil.calls

The tree structure containing request groups and requests.

Kind: instance property of Rcoil
Properties

Type
Array

rcoil._tmpPositionId

temporary variable to store the current position in the tree during the creation by the start/after/add methods

Kind: instance property of Rcoil
Properties

Type
String

rcoil._totalRequestGroups

count of the number of request groups in the Rcoil. This is used by the director to confirm when the execution is completed

Kind: instance property of Rcoil
Properties

Type
int

rcoil.startGroup(groupId) ⇒ Object

Starts a new request group in the tree, the group will be a child of the current group (or root of the tree). Request groups created as children are executed sequentially.

To create two parallel request groups use the afterGroup method to return to the previous node of the tree.

Kind: instance method of Rcoil
Returns: Object - The Rcoil object

Param	Type	Description
groupId	String	A unique id for the request group in the tree

Example

rcoil
  .startGroup("first")
    .startGroup("firstChild")
  .afterGroup("first") // going back to the first request group
    .startGroup("secondChild");
// requests within firstChild and secondChild will be execute simultaneously

rcoil.afterGroup(groupId) ⇒ Object

Returns to the given position in the tree.

Kind: instance method of Rcoil
Returns: Object - The symphony object

Param	Type	Description
groupId	String	The name of the node we need to walk back to

rcoil.addRequest(request) ⇒ Object

Adds a request to the current request group (started by startGroup or moved to by afterGroup).

Kind: instance method of Rcoil
Returns: Object - The symphony object

Param	Type	Description
request	Request	A configured request object

Example

rcoil
 .startGroup("testGroup")
   .addRequest(Request.get("listUsers", "https://api.com/listUsers"));

rcoil.fromTheBeginning() ⇒ Object

Returns the walker to the root node of the tree

Kind: instance method of Rcoil
Returns: Object - The symphony object

rcoil.requestGroupsCount() ⇒ int

Retrieves the total number of request groups in the this symphony

Kind: instance method of Rcoil
Returns: int - The number of request groups

rcoil.printCoil()

Uses console log and unicode tables to print out the structure of the coil

Kind: instance method of Rcoil

Request

Kind: global class

• Request
  • new Request(name)
  • instance
    • .getUrl() ⇒ String
    • .setHttpRequest(httpVerb, config) ⇒ Request
    • .setGet(config) ⇒ Request
    • .setPost(config) ⇒ Request
    • .setPut(config) ⇒ Request
    • .setPatch(config) ⇒ Request
    • .setDelete(config) ⇒ Request
    • .setHead(config) ⇒ Request
    • .setOptions(config) ⇒ Request
    • .setLambda(functionArn, qualifier) ⇒ Request
    • .onInput()
  • static
    • .HttpVerb
    • .get(name, config) ⇒ Request
    • .post(name, config) ⇒ Request
    • .put(name, config) ⇒ Request
    • .patch(name, config) ⇒ Request
    • .head(name, config) ⇒ Request
    • .delete(name, config) ⇒ Request
    • .options(name, config) ⇒ Request
    • .lambda(name, config) ⇒ Request

new Request(name)

The Request object contains the configuration for a single backend requests. The request object can represent both an HTTP request and a Lambda function invocation.

HTTP requests can be created using the static shortcuts or the instance methods. Request creation methods can receive either a target url or a full request configuration.

Param	Type	Description
name	String	A name to uniquely identify the request object

Example

// To quickly create a get request
var req = Request.get("name", "http://myapi.com/test");

// to sepcify a full configuration
var req = Request.get("name", {
    host: "myapi.com",
    path: "/test",
    port: "80",
    protocol: "http:",
    method: "GET"
});

// Request body can be set using the onInput callback
req.onInput(function(context, requestObject) {
  return {
    request: "body"
  };
});

request.getUrl() ⇒ String

constructs the full URL of the request from the settings object. For HTTP requests it returns the full request url, for LAMBDA requests it returns the full function ARN + qualifier.

Kind: instance method of Request
Returns: String - The URL for the function

request.setHttpRequest(httpVerb, config) ⇒ Request

Sets up the request object as an HTTP request

Kind: instance method of Request
Returns: Request - The updated request object

Param	Type	Description
httpVerb	String	The HTTP verb of the request.
config	String | Object	This can be a url for the request or a full request object configuration

request.setGet(config) ⇒ Request

Sets up the request object as an HTTP GET request.

Kind: instance method of Request
Returns: Request - The updated request object

Param	Type	Description
config	String | Object	This can be a url for the request or a full request object

request.setPost(config) ⇒ Request

Sets up the request object as an HTTP POST request.

Kind: instance method of Request
Returns: Request - The updated request object

Param	Type	Description
config	String | Object	This can be a url for the request or a full request object

request.setPut(config) ⇒ Request

Sets up the request object as an HTTP PUT request.

Kind: instance method of Request
Returns: Request - The updated request object

Param	Type	Description
config	String | Object	This can be a url for the request or a full request object

request.setPatch(config) ⇒ Request

Sets up the request object as an HTTP PATCH request.

Kind: instance method of Request
Returns: Request - The updated request object

Param	Type	Description
config	String | Object	This can be a url for the request or a full request object

request.setDelete(config) ⇒ Request

Sets up the request object as an HTTP DELETE request.

Kind: instance method of Request
Returns: Request - The updated request object

Param	Type	Description
config	String | Object	This can be a url for the request or a full request object

request.setHead(config) ⇒ Request

Sets up the request object as an HTTP HEAD request.

Kind: instance method of Request
Returns: Request - The updated request object

Param	Type	Description
config	String | Object	This can be a url for the request or a full request object

request.setOptions(config) ⇒ Request

Sets up the request object as an HTTP OPTIONS request.

Kind: instance method of Request
Returns: Request - The updated request object

Param	Type	Description
config	String | Object	This can be a url for the request or a full request object

request.setLambda(functionArn, qualifier) ⇒ Request

Sets up the request object as a Lambda function invocation

Kind: instance method of Request
Returns: Request - The updated request object

Param	Type	Description
functionArn	String	A valid Lambda function ARN
qualifier	String	A Lambda function version or alias

request.onInput()

Adds a callback function that will be executed just before the request is executed. Use the function to return an input for the request. The function will receive the context as a paramter.

If the Request is an HTTP request then the input function will receive both the context and the populated http.ClientRequest object. If it's a Lambda invoke the callback will only receive the context.

Kind: instance method of Request
Example

Request.post("createUser2", "http://myapi.com/createUser2")
  .onInput(function(context, requestObject) {
     // use the context object to read the response from a previous request
     var tmpResp = context.responseData("test", "createUser1");
     return JSON.parse(tmpResp.body);
  });

Request.HttpVerb

An object to simplify the creation of HTTP requests

Kind: static property of Request
Roperty: Object
Example

var r = new Request("requestName");
r.setHttpRequest(Request.HttpVerb.GET, "http://api.com/test");

Request.get(name, config) ⇒ Request

Creates a GET HTTP request. Can receive a url for the request or a full configuration object.

Kind: static method of Request
Returns: Request - An initialized request object

Param	Type	Description
name	String	A name that uniquely identifies the request
config	String | Object	A url string or a request configuration

Request.post(name, config) ⇒ Request

Creates a POST HTTP request. Can receive a url for the request or a full configuration object.

Kind: static method of Request
Returns: Request - An initialized request object

Param	Type	Description
name	String	A name that uniquely identifies the request
config	String | Object	A url string or a request configuration

Request.put(name, config) ⇒ Request

Creates a PUT HTTP request. Can receive a url for the request or a full configuration object.

Kind: static method of Request
Returns: Request - An initialized request object

Param	Type	Description
name	String	A name that uniquely identifies the request
config	String | Object	A url string or a request configuration

Request.patch(name, config) ⇒ Request

Creates a PATCH HTTP request. Can receive a url for the request or a full configuration object.

Kind: static method of Request
Returns: Request - An initialized request object

Param	Type	Description
name	String	A name that uniquely identifies the request
config	String | Object	A url string or a request configuration

Request.head(name, config) ⇒ Request

Creates a HEAD HTTP request. Can receive a url for the request or a full configuration object.

Kind: static method of Request
Returns: Request - An initialized request object

Param	Type	Description
name	String	A name that uniquely identifies the request
config	String | Object	A url string or a request configuration

Request.delete(name, config) ⇒ Request

Creates a DELETE HTTP request. Can receive a url for the request or a full configuration object.

Kind: static method of Request
Returns: Request - An initialized request object

Param	Type	Description
name	String	A name that uniquely identifies the request
config	String | Object	A url string or a request configuration

Request.options(name, config) ⇒ Request

Creates a OPTIONS HTTP request. Can receive a url for the request or a full configuration object.

Kind: static method of Request
Returns: Request - An initialized request object

Param	Type	Description
name	String	A name that uniquely identifies the request
config	String | Object	A url string or a request configuration

Request.lambda(name, config) ⇒ Request

Creates a Lambda request give a Lambda function ARN.

Kind: static method of Request
Returns: Request - An initialized request object

Param	Type	Description
name	String	A name that uniquely identifies the request
config	String | Object	A valid Lambda function ARN

treeWalkerCallback : function

the process function needs to return an object with 2 properties: a boolean to tell the walker to return and a value to return.

Kind: global typedef

Param	Type	Description
key	*	The key of the current property in the tree
value	*	The value for the property

Example

function(key, value) {
  return { shouldReturn: false, value: value }
}

inputCallback : function

the input function generates and returns request bodies for the coil's requests. The callback is triggered by the RequestPlayer before it starts each request. When starting an HTTP request the input callback is triggered with the ExecutionContext and the generated http.ClientRequest object. When invoking a Lambda function the callback simply receives the context.

Kind: global typedef

Param	Type	Description
executionContext	ExecutionContext	The populated execution context object
httpRequest	http.ClientRequest	The generated HTTP request

Example

// for HTTP requests
function(executionContext, httpRequest) {
  httpRequest.setHeader("x-customHeader", "customHeaderValue");

  return { 
    requestBodyParam1 : "value",
    requestBodyParam2 : "value2"
  }
}

// for Lambda invocations
function(executionContext) {
  return {
    lambdaEventProperty1: "value1",
  }
}