markbates-apn_on_rails 0.0.1.20090723180641 → 0.1.1.20090724152309

data/README

@@ -1,16 +1,17 @@
-APN on Rails
-(Apple Push Notifications on Rails)
-=====================
+=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.
+
+==Acknowledgements:
 
-Acknowledgements
-----------------
 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.
 
-Converting Your Certificate
----------------------------
+==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:
 
@@ -26,28 +27,38 @@ Put 'apple_push_notification_production.pem' in config/
 
 If you are using a development certificate, then change the name to apple_push_notification_development.pem instead.
 
-Installing
-----------
+==Installing:
+
+===Stable (RubyForge):
 
-From RubyForge:
   $ sudo gem install apn_on_rails
 
-Or, if you like to live on the edge:
+===Edge (GitHub):
+
   $ sudo gem install markbates-apn_on_rails --source=http://gems.github.com
-  
-Then you just add the following require, wherever it makes sense to you:
-  require 'apn_on_rails'
+
+===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 'markbates-apn_on_rails', :lib => 'apn_on_rails', :source => 'http://gems.github.com'
-  
-Setup
------
-Once you have the gem installed you need to add the following to your Rakefile so you can use the
+
+==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
@@ -55,22 +66,38 @@ Rake tasks that ship with APN on Rails:
   end
 
 Now, to create the tables you need for APN on Rails, run the following task:
+
   $ rake apn:db:migrate
 
+APN on Rails uses the Configatron gem, http://github.com/markbates/configatron/tree/master, 
+to configure itself. APN on Rails has the following default configurations that you change as you
+see fit:
+
+  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:
+  configatron.apn.host # => 'gateway.push.apple.com'
+  configatron.apn.cert #=> File.join(RAILS_ROOT, 'config', 'apple_push_notification_production.pem')
+
 That's it, now you're ready to start creating notifications.
 
-Example
--------
+==Example:
+
+  $ ./script/console
+  >> device = APN::Device.create(:token => "XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX")
+  >> notification = APN::Notification.new
+  >> notification.device = device
+  >> notification.badge = 5
+  >> notification.sound = true
+  >> notification.alert = "foobar"
+  >> notification.save
+  >> APN::Notification.send_notifications
 
-*Note: the spaces in `device_token` are optional.*
+You can also run the following Rake task to send your notifications:
 
-    $ ./script/console
-    >> a = ApplePushNotification.new
-    >> a.device_token = "XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX"
-    >> a.badge = 5
-    >> a.sound = true
-    >> a.alert = "foobar"
-    >> a.send_notification
-    => nil
+  $ rake apn:notifications:deliver
 
