{"id":20770609,"url":"https://github.com/ably/ably-ruby","last_synced_at":"2025-04-13T00:46:14.774Z","repository":{"id":21071124,"uuid":"24370613","full_name":"ably/ably-ruby","owner":"ably","description":"Ruby client library SDK for Ably realtime messaging service","archived":false,"fork":false,"pushed_at":"2025-04-03T10:24:47.000Z","size":3946,"stargazers_count":38,"open_issues_count":37,"forks_count":19,"subscribers_count":24,"default_branch":"main","last_synced_at":"2025-04-13T00:46:09.016Z","etag":null,"topics":["client-library","realtime","realtime-messaging","rest","ruby","sdk"],"latest_commit_sha":null,"homepage":"https://ably.com/download","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ably.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-09-23T12:33:47.000Z","updated_at":"2025-02-21T20:24:00.000Z","dependencies_parsed_at":"2024-01-08T18:03:36.702Z","dependency_job_id":"1c3ff402-e93b-4d6c-803b-ece5d0964a67","html_url":"https://github.com/ably/ably-ruby","commit_stats":{"total_commits":1441,"total_committers":26,"mean_commits":55.42307692307692,"dds":0.3566967383761277,"last_synced_commit":"e9a8a60cb55f8c30a2b1d98f2f745ae08fdd1c81"},"previous_names":[],"tags_count":58,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ably%2Fably-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ably%2Fably-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ably%2Fably-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ably%2Fably-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ably","download_url":"https://codeload.github.com/ably/ably-ruby/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248650432,"owners_count":21139672,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client-library","realtime","realtime-messaging","rest","ruby","sdk"],"created_at":"2024-11-17T12:10:46.525Z","updated_at":"2025-04-13T00:46:14.750Z","avatar_url":"https://github.com/ably.png","language":"Ruby","readme":"# [Ably](https://ably.com)\n\n[![Features](https://github.com/ably/ably-ruby/actions/workflows/features.yml/badge.svg)](https://github.com/ably/ably-ruby/actions/workflows/features.yml)\n\n[![Gem Version](https://img.shields.io/gem/v/ably?style=flat)](https://img.shields.io/gem/v/ably?style=flat)\n[![Coverage Status](https://coveralls.io/repos/ably/ably-ruby/badge.svg)](https://coveralls.io/r/ably/ably-ruby)\n\n_[Ably](https://ably.com) is the platform that powers synchronized digital experiences in realtime. Whether attending an event in a virtual venue, receiving realtime financial information, or monitoring live car performance data – consumers simply expect realtime digital experiences as standard. Ably provides a suite of APIs to build, extend, and deliver powerful digital experiences in realtime for more than 250 million devices across 80 countries each month. Organizations like Bloomberg, HubSpot, Verizon, and Hopin depend on Ably’s platform to offload the growing complexity of business-critical realtime data synchronization at global scale. For more information, see the [Ably documentation](https://ably.com/documentation)._\n\nThis is a Ruby client library for Ably. The library currently targets the [Ably 2.0.0 client library specification](https://ably.com/documentation/client-lib-development-guide/features/). You can see the complete list of features this client library supports in [our client library SDKs feature support matrix](https://ably.com/download/sdk-feature-support-matrix).\n\n## Supported platforms\n\nThis SDK supports Ruby 2.7 and 3.x. For eventmachine and Ruby 3.x note please visit [Ruby 3.0 support](#ruby-30-support) section.\n\nAs of v1.1.5 this library requires `libcurl` as a system dependency. On most systems this is already installed but in rare cases where it isn't (for example debian-slim Docker images such as ruby-slim) you will need to install it yourself. On debian you can install it with the command `sudo apt-get install libcurl4`.\n\nWe regression-test the SDK against a selection of Ruby versions (which we update over time, but usually consists of mainstream and widely used versions). Please refer to [.github/workflows/check.yml](./.github/workflows/check.yml) for the set of versions that currently undergo CI testing.\n\nIf you find any compatibility issues, please [do raise an issue](https://github.com/ably/ably-ruby/issues/new) in this repository or [contact Ably customer support](https://ably.com/support/) for advice.\n\n## Documentation\n\nVisit https://ably.com/documentation for a complete API reference and code examples.\n\n## Installation\n\nThe client library is available as a [gem from RubyGems.org](https://rubygems.org/gems/ably).\n\nAdd this line to your application's Gemfile:\n\n    gem 'ably'\n\nAnd then install this Bundler dependency:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install ably\n\n### Using with Rails or Sinatra\n\nThis `ably` gem provides both a [Realtime](https://ably.com/documentation/realtime/usage) and [REST](https://ably.com/documentation/rest/usage) 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.\n\nIf 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](https://github.com/ably/ably-ruby-rest).\n\n## Using the Realtime API\n\n### Introduction\n\nAll examples must be run within an [EventMachine](https://github.com/eventmachine/eventmachine) [reactor](https://github.com/eventmachine/eventmachine/wiki/General-Introduction) as follows:\n\n```ruby\nEventMachine.run do\n  # ...\nend\n```\n\nAll examples assume a client has been created using one of the following:\n\n```ruby\n# basic auth with an API key\nclient = Ably::Realtime.new(key: 'xxxxx')\n\n# using token auth\nclient = Ably::Realtime.new(token: 'xxxxx')\n```\n\nIf you do not have an API key, [sign up for a free API key now](https://ably.com/signup)\n\n### Connection\n\nSuccessful connection:\n\n```ruby\nclient.connection.connect do\n  # successful connection\nend\n```\n\nFailed connection:\n\n```ruby\nconnection_result = client.connection.connect\nconnection_result.errback = Proc.new do\n  # failed connection\nend\n```\n\nSubscribing to connection state changes:\n\n```ruby\nclient.connection.on do |state_change|\n  state_change.current #=\u003e :connected\n  state_change.previous #=\u003e :connecting\nend\n```\n\nRetrieve connection id, state etc\n\n```ruby\nconnection_id = client.connection.id\nstate = client.connection.state\nrecovery_key = client.connection.create_recovery_key # https://ably.com/docs/connect/states?q=recovery#connection-state-recover-options\n```\n\n### Subscribing to a channel\n\nGiven a channel is created as follows:\n\n```ruby\nchannel = client.channels.get('test')\n```\n\nSubscribe to all events:\n\n```ruby\nchannel.subscribe do |message|\n  message.name #=\u003e \"greeting\"\n  message.data #=\u003e \"Hello World!\"\nend\n```\n\nOnly certain events:\n\n```ruby\nchannel.subscribe('myEvent') do |message|\n  message.name #=\u003e \"myEvent\"\n  message.data #=\u003e \"myData\"\nend\n```\n\n### Publishing a message to a channel\n\n```ruby\nchannel.publish('greeting', 'Hello World!')\n```\n\n### Querying the History\n\n```ruby\nchannel.history do |messages_page|\n  messages_page #=\u003e #\u003cAbly::Models::PaginatedResult ...\u003e\n  messages_page.items.first # #\u003cAbly::Models::Message ...\u003e\n  messages_page.items.first.data # payload for the message\n  messages_page.items.length # number of messages in the current page of history\n  messages_page.next do |next_page|\n    next_page #=\u003e the next page =\u003e #\u003cAbly::Models::PaginatedResult ...\u003e\n  end\n  messages_page.has_next? # false, there are more pages\nend\n```\n\n### Presence on a channel\n\n```ruby\nchannel.presence.enter(data: 'metadata') do |presence|\n  presence.get do |members|\n    members #=\u003e [Array of members present]\n  end\nend\n```\n\n### Subscribing to presence events\n\n```ruby\nchannel.presence.subscribe do |member|\n  member #=\u003e { action: :enter, client_id: 'bob' }\nend\n```\n\n### Querying the Presence History\n\n```ruby\nchannel.presence.history do |presence_page|\n  presence_page.items.first.action # Any of :enter, :update or :leave\n  presence_page.items.first.client_id # client ID of member\n  presence_page.items.first.data # optional data payload of member\n  presence_page.next do |next_page|\n    next_page #=\u003e the next page =\u003e #\u003cAbly::Models::PaginatedResult ...\u003e\n  end\n  presence_page.has_next? # false, there are more pages\nend\n```\n\n### Symmetric end-to-end encrypted payloads on a channel\n\nWhen 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.\n\n```ruby\nsecret_key = Ably::Util::Crypto.generate_random_key\nchannel = client.channels.get('test', cipher: { key: secret_key })\nchannel.subscribe do |message|\n  message.data #=\u003e \"sensitive data (encrypted before being published)\"\nend\nchannel.publish \"name (not encrypted)\", \"sensitive data (encrypted before being published)\"\n```\n\n## Using the REST API\n\n### Introduction\n\nUnlike the Realtime API, all calls are synchronous and are not run within [EventMachine](https://github.com/eventmachine/eventmachine).\n\nAll examples assume a client and/or channel has been created as follows:\n\n```ruby\nclient = Ably::Rest.new(key: 'xxxxx')\nchannel = client.channel('test')\n```\n\n### Publishing a message to a channel\n\n```ruby\nchannel.publish('myEvent', 'Hello!') #=\u003e true\n```\n\n### Querying the History\n\n```ruby\nmessages_page = channel.history #=\u003e #\u003cAbly::Models::PaginatedResult ...\u003e\nmessages_page.items.first #=\u003e #\u003cAbly::Models::Message ...\u003e\nmessages_page.items.first.data # payload for the message\nmessages_page.next # retrieves the next page =\u003e #\u003cAbly::Models::PaginatedResult ...\u003e\nmessages_page.has_next? # false, there are more pages\n```\n\n### Current presence members on a channel\n\n```ruby\nmembers_page = channel.presence.get # =\u003e #\u003cAbly::Models::PaginatedResult ...\u003e\nmembers_page.items.first # first member present in this page =\u003e #\u003cAbly::Models::PresenceMessage ...\u003e\nmembers_page.items.first.client_id # client ID of first member present\nmembers_page.next # retrieves the next page =\u003e #\u003cAbly::Models::PaginatedResult ...\u003e\nmembers_page.has_next? # false, there are more pages\n```\n\n### Querying the presence history\n\n```ruby\npresence_page = channel.presence.history #=\u003e #\u003cAbly::Models::PaginatedResult ...\u003e\npresence_page.items.first #=\u003e #\u003cAbly::Models::PresenceMessage ...\u003e\npresence_page.items.first.client_id # client ID of first member\npresence_page.next # retrieves the next page =\u003e #\u003cAbly::Models::PaginatedResult ...\u003e\n```\n\n### Symmetric end-to-end encrypted payloads on a channel\n\nWhen 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.\n\n```ruby\nsecret_key = Ably::Util::Crypto.generate_random_key\nchannel = client.channels.get('test', cipher: { key: secret_key })\nchannel.publish nil, \"sensitive data\" # data will be encrypted before publish\nmessages_page = channel.history\nmessages_page.items.first.data #=\u003e \"sensitive data\"\n```\n\n### Generate a Token\n\nTokens are issued by Ably and are readily usable by any client to connect to Ably:\n\n```ruby\ntoken_details = client.auth.request_token\n# =\u003e #\u003cAbly::Models::TokenDetails ...\u003e\ntoken_details.token # =\u003e \"xVLyHw.CLchevH3hF....MDh9ZC_Q\"\nclient = Ably::Rest.new(token: token_details)\n```\n\n### Generate a TokenRequest\n\nToken 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.\n\n```ruby\ntoken_request = client.auth.create_token_request(ttl: 3600, client_id: 'jim')\n# =\u003e {\"id\"=\u003e...,\n#     \"clientId\"=\u003e\"jim\",\n#     \"ttl\"=\u003e3600,\n#     \"timestamp\"=\u003e...,\n#     \"capability\"=\u003e\"{\\\"*\\\":[\\\"*\\\"]}\",\n#     \"nonce\"=\u003e...,\n#     \"mac\"=\u003e...}\n\nclient = Ably::Rest.new(token: token_request)\n```\n\n### Fetching your application's stats\n\n```ruby\nstats_page = client.stats #=\u003e #\u003cAbly::Models::PaginatedResult ...\u003e\nstats_page.items.first = #\u003cAbly::Models::Stats ...\u003e\nstats_page.next # retrieves the next page =\u003e #\u003cAbly::Models::PaginatedResult ...\u003e\n```\n\n### Fetching the Ably service time\n\n```ruby\nclient.time #=\u003e 2013-12-12 14:23:34 +0000\n```\n\n## Ruby 3.0 support\n\nIf you cannot install ably realtime gem because of eventmachine openssl problems, please try to set your `openssl-dir`, i.e.:\n\n```ruby\ngem install eventmachine -- --with-openssl-dir=/usr/local/opt/openssl@1.1\n```\n\nMore about eventmachine and ruby 3.0 support here https://github.com/eventmachine/eventmachine/issues/932\n\n## Dependencies\n\nIf 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](https://rubygems.org/gems/ably-rest).\n\n## Upgrading from an older version\n\n- [Release and upgrade notes for v0.8 -\u003e v1.0](https://github.com/ably/docs/issues/235)\n\n## Support, feedback and troubleshooting\n\nPlease visit https://ably.com/support for access to our knowledgebase and to ask for any assistance.\n\nYou can also view the [community reported Github issues](https://github.com/ably/ably-ruby/issues).\n\nTo see what has changed in recent versions of Bundler, see the [CHANGELOG](CHANGELOG.md).\n\n## Contributing\n\n1. Fork it\n2. When pulling to local, make sure to also pull the `ably-common` repo (`git submodule init \u0026\u0026 git submodule update`)\n3. Create your feature branch (`git checkout -b my-new-feature`)\n4. Commit your changes (`git commit -am 'Add some feature'`)\n5. Ensure you have added suitable tests and the test suite is passing(`bundle exec rspec`)\n6. Push to the branch (`git push origin my-new-feature`)\n7. Create a new Pull Request\n\n## Release process\n\nThis library uses [semantic versioning](http://semver.org/). For each release, the following needs to be done:\n\n1. Create a branch for the release, named like `release/1.2.3` (where `1.2.3` is the new version number)\n2. Update the version number in [version.rb](./lib/ably/version.rb) and commit the change.\n3. Run [`github_changelog_generator`](https://github.com/github-changelog-generator/github-changelog-generator) to automate the update of the [CHANGELOG](./CHANGELOG.md). This may require some manual intervention, both in terms of how the command is run and how the change log file is modified. Your mileage may vary:\n   - The command you will need to run will look something like this: `github_changelog_generator -u ably -p ably-ruby --since-tag v1.2.3 --output delta.md --token $GITHUB_TOKEN_WITH_REPO_ACCESS`. Generate token [here](https://github.com/settings/tokens/new?description=GitHub%20Changelog%20Generator%20token).\n   - Using the command above, `--output delta.md` writes changes made after `--since-tag` to a new file\n   - The contents of that new file (`delta.md`) then need to be manually inserted at the top of the `CHANGELOG.md`, changing the \"Unreleased\" heading and linking with the current version numbers\n   - Also ensure that the \"Full Changelog\" link points to the new version tag instead of the `HEAD`\n4. Commit this change: `git add CHANGELOG.md \u0026\u0026 git commit -m \"Update change log.\"`\n5. Ideally, run `rake doc:spec` to generate a new [spec file](./SPEC.md). Then commit these changes.\n6. Make a PR against `main`. Once the PR is approved, merge it into `main`.\n7. Add a tag to the new `main` head commit and push to origin such as `git tag v1.0.3 \u0026\u0026 git push origin v1.0.3`.\n8. Visit [https://github.com/ably/ably-ruby/tags](https://github.com/ably/ably-ruby/tags) and `Add release notes` for the release including links to the changelog entry.\n9. Run `rake release` to publish the gem to [Rubygems](https://rubygems.org/gems/ably).\n10. Release the [REST-only library `ably-ruby-rest`](https://github.com/ably/ably-ruby-rest#release-process).\n11. Create the entry on the [Ably Changelog](https://changelog.ably.com/) (via [headwayapp](https://headwayapp.co/)).\n","funding_links":[],"categories":["Third-party APIs"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fably%2Fably-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fably%2Fably-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fably%2Fably-ruby/lists"}