gs-apns 0.2.0

data/.gitignore

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

data/Gemfile

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

data/MIT-LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2009 James Pozdena, 2010 Justin.tv, 2013 Geospike Pty Ltd
+ 
+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.textile

@@ -0,0 +1,158 @@
+h1. gs-apns
+
+gs-apns is a gem for accessing the Apple Push Notification Service that allows
+both sending notifications and reading from apple's feedback service. This gem
+is based heavily on the work of James Pozdena (http://github.com/jpoz/APNS) and
+"Paul Gebheim" (http://github.com/jpoz/APNS).
+
+Updates by William Denniss of Geospike: Apple's APNS service does not support JSON that isn't ascii encoded. Prior to rails 3.2.13
+it was encoded, but now it isn't.
+
+
+h2. Install
+
+<pre>
+sudo gem install jtv-apns
+</pre>
+
+h2. Setup:
+
+First, you will need to export your development/production iphone push service
+certificate and key from your keychain. To do this select the private key and
+certificate, and select File -> Export from your keychain. By default a .p12
+file will be generated containing certificate and key.
+
+Next, run the following command to convert this .p12 file into a .pem file.
+<pre>
+openssl pkcs12 -in cert.p12 -out cert.pem -nodes -clcerts
+</pre>
+
+This pem file should be stored somewhere secure that your application can access. Next, set the jtv-apns configuration parameters:
+
+<pre>
+###################
+# Hosts Config
+###################
+
+# Push Notification Service:
+#
+# (default: gateway.sandbox.push.apple.com is)
+# Set as below for a production install
+APNS.host = 'gateway.push.apple.com' 
+
+# (default: 2195)
+# APNS.port = 2195
+
+# Feedback Service:
+#
+# (default: feedback.sandbox.push.apple.com)
+APNS.feedback_host = 'feedback.push.apple.com'
+
+# (default: 2196)
+# APNS.feedback_port = 2196
+
+####################
+# Certificate Setup
+####################
+
+# Path to the .pem file created earlier
+APNS.pem  = '/path/to/pem/file'
+
+# Password for decrypting the .pem file, if one was used
+APNS.pass = 'xxxx'
+
+####################
+# Connection Mgmt
+####################
+
+# Cache open connections when sending push notifications
+# this will force the gem to keep 1 connection open per
+# host/port pair, and reuse it when sending notifications
+
+# (default: false)
+# APNS.cache_connections = true
+</pre>
+
+h2. Example (Single notification):
+
+Then to send a push notification you can either just send a string as the alert or give it a hash for the alert, badge and sound.
+
+<pre>
+device_token = '123abc456def'
+
+APNS.send_notification(device_token, 'Hello iPhone!')
+APNS.send_notification(device_token, :aps => {:alert => 'Hello iPhone!', :badge => 1, :sound => 'default'})
+</pre>
+
+h2. Example (Multiple notifications):
+
+You can also send multiple notifications using the same connection to Apple:
+
+<pre>
+device_token = '123abc456def'
+
+n1 = [device_token, :aps => { :alert => 'Hello...', :badge => 1, :sound => 'default' }
+n2 = [device_token, :aps => { :alert => '... iPhone!', :badge => 1, :sound => 'default' }]
+
+APNS.send_notifications([n1, n2])
+</pre>
+
+
+h2. Send other info along with aps
+
+Application-specific information can be included along with the alert by
+passing it along with the "aps" key in the message hash.
+
+<pre>
+APNS.send_notification(device_token, :aps => { :alert => 'Hello iPhone!', :badge => 1, :sound => 'default'},
+                                     :sent_by => 'Justin.tv')
+</pre>
+
+h2. Pre-establishing connections
+
+If connection caching is enabled, you can tell the gem to establish connections before sending any notifications.
+
+<pre>
+APNS.establish_notification_connection
+# ...
+if APNS.has_notification_connection?
+  APNS.send_notification(device_token, "It works!")
+end
+</pre>
+
+h2. Accessing the feedback service
+
+jtv-apns provides a simple api to access Apple's feedback service. Below is an example for setting the feedback time on an ActiveRecord object corresponding to a device token.
+
+<pre>
+# APNS.feedback_each returns an array of Hash objects with the following keys
+# :feedback_on => (Time) Time Apple considers app unregistered from device
+# :length => (Fixnum) Length of :device_token, currently always 32 (bytes)
+# :device_token => (String) hex-encoded device token
+APNS.feedback.each do |feedback|
+  d = RegisteredDevices.find(:first, :conditions => { :device_token = feedback.device_token })
+  unless d.nil?
+    d.feedback_on = feedback.feedback_on
+  end
+end
+</pre>
+
+h2. Getting your iPhone's device token
+
+After you setup push notification for your application with Apple. You need to ask Apple for you application specific device token.
+
+ApplicationAppDelegate.m
+<pre>
+- (void)applicationDidFinishLaunching:(UIApplication *)application {    
+    // Register with apple that this app will use push notification
+    [[UIApplication sharedApplication] registerForRemoteNotificationTypes:(UIRemoteNotificationTypeAlert | 
+      UIRemoteNotificationTypeSound | UIRemoteNotificationTypeBadge)];	
+}
+
+- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
+    // Show the device token obtained from apple to the log
+    NSLog(@"deviceToken: %@", deviceToken);
+}
+</pre>
+    
+

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/apns.gemspec

@@ -0,0 +1,20 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/apns/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["William Denniss", "Paul Gebheim", "James Pozdena"]
+  gem.email         = ["will@geospike.com"]
+  gem.description = %q{Simple Apple push notification service gem}
+  gem.summary = %q{Simple Apple push notification service gem}
+  gem.homepage = %q{http://github.com/WilliamDenniss/APNS}
+
+  gem.extra_rdoc_files = ["MIT-LICENSE"]
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "gs-apns"
+  gem.require_paths = ["lib"]
+  gem.version       = APNS::VERSION
+  
+  gem.add_development_dependency "rspec", "~> 2.6"
+end

data/lib/apns.rb

@@ -0,0 +1,27 @@
+# Copyright (c) 2009 James Pozdena, 2010 Justin.tv
+#  
+# 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.
+ 
+require 'apns/exceptions'
+require 'apns/apns_json'
+require 'apns/truncate'
+require 'apns/core'

data/lib/apns/apns_json.rb

@@ -0,0 +1,47 @@
+# Copyright (c) 2013 William Denniss
+#  
+# 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.
+
+module APNS
+  require 'json'
+
+    class ApnsJSON
+    
+      # generates JSON in a format acceptable to the APNS service (which is a subset of the JSON standard)
+      def self.apns_json(object)
+
+        JSON.generate(object, :ascii_only => false)
+      end
+
+      # calculates the byte-length of an object when encoded with APNS friendly JSON encoding
+      # if a string is passed, the byte-size is calculated as if it were in an object structure
+      def self.apns_json_size(object)
+
+        if object.is_a?(Hash) || object.is_a?(Array)
+          return apns_json(object).bytesize
+        else object.is_a?(String)
+          # wraps string in an array but discounts the extra chars
+          return apns_json([object]).bytesize - 4
+        end
+      end
+    end
+end

data/lib/apns/core.rb

@@ -0,0 +1,254 @@
+# Copyright (c) 2009 James Pozdena, 2010 Justin.tv, 2013 William Denniss
+#  
+# 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.
+ 
+module APNS
+  require 'socket'
+  require 'openssl'
+  
+  # Host for push notification service
+  # production: gateway.push.apple.com
+  # development: gateway.sandbox.apple.com
+  @host = 'gateway.sandbox.push.apple.com'
+  @port = 2195
+
+  # Host for feedback service
+  # production: feedback.push.apple.com
+  # development: feedback.sandbox.apple.com
+  @feedback_host = 'feedback.sandbox.push.apple.com'
+  @feedback_port = 2196
+
+  # openssl pkcs12 -in mycert.p12 -out client-cert.pem -nodes -clcerts
+  @pem = nil # this should be the path of the pem file not the contentes
+  @pass = nil
+
+  @cache_connections = false
+  @connections = {}
+
+  @truncate_mode = Truncate::TRUNCATE_METHOD_SOFT
+  @truncate_max_chopped = 10
+  @clean_whitespace = true
+  
+  @logging = true
+
+  class << self
+    attr_accessor :host, :port, :feedback_host, :feedback_port, :pem, :pass, :cache_connections, :clean_whitespace, :truncate_mode, :truncate_max_chopped, :logging
+  end
+
+  def self.establish_notification_connection
+    if @cache_connections
+      begin
+        self.get_connection(self.host, self.port)
+        return true
+      rescue
+      end
+    end
+    return false
+  end
+
+  def self.has_notification_connection?
+    return self.has_connection?(self.host, self.port)
+  end
+
+  def self.send_notification(device_token, message, notification_id = rand(9999), expiry = (Time.now + 1.year))
+    self.with_notification_connection do |conn|
+      conn.write(self.packaged_notification(device_token, message, notification_id, expiry))
+      conn.flush
+    end
+  end
+  
+  def self.send_notifications(notifications)
+    self.with_notification_connection do |conn|
+      notifications.each do |n|
+        conn.write(self.packaged_notification(n[0], n[1], (n[2] or rand(9999)), (n[3] or (Time.now + 1.year))))
+      end
+      conn.flush
+    end
+  end
+  
+  def self.feedback
+    apns_feedback = []
+    self.with_feedback_connection do |conn|
+      # Read buffers data from the OS, so it's probably not
+      # too inefficient to do the small reads
+      while data = conn.read(38)
+        apns_feedback << self.parse_feedback_tuple(data)
+      end
+    end
+    
+    return apns_feedback
+  end
+  
+  protected
+
+  # Each tuple is in the following format:
+  #
+  #              timestamp | token_length (32) | token
+  # bytes:  4 (big-endian)      2 (big-endian) | 32
+  #
+  # timestamp - seconds since the epoch, in UTC
+  # token_length - Always 32 for now
+  # token - 32 bytes of binary data specifying the device token
+  #
+  def self.parse_feedback_tuple(data)
+    feedback = data.unpack('N1n1H64')
+    {:feedback_at => Time.at(feedback[0]), :length => feedback[1], :device_token => feedback[2] }
+  end
+
+  def self.packaged_notification(device_token, message, identifier, expiry)
+    pt = self.packaged_token(device_token)
+    pm = self.packaged_message(message)
+    raise APNSException, "payload exceeds 256 byte limit" if pm.bytesize > 256
+
+    #return [0, 32, pt, pm.bytesize, pm].pack("cna*na*") # old format (NB. s> notation only compatible with ruby 1.9.3 and above)
+
+    expiry_unix = expiry.to_i
+    expiry_unix = 0 if expiry_unix < 0 # for APNS a zero timestamp has the same effect as a negative one and we are only encoding signed ints 
+    puts "[APNS] packaging notification for device:[#{device_token}] identifier:#{identifier} expiry:#{expiry_unix} payload-size:(#{pm.bytesize}) payload:#{pm}" if @logging
+    [1, identifier.to_i, expiry_unix, 32, pt, pm.bytesize, pm].pack("cNNna*na*")
+  end
+  
+  def self.packaged_token(device_token)
+    [device_token.gsub(/[\s|<|>]/,'')].pack('H*')
+  end
+  
+  def self.packaged_message(message)
+    if message.is_a?(Hash)
+      hash = message
+    elsif message.is_a?(String)
+      hash = {:aps => {:alert => message } }
+    else
+      raise "Message needs to be either a hash or string"
+    end
+    hash = Truncate.truncate_notification(hash, @clean_whitespace, @truncate_mode, @truncate_max_chopped)
+    ApnsJSON.apns_json(hash)
+  end
+  
+  def self.with_notification_connection(&block)
+    self.with_connection(self.host, self.port, &block)
+  end
+
+  def self.with_feedback_connection(&block)
+    # Explicitly disable the connection cache for feedback
+    cache_temp = @cache_connections
+    @cache_connections = false
+
+    self.with_connection(self.feedback_host, self.feedback_port, &block)
+
+  ensure
+    @cache_connections = cache_temp
+  end
+ 
+  private
+
+  def self.open_connection(host, port)
+    raise "The path to your pem file is not set. (APNS.pem = /path/to/cert.pem)" unless self.pem
+    raise "The path to your pem file does not exist!" unless File.exist?(self.pem)
+    
+    context      = OpenSSL::SSL::SSLContext.new
+    context.cert = OpenSSL::X509::Certificate.new(File.read(self.pem))
+    context.key  = OpenSSL::PKey::RSA.new(File.read(self.pem), self.pass)
+
+    retries = 0
+    begin
+      sock         = TCPSocket.new(host, port)
+      ssl          = OpenSSL::SSL::SSLSocket.new(sock, context)
+      ssl.connect
+      return ssl, sock
+    rescue SystemCallError
+      if (retries += 1) < 5
+        sleep 1
+        retry
+      else
+        # Too many retries, re-raise this exception
+        raise
+      end
+    end
+  end
+
+  def self.has_connection?(host, port)
+    @connections.has_key?([host,port])
+  end
+
+  def self.create_connection(host, port)
+    @connections[[host, port]] = self.open_connection(host, port)
+  end
+
+  def self.find_connection(host, port)
+    @connections[[host, port]]
+  end
+
+  def self.remove_connection(host, port)
+    if self.has_connection?(host, port)
+      ssl, sock = @connections.delete([host, port])
+      ssl.close
+      sock.close
+    end
+  end
+
+  def self.reconnect_connection(host, port)
+    self.remove_connection(host, port)
+    self.create_connection(host, port)
+  end
+
+  def self.get_connection(host, port)
+    if @cache_connections
+      # Create a new connection if we don't have one
+      unless self.has_connection?(host, port)
+        self.create_connection(host, port)
+      end
+
+      ssl, sock = self.find_connection(host, port)
+      # If we're closed, reconnect
+      if ssl.closed?
+        self.reconnect_connection(host, port)
+        self.find_connection(host, port)
+      else
+        return [ssl, sock]
+      end
+    else
+      self.open_connection(host, port)
+    end
+  end
+
+  def self.with_connection(host, port, &block)
+    retries = 0
+    begin
+      ssl, sock = self.get_connection(host, port)
+      yield ssl if block_given?
+
+      unless @cache_connections
+        ssl.close
+        sock.close
+      end
+    rescue Errno::ECONNABORTED, Errno::EPIPE, Errno::ECONNRESET
+      if (retries += 1) < 5
+        self.remove_connection(host, port)
+        retry
+      else
+        # too-many retries, re-raise
+        raise
+      end
+    end
+  end
+  
+end

data/lib/apns/exceptions.rb

@@ -0,0 +1,32 @@
+# Copyright (c) 2013 William Denniss
+#  
+# 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.
+module APNS
+
+  class APNSException < Exception
+  end
+
+  class TrucateException < APNSException
+  end
+
+
+end

data/lib/apns/truncate.rb

@@ -0,0 +1,106 @@
+# Copyright (c) 2013 William Denniss
+#  
+# 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.
+
+module APNS
+
+  class Truncate
+
+    TRUNCATE_METHOD_SOFT = 'soft'
+    TRUNCATE_METHOD_HARD = 'hard'
+  
+    NOTIFICATION_MAX_BYTE_SIZE = 256
+  
+    # forces a notification to fit within Apple's payload limits by truncating the message as required
+    def self.truncate_notification(notification, clean_whitespace = true, truncate_mode = TRUNCATE_METHOD_SOFT, truncate_soft_max_chopped = 10)
+      
+      raise ArgumentError, "notification is not a hash" unless notification.is_a?(Hash)
+      raise ArgumentError, "notification hash should contain :aps key" unless notification[:aps]
+      
+      return notification if !notification[:aps][:alert] || notification[:aps][:alert] == ""
+      
+      # cleans up whitespace
+      notification[:aps][:alert].gsub!(/([\s])+/, " ") if clean_whitespace
+                
+      # wd: trims the notification payload to fit in 255 bytes
+      if ApnsJSON.apns_json_size(notification) > NOTIFICATION_MAX_BYTE_SIZE
+
+        oversize_by = ApnsJSON.apns_json_size(notification) - NOTIFICATION_MAX_BYTE_SIZE
+        message_target_byte_size = ApnsJSON.apns_json_size(notification[:aps][:alert]) - oversize_by
+
+        if message_target_byte_size < 0
+          raise TrucateException, "notification does not fit within 256 byte limit even by if the message was completely truncated"
+        end
+        if message_target_byte_size == 0
+          raise TrucateException, "notification would only fit within 256 byte limit by completely truncating the message which changes the presentation in iOS"
+        end
+
+        notification[:aps][:alert] = truncate_string(notification[:aps][:alert], message_target_byte_size, truncate_mode, truncate_soft_max_chopped)
+      end
+      
+      return notification
+    end
+    
+    # truncates a string to a given byte size
+    def self.truncate_string(input_string, target_byte_size, truncate_mode = TRUNCATE_METHOD_SOFT, truncate_soft_max_chopped = 10, ellipsis = "\u2026", truncate_soft_regex = /\s/)
+
+      raise ArgumentError, "Cannot truncate string to a negative number" if target_byte_size < 0 
+      
+      return input_string if ApnsJSON.apns_json_size(input_string) <= target_byte_size
+      
+      # if the target size is below the size of the ellipsis, reverts to a hard-truncate with no ellipsis
+      if target_byte_size < ApnsJSON.apns_json_size(ellipsis)
+        truncate_mode = TRUNCATE_METHOD_HARD
+        ellipsis = ''
+      end
+
+      # reduces target-size by the ellipsis size
+      target_byte_size -= ApnsJSON.apns_json_size(ellipsis)
+
+      # starts with a string length equal to the target number bytes (which for an ASCII-only string is the final string)
+      string = input_string[0,target_byte_size]
+      
+      # chops off characters one at a time until the byte-size is within our target size, to handle variable-byte char strings
+      while ApnsJSON.apns_json_size(string) > target_byte_size
+        string = string[0,string.length-1]
+      end
+      
+      # further truncates string on whitespace boundaries
+      if truncate_mode == TRUNCATE_METHOD_SOFT
+      
+        string = input_string[0, string.length+1] # elongates string by 1 character in case it happens to be whitespace
+        trim_to_index = string.rindex(/\s/) # sets trim index to be last whitespace character
+        if !trim_to_index || (string.length - trim_to_index) > truncate_soft_max_chopped
+          trim_to_index = string.length-1 # cancels soft-truncate if no whitespace, or too much would be chopped
+        end
+        
+        string = string[0,trim_to_index]
+      end
+
+      string = '' if string.nil?  # if string is nil, it was entirely truncated
+      
+      return string + ellipsis
+    end
+    
+  end
+
+end

data/lib/apns/version.rb

@@ -0,0 +1,3 @@
+module APNS
+  VERSION = "0.2.0"
+end

data/spec/apns/core_spec.rb

@@ -0,0 +1,84 @@
+# Copyright (c) 2013 William Denniss
+#  
+# 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.
+
+require 'spec_helper'
+
+describe APNS do
+
+  it "should encode unicode to ascii-only json" do
+    string = "\u2601"
+    json = ApnsJSON.apns_json([string])
+    json.should == "[\"\u2601\"]"
+  end
+
+  it "should encode 5-byte unicode to JSON in an apple safe manner" do
+    string = "\u{1F511}"
+    json = ApnsJSON.apns_json([string])
+    json.should == "[\"\u{1F511}\"]"
+  end
+  
+  it "should return JSON escaped" do
+    n = {:aps => {:alert => "\u2601Hello iPhone", :badge => 3, :sound => 'awesome.caf'}}
+    json = ApnsJSON.apns_json(n)
+    json.should  == "{\"aps\":{\"alert\":\"\u2601Hello iPhone\",\"badge\":3,\"sound\":\"awesome.caf\"}}"
+  end
+  
+  it "should throw exception if payload is too big" do
+    # too big with alert
+    notification = {:aps => {:alert => "#{LONG_MESSAGE_QBF}#{LONG_MESSAGE_QBF}", :badge => '1', :sound => 'default'}, :server_info => {:type => 'example', :data => 12345, :something => LONG_MESSAGE_QBF, :again => LONG_MESSAGE_QBF}}
+    expect { APNS.packaged_notification("12345678901234567890123456789012",  notification, 1, Time.now + 14400) }.to raise_error(APNSException)
+  
+    # too big without alert
+    notification = notification = {:aps => {:badge => '1', :sound => 'default'}, :server_info => {:type => 'example', :data => 12345, :something => LONG_MESSAGE_QBF, :again => LONG_MESSAGE_QBF}}
+    expect { APNS.packaged_notification("12345678901234567890123456789012",  notification, 1, Time.now + 14400) }.to raise_error(APNSException)
+  end
+  
+  describe '#packaged_message' do
+
+    it "should return JSON with notification information" do
+      n = APNS.packaged_message({:aps => {:alert => 'Hello iPhone', :badge => 3, :sound => 'awesome.caf'}})
+      n.should  == "{\"aps\":{\"alert\":\"Hello iPhone\",\"badge\":3,\"sound\":\"awesome.caf\"}}"
+    end
+
+    it "should not include keys that are empty in the JSON" do
+      n = APNS.packaged_message({:aps => {:badge => 3}})
+      n.should == "{\"aps\":{\"badge\":3}}"
+    end
+
+  end
+
+  describe '#packaged_token' do
+    it "should package the token" do
+      n = APNS.packaged_token('<5b51030d d5bad758 fbad5004 bad35c31 e4e0f550 f77f20d4 f737bf8d 3d5524c6>')
+      Base64.encode64(n).should == "W1EDDdW611j7rVAEutNcMeTg9VD3fyDU9ze/jT1VJMY=\n"
+    end
+  end
+
+  describe '#packaged_notification' do
+    it "should package the notification" do
+      n = APNS.packaged_notification('device_token', {:aps => {:alert => 'Hello iPhone', :badge => 3, :sound => 'awesome.caf'}}, 1, 1367064263)
+      Base64.encode64(n).should == "AQAAAAFRe77HACDe8s79hOcAQHsiYXBzIjp7ImFsZXJ0IjoiSGVsbG8gaVBo\nb25lIiwiYmFkZ2UiOjMsInNvdW5kIjoiYXdlc29tZS5jYWYifX0=\n"
+    end
+  end
+   
+end

data/spec/apns/truncate_spec.rb

@@ -0,0 +1,180 @@
+# encoding: UTF-8
+
+# Copyright (c) 2013 William Denniss
+#  
+# 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.
+
+require 'spec_helper'
+
+include APNS
+
+describe APNS::Truncate do
+  
+  STRING_1TO9 = "123456789"
+  STRING_QBF = "the quick brown fox jumps over the lazy dog"
+  STRING_CHINESE = "中国上海北京南京西安东京水茶可乐咖啡"
+  ELLIPSIS = "\u2026"
+  LONG_MESSAGE_QBF = "#{STRING_QBF}#{STRING_QBF}#{STRING_QBF}#{STRING_QBF}#{STRING_QBF}#{STRING_QBF}#{STRING_QBF}#{STRING_QBF}#{STRING_QBF}"
+  LONG_MESSAGE_CHINESE = "#{STRING_CHINESE}#{STRING_CHINESE}#{STRING_CHINESE}#{STRING_CHINESE}"
+  
+  describe '#json_byte_length' do
+    it "should return the correct ascii-json byte size" do
+      # string sizes
+      ApnsJSON.apns_json_size("1").should == 1
+      ApnsJSON.apns_json_size("12").should == 2
+      ApnsJSON.apns_json_size("\u2026").should == 3
+      ApnsJSON.apns_json_size("\u{1F511}").should == 4
+
+      # object sizes
+      ApnsJSON.apns_json_size(["1"]).should == 1+4
+      ApnsJSON.apns_json_size(["12"]).should == 2+4
+      ApnsJSON.apns_json_size(["\u2026"]).should == 3+4
+      ApnsJSON.apns_json_size(["\u{1F511}"]).should == 4+4
+    end
+  end
+  
+  describe '#truncate_string' do
+
+    it "should handle byte-sizes smaller than the ellipsis size" do
+      s = Truncate.truncate_string(STRING_1TO9, 2)
+      s.should == "12"
+    end
+
+    it "should handle byte-sizes equal to the ellipsis size" do
+      s = Truncate.truncate_string(STRING_1TO9, ApnsJSON.apns_json_size(ELLIPSIS))
+      s.should == ELLIPSIS
+      
+      s = Truncate.truncate_string(STRING_CHINESE, ApnsJSON.apns_json_size(ELLIPSIS))
+      s.should == ELLIPSIS
+    end
+
+    it "should handle byte-sizes euqal to the ellipsis size+1" do
+      s = Truncate.truncate_string(STRING_1TO9, ApnsJSON.apns_json_size(ELLIPSIS)+1)
+      s.should == "1#{ELLIPSIS}"
+
+      s = Truncate.truncate_string(STRING_CHINESE, ApnsJSON.apns_json_size(ELLIPSIS)+1)
+      s.should == ELLIPSIS
+    end
+
+    it "should soft truncate stirngs to equal or below requested size #2" do
+    
+      s = Truncate.truncate_string(STRING_QBF, 8)
+      s.bytesize.should <= 8
+
+      s = Truncate.truncate_string(STRING_CHINESE, 8)
+      s.bytesize.should <= 8
+
+      s = Truncate.truncate_string(STRING_QBF, 35)
+      s.bytesize.should <= 35
+
+      s = Truncate.truncate_string(STRING_CHINESE, 35)
+      s.bytesize.should <= 35
+    end
+    
+    it "should hard-truncate to the exact str length" do
+      s = Truncate.truncate_string(STRING_QBF, 8, Truncate::TRUNCATE_METHOD_HARD, 0, '.')
+      s.bytesize.should == 8
+    end
+
+    it "should soft-truncate on word boundaries" do
+      s = Truncate.truncate_string(STRING_QBF, 9, Truncate::TRUNCATE_METHOD_SOFT, 10, '.')
+      s.should == "the."
+    end
+
+    it "shouldn't soft-truncate any more than needed (even if the space lies on the boundary)" do
+      s = Truncate.truncate_string(STRING_QBF, 10, Truncate::TRUNCATE_METHOD_SOFT, 10, '.')
+      s.should == "the quick."
+    end
+
+    it "soft truncate should handle strings with no spaces by reverting to hard-truncate" do
+      s = Truncate.truncate_string(STRING_1TO9, 8, Truncate::TRUNCATE_METHOD_SOFT, 10, '.')
+      s.bytesize.should == 8
+    end
+
+    it "soft truncate should handle unicode strings" do
+      s = Truncate.truncate_string(STRING_CHINESE, 20)
+      s.should_not == nil
+    end
+
+    it "should handle scripts that don't use whitespace and not soft-truncate more than needed" do
+      # soft truncate relies on spaces. Some scripts have no spaces and shouldn't be aversely truncated
+      soft = Truncate.truncate_string(STRING_CHINESE, 40, Truncate::TRUNCATE_METHOD_SOFT)
+      hard = Truncate.truncate_string(STRING_CHINESE, 40, Truncate::TRUNCATE_METHOD_HARD)
+      soft.should == hard
+    end
+  
+    it "shouldn't truncate stirngs it doesn't need to" do
+      s = APNS::Truncate.truncate_string("123456789", 20)
+      s.should == "123456789"
+
+      s = APNS::Truncate.truncate_string("123456789", 9)
+      s.should == "123456789"
+      
+      s = APNS::Truncate.truncate_string(STRING_CHINESE, 200)
+      s.should == STRING_CHINESE
+    end
+    
+  end
+  
+  describe '#truncate_notification' do
+    
+    it "should truncate notification to size" do
+      notification = {:aps => {:alert => LONG_MESSAGE_QBF, :badge => '1', :sound => 'default'}, :server_info => {:type => 'example', :data => 12345, :something => 'blar'}}
+      Truncate.truncate_notification(notification)
+      ApnsJSON.apns_json(notification).bytesize.should <= 256
+
+      notification = {:aps => {:alert => LONG_MESSAGE_CHINESE, :badge => '1', :sound => 'default'}, :server_info => {:type => 'example', :data => 12345, :something => 'blar'}}
+      Truncate.truncate_notification(notification)
+      ApnsJSON.apns_json(notification).bytesize.should <= 256
+     
+      notification = {:aps => {:alert => LONG_MESSAGE_QBF, :badge => '1', :sound => 'default'}, :server_info => {:type => 'example', :data => 12345, :something => 'blar'}}
+      Truncate.truncate_notification(notification, true, truncate_mode = Truncate::TRUNCATE_METHOD_HARD)
+      ApnsJSON.apns_json(notification).bytesize.should == 256
+    end
+    
+    it "should throw exception if the notification cannot be truncated" do
+    
+      notification = {:aps => {:alert => LONG_MESSAGE_QBF, :badge => '1', :sound => 'default'}, :server_info => {:type => 'example', :data => 12345, :something => LONG_MESSAGE_QBF, :again => LONG_MESSAGE_QBF}}
+      expect { Truncate.truncate_notification(notification) }.to raise_error
+    end
+
+    it "should throw exception if the notification structure is invalid" do
+    
+      notification = {:alert => LONG_MESSAGE_QBF, :badge => '1', :sound => 'default'}
+      expect { Truncate.truncate_notification(notification) }.to raise_error (ArgumentError)
+      
+      notification = [1,2,3]
+      expect { Truncate.truncate_notification(notification) }.to raise_error (ArgumentError)
+
+      
+    end
+
+
+    it "shouldn't truncate notification unless needed" do
+      notification = {:aps => {:alert => STRING_QBF, :badge => '1', :sound => 'default'}, :server_info => {:type => 'example', :data => 12345, :something => 'blar'}}
+      Truncate.truncate_notification(notification)
+      notification[:aps][:alert].should == STRING_QBF
+    end
+
+  end
+  
+end

data/spec/spec_helper.rb

@@ -0,0 +1,2 @@
+require 'apns'
+require 'base64'

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: gs-apns
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+  prerelease: 
+platform: ruby
+authors:
+- William Denniss
+- Paul Gebheim
+- James Pozdena
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-04-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.6'
+description: Simple Apple push notification service gem
+email:
+- will@geospike.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- MIT-LICENSE
+files:
+- .gitignore
+- Gemfile
+- MIT-LICENSE
+- README.textile
+- Rakefile
+- apns.gemspec
+- lib/apns.rb
+- lib/apns/apns_json.rb
+- lib/apns/core.rb
+- lib/apns/exceptions.rb
+- lib/apns/truncate.rb
+- lib/apns/version.rb
+- spec/apns/core_spec.rb
+- spec/apns/truncate_spec.rb
+- spec/spec_helper.rb
+homepage: http://github.com/WilliamDenniss/APNS
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.21
+signing_key: 
+specification_version: 3
+summary: Simple Apple push notification service gem
+test_files:
+- spec/apns/core_spec.rb
+- spec/apns/truncate_spec.rb
+- spec/spec_helper.rb