Centrifugo HTTP API client in Ruby.
Add this line to your application's Gemfile:
gem 'cent' And then execute:
$ bundle
Or install it yourself as:
$ gem install cent
Functionality is split between two classes:
Cent::Clientto call API methodsCent::Notaryto generate tokens
notary = Cent::Notary.new(secret: 'secret')By default it uses HS256 to generate tokens, but you can set it to one of the HMAC, RSA or ECDSA family.
secret = OpenSSL::PKey::RSA.new(File.read('./rsa_secret.pem'))
notary = Cent::Notary.new(secret: secret, algorithm: 'RS256')secret = OpenSSL::PKey::EC.new(File.read('./ecdsa_secret.pem'))
notary = Cent::Notary.new(secret: secret, algorithm: 'ES256')When connecting to Centrifugo client must provide connection JWT token with several predefined credential claims.
notary.issue_connection_token(sub: '42')
#=> "eyJhbGciOiJIUzI1NiJ9..."info and exp are supported as well:
notary.issue_connection_token(sub: '42', info: { scope: 'admin' }, exp: 1629050099)
#=> "eyJhbGciOiJIUzI1NiJ9..."All channels starting with $ considered private and require a channel token to subscribe. Private channel subscription token is also JWT(see the claims)
notary.issue_channel_token(sub: '42', channel: 'channel', exp: 1629050099, info: { scope: 'admin' })
#=> "eyJhbGciOiJIUzI1NiJ9..."A client requires your Centrifugo API key to execute all requests.
client = Cent::Client.new(api_key: 'key')you can customize your connection as you wish, just remember it's a Faraday::Connection instance:
client = Cent::Client.new(api_key: 'key', endpoint: 'https://centrifu.go/api') do |connection|
connection.headers['User-Agent'] = 'Centrifugo Ruby Client'
connection.options.open_timeout = 3
connection.options.timeout = 7
connection.adapter :typhoeus
endSend data to the channel.
client.publish(channel: 'chat', data: 'hello') # => {}Sends data to multiple channels.
client.broadcast(channels: ["clients", "staff"], data: 'hello') # => {}Unsubscribe user from channel. Receives to arguments: channel and user (user ID you want to unsubscribe)
client.unsubscribe(channel: 'chat', user: '1') # => {}Allows to disconnect user by it's ID. Receives user ID as an argument.
# Disconnect user with `id = 1`
#
client.disconnect(user: '1') # => {}Get channel presence information(all clients currently subscribed on this channel).
client.presence(channel: 'chat')
# {
# 'result' => {
# 'presence' => {
# 'c54313b2-0442-499a-a70c-051f8588020f' => {
# 'client' => 'c54313b2-0442-499a-a70c-051f8588020f',
# 'user' => '42'
# },
# 'adad13b1-0442-499a-a70c-051f858802da' => {
# 'client' => 'adad13b1-0442-499a-a70c-051f858802da',
# 'user' => '42'
# }
# }
# }
# }Get short channel presence information.
client.presence_stats(channel: 'chat')
# {
# "result" => {
# "num_clients" => 0,
# "num_users" => 0
# }
# }Get channel history information (list of last messages published into channel).
client.history(channel: 'chat')
# {
# 'result' => {
# 'publications' => [
# {
# 'data' => {
# 'text' => 'hello'
# }
# },
# {
# 'data' => {
# 'text' => 'hi!'
# }
# }
# ]
# }
# }Get list of active(with one or more subscribers) channels.
client.channels
# {
# 'result' => {
# 'channels' => [
# 'chat'
# ]
# }
# }Get running Centrifugo nodes information.
client.info
# {
# 'result' => {
# 'nodes' => [
# {
# 'name' => 'Alexanders-MacBook-Pro.local_8000',
# 'num_channels' => 0,
# 'num_clients' => 0,
# 'num_users' => 0,
# 'uid' => 'f844a2ed-5edf-4815-b83c-271974003db9',
# 'uptime' => 0,
# 'version' => ''
# }
# ]
# }
# }Network errors are not wrapped and will raise Faraday::ClientError.
In cases when Centrifugo returns 200 with error key in the body we wrap it and return custom error:
# Raised when response from Centrifugo contains any error as result of API command execution.
#
begin
client.publish(channel: 'channel', data: { foo: :bar })
rescue Cent::ResponseError => ex
ex.message # => "Invalid format"
endAfter checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/centrifugal/rubycent. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
The gem is available as open source under the terms of the MIT License.