Changes between Initial Version and Version 1 of RestQ

Timestamp:

09/17/09 18:19:00 (12 months ago)

Author:

mario (IP: 98.234.89.16)

Comment:

--

RestQ

@@ +1 @@
+= 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 [http://morbidq.com/svn/morbid/trunk/morbid/sample_restq/restq_dummy_daemon.py a sample RestQ callback recipient]. To try it out, first download [http://orbited.org/ 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 [http://morbidq.com/svn/morbid/trunk/morbid/sample_restq/restq_dummy_daemon.py 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, [http://morbidq.com/svn/morbid/trunk/morbid/sample_restq/restq_dummy_daemon.py 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 [http://morbidq.com/svn/morbid/trunk/morbid/sample_restq/restq_dummy_daemon.py the sample RestQ callback recipient that ships with MorbidQ] to fit your needs.