apns_dispatch 0.1.0

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.rvmrc
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in apns_dispatch.gemspec
+gemspec

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2012 SCVNGR, Inc.
+
+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.md

@@ -0,0 +1,54 @@
+# ApnsDispatch
+
+A simple Ruby framework for sending push notifications and receiving feedback using the Apple Push Notification service
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'apns_dispatch'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install apns_dispatch
+
+## Sending Notifications
+
+    connection = ApnsConnection.new(CERTIFICATE, production: true)
+    ApnNotification.new(connection, DEVICE_TOKEN, 'a message to a device').send_notification
+
+## Checking the Feedback Service
+
+[Apple recommends](https://developer.apple.com/library/ios/#documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CommunicatingWIthAPS/CommunicatingWIthAPS.html#//apple_ref/doc/uid/TP40008194-CH101-SW3)
+periodically checking their feedback service for device tokens that have failed delivery. The feedback
+service also returns the time of the failure. If a device token was registered before the failure time,
+it should be removed from your system.
+
+    connection = ApnsConnection.new(CERTIFICATE, production: true, feedback: true)
+    ApnFeedback.new(connection).failed_device_tokens.each do |device_token, failure_time|
+        # Delete this device token from your system, if the registration time is before failure_time
+    end
+
+## Connection Pooling
+
+If notifications are sent frequently, latency will be improved by reusing connections to the Push
+Notification service. ApnsDispatch also provides connection pooling:
+
+    # Initiates a new connection to the APNs
+    connection = ApnsConnectionPool.connection(CERTIFICATE, production: true)
+
+    # This will return the same connection, rather than initiating a new one
+    connection = ApnsConnectionPool.connection(CERTIFICATE, production: true)
+
+## Requirements
+
+`apns_dispatch` requires Ruby 1.9+.
+
+## License
+
+`apns_dispatch` is written by Costa Walcott, and is Copyright 2012 SCVNGR, Inc. It is free software,
+and may be redistributed under the terms specified in the MIT-LICENSE file.

data/Rakefile

@@ -0,0 +1,10 @@
+require 'bundler/setup'
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new do |t|
+  t.pattern = 'spec/**/*_spec.rb'
+end
+
+desc 'Default: run the rspec examples'
+task :default => [:spec]

data/apns_dispatch.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'apns_dispatch/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = 'apns_dispatch'
+  gem.version       = ApnsDispatch::VERSION
+  gem.authors       = ['Costa Walcott']
+  gem.email         = ['costa@scvngr.com']
+  gem.summary       = 'A simple Ruby framework for communicating with the APNs'
+  gem.description   = 'A simple Ruby framework for sending push notifications and receiving feedback using the Apple Push Notification service'
+  gem.homepage      = 'http://github.com/TheLevelUp/apns_dispatch'
+
+  gem.files         = `git ls-files`.split($/)
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+
+  gem.add_dependency 'json', '~> 1.7.5'
+
+  gem.add_development_dependency 'rake'
+  gem.add_development_dependency 'rspec', '~> 2.0'
+
+  gem.required_ruby_version = Gem::Requirement.new('>= 1.9.2')
+  gem.require_paths = ["lib"]
+end

data/lib/apns_dispatch.rb

@@ -0,0 +1,16 @@
+# This gem provides a simple Ruby wrapper for communicating with the Apple Push Notification service
+# (APNs). It handles SSL, sending push notifications to APNs using Apple's binary protocol, and
+# retriving failed device tokens using the APN feedback service. Both development and production
+# certificates are handled.
+#
+# Author::    Costa Walcott  (mailto:costa@scvngr.com)
+# Copyright:: Copyright (c) 2012 SCVNGR, Inc.
+# License::   MIT
+
+require 'json'
+
+require 'apns_dispatch/apn_feedback'
+require 'apns_dispatch/apn_notification'
+require 'apns_dispatch/apns_connection'
+require 'apns_dispatch/apns_connection_pool'
+require 'apns_dispatch/version'

data/lib/apns_dispatch/apn_feedback.rb

@@ -0,0 +1,30 @@
+module ApnsDispatch
+  # Retrieves and returns failed device tokens from production and development APNs connections.
+
+  class ApnFeedback
+    # Constants
+    FEEDBACK_PACKET_FORMAT = 'N1n1H140'
+    FEEDBACK_PACKET_LENGTH = 38
+
+    def initialize(connection)
+      @connection = connection
+    end
+
+    def failed_device_tokens
+      apns_feedback = []
+
+      while line = @connection.read(FEEDBACK_PACKET_LENGTH)
+        apns_feedback << unpackage(line)
+      end
+
+      apns_feedback
+    end
+
+    private
+
+    def unpackage(line)
+      feedback = line.unpack(FEEDBACK_PACKET_FORMAT)
+      [feedback[2], Time.at(feedback[0])]
+    end
+  end
+end

data/lib/apns_dispatch/apn_notification.rb

@@ -0,0 +1,43 @@
+module ApnsDispatch
+  # Creates a packaged notification for the APNs. Based on code from https://github.com/jpoz/APNS.
+
+  class ApnNotification
+    def initialize(connection, token, message, options = {})
+      @connection = connection
+      @token = token
+      @message = message
+      @options = options
+    end
+
+    def send_notification
+      @connection.write notification_packet
+    end
+
+    private
+
+    def binary_token
+      [@token].pack 'H*'
+    end
+
+    def command
+      0
+    end
+
+    def message_information
+      {
+        aps: {
+          alert: @message,
+          sound: 'default'
+        }
+      }
+    end
+
+    def notification_packet
+      [command, binary_token.bytesize, binary_token, payload.bytesize, payload].pack 'cna*na*'
+    end
+
+    def payload
+      message_information.merge(@options).to_json
+    end
+  end
+end

data/lib/apns_dispatch/apns_connection.rb

@@ -0,0 +1,100 @@
+require 'openssl'
+require 'socket'
+
+module ApnsDispatch
+  # Handles communication with the Apple Push Notification service (APNs).
+  # Based on code from https://github.com/itspriddle/apnd.
+
+  class ApnsConnection
+    # Constants
+    FEEDBACK_PORT = 2196
+    GATEWAY_PORT = 2195
+    PRODUCTION_FEEDBACK_HOST = 'feedback.push.apple.com'
+    PRODUCTION_GATEWAY_HOST = 'gateway.push.apple.com'
+    SANDBOX_FEEDBACK_HOST = 'feedback.sandbox.push.apple.com'
+    SANDBOX_GATEWAY_HOST = 'gateway.sandbox.push.apple.com'
+
+    # Attributes
+    attr_reader :certificate, :host, :options, :port
+
+    def initialize(certificate, options={})
+      if options[:feedback]
+        @port = FEEDBACK_PORT
+
+        if options[:production]
+          @host = PRODUCTION_FEEDBACK_HOST
+        else
+          @host = SANDBOX_FEEDBACK_HOST
+        end
+      else
+        @port = GATEWAY_PORT
+
+        if options[:production]
+          @host = PRODUCTION_GATEWAY_HOST
+        else
+          @host = SANDBOX_GATEWAY_HOST
+        end
+      end
+
+      @certificate = certificate
+      @options = options
+    end
+
+    def read(length)
+      with_connection { @ssl.read(length) }
+    end
+
+    def write(message)
+      with_connection { @ssl.write(message) }
+    end
+
+    private
+
+    def connect!
+      context = OpenSSL::SSL::SSLContext.new
+      context.cert = OpenSSL::X509::Certificate.new(@certificate)
+      context.key = OpenSSL::PKey::RSA.new(@certificate)
+
+      @sock = TCPSocket.new(host, port)
+      @ssl = OpenSSL::SSL::SSLSocket.new(@sock, context)
+      @ssl.sync = true
+      @ssl.connect
+    end
+
+    def connected?
+      !@ssl.nil?
+    end
+
+    def disconnect!
+      @ssl.close
+      @sock.close
+      @ssl = nil
+      @sock = nil
+    end
+
+    def reconnect!
+      disconnect!
+      connect!
+    end
+
+    def with_connection
+      unless connected?
+        connect!
+      end
+
+      attempted = false
+
+      begin
+        if block_given?
+          yield
+        end
+      rescue Errno::EPIPE, OpenSSL::SSL::SSLError
+        unless attempted
+          reconnect!
+          attempted = true
+          retry
+        end
+      end
+    end
+  end
+end

data/lib/apns_dispatch/apns_connection_pool.rb

@@ -0,0 +1,25 @@
+require 'digest/md5'
+require 'apns_dispatch/null_apns_connection'
+
+module ApnsDispatch
+  # Caches and returns individual unique ApnsConnections in memory.
+
+  class ApnsConnectionPool
+    def self.connection(certificate, options={})
+      if certificate
+        cache_key = cache_key(certificate, options)
+
+        @connections ||= {}
+        @connections[cache_key] ||= ApnsDispatch::ApnsConnection.new(certificate, options)
+      else
+        ApnsDispatch::NullApnsConnection.new
+      end
+    end
+
+    private
+
+    def self.cache_key(certificate, options)
+      [Digest::MD5.hexdigest(certificate), options.hash]
+    end
+  end
+end

data/lib/apns_dispatch/null_apns_connection.rb

@@ -0,0 +1,9 @@
+module ApnsDispatch
+  class NullApnsConnection
+    def read(length)
+    end
+
+    def write(message)
+    end
+  end
+end

data/lib/apns_dispatch/version.rb

@@ -0,0 +1,3 @@
+module ApnsDispatch
+  VERSION = '0.1.0'
+end

data/spec/apns_dispatch/apn_feedback_spec.rb

@@ -0,0 +1,22 @@
+require 'spec_helper'
+
+describe ApnsDispatch::ApnFeedback do
+  # Helpers
+  def packed_feedback(feedback)
+    [feedback[1].to_i, 140, feedback[0]].pack 'N1n1H*'
+  end
+
+  before do
+    @failed_token = ['ced238e503ece0f6d664e1b8bdae7d9dffc39c2303bf7466cd83cb2783ad40b2',
+      Time.new(2012, 9, 1)]
+
+    apn_connection = stub
+    apn_connection.stub(:read).with(38).and_return packed_feedback(@failed_token), nil
+
+    @apn_feedback = ApnsDispatch::ApnFeedback.new(apn_connection)
+  end
+
+  it 'returns the failed tokens' do
+    [@failed_token].should == @apn_feedback.failed_device_tokens
+  end
+end

data/spec/apns_dispatch/apn_notification_spec.rb

@@ -0,0 +1,20 @@
+require 'spec_helper'
+
+describe ApnsDispatch::ApnNotification do
+  before do
+    token = '7307dea69c58e9625250aabb040594e1a031f574dba5d97549fbe211327aff4c'
+    message = 'test message'
+    options = { order_id: 12345 }
+    @connection = stub
+    @apn_notificiation = ApnsDispatch::ApnNotification.new(@connection, token, message, options)
+
+    payload = { aps: { alert: message, sound: 'default'} }.merge(options).to_json
+    @packet = [0, 32, [token].pack('H*'), payload.bytesize, payload].pack('cna*na*')
+  end
+
+  it 'sends a notification packet to the connection' do
+    @connection.should_receive(:write).with(@packet)
+
+    @apn_notificiation.send_notification
+  end
+end

data/spec/apns_dispatch/apns_connection_pool_spec.rb

@@ -0,0 +1,34 @@
+require 'spec_helper'
+
+describe ApnsDispatch::ApnsConnectionPool do
+  before do
+    @options = { production: true }
+  end
+
+  context 'when a certificate is given' do
+    before do
+      @certificate = 'test-certificate'
+      @connection = ApnsDispatch::ApnsConnectionPool.connection(@certificate, @options)
+    end
+
+    context 'when called for the first time' do
+      it 'returns a new ApnsConnection with the correct values' do
+        @connection.certificate.should == @certificate
+        @connection.options.should == @options
+      end
+    end
+
+    context 'when called after the first time' do
+      it 'returns the same connection' do
+        ApnsDispatch::ApnsConnectionPool.connection(@certificate, @options).should == @connection
+      end
+    end
+  end
+
+  context 'when a nil certificate is given' do
+    it 'returns a null connection' do
+      result = ApnsDispatch::ApnsConnectionPool.connection(nil)
+      result.should be_kind_of(ApnsDispatch::NullApnsConnection)
+    end
+  end
+end

data/spec/apns_dispatch/apns_connection_spec.rb

@@ -0,0 +1,122 @@
+require 'spec_helper'
+
+describe ApnsDispatch::ApnsConnection do
+  # Helpers
+  def self.should_run_command_with_connection(command, argument)
+    before do
+      TCPSocket.stub new: stub(close: true)
+
+      certificate = 'test-certificate'
+      @ssl = stub(close: true, connect: true, read: true, 'sync=' => true, write: true)
+      OpenSSL::SSL::SSLSocket.stub new: @ssl
+      OpenSSL::X509::Certificate.stub new: certificate
+      OpenSSL::PKey::RSA.stub new: certificate
+
+      @apns_connection = ApnsDispatch::ApnsConnection.new(certificate)
+    end
+
+    it 'runs the given block' do
+      @ssl.should_receive(command).with(argument)
+
+      @apns_connection.send command, argument
+    end
+
+    it 'retries once' do
+      @ssl.should_receive(command).with(argument).twice.and_return do
+        unless @run
+          @run = true
+          raise OpenSSL::SSL::SSLError
+        end
+      end
+
+      @apns_connection.send command, argument
+    end
+
+    it 'uses the correct host and port' do
+      TCPSocket.should_receive(:new).with(@apns_connection.host, @apns_connection.port)
+
+      @apns_connection.send command, argument
+    end
+
+    context 'when there is no connection' do
+      it 'initiates a connection' do
+        @ssl.should_receive :connect
+
+        @apns_connection.send command, argument
+      end
+    end
+
+    context 'when there is already a connection' do
+      before do
+        @apns_connection.instance_variable_set :@ssl, @ssl
+      end
+
+      it 'does not reconnect' do
+        @ssl.should_receive(:connect).never
+
+        @apns_connection.send command, argument
+      end
+    end
+  end
+
+  it 'has the correct APNs hosts and ports' do
+    ApnsDispatch::ApnsConnection::FEEDBACK_PORT.should == 2196
+    ApnsDispatch::ApnsConnection::GATEWAY_PORT.should == 2195
+    ApnsDispatch::ApnsConnection::PRODUCTION_FEEDBACK_HOST.should == 'feedback.push.apple.com'
+    ApnsDispatch::ApnsConnection::PRODUCTION_GATEWAY_HOST.should == 'gateway.push.apple.com'
+    ApnsDispatch::ApnsConnection::SANDBOX_FEEDBACK_HOST.should == 'feedback.sandbox.push.apple.com'
+    ApnsDispatch::ApnsConnection::SANDBOX_GATEWAY_HOST.should == 'gateway.sandbox.push.apple.com'
+  end
+
+  context 'with :feedback option and :production option' do
+    before do
+      @connection = ApnsDispatch::ApnsConnection.new('test', feedback: true, production: true)
+    end
+
+    it 'uses the production feedback host and feedback port' do
+      @connection.host.should == ApnsDispatch::ApnsConnection::PRODUCTION_FEEDBACK_HOST
+      @connection.port.should == ApnsDispatch::ApnsConnection::FEEDBACK_PORT
+    end
+  end
+
+  context 'with :feedback option only' do
+    before do
+      @connection = ApnsDispatch::ApnsConnection.new('test', feedback: true)
+    end
+
+    it 'uses the sandbox feedback host and feedback port' do
+      @connection.host.should == ApnsDispatch::ApnsConnection::SANDBOX_FEEDBACK_HOST
+      @connection.port.should == ApnsDispatch::ApnsConnection::FEEDBACK_PORT
+    end
+  end
+
+  context 'with :production option only' do
+    before do
+      @connection = ApnsDispatch::ApnsConnection.new('test', production: true)
+    end
+
+    it 'uses the production gateway host and gateway port' do
+      @connection.host.should == ApnsDispatch::ApnsConnection::PRODUCTION_GATEWAY_HOST
+      @connection.port.should == ApnsDispatch::ApnsConnection::GATEWAY_PORT
+    end
+  end
+
+  context 'with no options' do
+    before do
+      @connection = ApnsDispatch::ApnsConnection.new('test')
+    end
+
+    it 'uses the sandbox gateway host and gateway port' do
+      @connection.host.should == ApnsDispatch::ApnsConnection::SANDBOX_GATEWAY_HOST
+      @connection.port.should == ApnsDispatch::ApnsConnection::GATEWAY_PORT
+    end
+  end
+
+  context 'with read command' do
+    should_run_command_with_connection :read, 10
+  end
+
+  context 'with write command' do
+    should_run_command_with_connection :write, 'test message'
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,4 @@
+require 'rubygems'
+require 'bundler/setup'
+
+require 'apns_dispatch'

metadata

@@ -0,0 +1,117 @@
+--- !ruby/object:Gem::Specification
+name: apns_dispatch
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Costa Walcott
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-11-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.7.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.7.5
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: A simple Ruby framework for sending push notifications and receiving
+  feedback using the Apple Push Notification service
+email:
+- costa@scvngr.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- MIT-LICENSE
+- README.md
+- Rakefile
+- apns_dispatch.gemspec
+- lib/apns_dispatch.rb
+- lib/apns_dispatch/apn_feedback.rb
+- lib/apns_dispatch/apn_notification.rb
+- lib/apns_dispatch/apns_connection.rb
+- lib/apns_dispatch/apns_connection_pool.rb
+- lib/apns_dispatch/null_apns_connection.rb
+- lib/apns_dispatch/version.rb
+- spec/apns_dispatch/apn_feedback_spec.rb
+- spec/apns_dispatch/apn_notification_spec.rb
+- spec/apns_dispatch/apns_connection_pool_spec.rb
+- spec/apns_dispatch/apns_connection_spec.rb
+- spec/spec_helper.rb
+homepage: http://github.com/TheLevelUp/apns_dispatch
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: A simple Ruby framework for communicating with the APNs
+test_files:
+- spec/apns_dispatch/apn_feedback_spec.rb
+- spec/apns_dispatch/apn_notification_spec.rb
+- spec/apns_dispatch/apns_connection_pool_spec.rb
+- spec/apns_dispatch/apns_connection_spec.rb
+- spec/spec_helper.rb