pusher 1.3.2 → 2.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: d7b2bbdf8bc09f38d44a290d712f4e4cfea3c02d
-  data.tar.gz: 72350a25756be9e9bff440195d2efba5d6f91a17
+SHA256:
+  metadata.gz: 71dc5eb4f9d389dce37f6ec8c1f78390402b31bd94edcb6f22094c70edeb2d72
+  data.tar.gz: 3b2d0db0ffe052cbd8c71b252ced1d5910ece64a08100a92c0f17b5ac9b6fa8a
 SHA512:
-  metadata.gz: 177ffe40c85c424260852a5928196bd56d0bd40984635426d82f57d5ec6f126f4ce0e6eb99ee87b2e821a29b35e9640abde5a80895f0f71795f2d99c809d7a9a
-  data.tar.gz: 76a3284cc6ec3ea2686066cad60a020ca34399bdec353ccf5b2dc776ff8f57b9d1f68c2ce4a5ad10e2166de4757c995d16500b7c42b8af235338493dcf2b315a
+  metadata.gz: 2f644cc58f1b8accd8785eeffc3fc74bad4c20677032455d96e655944ee0818f99802ed339a3f5f9049acd57ea1166817f6c01feba926c9b61256260239c6354
+  data.tar.gz: c0d4edd095918225bea29707df4e8e0364b16218c367b40f72c5541fe98232e4698e83e58ea8260b7caeeea54d314ec343ea25050f1f7847747d01a003c68221

data/CHANGELOG.md

@@ -1,103 +1,133 @@
-1.3.1 / 2017-03-15
-==================
+# Changelog
 
-  * Added missing client batch methods to default client delegations
-  * Document raised exception in the `authenticate` method
-  * Fixes em-http-request from using v2.5.0 of `addressable` breaking builds.
+## 2.0.3
 
-1.3.0 / 2016-08-23
-==================
+* [FIXED] Corrected the channels limit when publishing events. Upped from 10 to 100. 
 
-  * Add support for sending push notifications on up to 10 interests.
+## 2.0.2
 
-1.2.1 / 2016-08-22
-==================
+* [CHANGED] made encryption_master_key_base64 globally configurable 
 
-  * Fixes Rails 5 compatibility. Use duck-typing to detect request object
+## 2.0.1
 
-1.2.0 / 2016-08-15
-==================
+* [CHANGED] Only include lib and essential docs in gem.
 
-  * Minor release for Native notifications
+## 2.0.0
 
-1.2.0.rc1 / 2016-07-18
-==================
+* [CHANGED] Use TLS by default.
+* [REMOVED] Support for Ruby 2.4 and 2.5.
+* [FIXED] Handle empty or nil  configuration.
+* [REMOVED] Legacy Push Notification integration.
+* [ADDED] Stalebot and Github actions. 
+
+## 1.4.3
 
-  * Add support for Native notifications
+  * [FIXED] Remove newline from end of base64 encoded strings, some decoders don't like
+    them.
 
-1.1.0 / 2016-05-20
+## 1.4.2
 ==================
 
-  * Add support for batch events
+  * [FIXED] Return `shared_secret` to support authenticating encrypted channels. Thanks
+    @Benjaminpjacobs
 
-1.0.0 / 2016-05-19
-==================
+## 1.4.1
 
-No breaking changes, this release is just to follow semver and show that we
-are stable.
+  * [CHANGED] Remove rbnacl from dependencies so we don't get errors when it isn't
+    required. Thanks @y-yagi!
 
-0.18.0 / 2016-05-15
-==================
+## 1.4.0
 
-  * Introduce `Pusher::Client.from_env`
-  * Improve error handling on missing config
+  * [ADDED] Support for end-to-end encryption.
 
-0.17.0 / 2016-02-22
-==================
+## 1.3.3
 
-  * Introduce the `cluster` option.
+  * [CHANGED] Rewording to clarify "Pusher Channels" or simply "Channels" product name.
 
