Push0r 0.2.7 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fa717a28e1c056acef139e3284e60464dbfb09f0
-  data.tar.gz: 503739e4560048ba88389593c45d524c25a257cd
+  metadata.gz: ec063440562ff9633e4856679f911e047c69afb6
+  data.tar.gz: 1ecef9c128f4ac66a5a86af7d1301e51a6f709a1
 SHA512:
-  metadata.gz: 452648704f7ba045bd706a265ea2ca32d8682f3fe348de5c1aac4332acf4ad80324d842792a0a79699f09745d218058b678659cb5e05b9cd1d753ac74182e918
-  data.tar.gz: 8f4c71c6342ec73c567d0948093321f991e4e9f850c8487156580528267ba1b44f69995f9bd03ab18080c19c2e35655452048db127e71e0e51bad8888775d7a6
+  metadata.gz: e30bef2183bf8c659cb0489701de5a2175996de3599ebb91715d28bf8b9319ab02add199b4ea26dfb2463060b09990f4c8fc4e6c0a35d4ff6546c5609b460bc3
+  data.tar.gz: cbd6ae1c91f25ba19584107939dca1a1126ab57e815c366e9505992a93e4527fbef0e18c25ad14f8af6c18be0f1733e7c1c87dac44ffd92d2d588739e374d116

data/lib/push0r/APNS/ApnsPushMessage.rb

@@ -1,5 +1,11 @@
 module Push0r
+	# ApnsPushMessage is a {PushMessage} implementation that encapsulates a single push notification to be sent to a single user.
 	class ApnsPushMessage < PushMessage		
+		
+		# Returns a new ApnsPushMessage instance that encapsulates a single push notification to be sent to a single user.
+		# @param receiver_token [String] the apns push token (aka device token) to push the notification to
+		# @param identifier [Fixnum] a unique identifier to identify this push message during error handling. If nil, a random identifier is automatically generated.
+		# @param time_to_live [Fixnum] The time to live in seconds for this push messages. If nil, the time to live is set to zero seconds.
 		def initialize(receiver_token, identifier = nil, time_to_live = nil)
 			if identifier.nil? ## make sure the message has an identifier (required for apns error handling)
 				identifier = Random.rand(2**32)
@@ -7,6 +13,10 @@ module Push0r
 			super(receiver_token, identifier, time_to_live)
 		end
 		
+		# Convenience method to attach common data (that is an alert, a sound or a badge value) to this message's payload.
+		# @param alert_text [String] the alert text to be displayed
+		# @param sound [String] the sound to be played
+		# @param badge [Fixnum] the badge value to be displayed
 		def simple(alert_text = nil, sound = nil, badge = nil)
 			new_payload = {aps: {}}
 			if alert_text

data/lib/push0r/APNS/ApnsService.rb

@@ -1,6 +1,7 @@
 module Push0r
+
+	# A module that contains Apple Push Notification Service error codes
 	module ApnsErrorCodes
-		NO_ERROR 				= 0
 		PROCESSING_ERROR 		= 1
 		MISSING_DEVICE_TOKEN 	= 2
 		MISSING_TOPIC 			= 3
@@ -12,8 +13,18 @@ module Push0r
 		SHUTDOWN 				= 10
 		NONE 					= 255
 	end
-	
+
+	# ApnsService is a {Service} implementation to push notifications to iOS and OSX users using the Apple Push Notification Service.
+	# @example
+	#   queue = Push0r::Queue.new
+	#
+	#   apns_service = Push0r::ApnsService.new(File.read("aps.pem"), true)
+	#   queue.register_service(apns_service)
 	class ApnsService < Service
+
+		# Returns a new ApnsService instance
+		# @param certificate_data [String] the Apple push certificate in PEM format
+		# @param sandbox_environment [Boolean] true if the sandbox push server should be used, otherwise false
 		def initialize(certificate_data, sandbox_environment = false)
 			@certificate_data = certificate_data
 			@sandbox_environment = sandbox_environment
@@ -21,57 +32,61 @@ module Push0r
 			@sock = nil
 			@messages = []
 		end
