apn_sender 0.0.7 → 1.0.0

data/README.rdoc

@@ -1,17 +1,20 @@
-= CURRENT STATUS
+== Synopsis
 
-  This gem is still in development.  It is functional for me, but I'm still working on getting the background daemon running properly (read: haven't tested it at all, expect it to fail).
-  
-  I'll be working on this soon, though, and expect to have a stable version released in the next few weeks (or maybe days).
-  
+Need to send background notifications to an iPhone application over a <em>persistent</em> connection in Ruby? Keep reading...
+
+== The Story
+
+So you're building the server component of an iPhone application in Ruby.  And you want to send background notifications through the Apple Push Notification servers, which doesn't seem too bad at first.  But then you read in the {Apple Documentation}[https://developer.apple.com/iphone/library/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/WhatAreRemoteNotif/WhatAreRemoteNotif.html#//apple_ref/doc/uid/TP40008194-CH102-SW7] that Apple's servers may treat non-persistent connections as a Denial of Service attack, and you realize that Rails has no easy way to maintain a persistent connection internally, and things started looking more complicated.
+
+The apn_sender gem includes a background daemon which processes background messages from your application and sends them along to Apple <em>over a single, persistent socket</em>.  It also includes the ability to query the Feedback service, helper methods for enqueueing your jobs, and a sample monit config to make sure the background worker is around when you need it.
 
-= apn_sender
+== Yet another ApplePushNotification interface?
 
-So you're building the server component of an iPhone application in Ruby.  And you want to send background notifications through the Apple Push Notification servers, which doesn't seem too bad.  But then you read in the {Apple Documentation}[https://developer.apple.com/iphone/library/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/WhatAreRemoteNotif/WhatAreRemoteNotif.html#//apple_ref/doc/uid/TP40008194-CH102-SW7] (<em>Apple Dev account required</em>) that Apple's servers may treat non-persistent connections as a Denial of Service attack, and things started looking more complicated.
+Yup.  There's some great code out there already, but we didn't like the idea of getting banned from the APN gateway for establishing a new connection each time we needed to send a batch of messages, and none of the libraries I found handled maintaining a persistent connection.
 
-If this doesn't sound familiar, this gem probably isn't anything you need.  If it does, though...
+== Current Status
 
-The apn_sender gem includes a background daemon which processes background messages from your application and sends them along to Apple <em>over a single, persistent socket</em>.  It also includes helper methods for enqueueing your jobs and a sample monit config to make sure the background worker is around when you need it.
+This gem has been in production use since early May, 2010.  There are no guarantees of complete functionality, of course, but it's working for us. :)
 
 
 == Usage
@@ -39,14 +42,17 @@ Once this is done, you can fire off a background worker with
   
 For production, you're probably better off running a dedicated daemon and setting up monit to watch over it for you.  Luckily, that's pretty easy:
 
-  # To run standard daemon
-  ./script/apn_sender
-  
-  # To pass in options
-  ./script/apn_sender -- --cert-path=PATH_TO_NONSTANDARD_FOLDER_WITH_PEM_FILES --environment=production
+  # To generate daemon
+  ./script/generate apn_sender
+
+  # To run daemon. Pass --help to print all options
+  ./script/apn_sender --environment=production --verbose start
 
 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>.
 
+Check <code>RAILS_ROOT/logs/apn_sender.log</code> for debugging output.  In addition to logging any major errors there, apn_sender hooks into the Resque::Worker logging to display any verbose or very_verbose worker output in apn_sender.log file as well.
+
+
 === 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.
@@ -71,7 +77,7 @@ If you're interested in knowing exactly <em>when</em> Apple determined each toke
     # ... 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.
+The Feedback Service works as a big queue.  When you connect it pops off all its data and sends it over the wire at once, which means connecting a second time will return an empty array, so for ease of use a call to either +tokens+ or +data+ will connect once and cache the data.  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, which is probably not what you want).
 
 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.
 

data/VERSION

@@ -1 +1 @@
-0.0.7
+1.0.0

data/apn_sender.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{apn_sender}
-  s.version = "0.0.7"
+  s.version = "1.0.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Kali Donovan"]

data/contrib/apn_sender.monitrc

@@ -1,13 +1,21 @@
-# an example Monit configuration file for running the apple_push_notification background sender
+# An example Monit configuration file for running the apn_sender background daemon
 #
-# To use:
-# 1. copy to /var/www/apps/{app_name}/shared/apn_sender.monitrc
-# 2. replace {app_name} as appropriate
-# 3. add this to your /etc/monit/monitrc
-#
-#   include /var/www/apps/{app_name}/shared/apn_sender.monitrc
+#   1. Replace #{app_name} with the path to your configuration
+#   2. Add any arguments between apn_sender the and start/stop command
+#   3. Install as a monitrc file
+
+check process redis
+  with pidfile /tmp/redis.pid
+  group apn_sender
+  start program = "/usr/bin/redis-server /etc/redis.conf"
+  stop program = "/bin/echo SHUTDOWN | nc localhost 6379"
+  if failed host 127.0.0.1 port 6379 then restart
+  if 5 restarts within 5 cycles then timeout
+
 
 check process apn_sender