-0.16.0 / 2016-01-21
-==================
+## 1.3.2
 
-  * Bump httpclient version to 2.7
-  * Ruby 1.8.7 is not supported anymore.
+  * [FIXED] Return a specific error for "Request Entity Too Large" (body over 10KB).
+  * [ADDED] Add a `use_tls` option for SSL (defaults to false).
+  * [ADDED] Add a `from_url` client method (in addition to existing `from_env` option).
+  * [CHANGED] Improved documentation and fixed typos.
+  * [ADDED] Add Ruby 2.4 to test matrix.
 
-0.15.2 / 2015-12-03
-==================
+## 1.3.1
 
-  * Documented `Pusher.channel_info`, `Pusher.channels`
-  * Added `Pusher.channel_users`
+  * [FIXED] Added missing client batch methods to default client delegations
+  * [CHANGED] Document raised exception in the `authenticate` method
+  * [FIXED] Fixes em-http-request from using v2.5.0 of `addressable` breaking builds.
 
-0.15.1 / 2015-11-03
-==================
+## 1.3.0
 
-  * Fixed a bug where the `authenticate` method added in 0.15.0 wasn't exposed on the Pusher class.
+  * [ADDED] Add support for sending push notifications on up to 10 interests.
 
-0.15.0 / 2015-11-02
-==================
+## 1.2.1
 
-  * Added `Pusher.authenticate` method for authenticating private and presence channels.
-    This is prefered over the older `Pusher['a_channel'].authenticate(...)` style.
+  * [FIXED] Fixes Rails 5 compatibility. Use duck-typing to detect request object
 
-0.14.6 / 2015-09-29
-==================
-  * Updated to use the `pusher-signature` gem instead of `signature`.
-    This resolves namespace related issues.
+## 1.2.0
 
-0.14.5 / 2015-05-11
-==================
+  * [CHANGED] Minor release for Native notifications
 
-  * SECURITY: Prevent auth delegation trough crafted socket IDs
+## 1.2.0.rc1
 
-0.14.4 / 2015-01-20
-==================
+  * [ADDED] Add support for Native notifications
 
-  * SECURITY: Prevent timing attack, update signature to v0.1.8
-  * SECURITY: Prevent POODLE. Disable SSLv3, update httpclient to v2.5
-  * Fix channel name character limit.
-  * Adds support for listing users on a presence channel
+## 1.1.0
 
-0.14.3 / 2015-01-20
-==================
+  * [ADDED] Add support for batch events
 
-Yanked, bad release
+## 1.0.0
 
-0.14.2 / 2014-10-16
-==================
+ * [CHANGED] No breaking changes, this release is just to follow semver and show that we
+are stable.
+
+## 0.18.0
+
+  * [ADDED] Introduce `Pusher::Client.from_env`
+  * [FIXED] Improve error handling on missing config
+
+## 0.17.0
+
+  * [ADDED] Introduce the `cluster` option.
+
+## 0.16.0
+
+  * [CHANGED] Bump httpclient version to 2.7
+  * [REMOVED] Ruby 1.8.7 is not supported anymore.
+
+## 0.15.2
+
+  * [CHANGED] Documented `Pusher.channel_info`, `Pusher.channels`
+  * [ADDED] Added `Pusher.channel_users`
+
+## 0.15.1
+
+  * [FIXED] Fixed a bug where the `authenticate` method added in 0.15.0 wasn't exposed on the Pusher class.
+
+## 0.15.0
+
+  * [ADDED] Added `Pusher.authenticate` method for authenticating private and presence channels.
+    This is prefered over the older `Pusher['a_channel'].authenticate(...)` style.
+
+## 0.14.6
+
+  * [CHANGED] Updated to use the `pusher-signature` gem instead of `signature`.
+    This resolves namespace related issues.
+
+## 0.14.5
+
+  * [SECURITY] Prevent auth delegation trough crafted socket IDs
+
+## 0.14.4
 