-	
+
+		# @see Service#can_send?
 		def can_send?(message)
 			return message.is_a?(ApnsPushMessage)
 		end
-	
+
+		# @see Service#send
 		def send(message)
 			@messages << message
 		end
-		
+
+		# @see Service#init_push
 		def init_push
 			# not used for apns
 		end
-		
+
+		# @see Service#end_push
 		def end_push
 			failed_messages = []
 			begin
 				setup_ssl
 				(result, error_message, error_code) = transmit_messages
-				if result == false 
-					failed_messages << {:error_code => error_code, :message => error_message}
+				if result == false
+					failed_messages << FailedMessage.new(error_code, error_message.receiver_token, error_message)
 					reset_message(error_identifier)
 					if @messages.empty? then result = true end
 				end
 			end while result != true
-		
+
 			unless @ssl.nil?
 				@ssl.close
 			end
 			unless @sock.nil?
 				@sock.close
 			end
-			
+
 			@messages = [] ## reset
 			return [failed_messages, []]
 		end
-	
+
 		private
 		def setup_ssl
 			ctx = OpenSSL::SSL::SSLContext.new
-		
+
 			ctx.key = OpenSSL::PKey::RSA.new(@certificate_data, '')
 			ctx.cert = OpenSSL::X509::Certificate.new(@certificate_data)
-				
+
 			@sock = TCPSocket.new(@sandbox_environment ? "gateway.sandbox.push.apple.com" : "gateway.push.apple.com", 2195)
 			@ssl = OpenSSL::SSL::SSLSocket.new(@sock, ctx)
 			@ssl.connect
 		end
-		
+
 		def reset_message(error_identifier)
 			index = @messages.find_index {|o| o.identifier == error_identifier}
-			
+
 			if index.nil? ## this should never happen actually
 				@messages = []
 			elsif index < @messages.length - 1 # reset @messages to contain all messages after the one that has failed
@@ -80,61 +95,61 @@ module Push0r
 				@messages = []
 			end
 		end
-		
+
 		def create_push_frame(message)
 			receiver_token = message.receiver_token
 			payload = message.payload
 			identifier = message.identifier
 			time_to_live = (message.time_to_live.nil? || message.time_to_live.to_i < 0) ? 0 : message.time_to_live.to_i
-		
+
 			if receiver_token.nil? then raise(ArgumentError, "receiver_token is nil!") end
-			if payload.nil? then raise(ArgumentError, "payload is nil!") end	
-			
+			if payload.nil? then raise(ArgumentError, "payload is nil!") end
+
 			receiver_token = receiver_token.gsub(/\s+/, "")
-			if receiver_token.length != 64 then raise(ArgumentError, "invalid receiver_token length!") end			
-		
+			if receiver_token.length != 64 then raise(ArgumentError, "invalid receiver_token length!") end
+
 			devicetoken = [receiver_token].pack('H*')
 			devicetoken_length = [32].pack("n")
 			devicetoken_item = "\1#{devicetoken_length}#{devicetoken}"
-		
+
 			identifier = [identifier.to_i].pack("N")
 			identifier_length = [4].pack("n")
 			identifier_item = "\3#{identifier_length}#{identifier}"
-		
+
 			expiration_date = [(time_to_live > 0 ? Time.now.to_i + time_to_live : 0)].pack("N")
 			expiration_date_length = [4].pack("n")
 			expiration_item = "\4#{expiration_date_length}#{expiration_date}"
-		
+
 			priority = "\xA" ## default: high priority
 			if payload[:aps] && payload[:aps]["content-available"] && payload[:aps]["content-available"].to_i != 0 && (payload[:aps][:alert].nil? && payload[:aps][:sound].nil? && payload[:aps][:badge].nil?)
 				priority = "\5" ## lower priority for content-available pushes without alert/sound/badge
 			end
-		
+
 			priority_length = [1].pack("n")
 			priority_item = "\5#{priority_length}#{priority}"
