pusher 1.3.1 → 1.4.2

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    YThkNzIxNmMwMTgyY2ZhZmJlYjY3Njk1NGEzMDFiOWMxYzk5Mjc1MQ==
-  data.tar.gz: !binary |-
-    Mjk3MmUwODFhNDcxY2U1ZjVhZTlkMGUzYmZlMGE3NWY0ZGNkZGE3Mg==
+SHA256:
+  metadata.gz: 81a153328f0e5452bcdd87e9cd09339464a26679566f1d14f087fee9a29a69b2
+  data.tar.gz: f5e282e3a9f0d60d441da0ef023073cefa1d4ebd2ada5b7fcb82a258a53c402a
 SHA512:
-  metadata.gz: !binary |-
-    NDllZTg5MzdiYzMyODFkZjE1M2QxMjEzNjcwMGQ0OGNlODhiY2Q2NmMzZDMy
-    ZTBiNzUyODYzYWE4NjQxNDE5OWQ2ZjIxMTMwYzUwYTdhNjkyNTY0OWZmMDQ2
-    YTA4NWVmMTJmMmZhMmFiNGY0NTM4Mjg5YjhlMDRhM2FkNDcxYWE=
-  data.tar.gz: !binary |-
-    ZGZmNzQ0YmExMGMzZjlkY2U2Yzk5MzgyMWUwOTJhNzFmYjkxNTFkMGZmODNl
-    MmI4OGJlMmI0OGJiZjZhN2MwYzE3MDJiZWUzNzlhNzE1NDQ0OTQzODQxNTdj
-    ZGMwNGExNDljYTU4MjY1OTBjMWYzZTIzM2Q2YTdkMTY4OWI2Mzc=
+  metadata.gz: 87ed04a2e5bd63cfffd67798066dc9d014d119a00f7b6caad6c7d9a0d1a64c0a251c5f5b9706d883025532758e53f9a5d2f34579b555a206bb341182c624f58d
+  data.tar.gz: 7776a1f8477dc5d7d33efb0cb46edd3dfe0d77d7c40d691eb8cb525d71998216eb4fc7832b546fb7c43f7ec1bb1db5db32e169ed1d4d1c2cdd1291d89e9f8b73

data/.github/stale.yml

@@ -0,0 +1,26 @@
+# Configuration for probot-stale - https://github.com/probot/stale
+
+# Number of days of inactivity before an Issue or Pull Request becomes stale
+daysUntilStale: 365
+
+# Number of days of inactivity before an Issue or Pull Request with the stale label is closed.
+# Set to false to disable. If disabled, issues still need to be closed manually, but will remain marked as stale.
+daysUntilClose: 7
+
+# Only issues or pull requests with all of these labels are check if stale. Defaults to `[]` (disabled)
+onlyLabels: []
+
+# Issues or Pull Requests with these labels will never be considered stale. Set to `[]` to disable
+exemptLabels:
+  - pinned
+  - security
+
+# Set to true to ignore issues with an assignee (defaults to false)
+exemptAssignees: true
+
+# Comment to post when marking as stale. Set to `false` to disable
+markComment: >
+  This issue has been automatically marked as stale because it has not had
+  recent activity. It will be closed if no further activity occurs. If you'd
+  like this issue to stay open please leave a comment indicating how this issue
+  is affecting you. Thankyou.

data/.travis.yml

@@ -1,11 +1,12 @@
+before_install:
+  - sudo apt-get -y install libsodium18
+
 language: ruby
 sudo: false
 rvm:
-  - 1.9.3
-  - 2.0
-  - 2.1
-  - 2.2
-  - 2.3.0
+  - 2.4
+  - 2.5
+  - 2.6
   - jruby
   - rbx-2
 

data/CHANGELOG.md

