User Manual

In order to obtain JSON responses include "accept":application/json in request header. ##Provision An HTTP request with content-type: application/json

##Entry Point: ###HTTP-POST:[3001] [host]/trans

####POST-DATA: The body must be a JSON with the data for provision The object must contain a payload, a priority (H or L) and a list ('queue') of objects with an 'id' property, for the target devices Optionally a callback, expirationDat could be set as an UNIXTIMESTAMP

Provision.json

{
"payload": "MESSAGE",
"priority":"H",
"callback":"http://foo.bar",
"queue":[
{"id":"Ax"},
{"id":"Bx"}
],
"expirationDate": 1340880820 //UNIXTIMESTAMP 
}

###Response: The response is an object with an 'id' field with the id of the provisioned transaction. In case of error, the response will be a 400 and an object with a list of error messages in its "error" property

HTTP/1.1 200 OK content-type: application/json
{"ok":true, "data":"d84814f0-6776-11e1-a330-3324e9d100c2"}

HTTP/1.1 400 Bad Request content-type: application/json
{"errors":["undefined priority","undefined payload"]}

#Consumer Allows to retrieve the device messages, the id device must be append to the URL.

##Entry Point: ###HTTP-POST:[3001] [host]/queue/[id]/pop

###GET PARAMS: "timeout": if the queue is empty , it will wait the value in seconds before returning an empty list ([]) or data arrived during the waiting period as soon as it arrives.

"max" : maximum number of mesages to retrieve. If there are more, they will be in te queue for later requests.

###Response: The response is a list with the messages as strings. if there are no messages an empty list will be returned ([])

HTTP/1.1 200 OK content-type: application/json
{"ok":true, "data":["MSG ALTA prioridad 1","MSG BAJA prioridad 2"]}

#Peek Allows to get the device messages, the id device must be append to the URL. With this operation, messages are not deleted from queues and its states don't change.

##Entry Point: ###HTTP-GET:[3001] [host]/queue/[id]/peek

###GET PARAMS: "max" : maximum number of mesages to get.

###Response: The response is a list with the messages as strings. if there are no messages an empty list will be returned ([])

HTTP/1.1 200 OK content-type: application/json
{"ok":true, "data":["MSG ALTA prioridad 1","MSG BAJA prioridad 2"]}

#Transaction State in queues Provide information about transaction's states (All, Pending, Delivered, Expired)

##Entry Point HTTP-GET:[3001] /trans/[transaction_id]?queues=[summary|All|Pending|Delivered|Expired] Shows the state of the message on each queue of the transaction ###Response:

All
{"ok":true, "data":{"q1":"Pending","q2":"Delivered"}}

Pending
{"ok":true, "data":{"q1":"Pending"}}

Delivered
{"ok":true, "data":{"q2":"Delivered"}}

Summary
{"ok":true, "data":{"total_notifications":2,"Pending":1,"Delivered":1}}

#Transaction info Get the metainformation related to a given transaction

##Entry point HTTP-GET:[3001] /trans/[transaction_id]

###Response

{"ok":true, 
"data":{
  "payload": "MESSAGE",
  "priority": "H",
  "callback":"http://foo.bar",
  "expirationDate": UNIXTIMESTAMP,
  "queue":[
    {"id":"Ax"},
    {"id":"Bx"}
  ], 
 }
}

#Queue info Get the metainformation related to a given queue

##Entry point HTTP-GET:[3001] /queue/[queue_id] ###Response Provision.json

{   "ok":true,
    "host":"localhost:3001",
    "lastPop":"1340634743",
    "size":10,
    "high":[
        {
            "id":"ae98523f-be4e-4bf9-a096-d3388c642491",
            "href":"http://localhost:3001/trans/ae98523f-be4e-4bf9-a096-d3388c642491?queues=All"
        }
    ],
    "low":[
        {
            "id":"81ae88b7-169d-4881-9300-2c8fc93aed32",
            "href":"http://localhost:3001/trans/81ae88b7-169d-4881-9300-2c8fc93aed32?queues=All"
        },
        {
            "id":"62a81dce-0dbf-4cec-b4d3-1d20934a398f",
            "href":"http://localhost:3001/trans/62a81dce-0dbf-4cec-b4d3-1d20934a398f?queues=All"
        }
    ]
}

#Modify Transaction Modify the current Transaction. This changes will apply to Pending Notifications for any of the following properties: Payload, Callback, ExpirationDate

Note that properties like Priority or the destination Queues can´t be modified.

###Entry Point HTTP-PUT:[3001] [host]/trans/[id] ####PUT/POST-DATA: Provision.json (subset)

{
"payload": "MESSAGE",
"callback":"http://foo.bar",
"expirationDate": UNIXTIMESTAMP 
}

###Response:

{"ok":"true"}
{"errors":["Redis connection to localhost:6379 failed - connect ECONNREFUSED"]}

#Delete Transaction Remove a given transaction. The behaviour will be the same as "EXPIRED" transaction. ###Entry Point HTTP-DELETE:[3001] [host]/trans/[id]

###Response:

{"ok":"true"}
{"errors":["Redis connection to localhost:6379 failed - connect ECONNREFUSED"]}

##Running Tests To run the suite of tests first you need to install the dependencies. There's a package.json in the "tests" directory which will automatically install them using the npm install command.

The tests run in Mocha. If you want to run a single test the command will be this: ./mocha [name_of_the_test]. Otherwise, if you want to run all the tests the command is: make test

##Running Benchmark

There are four scenarios that can run:

• First Scenario: This test determines the time taken by the system to provision X inboxes with messages of Z KB. When the test is finished, the following message will be shown: "X inboxes have been provisioned with a Z KBytes payload in Y seconds with no errors" (maxProvision.js)

• Second Scenario: This test tries to calculates the maximun number of simultaneous blocking connections that the system can handle. When finished, a message like this will be shown: "The system can handle X simultaneous connections with no errors" (max_con.js)

• Third Scenario: In this case, the max ratio of pop requests supported by the system will be evaluated extracting messages of 1K each. When finished, a message like this will be shown: "The system can handle X pop request (1K) in Y segs with no errors" (maxPop.js)

• Fourth Scenario: Long term test. The system will be running a large period of time while several clients (provisioners and consumers) will be launching requests to it. When finished, a message will be shown: "The system has been active for X days and Y transactions have been transferred." (randomTest.js)

There are two options for runnning the Benchmark Test suite:

1. With monitor:

The variable launchWithDeployment must be set to true in the file config.js. This file is located in the "benchmark" folder. Run the monitor.js in each host where you want to execute the Agent.js. In config.js you need to specify the hosts and ports where the agents are running (agentHosts), you also need to specify the hosts and ports for the transactions and queues servers (redisTrans and redisServer).

2. Without monitor:

This option does not use monitors because benchmark.js connects with agents that are running with their corresponding redis servers. In config.js you need to specify the hosts and ports where the agents are running (agentHosts), also you need to specify the hosts and ports for the transactions and queues servers (redisTrans and redisServer). With this option it is not possible to obtain the memory and CPU because there are not monitors running in hosts where the agents are executed.

• Example to specify ports and hosts:[{host:'192.168.1.51', port: 3001},{host:'192.168.1.52', port: 3001}]

Run test

After choosing one option run benchmark.js which wait a connection in port 8090. If you connect to benchmark.js with a browser (http://host:8090), you can see a page where you can choose a scenario to run and track the results of it (graphics,memory and cpu for each Agent.js) in the same page.

If you are running the second or the third scenario, you have to change the maximum number of file descriptors which a program can open. By default this value is 1024. However, these scenarios open too many connections and 1024 file descriptors are insufficient. To change this value you have to execute the following command (as root):

ulimit -SHn 200000

It's necessary to execute this command before executing redis, the benchmark and the monitors.