apn_sender 0.0.3 → 0.0.4

data/README.rdoc

@@ -9,7 +9,7 @@ The apn_sender gem includes a background daemon which processes background messa
 
 == Usage
 
-=== Queueing Messages From Your Application
+=== 1. Queueing Messages From Your Application
 
 To queue a message for sending through Apple's Push Notification service from your Rails application:
 
@@ -22,7 +22,7 @@ where +token+ is the unique identifier of the iPhone to receive the notification
   # :sound  #=> The sound file to play on receipt, or true to play the default sound installed with your app
   # :custom #=> Hash of application-specific custom data to send along with the notification
 
-=== Getting Messages Actually Sent to Apple
+=== 2. Sending Queued Messages
 
 Put your <code>apn_development.pem</code> and <code>apn_production.pem</code> certificates from Apple in your <code>RAILS_ROOT/config/certs</code> directory.
 
@@ -40,6 +40,43 @@ For production, you're probably better off running a dedicated daemon and settin
 
 Note the --environment must be explicitly set (separately from your <code>RAILS_ENV</code>) to production in order to send messages via the production APN servers.  Any other environment sends messages through Apple's sandbox servers at <code>gateway.sandbox.push.apple.com</code>.
 
+=== 3. Checking Apple's Feedback Service
+  
+Since push notifications are a fire-and-forget sorta deal, where you get no indication if your message was received (or if the specified recipient even exists), Apple needed to come up with some other way to ensure their network isn't clogged with thousands of bogus messages (e.g. from developers sending messages to phones where their application <em>used</em> to be installed, but where the user has since removed it).  Hence, the Feedback Service.
+
+It's actually really simple - you connect to them periodically and they give you a big dump of tokens you shouldn't send to anymore.  The gem wraps this up nicely -- just call:
+
+  # APN::Feedback accepts the same optional :environment and :cert_path options as APN::Sender
+  feedback = APN::Feedback.new()
+
+  tokens = feedback.tokens # => Array of device tokens
+  tokens.each do |token|
+    # ... custom logic here to stop you app from
+    # sending further notifications to this token
+  end
+  
+If you're interested in knowing exactly <em>when</em> Apple determined each token was expired (which can be useful in determining if the application re-registered with your service since it first appeared in the expired queue):
+
+  items = feedback.data # => Array of APN::FeedbackItem elements
+  items.each do |item|
+    item.token
+    item.timestamp
+    # ... custom logic here
+  end
+
+The Feedback Service works as a big queue, and when you connect it pops off all its data and sends it over the wire.  This means that connecting a second time will return an empty array.  For ease of use, a call to either +tokens+ or +data+ will connect once and cache the data, so if you call either one again it'll continue to use its cached version rather than connecting to Apple a second time to retrieve an empty array.
+
+Forcing a reconnect is as easy as calling either method with the single parameter +true+, but be sure you've already used the existing data because you'll never get it back.
+
+
+==== Warning: No really, check Apple's Feedback Service occasionally
+
+If you're sending notifications, you should definitely call one of the <code>receive</code> methods periodically, as Apple's policies require it and they apparently monitors providers for compliance.  I'd definitely recommend throwing together a quick rake task to take care of this for you (the {whenever library}[http://github.com/javan/whenever] provides a nice wrapper around scheduling tasks to run at certain times (for systems with cron enabled)).
+
+
+
+
+
 === Keeping Your Workers Working
 
 There's also an included sample <code>apn_sender.monitrc</code> file in the <code>contrib/</code> folder to help monit handle server restarts and unexpected disasters.

data/VERSION

@@ -1 +1 @@
-0.0.3
+0.0.4

