rapns 0.1.0

data/README.md

@@ -0,0 +1,105 @@
+# rapns [![Build Status](https://secure.travis-ci.org/ileitch/rapns.png)](http://travis-ci.org/ileitch/rapns)
+
+Easy to use library for Apple's Push Notification Service with Rails 3.
+
+## Features
+
+* Works with Rails 3 and Ruby 1.9.
+* 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.
+* [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).
+
+## Getting Started
+
+Add rapns to your Gemfile:
+
+    gem 'rapns'
+  
+Generate the migration, rapns.yml and migrate:
+
+    rails g rapns
+    rake db:migrate
+
+## Generating Certificates
+
+1. Open up Keychain Access and select the `Certificates` category in the sidebar.
+2. Expand the disclosure arrow next to the iOS Push Services certificate you want to export.
+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 Configuration section below.
+7. Convert the certificate to a .pem, where `<environment>` should be `development` or `production`, depending on the certificate you exported.
+
+    `openssl pkcs12 -nodes -clcerts -in cert.p12 -out <environment>.pem`
+      
+8. Move the .pem file into your Rails application under `config/rapns`.
+
+## Configuration
+
+Environment configuration lives in `config/rapns/rapns.yml`. For common setups you probably wont need to change this file.
+
+If you want to use rapns in environments other than development or production, you will need to create an entry for it. Simply duplicate the configuration for development or production, depending on which iOS Push Certificate you wish to use.
+
+### 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.
+* `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.
+
+## Starting the rapns Daemon
+
+    cd /path/to/rails/app
+    bundle exec rapns <Rails environment>
+    
+### Options
+
+* `--foreground` will prevent rapns from forking into a daemon. Activity information will be printed to the screen.
+
+## Sending a Notification
+
+    n = Rapns::Notification.new
+    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!
+
+* `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 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.
+
+### 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).
+
+Not yet implemented!
+
+## Delivery Failures
+
+The APN service 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.
+
+Not implemented yet!
+
+

data/bin/rapns

@@ -0,0 +1,26 @@
+#!/usr/bin/env ruby
+
+require "optparse"
+require "rapns"
+require "rapns/daemon"
+
+foreground = false
+environment = ARGV[0]
+banner = "Usage: rapns <Rails environment> [options]"
+ARGV.options do |opts|
+  opts.banner = banner
+  opts.on("-f", "--foreground", "Run in the foreground.") { foreground = true }
+  opts.on("-v", "--version", "Print this version of rapns.") { puts "rapns #{Rapns::VERSION}"; exit }
+  opts.on("-h", "--help", "You're looking at it.") { puts opts; exit }
+  opts.parse!
+end
+
+if environment.nil?
+  puts banner
+  exit 1
+end
+
+ENV["RAILS_ENV"] = environment
+load "config/environment.rb"
+
+Rapns::Daemon.start(environment, foreground)

data/lib/generators/rapns_generator.rb

@@ -0,0 +1,16 @@
+class RapnsGenerator < Rails::Generators::Base
+  include Rails::Generators::Migration
+  source_root File.expand_path('../templates', __FILE__)
+
+  def self.next_migration_number(path)
+    Time.now.utc.strftime("%Y%m%d%H%M%S")
+  end
+
+  def copy_migration
+     migration_template "create_rapns_notifications.rb", "db/migrate/create_rapns_notifications.rb"
+  end
+
+  def copy_config
+    copy_file "rapns.yml", "config/rapns/rapns.yml"
+  end
+end

data/lib/generators/templates/create_rapns_notifications.rb

@@ -0,0 +1,26 @@
+class CreateRapnsNotifications < ActiveRecord::Migration
+  def self.up
+    create_table :rapns_notifications do |t|
+      t.integer   :badge,                 :null => true
+      t.string    :device_token,          :null => false, :limit => 64
+      t.string    :sound,                 :null => true,  :default => "1.aiff"
+      t.string    :alert,                 :null => true
+      t.text      :attributes_for_device, :null => true
+      t.integer   :expiry,                :null => false, :default => 1.day.to_i
+      t.boolean   :delivered,             :null => false, :default => false
+      t.timestamp :delivered_at,          :null => true
+      t.boolean   :failed,                :null => false, :default => false
+      t.timestamp :failed_at,             :null => true
+      t.integer   :error_code,            :null => true
+      t.string    :error_description,     :null => true
+      t.timestamp :deliver_after,         :null => true
+      t.timestamps
+    end
+
+    add_index :rapns_notifications, [:delivered, :failed, :deliver_after], :name => "index_rapns_notifications_on_delivered_failed_deliver_after"
+  end
+
+  def self.down
+    drop_table :rapns_notifications
+  end
+end

data/lib/generators/templates/rapns.yml

@@ -0,0 +1,17 @@
+development:
+  host: gateway.sandbox.push.apple.com
+  port: 2195
+  certificate: development.pem
+  certificate_password:
+  airbrake_notify: true
+  poll: 2
+  connections: 3
+
+production:
+  host: gateway.push.apple.com
+  port: 2195
+  certificate: production.pem
+  certificate_password:
+  airbrake_notify: true
+  poll: 2
+  connections: 3

