Getting Started With RestQ

RestQ is MorbidQ's unique solution for the problem of message queue integration with other systems, web frameworks in particular. The basic idea of RestQ is fairly straightforward. When MorbidQ starts up, RestQ hits some http resource, and that resource responds with a JSON dictionary mapping no more than 5 queue event types to no more than 5 urls. Whenever a flagged event occurs, RestQ hits the specified url and takes any actions indicated in the response.

Events and Callbacks

The possible event types are: subscribe, unsubscribe, send, connect, disconnect. All callbacks are optional. If you don't care about a certain event type, simply don't specify a resource in your initial response to RestQ.

Here's the basic structure of communication between RestQ and the callback recipient:

subscribe
  request
    username
    destination
  response
    allow = ('yes'/'no')
    autosubscribe = ['/topic/this', '/topic/that', ...]
    autounsubscribe = ['/topic/this', '/topic/that', ...]
unsubscribe
  request
    username
    destination
  response
    autosubscribe = ['/topic/this', '/topic/that', ...]
    autounsubscribe = ['/topic/this', '/topic/that', ...]
send
  request
    username
    destination
    body
  response
    allow = ('yes'/'no')
    body = modified_body
connect
  request
    username
    password
  response
    allow = ('yes'/'no')
    autosubscribe = ['/topic/this', '/topic/that', ...]
    autounsubscribe = ['/topic/this', '/topic/that', ...]
disconnect
  request
    username
  response
    {}

A RestQ request will always be a JSON dictionary wrapped in a POST. The callback recipient will always respond with a JSON dictionary. All response fields are optional, so the response can sometimes just be "{}".

Sample RestQ Callback Recipient

MorbidQ ships with a sample RestQ callback recipient. To try it out, first download Orbited. The 0.7 series comes with a nice gui for playing around with STOMP, which is what we're about to do. Make two text files:

orbited.cfg:

[listen]
http://:8000
stomp://:61613 stomp.cfg

[access]
* -> localhost:61613

stomp.cfg:

restq = http://localhost:5000/

The contents of stomp.cfg tells MorbidQ that it should hit http://localhost:5000/ when it starts up, and that it should expect the response to be a JSON dictionary mapping event types to callback urls. This is equivalent to running MorbidQ like this:

morbid -r http://localhost:5000/

The [listen] section of orbited.cfg tells Orbited to proxy http connections on port 8000 and to run MorbidQ on port 61613 with the configuration found at stomp.cfg. The access section adds localhost:61613 to Orbited's proxy whitelist.

Now open a terminal and navigate to the directory containing orbited.cfg and stomp.cfg. Type:

orbited

You'll get an error. This is because the remote resource specified in stomp.cfg is offline. In other words, there's no RestQ callback recipient running.

Open another terminal, and type:

morbid_restq_test

This calls main() in the sample RestQ callback recipient that ships with MorbidQ. Now that that's running, go back to your first terminal and type (again):

orbited

You'll notice that it starts up fine. In a web browser, navigate to http://localhost:8000/static/demos/stomp/. Play around. The users "noconnect" and "nosend" can't connect or send, respectively. Subscribing and unsubscribing to the destination "auto" causes autosubscriptions and autounsubscriptions to "room1", "room2", and "room3". Also, whenever a user sends a message, the sample RestQ callback recipient replaces "apples" with "bananas" in the message body.

Now You're Ready

At this point, you should be able to write your own RestQ callback recipient without too much trouble. If you're extending an existing web application, chances are you'll just want to add a resource (such as http://example.com/mywebapplication/restq/) to handle everything in the same process, thus exposing all the data RestQ has to offer to the rest of your logic. If not, don't be afraid to modify the sample RestQ callback recipient that ships with MorbidQ to fit your needs.