Centrifugo HTTP API client in Ruby.
Installation
Add this line to your application's Gemfile:
gem 'cent' And then execute:
$ bundle
Or install it yourself as:
$ gem install cent
Usage
Functionality is split between two classes:
-
Cent::Clientto call API methods -
Cent::Notaryto generate tokens
Token Generation
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.
RSA
secret = OpenSSL::PKey::RSA.new(File.read('./rsa_secret.pem'))
notary = Cent::Notary.new(secret: secret, algorithm: 'RS256')ECDSA
secret = OpenSSL::PKey::EC.new(File.read('./ecdsa_secret.pem'))
notary = Cent::Notary.new(secret: secret, algorithm: 'ES256')Connection token
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..."Private channel token
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..."API Client
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
endPublish
Send data to the channel.
client.publish(channel: 'chat', data: 'hello') # => {}Broadcast
Sends data to multiple channels.
client.broadcast(channels: ["clients", "staff"], data: 'hello') # => {}Unsubscribe
Unsubscribe user from channel. Receives to arguments: channel and user (user ID you want to unsubscribe)
client.unsubscribe(channel: 'chat', user: '1') # => {}Disconnect
Allows to disconnect user by it's ID. Receives user ID as an argument.
# Disconnect user with `id = 1`
#
client.disconnect(user: '1') # => {}Presence
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'
# }
# }
# }
# }Presence stats
Get short channel presence information.
client.presence_stats(channel: 'chat')
# {
# "result" => {
# "num_clients" => 0,
# "num_users" => 0
# }
# }History
Get channel history information (list of last messages published into channel).
client.history(channel: 'chat')
# {
# 'result' => {
# 'publications' => [
# {
# 'data' => {
# 'text' => 'hello'
# }
# },
# {
# 'data' => {
# 'text' => 'hi!'
# }
# }
# ]
# }
# }Channels
Get list of active(with one or more subscribers) channels.
client.channels
# {
# 'result' => {
# 'channels' => [
# 'chat'
# ]
# }
# }Info
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' => ''
# }
# ]
# }
# }Errors
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"
endDevelopment
After 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.
Contributing
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.
License
The gem is available as open source under the terms of the MIT License.