matchbox20 0.3.2

data/.gitignore

@@ -0,0 +1,2 @@
+.DS_Store
+pkg

data/Gemfile

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

data/Rakefile

@@ -0,0 +1,2 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks

data/Readme.markdown

@@ -0,0 +1,116 @@
+# Matchbox20 - Apple Push Notifications in Rails Done Right.
+
+This plugin helps you use the Apple Push Notification system.
+
+## Installing
+
+#### In Rails 3:
+
+Add to Gemfile:
+
+    gem "matchbox20"
+
+At command prompt:
+
+    $ bundle install
+
+## Converting Your Certificate
+
+Once you have the certificate from Apple for your application, export your key
+and the apple certificate as p12 files. Here's how:
+
+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 apn_development.pem -nodes -clcerts && rm -f cert.p12
+
+Put `apn_development.pem` in `config/certs` in your rails app. For production, name your certificate `apn_production.pem` and put it in the same directory. See the environment section for more about environments.
+
+## Environment
+
+By default, the development environment will always be used. This makes it easy to test your app in production before your iPhone application is approved and your production certificate is active. You can easily override this by adding this line in an initializer or environment file.
+
+    Matchbox20.enviroment = Rails.env.to_sym
+
+You can also simply set `Matchbox20.enviroment` to `:development` or `:production`. Setting the `Matchbox20.enviroment` chooses the appropriate certificate in your `certs` folder and Apple push notification server.
+
+## Usage
+
+You can use Matchbox20 with an ActiveRecord model, standalone, or on any object.
+
+### ActiveRecord
+
+Just add `acts_as_pushable` to your model.
+
+    class Device < ActiveRecord::Base
+        acts_as_pushable
+    end
+
+You can then send a notification like this
+
+    d.send_notification :alert => "I wanna push you around, well I will, well I will."
+
+The `send_notification` method accepts a hash of options for the notification parameters. See the Parameters section for more information.
+
+Your model must have a `device_token` attribute. If you wish to change this to something else (like `device` for example), simply pass it like this `acts_as_pushable :device`.
+
+### Standalone
+
+Simply call `Matchbox20.send_notification` and pass the device token as the first parameter and the hash of notification options as the second (see the Parameters section for more information).
+
+    $ rails console
+    >> token = "XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX"
+    >> Matchbox20.send_notification token, :alert => "Hello World!", :badge => 5, :sound => "RobThomas.aif"
+    => nil
+
+### Batching
+
+If you have a lot of notifications to send, its probably better for performance reasons to open one connection to Apple's servers, push all your notifications through, then close the connection. This is really easy thank's to Matchbox20's `send_notification_batch` method. You can simply pass it a block like so:
+
+    Matchbox20.send_notification_batch do
+		Matchbox20.send_notification token, :alert => "I wish the real world", :badge => 1, :sound => true
+		Matchbox20.send_notification token, :alert => "would just stop", :badge => 2, :sound => true
+		Matchbox20.send_notification token, :alert => "hasslin' me!", :badge => 3, :sound => true
+   	end
+
+### Any Object
+
+You can extend Matchbox20 with any class. It will look for the `device_token` method when sending the notification. When Matchbox20 is extended, if `device_token=` isn't defined, getters and setters are generated.
+
+    $ rails console
+    >> token = "XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX"
+    >> d = Object.new
+    >> d.extend Matchbox20
+    >> d.device_token = token
+    >> d.send_notification :alert => "So flexible"
+    => nil
+
+See the Parameters section for more information on what `send_notification` accepts.
+
+## Parameters
+
+The following notification parameters can be defined in the options hash:
+
+* `alert` - text displayed to the use
+* `sound` - this can be the filename (i.e. `explosion.aiff`) or `true` which will play the default notification sound
+* `badge` - this must be an integer
+* `extra` - this is optional and should be a hash of the extra values you'd like to pass on in your notification payload (keep in mind that notification payloads are limited to 256 bytes)
+
+## Feedback
+
+#### Getting a list of device tokens that have removed your app
+
+Apple recommends that you (and you really should) stop sending push notifications to devices that have removed your app. While any notifications sent to these devices will simply fail with an error upon sending, its just wasteful to be sending all those packets for nothing. Matchbox20 provides a great way for you to get a list back of device tokens that have remove your app from their phones. You can call these periodically in the background using some gems like delayed_job and whenever. You interact with this list of devices by passing a block like so:
+
+    Matchbox20.expired_tokens do |token, removed_at|
+		# do whatever you need to with these values, likely up the devices by token in your database and set whatever flags you'd like on that object
+   	end
+
+## Notes
+
+* The spaces in `device_token` are optional and will be ignored. 
+
+Copyright (c) 2010 [Jake Marsh](http://deallocatedobjects.com). Released under the MIT license. Forked from Sam Soffes who forked it from Fabien Penso.

data/lib/matchbox20/acts_as_pushable.rb

@@ -0,0 +1,16 @@
+module Matchbox20
+    module ActsAsPushable
+        
+    end
+end
+
+ActiveRecord::Base.class_eval do
+    def self.acts_as_pushable(device_token_field = :device_token)
+        class_inheritable_reader :acts_as_push_options
+        write_inheritable_attribute :acts_as_push_options, {
+            :device_token_field => device_token_field
+        }
+
+        include Matchbox20
+    end
+end

data/lib/matchbox20/version.rb

@@ -0,0 +1,3 @@
+module Matchbox20
+    VERSION = "0.3.2"
+end

data/lib/matchbox20.rb

@@ -0,0 +1,199 @@
+require 'socket'
+require 'openssl'
+require 'pp'
+
+module Matchbox20
+    def self.extended(base)
+        # Added device_token attribute if not included by acts_as_pushable
+        unless base.respond_to?(:acts_as_push_options)
+            base.class_eval do
+                attr_accessor :device_token
+            end
+        end
+    end
+
+    APN_PORT = 2195
+    APN_GATEWAY = "gateway.push.apple.com"
+    APN_SANDBOX_GATEWAY = "gateway.sandbox.push.apple.com"
+
+    FEEDBACK_PORT = 2196
+    FEEDBACK_SERVICE = "feedback.push.apple.com"
+    FEEDBACK_SANDBOX_SERVICE = "feedback.sandbox.push.apple.com"
+
+    @@apn_cert = nil
+    @@apn_host = nil
+    @@apn_feedback_host = nil
+    
+    @@s = nil
+    @@ssl = nil
+
+
+
+    def self.apn_enviroment
+        @@apn_enviroment
+    end
+
+    def self.apn_development?
+        @@apn_enviroment != :production
+    end
+
+    def self.apn_production?
+        @@apn_enviroment == :production
+    end
+
+    def self.apn_enviroment= enviroment
+        @@apn_enviroment = enviroment.to_sym
+        @@apn_host = self.apn_production? ? APN_GATEWAY : APN_SANDBOX_GATEWAY
+        @@apn_feedback_host = self.apn_production? ? FEEDBACK_SERVICE : FEEDBACK_SANDBOX_SERVICE
+
+        cert = self.apn_production? ? "apn_production.pem" : "apn_development.pem"
+
+        path = File.join(File.expand_path(Rails.root.to_s), "config", "certs", cert)
+        @@apn_cert = File.exists?(path) ? File.read(path) : nil
+
+        raise "Missing apple push notification certificate in #{path}" unless @@apn_cert
+    end
+
+    self.apn_enviroment = :development
+
+    def send_notification options
+        raise "Missing apple push notification certificate" unless @@apn_cert
+
+        if Matchbox20.is_connected_to_gateway?
+            self.write_notification_to_connection_using_options(options)
+        else
+            Matchbox20.open_ssl_connection(@@apn_host, APN_PORT)
+            self.write_notification_to_connection_using_options(options)
+            Matchbox20.close_ssl_connection
+        end
+    end
+
+    def self.send_notification_batch
+        Matchbox20.open_ssl_connection(@@apn_host, APN_PORT)
+
+        yield
+
+        Matchbox20.close_ssl_connection
+    end
+
+    def self.send_notification token, options = {}
+        d = Object.new
+        d.extend Matchbox20
+        d.device_token = token
+        d.send_notification options
+    end
+
+    def self.expired_tokens
+        Matchbox20.open_ssl_connection(@@apn_feedback_host, FEEDBACK_PORT)
+
+        while line = @@ssl.read(38)
+            line.strip!
+            feedback = line.unpack('N1n1H140')
+            token = feedback[2].scan(/.{0,8}/).join('').strip
+
+            yield(token, Time.at(feedback[0]))
+
+            puts "Found Deactivated Token: #{token}, deactivated on #{Time.at(feedback[0])}"
+        end
+
+        Matchbox20.close_ssl_connection
+    end
+
+
+
+
+    protected
+    
+    def self.is_connected_to_gateway?
+        @@s && @@ssl
+    end
+    
+    def write_notification_to_connection_using_options(options)
+        puts "Sending Notification..."
+        @@ssl.write(self.apn_message_for_sending(options))
+    rescue SocketError => error
+        @@s = nil
+        @@ssl = nil
+
+        raise "Error while sending notification: #{error}"
+    end
+
+    def apn_message_for_sending options
+        json = Matchbox20::apple_json_array options
+        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
+        # Use `device_token` as the method to get the token from
+        # unless it is overridde from acts_as_pushable
+
+        apn_token_field = "device_token"
+        if respond_to?(:acts_as_push_options)
+            apn_token_field = acts_as_push_options[:device_token_field]
+        end
+
+        token = send(apn_token_field.to_sym)
+        raise "Cannot send push notification without device token" if !token || token.empty?
+        [token.delete(' ')].pack('H*')
+    end
+
+    def self.apple_json_array options
+        pp options
+
+        result = {}
+
+        result['aps'] = {}
+        result['aps']['alert'] = options[:alert].to_s if options[:alert]
+        result['aps']['badge'] = options[:badge].to_i if options[:badge]
+        result['aps']['sound'] = options[:sound] if options[:sound] and options[:sound].is_a? String
+        result['aps']['sound'] = 'default' if options[:sound] and options[:sound].is_a? TrueClass
+
+        if options[:extra]
+            options[:extra].keys.each do |key|
+                result[key.to_s] = options[:extra][key]
+            end
+        end
+
+        pp result        
+
+        result.to_json
+    end
+
+    def self.open_ssl_connection(host, port)
+        raise "Missing apple push notification certificate" unless @@apn_cert
+
+        ctx = OpenSSL::SSL::SSLContext.new
+        ctx.key = OpenSSL::PKey::RSA.new(@@apn_cert)
+        ctx.cert = OpenSSL::X509::Certificate.new(@@apn_cert)
+
+        @@s = TCPSocket.new(host, port)
+        @@ssl = OpenSSL::SSL::SSLSocket.new(@@s, ctx)
+        @@ssl.sync = true
+        puts "Opening connection..."
+        @@ssl.connect
+     rescue SocketError => error
+        @@s = nil
+        @@ssl = nil
+
+        raise "Error while opening ssl connection: #{error}"
+    end
+
+   def self.close_ssl_connection
+       puts "Closing connection..."
+
+       @@ssl.close
+       @@s.close
+
+       @@s = nil
+       @@ssl = nil
+   rescue SocketError => error
+       @@s = nil
+       @@ssl = nil
+
+       raise "Error while finishing sending notification session: #{error}"
+   end
+end
+
+require File.dirname(__FILE__) + "/matchbox20/acts_as_pushable"

data/matchbox20.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "matchbox20/version"
+
+Gem::Specification.new do |s|
+    s.name        = "matchbox20"
+
+    s.version     = Matchbox20::VERSION
+    s.platform    = Gem::Platform::RUBY
+
+    s.authors     = ["Jake Marsh", "Sam Soffes"]
+    s.email       = ["jake@thejakemarsh.com", "sam@soff.es"]
+    s.homepage    = "http://github.com/jakemarsh/matchbox20"
+    s.summary     = %q{Rails plugin for Apple Push Notifications}
+    s.description = %q{Rails plugin for Apple Push Notifications}
+
+    s.rubyforge_project = "matchbox20"
+
+    s.files         = `git ls-files`.split("\n")
+    s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+    s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+    s.require_paths = ["lib"]
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification 
+name: matchbox20
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 3
+  - 2
+  version: 0.3.2
+platform: ruby
+authors: 
+- Jake Marsh
+- Sam Soffes
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-01-17 00:00:00 -06:00
+default_executable: 
+dependencies: []
+
+description: Rails plugin for Apple Push Notifications
+email: 
+- jake@thejakemarsh.com
+- sam@soff.es
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- Rakefile
+- Readme.markdown
+- lib/matchbox20.rb
+- lib/matchbox20/acts_as_pushable.rb
+- lib/matchbox20/version.rb
+- matchbox20.gemspec
+has_rdoc: true
+homepage: http://github.com/jakemarsh/matchbox20
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: matchbox20
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Rails plugin for Apple Push Notifications
+test_files: []
+