added docs

Author: Carlos Alonso

Gemfile.lock

@@ -1,18 +1,18 @@
 PATH
   remote: .
   specs:
-    ruby-push-notifications (0.0.1)
+    ruby-push-notifications (0.1.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (4.2.0)
+    activesupport (4.2.1)
       i18n (~> 0.7)
       json (~> 1.7, >= 1.7.7)
       minitest (~> 5.1)
       thread_safe (~> 0.3, >= 0.3.4)
       tzinfo (~> 1.1)
-    addressable (2.3.7)
+    addressable (2.3.8)
     codeclimate-test-reporter (0.4.7)
       simplecov (>= 0.7.1, < 1.0.0)
     crack (0.4.2)
@@ -30,25 +30,25 @@ GEM
       rspec-core (~> 3.2.0)
       rspec-expectations (~> 3.2.0)
       rspec-mocks (~> 3.2.0)
-    rspec-core (3.2.0)
+    rspec-core (3.2.2)
       rspec-support (~> 3.2.0)
     rspec-expectations (3.2.0)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.2.0)
-    rspec-mocks (3.2.0)
+    rspec-mocks (3.2.1)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.2.0)
-    rspec-support (3.2.1)
+    rspec-support (3.2.2)
     safe_yaml (1.0.4)
     simplecov (0.9.2)
       docile (~> 1.1.0)
       multi_json (~> 1.0)
       simplecov-html (~> 0.9.0)
     simplecov-html (0.9.0)
-    thread_safe (0.3.4)
+    thread_safe (0.3.5)
     tzinfo (1.2.2)
       thread_safe (~> 0.1)
-    webmock (1.20.4)
+    webmock (1.21.0)
       addressable (>= 2.3.6)
       crack (>= 0.3.2)
 

lib/ruby-push-notifications.rb

@@ -1,8 +1,3 @@
-require "ruby-push-notifications/version"
-
-module RubyPushNotifications
-  # Your code goes here...
-end
-
+require 'ruby-push-notifications/version'
 require 'ruby-push-notifications/apns'
 require 'ruby-push-notifications/gcm'

lib/ruby-push-notifications/apns.rb

@@ -1,15 +1,40 @@
-
+#
+# @author Carlos Alonso
+#
 module RubyPushNotifications::APNS
+
+  # No Status Error Code. Represents a successfully sent notification
   NO_ERROR_STATUS_CODE = 0
+
+  # An error occurred while processing the notification
   PROCESSING_ERROR_STATUS_CODE = 1
+
+  # The notification contains no device token
   MISSING_DEVICE_TOKEN_STATUS_CODE = 2
-  MISSING_TOPIC_STATUS_CODE = 3 # You're writing to the TCPSocket rather than the SSL one
+
+  # The notification is being sent through the plain TCPSocket,
+  # rather than the SSL one
+  MISSING_TOPIC_STATUS_CODE = 3
+
+  # The notification contains no payload
   MISSING_PAYLOAD_STATUS_CODE = 4
+
+  # The given token sice is invalid (!= 32)
   INVALID_TOKEN_SIZE_STATUS_CODE = 5
+
+  # The given topic size is invalid
   INVALID_TOPIC_SIZE_STATUS_CODE = 6
+
+  # Payload size is invalid (256 bytes if iOS < 8, 2Kb otherwise)
   INVALID_PAYLOAD_SIZE_STATUS_CODE = 7
-  INVALID_TOKEN_STATUS_CODE = 8 # The token is for dev and the env is prod or viceversa, or simply wrong
+
+  # The token is for dev and the env is prod or viceversa, or simply wrong
+  INVALID_TOKEN_STATUS_CODE = 8
+
+  # Connection closed at Apple's end
   SHUTDOWN_STATUS_CODE = 10
+
+  # Unknown error
   UNKNOWN_ERROR_STATUS_CODE = 255
 end
 

lib/ruby-push-notifications/apns/apns_connection.rb

@@ -5,15 +5,28 @@
 
 module RubyPushNotifications
   module APNS
+    # This class encapsulates a connection with APNS.
+    #
+    # @author Carlos Alonso
     class APNSConnection
       extend Forwardable
 
+      # @private URL of the APNS Sandbox environment
       APNS_SANDBOX_URL = 'gateway.sandbox.push.apple.com'
+
+      # @private URL of APNS production environment
       APNS_PRODUCTION_URL = 'gateway.push.apple.com'
+
+      # @private Port to connect to
       APNS_PORT = 2195
 
       def_delegators :@sslsock, :write, :flush, :to_io, :read
 
+      # Opens a connection with APNS
+      #
+      # @param cert [String]. Contents of the PEM encoded certificate
+      # @param sandbox [Boolean]. Whether to use the sandbox environment or not.
+      # @return [APNSConnection]. The recently stablished connection.
       def self.open(cert, sandbox)
         ctx = OpenSSL::SSL::SSLContext.new
         ctx.key = OpenSSL::PKey::RSA.new cert