@@ -1,3 +1,34 @@
+1.4.2 / 2020-10-20
+==================
+
+  * Return `shared_secret` to support authenticating encrypted channels. Thanks
+    @Benjaminpjacobs
+
+1.4.1 / 2020-10-05
+==================
+
+  * Remove rbnacl from dependencies so we don't get errors when it isn't
+    required. Thanks @y-yagi!
+
+1.4.0 / 2020-09-29
+==================
+
+  * Support for end-to-end encryption.
+
+1.3.3 / 2019-07-02
+==================
+
+  * Rewording to clarify "Pusher Channels" or simply "Channels" product name.
+
+1.3.2 / 2018-10-17
+==================
+
+  * Return a specific error for "Request Entity Too Large" (body over 10KB).
+  * Add a `use_tls` option for SSL (defaults to false).
+  * Add a `from_url` client method (in addition to existing `from_env` option).
+  * Improved documentation and fixed typos.
+  * Add Ruby 2.4 to test matrix.
+
 1.3.1 / 2017-03-15
 ==================
 
@@ -100,4 +131,3 @@ First release with a changelog !
 
   * Bump httpclient to v2.4. See #62 (POODLE SSL)
   * Fix limited channel count at README.md. Thanks @tricknotes
-

data/README.md

@@ -1,11 +1,12 @@
-Pusher gem
-==========
+# Gem for Pusher Channels
 
