{"id":13880499,"url":"https://github.com/pusher/pusher-http-ruby","last_synced_at":"2025-12-29T23:28:38.158Z","repository":{"id":424398,"uuid":"502150","full_name":"pusher/pusher-http-ruby","owner":"pusher","description":"Ruby library for Pusher Channels HTTP API","archived":false,"fork":false,"pushed_at":"2023-07-04T12:28:50.000Z","size":541,"stargazers_count":665,"open_issues_count":4,"forks_count":124,"subscribers_count":26,"default_branch":"master","last_synced_at":"2025-07-11T05:38:03.605Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://pusher.com/channels","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pusher.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}},"created_at":"2010-02-04T12:39:28.000Z","updated_at":"2025-06-19T12:39:00.000Z","dependencies_parsed_at":"2023-07-05T14:53:24.776Z","dependency_job_id":null,"html_url":"https://github.com/pusher/pusher-http-ruby","commit_stats":{"total_commits":485,"total_committers":70,"mean_commits":6.928571428571429,"dds":0.5608247422680412,"last_synced_commit":"18109ec781501c673fb1853869cf89f8ed27296d"},"previous_names":[],"tags_count":68,"template":false,"template_full_name":null,"purl":"pkg:github/pusher/pusher-http-ruby","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pusher%2Fpusher-http-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pusher%2Fpusher-http-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pusher%2Fpusher-http-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pusher%2Fpusher-http-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pusher","download_url":"https://codeload.github.com/pusher/pusher-http-ruby/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pusher%2Fpusher-http-ruby/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265527540,"owners_count":23782480,"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":[],"created_at":"2024-08-06T08:03:05.155Z","updated_at":"2025-12-29T23:28:38.104Z","avatar_url":"https://github.com/pusher.png","language":"Ruby","readme":"# Gem for Pusher Channels\n\nThis Gem provides a Ruby interface to [the Pusher HTTP API for Pusher Channels](https://pusher.com/docs/channels/library_auth_reference/rest-api).\n\n[![Build Status](https://github.com/pusher/pusher-http-ruby/workflows/Tests/badge.svg)](https://github.com/pusher/pusher-http-ruby/actions?query=workflow%3ATests+branch%3Amaster) [![Gem](https://img.shields.io/gem/v/pusher)](https://rubygems.org/gems/pusher) [![Gem](https://img.shields.io/gem/dt/pusher)](https://rubygems.org/gems/pusher)\n\n## Supported Platforms\n\n* Ruby - supports **Ruby 2.6 or greater**.\n\n## Installation and Configuration\n\nAdd `pusher` to your Gemfile, and then run `bundle install`\n\n``` ruby\ngem 'pusher'\n```\n\nor install via gem\n\n``` bash\ngem install pusher\n```\n\nAfter registering at [Pusher](https://dashboard.pusher.com/accounts/sign_up), configure your Channels app with the security credentials.\n\n### Instantiating a Pusher Channels client\n\nCreating a new Pusher Channels `client` can be done as follows.\n\n``` ruby\nrequire 'pusher'\n\npusher = Pusher::Client.new(\n  app_id: 'your-app-id',\n  key: 'your-app-key',\n  secret: 'your-app-secret',\n  cluster: 'your-app-cluster',\n  use_tls: true\n)\n```\n\nThe `cluster` value will set the `host` to `api-\u003ccluster\u003e.pusher.com`. The `use_tls` value is optional and defaults to `true`. It will set the `scheme` and `port`. A custom `port` value takes precendence over `use_tls`.\n\nIf you want to set a custom `host` value for your client then you can do so when instantiating a Pusher Channels client like so:\n\n``` ruby\nrequire 'pusher'\n\npusher = Pusher::Client.new(\n  app_id: 'your-app-id',\n  key: 'your-app-key',\n  secret: 'your-app-secret',\n  host: 'your-app-host'\n)\n```\n\nIf you pass both `host` and `cluster` options, the `host` will take precendence and `cluster` will be ignored.\n\nFinally, if you have the configuration set in an `PUSHER_URL` environment\nvariable, you can use:\n\n``` ruby\npusher = Pusher::Client.from_env\n```\n\n### Global configuration\n\nThe library can also be configured globally on the `Pusher` class.\n\n``` ruby\nPusher.app_id = 'your-app-id'\nPusher.key = 'your-app-key'\nPusher.secret = 'your-app-secret'\nPusher.cluster = 'your-app-cluster'\n```\n\nGlobal configuration will automatically be set from the `PUSHER_URL` environment variable if it exists. This should be in the form  `http://KEY:SECRET@HOST/apps/APP_ID`. On Heroku this environment variable will already be set.\n\nIf you need to make requests via a HTTP proxy then it can be configured\n\n``` ruby\nPusher.http_proxy = 'http://(user):(password)@(host):(port)'\n```\n\nBy default API requests are made over HTTPS. HTTP can be used by setting `use_tls` to `false`.\nIssuing this command is going to reset `port` value if it was previously specified.\n\n``` ruby\nPusher.use_tls = false\n```\n\nAs of version 0.12, SSL certificates are verified when using the synchronous http client. If you need to disable this behaviour for any reason use:\n\n``` ruby\nPusher.default_client.sync_http_client.ssl_config.verify_mode = OpenSSL::SSL::VERIFY_NONE\n```\n\n## Interacting with the Channels HTTP API\n\nThe `pusher` gem contains a number of helpers for interacting with the API. As a general rule, the library adheres to a set of conventions that we have aimed to make universal.\n\n### Handling errors\n\nHandle errors by rescuing `Pusher::Error` (all errors are descendants of this error)\n\n``` ruby\nbegin\n  pusher.trigger('a_channel', 'an_event', :some =\u003e 'data')\nrescue Pusher::Error =\u003e e\n  # (Pusher::AuthenticationError, Pusher::HTTPError, or Pusher::Error)\nend\n```\n\n### Logging\n\nErrors are logged to `Pusher.logger`. It will by default log at info level to STDOUT using `Logger` from the standard library, however you can assign any logger:\n\n``` ruby\nPusher.logger = Rails.logger\n```\n\n### Publishing events\n\nAn event can be published to one or more channels (limited to 10) in one API call:\n\n``` ruby\npusher.trigger('channel', 'event', foo: 'bar')\npusher.trigger(['channel_1', 'channel_2'], 'event_name', foo: 'bar')\n```\n\nAn optional fourth argument may be used to send additional parameters to the API, for example to [exclude a single connection from receiving the event](https://pusher.com/docs/channels/server_api/excluding-event-recipients).\n\n``` ruby\npusher.trigger('channel', 'event', {foo: 'bar'}, {socket_id: '123.456'})\n```\n\n#### Batches\n\nIt's also possible to send multiple events with a single API call (max 10\nevents per call on multi-tenant clusters):\n\n``` ruby\npusher.trigger_batch([\n  {channel: 'channel_1', name: 'event_name', data: { foo: 'bar' }},\n  {channel: 'channel_1', name: 'event_name', data: { hello: 'world' }}\n])\n```\n\n#### Deprecated publisher API\n\nMost examples and documentation will refer to the following syntax for triggering an event:\n\n``` ruby\nPusher['a_channel'].trigger('an_event', :some =\u003e 'data')\n```\n\nThis will continue to work, but has been replaced by `pusher.trigger` which supports one or multiple channels.\n\n### Getting information about the channels in your Pusher Channels app\n\nThis gem provides methods for accessing information from the [Channels HTTP API](https://pusher.com/docs/channels/library_auth_reference/rest-api). The documentation also shows an example of the responses from each of the API endpoints.\n\nThe following methods are provided by the gem.\n\n- `pusher.channel_info('channel_name', {info:\"user_count,subscription_count\"})` returns a hash describing the state of the channel([docs](https://pusher.com/docs/channels/library_auth_reference/rest-api#get-channels-fetch-info-for-multiple-channels-)).\n\n- `pusher.channel_users('presence-channel_name')` returns a list of all the users subscribed to the channel (only for Presence Channels) ([docs](https://pusher.com/docs/channels/library_auth_reference/rest-api#get-channels-fetch-info-for-multiple-channels-)).\n\n- `pusher.channels({filter_by_prefix: 'presence-', info: 'user_count'})` returns a hash of occupied channels (optionally filtered by prefix, f.i. `presence-`), and optionally attributes for these channels ([docs](https://pusher.com/docs/channels/library_auth_reference/rest-api#get-channels-fetch-info-for-multiple-channels-)).\n\n### Asynchronous requests\n\nThere are two main reasons for using the `_async` methods:\n\n* In a web application where the response from the Channels HTTP API is not used, but you'd like to avoid a blocking call in the request-response cycle\n* Your application is running in an event loop and you need to avoid blocking the reactor\n\nAsynchronous calls are supported either by using an event loop (eventmachine, preferred), or via a thread.\n\nThe following methods are available (in each case the calling interface matches the non-async version):\n\n* `pusher.get_async`\n* `pusher.post_async`\n* `pusher.trigger_async`\n\nIt is of course also possible to make calls to the Channels HTTP API via a job queue. This approach is recommended if you're sending a large number of events.\n\n#### With EventMachine\n\n* Add the `em-http-request` gem to your Gemfile (it's not a gem dependency).\n* Run the EventMachine reactor (either using `EM.run` or by running inside an evented server such as Thin).\n\nThe `_async` methods return an `EM::Deferrable` which you can bind callbacks to:\n\n``` ruby\npusher.get_async(\"/channels\").callback { |response|\n  # use reponse[:channels]\n}.errback { |error|\n  # error is an instance of Pusher::Error\n}\n```\n\nA HTTP error or an error response from Channels will cause the errback to be called with an appropriate error object.\n\n#### Without EventMachine\n\nIf the EventMachine reactor is not running, async requests will be made using threads (managed by the httpclient gem).\n\nAn `HTTPClient::Connection` object is returned immediately which can be [interrogated](http://rubydoc.info/gems/httpclient/HTTPClient/Connection) to discover the status of the request. The usual response checking and processing is not done when the request completes, and frankly this method is most useful when you're not interested in waiting for the response.\n\n\n## Authenticating subscription requests\n\nIt's possible to use the gem to authenticate subscription requests to private or presence channels. The `authenticate` method is available on a channel object for this purpose and returns a JSON object that can be returned to the client that made the request. More information on this authentication scheme can be found in the docs on \u003chttps://pusher.com/docs/channels/server_api/authenticating-users\u003e\n\n### Private channels\n\n``` ruby\npusher.authenticate('private-my_channel', params[:socket_id])\n```\n\n### Presence channels\n\nThese work in a very similar way, but require a unique identifier for the user being authenticated, and optionally some attributes that are provided to clients via presence events:\n\n``` ruby\npusher.authenticate('presence-my_channel', params[:socket_id],\n  user_id: 'user_id',\n  user_info: {} # optional\n)\n```\n\n## Receiving WebHooks\n\nA WebHook object may be created to validate received WebHooks against your app credentials, and to extract events. It should be created with the `Rack::Request` object (available as `request` in Rails controllers or Sinatra handlers for example).\n\n``` ruby\nwebhook = pusher.webhook(request)\nif webhook.valid?\n  webhook.events.each do |event|\n    case event[\"name\"]\n    when 'channel_occupied'\n      puts \"Channel occupied: #{event[\"channel\"]}\"\n    when 'channel_vacated'\n      puts \"Channel vacated: #{event[\"channel\"]}\"\n    end\n  end\n  render text: 'ok'\nelse\n  render text: 'invalid', status: 401\nend\n```\n\n### End-to-end encryption\n\nThis library supports [end-to-end encrypted channels](https://pusher.com/docs/channels/using_channels/encrypted-channels). This means that only you and your connected clients will be able to read your messages. Pusher cannot decrypt them. You can enable this feature by following these steps:\n\n1. Add the `rbnacl` gem to your Gemfile (it's not a gem dependency).\n\n2. Install [Libsodium](https://github.com/jedisct1/libsodium), which we rely on to do the heavy lifting. [Follow the installation instructions for your platform.](https://github.com/RubyCrypto/rbnacl/wiki/Installing-libsodium)\n\n3. Encrypted channel subscriptions must be authenticated in the exact same way as private channels. You should therefore [create an authentication endpoint on your server](https://pusher.com/docs/authenticating_users).\n\n4. Next, generate your 32 byte master encryption key, encode it as base64 and pass it to the Pusher constructor.\n\n   This is secret and you should never share this with anyone.\n   Not even Pusher.\n\n   ```bash\n   openssl rand -base64 32\n   ```\n\n   ```rb\n   pusher = new Pusher::Client.new({\n     app_id: 'your-app-id',\n     key: 'your-app-key',\n     secret: 'your-app-secret',\n     cluster: 'your-app-cluster',\n     use_tls: true\n     encryption_master_key_base64: '\u003cKEY GENERATED BY PREVIOUS COMMAND\u003e',\n   });\n   ```\n\n5. Channels where you wish to use end-to-end encryption should be prefixed with `private-encrypted-`.\n\n6. Subscribe to these channels in your client, and you're done! You can verify it is working by checking out the debug console on the [https://dashboard.pusher.com/](dashboard) and seeing the scrambled ciphertext.\n\n**Important note: This will __not__ encrypt messages on channels that are not prefixed by `private-encrypted-`.**\n\n**Limitation**: you cannot trigger a single event on multiple channels in a call to `trigger`, e.g.\n\n```rb\npusher.trigger(\n  ['channel-1', 'private-encrypted-channel-2'],\n  'test_event',\n  { message: 'hello world' },\n)\n```\n\nRationale: the methods in this library map directly to individual Channels HTTP API requests. If we allowed triggering a single event on multiple channels (some encrypted, some unencrypted), then it would require two API requests: one where the event is encrypted to the encrypted channels, and one where the event is unencrypted for unencrypted channels.\n","funding_links":[],"categories":["Ruby","Third-party APIs"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpusher%2Fpusher-http-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpusher%2Fpusher-http-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpusher%2Fpusher-http-ruby/lists"}