-  with pidfile /var/www/apps/{app_name}/shared/pids/apn_sender.pid
-  start program = "/usr/bin/env RAILS_ENV=production /var/www/apps/{app_name}/current/script/apn_sender start"
-  stop program = "/usr/bin/env RAILS_ENV=production /var/www/apps/{app_name}/current/script/apn_sender stop"
+  with pidfile /var/www/apps/#{app_name}/shared/pids/apn_sender.pid
+  group apn_sender
+  start program = "/usr/bin/env RAILS_ENV=production /var/www/apps/{app_name}/current/script/apn_sender --environment=production start"
+  stop program = "/usr/bin/env RAILS_ENV=production /var/www/apps/{app_name}/current/script/apn_sender --environment=production stop"
+  depends_on redis

data/lib/apn/connection/base.rb

@@ -4,6 +4,8 @@ require 'resque'
 
 module APN
   module Connection
+    # APN::Connection::Base takes care of all the boring certificate loading, socket creating, and logging
+    # responsibilities so APN::Sender and APN::Feedback and focus on their respective specialties.
     module Base
       attr_accessor :opts, :logger
       
@@ -25,6 +27,7 @@ module APN
             
       protected
       
+      # Default to Rails or Merg logger, if available
       def setup_logger
         @logger = if defined?(Merb::Logger)
           Merb.logger

data/lib/apn/notification.rb

@@ -59,13 +59,14 @@ module APN
     # Extracts :alert, :badge, and :sound keys into the 'aps' hash, merges any other hash data
     # into the root of the hash to encode and send to apple.
     def packaged_message
+      opts = @options.clone # Don't destroy our pristine copy
       hsh = {'aps' => {}}
-      hsh['aps']['alert'] = @options.delete(:alert).to_s if @options[:alert]
-      hsh['aps']['badge'] = @options.delete(:badge).to_i if @options[:badge]
-      if sound = @options.delete(:sound)
+      hsh['aps']['alert'] = opts.delete(:alert).to_s if opts[:alert]
+      hsh['aps']['badge'] = opts.delete(:badge).to_i if opts[:badge]
+      if sound = opts.delete(:sound)
         hsh['aps']['sound'] = sound.is_a?(TrueClass) ? 'default' : sound.to_s
       end
-      hsh.merge!(@options)
+      hsh.merge!(opts)
       hsh.to_json
     end
     

data/lib/apn/notification_job.rb

@@ -9,7 +9,7 @@ module APN
     # 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?
+      raise "Invalid notification options (did you provide :alert, :badge, or :sound?): #{opts.inspect}" unless msg.valid?
 
       worker.send_to_apple( msg )
     end

data/lib/apn/sender.rb

@@ -54,23 +54,23 @@ __END__
 ## To enqueue test job
 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 k, '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
+# To run worker from rake task
 CERT_PATH=/Users/kali/Code/insurrection/certs/ ENVIRONMENT=production rake apn:work
 
-## To run worker from IRB 
+# To run worker from IRB 
 Resque.workers.map(&:unregister_worker)
 require 'ruby-debug'
 worker = APN::Sender.new(:cert_path => '/Users/kali/Code/insurrection/certs/', :environment => :production)
 worker.very_verbose = true
 worker.work(5)
 
-## To run worker as daemon - NOT YET TESTED
-APN::SenderDaemon.new(ARGV).daemonize
+# To run worker as daemon
+args = ['--environment=production', '--cert-path=/Users/kali/Code/insurrection/certs/']
+APN::SenderDaemon.new(args).daemonize
 
 

data/lib/apn/sender_daemon.rb

@@ -4,12 +4,17 @@ require 'daemons'
 require 'optparse'
 
 module APN
+  # A wrapper designed to daemonize an APN::Sender instance to keep in running in the background.
+  # Connects worker's output to the Rails logger, if available.  Creates a pid file suitable for
+  # monitoring with {monit}[http://mmonit.com/monit/].
+  #
+  # Based off delayed_job's great example.  To use in a Rails app, <code>script/generate apn_sender</code>.
   class SenderDaemon
     
     def initialize(args)
-      @options = {:quiet => true, :worker_count => 1, :environment => :development}
+      @options = {:quiet => true, :worker_count => 1, :environment => :development, :delay => 5}
       
-      opts = OptionParser.new do |opts|
+      optparse = OptionParser.new do |opts|
         opts.banner = "Usage: #{File.basename($0)} [options] start|stop|restart|run"
 
         opts.on('-h', '--help', 'Show this message') do
@@ -38,8 +43,7 @@ module APN
       
       # If no arguments, give help screen
       @args = optparse.parse!(args.empty? ? ['-h'] : args)
-      
-      puts "OPTS: #{@options.inspect}"
+      @options[:verbose] = true if @options[:very_verbose]
     end
   
     def daemonize

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: apn_sender
 version: !ruby/object:Gem::Version 
-  version: 0.0.7
+  version: 1.0.0
 platform: ruby
 authors: 
 - Kali Donovan