@@ -27,15 +40,25 @@ def self.open(cert, sandbox)
         new socket, ssl
       end
 
+      # Returns the URL to connect to.
+      #
+      # @param sandbox [Boolean]. Whether it is the sandbox or the production
+      #  environment we're looking for.
+      # @return [String]. The URL for the APNS service.
       def self.host(sandbox)
         sandbox ? APNS_SANDBOX_URL : APNS_PRODUCTION_URL
       end
 
+      # Initializes the APNSConnection
+      #
+      # @param tcpsock [TCPSocket]. The used TCP Socket.
+      # @param sslsock [SSLSocket]. The connected SSL Socket.
       def initialize(tcpsock, sslsock)
         @tcpsock = tcpsock
         @sslsock = sslsock
       end
 
+      # Closes the APNSConnection
       def close
         @sslsock.close
         @tcpsock.close

lib/ruby-push-notifications/apns/apns_notification.rb

@@ -3,57 +3,89 @@
 
 module RubyPushNotifications
   module APNS
+    # Represents a APNS Notification.
+    # Manages the conversion of the notification to APNS binary format for
+    # each of the destinations.
+    # By default sets maximum expiration date (4 weeks).
+    #
+    # @author Carlos Alonso
     class APNSNotification
 
-      WEEKS_4 = 2419200 # 4 weeks
+      # @private. 4 weeks in seconds
+      WEEKS_4 = 2419200
 
+      # @return [Array]. Array with the results from sending this notification
       attr_accessor :results
 
+      # Initializes the APNS Notification
+      #
+      # @param [Array]. Array containing all destinations for the notification
+      # @param [Hash]. Hash with the data to use as payload.
       def initialize(tokens, data)
         @tokens = tokens
         @data = data
       end
 
+      # Method that yields the notification's binary for each of the receivers.
+      #
+      # @param starting_id [Integer]. Every notification encodes a unique ID for
+      #   further reference. This parameter represents the first id the first
+      #   notification of this group should use.
+      # @yieldparam [String]. APNS binary's representation of this notification.
+      #   Consisting of:
+      #     Notification = 2(1), FrameLength(4), items(FrameLength)
+      #     Item = ItemID(1), ItemLength(2), data(ItemLength)
+      #     Items:
+      #       Device Token => Id: 1, length: 32, data: binary device token
+      #       Payload => Id: 2, length: ??, data: json formatted payload
+      #       Notification ID => Id: 3, length: 4, data: notif id as int
+      #       Expiration Date => Id: 4, length: 4, data: Unix timestamp as int
+      #       Priority => Id: 5, length: 1, data: 10 as 1 byte int
+      # (https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/CommunicatingWIthAPS.html#//apple_ref/doc/uid/TP40008194-CH101-SW4)
       def each_message(starting_id)
         @tokens.each_with_index do |token, i|
-          # Notification = 2(1), FrameLength(4), items(FrameLength)
-          # Item = ItemID(1), ItemLength(2), data(ItemLength)
-          # Items:
-          # Device Token => Id: 1, length: 32, data: binary device token
-          # Payload => Id: 2, length: ??, data: json formatted payload
-          # Notification ID => Id: 3, length: 4, data: notif id as int
-          # Expiration Date => Id: 4, length: 4, data: Unix timestamp as int
-          # Priority => Id: 5, length: 1, data: 10 as 1 byte int
           bytes = device_token(token) + payload + notification_id(starting_id + i) + expiration_date + priority
           yield [2, bytes.bytesize, bytes].pack 'cNa*'
         end
       end
 
+      # @return [Integer]. The number of binaries this notification will send.
+      #    One for each receiver.
       def count
         @tokens.count
       end
 
       private
 
+      # @param [String]. The device token to encode.
+      # @return [String]. Binary representation of the device token field.
       def device_token(token)
         [1, 32, token].pack 'cnH64'
       end
 
+      # Generates the APNS's binary representation of the notification's payload.
+      # Caches the value in an instance variable.
+      #
+      # @return [String]. Binary representation of the notification's payload.
       def payload
         @encoded_payload ||= -> {
             json = JSON.dump(@data).force_encoding 'ascii-8bit'
             [2, json.bytesize, json].pack 'cna*'
           }.call
       end
 
+      # @param [Integer]. The unique ID for this notification.
+      # @return [String]. Binary representation of the notification id field.
       def notification_id(id)
         [3, 4, id].pack 'cnN'
       end
 
+      # @return [String]. Binary representation of the expiration date field.
       def expiration_date
         [4, 4, (Time.now + WEEKS_4).to_i].pack 'cnN'
       end
 