data/apn_sender.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{apn_sender}
-  s.version = "0.0.3"
+  s.version = "0.0.4"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Kali Donovan"]
-  s.date = %q{2010-04-25}
+  s.date = %q{2010-05-02}
   s.description = %q{Resque-based background worker to send Apple Push Notifications over a persistent TCP socket. Includes Resque tweaks to allow persistent sockets between jobs, helper methods for enqueueing APN notifications, and a background daemon to send them.}
   s.email = %q{kali.donovan@gmail.com}
   s.extra_rdoc_files = [
@@ -29,6 +29,8 @@ Gem::Specification.new do |s|
      "generators/templates/script",
      "init.rb",
      "lib/apn.rb",
+     "lib/apn/connection/base.rb",
+     "lib/apn/feedback.rb",
      "lib/apn/notification.rb",
      "lib/apn/notification_job.rb",
      "lib/apn/queue_manager.rb",

data/lib/apn/connection/base.rb

@@ -0,0 +1,97 @@
+require 'socket'
+require 'openssl'
+require 'resque'
+
+module APN
+  module Connection
+    module Base
+      attr_accessor :opts, :logger
+      
+      def initialize(opts = {})
+        @opts = opts
+
+        setup_logger
+        apn_log(:info, "APN::Sender initializing. Establishing connections first...") if @opts[:verbose]
+        setup_paths
+
+        super( APN::QUEUE_NAME ) if self.class.ancestors.include?(Resque::Worker)
+      end
+      
+      # Lazy-connect the socket once we try to access it in some way
+      def socket
+        setup_connection unless @socket
+        return @socket
+      end
+            
+      protected
+      
+      def setup_logger
+        @logger = if defined?(Merb::Logger)
+          Merb.logger
+        elsif defined?(RAILS_DEFAULT_LOGGER)
+          RAILS_DEFAULT_LOGGER
+        end
+      end
+      
+      def apn_log(level, message)
+        return false unless self.logger
+        self.logger.send(level, "#{Time.now}: #{message}")
+      end
+      
+      def apn_production?
+        @opts[:environment] && @opts[:environment] != '' && :production == @opts[:environment].to_sym
+      end
+      
+      # Get a fix on the .pem certificate we'll be using for SSL
+      def setup_paths
+        # Set option defaults
+        @opts[:cert_path] ||= File.join(File.expand_path(RAILS_ROOT), "config", "certs") if defined?(RAILS_ROOT)
+        @opts[:environment] ||= RAILS_ENV if defined?(RAILS_ENV)
+        
+        raise "Missing certificate path. Please specify :cert_path when initializing class." unless @opts[:cert_path]
+        cert_name = apn_production? ? "apn_production.pem" : "apn_development.pem"
+        cert_path = File.join(@opts[:cert_path], cert_name)
+
+        @apn_cert = File.exists?(cert_path) ? File.read(cert_path) : nil
+        raise "Missing apple push notification certificate in #{cert_path}" unless @apn_cert
+      end
+      
+      # Open socket to Apple's servers
+      def setup_connection
+        raise "Missing apple push notification certificate" unless @apn_cert
+        return true if @socket && @socket_tcp
+        raise "Trying to open half-open connection" if @socket || @socket_tcp
+
+        ctx = OpenSSL::SSL::SSLContext.new
+        ctx.cert = OpenSSL::X509::Certificate.new(@apn_cert)
+        ctx.key = OpenSSL::PKey::RSA.new(@apn_cert)
+
+        @socket_tcp = TCPSocket.new(apn_host, apn_port)
+        @socket = OpenSSL::SSL::SSLSocket.new(@socket_tcp, ctx)
+        @socket.sync = true
+        @socket.connect
+      rescue SocketError => error
+        apn_log(:error, "Error with connection to #{apn_host}: #{error}")
+        raise "Error with connection to #{apn_host}: #{error}"      
+      end
+
+      # Close open sockets
+      def teardown_connection
+        apn_log(:info, "Closing connections...") if @opts[:verbose]
+
+        begin
+          @socket.close if @socket
+        rescue Exception => e
+          apn_log(:error, "Error closing SSL Socket: #{e}")
+        end
+
+        begin
+          @socket_tcp.close if @socket_tcp
+        rescue Exception => e
+          apn_log(:error, "Error closing TCP Socket: #{e}")
+        end
+      end
+      
+    end
+  end
+end

data/lib/apn/feedback.rb

@@ -0,0 +1,92 @@
+require File.expand_path(File.dirname(__FILE__) + '/connection/base')
+
+module APN
+  # Encapsulates data returned from the {APN Feedback Service}[http://developer.apple.com/iphone/library/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CommunicatingWIthAPS/CommunicatingWIthAPS.html#//apple_ref/doc/uid/TP40008194-CH101-SW3].
+  # Possesses +timestamp+ and +token+ attributes.
+  class FeedbackItem
+    attr_accessor :timestamp, :token
+
+    def initialize(time, token)
+      @timestamp = time
+      @token = token
+    end
+
+    # For convenience, return the token on to_s
+    def to_s
+      token
+    end
+  end
+  
+  # When supplied with the certificate path and the desired environment, connects to the {APN Feedback Service}[http://developer.apple.com/iphone/library/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CommunicatingWIthAPS/CommunicatingWIthAPS.html#//apple_ref/doc/uid/TP40008194-CH101-SW3]
+  # and returns any response as an array of APN::FeedbackItem elements.
+  # 
+  # See README for usage and details.
+  class Feedback
+    include APN::Connection::Base
+        
+    # Returns array of APN::FeedbackItem elements read from Apple. Connects to Apple once and caches the
+    # data, continues to returns cached data unless called with <code>data(true)</code>, which clears the
+    # existing feedback array.  Note that once you force resetting the cache you loose all previous feedback,
+    # so be sure you've already processed it.
+    def data(force = nil)
+      @feedback = nil if force
+      @feedback ||= receive
+    end
+    
+    # Wrapper around +data+ returning just an array of token strings.
+    def tokens(force = nil)
+      data(force).map(&:token)
+    end
+    
+    # Prettify to return meaningful status information when printed. Can't add these directly to connection/base, because Resque depends on decoding to_s
+    def inspect
+      "#<#{self.class.name}: #{to_s}>"
+    end
+    
+    # Prettify to return meaningful status information when printed. Can't add these directly to connection/base, because Resque depends on decoding to_s
+    def to_s
+      "#{@socket ? 'Connected' : 'Connection not currently established'} to #{apn_host} on #{apn_port}"
+    end
+    
+    protected
+        
+    # Connects to Apple's Feedback Service and checks if there's anything there for us.  
+    # Returns an array of APN::FeedbackItem pairs
+    def receive
+      feedback = []
+
+      # Hi Apple
+      setup_connection
+
+      # Unpacking code borrowed from http://github.com/jpoz/APNS/blob/master/lib/apns/core.rb
+      while line = socket.gets   # Read lines from the socket
+        line.strip!
+        f = line.unpack('N1n1H140')
+        feedback << APN::FeedbackItem.new(Time.at(f[0]), f[2])
+      end
+
+      # Bye Apple
+      teardown_connection
+
+      return feedback
+    end
+    
+    
+    def apn_host
+      @apn_host ||= apn_production? ? "feedback.push.apple.com" : "feedback.sandbox.push.apple.com"
+    end
+    
+    def apn_port
+      2196
+    end
+    
+  end
+end
+
+
+
+__END__
+# Testing from irb
+irb -r 'lib/apn/feedback'
+
+a=APN::Feedback.new(:cert_path => '/Users/kali/Code/insurrection/certs/', :environment => :production)

data/lib/apn/notification.rb

@@ -18,28 +18,40 @@ module APN
   #   APN::Notification.new(token, {:alert => 'Some Alert'})
   #
   class Notification
-    attr_accessor :message, :options, :json
+    attr_accessor :options, :token
     def initialize(token, opts)
       @options = hash_as_symbols(opts.is_a?(Hash) ? opts : {:alert => opts})
-      @json = generate_apple_json
-      hex_token = [token.delete(' ')].pack('H*')
-      @message = "\0\0 #{hex_token}\0#{json.length.chr}#{json}"
-      raise "The maximum size allowed for a notification payload is 256 bytes." if @message.size.to_i > 256
+      @token = token
+
+      raise "The maximum size allowed for a notification payload is 256 bytes." if packaged_notification.size.to_i > 256
     end
 
     def to_s
-      @message      
+      packaged_notification
     end
     
+    # Ensures at least one of <code>%w(alert badge sound)</code> is present
     def valid?
       return true if %w(alert badge sound).any?{|key| options.keys.include?(key.to_sym) }
       false
     end
     
     protected
-    
+
+    # Completed encoded notification, ready to send down the wire to Apple
+    def packaged_notification
+      pt = packaged_token
+      pm = packaged_message
+      [0, 0, 32, pt, 0, pm.size, pm].pack("ccca*cca*") 
+    end
+
+    # Device token, compressed and hex-ified
+    def packaged_token
+      [@token.gsub(/[\s|<|>]/,'')].pack('H*')
+    end
+
     # Convert the supplied options into the JSON needed for Apple's push notification servers
-    def generate_apple_json
+    def packaged_message
       hsh = {'aps' => {}}
       hsh['aps']['alert'] = @options[:alert].to_s if @options[:alert]
       hsh['aps']['badge'] = @options[:badge].to_i if @options[:badge]
@@ -48,7 +60,7 @@ module APN
       hsh.merge!(@options[:custom]) if @options[:custom]
       hsh.to_json
     end
-
+    
     # Symbolize keys, using ActiveSupport if available
     def hash_as_symbols(hash)
       if hash.respond_to?(:symbolize_keys)

data/lib/apn/notification_job.rb

@@ -5,18 +5,19 @@ module APN
   class NotificationJob
     # Behind the scenes, this is the name of our Resque queue
     @queue = APN::QUEUE_NAME
-    
+
     # Build a notification from arguments and send to Apple
     def self.perform(token, opts)
       msg = APN::Notification.new(token, opts)
       raise "Invalid notification options: #{opts.inspect}" unless msg.valid?
+
       worker.send_to_apple( msg )
     end
-   
-   
+
+
     # Only execute this job in specialized APN::Sender workers, since
     # standard Resque workers don't maintain the persistent TCP connection.
     extend Resque::Plugins::AccessWorkerFromJob
     self.required_worker_class = 'APN::Sender'
   end
-end
+end

data/lib/apn/sender.rb

@@ -1,7 +1,3 @@
-require 'socket'
-require 'openssl'
-require 'resque'
-
 module APN
   # Subclass of Resque::Worker which initializes a single TCP socket on creation to communicate with Apple's Push Notification servers.
   # Shares this socket with each child process forked off by Resque to complete a job. Socket is closed in the before_unregister_worker
@@ -14,94 +10,38 @@ module APN
   # Rails context, will default to RAILS_ENV and RAILS_ROOT/config/certs. :environment will default to development.  
   # APN::Sender expects two files to exist in the specified <code>:cert_path</code> directory: 
   # <code>apn_production.pem</code> and <code>apn_development.pem</code>.
+  #
+  # If a socket error is encountered, will teardown the connection and retry again twice before admitting defeat.
   class Sender < ::Resque::Worker
-    APN_PORT = 2195
-    attr_accessor :apn_cert, :apn_host, :socket, :socket_tcp, :opts
-    
-    class << self
-      attr_accessor :logger
-    end
-    
-    self.logger = if defined?(Merb::Logger)
-      Merb.logger
-    elsif defined?(RAILS_DEFAULT_LOGGER)
-      RAILS_DEFAULT_LOGGER
-    end
-
-    def initialize(opts = {})
-      @opts = opts
-
-      # Set option defaults
-      @opts[:cert_path] ||= File.join(File.expand_path(RAILS_ROOT), "config", "certs") if defined?(RAILS_ROOT)
-      @opts[:environment] ||= RAILS_ENV if defined?(RAILS_ENV)
-      
-      logger.info "APN::Sender initializing. Establishing connections first..." if @opts[:verbose]
-      setup_paths
-      setup_connection
-      
-      super( APN::QUEUE_NAME )
-    end
-        
+    include APN::Connection::Base
+    TIMES_TO_RETRY_SOCKET_ERROR = 2
+                                
     # Send a raw string over the socket to Apple's servers (presumably already formatted by APN::Notification)
-    def send_to_apple(msg)
-      @socket.write( msg.to_s )
+    def send_to_apple( notification, attempt = 0 )
+      if attempt > TIMES_TO_RETRY_SOCKET_ERROR
+        raise "Error with connection to #{apn_host} (retried #{TIMES_TO_RETRY_SOCKET_ERROR} times): #{error}"
+      end
+      
+      self.socket.write( notification.to_s )
     rescue SocketError => error
-      logger.error("Error with connection to #{@apn_host}: #{error}")
-      raise "Error with connection to #{@apn_host}: #{error}"
+      apn_log(:error, "Error with connection to #{apn_host} (attempt #{attempt}): #{error}")
+      
+      # Try reestablishing the connection
+      teardown_connection
+      setup_connection
+      send_to_apple(notification, attempt + 1)
     end
-            
+    
     protected
     
-    def apn_production?
-      @opts[:environment] && @opts[:environment] != '' && :production == @opts[:environment].to_sym
+    def apn_host
+      @apn_host ||= apn_production? ? "gateway.push.apple.com" : "gateway.sandbox.push.apple.com"
     end
     
-    # Get a fix on the .pem certificate we'll be using for SSL
-    def setup_paths
-      raise "Missing certificate path. Please specify :cert_path when initializing class." unless @opts[:cert_path]
-      @apn_host = apn_production? ? "gateway.push.apple.com" : "gateway.sandbox.push.apple.com"
-      cert_name = apn_production? ? "apn_production.pem" : "apn_development.pem"
-      cert_path = File.join(@opts[:cert_path], cert_name)
-
-      @apn_cert = File.exists?(cert_path) ? File.read(cert_path) : nil
-      raise "Missing apple push notification certificate in #{cert_path}" unless @apn_cert
+    def apn_port
+      2195
     end
 
-    # Open socket to Apple's servers
-    def setup_connection
-      raise "Missing apple push notification certificate" unless @apn_cert
-      raise "Trying to open already-open socket" if @socket || @socket_tcp
-      
-      ctx = OpenSSL::SSL::SSLContext.new
-      ctx.cert = OpenSSL::X509::Certificate.new(@apn_cert)
-      ctx.key = OpenSSL::PKey::RSA.new(@apn_cert)
-
-      @socket_tcp = TCPSocket.new(@apn_host, APN_PORT)
-      @socket = OpenSSL::SSL::SSLSocket.new(@socket_tcp, ctx)
-      @socket.sync = true
-      @socket.connect
-    rescue SocketError => error
-      logger.error("Error with connection to #{@apn_host}: #{error}")
-      raise "Error with connection to #{@apn_host}: #{error}"      
-    end
-    
-    # Close open sockets
-    def teardown_connection
-      logger.info "Closing connections..." if @opts[:verbose]
-
-      begin
-        @socket.close if @socket
-      rescue Exception => e
-        logger.error("Error closing SSL Socket: #{e}")
-      end
-      
-      begin
-        @socket_tcp.close if @socket_tcp
-      rescue Exception => e
-        logger.error("Error closing TCP Socket: #{e}")
-      end
-    end
-    
   end
 
 end
@@ -112,9 +52,14 @@ __END__
 # irb -r 'lib/apple_push_notification'
 
 ## To enqueue test job
-Resque.enqueue APN::NotificationJob, 'ceecdc18 ef17b2d0 745475e0 0a6cd5bf 54534184 ac2649eb 40873c81 ae76dbe8', {:alert => 'Resque Test'}
+k = 'ceecdc18 ef17b2d0 745475e0 0a6cd5bf 54534184 ac2649eb 40873c81 ae76dbe8'
+c = '0f58e3e2 77237b8f f8213851 c835dee0 376b7a31 9e0484f7 06fe3035 7c5dda2f'
+Resque.enqueue APN::NotificationJob, k, {:alert => 'Resque Test'}
 APN.notify 'ceecdc18 ef17b2d0 745475e0 0a6cd5bf 54534184 ac2649eb 40873c81 ae76dbe8', 'Resque Test'
 
+# If you need to really force quit some screwed up workers
+Resque.workers.map{|w| Resque.redis.srem(:workers, w)}
+
 ## To run worker from rake task
 CERT_PATH=/Users/kali/Code/insurrection/certs/ ENVIRONMENT=production rake apn:work
 
@@ -128,6 +73,4 @@ worker.work(5)
 ## To run worker as daemon - NOT YET TESTED
 APN::SenderDaemon.new(ARGV).daemonize
 
-## TESTING - check the broken pipe errors
 
-## TESTING - then check implementation of resque-web

data/lib/apn.rb

@@ -22,4 +22,6 @@ end
 
 require 'apn/notification'
 require 'apn/notification_job'
-require 'apn/sender'
+require 'apn/connection/base'
+require 'apn/sender'
+require 'apn/feedback'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: apn_sender
 version: !ruby/object:Gem::Version 
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors: 
 - Kali Donovan
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-04-25 00:00:00 -07:00
+date: 2010-05-02 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -54,6 +54,8 @@ files:
 - generators/templates/script
 - init.rb
 - lib/apn.rb
+- lib/apn/connection/base.rb
+- lib/apn/feedback.rb
 - lib/apn/notification.rb
 - lib/apn/notification_job.rb
 - lib/apn/queue_manager.rb