gwong-apn_on_rails 0.4.2

data/.rspec

@@ -0,0 +1,2 @@
+-f d
+--colour

data/.specification

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification 
+name: apn_on_rails
+version: !ruby/object:Gem::Version 
+  version: 0.3.1
+platform: ruby
+authors: 
+- markbates
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-01-26 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: configatron
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: "apn_on_rails was developed by: markbates"
+email: mark@markbates.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- LICENSE
+files: 
+- lib/apn_on_rails/apn_on_rails.rb
+- lib/apn_on_rails/app/models/apn/base.rb
+- lib/apn_on_rails/app/models/apn/device.rb
+- lib/apn_on_rails/app/models/apn/notification.rb
+- lib/apn_on_rails/libs/connection.rb
+- lib/apn_on_rails/libs/feedback.rb
+- lib/apn_on_rails/tasks/apn.rake
+- lib/apn_on_rails/tasks/db.rake
+- lib/apn_on_rails.rb
+- lib/apn_on_rails_tasks.rb
+- README
+- LICENSE
+- generators/apn_migrations_generator.rb
+- generators/templates/apn_migrations/001_create_apn_devices.rb
+- generators/templates/apn_migrations/002_create_apn_notifications.rb
+- generators/templates/apn_migrations/003_alter_apn_devices.rb
+has_rdoc: true
+homepage: http://www.metabates.com
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: magrathea
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: apn_on_rails
+test_files: []
+

data/Gemfile

@@ -0,0 +1,19 @@
+source :gemcutter
+gem 'configatron'
+
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem 'autotest'
+  gem 'sqlite3-ruby'
+  gem "rspec", ">= 2.0.0"
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.5.0"
+  gem "rcov", ">= 0"
+  gem "actionpack", '~> 2.3.0'
+  gem 'activerecord', "~> 2.3.0", :require => 'active_record'
+end

data/Gemfile.lock