-[![Build Status](https://secure.travis-ci.org/pusher/pusher-http-ruby.svg?branch=master)](http://travis-ci.org/pusher/pusher-http-ruby)
+This Gem provides a Ruby interface to [the Pusher HTTP API for Pusher Channels](https://pusher.com/docs/channels/library_auth_reference/rest-api).
 
-## Installation & Configuration
+[![Build Status](https://secure.travis-ci.org/pusher/pusher-http-ruby.svg?branch=master)](http://travis-ci.org/pusher/pusher-http-ruby) [![Gem Version](https://badge.fury.io/rb/pusher.svg)](https://badge.fury.io/rb/pusher)
 
-Add pusher to your Gemfile, and then run `bundle install`
+## Installation and Configuration
+
+Add `pusher` to your Gemfile, and then run `bundle install`
 
 ``` ruby
 gem 'pusher'
@@ -17,68 +18,60 @@ or install via gem
 gem install pusher
 ```
 
-After registering at <http://pusher.com> configure your 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 client
+### Instantiating a Pusher Channels client
 
-Creating a new Pusher `client` can be done as follows.
+Creating a new Pusher Channels `client` can be done as follows.
 
 ``` ruby
-pusher_client = Pusher::Client.new(
-  app_id: 'your-pusher-app-id',
-  key: 'your-pusher-key',
-  secret: 'your-pusher-secret'
+require 'pusher'
+
+pusher = Pusher::Client.new(
+  app_id: 'your-app-id',
+  key: 'your-app-key',
+  secret: 'your-app-secret',
+  cluster: 'your-app-cluster',
+  use_tls: true
 )
 ```
 
-If you want to set a custom `host` value for your client then you can do so when instantiating a Pusher client like so:
-
-``` ruby
-pusher_client = Pusher::Client.new(
-  app_id: 'your-pusher-app-id',
-  key: 'your-pusher-key',
-  secret: 'your-pusher-secret',
-  host: 'your-pusher-host'
-)
-```
+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`.
 
-If you created your app in a different cluster to the default cluster, you must pass the `cluster` option as follows:
+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
-pusher_client = Pusher::Client.new(
-  app_id: 'your-pusher-app-id',
-  key: 'your-pusher-key',
-  secret: 'your-pusher-secret',
-  cluster: 'your-app-cluster'
+require 'pusher'
+
+pusher = Pusher::Client.new(
+  app_id: 'your-app-id',
+  key: 'your-app-key',
+  secret: 'your-app-secret',
+  host: 'your-app-host'
 )
 ```
 
-This will set the `host` to `api-<cluster>.pusher.com`. If you pass both `host` and `cluster` options, the `host` will take precendence and `cluster` will be ignored.
+If you pass both `host` and `cluster` options, the `host` will take precendence and `cluster` will be ignored.
 
 Finally, if you have the configuration set in an `PUSHER_URL` environment
 variable, you can use:
 
 ``` ruby
-pusher_client = Pusher::Client.from_env
+pusher = Pusher::Client.from_env
 ```
 
-### Global
-
-Configuring Pusher can also be done globally on the Pusher class.
-
-``` ruby
-Pusher.app_id = 'your-pusher-app-id'
-Pusher.key = 'your-pusher-key'
-Pusher.secret = 'your-pusher-secret'
-```
+### Global configuration
 
-If you created your app in a different cluster to the default cluster, you must set it as follows:
+The library can also be configured globally on the `Pusher` class.
 
 ``` ruby
+Pusher.app_id = 'your-app-id'
+Pusher.key = 'your-app-key'
+Pusher.secret = 'your-app-secret'
 Pusher.cluster = 'your-app-cluster'
 ```
 
-Global configuration will automatically be set from the `PUSHER_URL` environment variable if it exists. This should be in the form  `http://KEY:SECRET@api.pusherapp.com/apps/APP_ID`. On Heroku this environment variable will already be set.
+Global 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.
 
 If you need to make requests via a HTTP proxy then it can be configured
 
@@ -86,7 +79,8 @@ 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
+By default API requests are made over HTTP. HTTPS can be used by setting `encrypted` to `true`.
+Issuing this command is going to reset `port` value if it was previously specified.
 
 ``` ruby
 Pusher.encrypted = true
@@ -98,9 +92,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
 
@@ -108,7 +102,7 @@ Handle errors by rescuing `Pusher::Error` (all errors are descendants of this er
 
 ``` ruby
 begin
-  Pusher.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
@@ -127,14 +121,14 @@ Pusher.logger = Rails.logger
 An event can be published to one or more channels (limited to 10) in one API call:
 
 ``` ruby
-Pusher.trigger('channel', 'event', foo: 'bar')
-Pusher.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
-Pusher.trigger('channel', 'event', {foo: 'bar'}, {socket_id: '123.456'})
+pusher.trigger('channel', 'event', {foo: 'bar'}, {socket_id: '123.456'})
 ```
 
 #### Batches
@@ -143,8 +137,8 @@ It's also possible to send multiple events with a single API call (max 10
 events per call on multi-tenant clusters):
 
 ``` ruby
-Pusher.trigger_batch([
-  {channel: 'channel_1', name: 'event_name', data: { foo: 'bar' }}
+pusher.trigger_batch([
+  {channel: 'channel_1', name: 'event_name', data: { foo: 'bar' }},
   {channel: 'channel_1', name: 'event_name', data: { hello: 'world' }}
 ])
 ```
@@ -157,69 +151,69 @@ 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 `Pusher.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.
 
-### Using the Pusher REST API
+### Getting information about the channels in your Pusher Channels app
 
-This gem provides methods for accessing information from the [Pusher REST API](https://pusher.com/docs/rest_api). The documentation also shows an example of the responses from each of the API endpionts.
+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.
 
-- `Pusher.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-)).
 
-- `Pusher.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-)).
 
-- `Pusher.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 Pusher 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):
 
-* `Pusher.get_async`
-* `Pusher.post_async`
-* `Pusher.trigger_async`
+* `pusher.get_async`
+* `pusher.post_async`
+* `pusher.trigger_async`
 
-It is of course also possible to make calls to pusher via a job queue. This approach is recommended if you're sending a large number of events to pusher.
+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
+#### With EventMachine
 
 * Add the `em-http-request` gem to your Gemfile (it's not a gem dependency).
-* Run the eventmachine reactor (either using `EM.run` or by running inside an evented server such as Thin).
+* Run the EventMachine reactor (either using `EM.run` or by running inside an evented server such as Thin).
 
 The `_async` methods return an `EM::Deferrable` which you can bind callbacks to:
 
 ``` ruby
-Pusher.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
+#### Without EventMachine
 
-If the eventmachine reactor is not running, async requests will be made using threads (managed by the httpclient gem).
+If the EventMachine reactor is not running, async requests will be made using threads (managed by the httpclient gem).
 
 An `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.
 
 
 ## 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
-Pusher.authenticate('private-my_channel', params[:socket_id])
+pusher.authenticate('private-my_channel', params[:socket_id])
 ```
 
 ### Presence channels
@@ -227,7 +221,7 @@ Pusher.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
-Pusher.authenticate('presence-my_channel', params[:socket_id],
+pusher.authenticate('presence-my_channel', params[:socket_id],
   user_id: 'user_id',
   user_info: {} # optional
 )
@@ -238,7 +232,7 @@ Pusher.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 = Pusher.webhook(request)
+webhook = pusher.webhook(request)
 if webhook.valid?
   webhook.events.each do |event|
     case event["name"]
@@ -254,62 +248,53 @@ else
 end
 ```
 
-## Push Notifications (BETA)
+### End-to-end encryption
 
-Pusher now allows sending native notifications to iOS and Android devices. Check out the [documentation](https://pusher.com/docs/push_notifications) for information on how to set up push notifications on Android and iOS. There is no additional setup required to use it with this library. It works out of the box with the same Pusher instance. All you need are the same pusher credentials.
+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:
 
-### Sending native pushes
+1. Add the `rbnacl` gem to your Gemfile (it's not a gem dependency).
 
-The native notifications API is hosted at `nativepush-cluster1.pusher.com` and only accepts https requests.
+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)
 
-You can send pushes by using the `notify` method, either globally or on the instance. The method takes two parameters:
+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).
 
-- `interests`: An Array of strings which represents the interests your devices are subscribed to. These are akin to channels in the DDN with less of an epehemeral nature. Note that currently, you can only publish to, at most, _ten_ interests.
-- `data`: The content of the notification represented by a Hash. You must supply either the `gcm` or `apns` key. For a detailed list of the acceptable keys, take a look at the [iOS](https://pusher.com/docs/push_notifications/ios/server) and [Android](https://pusher.com/docs/push_notifications/android/server) docs.
+4. Next, generate your 32 byte master encryption key, encode it as base64 and pass it to the Pusher constructor.
 
-Example:
+   This is secret and you should never share this with anyone.
+   Not even Pusher.
 
-```ruby
-data = {
-  apns: {
-    aps: {
-      alert: {
-        body: 'tada'
-      }
-    }
-  }
-}
+   ```bash
+   openssl rand -base64 32
+   ```
 
-pusher.notify(["my-favourite-interest"], data)
-```
+   ```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>',
+   });
+   ```
 
-### Errors
-
-Push notification requests, once submitted to the service are executed asynchronously. To make reporting errors easier, you can supply a `webhook_url` field in the body of the request. This will be used by the service to send a webhook to the supplied URL if there are errors.
-
-You may also supply a `webhook_level` field in the body, which can either be INFO or DEBUG. It defaults to INFO - where INFO only reports customer facing errors, while DEBUG reports all errors.
-
-For example:
-
-```ruby
-data = {
-  apns: {
-    aps: {
-      alert: {
-        body: "hello"
-      }
-    }
-  },
-  gcm: {
-    notification: {
-      title: "hello",
-      icon: "icon"
-    }
-  },
-  webhook_url: "http://yolo.com",
-  webhook_level: "INFO"
-}
+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' },
+)
 ```
 
-**NOTE:** This is currently a BETA feature and there might be minor bugs and issues. Changes to the API will be kept to a minimum, but changes are expected. If you come across any bugs or issues, please do get in touch via [support](support@pusher.com) or create an issue here.
+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.
 
+## Supported Ruby versions
+2.4+