riproad_rapns 1.1.3

data/History.md

@@ -0,0 +1,5 @@
+
+1.0.7 / 2012-04-22 
+==================
+
+  * Reconnect if the connnection has been idle for more than 30 minutes. TCP Keepalive alone is not enough to ensure the connection is still connected.

data/README.md

@@ -0,0 +1,145 @@
+# 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 & 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
+
+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:
+
+* `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.
+* `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
+
+    cd /path/to/rails/app
+    bundle exec rapns <Rails environment>
+    
+### Options
+
+* `--foreground` will prevent rapns from forking into a daemon.
+
+## Logging
+
+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.
+
+## 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 (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.
+
+### 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).
+
+## 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
+
+After updating you should run `rails g rapns` to check for any new migrations or configuration changes.
+
+## Wiki
+
+* [Why open multiple connections to the APNs?](https://github.com/ileitch/rapns/wiki/Why-open-multiple-connections-to-the-APNs%3F)
+
+## Contributing to rapns
+
+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`.
+
+### 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/bin/rapns

@@ -0,0 +1,28 @@
+#!/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'
+
+require 'rapns/patches'
+
+Rapns::Daemon.start(environment, foreground)

data/lib/generators/rapns_generator.rb

@@ -0,0 +1,33 @@
+class RapnsGenerator < Rails::Generators::Base
+  include Rails::Generators::Migration
+  source_root File.expand_path('../templates', __FILE__)
+
+  def self.next_migration_number(path)
+    @time ||= Time.now.utc
+    @calls ||= -1
+    @calls += 1
+    (@time + @calls.seconds).strftime("%Y%m%d%H%M%S")
+  end
+
+  def copy_migration
+    add_rapns_migration('create_rapns_notifications')
+    add_rapns_migration('create_rapns_feedback')
+    add_rapns_migration('add_alert_is_json_to_rapns_notifications')
+    add_rapns_migration('add_retry_count_to_rapns_notifications')
+    add_rapns_migration('add_web_service_notification_request_id_to_rapns_notifications')
+  end
+
+  def copy_config
+    copy_file 'rapns.yml', 'config/rapns/rapns.yml'
+  end
+
+  protected
+
+  def add_rapns_migration(template)
+    migration_dir = File.expand_path('db/migrate')
+
+    if !self.class.migration_exists?(migration_dir, template)
+      migration_template "#{template}.rb", "db/migrate/#{template}.rb"
+    end
+  end
+end

data/lib/generators/templates/add_alert_is_json_to_rapns_notifications.rb

@@ -0,0 +1,9 @@
+class AddAlertIsJsonToRapnsNotifications < ActiveRecord::Migration
+  def self.up
+    add_column :rapns_notifications, :alert_is_json, :boolean, :null => true, :default => false
+  end
+
+  def self.down
+    remove_column :rapns_notifications, :alert_is_json
+  end
+end

data/lib/generators/templates/add_retry_count_to_rapns_notifications.rb

@@ -0,0 +1,9 @@
+class AddRetryCountToRapnsNotifications < ActiveRecord::Migration
+  def self.up
+    add_column :rapns_notifications, :retry_count, :integer, :null => true
+  end
+
+  def self.down
+    remove_column :rapns_notifications, :retry_count
+  end
+end

data/lib/generators/templates/add_web_service_notification_request_id_to_rapns_notifications.rb

@@ -0,0 +1,9 @@
+class AddWebServiceNotificationRequestIdToRapnsNotifications < ActiveRecord::Migration
+  def self.up
+    add_column :rapns_notifications, :web_service_notification_request_id, :integer, :null => true
+  end
+
+  def self.down
+    remove_column :rapns_notifications, :web_service_notification_request_id
+  end
+end

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/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,31 @@
+development:
+  certificate: development.pem
+  certificate_password:
+
+  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:
+  certificate: production.pem
+  certificate_password:
+  airbrake_notify: true
+  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.rb

@@ -0,0 +1,7 @@
+require 'active_record'
+
+require 'rapns/version'
+require 'rapns/binary_notification_validator'
+require 'rapns/device_token_format_validator'
+require 'rapns/notification'
+require 'rapns/feedback'

data/lib/rapns/binary_notification_validator.rb

@@ -0,0 +1,10 @@
+module Rapns
+  class BinaryNotificationValidator < ActiveModel::Validator
+
+    def validate(record)
+      if record.payload_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.rb

@@ -0,0 +1,111 @@
+require 'thread'
+require 'socket'
+require 'pathname'
+
+require 'rapns/daemon/interruptible_sleep'
+require 'rapns/daemon/configuration'
+require 'rapns/daemon/certificate'
+require 'rapns/daemon/delivery_error'
+require 'rapns/daemon/disconnection_error'
+require 'rapns/daemon/pool'
+require 'rapns/daemon/connection'
+require 'rapns/daemon/database_reconnectable'
+require 'rapns/daemon/delivery_queue'
+require 'rapns/daemon/delivery_handler'
+require 'rapns/daemon/delivery_handler_pool'
+require 'rapns/daemon/feedback_receiver'
+require 'rapns/daemon/feeder'
+require 'rapns/daemon/logger'
+
+module Rapns
+  module Daemon
+    class << self
+      attr_accessor :logger, :configuration, :certificate,
+        :delivery_queue, :delivery_handler_pool, :foreground
+      alias_method  :foreground?, :foreground
+    end
+
+    def self.start(environment, foreground)
+      @foreground = foreground
+      setup_signal_hooks
+
+      self.configuration = Configuration.new(environment, File.join(Rails.root, 'config', 'rapns', 'rapns.yml'))
+      configuration.load
+
+      self.logger = Logger.new(:foreground => foreground, :airbrake_notify => configuration.airbrake_notify)
+
+      self.certificate = Certificate.new(configuration.certificate)
+      certificate.load
+
+      self.delivery_queue = DeliveryQueue.new
+
+      daemonize unless foreground?
+
+      write_pid_file
+
+      self.delivery_handler_pool = DeliveryHandlerPool.new(configuration.push.connections)
+      delivery_handler_pool.populate
+
+      logger.info('Ready')
+
+      FeedbackReceiver.start
+      Feeder.start(foreground?)
+    end
+
+    protected
+
+    def self.setup_signal_hooks
+      @shutting_down = false
+
+      ['SIGINT', 'SIGTERM'].each do |signal|
+        Signal.trap(signal) do
+          handle_shutdown_signal
+        end
+      end
+    end
+
+    def self.handle_shutdown_signal
+      exit 1 if @shutting_down
+      @shutting_down = true
+      shutdown
+    end
+
+    def self.shutdown
+      puts "\nShutting down..."
+      Rapns::Daemon::FeedbackReceiver.stop
+      Rapns::Daemon::Feeder.stop
+      Rapns::Daemon.delivery_handler_pool.drain if Rapns::Daemon.delivery_handler_pool
+      delete_pid_file
+    end
+
+    def self.daemonize
+      exit if pid = fork
+      Process.setsid
+      exit if pid = fork
+
+      Dir.chdir '/'
+      File.umask 0000
+
+      STDIN.reopen '/dev/null'
+      STDOUT.reopen '/dev/null', 'a'
+      STDERR.reopen STDOUT
+    end
+
+    def self.write_pid_file
+      if !configuration.pid_file.blank?
+        begin
+          File.open(configuration.pid_file, 'w') do |f|
+            f.puts $$
+          end
+        rescue SystemCallError => e
+          logger.error("Failed to write PID to '#{configuration.pid_file}': #{e.inspect}")
+        end
+      end
+    end
+
+    def self.delete_pid_file
+      pid_file = configuration.pid_file
+      File.delete(pid_file) if !pid_file.blank? && File.exists?(pid_file)
+    end
+  end
+end