-First release with a changelog !
+  * [SECURITY] Prevent timing attack, update signature to v0.1.8
+  * [SECURITY] Prevent POODLE. Disable SSLv3, update httpclient to v2.5
+  * [FIXED] Fix channel name character limit.
+  * [ADDED] Adds support for listing users on a presence channel
 
-  * Bump httpclient to v2.4. See #62 (POODLE SSL)
-  * Fix limited channel count at README.md. Thanks @tricknotes
+## 0.14.2
 
+  * [CHANGED] Bump httpclient to v2.4. See #62 (POODLE SSL)
+  * [CHANGED] Fix limited channel count at README.md. Thanks @tricknotes

data/README.md

@@ -1,8 +1,12 @@
 # Gem for Pusher Channels
 
-This Gem provides a Ruby interface to [the Pusher HTTP API for Pusher Channels](https://pusher.com/docs/rest_api).
+This Gem provides a Ruby interface to [the Pusher HTTP API for Pusher Channels](https://pusher.com/docs/channels/library_auth_reference/rest-api).
 
-[![Build Status](https://secure.travis-ci.org/pusher/pusher-http-ruby.svg?branch=master)](http://travis-ci.org/pusher/pusher-http-ruby)
+[![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)
+
+## Supported Platforms
+
+* Ruby - supports **Ruby 2.6 or greater**.
 
 ## Installation and Configuration
 
@@ -18,7 +22,7 @@ or install via gem
 gem install pusher
 ```
 
-After registering at <https://dashboard.pusher.com/>, configure your Pusher Channels app with the security credentials.
+After registering at [Pusher](https://dashboard.pusher.com/accounts/sign_up), configure your Channels app with the security credentials.
 
 ### Instantiating a Pusher Channels client
 
@@ -27,7 +31,7 @@ Creating a new Pusher Channels `client` can be done as follows.
 ``` ruby
 require 'pusher'
 
-channels_client = Pusher::Client.new(
+pusher = Pusher::Client.new(
   app_id: 'your-app-id',
   key: 'your-app-key',
   secret: 'your-app-secret',
@@ -36,14 +40,14 @@ channels_client = Pusher::Client.new(
 )
 ```
 
-The `cluster` value will set the `host` to `api-<cluster>.pusher.com`. The `use_tls` value is optional and defaults to `false`. It will set the `scheme` and `port`. Custom `scheme` and `port` values take precendence over `use_tls`.
+The `cluster` value will set the `host` to `api-<cluster>.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`.
 
 If you want to set a custom `host` value for your client then you can do so when instantiating a Pusher Channels client like so:
 
 ``` ruby
 require 'pusher'
 
-channels_client = Pusher::Client.new(
+pusher = Pusher::Client.new(
   app_id: 'your-app-id',
   key: 'your-app-key',
   secret: 'your-app-secret',
@@ -57,12 +61,12 @@ Finally, if you have the configuration set in an `PUSHER_URL` environment
 variable, you can use:
 
 ``` ruby
-channels_client = Pusher::Client.from_env
+pusher = Pusher::Client.from_env
 ```
 
 ### Global configuration
 
-Configuring Pusher can also be done globally on the Pusher class.
+The library can also be configured globally on the `Pusher` class.
 
 ``` ruby
 Pusher.app_id = 'your-app-id'
@@ -79,11 +83,11 @@ If you need to make requests via a HTTP proxy then it can be configured
 Pusher.http_proxy = 'http://(user):(password)@(host):(port)'
 ```
 
-By default API requests are made over HTTP. HTTPS can be used by setting `encrypted` to `true`.
+By default API requests are made over HTTPS. HTTP can be used by setting `use_tls` to `false`.
 Issuing this command is going to reset `port` value if it was previously specified.
 
 ``` ruby
-Pusher.encrypted = true
+Pusher.use_tls = false
 ```
 
 As 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:
@@ -92,9 +96,9 @@ As of version 0.12, SSL certificates are verified when using the synchronous htt
 Pusher.default_client.sync_http_client.ssl_config.verify_mode = OpenSSL::SSL::VERIFY_NONE
 ```
 
-## Interacting with the Pusher service
+## Interacting with the Channels HTTP API
 
-The Pusher gem contains a number of helpers for interacting with the service. As a general rule, the library adheres to a set of conventions that we have aimed to make universal.
+The `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.
 
 ### Handling errors
 
@@ -102,7 +106,7 @@ Handle errors by rescuing `Pusher::Error` (all errors are descendants of this er
 
 ``` ruby
 begin
-  channels_client.trigger('a_channel', 'an_event', :some => 'data')
+  pusher.trigger('a_channel', 'an_event', :some => 'data')
 rescue Pusher::Error => e
   # (Pusher::AuthenticationError, Pusher::HTTPError, or Pusher::Error)
 end
@@ -121,14 +125,14 @@ Pusher.logger = Rails.logger
 An event can be published to one or more channels (limited to 10) in one API call:
 
 ``` ruby
-channels_client.trigger('channel', 'event', foo: 'bar')
-channels_client.trigger(['channel_1', 'channel_2'], 'event_name', foo: 'bar')
+pusher.trigger('channel', 'event', foo: 'bar')
+pusher.trigger(['channel_1', 'channel_2'], 'event_name', foo: 'bar')
 ```
 
-An optional fourth argument may be used to send additional parameters to the API, for example to [exclude a single connection from receiving the event](http://pusher.com/docs/publisher_api_guide/publisher_excluding_recipients).
+An 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).
 
 ``` ruby
-channels_client.trigger('channel', 'event', {foo: 'bar'}, {socket_id: '123.456'})
+pusher.trigger('channel', 'event', {foo: 'bar'}, {socket_id: '123.456'})
 ```
 
 #### Batches
@@ -137,7 +141,7 @@ It's also possible to send multiple events with a single API call (max 10
 events per call on multi-tenant clusters):
 
 ``` ruby
-channels_client.trigger_batch([
+pusher.trigger_batch([
   {channel: 'channel_1', name: 'event_name', data: { foo: 'bar' }},
   {channel: 'channel_1', name: 'event_name', data: { hello: 'world' }}
 ])
@@ -151,36 +155,36 @@ Most examples and documentation will refer to the following syntax for triggerin
 Pusher['a_channel'].trigger('an_event', :some => 'data')
 ```
 
-This will continue to work, but has been replaced by `channels_client.trigger` which supports one or multiple channels.
+This will continue to work, but has been replaced by `pusher.trigger` which supports one or multiple channels.
 
 ### Getting information about the channels in your Pusher Channels app
 
-This gem provides methods for accessing information from the [Pusher HTTP API](https://pusher.com/docs/rest_api). The documentation also shows an example of the responses from each of the API endpoints.
+This 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.
 
 The following methods are provided by the gem.
 
-- `channels_client.channel_info('channel_name')` returns information about that channel.
+- `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-)).
 
-- `channels_client.channel_users('channel_name')` returns a list of all the users subscribed to the channel.
+- `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-)).
 
-- `channels_client.channels` returns information about all the channels in your Pusher application.
+- `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-)).
 
 ### Asynchronous requests
 
 There are two main reasons for using the `_async` methods:
 
-* In a web application where the response from the Pusher Channels HTTP API is not used, but you'd like to avoid a blocking call in the request-response cycle
+* 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
 * Your application is running in an event loop and you need to avoid blocking the reactor
 
 Asynchronous calls are supported either by using an event loop (eventmachine, preferred), or via a thread.
 
 The following methods are available (in each case the calling interface matches the non-async version):
 
-* `channels_client.get_async`
-* `channels_client.post_async`
-* `channels_client.trigger_async`
+* `pusher.get_async`
+* `pusher.post_async`
+* `pusher.trigger_async`
 
-It is of course also possible to make calls to the Pusher Channels HTTP API via a job queue. This approach is recommended if you're sending a large number of events.
+It 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.
 
 #### With EventMachine
 
@@ -190,14 +194,14 @@ It is of course also possible to make calls to the Pusher Channels HTTP API via
 The `_async` methods return an `EM::Deferrable` which you can bind callbacks to:
 
 ``` ruby
-channels_client.get_async("/channels").callback { |response|
+pusher.get_async("/channels").callback { |response|
   # use reponse[:channels]
 }.errback { |error|
   # error is an instance of Pusher::Error
 }
 ```
 
-A HTTP error or an error response from pusher will cause the errback to be called with an appropriate error object.
+A HTTP error or an error response from Channels will cause the errback to be called with an appropriate error object.
 
 #### Without EventMachine
 
@@ -208,12 +212,12 @@ An `HTTPClient::Connection` object is returned immediately which can be [interro
 
 ## Authenticating subscription requests
 
-It'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 <http://pusher.com>
+It'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 <https://pusher.com/docs/channels/server_api/authenticating-users>
 
 ### Private channels
 
 ``` ruby
-channels_client.authenticate('private-my_channel', params[:socket_id])
+pusher.authenticate('private-my_channel', params[:socket_id])
 ```
 
 ### Presence channels
@@ -221,7 +225,7 @@ channels_client.authenticate('private-my_channel', params[:socket_id])
 These 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:
 
 ``` ruby
-channels_client.authenticate('presence-my_channel', params[:socket_id],
+pusher.authenticate('presence-my_channel', params[:socket_id],
   user_id: 'user_id',
   user_info: {} # optional
 )
@@ -232,7 +236,7 @@ channels_client.authenticate('presence-my_channel', params[:socket_id],
 A 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).
 
 ``` ruby
-webhook = channels_client.webhook(request)
+webhook = pusher.webhook(request)
 if webhook.valid?
   webhook.events.each do |event|
     case event["name"]
@@ -247,3 +251,51 @@ else
   render text: 'invalid', status: 401
 end
 ```
+
+### End-to-end encryption
+
+This 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:
+
+1. Add the `rbnacl` gem to your Gemfile (it's not a gem dependency).
+
+2. 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)
+
+3. 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).
+
+4. Next, generate your 32 byte master encryption key, encode it as base64 and pass it to the Pusher constructor.
+
+   This is secret and you should never share this with anyone.
+   Not even Pusher.
+
+   ```bash
+   openssl rand -base64 32
+   ```
+
+   ```rb
+   pusher = new Pusher::Client.new({
+     app_id: 'your-app-id',
+     key: 'your-app-key',
+     secret: 'your-app-secret',
+     cluster: 'your-app-cluster',
+     use_tls: true
+     encryption_master_key_base64: '<KEY GENERATED BY PREVIOUS COMMAND>',
+   });
+   ```
+
+5. Channels where you wish to use end-to-end encryption should be prefixed with `private-encrypted-`.
+
+6. 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.
+
+**Important note: This will __not__ encrypt messages on channels that are not prefixed by `private-encrypted-`.**
+
+**Limitation**: you cannot trigger a single event on multiple channels in a call to `trigger`, e.g.
+
+```rb
+pusher.trigger(
+  ['channel-1', 'private-encrypted-channel-2'],
+  'test_event',
+  { message: 'hello world' },
+)
+```
+
+Rationale: 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.

data/lib/pusher/channel.rb

@@ -174,6 +174,15 @@ module Pusher
       r
     end
 
+    def shared_secret(encryption_master_key)
+      return unless encryption_master_key
+
+      secret_string = @name + encryption_master_key
+      digest = OpenSSL::Digest::SHA256.new
+      digest << secret_string
+      digest.digest
+    end
+
     private
 
     def validate_socket_id(socket_id)