data/lib/rapns/binary_notification_validator.rb

@@ -0,0 +1,10 @@
+module Rapns
+  class BinaryNotificationValidator < ActiveModel::Validator
+
+    def validate(record)
+      if record.to_binary(:for_validation => true).size > 256
+        record.errors[:base] << "APN notification cannot be larger than 256 bytes. Try condensing your alert and device attributes."
+      end
+    end
+  end
+end

data/lib/rapns/daemon/certificate.rb

@@ -0,0 +1,27 @@
+module Rapns
+  class CertificateError < StandardError; end
+
+  module Daemon
+    class Certificate
+      attr_accessor :certificate
+
+      def initialize(certificate_path)
+        @certificate_path = certificate_path
+      end
+
+      def load
+        @certificate = read_certificate
+      end
+
+      protected
+
+      def read_certificate
+        if !File.exists?(@certificate_path)
+          raise CertificateError, "#{@certificate_path} does not exist. The certificate location can be configured in config/rapns/rapns.yml."
+        else
+          File.read(@certificate_path)
+        end
+      end
+    end
+  end
+end

data/lib/rapns/daemon/configuration.rb

@@ -0,0 +1,69 @@
+require "yaml"
+
+module Rapns
+  class ConfigurationError < StandardError; end
+
+  module Daemon
+    class Configuration
+      attr_accessor :host, :port, :certificate, :certificate_password, :poll, :airbrake_notify, :connections
+      alias_method  :airbrake_notify?, :airbrake_notify
+
+      def initialize(environment, config_path)
+        @environment = environment
+        @config_path = config_path
+      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)
+      end
+
+      def certificate
+        if Pathname.new(@certificate).absolute?
+          @certificate
+        else
+          File.join(Rails.root, "config", "rapns", @certificate)
+        end
+      end
+
+      protected
+
+      def read_config
+        ensure_config_exists
+        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 == ""
+          if options[:optional]
+            instance_variable_set("@#{key}", options[:default])
+          else
+            raise Rapns::ConfigurationError, "'#{key}' not defined for environment '#{@environment}' in #{@config_path}"
+          end
+        else
+          instance_variable_set("@#{key}", config[key.to_s])
+        end
+      end
+
+      def ensure_config_exists
+        if !File.exists?(@config_path)
+          raise Rapns::ConfigurationError, "#{@config_path} does not exist. Have you run 'rails g rapns'?"
+        end
+      end
+
+      def ensure_environment_configured(config)
+        if !config.key?(@environment)
+          raise Rapns::ConfigurationError, "Configuration for environment '#{@environment}' not defined in #{@config_path}"
+        end
+      end
+    end
+  end
+end

data/lib/rapns/daemon/connection.rb

@@ -0,0 +1,99 @@
+module Rapns
+  module Daemon
+    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)
+        @name = name
+      end
+
+      def connect
+        @ssl_context = setup_ssl_context
+        @tcp_socket, @ssl_socket = connect_socket
+      end
+
+      def close
+        @ssl_socket.close if @ssl_socket
+        @tcp_socket.close if @tcp_socket
+      end
+
+      def write(data)
+        retry_count = 0
+
+        begin
+          @ssl_socket.write(data)
+          @ssl_socket.flush
+
+          check_for_error
+        rescue Errno::EPIPE => e
+          Rapns::Daemon.logger.warn("[#{@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 < 3
+            sleep 1
+            retry
+          else
+            raise ConnectionError, "#{@name} tried #{retry_count} times to reconnect but failed: #{e.inspect}"
+          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")
+
+            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
+
+          begin
+            Rapns::Daemon.logger.warn("[#{@name}] Error received, reconnecting...")
+            close
+            @tcp_socket, @ssl_socket = connect_socket
+          ensure
+            raise delivery_error if delivery_error
+          end
+        end
+      end
+
+      def setup_ssl_context
+        ssl_context = OpenSSL::SSL::SSLContext.new
+        ssl_context.key = OpenSSL::PKey::RSA.new(Rapns::Daemon.certificate.certificate, Rapns::Daemon.configuration.certificate_password)
+        ssl_context.cert = OpenSSL::X509::Certificate.new(Rapns::Daemon.certificate.certificate)
+        ssl_context
+      end
+
+      def connect_socket
+        tcp_socket = TCPSocket.new(Rapns::Daemon.configuration.host, Rapns::Daemon.configuration.port)
+        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}")
+        [tcp_socket, ssl_socket]
+      end
+    end
+  end
+end

data/lib/rapns/daemon/connection_pool.rb

@@ -0,0 +1,31 @@
+module Rapns
+  module Daemon
+    class ConnectionPool < Pool
+
+      def claim_connection
+        connection = nil
+        begin
+          connection = @queue.pop
+          yield connection
+        ensure
+          @queue.push(connection) if connection
+        end
+        connection
+      end
+
+      protected
+
+      def new_object_for_pool(i)
+        Connection.new("Connection #{i}")
+      end
+
+      def object_added_to_pool(object)
+        object.connect
+      end
+
+      def object_removed_from_pool(object)
+        object.close
+      end
+    end
+  end
+end