-		
+
 			payload = payload.to_json.force_encoding("BINARY")
 			payload_length = [payload.bytesize].pack("n")
 			payload_item = "\2#{payload_length}#{payload}"
-		
+
 			frame_length = [devicetoken_item.bytesize + payload_item.bytesize + identifier_item.bytesize + expiration_item.bytesize + priority_item.bytesize].pack("N")
 			frame = "\2#{frame_length}#{devicetoken_item}#{payload_item}#{identifier_item}#{expiration_item}#{priority_item}"
-		
+
 			return frame
 		end
-		
+
 		def transmit_messages
 			if @messages.empty? || @ssl.nil?
 				return [true, nil, nil]
 			end
-			
+
 			pushdata = ""
 			@messages.each do |message|
 				pushdata << create_push_frame(message)
 			end
-			
+
 			@ssl.write(pushdata)
-		
+
 			if IO.select([@ssl], nil, nil, 2)
 				begin
 					read_buffer = @ssl.read(6)
@@ -153,7 +168,7 @@ module Push0r
 			end
 			return [true, nil, nil]
 		end
-		
+
 		def message_for_identifier(identifier)
 			index = @messages.find_index {|o| o.identifier == identifier}
 			if index.nil?
@@ -163,4 +178,4 @@ module Push0r
 			end
 		end
 	end
-end
+end

data/lib/push0r/FlushResult.rb

@@ -0,0 +1,48 @@
+module Push0r
+	# FlushResult models the result of a single {Queue} flushing process.
+	class FlushResult
+		attr_reader :failed_messages
+		attr_reader :new_token_messages
+		
+		def initialize(failed_message, new_token_messages)
+			@failed_messages = failed_message
+			@new_token_messages = new_token_messages
+		end
+		
+		def to_s
+			"FlushResult - Failed: #{@failed_messages.count} NewToken: #{@new_token_messages.count}"
+		end
+	end
+	
+	class FailedMessage
+		attr_reader :error_code
+		attr_reader :receivers
+		attr_reader :message
+		
+		def initialize(error_code, receivers, message)
+			@error_code = error_code
+			@receivers = receivers
+			@message = message
+		end
+		
+		def to_s
+			"FailedMessage: errorCode: #{@error_code} receivers: #{@receivers.inspect}"
+		end
+	end
+	
+	class NewTokenMessage
+		attr_reader :message
+		attr_reader :token
+		attr_reader :new_token
+		
+		def initialize(token, new_token, message)
+			@token = token
+			@new_token = new_token
+			@message = message
+		end
+		
+		def to_s
+			"NewTokenMessage: oldToken: #{@token} newToken: #{@new_token}"
+		end
+	end
+end

data/lib/push0r/GCM/GcmPushMessage.rb

@@ -1,5 +1,11 @@
 module Push0r
+	# GcmPushMessage is a {PushMessage} implementation that encapsulates a single push notification to be sent to a single or multiple users.
 	class GcmPushMessage < PushMessage
+		
+		# Returns a new GcmPushMessage instance that encapsulates a single push notification to be sent to a single or multiple users.
+		# @param receiver_token [Array<String>] the apns push tokens (aka registration ids) to push the notification to
+		# @param identifier [Fixnum] a unique identifier to identify this push message during error handling. If nil, a random identifier is automatically generated.
+		# @param time_to_live [Fixnum] The time to live in seconds for this push messages. If nil, the time to live is set to four weeks.
 		def initialize(receiver_token, identifier = nil, time_to_live = nil)
 			if identifier.nil? ## make sure the message has an identifier
 				identifier = Random.rand(2**32)

data/lib/push0r/GCM/GcmService.rb

@@ -1,12 +1,9 @@
 require 'net/http'
 
 module Push0r
-	
+
+	# A module that contains constants for Google Cloud Messaging error codes
 	module GcmErrorCodes
-		NO_ERROR 				= 0
-		UNABLE_TO_PARSE_JSON	= 400
-		NOT_AUTHENTICATED		= 401
-		INTERNAL_ERROR			= 500
 		UNKNOWN_ERROR			= 1
 		INVALID_REGISTRATION	= 2
 		UNAVAILABLE				= 3