+      # @return [String]. Binary representation of the priority field.
       def priority
         [5, 1, 10].pack 'cnc'
       end

lib/ruby-push-notifications/apns/apns_pusher.rb

@@ -1,13 +1,34 @@
 
 module RubyPushNotifications
   module APNS
+    # This class coordinates the process of sending notifications.
+    # It takes care of reopening closed APNSConnections and seeking back to
+    # the failed notification to keep writing.
+    #
+    # Remember that APNS doesn't confirm successful notification, it just
+    # notifies when one went wrong and closes the connection. Therefore, this
+    # APNSPusher reconnects and rewinds the array until the notification that
+    # Apple rejected.
+    #
+    # @author Carlos Alonso
     class APNSPusher
 
+      # @param certificate [String]. The PEM encoded APNS certificate.
+      # @param sandbox [Boolean]. Whether the certificate is an APNS sandbox or not.
       def initialize(certificate, sandbox)
         @certificate = certificate
         @sandbox = sandbox
       end
 
+      # Pushes the notifications.
+      # Builds an array with all the binaries (one for each notification and receiver)
+      # and pushes them sequentially to APNS monitoring the response.
+      # If an error is received, the connection is reopened and the process
+      # continues at the next notification after the failed one (pointed by the response error)
+      #
+      # For each notification assigns an array with the results of each submission.
+      #
+      # @param notifications [Array]. All the APNSNotifications to be sent.
       def push(notifications)
         conn = APNSConnection.open @certificate, @sandbox
 

lib/ruby-push-notifications/gcm/gcm_connection.rb

@@ -3,14 +3,31 @@
 
 module RubyPushNotifications
   module GCM
+    # Encapsulates a connection to the GCM service
+    # Responsible for final connection with the service.
+    #
+    # @author Carlos Alonso
     class GCMConnection
 
+      # @private The URL of the Android GCM endpoint
       GCM_URL = 'https://android.googleapis.com/gcm/send'
 
+      # @private Content-Type HTTP Header string
       CONTENT_TYPE_HEADER  = 'Content-Type'
+
+      # @private Application/JSON content type
       JSON_CONTENT_TYPE    = 'application/json'
+
+      # @private Authorization HTTP Header String
       AUTHORIZATION_HEADER = 'Authorization'
 
+      # Issues a POST request to the GCM send endpoint to
+      # submit the given notifications.
+      #
+      # @param notification [String]. The text to POST
+      # @param key [String]. The GCM sender id to use
+      #    (https://developer.android.com/google/gcm/gcm.html#senderid)
+      # @return [GCMResponse]. The GCMResponse that encapsulates the received response
       def self.post(notification, key)
         headers = {
             CONTENT_TYPE_HEADER => JSON_CONTENT_TYPE,

lib/ruby-push-notifications/gcm/gcm_error.rb

@@ -1,6 +1,9 @@
 
 module RubyPushNotifications
   module GCM
+    # Base class for all GCM related errors
+    #
+    # @author Carlos Alonso
     class GCMError < StandardError ; end
 
     class MalformedGCMJSONError < GCMError ; end

lib/ruby-push-notifications/gcm/gcm_notification.rb

@@ -1,15 +1,27 @@
 
 module RubyPushNotifications
   module GCM
+    # Encapsulates a GCM Notification.
+    # By default only Required fields are set.
+    # (https://developer.android.com/google/gcm/server-ref.html#send-downstream)
+    #
+    # @author Carlos Alonso
     class GCMNotification
 
+      # @return [Array]. Array with the results from sending this notification
       attr_accessor :results
 
+      # Initializes the notification
+      #
+      # @param [Array]. Array with the receiver's GCM registration ids.
+      # @param [Hash]. Payload to send.
       def initialize(registration_ids, data)
         @registration_ids = registration_ids
         @data = data
       end
 
+      # @return [String]. The GCM's JSON format for the payload to send.
+      #    (https://developer.android.com/google/gcm/server-ref.html#send-downstream)
       def as_gcm_json
         JSON.dump(
           registration_ids: @registration_ids,

lib/ruby-push-notifications/gcm/gcm_pusher.rb

@@ -1,12 +1,25 @@
 
 module RubyPushNotifications
   module GCM
+
+    # This class is responsible for sending notifications to the GCM service.
+    #
+    # @author Carlos Alonso
     class GCMPusher
 
+      # Initializes the GCMPusher
+      #
+      # @param key [String]. GCM sender id to use
+      #   ((https://developer.android.com/google/gcm/gcm.html#senderid))
       def initialize(key)
         @key = key
       end
 
+      # Actually pushes the given notifications.
+      # Assigns every notification an array with the result of each
+      # individual notification.
+      #
+      # @param notifications [Array]. Array of GCMNotification to send.
       def push(notifications)
         notifications.each do |notif|
           notif.results = GCMConnection.post notif.as_gcm_json, @key