Kosmonaut - ruby client for the WebRocket
=========================================

Kosmonaut.rb is a ruby backend client for the WebRocket.
The idea of the Kosmonaut is to keep it simple, straightforward
and easy to maintain, although to allow to build more
sophisticated libraries at top of it.

Installation
------------
You can install it easily from rubygems:

    $ gem install kosmonaut

Or using bundler, add this line to your gemfile:

    gem 'kosmonaut'

Usage
-----
Kosmonaut has two components: Client and Worker. Client is
used to manage a WebRocket's vhost and broadcast messages,
for example:

    c = Kosmonaut::Client.new("wr://token@127.0.0.1:8081/vhost")
    c.open_channel("world")
    c.broadcast("world", "hello", {:who => "Chris"})
    c.broadcast("world", "bye", {:see_you_when => "Soon!"})
    c.request_single_access_token(".*")

Worker is used to listen for incoming messages and handle
it in user's desired way, example:

    class ChatBackend
      # This method will be triggered on 'chat/save_to_history' event.
      def save_to_history(msg)
        room.find(msg[:room])
        room.history.append(msg)
      end
    end

    Kosmonaut::Application.build "wr://token@127.0.0.1:8081/vhost" do
      use ChatBackend, :as => "chat"
      run
    end

Hacking
-------
If you want to run kosmonaut.rb in development mode, first clone
the repo and install dependencies:

    $ git clone https://github.com/webrocket/kosmonaut.rb.git
    $ cd kosmonaut.rb
    $ bundle

To run the tests you should have a `webrocket-server` instance
running with a `/test` vhost created. To create it use the
`webrocket-admin` tool:

    $ webrocket-admin add_vhost /test
    /test
    a70d7d2c0bc5761620948b3420d18df9072ca0d1

Now get the access token and run kosmonaut's tests using
rake task:

    $ VHOST_TOKEN=a70d7d2c0bc5761620948b3420d18df9072ca0d1 rake test

If you want to get debug output add a `DEBUG` environment variable
while running tests:

    $ VHOST_TOKEN=... DEBUG=1 rake test

With any quirks and doubts don't hesitate to start a github issue
or email one of the maintainers.
   
Sponsors
--------
All the work on the project is sponsored and supported by Cubox - an
awesome dev shop from Uruguay <http://cuboxlabs.com>.
   
Copyright
---------
Copyright (C) 2012 Krzysztof Kowalik <chris@nu7hat.ch> and folks at Cubox

Released under the MIT license. See COPYING for details.