@@ -18,30 +15,46 @@ module Push0r
 		INVALID_TTL				= 9
 		INVALID_PACKAGE_NAME	= 10
 		CONNECTION_ERROR		= 11
+		UNABLE_TO_PARSE_JSON	= 400
+		NOT_AUTHENTICATED		= 401
+		INTERNAL_ERROR			= 500
 	end
-	
+
+	# GcmService is a {Service} implementation to push notifications to Android users using the Google Cloud Messaging Service.
+	# @example
+	#   queue = Push0r::Queue.new
+	#
+	#   gcm_service = Push0r::GcmService.new("__gcm_api_token__")
+	#   queue.register_service(gcm_service)
 	class GcmService < Service
+
+		# Returns a new ApnsService instance
+		# @param api_key [String] the GCM API key obtained from the Google Developers Console
 		def initialize(api_key)
 			@api_key = api_key
 			@messages = []
 		end
-		
+
+		# @see Service#can_send?
 		def can_send?(message)
 			return message.is_a?(GcmPushMessage)
 		end
-		
+
+		# @see Service#send
 		def send(message)
 			@messages << message
 		end
-		
+
+		# @see Service#init_push
 		def init_push
 			## not used for gcm
 		end
-		
+
+		# @see Service#end_push
 		def end_push
 			failed_messages = []
 			new_registration_messages = []
-			
+
 			uri = URI.parse("https://android.googleapis.com/gcm/send")
 			http = Net::HTTP.new(uri.host, uri.port)
 			http.use_ssl = true
@@ -53,24 +66,24 @@ module Push0r
 					response = http.request(request)
 				rescue SocketError
 					## connection error
-					failed_messages << {:error_code => Push0r::GcmErrorCodes::CONNECTION_ERROR, :message => message, :receivers => message.receiver_token}
+					failed_messages << FailedMessage.new(Push0r::GcmErrorCodes::CONNECTION_ERROR, message.receiver_token, message)
 					next
 				end
-				
+
 				if response.code.to_i == 200
 					json = JSON.parse(response.body)
-					
+
 					if json["failure"].to_i > 0 || json["canonical_ids"].to_i > 0
 						error_receivers = {}
-						
+
 						json["results"].each_with_index do |result,i|
 							receiver_token = message.receiver_token[i]
 							error = result["error"]
 							message_id = result["message_id"]
 							registration_id = result["registration_id"]
-							
+
 							if message_id && registration_id
-								new_registration_messages << {:message => message, :receiver => receiver_token, :new_receiver => registration_id}
+								new_registration_messages << NewTokenMessage.new(receiver_token, registration_id, message)
 							elsif error
 								error_code = Push0r::GcmErrorCodes::UNKNOWN_ERROR
 								if error == "InvalidRegistration"
@@ -86,7 +99,7 @@ module Push0r
 								elsif error == "MessageTooBig"
 									error_code = Push0r::GcmErrorCodes::MESSAGE_TOO_BIG
 								elsif error == "InvalidDataKey"
-									error_code = Push0r::GcmErrorCodes::INVALID_DATA_KEY	
+									error_code = Push0r::GcmErrorCodes::INVALID_DATA_KEY
 								elsif error == "InvalidTtl"
 									error_code = Push0r::GcmErrorCodes::INVALID_TTL
 								elsif error == "InvalidPackageName"
@@ -96,21 +109,21 @@ module Push0r
 								error_receivers[error_code] << receiver_token
 							end
 						end
-						
+
 						## if there are any receivers with errors: add a hash for every distinct error code and the related receivers to the failed_messages array
 						error_receivers.each do |error_code, receivers|
-							failed_messages << {:error_code => error_code, :message => message, :receivers => receivers}
+							failed_messages << FailedMessage.new(error_code, receivers, message)
 						end
 					end
 				elsif response.code.to_i >= 500 && response.code.to_i <= 599
