wiki:WikiStart
Last modified 4 years ago Last modified on 01/28/10 20:46:28

Kamaloka-js: AMQP bindings for native JavaScript

home | faq | developer documents

About

Kamaloka-js is an implementation of the AMQP messaging protocol (http://amqp.org/) in native JavaScript. It is setup to be used with Orbited (http://orbited.org/) but can be used with any library which produce TCPSockets in the browser similar to Orbited. Kamaloka bindings are generated from qpid XML protocol description files.

Status

You can currently :

  • negotiate a connection with an AMQP 0.10 server
  • issue any commands and controls described by the spec (some types still not be supported)
  • Use the new Receiver/Sender? and addressing API which is being developed as a bridge between the 0.10 and 1.0 protocol specs
  • Handle multiple frames and channels
  • tested on FireFox 3.5, Chromium devel builds (WebKit), Midori (WebKit), Opera 10, Konqueror 4.3.1 (khtml) - may work on older versions of these browsers and other browsers which use similar engines

Some limitation:

  • we don't do automatic version negotiation, but then we only implement one version
  • Transactions aren't supported directly in sessions (though you do have access to the underlying protocol support)
  • Message ACK's aren't handled internally
  • doesn't work on IE yet

Playground

Included in the distribution is a playground for testing the bindings in interesting AMQP configurations on your local machine. As pieces get implemented the playground will expand to show off different ways of using the bindings. Below is an example of using the current pub/sub high level bindings based off the python subscribe example.

<script src="/static/Orbited.js"></script>
<script src="/javascript/jsio/jsio.js"></script>

<script type="text/JavaScript">
    Orbited.settings.port = 9000;
    amqp_broker_port = 7000;

    jsio("import qpid_amqp as amqp");
    jsio("from amqp.protocol import register");
    // load the 0.10 version of the protocol
    register("amqp.protocol_0_10");

    amqp_conn = amqp.Connection({host: 'localhost',
                                 port: amqp_broker_port,
                                 socket_cls: Orbited.TCPSocket
                                });

    // You should have your server generate a UUID since browser methods
    // are unreliable at best
    var session_id = 'not_a_great_id' + (new Date().getTime() + Math.random());
    session = amqp_conn.session(session_id);
    
    var output_cb = function() {
        var msg = this.fetch();
        alert(msg.get('_body'));
    }
 
    var receiver = session.receiver('amq.topic/org.j5live.*');
    receiver.onReady = output_cb;
    receiver.capacity(0xFFFFFFFF);
    
    // test a multi segment transfer
    var sender = session.sender('amq.topic/org.j5live.test;');
    sender.send('Test Transfer From Browser');
</script>

To run this example:

  • get the code and all the dependencies (read the README file which comes with the code for more details)
  • run the update_playground.py python script - this will generate up to date bindings and copy the files to the playground
  • cd into the playground directory and start the services with the forwarding-brokers-test.sh script - make sure ports 6000, 7000 and 9000 are free
    • port 6000 - main broker that messages are published to
    • port 7000 - relay broker for testing federation, the example attaches to this to receive the messages being sent to the main broker
    • port 9000 - orbited proxy server runs on this port - as long as this server runs on the same host/port the orbited files are served from any of the other services can be run on any port or host provided the configuration is set up correctly
  • after the services are started simply point a supported browser to http://localhost:9000/ to see the example in action - if port 9000 is accessible from outside the host you can even use an external browser to run the test
  • cd into the python_examples directory and run the topic_publisher.py script - messages should start to pop up in the browser

On a Fedora machine these steps can be accomplished in a terminal:

> sudo yum install orbited 
> git clone http://git.fedorahosted.org/git/kamaloka-js.git
> cd kamaloka-js
> python update_playground.py
> cd playground
> ./forwarding-brokers-test.sh start

start your favorite browser and point it to http://localhost:9000/

> cd python_examples
> python topic_publisher.py

Get Involved

Releases

Latest Release

kamaloka-0.9.0 - Jan 28, 2010

Download

Released by John (J5) Palmieri <johnp@…>

  • Rework API to conform to the new Sender/Reciever? API and addressing format
  • Supports multi-channel/multi-frame parts of the spec
  • Uses js.io class infrastructure
  • Generated code now easier to read with decoders implemented in a class hierarchy
  • Rewritten dispatch layer - event code now works on the message layer instead of the frame layer even for low level dispatching
  • Much closer to implementing 100% of the 0.10 spec
  • Infrastructure in place to start working on the 1.0 spec

kamaloka-0.1.0 - Sep 23, 2009

Download

Released by John (J5) Palmieri <johnp@…>

  • Initial release
  • Connection handshaking works
  • AMQP lowlevel bindings for version 0.10 of the AMQP Protocol mostly complete
  • Higher level bindings implementing the publisher/subscriber pattern is ready for use

home | faq | developer documents