rapns 0.2.3 → 1.0.0

data/README.md

@@ -4,11 +4,14 @@ Easy to use library for Apple's Push Notification Service with Rails 3.
 
 ## Features
 
-* Works with Rails 3 and Ruby 1.9.
+* Works with Rails 3 and Ruby 1.9 & 1.8.
 * Uses a daemon process to keep open a persistent connection to the Push Notification Service, as recommended by Apple.
 * Uses the [enhanced binary format](http://developer.apple.com/library/ios/#documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CommunicatingWIthAPS/CommunicatingWIthAPS.html#//apple_ref/doc/uid/TP40008194-CH101-SW4) (Figure 5-2) so that delivery errors can be reported.
+* Records feedback from [The Feedback Service](http://developer.apple.com/library/mac/#documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CommunicatingWIthAPS/CommunicatingWIthAPS.html#//apple_ref/doc/uid/TP40008194-CH101-SW3).
 * [Airbrake](http://airbrakeapp.com/) (Hoptoad) integration.
 * Support for [dictionary `alert` properties](http://developer.apple.com/library/ios/#documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/ApplePushService/ApplePushService.html#//apple_ref/doc/uid/TP40008194-CH100-SW1) (Table 3-2).
+* Reconnects to the APNs if connections are lost.
+* Reconnects to your database if the connect is lost.
 
 ## Getting Started
 
@@ -43,13 +46,20 @@ If you want to use rapns in environments other than development or production, y
 
 ### Options:
 
-* `host` the APNs host to connect to, either `gateway.sandbox.push.apple.com` or `gateway.sandbox.push.apple.com`.
-* `port` the APNs port. Currently `2195` for both hosts.
+* `push` this section contains options to configure the delivery of notifications.
+    * `host` the APNs host to connect to, either `gateway.push.apple.com` or `gateway.sandbox.push.apple.com`.
+    * `port` the APNs port. Currently `2195` for both hosts.
+    * `poll` (default: 2) Frequency in seconds to check for new notifications to deliver.
+    * `connections` (default: 3) the number of connections to keep open to the APNs. Consider increasing this if you are sending a very large number of notifications.
+    
+* `feedback` this section contains options to configure feedback checking.
+    * `host` the APNs host to connect to, either `feedback.push.apple.com` or `feedback.sandbox.push.apple.com`.
+    * `port` the APNs port. Currently `2196` for both hosts.
+    * `poll` (default: 60) Frequency in seconds to check for new feedback.
+
 * `certificate` The path to your .pem certificate, `config/rapns` is automatically checked if a relative path is given.
 * `certificate_password` (default: blank) the password you used when exporting your certificate, if any.
 * `airbrake_notify` (default: true) Enables/disables error notifications via Airbrake.
-* `poll` (default: 2) Frequency in seconds to check for new notifications to deliver.
-* `connections` (default: 3) the number of connections to keep open to the APNs. Consider increasing this if you are sending a very large number of notifications.
 * `pid_file` (default: blank) the file that rapns will write its process ID to. Paths are relative to your project's RAILS_ROOT unless an absolute path is given.
 
 ## Starting the rapns Daemon
@@ -86,11 +96,9 @@ rapns logs activity to `rapns.log` in your Rails log directory. This is also pri
 
 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).
 
-Not yet implemented!
-
 ## Delivery Failures
 
-The APN service provides two mechanism for delivery failure notification:
+The APNs provides two mechanism for delivery failure notification:
 
 ### Immediately, when processing a notification for delivery.
 
@@ -105,7 +113,15 @@ rapns will not attempt to deliver the notification again.
 
 ### Via the Feedback Service.
 
-Not implemented yet!
+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
+
+After updating you should run `rails g rapns` to check for any new migrations or configuration changes.
 
 ## Contributing to rapns
 
@@ -113,4 +129,13 @@ Fork as usual and go crazy!
 
 When running specs, please note that the ActiveRecord adapter can be changed by setting the `ADAPTER` environment variable. For example: `ADAPTER=postgresql rake`.
 
-Available adapters for testing are `mysql`, `mysql2` and `postgresql`.
+Available adapters for testing are `mysql`, `mysql2` and `postgresql`.
+
+### Contributors
+
+Thank you to the following wonderful people for contributing to rapns:
+
+* [@blakewatters](https://github.com/blakewatters)
+* [@forresty](https://github.com/forresty)
+* [@sjmadsen](https://github.com/sjmadsen)
+* [@ivanyv](https://github.com/ivanyv)

data/lib/generators/rapns_generator.rb

@@ -7,7 +7,15 @@ class RapnsGenerator < Rails::Generators::Base
   end
 
   def copy_migration
-     migration_template "create_rapns_notifications.rb", "db/migrate/create_rapns_notifications.rb"
+    migration_dir = File.expand_path("db/migrate")
+
+    if !self.class.migration_exists?(migration_dir, 'create_rapns_notifications')
+      migration_template "create_rapns_notifications.rb", "db/migrate/create_rapns_notifications.rb"
+    end
+
+    if !self.class.migration_exists?(migration_dir, 'create_rapns_feedback')
+      migration_template "create_rapns_feedback.rb", "db/migrate/create_rapns_feedback.rb"
+    end
   end
 
   def copy_config

data/lib/generators/templates/create_rapns_feedback.rb

@@ -0,0 +1,15 @@
+class CreateRapnsFeedback < ActiveRecord::Migration
+  def self.up
+    create_table :rapns_feedback do |t|
+      t.string    :device_token,          :null => false, :limit => 64
+      t.timestamp :failed_at,             :null => false
+      t.timestamps
+    end
+
+    add_index :rapns_feedback, :device_token
+  end
+
+  def self.down
+    drop_table :rapns_feedback
+  end
+end

data/lib/generators/templates/rapns.yml

@@ -1,18 +1,31 @@
 development:
-  host: gateway.sandbox.push.apple.com
-  port: 2195
   certificate: development.pem
   certificate_password:
-  airbrake_notify: true
-  poll: 2
-  connections: 3
+
+  push:
+    host: gateway.sandbox.push.apple.com
+    port: 2195
+    poll: 2
+    connections: 3
+
+  feedback:
+    host: feedback.sandbox.push.apple.com
+    port: 2196
+    poll: 60
 
 production:
-  host: gateway.push.apple.com
-  port: 2195
   certificate: production.pem
   certificate_password:
   airbrake_notify: true
-  poll: 2
-  connections: 3
   pid_file: tmp/pids/rapns.pid
+
+  push:
+    host: gateway.push.apple.com
+    port: 2195
+    poll: 2
+    connections: 3
+
+  feedback:
+    host: feedback.push.apple.com
+    port: 2196
+    poll: 60

data/lib/rapns/daemon/configuration.rb

@@ -5,26 +5,35 @@ module Rapns
 
   module Daemon
     class Configuration
-      attr_accessor :host, :port, :certificate, :certificate_password, :poll, :airbrake_notify, :connections, :pid_file
+      attr_accessor :push, :feedback
+      attr_accessor :certificate, :certificate_password, :airbrake_notify, :pid_file
       alias_method  :airbrake_notify?, :airbrake_notify
 
       def initialize(environment, config_path)
         @environment = environment
         @config_path = config_path
+
+        self.push = Struct.new(:host, :port, :connections, :poll).new
+        self.feedback = Struct.new(:host, :port, :poll).new
       end
 
       def load
         config = read_config
         ensure_environment_configured(config)
         config = config[@environment]
-        set_variable(:host, config)
-        set_variable(:port, config)
-        set_variable(:certificate, config)
-        set_variable(:airbrake_notify, config, :optional => true, :default => true)
-        set_variable(:certificate_password, config, :optional => true, :default => "")
-        set_variable(:poll, config, :optional => true, :default => 2)
-        set_variable(:connections, config, :optional => true, :default => 3)
-        set_variable(:pid_file, config, :optional => true, :default => "")
+        set_variable(:push, :host, config)
+        set_variable(:push, :port, config)
+        set_variable(:push, :poll, config, :optional => true, :default => 2)
+        set_variable(:push, :connections, config, :optional => true, :default => 3)
+
+        set_variable(:feedback, :host, config)
+        set_variable(:feedback, :port, config)
+        set_variable(:feedback, :poll, config, :optional => true, :default => 60)
+
+        set_variable(nil, :certificate, config)
+        set_variable(nil, :airbrake_notify, config, :optional => true, :default => true)
+        set_variable(nil, :certificate_password, config, :optional => true, :default => "")
+        set_variable(nil, :pid_file, config, :optional => true, :default => "")
       end
 
       def certificate
@@ -52,15 +61,24 @@ module Rapns
         File.open(@config_path) { |fd| YAML.load(fd) }
       end
 
-      def set_variable(key, config, options = {})
-        if !config.key?(key.to_s) || config[key.to_s].to_s.strip == ""
+      def set_variable(base_key, key, config, options = {})
+        if base_key
+          base = send(base_key)
+          value = config.key?(base_key.to_s) ? config[base_key.to_s][key.to_s] : nil
+        else
+          base = self
+          value = config[key.to_s]
+        end
+
+        if value.to_s.strip == ""
           if options[:optional]
-            instance_variable_set("@#{key}", options[:default])
+            base.send("#{key}=", options[:default])
           else
-            raise Rapns::ConfigurationError, "'#{key}' not defined for environment '#{@environment}' in #{@config_path}"
+            key_path = base_key ? "#{base_key}.#{key}" : key
+            raise Rapns::ConfigurationError, "'#{key_path}' not defined for environment '#{@environment}' in #{@config_path}. You may need to run 'rails g rapns' after updating."
           end
         else
-          instance_variable_set("@#{key}", config[key.to_s])
+          base.send("#{key}=", value)
         end
       end
 

data/lib/rapns/daemon/connection.rb

@@ -3,22 +3,10 @@ module Rapns
     class ConnectionError < StandardError; end
 
     class Connection
-      SELECT_TIMEOUT = 0.5
-      ERROR_PACKET_BYTES = 6
-      APN_ERRORS = {
-        1 => "Processing error",
-        2 => "Missing device token",
-        3 => "Missing topic",
-        4 => "Missing payload",
-        5 => "Missing token size",
-        6 => "Missing topic size",
-        7 => "Missing payload size",
-        8 => "Invalid token",
-        255 => "None (unknown error)"
-      }
-
-      def initialize(name)
+      def initialize(name, host, port)
         @name = name
+        @host = host
+        @port = port
       end
 
       def connect
@@ -27,56 +15,53 @@ module Rapns
       end
 
       def close
-        @ssl_socket.close if @ssl_socket
-        @tcp_socket.close if @tcp_socket
+        begin
+          @ssl_socket.close if @ssl_socket
+          @tcp_socket.close if @tcp_socket
+        rescue IOError
+        end
+      end
+
+      def read(num_bytes)
+        @ssl_socket.read(num_bytes)
+      end
+
+      def select(timeout)
+        IO.select([@ssl_socket], nil, nil, timeout)
       end
 
       def write(data)
         retry_count = 0
 
         begin
-          @ssl_socket.write(data)
-          @ssl_socket.flush
+          write_data(data)
+        rescue Errno::EPIPE, Errno::ETIMEDOUT, OpenSSL::SSL::SSLError => e
+          retry_count += 1;
 
-          check_for_error
-        rescue Errno::EPIPE, OpenSSL::SSL::SSLError => e
-          Rapns::Daemon.logger.error("[#{@name}] Lost connection to #{Rapns::Daemon.configuration.host}:#{Rapns::Daemon.configuration.port}, reconnecting...")
-          @tcp_socket, @ssl_socket = connect_socket
-
-          retry_count += 1
+          if retry_count == 1
+            Rapns::Daemon.logger.error("[#{@name}] Lost connection to #{@host}:#{@port} (#{e.class.name}), reconnecting...")
+          end
 
-          if retry_count < 3
+          if retry_count <= 3
+            reconnect
             sleep 1
             retry
           else
-            raise ConnectionError, "#{@name} tried #{retry_count} times to reconnect but failed: #{e.inspect}"
+            raise ConnectionError, "#{@name} tried #{retry_count-1} times to reconnect but failed (#{e.class.name})."
           end
         end
       end
 
-      protected
-
-      def check_for_error
-        if IO.select([@ssl_socket], nil, nil, SELECT_TIMEOUT)
-          delivery_error = nil
-
-          if error = @ssl_socket.read(ERROR_PACKET_BYTES)
-            cmd, status, notification_id = error.unpack("ccN")
+      def reconnect
+        close
+        @tcp_socket, @ssl_socket = connect_socket
+      end
 
-            if cmd == 8 && status != 0
-              description = APN_ERRORS[status] || "Unknown error. Possible rapns bug?"
-              delivery_error = Rapns::DeliveryError.new(status, description, notification_id)
-            end
-          end
+      protected
 
-          begin
-            Rapns::Daemon.logger.error("[#{@name}] Error received, reconnecting...")
-            close
-            @tcp_socket, @ssl_socket = connect_socket
-          ensure
-            raise delivery_error if delivery_error
-          end
-        end
+      def write_data(data)
+        @ssl_socket.write(data)
+        @ssl_socket.flush
       end
 
       def setup_ssl_context
@@ -87,13 +72,13 @@ module Rapns
       end
 
       def connect_socket
-        tcp_socket = TCPSocket.new(Rapns::Daemon.configuration.host, Rapns::Daemon.configuration.port)
+        tcp_socket = TCPSocket.new(@host, @port)
         tcp_socket.setsockopt(Socket::SOL_SOCKET, Socket::SO_KEEPALIVE, 1)
         tcp_socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
         ssl_socket = OpenSSL::SSL::SSLSocket.new(tcp_socket, @ssl_context)
         ssl_socket.sync = true
         ssl_socket.connect
-        Rapns::Daemon.logger.info("[#{@name}] Connected to #{Rapns::Daemon.configuration.host}:#{Rapns::Daemon.configuration.port}")
+        Rapns::Daemon.logger.info("[#{@name}] Connected to #{@host}:#{@port}")
         [tcp_socket, ssl_socket]
       end
     end

data/lib/rapns/daemon/delivery_handler.rb

@@ -2,9 +2,33 @@ module Rapns
   module Daemon
     class DeliveryHandler
       STOP = 0x666
+      ERROR_CMD = 8
+      OK_STATUS = 0
+      SELECT_TIMEOUT = 0.5
+      ERROR_TUPLE_BYTES = 6
+      APN_ERRORS = {
+        1 => "Processing error",
+        2 => "Missing device token",
+        3 => "Missing topic",
+        4 => "Missing payload",
+        5 => "Missing token size",
+        6 => "Missing topic size",
+        7 => "Missing payload size",
+        8 => "Invalid token",
+        255 => "None (unknown error)"
+      }
+
+      def initialize(i)
+        @name = "DeliveryHandler #{i}"
+        host = Rapns::Daemon.configuration.push.host
+        port = Rapns::Daemon.configuration.push.port
+        @connection = Connection.new(@name, host, port)
+      end
 
       def start
-        Thread.new do 
+        @connection.connect
+
+        Thread.new do
           loop do
             break if @stop
             handle_next_notification
@@ -14,29 +38,28 @@ module Rapns
 
       def stop
         @stop = true
+        Rapns::Daemon.delivery_queue.push(STOP)
       end
 
       protected
 
       def deliver(notification)
-        Rapns::Daemon.connection_pool.claim_connection do |connection|
-          begin
-            connection.write(notification.to_binary)
+        begin
+          @connection.write(notification.to_binary)
+          check_for_error
 
-            notification.delivered = true
-            notification.delivered_at = Time.now
-            notification.save!(:validate => false)
+          notification.delivered = true
+          notification.delivered_at = Time.now
+          notification.save!(:validate => false)
 
-            Rapns::Daemon.logger.info("Notification #{notification.id} delivered to #{notification.device_token}")
-          rescue Rapns::DeliveryError => error
-            handle_delivery_error(notification, error)
-          end
+          Rapns::Daemon.logger.info("Notification #{notification.id} delivered to #{notification.device_token}")
+        rescue Rapns::DeliveryError => error
+          handle_delivery_error(notification, error)
+          raise
         end
       end
 
       def handle_delivery_error(notification, error)
-        Rapns::Daemon.logger.error(error)
-
         notification.delivered = false
         notification.delivered_at = nil
         notification.failed = true
@@ -46,15 +69,42 @@ module Rapns
         notification.save!(:validate => false)
       end
 
+      def check_for_error
+        if @connection.select(SELECT_TIMEOUT)
+          delivery_error = nil
+
+          if error = @connection.read(ERROR_TUPLE_BYTES)
+            cmd, status, notification_id = error.unpack("ccN")
+
+            if cmd == ERROR_CMD && status != OK_STATUS
+              description = APN_ERRORS[status] || "Unknown error. Possible rapns bug?"
+              delivery_error = Rapns::DeliveryError.new(status, description, notification_id)
+            end
+          end
+
+          begin
+            Rapns::Daemon.logger.error("[#{@name}] Error received, reconnecting...")
+            @connection.reconnect
+          ensure
+            raise delivery_error if delivery_error
+          end
+        end
+      end
+
       def handle_next_notification
         notification = Rapns::Daemon.delivery_queue.pop
+
+        if notification == STOP
+          @connection.close
+          return
+        end
+
         begin
-          return if notification == STOP
           deliver(notification)
         rescue StandardError => e
           Rapns::Daemon.logger.error(e)
         ensure
-          Rapns::Daemon.delivery_queue.handler_available
+          Rapns::Daemon.delivery_queue.notification_processed
         end
       end
     end

data/lib/rapns/daemon/delivery_handler_pool.rb

@@ -5,7 +5,7 @@ module Rapns
       protected
 
       def new_object_for_pool(i)
-        DeliveryHandler.new
+        DeliveryHandler.new(i)
       end
 
       def object_added_to_pool(object)
@@ -15,10 +15,6 @@ module Rapns
       def object_removed_from_pool(object)
         object.stop
       end
-
-      def drain_started
-        @num_objects.times { Rapns::Daemon.delivery_queue.push(Rapns::Daemon::DeliveryHandler::STOP) }
-      end
     end
   end
 end

data/lib/rapns/daemon/delivery_queue.rb

@@ -1,44 +1,27 @@
 module Rapns
   module Daemon
     class DeliveryQueue
-      def initialize(num_handlers)
-        @num_handlers = num_handlers
+      def initialize
+        @mutex = Mutex.new
+        @num_notifications = 0
         @queue = Queue.new
-        @feeder = nil
-        @handler_mutex = Mutex.new
       end
 
-      def push(obj)
-        @queue.push(obj)
+      def push(notification)
+        @mutex.synchronize { @num_notifications += 1 }
+        @queue.push(notification)
       end
 
       def pop
         @queue.pop
       end
 
-      def handler_available
-        @handler_mutex.synchronize do
-          signal_feeder if handler_available?
-        end
+      def notification_processed
+        @mutex.synchronize { @num_notifications -= 1 }
       end
 
-      def handler_available?
-        @queue.size < @num_handlers
-      end
-
-      def signal_feeder
-        begin
-          @feeder.wakeup if @feeder
-        rescue ThreadError
-          retry
-        end
-      end
-
-      def wait_for_available_handler
-        if !handler_available?
-          @feeder = Thread.current
-          @feeder.stop
-        end
+      def notifications_processed?
+        @mutex.synchronize { @num_notifications == 0 }
       end
     end
   end

data/lib/rapns/daemon/feedback_receiver.rb

@@ -0,0 +1,57 @@
+module Rapns
+  module Daemon
+    class FeedbackReceiver
+      extend InterruptibleSleep
+
+      FEEDBACK_TUPLE_BYTES = 38
+
+      def self.start
+        @thread = Thread.new do
+          loop do
+            break if @stop
+            check_for_feedback
+            interruptible_sleep Rapns::Daemon.configuration.feedback.poll
+          end
+        end
+      end
+
+      def self.stop
+        @stop = true
+        interrupt_sleep
+        @thread.join if @thread
+      end
+
+      def self.check_for_feedback
+        connection = nil
+        begin
+          host = Rapns::Daemon.configuration.feedback.host
+          port = Rapns::Daemon.configuration.feedback.port
+          connection = Connection.new("FeedbackReceiver", host, port)
+          connection.connect
+
+          while tuple = connection.read(FEEDBACK_TUPLE_BYTES)
+            timestamp, device_token = parse_tuple(tuple)
+            create_feedback(timestamp, device_token)
+          end
+        rescue StandardError => e
+          Rapns::Daemon.logger.error(e)
+        ensure
+          connection.close if connection
+        end
+      end
+
+      protected
+
+      def self.parse_tuple(tuple)
+        failed_at, _, device_token = tuple.unpack("N1n1H*")
+        [Time.at(failed_at), device_token]
+      end
+
+      def self.create_feedback(failed_at, device_token)
+        formatted_failed_at = failed_at.strftime("%Y-%m-%d %H:%M:%S UTC")
+        Rapns::Daemon.logger.info("[FeedbackReceiver] Delivery failed at #{formatted_failed_at} for #{device_token}")
+        Rapns::Feedback.create!(:failed_at => failed_at, :device_token => device_token)
+      end
+    end
+  end
+end

data/lib/rapns/daemon/feeder.rb

@@ -7,36 +7,38 @@ ADAPTER_ERRORS = [PGError, Mysql::Error, Mysql2::Error]
 module Rapns
   module Daemon
     class Feeder
+      extend InterruptibleSleep
+
       def self.start(foreground)
         connect unless foreground
 
         loop do
           break if @stop
           enqueue_notifications
+          interruptible_sleep Rapns::Daemon.configuration.push.poll
         end
       end
 
       def self.stop
         @stop = true
+        interrupt_sleep
       end
 
       protected
 
       def self.enqueue_notifications
         begin
-          Rapns::Notification.ready_for_delivery.each do |notification|
-            Rapns::Daemon.delivery_queue.push(notification)
+          if Rapns::Daemon.delivery_queue.notifications_processed?
+            Rapns::Notification.ready_for_delivery.each do |notification|
+              Rapns::Daemon.delivery_queue.push(notification)
+            end
           end
-
-          Rapns::Daemon.delivery_queue.wait_for_available_handler
         rescue ActiveRecord::StatementInvalid, *ADAPTER_ERRORS => e
           Rapns::Daemon.logger.error(e)
           reconnect
         rescue StandardError => e
           Rapns::Daemon.logger.error(e)
         end
-
-        sleep Rapns::Daemon.configuration.poll
       end
 
       def self.reconnect
@@ -62,7 +64,7 @@ module Rapns
       end
 
       def self.check_is_connected
-        # Simple asking the adapter for the connection state is not sufficient.
+        # Simply asking the adapter for the connection state is not sufficient.
         Rapns::Notification.count
       end