pushing 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 562381d6f82d103cc6e5db2b3408ea36d28fdb7a
+  data.tar.gz: 4df883a714c37d2a87f7555b75eb1cce48d5f370
+SHA512:
+  metadata.gz: be1bde88cd14ce57d6196cffb630bcf228d89e47040c7cce38e3887b6291bc32ff0edf83ed93ce3532deb1b9f477ab9990f0fae094df5a9f1566ed4816524e42
+  data.tar.gz: 060ca860f1f7960dfa264c4d5fd3ee6aa21fa11546cd6dcf6ce6cc87e6d879a16f0ab1211b9715925938fc64e38251cc14771767c5437a59d355f226ad44cce9

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+gemfiles/*.lock
+certs/apns_example_production.pem
+gemfiles/.bundle/

data/.travis.yml

@@ -0,0 +1,28 @@
+nguage: ruby
+script: bundle exec rake test test:isolated test:integration
+cache:  bundler
+sudo:   false
+
+before_install:
+  openssl aes-256-cbc -K $encrypted_86ed69f44076_key -iv $encrypted_86ed69f44076_iv -in ./certs/apns_example_production.pem.enc -out certs/apns_example_production.pem -d
+
+rvm:
+  - 2.2.7
+  - 2.3.4
+  - 2.4.1
+  - ruby-head
+  - jruby-9.1.10.0
+  - jruby-head
+
+gemfile:
+  - gemfiles/rails_42.gemfile
+  - gemfiles/rails_50.gemfile
+  - gemfiles/rails_51.gemfile
+  - gemfiles/rails_edge.gemfile
+
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+    - rvm: jruby-9.1.10.0
+    - rvm: jruby-head
+    - gemfile: gemfiles/rails_edge.gemfile

data/Appraisals

@@ -0,0 +1,29 @@
+appraise "rails_edge" do
+  git 'git://github.com/rails/rails.git' do
+    gem "railties"
+    gem "actionpack"
+    gem "actionview"
+    gem "activejob"
+  end
+end
+
+appraise "rails_50" do
+  gem "railties", '~> 5.0.0'
+  gem "actionpack", '~> 5.0.0'
+  gem "actionview", '~> 5.0.0'
+  gem "activejob", '~> 5.0.0'
+end
+
+appraise "rails_51" do
+  gem "railties", '~> 5.1.0'
+  gem "actionpack", '~> 5.1.0'
+  gem "actionview", '~> 5.1.0'
+  gem "activejob", '~> 5.1.0'
+end
+
+appraise "rails_42" do
+  gem "rails", '~> 4.2.0'
+  gem "actionpack", '~> 4.2.0'
+  gem "actionview", '~> 4.2.0'
+  gem "activejob", '~> 4.2.0'
+end

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at mail@yukinishijima.net. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,17 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in pushing.gemspec
+gemspec
+
+# APNs
+gem 'houston', require: false
+gem 'apnotic', require: false
+gem 'lowdown', require: false
+
+# FCM
+gem 'andpush', require: false
+gem 'fcm', require: false
+
+# Debugging
+gem 'pry'
+gem 'pry-byebug', platforms: :mri

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Yuki Nishijima
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,225 @@
+# Pushing [![Build Status](https://travis-ci.org/yuki24/pushing.svg?branch=master)](https://travis-ci.org/yuki24/pushing)
+
+Pushing is a push notification framework that implements interfaces similar to ActionMailer's APIs.
+
+ * **Convention over Configuration**: Pushing brings Convention over Configuration to your app's push notification implementation.
+ * **Extremely Easy to Learn**: If you know how to use ActionMailer, you already know how to use Pushing. Send notifications asynchronously with ActiveJob at no learning cost.
+ * **Testability**: First-class support for push notification. No more hassle writing custom code or stubs/mocks for your tests.
+
+## Getting Started
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'pushing', github: 'yuki24/pushing'
+gem 'jbuilder'
+```
+
+As the time of writing, Pushing only has support for [jbuilder](https://github.com/rails/jbuilder) (Rails' default JSON constructor), but there are plans to add support for [jb](https://github.com/amatsuda/jb) and [rabl](https://github.com/nesquena/rabl).
+
+### Supported Client Gems
+
+Pushing itself doesn't make HTTP requests. Instead, it uses an adapter and let an underlaying gem do it. Currently, Pushing has support for the following client gems:
+
+ * [APNs](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/APNSOverview.html#//apple_ref/doc/uid/TP40008194-CH8-SW1):
+   * [anpotic](https://github.com/ostinelli/apnotic) (recommended)
+   * [lowdown](https://github.com/alloy/lowdown)
+   * [houston](https://github.com/nomad/houston)
+
+ * [FCM](https://firebase.google.com/docs/cloud-messaging/):
+   * [andpush](https://github.com/yuki24/andpush) (recommended)
+   * [fcm](https://github.com/spacialdb/fcm)
+
+If you are starting from scratch, it is recommended using [anpotic](https://github.com/ostinelli/apnotic) for APNs and [andpush](https://github.com/yuki24/andpush) for FCM due to their reliability and performance:
+
+```ruby
+gem 'apnotic' # APNs integration
+gem 'andpush' # FCM integration
+```
+
+### Walkthrough to Writing a Notifier
+
+In this README, we'll use Twitter as an example. Suppose you'd like to send a push notification when a user receives a new direct message from other user. To get started, you can use Pushing's notifier generator:
+
+```sh
+$ rails g pushing:notifier TweetNotifier new_direct_message
+```
+
+#### Edit the Notifier
+
+Let's say there are `direct_messages` and `device_tokens` tables where we store actual messages and device tokens (a.k.a registration ids in FCM) given by APNs or FCM.
+
+```ruby
+# app/notifiers/tweet_notifier.rb
+class TweetNotifier < ApplicationNotifier
+  def new_direct_message(message_id, token_id)
+    @message = DirectMessage.find(message_id)
+    @token   = DeviceToken.find(token_id)
+
+    push apn: @token.apn? && @token.device_token, fcm: @token.fcm?
+  end
+end
+```
+
+Notice that the `:apn` key takes a truthy string value while the `:fcm` key takes a boolean value. Also, Pushing only sends a notification for the platforms that are given a truthy value. For example, the call:
+
+```ruby
+# only sends a push notification to FCM
+push apn: false, fcm: @token.registration_id
+```
+
+will only send a notification to the FCM service.
+
+#### Edit the Push Notification Payload
+
+Next, let's modify the templates to generate JSON that contains message data. Like controllers, you can use all the instance variables initialized in the action.
+
+APNs:
+
+```ruby
+# app/views/tweet_notifier/new_direct_message.json+apn.jbuilder
+json.aps do
+  json.alert do
+    json.title "#{@tweet.user.display_name} tweeted:"
+    json.body truncate(@tweet.body, length: 235)
+  end
+
+  json.badge 1
+  json.sound 'bingbong.aiff'
+end
+```
+
+FCM:
+
+```ruby
+# app/views/tweet_notifier/new_direct_message.json+fcm.jbuilder
+json.to @token.registration_id
+
+json.notification do
+  json.title "#{@tweet.user.display_name} tweeted:"
+  json.body truncate(@tweet.body, length: 1024)
+
+  json.icon 1
+  json.sound 'default'
+end
+```
+
+### Deliver the Push Notifications
+
+Finally, send a push notification to the user. You can call the `#deliver_now!` method to immediately send a notification, or the `#deliver_later!` method if you have ActiveJob set up.
+
+```ruby
+TweetNotifier.new_direct_message(message_id, device_token.id).deliver_now!
+# => sends a push notification immediately
+
+TweetNotifier.new_direct_message(message_id, device_token.id).deliver_later!
+# => enqueues a job that sends a push notification later
+```
+
+## Error Handling
+
+Like ActionMailer, you can use the `rescue_from` hook to handle exceptions. A common use-case would be to handle a **'BadDeviceToken'** response from APNs or a response with a **'Retry-After'** header from FCM.
+
+**Handling a 'BadDeviceToken' response from APNs**:
+
+```ruby
+class ApplicationNotifier < Pushing::Base
+  rescue_from Pushing::ApnDeliveryError do |error|
+    response = error.response
+
+    if response.status == 410 || (response.status == 400 && response.json[:reason] == 'BadDeviceToken')
+      token = error.notification.device_token
+
+      # delete device token accordingly
+    else
+      raise # Make sure to raise any other types of error to re-enqueue the job
+    end
+  end
+end
+```
+
+**Handling a 'Retry-After' header from FCM**:
+
+```ruby
+class ApplicationNotifier < Pushing::Base
+  rescue_from Pushing::FcmDeliveryError do |error|
+    if error.response&.headers['Retry-After']
+      # re-enqueue the job honoring the 'Retry-After' header
+    else
+      raise # Make sure to raise any other types of error to re-enqueue the job
+    end
+  end
+end
+```
+
+## Interceptors and Observers
+
+Pushing implements the Interceptor and Observer patterns. A common use-case would be to update registration ids with canonical ids from FCM:
+
+```ruby
+# app/observers/fcm_token_handler.rb
+class FcmTokenHandler
+  def delivered_notification(payload, response)
+    return if response.json[:canonical_ids].to_i.zero?
+
+    response.json[:results].select {|result| result[:registration_id] }.each do |result|
+      result[:registration_id] # => returns a canonical id
+
+      # Update registration ids accordingly
+    end
+  end
+end
+
+# app/notifiers/application_notifier.rb
+class ApplicationNotifier < Pushing::Base
+  register_observer FcmTokenHandler.new
+
+  ...
+end
+```
+
+## Configuration
+
+TODO
+
+## Testing
+
+Pushing provides first-class support for testing. In the test environment, use the `:test` adapter instead of an actual adapter you'd like to use in development/production.
+
+```ruby
+# config/initializers/pushing.rb
+Pushing::Platforms.configure do |config|
+  config.apn.adapter = Rails.env.test? ? :test : :apnotic
+  config.fcm.adapter = Rails.env.test? ? :test : :andpush
+end
+```
+
+Now you can use the `#deliveries` method. Here is an example with [ActiveSupport::TestCase](http://api.rubyonrails.org/classes/ActiveSupport/TestCase.html):
+
+```ruby
+TweetNotifier.deliveries.clear # => clears the test inbox
+
+assert_changes -> { TweetNotifier.deliveries.apn.size }, from: 0, to: 1 do
+  TweetNotifier.new_direct_message(message.id, apn_device_token.id).deliver_now!
+end
+
+apn_message = TweetNotifier.deliveries.apn.first
+assert_equal 'apn-device-token',  apn_message.device_token
+assert_equal "Hey coffee break?", apn_message.payload[:aps][:alert][:body]
+
+assert_changes -> { TweetNotifier.deliveries.fcm.size }, from: 0, to: 1 do
+  TweetNotifier.new_direct_message(message.id, fcm_registration_id.id).deliver_now!
+end
+
+fcm_payload = TweetNotifier.deliveries.fcm.first.payload
+assert_equal 'fcm-registration-id', fcm_payload[:to]
+assert_equal "Hey coffee break?",   fcm_payload[:notification][:body]
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/yuki24/pushing. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,22 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/**/*_test.rb'] - FileList['test/integration/**/*'] - ["test/railtie_test.rb"]
+end
+
+Rake::TestTask.new('test:integration') do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/integration/**/*_test.rb']
+end
+
+Rake::TestTask.new('test:isolated') do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = ["test/railtie_test.rb"]
+end
+
+task default: [:test, 'test:isolated']