-					failed_messages << {:error_code => Push0r::GcmErrorCodes::INTERNAL_ERROR, :message => message, :receivers => message.receiver_token}
+					failed_messages << FailedMessage.new(Push0r::GcmErrorCodes::INTERNAL_ERROR, message.receiver_token, message)
 				else
-					failed_messages << {:error_code => response.code.to_i, :message => message, :receivers => message.receiver_token}
+					failed_messages << FailedMessage.new(response.code.to_i, message.receiver_token, message)
 				end
 			end
-				
-			@messages = [] ## reset	
+
+			@messages = [] ## reset
 			return [failed_messages, new_registration_messages]
 		end
 	end
-end
+end

data/lib/push0r/PushMessage.rb

@@ -1,14 +1,28 @@
 module Push0r
+	# PushMessage is the base class for all implemented push message types. A PushMessage encapsulates values like the notification's payload, its receiver, etc.
+	# @abstract
+	# @attr_reader [Hash] payload the payload for this push message
+	# @attr_reader [Fixnum] identifier the unique identifier for this push message
+	# @attr_reader [String, Array] receiver_token the receiver's push token
+	# @attr_reader [Fixnum] time_to_live the time to live in seconds for this push message
 	class PushMessage
 		attr_reader :payload, :identifier, :receiver_token, :time_to_live
-	
+
+		# Creates a new PushMessage instance
+		# @param receiver_token [String, Array] the receiver's push token. Some subclasses might also accept an Array of tokens.
+		# @param identifier [Fixnum] a unique identifier to identify this push message during error handling. If nil, a random identifier is automatically generated.
+		# @param time_to_live [Fixnum] The time to live in seconds for this push messages. If nil, the time to live depends on the service used to transmit the message.
 		def initialize(receiver_token, identifier = nil, time_to_live = nil)
 			@receiver_token = receiver_token
 			@identifier = identifier
 			@time_to_live = time_to_live
 			@payload = {}
 		end
-	
+
+		# Attaches the given payload to the push message.
+		# @note attaching is done using the merge! method of the Hash class, i.e. be careful not to overwrite previously set Hash keys.
+		# @param payload [Hash] the payload to attach to the message.
+		# @return [self] self
 		def attach(payload = {})
 			@payload.merge!(payload)
 			return self
@@ -17,4 +31,4 @@ module Push0r
 end
 
 require_relative 'APNS/ApnsPushMessage'
-require_relative 'GCM/GcmPushMessage'
+require_relative 'GCM/GcmPushMessage'

data/lib/push0r/Queue.rb

@@ -1,16 +1,46 @@
 module Push0r
+	
+	# A Queue is used to register services to be used to transmit PushMessages. Single PushMessages are then put into the queue and a call to the {#flush} method transmits all enqueued messages using the registered services.  In a sense, Queue is the class that ties all the other Push0r components together.
+	# @example
+	#   queue = Push0r::Queue.new
+	#
+	#   gcm_service = Push0r::GcmService.new("__gcm_api_token__")
+	#   queue.register_service(gcm_service)
+	#
+	#   apns_service = Push0r::ApnsService.new(File.read("aps.pem"), true)
+	#   queue.register_service(apns_service)
+	#
+	#   gcm_message = Push0r::GcmPushMessage.new("__registration_id__")
+	#   gcm_message.attach({"data" => {"d" => "1"}})
+	#
+	#   apns_message = Push0r::ApnsPushMessage.new("__device_token__")
+	#   apns_message.attach({"data" => {"v" => "1"}}
+	#
+	#   queue.add(gcm_message)
+	#   queue.add(apns_message)
+	#
+	#   queue.flush
 	class Queue
 		def initialize
 			@services = []
 			@queued_messages = {}
 		end
 	
+		# Registers a Service with the Queue
+		# @note Every service can only be registered once with the same queue
+		# @param service [Service] the service to be registered with the queue
+		# @return [void]
+		# @see Service
 		def register_service(service)
 			unless @services.include?(service)
 				@services << service
 			end
 		end
 	
