rapns 3.0.1 → 3.1.0

data/CHANGELOG.md

@@ -1,7 +1,15 @@
-## 3.0.1 (Sun 16, 2012)
+## 3.1.0 (Jan 26, 2013)
+  * Rapns.reflect API for fine-grained introspection.
+  * Rapns.embed API for embedding Rapns into an existing process.
+  * Rapns.push API for using Rapns in scheduled jobs.
+  * Fix issue with integration with ActiveScaffold (#98) (@jeffarena).
+  * Fix content-available setter for APNs (#95) (@dup2).
+  * GCM validation fixes (#96) (@DianthuDia).
+
+## 3.0.1 (Dec 16, 2012)
   * Fix compatibility with Rails 3.0.x. Fixes #89.
 
-## 3.0.0 (Sat 15, 2012)
+## 3.0.0 (Dec 15, 2012)
   * Add support for Google Cloud Messaging.
   * Fix Heroku logging issue.
 

data/README.md

@@ -1,14 +1,18 @@
 [![Build Status](https://secure.travis-ci.org/ileitch/rapns.png?branch=master)](http://travis-ci.org/ileitch/rapns)
 
-### Rapns - Professional grade APNs and GCM daemon
+### Rapns - Professional grade APNs and GCM for Ruby.
 
 * 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.
+* Run as a daemon or inside an existing process.
+* Use in a scheduler for low-workload deployments ([Push API](rapns/wiki/Push-API)).
+* Reflection API for fine-grained instrumentation ([Reflection API](rapns/wiki/Relfection-API)).
 * Works with MRI, JRuby, Rubinius 1.8 and 1.9.
 * [Airbrake](http://airbrakeapp.com/) integration.
+* Built with a love for Open Source :)
 
 #### 2.x users please read [upgrading from 2.x to 3.0](rapns/wiki/Upgrading-from-version-2.x-to-3.0)
 
@@ -36,11 +40,16 @@ Generate the migrations, rapns.yml and migrate:
 3. Select both the certificate and private key.
 4. Right click and select `Export 2 items...`.
 5. Save the file as `cert.p12`, make sure the File Format is `Personal Information Exchange (p12)`.
-6. If you decide to set a password for your exported certificate, please read the 'Adding Apps' section below.
-7. Convert the certificate to a .pem, where `<environment>` should be `development` or `production`, depending on the certificate you exported.
+6. Convert the certificate to a .pem, where `<environment>` should be `development` or `production`, depending on the certificate you exported.
+
+Without a password:
 
     `openssl pkcs12 -nodes -clcerts -in cert.p12 -out <environment>.pem`
 
+With a password:
+
+    `openssl pkcs12 -clcerts -in cert.p12 -out <environment>.pem`
+
 ## Create an App
 
 #### APNs
@@ -86,9 +95,17 @@ n.save!
 
 ## Starting Rapns
 
+As a daemon:
+
     cd /path/to/rails/app
     rapns <Rails environment> [options]
 
+Inside an existing process:
+
+    Rapns.embed
+
+*Please note that only ever a single instance of Rapns should be running.*
+
 See [Configuration](rapns/wiki/Configuration) for a list of options, or run `rapns --help`.
 
 ## Updating Rapns
@@ -102,6 +119,9 @@ After updating you should run `rails g rapns` to check for any new migrations.
 * [Upgrading from 2.x to 3.0](rapns/wiki/Upgrading-from-version-2.x-to-3.0)
 * [Deploying to Heroku](rapns/wiki/Heroku)
 * [Hot App Updates](rapns/wiki/Hot-App-Updates)
+* [Reflection API](rapns/wiki/Reflection-API)
+* [Push API](rapns/wiki/Push-API)
+* [Embedding API](rapns/wiki/Embedding-API)
 
 ### APNs
 * [Advanced APNs Features](rapns/wiki/Advanced-APNs-Features)
@@ -138,3 +158,6 @@ Thank you to the following wonderful people for contributing:
 * [@adorr](https://github.com/adorr)
 * [@mattconnolly](https://github.com/mattconnolly)
 * [@emeitch](https://github.com/emeitch)
+* [@jeffarena](https://github.com/jeffarena)
+* [@DianthuDia](https://github.com/DianthuDia)
+* [@dup2](https://github.com/dup2)

data/bin/rapns

@@ -11,9 +11,7 @@ if environment.nil? || environment =~ /^-/
   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
+config = Rapns::ConfigurationWithoutDefaults.new
 
 ARGV.options do |opts|
   opts.banner = banner
@@ -34,8 +32,5 @@ 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'
-
+Rapns.require_for_daemon
 Rapns::Daemon.start

data/lib/generators/templates/add_gcm.rb

@@ -34,7 +34,9 @@ class AddGcm < ActiveRecord::Migration
 
     add_column :rapns_notifications, :collapse_key, :string, :null => true
     add_column :rapns_notifications, :delay_while_idle, :boolean, :null => false, :default => false
-    add_column :rapns_notifications, :registration_ids, :text, :null => true
+
+    reg_ids_type = ActiveRecord::Base.connection.adapter_name.include?('Mysql') ? :mediumtext : :text
+    add_column :rapns_notifications, :registration_ids, reg_ids_type, :null => true
     add_column :rapns_notifications, :app_id, :integer, :null => true
     add_column :rapns_notifications, :retries, :integer, :null => true, :default => 0
 

data/lib/generators/templates/rapns.rb

@@ -23,17 +23,48 @@
   # 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.
+ end
+
+Rapns.reflect do |on|
+
+  # 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.
+  # on.apns_feedback do |feedback|
+  # end
+
+  # Called when a notification is queued internally for delivery.
+  # The internal queue for each app runner can be inspected:
   #
-  # Example:
-  # config.on_apns_feedback do |feedback|
-  #   device = Device.find_by_device_token(feedback.device_token)
-  #   if device
-  #     device.active = false
-  #     device.save!
-  #   end
+  # Rapns::Daemon::AppRunner.runners.each do |app_id, runner|
+  #   runner.app
+  #   runner.queue_size
+  # end
+  #
+  # on.notification_enqueued do |notification|
   # end
 
- end
+  # Called when a notification is successfully delivered.
+  # on.notification_delivered do |notification|
+  # end
+
+  # Called when notification delivery failed.
+  # Call 'error_code' and 'error_description' on the notification for the cause.
+  # on.notification_failed do |notification|
+  # end
+
+  # Called when a notification will be retried at a later date.
+  # Call 'deliver_after' on the notification for the next delivery date
+  # and 'retries' for the number of times this notification has been retried.
+  # on.notification_will_retry do |notification|
+  # end
+
+  # Called when an APNs connection is lost and will be reconnected.
+  # on.apns_connection_lost do |app, error|
+  # end
+
+  # Called when an exception is raised.
+  # on.error do |error|
+  # end
+
+end

data/lib/rapns/apns/notification.rb

@@ -43,13 +43,13 @@ module Rapns
 
       MDM_KEY = '__rapns_mdm__'
       def mdm=(magic)
-        self.attributes_for_device = { MDM_KEY => magic }
+        self.attributes_for_device = (attributes_for_device || {}).merge({ MDM_KEY => magic })
       end
 
       CONTENT_AVAILABLE_KEY = '__rapns_content_available__'
       def content_available=(bool)
         return unless bool
-        self.attributes_for_device = { CONTENT_AVAILABLE_KEY => true }
+        self.attributes_for_device = (attributes_for_device || {}).merge({ CONTENT_AVAILABLE_KEY => true })
       end
 
       def as_json
@@ -81,6 +81,12 @@ module Rapns
         [1, id_for_pack, expiry, 0, 32, device_token, payload_size, payload].pack("cNNccH*na*")
       end
 
+      def data=(attrs)
+        return unless attrs
+        raise ArgumentError, "must be a Hash" if !attrs.is_a?(Hash)
+        super attrs.merge(data || {})
+      end
+
     end
   end
 end

data/lib/rapns/app.rb

@@ -4,7 +4,7 @@ module Rapns
 
     attr_accessible :name, :environment, :certificate, :password, :connections, :auth_key
 
-    has_many :notifications
+    has_many :notifications, :class_name => 'Rapns::Notification'
 
     validates :name, :presence => true, :uniqueness => { :scope => [:type, :environment] }
     validates_numericality_of :connections, :greater_than => 0, :only_integer => true
@@ -16,8 +16,8 @@ module Rapns
     def certificate_has_matching_private_key
       result = false
       if certificate.present?
-        x509 = OpenSSL::X509::Certificate.new certificate rescue nil
-        pkey = OpenSSL::PKey::RSA.new certificate rescue nil
+        x509 = OpenSSL::X509::Certificate.new(certificate) rescue nil
+        pkey = OpenSSL::PKey::RSA.new(certificate, password) rescue nil
         result = !x509.nil? && !pkey.nil?
         unless result
           errors.add :certificate, 'Certificate value must contain a certificate and a private key.'

data/lib/rapns/configuration.rb

@@ -7,21 +7,21 @@ module Rapns
     yield config if block_given?
   end
 
-  CONFIG_ATTRS = [:foreground, :push_poll, :feedback_poll,
-    :airbrake_notify, :check_for_errors, :pid_file, :batch_size]
+  CONFIG_ATTRS = [:foreground, :push_poll, :feedback_poll, :embedded,
+    :airbrake_notify, :check_for_errors, :pid_file, :batch_size,
+    :push]
+
+  class ConfigurationWithoutDefaults < Struct.new(*CONFIG_ATTRS)
+  end
 
   class Configuration < Struct.new(*CONFIG_ATTRS)
+    include Deprecatable
+
     attr_accessor :apns_feedback_callback
 
     def initialize
       super
-
-      self.foreground = false
-      self.push_poll = 2
-      self.feedback_poll = 60
-      self.airbrake_notify = true
-      self.check_for_errors = true
-      self.batch_size = 5000
+      set_defaults
     end
 
     def update(other)
@@ -31,10 +31,6 @@ module Rapns
       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))
@@ -42,5 +38,42 @@ module Rapns
         super
       end
     end
+
+    def foreground=(bool)
+      if defined? JRUBY_VERSION
+        # The JVM does not support fork().
+        super(true)
+      else
+        super
+      end
+    end
+
+    def on_apns_feedback(&block)
+      self.apns_feedback_callback = block
+    end
+    deprecated(:on_apns_feedback, 3.2, "Please use the Rapns.reflect API instead.")
+
+    private
+
+    def set_defaults
+      if defined? JRUBY_VERSION
+        # The JVM does not support fork().
+        self.foreground = true
+      else
+        self.foreground = false
+      end
+
+      self.push_poll = 2
+      self.feedback_poll = 60
+      self.airbrake_notify = true
+      self.check_for_errors = true
+      self.batch_size = 5000
+      self.pid_file = nil
+      self.apns_feedback_callback = nil
+
+      # Internal options.
+      self.embedded = false
+      self.push = false
+    end
   end
 end

data/lib/rapns/daemon/apns/connection.rb

@@ -4,18 +4,20 @@ module Rapns
       class ConnectionError < StandardError; end
 
       class Connection
+        include Reflectable
+
         attr_accessor :last_write
 
         def self.idle_period
           30.minutes
         end
 
-        def initialize(name, host, port, certificate, password)
-          @name = name
+        def initialize(app, host, port)
+          @app = app
           @host = host
           @port = port
-          @certificate = certificate
-          @password = password
+          @certificate = app.certificate
+          @password = app.password
           written
         end
 
@@ -51,7 +53,8 @@ module Rapns
             retry_count += 1;
 
             if retry_count == 1
-              Rapns::Daemon.logger.error("[#{@name}] Lost connection to #{@host}:#{@port} (#{e.class.name}), reconnecting...")
+              Rapns::Daemon.logger.error("[#{@app.name}] Lost connection to #{@host}:#{@port} (#{e.class.name}), reconnecting...")
+              reflect(:apns_connection_lost, @app, e)
             end
 
             if retry_count <= 3
@@ -59,7 +62,7 @@ module Rapns
               sleep 1
               retry
             else
-              raise ConnectionError, "#{@name} tried #{retry_count-1} times to reconnect but failed (#{e.class.name})."
+              raise ConnectionError, "#{@app.name} tried #{retry_count-1} times to reconnect but failed (#{e.class.name})."
             end
           end
         end
@@ -72,7 +75,7 @@ module Rapns
         protected
 
         def reconnect_idle
-          Rapns::Daemon.logger.info("[#{@name}] Idle period exceeded, reconnecting...")
+          Rapns::Daemon.logger.info("[#{@app.name}] Idle period exceeded, reconnecting...")
           reconnect
         end
 
@@ -104,10 +107,10 @@ module Rapns
           ssl_socket = OpenSSL::SSL::SSLSocket.new(tcp_socket, @ssl_context)
           ssl_socket.sync = true
           ssl_socket.connect
-          Rapns::Daemon.logger.info("[#{@name}] Connected to #{@host}:#{@port}")
+          Rapns::Daemon.logger.info("[#{@app.name}] Connected to #{@host}:#{@port}")
           [tcp_socket, ssl_socket]
         end
       end
     end
   end
-end
+end

data/lib/rapns/daemon/apns/delivery_handler.rb

@@ -4,7 +4,7 @@ module Rapns
       class DeliveryHandler < Rapns::Daemon::DeliveryHandler
         def initialize(app, host, port)
           @app = app
-          @connection = Connection.new(@app.name, host, port, @app.certificate, @app.password)
+          @connection = Connection.new(@app, host, port)
           @connection.connect
         end
 

data/lib/rapns/daemon/apns/feedback_receiver.rb

@@ -2,6 +2,7 @@ module Rapns
   module Daemon
     module Apns
       class FeedbackReceiver
+        include Reflectable
         include InterruptibleSleep
         include DatabaseReconnectable
 
@@ -35,7 +36,7 @@ module Rapns
         def check_for_feedback
           connection = nil
           begin
-            connection = Connection.new("FeedbackReceiver:#{@app.name}", @host, @port, @certificate, @password)
+            connection = Connection.new(@app, @host, @port)
             connection.connect
 
             while tuple = connection.read(FEEDBACK_TUPLE_BYTES)
@@ -59,8 +60,11 @@ module Rapns
         def create_feedback(failed_at, device_token)
           formatted_failed_at = failed_at.strftime("%Y-%m-%d %H:%M:%S UTC")
           with_database_reconnect_and_retry do
-            Rapns::Daemon.logger.info("[FeedbackReceiver:#{@app.name}] Delivery failed at #{formatted_failed_at} for #{device_token}")
+            Rapns::Daemon.logger.info("[#{@app.name}] [FeedbackReceiver] Delivery failed at #{formatted_failed_at} for #{device_token}.")
             feedback = Rapns::Apns::Feedback.create!(:failed_at => failed_at, :device_token => device_token, :app => @app)
+            reflect(:apns_feedback, feedback)
+
+            # Deprecated.
             begin
               Rapns.config.apns_feedback_callback.call(feedback) if Rapns.config.apns_feedback_callback
             rescue StandardError => e

data/lib/rapns/daemon/app_runner.rb

@@ -2,7 +2,7 @@ module Rapns
   module Daemon
     class AppRunner
       class << self
-        attr_reader :runners # TODO: Needed?
+        attr_reader :runners
       end
 
       @runners = {}
@@ -86,20 +86,28 @@ module Rapns
         diff = handlers.size - app.connections
         return if diff == 0
         if diff > 0
-          diff.times { handlers.pop.stop }
-          Rapns::Daemon.logger.info("[#{app.name}] Terminated #{handlers_str(diff)}. #{handlers_str} remaining.")
+          diff.times { decrement_handlers }
+          Rapns::Daemon.logger.info("[#{app.name}] Stopped #{handlers_str(diff)}. #{handlers_str} remaining.")
         else
-          diff.abs.times { handlers << start_handler }
-          Rapns::Daemon.logger.info("[#{app.name}] Added #{handlers_str(diff)}. #{handlers_str} remaining.")
+          diff.abs.times { increment_handlers }
+          Rapns::Daemon.logger.info("[#{app.name}] Started #{handlers_str(diff)}. #{handlers_str} remaining.")
         end
       end
 
+      def decrement_handlers
+        handlers.pop.stop
+      end
+
+      def increment_handlers
+        handlers << start_handler
+      end
+
       def debug
         Rapns::Daemon.logger.info <<-EOS
 
 #{@app.name}:
-  handlers: #{handlers.size}
-  queued: #{queue.size}
+  handlers: #{num_handlers}
+  queued: #{queue_size}
   idle: #{idle?}
         EOS
       end
@@ -108,6 +116,14 @@ module Rapns
         queue.notifications_processed?
       end
 
+      def queue_size
+        queue.size
+      end
+
+      def num_handlers
+        handlers.size
+      end
+
       protected
 
       def start_handler

data/lib/rapns/daemon/delivery.rb

@@ -2,6 +2,7 @@ module Rapns
   module Daemon
     class Delivery
       include DatabaseReconnectable
+      include Reflectable
 
       def self.perform(*args)
         new(*args).perform
@@ -13,6 +14,7 @@ module Rapns
           notification.deliver_after = deliver_after
           notification.save!(:validate => false)
         end
+        reflect(:notification_will_retry, notification)
       end
 
       def retry_exponentially(notification)
@@ -25,6 +27,7 @@ module Rapns
           @notification.delivered_at = Time.now
           @notification.save!(:validate => false)
         end
+        reflect(:notification_delivered, @notification)
       end
 
       def mark_failed(code, description)
@@ -37,7 +40,8 @@ module Rapns
           @notification.error_description = description
           @notification.save!(:validate => false)
         end
+        reflect(:notification_failed, @notification)
       end
     end
   end
-end
+end

data/lib/rapns/daemon/delivery_handler.rb

@@ -1,6 +1,8 @@
 module Rapns
   module Daemon
     class DeliveryHandler
+      include Reflectable
+
       attr_accessor :queue
 
       def start
@@ -35,8 +37,10 @@ module Rapns
 
         begin
           deliver(notification)
+          reflect(:notification_delivered, notification)
         rescue StandardError => e
           Rapns::Daemon.logger.error(e)
+          reflect(:error, e)
         ensure
           queue.notification_processed
         end

data/lib/rapns/daemon/feeder.rb

@@ -3,12 +3,17 @@ module Rapns
     class Feeder
       extend InterruptibleSleep
       extend DatabaseReconnectable
+      extend Reflectable
 
-      def self.start(poll)
-        loop do
+      def self.start
+        @stop = false
+
+        if Rapns.config.embedded
+          Thread.new { feed_forever }
+        elsif Rapns.config.push
           enqueue_notifications
-          interruptible_sleep poll
-          break if @stop
+        else
+          feed_forever
         end
       end
 
@@ -19,17 +24,33 @@ module Rapns
 
       protected
 
+      def self.feed_forever
+        loop do
+          enqueue_notifications
+          interruptible_sleep(Rapns.config.push_poll)
+          break if stop?
+        end
+      end
+
+      def self.stop?
+        @stop
+      end
+
       def self.enqueue_notifications
         begin
           with_database_reconnect_and_retry do
             batch_size = Rapns.config.batch_size
             idle = Rapns::Daemon::AppRunner.idle.map(&:app)
-            Rapns::Notification.ready_for_delivery.for_apps(idle).limit(batch_size).each do |notification|
+            relation = Rapns::Notification.ready_for_delivery.for_apps(idle)
+            relation = relation.limit(batch_size) unless Rapns.config.push
+            relation.each do |notification|
               Rapns::Daemon::AppRunner.enqueue(notification)
+              reflect(:notification_enqueued, notification)
             end
           end
         rescue StandardError => e
           Rapns::Daemon.logger.error(e)
+          reflect(:error, e)
         end
       end
     end

data/lib/rapns/daemon/reflectable.rb

@@ -0,0 +1,13 @@
+module Rapns
+  module Daemon
+    module Reflectable
+      def reflect(name, *args)
+        begin
+          Rapns.reflections.__dispatch(name, *args)
+        rescue StandardError => e
+          Rapns::Daemon.logger.error(e)
+        end
+      end
+    end
+  end
+end