pling 0.1.0 → 0.2.0

data/Gemfile

@@ -5,5 +5,6 @@ gemspec
 
 gem 'guard'
 gem 'guard-rspec'
+gem 'guard-yard', :platform => :ruby_19
 gem 'growl_notify' if RUBY_PLATFORM =~ /darwin/
 gem 'rdiscount', ">= 1.6.8", :platform => :ruby

data/Guardfile

@@ -2,3 +2,7 @@ guard 'rspec', :version => 2, :all_on_start => true, :all_after_pass => true do
   watch(%r{^spec/.+_spec\.rb$})
   watch(%r{^lib/(.+)\.rb$})                           { |m| "spec/#{m[1]}_spec.rb" }
 end
+
+guard 'yard' do
+  watch(%r{lib/.+\.rb})
+end

data/README.md

@@ -2,6 +2,7 @@
 
 Pling is a notification framework that supports multiple gateways. This gem implements the basic framework as well as a gateway to Google's Cloud to Device Messaging Service (C2DM) and Apple's Push Notification Service (APN).
 
+See the [API Documentation](http://rubydoc.info/github/flinc/pling/master/file/README.md) for more in depth documentation.
 
 ## Requirements
 
@@ -24,8 +25,8 @@ Add this line to your `Gemfile`:
 The configuration is pretty simple. Just add a configuration block like this to your code:
 
     Pling.configure do |config|
-      config.gateways.use Pling::Gateway::C2DM, :email => 'your-email@gmail.com', :password => 'your-password', :source => 'your-app-name'
-      config.gateways.use Pling::Gateway::APN, :certificate => '/path/to/certificate.pem'
+      config.gateways.use Pling::C2DM::Gateway, :email => 'your-email@gmail.com', :password => 'your-password', :source => 'your-app-name'
+      config.gateways.use Pling::APN::Gateway, :certificate => '/path/to/certificate.pem'
 
       # config.middleware.use Your::Custom::Middleware, :your => :custom, :configuration => true
 
@@ -40,7 +41,7 @@ After configuring Pling you can send messages to devices by like this:
     device  = Pling::Device.new(:identifier => 'XXXXXXXXXX...XXXXXX', :type => :iphone)
     device.deliver(message)
 
-    # ... or call Pling.delver
+    # ... or call Pling.deliver
     Pling.deliver(message, device)
 
 Pling has three core components:
@@ -77,12 +78,12 @@ The Gateway delivers the message in the required format to the service provider.
 
 Currently there are these gateways available:
 
-* [Android C2DM](http://rdoc.info/github/flinc/pling/master/Pling/Gateway/C2DM)
-* [Apple Push Notification](http://rdoc.info/github/flinc/pling/master/Pling/Gateway/APN)
+* [Android C2DM](http://rdoc.info/github/flinc/pling/master/Pling/C2DM/Gateway)
+* [Apple Push Notification](http://rdoc.info/github/flinc/pling/master/Pling/APN/Gateway)
 * [SMS via Mobilant](https://github.com/flinc/pling-mobilant) (See `pling-mobilant` gem)
 * [Email](https://github.com/flinc/pling-actionmailer) (See `pling-actionmailer` gem)
 
-See the [API documentation](http://rdoc.info/github/flinc/pling) for details on the available gateways.
+See the [API documentation](http://rubydoc.info/github/flinc/pling/master/file/README.md) for details on the available gateways.
 
 
 ### Middleware
@@ -106,7 +107,7 @@ Pling has support for middlewares. Currently pling itself does not provide any m
 You can either add middlewares for all gateways or for specific gateways:
 
     Pling.configure do |config|
-      config.gateways.use Pling::Gateway::APN, {
+      config.gateways.use Pling::APN::Gateway, {
         :certificate => '/path/to/certificate.pem',
         :middlewares => [
           [Pling::Middleware::TimeFilter, { :range => 9..17 }] # Don't deliver any messages to iOS devices between 9am and 5pm

data/lib/pling/adapter/base.rb

@@ -8,6 +8,8 @@ module Pling
       end
 
       def deliver(message, device)
+        Pling.logger.info "#{self.class} -- Delivering #{message.inspect} to #{device.inspect}"
+
         gateway = Pling::Gateway.discover(device)
         gateway.deliver(message, device)
       end

data/lib/pling/apn/connection.rb

@@ -0,0 +1,122 @@
+require 'openssl'
+
+module Pling
+  module APN
+    class Connection
+      include Pling::Configurable
+
+      def initialize(config)
+        setup_configuration(config, :require => [:certificate])
+        open
+      end
+
+      def open
+        Pling.logger.info "#{self.class} -- Opening connection in #{Process.pid}"
+        ssl_socket.connect
+
+        self
+      end
+
+      def reopen
+        close
+        open
+      end
+
+      def open?
+        not closed?
+      end
+
+      def close
+        Pling.logger.info "#{self.class} -- Closing connection in #{Process.pid}"
+        ssl_socket.close rescue true
+        tcp_socket.close rescue true
+
+        @ssl_socket = @tcp_socket = nil
+
+        self
+      end
+
+      def closed?
+        return true if ssl_socket.closed?
+        tcp_socket.read_nonblock(1)
+        return false
+      rescue Errno::EAGAIN
+        return false
+      rescue Exception => e
+        return !e.message.match(/read would block/)
+      end
+
+      def write(*args, &block)
+        with_retries do
+          raise IOError, "Connection closed" if closed?
+          ssl_socket.write(*args, &block)
+        end
+      end
+      
+      def puts(*args, &block)
+        with_retries do
+          raise IOError, "Connection closed" if closed?
+          ssl_socket.puts(*args, &block)
+        end
+      end
+
+      def read(*args, &block)
+        with_retries do
+          raise IOError, "Connection closed" if closed?
+          ssl_socket.read(*args, &block)
+        end
+      end
+      
+      def gets(*args, &block)
+        with_retries do
+          raise IOError, "Connection closed" if closed?
+          ssl_socket.gets(*args, &block)
+        end
+      end
+
+      protected
+
+        def ssl_context
+          @ssl_context ||= OpenSSL::SSL::SSLContext.new.tap do |context|
+            certificate  = File.read(configuration[:certificate])
+
+            context.cert = OpenSSL::X509::Certificate.new(certificate)
+            context.key  = OpenSSL::PKey::RSA.new(certificate)
+          end
+        end
+
+        def tcp_socket
+          @tcp_socket ||= TCPSocket.new(configuration[:host], configuration[:port]).tap do |tcp_socket|
+            tcp_socket.setsockopt(Socket::SOL_SOCKET,  Socket::SO_KEEPALIVE, true)
+            tcp_socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY,  true)
+          end
+        end
+
+        def ssl_socket
+          @ssl_socket ||= OpenSSL::SSL::SSLSocket.new(tcp_socket, ssl_context) do |ssl_socket|
+            ssl_socket.sync = true
+          end
+        end
+
+      private
+
+        def default_configuration
+          super.merge(
+            :host => 'gateway.push.apple.com',
+            :port => 2195
+          )
+        end
+
+        def with_retries(count = 3)
+          yield
+        rescue OpenSSL::SSL::SSLError, SocketError, SystemCallError, IOError
+          if (count -= 1) > 0
+            Pling.logger.info "#{self.class} -- #{$!.message}"
+            reopen; retry
+          else
+            raise IOError, $!.message
+          end
+        end
+    end
+  end
+end

data/lib/pling/apn/feedback.rb

@@ -0,0 +1,88 @@
+module Pling
+  module APN
+    
+    ##
+    # Instances of this class can be used to retrieve device identifiers that
+    # have been marked invalid. This should be done on a regular basis since
+    # Apple will ban you if you continue to send push notifications to
+    # invalid devices.
+    #
+    # The only operation supported by instances of this class is {#get}. 
+    # The method simply returns a list of the identifieres that have been 
+    # marked invalid since you last called this method.
+    #
+    # @example
+    #
+    #   feedback = Pling::APN::Feedback.new(:certificate => '/path/to/certificate.pem')
+    #   tokens = feedback.get
+    #
+    #   tokens.each do |token|
+    #     # process token
+    #   end
+    #
+    class Feedback
+      include Pling::Configurable
+      
+      ##
+      # Creates a new instance of this class and establishes a connection to
+      # Apple's Push Notification Service.
+      # 
+      # The connection is only established once since Apple will ban you if
+      # you reconnect each time you want to retrieve the list of invalid
+      # device identifiers. For testing purposes, you should use Apple's
+      # sandbox feedback service +feedback.sandbox.push.apple.com+. In order
+      # to do this, you have to specify the optional +:host+ parameter when
+      # creating instances of this class.
+      #
+      # @param [Hash] configuration Parameters to control the connection configuration
+      # @option configuration [#to_s] :certificate Path to PEM certificate file (Required)
+      # @option configuration [String] :host Host to connect to (Default: feedback.push.apple.com)
+      # @option configuration [Integer] :port Port to connect to (Default: 2196)
+      #
+      # @example
+      #
+      #   Pling::APN::Feedback.new(
+      #     :certificate => '/path/to/certificate.pem',
+      #     :host => 'feedback.push.apple.com',
+      #     :port => 2196
+      #   )
+      #
+      def initialize(configuration)
+        setup_configuration(configuration, :require => :certificate)
+      end
+      
+      ##
+      # Retrieves all device identifiers that have been marked invalid since
+      # the method has been called last.
+      #
+      # @return [Array<String>] The list of invalid device identifiers
+      #
+      def get
+        tokens = []
+        while line = connection.gets
+          time, length = line.unpack("Nn")
+          tokens << line.unpack("x6H#{length << 1}").first
+        end
+        tokens
+      end
+
+      private
+
+        def connection
+          @connection ||= Connection.new(
+            :host        => configuration[:host],
+            :port        => configuration[:port],
+            :certificate => configuration[:certificate]
+          )
+        end
+
+        def default_configuration
+          super.merge(
+            :host => 'feedback.push.apple.com',
+            :port => 2196
+          )
+        end
+
+    end
+  end
+end

data/lib/pling/{gateway/apn.rb → apn/gateway.rb}

@@ -3,21 +3,21 @@ require 'openssl'
 require 'json'
 
 module Pling
-  module Gateway
+  module APN
     ##
     # Pling gateway to communicate with Apple's Push Notification service.
     #
-    # This gateway handles these device types: 
+    # This gateway handles these device types:
     #     :apple, :apn, :ios, :ipad, :iphone, :ipod
     #
     # Configure it by providing the path to your certificate:
     #
-    #     Pling::Gateway::APN.new({
+    #     Pling::APN::Gateway.new({
     #       :certificate => '/path/to/certificate.pem', # Required
     #       :host => 'gateway.sandbox.push.apple.com'   # Optional
     #     })
     #
-    class APN < Base
+    class Gateway < Pling::Gateway
       handles :apple, :apn, :ios, :ipad, :iphone, :ipod
 
       ##
@@ -30,7 +30,13 @@ module Pling
       def initialize(configuration)
         super
         require_configuration(:certificate)
-        connection
+        setup!
+      end
+
+      ## 
+      # Establishes a new connection if connection is not available or closed
+      def setup!
+        connection.reopen if connection.closed?
       end
 
       ##
@@ -39,47 +45,48 @@ module Pling
       # @param [#to_pling_message] message
       # @param [#to_pling_device] device
       def deliver!(message, device)
-        token = [device.identifier].pack('H*')
-
         data = {
           :aps => {
-            :alert => message.body
-          }
-        }.to_json
+            :alert => message.body,
+            :badge => message.badge && message.badge.to_i,
+            :sound => message.sound
+          }.delete_if { |_, value| value.nil? }
+        }
 
-        raise Pling::DeliveryFailed, "Payload size of #{data.bytesize} exceeds allowed size of 256 bytes." if data.bytesize > 256
+        data.merge!(message.payload) if configuration[:payload] && message.payload
+
+        data = data.to_json
+
+        if data.bytesize > 256
+          raise Pling::DeliveryFailed.new(
+            "Payload size of #{data.bytesize} exceeds allowed size of 256 bytes.",
+            message,
+          device)
+        end
 
-        connection.write([0, 0, 32, token, 0, data.bytesize, data].pack('ccca*cca*'))
+        token = [device.identifier].pack('H*')
+
+        connection.write([0, token.bytesize, token, data.bytesize, data].pack('cna*na*'))
       end
 
       private
 
         def default_configuration
-          super.merge({
+          super.merge(
             :host => 'gateway.push.apple.com',
-            :port => 2195
-          })
+            :port => 2195,
+            :payload => false
+          )
         end
 
         def connection
-          @connection ||= OpenSSL::SSL::SSLSocket.new(tcp_socket, ssl_context).tap do |socket|
-            socket.sync = true
-            socket.connect
-          end
-        end
-
-        def ssl_context
-          @ssl_context ||= OpenSSL::SSL::SSLContext.new.tap do |context|
-            certificate  = File.read(configuration[:certificate])
-
-            context.cert = OpenSSL::X509::Certificate.new(certificate)
-            context.key  = OpenSSL::PKey::RSA.new(certificate)
-          end
+          @connection ||= Connection.new(
+            :host        => configuration[:host],
+            :port        => configuration[:port],
+            :certificate => configuration[:certificate]
+          )
         end
 
-        def tcp_socket
-          @tcp_socket ||= TCPSocket.new(configuration[:host], configuration[:port])
-        end
     end
   end
 end

data/lib/pling/apn.rb

@@ -0,0 +1,13 @@
+module Pling
+  
+  ##
+  # The {APN} module wraps Apple's Push Notification Service into an easy
+  # to use API. You can use instances of {Gateway} to send push notifications
+  # and instances of {Feedback} to get device identifiers that have been
+  # marked invalid.
+  module APN
+    autoload :Connection, 'pling/apn/connection'
+    autoload :Gateway, 'pling/apn/gateway'
+    autoload :Feedback, 'pling/apn/feedback'
+  end
+end

data/lib/pling/{gateway/c2dm.rb → c2dm/gateway.rb}

@@ -1,16 +1,16 @@
 require 'faraday'
 
 module Pling
-  module Gateway
+  module C2DM
     ##
     # Pling gateway to communicate with Google's Android C2DM service.
     #
     # The gateway is implemented using Faraday. It defaults to Faraday's :net_http adapter.
     # You can customize the adapter by passing the :adapter configuration.
     #
-    # Example:
+    # @example
     #
-    #   Pling::Gateway::C2DM.new({
+    #   Pling::C2DM::Gateway.new({
     #     :email    => 'your-email@gmail.com', # Your google account's email address (Required)
     #     :password => 'your-password',        # Your google account's password (Required)
     #     :source   => 'your-app-name',        # Your applications source identifier (Required)
@@ -20,7 +20,9 @@ module Pling
     #     :adapter            => :net_http,    # The Faraday adapter you want to use (Optional, Default: :net_http)
     #     :connection         => {}            # Options you want to pass to Faraday (Optional, Default: {})
     #   })
-    class C2DM < Base
+    class Gateway < Pling::Gateway
+
+      handles :android, :c2dm
 
       attr_reader :token
 
@@ -39,7 +41,11 @@ module Pling
       def initialize(configuration)
         super
         require_configuration([:email, :password, :source])
-        authenticate!
+        setup!
+      end
+
+      def setup!
+        authenticate! unless token
       end
 
       ##
@@ -49,14 +55,26 @@ module Pling
       # @param [#to_pling_device] device
       # @raise Pling::DeliveryFailed
       def deliver!(message, device)
-        response = connection.post(configuration[:push_url], {
+        data = {
           :registration_id => device.identifier,
-          :"data.body" => message.body,
+          :'data.body'  => message.body,
+          :'data.badge' => message.badge,
+          :'data.sound' => message.sound,
+          :'data.subject' => message.subject,
           :collapse_key => message.body.hash
-        }, { :Authorization => "GoogleLogin auth=#{@token}"})
+        }.delete_if { |_, value| value.nil? }
+
+        if configuration[:payload] && message.payload
+          message.payload.each do |key, value|
+            data["data.#{key}".to_sym] = value
+          end
+        end
+
+        response = connection.post(configuration[:push_url], data, { :Authorization => "GoogleLogin auth=#{@token}"})
 
         if !response.success? || response.body =~ /^Error=(.+)$/
-          raise(Pling::DeliveryFailed, "C2DM Delivery failed: [#{response.status}] #{response.body}")
+          error_class = Pling::C2DM.const_get($1) rescue Pling::DeliveryFailed
+          raise error_class.new("C2DM Delivery failed: [#{response.status}] #{response.body}", message, device)
         end
       end
 

data/lib/pling/c2dm.rb

@@ -0,0 +1,17 @@
+module Pling
+  ##
+  # This module adds support for Google's Cloud to Device Messaging (C2DM) to pling.
+  # Please refer to {Pling::C2DM::Gateway} for documentation.
+  #
+  # @see Pling::C2DM::Gateway
+  module C2DM
+    autoload :Gateway, 'pling/c2dm/gateway'
+
+    class QuotaExceeded       < Pling::DeliveryFailed; end
+    class DeviceQuotaExceeded < Pling::DeliveryFailed; end
+    class InvalidRegistration < Pling::DeliveryFailed; end
+    class NotRegistered       < Pling::DeliveryFailed; end
+    class MessageTooBig       < Pling::DeliveryFailed; end
+    class MissingCollapseKey  < Pling::DeliveryFailed; end
+  end
+end

data/lib/pling/delayed_initializer.rb

@@ -6,7 +6,9 @@ module Pling
 
     def initialize!
       map! do |item|
-        item.kind_of?(Array) ? item.shift.new(*item) : item
+        item = item.kind_of?(Array) ? item.shift.new(*item) : item
+        item.setup! if item.respond_to?(:setup!)
+        item
       end
     end 
   end

data/lib/pling/gateway.rb

@@ -1,10 +1,34 @@
 module Pling
-  module Gateway
-    autoload :Base, 'pling/gateway/base'
-    autoload :C2DM, 'pling/gateway/c2dm'
-    autoload :APN,  'pling/gateway/apn'
+  ##
+  # This is the base class of all gateways. It defines the public interface of 
+  # all gateways and provides helper methods to configure gateways and define
+  # the device types a gateway is able to handle.
+  #
+  # Gateway implementations must set the types they're able to handle by calling
+  # the {handles} macro.
+  #
+  # Every gateway must implement a {#deliver!} method which 
+  # does the actual delivering.
+  #
+  # @example
+  #
+  #     class Pling::Example::Gateway < Pling::Gateway
+  #       handles :example, :foo, :bar
+  #
+  #       def deliver!(message, device)
+  #         puts "Delivering #{message.body} to #{device.identifier} (#{device.type})"
+  #       end
+  #     end
+  class Gateway
+    include Pling::Configurable
 
     class << self
+      ##
+      # Finds a gateway that handles the given device
+      #
+      # @param device [#to_pling_device]
+      # @raise [Pling::NoGatewayFound] No gateway was found that is able to handle the given device
+      # @return [Pling::Gateway] A gateway that handles the given device
       def discover(device)
         device = Pling._convert(device, :device)
         Pling.gateways.initialize!
@@ -12,6 +36,98 @@ module Pling
           gateway.handles?(device)
         end or raise(Pling::NoGatewayFound, "Could not find a gateway for #{device.class} with type :#{device.type}")
       end
+
+      ##
+      # Defines the device types a gateway is able to handle
+      #
+      # @param types [Array<#to_sym>] List of types
+      # @return [Array<#to_sym>] List of types
+      def handles(*types)
+        @handled_types = [types].flatten.map { |t| t.to_sym }
+      end
+
+      ##
+      # Returns a list of device types that this gateway is able to handle
+      #
+      # @return [Array<#to_sym>] List of types
+      def handled_types
+        @handled_types ||= []
+      end
+    end
+
+    ##
+    # Initializes a new Gateway instance.
+    #
+    # @param [Hash] config Configuration for this gateway instance
+    # @option config [Array] :middlewares List of middlewares to execute before delivering
+    # @option config [#call(exception)] :on_exception Callback to execute when an exception is raised
+    def initialize(config = {})
+      setup_configuration(config)
+      middlewares = configuration[:middlewares]
+      configuration.merge!(:middlewares => Pling::DelayedInitializer.new)
+      middlewares.each { |middleware| configuration[:middlewares] << middleware } if middlewares
+    end
+
+    ##
+    # Sets up this gateway
+    def setup!
+    end
+
+    ##
+    # Tears down this gateway
+    def teardown!
+    end
+
+    ##
+    # Checks if this gateway is able to handle the given device
+    # @param device [#to_pling_device]
+    # @return [Boolean]
+    def handles?(device)
+      device  = Pling._convert(device,  :device)
+      self.class.handled_types.include?(device.type)
     end
+
+    ##
+    # Delivers the given message to the given device using the given stack.
+    # If the :on_exception callback is configured it'll rescue all Pling::Errors
+    # and pass them to the given callback.
+    #
+    # @param message [#to_pling_message]
+    # @param device [#to_pling_device]
+    # @param stack [Array] The stack to use (Default: configuration[:middlewares])
+    # @raise [Pling::DeliveryError] unless configuration[:on_exception] callback is set
+    def deliver(message, device, stack = nil)
+      message = Pling._convert(message, :message)
+      device  = Pling._convert(device,  :device)
+
+      stack ||= [] + configuration[:middlewares].initialize!
+
+      return deliver!(message, device) if stack.empty?
+
+      stack.shift.deliver(message, device) do |m, d|
+        deliver(m, d, stack)
+      end
+    rescue Pling::Error => error
+      callback = configuration[:on_exception]
+      callback && callback.respond_to?(:call) ? callback.call(error) : raise
+    end
+
+    ##
+    # Delivers the given message to the given device without using the middleware.
+    #
+    # @param message [#to_pling_message]
+    # @param device [#to_pling_device]
+    # @raise [Pling::NotImplementedError] This method must be implemented in subclasses
+    def deliver!(message, device)
+      raise NotImplementedError, "Please implement #{self.class}#deliver!(message, device)"
+    end
+
+    protected
+
+      def default_configuration
+        {
+          :middlewares => Pling::DelayedInitializer.new
+        }
+      end
   end
 end