+		# Adds a PushMessage to the queue
+		# @param message [PushMessage] the message to be added to the queue
+		# @return [Boolean] true if message was added to the queue (that is: if any of the registered services can handle the message), otherwise false
+		# @see PushMessage
 		def add(message)
 			@services.each do |service|
 				if service.can_send?(message)
@@ -24,21 +54,23 @@ module Push0r
 			return false
 		end
 	
+		# Flushes the queue by transmitting the enqueued messages using the registered services
+		# @return [FlushResult] the result of the operation
 		def flush
 			failed_messages = []
-			new_registration_messages = []
+			new_token_messages = []
 			
 			@queued_messages.each do |service, messages|
 				service.init_push
 				messages.each do |message|
 					service.send(message)
 				end
-				(failed, new_registration) = service.end_push
+				(failed, new_token) = service.end_push
 				failed_messages += failed
-				new_registration_messages += new_registration
+				new_token_messages += new_token
 			end
 			@queued_messages = {}
-			return [failed_messages, new_registration_messages]
+			return FlushResult.new(failed_messages, new_token_messages)
 		end
 	end
 end

data/lib/push0r/Service.rb

@@ -1,17 +1,46 @@
 module Push0r
+	module ErrorCodes
+		NO_ERROR = -1
+	end
+
+	# Service is the base class for all implemented push services. A Service encapsulates everything that is necessary to take a batch of push notifications and transmit it to the receivers.
+	# @abstract
 	class Service
+
+		# Called on the service every time a PushMessage is added to a Queue in order to determine whether it can send the given message.
+		# @param message [PushMessage] the message
+		# @return [Boolean] true if this service can send the given message, otherwise false
+		# @abstract
+		# @see PushMessage
+		# @see Queue
 		def can_send?(message)
 			return false
 		end
-	
+
+		# Sends a single push message. This is called during the flushing of a Queue for every enqueued PushMessage. The service may create its own internal queue in order to efficiently batch the messages.
+		# @param message [PushMessage] the message to be sent
+		# @return [void]
+		# @abstract
+		# @see PushMessage
+		# @see Queue
 		def send(message)
 			## empty
 		end
-	
+
+		# Called on the service during the flushing of a Queue before the first PushMessage is sent.
+		# @return [void]
+		# @abstract
+		# @see PushMessage
+		# @see Queue
 		def init_push
 			## empty
 		end
-	
+
+		# Called on the service during the flushing of a Queue after the last PushMessage has been sent. If the service manages its own internal queue, this is the place to actually transmit all messages.
+		# @return [Array(Array<String>, Array<String>)] Failed new RegId Messages
+		# @abstract
+		# @see PushMessage
+		# @see Queue
 		def end_push
 			## empty
 			return [[], []]
@@ -20,4 +49,4 @@ module Push0r
 end
 
 require_relative 'APNS/ApnsService'
-require_relative 'GCM/GcmService'
+require_relative 'GCM/GcmService'

data/lib/push0r.rb

@@ -2,6 +2,7 @@ require 'socket'
 require 'openssl'
 require 'json'
 
+require_relative 'push0r/FlushResult'
 require_relative 'push0r/Queue'
 require_relative 'push0r/Service'
-require_relative 'push0r/PushMessage'
+require_relative 'push0r/PushMessage'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: Push0r
 version: !ruby/object:Gem::Version
-  version: 0.2.7
+  version: 0.3.0
 platform: ruby
 authors:
 - Kai Straßmann
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-05-20 00:00:00.000000000 Z
+date: 2014-05-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -33,6 +33,7 @@ files:
 - lib/push0r.rb
 - lib/push0r/APNS/ApnsPushMessage.rb
 - lib/push0r/APNS/ApnsService.rb
+- lib/push0r/FlushResult.rb
 - lib/push0r/GCM/GcmPushMessage.rb
 - lib/push0r/GCM/GcmService.rb
 - lib/push0r/PushMessage.rb
@@ -63,3 +64,4 @@ signing_key:
 specification_version: 4
 summary: Push0r gem
 test_files: []
+has_rdoc: