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 you need to install the dependencies first. These dependencies are automatically installed when npm install is executed in PopBox root directory.

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)

For the first two scenarios, there are two options for runnning the Benchmark Test suite:

1. With monitor:

If you want to monitor some of the processes involving PopBox you must run the monitor program included in Performance Framework indicating the paths of the programs that you want to monitor. For example, if you want to monitor two agents (in the same machine) and redis server, you have to execute the following command:

node node_modules/performanceFramework/monitor.js "redis-server" "node ../src/Agent.js" "node ../src/Agent.js" 

If you have agents in different machines, you must run the monitor in all the machines. In addition, you must modify the config.js file (maxProvision.pf.monitors or maxPop.pf.monitors) to indicate the machines to monitor.

In config.js file you also need to specify the hosts and ports for the transactions and queues servers (redisTrans and redisServer).

2. Without monitor:

If you don't want to use monitors, you have to start PopBox normally. You also need to modify the config.js file and leave maxProvision.pf.monitors and/or maxPop.pf.monitors in blank.

Run the first two scenarios

Run node maxProvision.js or node maxPop.js according to the benchmark that you want to execute. A HTML file will be generated containing the results of the tests (CPU, MEM, main graph, logs, ...).

Run the last two scenarios

To run these scenarios, first of all you have to run the redis server. Then, you have to run an Agent, and finally you have to run the benchmark you want to run:

./redis-server        #Run the redis server (located in the source folder of redis)
node Agent.js         #Execute one anget (located in the source folder of PopBox)
node maxCon.js        #Execute the third scenario (located in the benchmark folder of PopBox)
node randomTest.js    #Execute the fourth scenario (located in the benchmark folder of PopBox)

If you want to run ther third scenario, you have to change the maximum number of file descriptors which a program can open. By default this value is 1024. However, this scenario open too many connections and 1024 file descriptors are insufficient. To change this value you have to execute the following command (as root) before running redis, the agent and the benchmark.

ulimit -SHn 200000