A Ruby client library for ably.io, the realtime messaging service.
Visit https://www.ably.io/documentation for a complete API reference and more examples.
The client library is available as a gem from RubyGems.org.
Add this line to your application's Gemfile:
gem 'ably'
And then install this Bundler dependency:
$ bundle
Or install it yourself as:
$ gem install ably
This ably
gem provides both a Realtime and REST version of the Ably library. Realtime depends on EventMachine to provide an asynchronous evented framework to run the library in, whereas the REST library depends only on synchronous libraries such as Faraday.
If you are using Ably within your Rails or Sinatra apps, more often than not, you probably want to use the REST only version of the library that has no dependency on EventMachine and provides a synchronous API that you will be used to using within Rails and Sinatra. See the REST only Ruby version of the Ably library.
All examples must be run within an EventMachine reactor as follows:
EventMachine.run do
# ...
end
All examples assume a client has been created using one of the following:
# basic auth with an API key
client = Ably::Realtime.new(key: 'xxxxx')
# using token auth
client = Ably::Realtime.new(token: 'xxxxx')
If you do not have an API key, sign up for a free API key now
Successful connection:
client.connection.connect do
# successful connection
end
Failed connection:
connection_result = client.connection.connect
connection_result.errback = Proc.new do
# failed connection
end
Subscribing to connection state changes:
client.connection.on do |state_change|
state_change.current #=> :connected
state_change.previous #=> :connecting
end
Given a channel is created as follows:
channel = client.channels.get('test')
Subscribe to all events:
channel.subscribe do |message|
message.name #=> "greeting"
message.data #=> "Hello World!"
end
Only certain events:
channel.subscribe('myEvent') do |message|
message.name #=> "myEvent"
message.data #=> "myData"
end
channel.publish('greeting', 'Hello World!')
channel.history do |messages_page|
messages_page #=> #<Ably::Models::PaginatedResult ...>
messages_page.items.first # #<Ably::Models::Message ...>
messages_page.items.first.data # payload for the message
messages_page.items.length # number of messages in the current page of history
messages_page.next do |next_page|
next_page #=> the next page => #<Ably::Models::PaginatedResult ...>
end
messages_page.has_next? # false, there are more pages
end
channel.presence.enter(data: 'metadata') do |presence|
presence.get do |members|
members #=> [Array of members present]
end
end
channel.presence.subscribe do |member|
member #=> { action: :enter, client_id: 'bob' }
end
channel.presence.history do |presence_page|
presence_page.items.first.action # Any of :enter, :update or :leave
presence_page.items.first.client_id # client ID of member
presence_page.items.first.data # optional data payload of member
presence_page.next do |next_page|
next_page #=> the next page => #<Ably::Models::PaginatedResult ...>
end
presence_page.has_next? # false, there are more pages
end
When a 128 bit or 256 bit key is provided to the library, all payloads are encrypted and decrypted automatically using that key on the channel. The secret key is never transmitted to Ably and thus it is the developer's responsibility to distribute a secret key to both publishers and subscribers.
secret_key = Ably::Util::Crypto.generate_random_key
channel = client.channels.get('test', cipher: { key: secret_key })
channel.subscribe do |message|
message.data #=> "sensitive data (encrypted before being published)"
end
channel.publish "name (not encrypted)", "sensitive data (encrypted before being published)"
Unlike the Realtime API, all calls are synchronous and are not run within an EventMachine reactor.
All examples assume a client and/or channel has been created as follows:
client = Ably::Rest.new(key: 'xxxxx')
channel = client.channel('test')
channel.publish('myEvent', 'Hello!') #=> true
messages_page = channel.history #=> #<Ably::Models::PaginatedResult ...>
messages_page.items.first #=> #<Ably::Models::Message ...>
messages_page.items.first.data # payload for the message
messages_page.next # retrieves the next page => #<Ably::Models::PaginatedResult ...>
messages_page.has_next? # false, there are more pages
members_page = channel.presence.get # => #<Ably::Models::PaginatedResult ...>
members_page.items.first # first member present in this page => #<Ably::Models::PresenceMessage ...>
members_page.items.first.client_id # client ID of first member present
members_page.next # retrieves the next page => #<Ably::Models::PaginatedResult ...>
members_page.has_next? # false, there are more pages
presence_page = channel.presence.history #=> #<Ably::Models::PaginatedResult ...>
presence_page.items.first #=> #<Ably::Models::PresenceMessage ...>
presence_page.items.first.client_id # client ID of first member
presence_page.next # retrieves the next page => #<Ably::Models::PaginatedResult ...>
When a 128 bit or 256 bit key is provided to the library, all payloads are encrypted and decrypted automatically using that key on the channel. The secret key is never transmitted to Ably and thus it is the developer's responsibility to distribute a secret key to both publishers and subscribers.
secret_key = Ably::Util::Crypto.generate_random_key
channel = client.channels.get('test', cipher: { key: secret_key })
channel.publish nil, "sensitive data" # data will be encrypted before publish
messages_page = channel.history
messages_page.items.first.data #=> "sensitive data"
Tokens are issued by Ably and are readily usable by any client to connect to Ably:
token_details = client.auth.request_token
# => #<Ably::Models::TokenDetails ...>
token_details.token # => "xVLyHw.CLchevH3hF....MDh9ZC_Q"
client = Ably::Rest.new(token: token_details)
Token requests are issued by your servers and signed using your private API key. This is the preferred method of authentication as no secrets are ever shared, and the token request can be issued to trusted clients without communicating with Ably.
token_request = client.auth.create_token_request(ttl: 3600, client_id: 'jim')
# => {"id"=>...,
# "clientId"=>"jim",
# "ttl"=>3600,
# "timestamp"=>...,
# "capability"=>"{\"*\":[\"*\"]}",
# "nonce"=>...,
# "mac"=>...}
client = Ably::Rest.new(token: token_request)
stats_page = client.stats #=> #<Ably::Models::PaginatedResult ...>
stats_page.items.first = #<Ably::Models::Stats ...>
stats_page.next # retrieves the next page => #<Ably::Models::PaginatedResult ...>
client.time #=> 2013-12-12 14:23:34 +0000
If you only need to use the REST features of this library and do not want EventMachine as a dependency, then you should consider using the Ably Ruby REST gem.
Please visit http://support.ably.io/ for access to our knowledgebase and to ask for any assistance.
You can also view the community reported Github issues.
To see what has changed in recent versions of Bundler, see the CHANGELOG.
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Ensure you have added suitable tests and the test suite is passing(
bundle exec rspec
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request
This library uses semantic versioning. For each release, the following needs to be done:
- Update the version number in version.rb and commit the change.
- Run
github_changelog_generator
to automate the update of the CHANGELOG. Once theCHANGELOG
update has completed, manually change theUnreleased
heading and link with the current version number such asv1.0.0
. Also ensure that theFull Changelog
link points to the new version tag instead of theHEAD
. Commit this change. - Add a tag and push to origin such as
git tag v1.0.0 && git push origin v1.0.0
- Run
rake release
to publish the gem to Rubygems
Copyright (c) 2016 Ably Real-time Ltd, Licensed under the Apache License, Version 2.0. Refer to LICENSE for the license terms.