rapns 3.0.0.beta.1 → 3.0.0.rc.1

data/README.md

@@ -1,27 +1,24 @@
 [![Build Status](https://secure.travis-ci.org/ileitch/rapns.png?branch=master)](http://travis-ci.org/ileitch/rapns)
 
-# Features
+### Rapns - Professional grade APNs and GCM daemon
 
-* Works with Rails 3 and Ruby 1.9 & 1.8.
-* Supports multiple iOS apps.
-* [Add & remove apps](#hot-app-updates) without restarting or affecting the delivery of notifications to other apps.
-* Uses a daemon process to keep open persistent connections to the APNs, as recommended by Apple.
-* Uses the enhanced binary format so that [delivery errors can be reported](#delivery-failures).
-* Records feedback from [The Feedback Service](#delivery-failures).
-* [Airbrake](http://airbrakeapp.com/) (Hoptoad) integration.
-* Support for [dictionary `alert` properties](#assigning-a-hash-to-alert).
-* [Mobile Device Management (MDM)](#mobile-device-management)
-* Stable. Reconnects to the APNs and your database if connections are lost.
+* Supports both APNs (iOS) and GCM (Google Cloud Messaging, Android).
+* Seamless Rails integration.
+* Scalable - choose the number of threads each app spawns.
+* Designed for uptime - signal -HUP to add, update apps.
+* Stable - reconnects database and network connections when lost.
+* Works with MRI, JRuby, Rubinius 1.8 and 1.9.
+* [Airbrake](http://airbrakeapp.com/) integration.
 
-### Who uses rapns?
+### Who uses Rapns?
 
 [GateGuru](http://gateguruapp.com) and [Desk.com](http://desk.com), among others!
 
-*I'd love to hear if you use rapns - @ileitch on twitter.*
+*I'd love to hear if you use Rapns - @ileitch on twitter.*
 
 ## Getting Started
 
-Add rapns to your Gemfile:
+Add Rapns to your Gemfile:
 
     gem 'rapns'
 
@@ -44,107 +41,75 @@ Generate the migration, rapns.yml and migrate:
 
 ## Create an App
 
-    app = Rapns::App.new
-    app.key = "my_app"
-    app.certificate = File.read("/path/to/development.pem")
-    app.environment = "development"
-    app.password = "certificate password"
-    app.connections = 1
-    app.save!
-
-* `key` is a symbolic name to tie this app to notifications.
-* `certificate` is the contents of your PEM certificate, NOT its path on disk.
-* `environment` the certificate type, either `development` or `production`.
-* `password` should be left blank if you did not password protect your certificate.
-* `connections` (default: 1) the number of connections to keep open to the APNs. Consider increasing this if you are sending a large number of notifications to this app.
-
-## Starting the rapns Daemon
+#### APNs
+```ruby
+app = Rapns::Apns::App.new
+app.name = "ios_app"
+app.certificate = File.read("/path/to/development.pem")
+app.environment = "development"
+app.password = "certificate password"
+app.connections = 1
+app.save!
+```
+
+#### GCM
+```ruby
+app = Rapns::Gcm::App.new
+app.name = "android_app"
+app.auth_key = "..."
+app.connections = 1
+app.save!
+```
+
+## Create a Notification
+
+#### APNs
+```ruby
+n = Rapns::Apns::Notification.new
+n.app = Rapns::Apns::App.find_by_name("ios_app")
+n.device_token = "..."
+n.alert = "hi mom!"
+n.attributes_for_device = {:foo => :bar}
+n.save!
+```
+
+#### GCM
+```ruby
+n = Rapns::Gcm::Notification.new
+n.app = Rapns::Gcm::App.find_by_name("android_app")
+n.registration_ids = ["..."]
+n.data = {:message => "hi mom!"}
+n.save!
+```
+
+## Starting Rapns
 
     cd /path/to/rails/app
-    bundle exec rapns <Rails environment> [options]
-
-### Options
-
-* `-f` `--foreground` Prevent rapns from forking into a daemon.
-* `-P N` `--db-poll N` Frequency in seconds to check for new notifications. Default: 2.
-* `-F N` `--feedback-poll N` Frequency in seconds to check for feedback. Default: 60.
-* `-e` `--no-error-checks` Disables [error checking](#immediately-when-processing-a-notification-for-delivery) after notification delivery. You may want to disable this if you are sending a very high number of notifications.
-* `-n` `--no-airbrake-notify` Disables error notifications via Airbrake.
-* `-p PATH` `--pid-file PATH` Path to write PID file. Relative to Rails root unless absolute.
-* `-b N` `--batch-size N` ActiveRecord batch size of notifications. Increase for possible higher throughput but higher memory footprint. Default: 5000.
-
-## Sending a Notification
-
-    n = Rapns::Notification.new
-    n.app = "my_app"
-    n.device_token = "934f7a..."
-    n.alert = "This is the message shown on the device."
-    n.badge = 1
-    n.sound = "1.aiff"
-    n.expiry = 1.day.to_i
-    n.attributes_for_device = {"question" => nil, "answer" => 42}
-    n.deliver_after = 1.hour.from_now
-    n.save!
-
-* `app` must match `key` on an `Rapns::App`.
-* `sound` defaults to `1.aiff`. You can either set it to a custom .aiff file, or `nil` for no sound.
-* `expiry` is the time in seconds the APNs (not rapns) will spend trying to deliver the notification to the device. The notification is discarded if it has not been delivered in this time. Default is 1 day.
-* `attributes_for_device` is the `NSDictionary` argument passed to your iOS app in either `didFinishLaunchingWithOptions` or `didReceiveRemoteNotification`.
-* `deliver_after` is not required, but may be set if you'd like to delay delivery of the notification to a specific time in the future.
-
-### Mobile Device Management
-
-    n = Rapns::Notification.new
-    n.mdm = "magic"
-    n.save!
-
-### Assigning a Hash to alert
-
-Please refer to Apple's [documentation](http://developer.apple.com/library/ios/#documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/ApplePushService/ApplePushService.html#//apple_ref/doc/uid/TP40008194-CH100-SW1) (Tables 3-1 and 3-2).
-
-## Hot App Updates
-
-If you signal the rapns process with `HUP` it will synchronize with the current `Rapns::App` configurations. This includes adding an app, removing and increasing/decreasing the number of connections an app uses.
-
-This synchronization process does not pause the delivery of notifications to other apps.
+    rapns <Rails environment> [options]
 
-## Logging
+See [Configuration](wiki/Configuration) for a list of options, or run `rapns --help`.
 
-rapns logs activity to `rapns.log` in your Rails log directory. This is also printed to STDOUT when running in the foreground. When running as a daemon rapns does not print to STDOUT or STDERR.
-
-## Delivery Failures
-
-The APNs provides two mechanism for delivery failure notification:
-
-### Immediately, when processing a notification for delivery.
-
-Although rapns makes such errors highly unlikely due to validation, the APNs reports processing errors immediately after being sent a notification. These errors are all centred around the well-formedness of the notification payload. Should a notification be rejected due to such an error, rapns will update the following attributes on the notification and send a notification via Airbrake/Hoptoad (if enabled):
-
-`failed` flag is set to true.
-`failed_at` is set to the time of failure.
-`error` is set to Apple's code for the error.
-`error_description` is set to a (somewhat brief) description of the error.
-
-rapns will not attempt to deliver the notification again.
-
-### Via the Feedback Service.
-
-rapns checks for feedback periodically and stores results in the `Rapns::Feedback` model. Each record contains the device token and a timestamp of when the APNs determined that the app no longer exists on the device.
-
-It is your responsibility to avoid creating new notifications for devices that no longer have your app installed. rapns does not and will not check `Rapns::Feedback` before sending notifications.
-
-*Note: In my testing and from other reports on the Internet, it appears you may not receive feedback when using the APNs sandbox environment.*
-
-## Updating rapns
+## Updating Rapns
 
 After updating you should run `rails g rapns` to check for any new migrations.
 
 ## Wiki
 
-* [Deploying to Heroku](https://github.com/ileitch/rapns/wiki/Heroku)
-* [Why open multiple connections to the APNs?](https://github.com/ileitch/rapns/wiki/Why-open-multiple-connections-to-the-APNs%3F)
+### General
+* [Configuration](wiki/Configuration)
+* [Upgrading from 2.x to 3.0](wiki/Upgrading-from-version-2.x-to-3.0)
+* [Deploying to Heroku](wiki/Heroku)
+* [Hot App Updates](wiki/Hot-App-Updates)
 
-## Contributing to rapns
+### APNs
+* [Advanced APNs Features](wiki/Advanced-APNs-Features)
+* [APNs Delivery Failure Handling](wiki/APNs-Delivery-Failure-Handling)
+* [Why open multiple connections to the APNs?](wiki/Why-open-multiple-connections-to-the-APNs%3F)
+* [Silent failures might be dropped connections](wiki/Dropped-connections)
+
+### GCM
+
+## Contributing
 
 Fork as usual and go crazy!
 
@@ -152,9 +117,13 @@ When running specs, please note that the ActiveRecord adapter can be changed by
 
 Available adapters for testing are `mysql`, `mysql2` and `postgresql`.
 
+Note that the database username is changed at runtime to be the currently logged in user's name. So if you're testing
+with mysql and you're using a user named 'bob', you will need to grant a mysql user 'bob' access to the 'rapns_test'
+mysql database.
+
 ### Contributors
 
-Thank you to the following wonderful people for contributing to rapns:
+Thank you to the following wonderful people for contributing:
 
 * [@blakewatters](https://github.com/blakewatters)
 * [@forresty](https://github.com/forresty)

data/bin/rapns

@@ -5,16 +5,23 @@ require 'rapns'
 
 environment = ARGV[0]
 
-config = Rapns.configuration
-
 banner = 'Usage: rapns <Rails environment> [options]'
+if environment.nil? || environment =~ /^-/
+  puts banner
+  exit 1
+end
+
+# A mock configuration to be used before the Rails environment is loaded.
+class CommandlineConfig < Struct.new(*Rapns::CONFIG_ATTRS); end
+config = CommandlineConfig.new
+
 ARGV.options do |opts|
   opts.banner = banner
   opts.on('-f', '--foreground', 'Run in the foreground.') { config.foreground = true }
   opts.on('-P N', '--db-poll N', Integer, "Frequency in seconds to check for new notifications. Default: #{config.push_poll}.") { |n| config.push_poll = n }
   opts.on('-F N', '--feedback-poll N', Integer, "Frequency in seconds to check for feedback. Default: #{config.feedback_poll}.") { |n| config.feedback_poll = n }
-  opts.on('-e', '--no-error-checks', 'Disable error checking after notification delivery.') { config.airbrake_notify = false }
-  opts.on('-n', '--no-airbrake-notify', 'Disables error notifications via Airbrake.') { config.check_for_errors = false }
+  opts.on('-e', '--no-error-checks', 'Disable APNs error checking after notification delivery.') { config.check_for_errors = false }
+  opts.on('-n', '--no-airbrake-notify', 'Disables error notifications via Airbrake.') { config.airbrake_notify = false }
   opts.on('-p PATH', '--pid-file PATH', String, 'Path to write PID file. Relative to Rails root unless absolute.') { |path| config.pid_file = path }
   opts.on('-b N', '--batch-size N', Integer, 'ActiveRecord notifications batch size.') { |n| config.batch_size = n }
   opts.on('-v', '--version', 'Print this version of rapns.') { puts "rapns #{Rapns::VERSION}"; exit }
@@ -22,20 +29,13 @@ ARGV.options do |opts|
   opts.parse!
 end
 
-if environment.nil? || environment =~ /^-/
-  puts banner
-  exit 1
-end
-
 ENV['RAILS_ENV'] = environment
 load 'config/environment.rb'
 load 'config/initializers/rapns.rb' if File.exist?('config/initializers/rapns.rb')
 
+Rapns.config.update(config)
+
 require 'rapns/daemon'
 require 'rapns/patches'
 
-if config.pid_file && !Pathname.new(config.pid_file).absolute?
-  config.pid_file = File.join(Rails.root, config.pid_file)
-end
-
-Rapns::Daemon.start(config)
+Rapns::Daemon.start

data/config/database.yml

@@ -29,3 +29,11 @@ mysql2:
   username: rapns_test
   password: ""
   encoding: utf8
+
+jdbcmysql:
+  adapter: jdbcmysql
+  database: rapns_test
+  host: localhost
+  username: rapns_test
+  password: ""
+  encoding: utf8

data/lib/generators/rapns_generator.rb

@@ -18,6 +18,10 @@ class RapnsGenerator < Rails::Generators::Base
     add_rapns_migration('add_gcm')
   end
 
+   def copy_config
+    copy_file 'rapns.rb', 'config/initializers/rapns.rb'
+  end
+
   protected
 
   def add_rapns_migration(template)
@@ -27,4 +31,4 @@ class RapnsGenerator < Rails::Generators::Base
       migration_template "#{template}.rb", "db/migrate/#{template}.rb"
     end
   end
-end
+end

data/lib/generators/templates/add_gcm.rb

@@ -25,6 +25,7 @@ class AddGcm < ActiveRecord::Migration
     change_column_null :rapns_apps, :certificate, true
 
     change_column :rapns_notifications, :error_description, :text
+    change_column :rapns_notifications, :sound, :string, :default => 'default'
 
     rename_column :rapns_notifications, :attributes_for_device, :data
     rename_column :rapns_apps, :key, :name
@@ -46,6 +47,9 @@ class AddGcm < ActiveRecord::Migration
 
     change_column_null :rapns_notifications, :app_id, false
     remove_column :rapns_notifications, :app
+
+    remove_index :rapns_notifications, :name => "index_rapns_notifications_multi"
+    add_index :rapns_notifications, [:app_id, :delivered, :failed, :deliver_after], :name => "index_rapns_notifications_multi"
   end
 
   def self.down
@@ -60,6 +64,7 @@ class AddGcm < ActiveRecord::Migration
     change_column_null :rapns_apps, :certificate, false
 
     change_column :rapns_notifications, :error_description, :string
+    change_column :rapns_notifications, :sound, :string, :default => '1.aiff'
 
     rename_column :rapns_notifications, :data, :attributes_for_device
     rename_column :rapns_apps, :name, :key
@@ -82,5 +87,8 @@ class AddGcm < ActiveRecord::Migration
 
     change_column_null :rapns_notifications, :key, false
     remove_column :rapns_notifications, :app_id
+
+    remove_index :rapns_notifications, :name => "index_rapns_notifications_multi"
+    add_index :rapns_notifications, [:delivered, :failed, :deliver_after], :name => "index_rapns_notifications_multi"
   end
 end

data/lib/generators/templates/rapns.rb

@@ -0,0 +1,39 @@
+ # Rapns configuration. Options set here are overridden by command-line options.
+
+ Rapns.configure do |config|
+
+  # Run in the foreground?
+  # config.foreground = false
+
+  # Frequency in seconds to check for new notifications.
+  # config.push_poll = 2
+
+  # Frequency in seconds to check for feedback
+  # config.feedback_poll = 60
+
+  # Enable/Disable error notifications via Airbrake.
+  # config.airbrake_notify = true
+
+  # Disable APNs error checking after notification delivery.
+  # config.check_for_errors = true
+
+  # ActiveRecord notifications batch size.
+  # config.batch_size = 5000
+
+  # Path to write PID file. Relative to Rails root unless absolute.
+  # config.pid_file = '/path/to/rapns.pid'
+
+  # Define a block that will be called with a Rapns::Apns::Feedback instance
+  # when feedback is received from the APNs that a notification has
+  # failed to be delivered. Further notifications should not be sent to the device.
+  #
+  # Example:
+  # config.on_apns_feedback do |feedback|
+  #   device = Device.find_by_device_token(feedback.device_token)
+  #   if device
+  #     device.active = false
+  #     device.save!
+  #   end
+  # end
+
+ end

data/lib/rapns.rb

@@ -9,6 +9,7 @@ require 'rapns/configuration'
 
 require 'rapns/apns/binary_notification_validator'
 require 'rapns/apns/device_token_format_validator'
+require 'rapns/apns/required_fields_validator'
 require 'rapns/apns/notification'
 require 'rapns/apns/feedback'
 require 'rapns/apns/app'

data/lib/rapns/apns/notification.rb

@@ -8,6 +8,7 @@ module Rapns
 
       validates_with Rapns::Apns::DeviceTokenFormatValidator
       validates_with Rapns::Apns::BinaryNotificationValidator
+      validates_with Rapns::Apns::RequiredFieldsValidator
 
       alias_method :attributes_for_device=, :data=
       alias_method :attributes_for_device, :data
@@ -79,6 +80,7 @@ module Rapns
         id_for_pack = options[:for_validation] ? 0 : id
         [1, id_for_pack, expiry, 0, 32, device_token, payload_size, payload].pack("cNNccH*na*")
       end
+
     end
   end
 end

data/lib/rapns/apns/required_fields_validator.rb

@@ -0,0 +1,14 @@
+module Rapns
+  module Apns
+    class RequiredFieldsValidator < ActiveModel::Validator
+
+      # Notifications must contain one of alert, badge or sound as per:
+      # https://developer.apple.com/library/ios/#documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/ApplePushService/ApplePushService.html
+      def validate(record)
+        if record.alert.nil? && record.badge.nil? && record.sound.nil?
+          record.errors[:base] << "APN Notification must contain one of alert, badge, or sound"
+        end
+      end
+    end
+  end
+end

data/lib/rapns/configuration.rb

@@ -1,28 +1,21 @@
 module Rapns
-
-  # A globally accessible instance of Rapns::Configuration
-  def self.configuration
-    @configuration ||= Rapns::Configuration.new
+  def self.config
+    @config ||= Rapns::Configuration.new
   end
 
-  # Call the given block yielding to it the global Rapns::Configuration instance for setting
-  # configuration values / callbacks.
-  #
-  # Typically this would be used in your Rails application's config/initializers/rapns.rb file
   def self.configure
-    yield configuration if block_given?
+    yield config if block_given?
   end
 
-  # A class to hold Rapns configuration settings and callbacks.
-  class Configuration < Struct.new(:foreground, :push_poll, :feedback_poll, :airbrake_notify, :check_for_errors, :pid_file, :batch_size)
+  CONFIG_ATTRS = [:foreground, :push_poll, :feedback_poll,
+    :airbrake_notify, :check_for_errors, :pid_file, :batch_size]
 
-    attr_accessor :feedback_callback
+  class Configuration < Struct.new(*CONFIG_ATTRS)
+    attr_accessor :apns_feedback_callback
 
-    # Initialize the Config with default values
     def initialize
       super
 
-      # defaults:
       self.foreground = false
       self.push_poll = 2
       self.feedback_poll = 60
@@ -31,25 +24,23 @@ module Rapns
       self.batch_size = 5000
     end
 
-    # Define a block that will be executed with a Rapns::Feedback instance when feedback has been received from the
-    # push notification servers that a notification has failed to be delivered. Further notifications should not
-    # be sent to this device token.
-    #
-    # Example usage (in config/initializers/rapns.rb):
-    #
-    #  Rapns.configure do |config|
-    #    config.on_feedback do |feedback|
-    #      device = Device.find_by_device_token feedback.device_token
-    #      if device
-    #        device.active = false
-    #        device.save
-    #      end
-    #    end
-    #  end
-    #
-    # Where `Device` is a model specific to your Rails app that has a `device_token` field.
-    def on_feedback(&block)
-      self.feedback_callback = block
+    def update(other)
+      CONFIG_ATTRS.each do |attr|
+        other_value = other.send(attr)
+        send("#{attr}=", other_value) unless other_value.nil?
+      end
+    end
+
+    def on_apns_feedback(&block)
+      self.apns_feedback_callback = block
+    end
+
+    def pid_file=(path)
+      if path && !Pathname.new(path).absolute?
+        super(File.join(Rails.root, path))
+      else
+        super
+      end
     end
   end
 end