# Centrifuge
[![Code Climate](https://codeclimate.com/github/centrifugal/centrifuge-ruby/badges/gpa.svg)](https://codeclimate.com/github/centrifugal/centrifuge-ruby)
[![Build Status](https://travis-ci.org/centrifugal/centrifuge-ruby.svg)](https://travis-ci.org/centrifugal/centrifuge-ruby)

Ruby gem for [Centrifuge](https://github.com/centrifugal/centrifuge) real-time messaging broker

## Installation

Add this line to your application's Gemfile:

```ruby
	gem 'centrifuge'
```

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install centrifuge

## Compatibility

Centrifuge-ruby 1.0.0+ supports only Centrifuge version 1.0.0+ with single project only.
If you want to use multiproject Centrifuge, please use centrifuge-ruby 0.1.0

## Usage

`Centrifuge::Client` - is main usable class. Start with:

```ruby
	client = Centrifuge::Client.new(scheme: :http, host: :localhost, port: 80, secret: 'cde')
```

Or just:

```ruby
	Centrifuge.scheme = :http
	Centrifuge.host = 'localhost'
	Centrifuge.port = 8000
	Centrifuge.secret = 'def'
```

There are six methods available:

### Publish

Sends message to all connected users:

```ruby
	client.publish('teshchannel', { data: :foo })
```

You can also use class methods if you set all necessary config data:

```ruby
	Centrifuge.publish('testchannel', { data: :foo })
```

### Unsubscribe

Unsubscribes user from channel:

```ruby
	client.unsubscribe('testchannel', 'user#23')
```

`user#23` - is string identificator of user.

### Disconnect

Disconnects user from Centrifuge:

```ruby
	client.disconnect('user#23')
```
### Presence

Gets presence info of the channel:

```ruby
	client.presence('testchannel')
```
### History

Gets message history of the channel:

```ruby
	client.history('test_channel')
```

### Channels

Get active channels (with one or more subscribers):

```ruby
	client.channels()
```

### JS Client token generation

Generates token for JS client:

```ruby
	client.token_for('testuser', '1443422448')
```
Where `1443422448` is UNIX timestamp seconds. You can also add user info as valid json string as third parameter:

```ruby
	client.token_for('testuser', '1443422448', "{}")
```
### Channel Sign token generation

Generates Sign token for a Channel:

```ruby
client.generate_channel_sign(params[:client], params[:channels], "{}")
```

Where ```params[:client]``` is client passed during authentication and ```params[:channels]``` can be an array of channels or a single channel. You can read more here about batching channels here [JS Documentation](https://fzambia.gitbooks.io/centrifugal/content/client/api.html).

You can also add user info as valid json string as third parameter:

```ruby
client.generate_channel_sign(params[:client], params[:channels], "{"name": "John"}")
```

On server side using rails, you can authenticate private channels like so:

```ruby

	#routes.rb or any router lib
	post 'sockets/auth'

	# Auth method to authenticate private channels
	#sockets_controller.rb or anywhere in your app

	# client = Instance of Centrifuge initialized // check Usage section
	# params[:channels] = single/array of channels
	def auth
	  if user_signed_in? # Or use a before_filter
	    data = {}
	    sign = client.generate_channel_sign(
	        params[:client], params[:channels], "{}"
	    )
	    data[channel] = {
	        "sign": sign,
	        "info": "{}"
	    }
	    render :json => data
	  else
	    render :text => "Not authorized", :status => '403'
	  end
	end
```
On client side initialize Centrifuge like so:

``` javascript

	// client_info = valid JSON string of user_info
	// client_token = client.token_for (described above)

	var centrifuge = new Centrifuge({
	   url: "http://localhost:8000/connection",
	   user: window.currentUser.id,
	   timestamp: window.currentUser.current_timestamp,
	   debug: true,
	   info: JSON.stringify(window.client_info),
	   token: window.client_token,
	   refreshEndpoint: "/sockets/refresh",
	   authEndpoint: "/sockets/auth",
	   authHeaders: {
	      'X-Transaction': 'WebSocket Auth',
	      'X-CSRF-Token': window.currentUser.form_authenticity_token
	   },
	   refreshHeaders: {
	      'X-Transaction': 'WebSocket Auth',
	      'X-CSRF-Token': window.currentUser.form_authenticity_token
	   }
	 });

	centrifuge.connect();

	// If you using jbuiler use raw render(template_name) and use a global window object to load the user information.
```

If you want to batch sign channels request to avoid multiple HTTP requests, you can use centrifuge JS client to batch channels ```centrifuge.startBatching(); // your code // centrifuge.stopBatching();``` in one request and on the server iterate through channels and subscribe.

Read more: [JS client Documentation](https://fzambia.gitbooks.io/centrifugal/content/client/api.html)

### API request sign

When you use Centrifugo server API you should sign each request to successfully authorize with the server.

```ruby

	# For example this is how you would encode a Publish command
	commands = {
		"method": "publish",
	  	"params": {
			"channel": "Test",
		  	"data": { "name": "John Doe" }
	  	}
	}

	encoded_data = MultiJson.dump(commands) # Or use to_json
	sign = client.sign(encoded_data) #Sign the data

	# Using HTTP party GEM interact with Server API
	r = HTTParty.post(client.url.to_s, query: {"sign": sign, "data": encoded_data})
	r.parsed_response

```

```encoded_data``` is a JSON string with your API command/commands. See all available commands in [Server API](https://fzambia.gitbooks.io/centrifugal/content/server/api.html) chapter.


## Rails assets

To use Centrifuge js client just add this line to your application.js manifest:

	//= require centrifuge

If you want to use sockjs require it before centrifuge:

	//= require sockjs
	//= require centrifuge

### Other API

Other API methods, like projects and channels management are unavailable now.

## Contributing

1. Fork it ( https://github.com/centrifugal/centrifuge-ruby/fork )
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create a new Pull Request