data/lib/rapns/daemon/delivery_error.rb

@@ -0,0 +1,15 @@
+module Rapns
+  class DeliveryError < StandardError
+    attr_reader :code, :description, :notification_id
+
+    def initialize(code, description, notification_id)
+      @code = code
+      @description = description
+      @notification_id = notification_id
+    end
+
+    def message
+      "Unable to deliver notification #{notification_id}, received APN error #{code} (#{description})"
+    end
+  end
+end

data/lib/rapns/daemon/delivery_handler.rb

@@ -0,0 +1,53 @@
+module Rapns
+  module Daemon
+    class DeliveryHandler
+      STOP = 0x666
+
+      def start
+        @thread = Thread.new do 
+          loop do
+            break if @stop
+            handle_next_notification
+          end
+        end
+      end
+
+      def stop
+        @stop = true
+      end
+
+      protected
+
+      def handle_next_notification
+        begin
+          notification = Rapns::Daemon.delivery_queue.pop
+          return if notification == STOP
+
+          Rapns::Daemon.connection_pool.claim_connection do |connection|
+            begin
+              connection.write(notification.to_binary)
+
+              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
+              Rapns::Daemon.logger.error(error)
+
+              notification.delivered = false
+              notification.delivered_at = nil
+              notification.failed = true
+              notification.failed_at = Time.now
+              notification.error_code = error.code
+              notification.error_description = error.description
+              notification.save!(:validate => false)
+            end
+          end
+        rescue StandardError => e
+          Rapns::Daemon.logger.error(e)
+        end
+      end
+    end
+  end
+end

data/lib/rapns/daemon/delivery_handler_pool.rb

@@ -0,0 +1,24 @@
+module Rapns
+  module Daemon
+    class DeliveryHandlerPool < Pool
+
+      protected
+
+      def new_object_for_pool(i)
+        DeliveryHandler.new
+      end
+
+      def object_added_to_pool(object)
+        object.start
+      end
+
+      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/feeder.rb

@@ -0,0 +1,31 @@
+module Rapns
+  module Daemon
+    class Feeder
+      def self.start
+        @thread = Thread.new do
+          loop do
+            break if @stop
+            enqueue_notifications
+          end
+        end
+        @thread.join
+      end
+
+      def self.enqueue_notifications
+        begin
+          Rapns::Notification.ready_for_delivery.each do |notification|
+            Rapns::Daemon.delivery_queue.push(notification)
+          end
+        rescue StandardError => e
+          Rapns::Daemon.logger.error(e)
+        end
+
+        sleep Rapns::Daemon.configuration.poll
+      end
+
+      def self.stop
+        @stop = true
+      end
+    end
+  end
+end

data/lib/rapns/daemon/logger.rb

@@ -0,0 +1,49 @@
+module Rapns
+  module Daemon
+    class Logger
+      def initialize(options)
+        @options = options
+        log_path = File.join(Rails.root, "log", "rapns.log")
+        @logger = ActiveSupport::BufferedLogger.new(log_path, Rails.logger.level)
+        @logger.auto_flushing = Rails.logger.auto_flushing
+      end
+
+      def info(msg)
+        log(:info, msg)
+      end
+
+      def error(msg)
+        airbrake_notify(msg) if msg.is_a?(Exception)
+        log(:error, msg, "ERROR")
+      end
+
+      def warn(msg)
+        log(:warn, msg, "WARNING")
+      end
+
+      private
+
+      def log(where, msg, prefix = nil)
+        if msg.is_a?(Exception)
+          msg = "#{msg.class.name}, #{msg.message}"
+        end
+
+        formatted_msg = "[#{Time.now.to_s(:db)}] "
+        formatted_msg << "[#{prefix}] " if prefix
+        formatted_msg << msg
+        puts formatted_msg if @options[:foreground]
+        @logger.send(where, formatted_msg)
+      end
+
+      def airbrake_notify(e)
+        return unless @options[:airbrake_notify] == true
+
+        if defined?(Airbrake)
+          Airbrake.notify(e)
+        elsif defined?(HoptoadNotifier)
+          HoptoadNotifier.notify(e)
+        end
+      end
+    end
+  end
+end

data/lib/rapns/daemon/pool.rb

@@ -0,0 +1,41 @@
+module Rapns
+  module Daemon
+    class Pool
+      def initialize(num_objects)
+        @num_objects = num_objects
+        @queue = Queue.new
+      end
+
+      def populate
+        @num_objects.times do |i|
+          object = new_object_for_pool(i)
+          @queue.push(object)
+          object_added_to_pool(object)
+        end
+      end
+
+      def drain
+        drain_started
+
+        while !@queue.empty?
+          object = @queue.pop
+          object_removed_from_pool(object)
+        end
+      end
+
+      protected
+
+      def new_object_for_pool(i)
+      end
+
+      def object_added_to_pool(object)
+      end
+
+      def object_removed_from_pool(object)
+      end
+
+      def drain_started
+      end
+    end
+  end
+end