-Copyright (c) 2009 Fabien Penso. Released under the MIT license. Modified by [Sam Soffes](http://samsoff.es).
+Released under the MIT license.

data/lib/apn_on_rails/apn_on_rails.rb

@@ -22,13 +22,14 @@ if rails_env == 'production'
   configatron.apn.set_default(:cert, File.join(rails_root, 'config', 'apple_push_notification_production.pem'))
 end
 
-module APN
+module APN # :nodoc:
   
-  module Errors
+  module Errors # :nodoc:
     
+    # Raised when a notification message to Apple is longer than 256 bytes.
     class ExceededMessageSizeError < StandardError
       
-      def initialize(message)
+      def initialize(message) # :nodoc:
         super("The maximum size allowed for a notification payload is 256 bytes: '#{message}'")
       end
       

data/lib/apn_on_rails/app/models/apn/device.rb

@@ -1,3 +1,8 @@
+# Represents an iPhone (or other APN enabled device).
+# An APN::Device can have many APN::Notification.
+# 
+# Example:
+#   Device.create(:token => '5gxadhy6 6zmtxfl6 5zpbcxmw ez3w7ksf qscpr55t trknkzap 7yyt45sc g6jrw7qz')
 class APN::Device < ActiveRecord::Base
   set_table_name 'apn_devices'
   
@@ -6,6 +11,8 @@ class APN::Device < ActiveRecord::Base
   validates_uniqueness_of :token
   validates_format_of :token, :with => /^[a-z0-9]{8}\s[a-z0-9]{8}\s[a-z0-9]{8}\s[a-z0-9]{8}\s[a-z0-9]{8}\s[a-z0-9]{8}\s[a-z0-9]{8}\s[a-z0-9]{8}$/
   
+  # Stores the token (Apple's device ID) of the iPhone (device).
+  # 
   # If the token comes in like this:
   #  '<5gxadhy6 6zmtxfl6 5zpbcxmw ez3w7ksf qscpr55t trknkzap 7yyt45sc g6jrw7qz>'
   # Then the '<' and '>' will be stripped off.

data/lib/apn_on_rails/app/models/apn/notification.rb

@@ -1,9 +1,31 @@
+# Represents the message you wish to send. 
+# An APN::Notification belongs to an APN::Device.
+# 
+# Example:
+#   apn = APN::Notification.new
+#   apn.badge = 5
+#   apn.sound = 'my_sound.aiff'
+#   apn.alert = 'Hello!'
+#   apn.device = APN::Device.find(1)
+#   apn.save
+# 
+# To deliver call the following method:
+#   APN::Notification.send_notifications
+# 
+# As each APN::Notification is sent the <tt>sent_at</tt> column will be timestamped,
+# so as to not be sent again.
 class APN::Notification < ActiveRecord::Base
   include ::ActionView::Helpers::TextHelper
+  extend ::ActionView::Helpers::TextHelper
+  
   set_table_name 'apn_notifications'
   
   belongs_to :device, :class_name => 'APN::Device'
   
+  # Stores the text alert message you want to send to the device.
+  # 
+  # If the message is over 150 characters long it will get truncated
+  # to 150 characters with a <tt>...</tt>
   def alert=(message)
     if !message.blank? && message.size > 150
       message = truncate(message, :length => 150)
@@ -53,25 +75,37 @@ class APN::Notification < ActiveRecord::Base
   
   class << self
     
-    def send_notifications(notifications)
-      cert = File.read(configatron.apn.cert)
-      ctx = OpenSSL::SSL::SSLContext.new
-      ctx.key = OpenSSL::PKey::RSA.new(cert, configatron.apn.passphrase)
-      ctx.cert = OpenSSL::X509::Certificate.new(cert)
+    # Opens a connection to the Apple APN server and attempts to batch deliver
+    # an Array of notifications.
+    # 
+    # This method expects an Array of APN::Notifications. If no parameter is passed
+    # in then it will use the following:
+    #   APN::Notification.all(:conditions => {:sent_at => nil})
+    # 
+    # As each APN::Notification is sent the <tt>sent_at</tt> column will be timestamped,
+    # so as to not be sent again.
+    def send_notifications(notifications = APN::Notification.all(:conditions => {:sent_at => nil}))
+      unless notifications.nil? || notifications.empty?
+        logger.info "APN: Attempting to deliver #{pluralize(notifications.size, 'notification')}."
+        cert = File.read(configatron.apn.cert)
+        ctx = OpenSSL::SSL::SSLContext.new
+        ctx.key = OpenSSL::PKey::RSA.new(cert, configatron.apn.passphrase)
+        ctx.cert = OpenSSL::X509::Certificate.new(cert)
   
-      s = TCPSocket.new(configatron.apn.host, configatron.apn.port)
-      ssl = OpenSSL::SSL::SSLSocket.new(s, ctx)
-      ssl.sync = true
-      ssl.connect
+        s = TCPSocket.new(configatron.apn.host, configatron.apn.port)
+        ssl = OpenSSL::SSL::SSLSocket.new(s, ctx)
+        ssl.sync = true
+        ssl.connect
   
-      notifications.each do |noty|
-        ssl.write(noty.message_for_sending)
-        noty.sent_at = Time.now
-        noty.save
-      end
+        notifications.each do |noty|
+          ssl.write(noty.message_for_sending)
+          noty.sent_at = Time.now
+          noty.save
+        end
   
-      ssl.close
-      s.close
+        ssl.close
+        s.close
+      end
     end
     
   end # class << self

data/lib/apn_on_rails/db/migrate/20090723132058_create_apn_devices.rb

@@ -1,4 +1,4 @@
-class CreateApnDevices < ActiveRecord::Migration
+class CreateApnDevices < ActiveRecord::Migratio # :nodoc:
   def self.up
     create_table :apn_devices do |t|
       t.text :token, :size => 71, :null => false

data/lib/apn_on_rails/db/migrate/20090723132059_create_apn_notifications.rb

@@ -1,4 +1,4 @@
-class CreateApnNotifications < ActiveRecord::Migration
+class CreateApnNotifications < ActiveRecord::Migration # :nodoc:
   
   def self.up
 

data/lib/apn_on_rails/tasks/apn.rake

@@ -4,12 +4,7 @@ namespace :apn do
     
     desc "Deliver all unsent APN notifications."
     task :deliver => [:environment] do
-      notifications = APN::Notification.all(:conditions => {:sent_at => nil})
-      unless notifications.empty?
-        include ActionView::Helpers::TextHelper
-        RAILS_DEFAULT_LOGGER.info "APN: Attempting to deliver #{pluralize(notifications.size, 'notification')}."
-        APN::Notification.send_notifications(notifications)
-      end
+      APN::Notification.send_notifications
     end
     
   end # notifications

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: markbates-apn_on_rails
 version: !ruby/object:Gem::Version 
-  version: 0.0.1.20090723180641
+  version: 0.1.1.20090724152309
 platform: ruby
 authors: 
 - markbates
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-07-23 00:00:00 -07:00
+date: 2009-07-24 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -35,7 +35,6 @@ files:
 - lib/apn_on_rails/apn_on_rails.rb
 - lib/apn_on_rails/app/models/apn/device.rb
 - lib/apn_on_rails/app/models/apn/notification.rb
-- lib/apn_on_rails/app/models/apple_push_notification.rb
 - lib/apn_on_rails/db/migrate/20090723132058_create_apn_devices.rb
 - lib/apn_on_rails/db/migrate/20090723132059_create_apn_notifications.rb
 - lib/apn_on_rails/tasks/apn.rake

data/lib/apn_on_rails/app/models/apple_push_notification.rb

@@ -1,94 +0,0 @@
-# # 
-# # Fabien Penso <fabien.penso@conovae.com>
-# # April 6th, 2009.
-# # 
-# 
-# require 'socket'
-# require 'openssl'
-# 
-# class ApplePushNotification < ActiveRecord::Base
-# 
-#   HOST = "gateway.sandbox.push.apple.com"
-#   PATH = '/'
-#   PORT = 2195
-#   path = File.join(RAILS_ROOT, 'config', 'apple_push_notification_development.pem')
-#   CERT = File.read(path) if File.exists?(path)
-#   PASSPHRASE = "foobar"
-#   CACERT = File.expand_path(File.dirname(__FILE__) + "certs/ca.gateway.sandbox.push.apple.com.crt")
-#   USERAGENT = 'Mozilla/5.0 (apple_push_notification Ruby on Rails 0.1)'
-# 
-#   # attr_accessor :paylod, :sound, :badge, :alert, :appdata
-#   attr_accessible :device_token
-# 
-#   # validates_uniqueness_of :device_token
-# 
-#   # def send_notification
-#   # 
-#   #   ctx = OpenSSL::SSL::SSLContext.new
-#   #   ctx.key = OpenSSL::PKey::RSA.new(CERT, PASSPHRASE)
-#   #   ctx.cert = OpenSSL::X509::Certificate.new(CERT)
-#   # 
-#   #   s = TCPSocket.new(HOST, PORT)
-#   #   ssl = OpenSSL::SSL::SSLSocket.new(s, ctx)
-#   #   ssl.sync = true
-#   #   ssl.connect
-#   # 
-#   #   ssl.write(self.apn_message_for_sending)
-#   # 
-#   #   ssl.close
-#   #   s.close
-#   # 
-#   # rescue SocketError => error
-#   #   raise "Error while sending notifications: #{error}"
-#   # end
-# 
-#   def self.send_notifications(notifications)
-#     ctx = OpenSSL::SSL::SSLContext.new
-#     ctx.key = OpenSSL::PKey::RSA.new(CERT, PASSPHRASE)
-#     ctx.cert = OpenSSL::X509::Certificate.new(CERT)
-# 
-#     s = TCPSocket.new(HOST, PORT)
-#     ssl = OpenSSL::SSL::SSLSocket.new(s, ctx)
-#     ssl.sync = true
-#     ssl.connect
-# 
-#     for notif in notifications do
-#       ssl.write(notif.apn_message_for_sending)
-#       notif.sent_at = Time.now
-#       notif.save
-#     end
-# 
-#     ssl.close
-#     s.close
-#   rescue SocketError => error
-#     raise "Error while sending notifications: #{error}"
-#   end
-# 
-#   def to_apple_json
-#     logger.debug "Sending #{self.apple_hash.to_json}"
-#     self.apple_hash.to_json
-#   end
-# 
-#   def apn_message_for_sending
-#     json = self.to_apple_json
-#     message = "\0\0 #{self.device_token_hexa}\0#{json.length.chr}#{json}"
-#     raise "The maximum size allowed for a notification payload is 256 bytes." if message.size.to_i > 256
-#     message
-#   end
-# 
-#   def device_token_hexa
-#     [self.device_token.delete(' ')].pack('H*')
-#   end
-# 
-#   def apple_hash
-#     result = {}
-#     result['aps'] = {}
-#     result['aps']['alert'] = alert if alert
-#     result['aps']['badge'] = badge.to_i if badge
-#     result['aps']['sound'] = sound if sound and sound.is_a? String
-#     result['aps']['sound'] = "1.aiff" if sound and sound.is_a?(TrueClass)
-#     result.merge appdata if appdata
-# 
-#     result
-#   end
-# end