@@ -0,0 +1,47 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    ZenTest (4.4.2)
+    actionpack (2.3.10)
+      activesupport (= 2.3.10)
+      rack (~> 1.1.0)
+    activerecord (2.3.10)
+      activesupport (= 2.3.10)
+    activesupport (2.3.10)
+    autotest (4.4.6)
+      ZenTest (>= 4.4.1)
+    configatron (2.6.4)
+      yamler (>= 0.1.0)
+    diff-lcs (1.1.2)
+    git (1.2.5)
+    jeweler (1.5.2)
+      bundler (~> 1.0.0)
+      git (>= 1.2.5)
+      rake
+    rack (1.1.0)
+    rake (0.8.7)
+    rcov (0.9.9)
+    rspec (2.4.0)
+      rspec-core (~> 2.4.0)
+      rspec-expectations (~> 2.4.0)
+      rspec-mocks (~> 2.4.0)
+    rspec-core (2.4.0)
+    rspec-expectations (2.4.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.4.0)
+    sqlite3-ruby (1.3.2)
+    yamler (0.1.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  actionpack (~> 2.3.0)
+  activerecord (~> 2.3.0)
+  autotest
+  bundler (~> 1.0.0)
+  configatron
+  jeweler (~> 1.5.0)
+  rcov
+  rspec (>= 2.0.0)
+  sqlite3-ruby

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2009 markbates
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README

@@ -0,0 +1,179 @@
+=APN on Rails (Apple Push Notifications on Rails)
+
+APN on Rails is a Ruby on Rails gem that allows you to easily add Apple Push Notification (iPhone)
+support to your Rails application.  
+
+It supports: 
+* Multiple iPhone apps managed from the same Rails application as well as a legacy default "app" with certs stored in config
+* Individual notifications and group notifications
+* Alerts, badges, sounds, and custom properties in notifications
+* Pull notifications
+
+== Feature Descriptions
+
+Multiple iPhone Apps: In previous versions of this gem a single Rails application was set up to 
+manage push notifications for a single iPhone app.  In many cases it is useful to have a single Rails
+app manage push notifications for multiple iPhone apps.  With the addition of an APN::App model, this 
+is now possible.  The certificates are now stored on instances of APN::App and devices are intended to be associated
+with a particular app.  For compatibility with existing implementations it is still possible to create devices that 
+are not associated with an APN::App and to send individual notifications to them using the certs stored in the 
+config directory.  
+
+Individual and Group Notifications: Previous versions of this gem treated each notification individually
+and did not provide a built-in way to send a broadcast notification to a group of devices.  Group notifications
+are now built into the gem.  A group notification is associated with a group of devices and shares its 
+contents across the entire group of devices.  (Group notifications are only available for groups of devices associated 
+with an APN::App)
+
+Notification Content Areas: Notifications may contain alerts, badges, sounds, and custom properties.
+
+Pull Notifications: This version of the gem supports an alternative notification method that relies
+on pulls from client devices and does not interact with the Apple Push Notification servers.  This feature
+may be used entirely independently of the push notification features.  Pull notifications may be
+created for an app.  A client app can query for the most recent pull notification available since a 
+given date to retrieve any notifications waiting for it. 
+
+==Version 0.4.1 Notes
+
+* Backwards compatibility.  0.4.0 required a manual upgrade to associate existing and new devices with an APN::App model.  This version allows continued use of devices that are associated with a default "app" that stores its certificates in the config directory.  This ought to allow upgrade to this version without code changes.  
+* Batched finds.  Finds on the APN::Device model that can return large numbers of records have been batched to limit memory impact. 
+* Custom properties migration.  At a pre-0.4.0 version the custom_properties attribute was added to the migration template that created the notifications table.  This introduced a potential problem for gem users who had previously run this migration.  The custom_properties alteration to the apn_notifications table has been moved to its own migration and should work regardless of whether your apn_notifications table already has a custom_properties attribute. 
+* last_registered_at changed to work intuitively.  The last_registered_at attribute of devices was being updated only on creation potentially causing a bug in which a device that opts out of APNs and then opts back in before apn_on_rails received feedback about it might miss a period of APNs that it should receive.  
+
+==Acknowledgements:
+
+From Mark Bates: 
+
+This gem is a re-write of a plugin that was written by Fabien Penso and Sam Soffes.
+Their plugin was a great start, but it just didn't quite reach the level I hoped it would.
+I've re-written, as a gem, added a ton of tests, and I would like to think that I made it
+a little nicer and easier to use.
+
+From Rebecca Nesson (PRX.org): 
+
+This gem extends the original version that Mark Bates adapted.  His gem did the hard
+work of setting up and handling all communication with the Apple push notification servers.
+
+==Converting Your Certificate:
+
+Once you have the certificate from Apple for your application, export your key
+and the apple certificate as p12 files. Here is a quick walkthrough on how to do this:
+
+1. Click the disclosure arrow next to your certificate in Keychain Access and select the certificate and the key. 
+2. Right click and choose `Export 2 items...`. 
+3. Choose the p12 format from the drop down and name it `cert.p12`. 
+
+Now covert the p12 file to a pem file:
+
+  $ openssl pkcs12 -in cert.p12 -out apple_push_notification_production.pem -nodes -clcerts
+
+If you are using a development certificate, then change the name to apple_push_notification_development.pem instead.
+
+Store the contents of the certificate files on the app model for the app you want to send notifications to. 
+
+==Installing:
+
+===Stable (RubyForge):
+
+  $ sudo gem install apn_on_rails
+
+===Edge (GitHub):
+
+  $ sudo gem install PRX-apn_on_rails.git --source=http://gems.github.com
+
+===Rails Gem Management:
+
+If you like to use the built in Rails gem management:
+
+  config.gem 'apn_on_rails'
+
+Or, if you like to live on the edge:
+
+  config.gem 'PRX-apn_on_rails', :lib => 'apn_on_rails', :source => 'http://gems.github.com'
+
+==Setup and Configuration:
+
+Once you have the gem installed via your favorite gem installation, you need to require it so you can
+start to use it:
+
+Add the following require, wherever it makes sense to you:
+
+  require 'apn_on_rails'
+
+You also need to add the following to your Rakefile so you can use the
+Rake tasks that ship with APN on Rails:
+
+  begin
+    require 'apn_on_rails_tasks'
+  rescue MissingSourceFile => e
+    puts e.message
+  end
+
+Now, to create the tables you need for APN on Rails, run the following task:
+
+  $ ruby script/generate apn_migrations
+
+APN on Rails uses the Configatron gem, http://github.com/markbates/configatron/tree/master, 
+to configure itself. (With the change to multi-app support, the certifications are stored in the 
+database rather than in the config directory, however, it is still possible to use the default "app" and the certificates
+stored in the config directory.  For this setup, the following configurations apply.) 
+APN on Rails has the following default configurations that you change as you see fit:
+
+  # development (delivery):
+  configatron.apn.passphrase # => ''
+  configatron.apn.port # => 2195
+  configatron.apn.host # => 'gateway.sandbox.push.apple.com'
+  configatron.apn.cert #=> File.join(RAILS_ROOT, 'config', 'apple_push_notification_development.pem')
+  
+  # production (delivery):
+  configatron.apn.host # => 'gateway.push.apple.com'
+  configatron.apn.cert #=> File.join(RAILS_ROOT, 'config', 'apple_push_notification_production.pem')
+  
+  # development (feedback):
+  configatron.apn.feedback.passphrase # => ''
+  configatron.apn.feedback.port # => 2196
+  configatron.apn.feedback.host # => 'feedback.sandbox.push.apple.com'
+  configatron.apn.feedback.cert #=> File.join(RAILS_ROOT, 'config', 'apple_push_notification_development.pem')
+  
+  # production (feedback):
+  configatron.apn.feedback.host # => 'feedback.push.apple.com'
+  configatron.apn.feedback.cert #=> File.join(RAILS_ROOT, 'config', 'apple_push_notification_production.pem')
+
+That's it, now you're ready to start creating notifications.
+
+===Upgrade Notes:
+
+If you are upgrading to a new version of APN on Rails you should always run:
+
+  $ ruby script/generate apn_migrations
+
+That way you ensure you have the latest version of the database tables needed.
+
+==Example (assuming you have created an app and stored your keys on it):
+
+  $ ./script/console
+  >> app = APN::App.create(:name => "My App", :apn_dev_cert => "PASTE YOUR DEV CERT HERE", :apn_prod_cert => "PASTE YOUR PROD CERT HERE")
+  >> device = APN::Device.create(:token => "XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX",:app_id => app.id)
+  >> notification = APN::Notification.new
+  >> notification.device = device
+  >> notification.badge = 5
+  >> notification.sound = true
+  >> notification.alert = "foobar"
+  >> notification.custom_properties = {:link => "http://www.prx.org"}
+  >> notification.save
+
+You can use the following Rake task to deliver your individual notifications:
+
+  $ rake apn:notifications:deliver
+
+And the following task to deliver your group notifications: 
+
+  $ rake apn:group_notifications:deliver
+
+The Rake task will find any unsent notifications in the database. If there aren't any notifications
+it will simply do nothing. If there are notifications waiting to be delivered it will open a single connection
+to Apple and push all the notifications through that one connection. Apple does not like people opening/closing
+connections constantly, so it's pretty important that you are careful about batching up your notifications so
+Apple doesn't shut you down.
+
+Released under the MIT license.

data/README.textile

@@ -0,0 +1,209 @@
+h1. APN on Rails (Apple Push Notifications on Rails)
+
+APN on Rails is a Ruby on Rails gem that allows you to easily add Apple Push Notification (iPhone)
+support to your Rails application.  
+
+It supports: 
+* Multiple iPhone apps managed from the same Rails application as well as a legacy default "app" with certs stored in config
+* Individual notifications and group notifications
+* Alerts, badges, sounds, and custom properties in notifications
+* Pull notifications
+
+h2. Feature Descriptions
+
+Multiple iPhone Apps: In previous versions of this gem a single Rails application was set up to 
+manage push notifications for a single iPhone app.  In many cases it is useful to have a single Rails
+app manage push notifications for multiple iPhone apps.  With the addition of an APN::App model, this 
+is now possible.  The certificates are now stored on instances of APN::App and all devices are intended to be associated
+with a particular app.  For compatibility with existing implementations it is still possible to create devices that 
+are not associated with an APN::App and to send individual notifications to them using the certs stored in the 
+config directory.
+
+Individual and Group Notifications: Previous versions of this gem treated each notification individually
+and did not provide a built-in way to send a broadcast notification to a group of devices.  Group notifications
+are now built into the gem.  A group notification is associated with a group of devices and shares its 
+contents across the entire group of devices. (Group notifications are only available for groups of devices associated 
+with an APN::App) 
+
+Notification Content Areas: Notifications may contain alerts, badges, sounds, and custom properties.
+
+Pull Notifications: This version of the gem supports an alternative notification method that relies
+on pulls from client devices and does not interact with the Apple Push Notification servers.  This feature
+may be used entirely independently of the push notification features.  Pull notifications may be
+created for an app.  A client app can query for the most recent pull notification available since a 
+given date to retrieve any notifications waiting for it.  
+
+h2. Version 0.4.1 Notes
+
+* Backwards compatibility.  0.4.0 required a manual upgrade to associate existing and new devices with an APN::App model.  This version allows continued use of devices that are associated with a default "app" that stores its certificates in the config directory.  This ought to allow upgrade to this version without code changes.  
+* Batched finds.  Finds on the APN::Device model that can return large numbers of records have been batched to limit memory impact. 
+* Custom properties migration.  At a pre-0.4.0 version the custom_properties attribute was added to the migration template that created the notifications table.  This introduced a potential problem for gem users who had previously run this migration.  The custom_properties alteration to the apn_notifications table has been moved to its own migration and should work regardless of whether your apn_notifications table already has a custom_properties attribute. 
+* last_registered_at changed to work intuitively.  The last_registered_at attribute of devices was being updated only on creation potentially causing a bug in which a device that opts out of APNs and then opts back in before apn_on_rails received feedback about it might miss a period of APNs that it should receive.
+
+h2. Acknowledgements:
+
+From Mark Bates: 
+
+This gem is a re-write of a plugin that was written by Fabien Penso and Sam Soffes.
+Their plugin was a great start, but it just didn't quite reach the level I hoped it would.
+I've re-written, as a gem, added a ton of tests, and I would like to think that I made it
+a little nicer and easier to use.
+
+From Rebecca Nesson (PRX.org): 
+
+This gem extends the original version that Mark Bates adapted.  His gem did the hard
+work of setting up and handling all communication with the Apple push notification servers.
+
+h2. Converting Your Certificate:
+
+Once you have the certificate from Apple for your application, export your key
+and the apple certificate as p12 files. Here is a quick walkthrough on how to do this:
+
+1. Click the disclosure arrow next to your certificate in Keychain Access and select the certificate and the key. 
+2. Right click and choose `Export 2 items...`. 
+3. Choose the p12 format from the drop down and name it `cert.p12`. 
+
+Now covert the p12 file to a pem file:
+
+<pre><code>
+  $ openssl pkcs12 -in cert.p12 -out apple_push_notification_production.pem -nodes -clcerts
+</pre></code>
+
+If you are using a development certificate, then change the name to apple_push_notification_development.pem instead.
+
+Store the contents of the certificate files on the app model for the app you want to send notifications to. 
+
+h2. Installing:
+
+h3. Stable (RubyForge):
+
+<pre><code>
+  $ sudo gem install apn_on_rails
+</pre></code>
+
+h3. Edge (GitHub):
+
+<pre><code>
+  $ sudo gem install PRX-apn_on_rails.git --source=http://gems.github.com
+</pre></code>
+
+h3. Rails Gem Management:
+
+If you like to use the built in Rails gem management:
+
+<pre><code>
+  config.gem 'apn_on_rails'
+</pre></code>
+
+Or, if you like to live on the edge:
+
+<pre><code>
+  config.gem 'PRX-apn_on_rails', :lib => 'apn_on_rails', :source => 'http://gems.github.com'
+</pre></code>
+
+h2. Setup and Configuration:
+
+Once you have the gem installed via your favorite gem installation, you need to require it so you can
+start to use it:
+
+Add the following require, wherever it makes sense to you:
+
+<pre><code>
+  require 'apn_on_rails'
+</pre></code>
+
+You also need to add the following to your Rakefile so you can use the
+Rake tasks that ship with APN on Rails:
+
+<pre><code>
+  begin
+    require 'apn_on_rails_tasks'
+  rescue MissingSourceFile => e
+    puts e.message
+  end
+</pre></code>
+
+Now, to create the tables you need for APN on Rails, run the following task:
+
+<pre><code>
+  $ ruby script/generate apn_migrations
+</pre></code>
+
+APN on Rails uses the Configatron gem, http://github.com/markbates/configatron/tree/master, 
+to configure itself. (With the change to multi-app support, the certifications are stored in the 
+database rather than in the config directory, however, it is still possible to use the default "app" and the certificates
+stored in the config directory.  For this setup, the following configurations apply.)
+APN on Rails has the following default configurations that you change as you
+see fit:
+
+<pre><code>
+  # development (delivery):
+  configatron.apn.passphrase # => ''
+  configatron.apn.port # => 2195
+  configatron.apn.host # => 'gateway.sandbox.push.apple.com'
+  configatron.apn.cert #=> File.join(RAILS_ROOT, 'config', 'apple_push_notification_development.pem')
+  
+  # production (delivery):
+  configatron.apn.host # => 'gateway.push.apple.com'
+  configatron.apn.cert #=> File.join(RAILS_ROOT, 'config', 'apple_push_notification_production.pem')
+  
+  # development (feedback):
+  configatron.apn.feedback.passphrase # => ''
+  configatron.apn.feedback.port # => 2196
+  configatron.apn.feedback.host # => 'feedback.sandbox.push.apple.com'
+  configatron.apn.feedback.cert #=> File.join(RAILS_ROOT, 'config', 'apple_push_notification_development.pem')
+  
+  # production (feedback):
+  configatron.apn.feedback.host # => 'feedback.push.apple.com'
+  configatron.apn.feedback.cert #=> File.join(RAILS_ROOT, 'config', 'apple_push_notification_production.pem')
+</pre></code>
+
+That's it, now you're ready to start creating notifications.
+
+h3. Upgrade Notes:
+
+If you are upgrading to a new version of APN on Rails you should always run:
+
+<pre><code>
+  $ ruby script/generate apn_migrations
+</pre></code>
+
+That way you ensure you have the latest version of the database tables needed.
+(There is an unaddressed problem in which migration 002 was modified in the repo to add the column custom_properties.
+If you installed the gem prior to that change and try to upgrade following this path you will have to add the 
+custom_properties column to the apn_notifications table by hand.)
+
+h2. Example (assuming you have created an app and stored your keys on it):
+
+<pre><code>
+  $ ./script/console
+  >> app = APN::App.create(:name => "My App", :apn_dev_cert => "PASTE YOUR DEV CERT HERE", :apn_prod_cert => "PASTE YOUR PROD CERT HERE")
+  >> device = APN::Device.create(:token => "XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX",:app_id => app.id)
+  >> notification = APN::Notification.new
+  >> notification.device = device
+  >> notification.badge = 5
+  >> notification.sound = true
+  >> notification.alert = "foobar"
+  >> notification.custom_properties = {:link => "http://www.prx.org"}
+  >> notification.save
+</pre></code>
+
+You can use the following Rake task to deliver your individual notifications:
+
+<pre><code>
+  $ rake apn:notifications:deliver
+</pre></code>
+
+And the following task to deliver your group notifications: 
+
+<pre><code>
+  $ rake apn:group_notifications:deliver
+</pre></code>
+
+The Rake task will find any unsent notifications in the database. If there aren't any notifications
+it will simply do nothing. If there are notifications waiting to be delivered it will open a single connection
+to Apple and push all the notifications through that one connection. Apple does not like people opening/closing
+connections constantly, so it's pretty important that you are careful about batching up your notifications so
+Apple doesn't shut you down.
+
+Released under the MIT license.