pling 0.0.1 → 0.1.0

data/.gitignore

@@ -1,5 +1,8 @@
 *.gem
 .bundle
 .rspec
+.rvmrc
+.yardoc/
+doc/
 Gemfile.lock
 pkg/*

data/Gemfile

@@ -3,4 +3,7 @@ source 'http://rubygems.org'
 # Specify your gem's dependencies in pling.gemspec
 gemspec
 
-gem 'guard'
+gem 'guard'
+gem 'guard-rspec'
+gem 'growl_notify' if RUBY_PLATFORM =~ /darwin/
+gem 'rdiscount', ">= 1.6.8", :platform => :ruby

data/Guardfile

@@ -0,0 +1,4 @@
+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

data/README.md

@@ -1,10 +1,16 @@
-# Pling ![Travis build status of pling](http://travis-ci.org/flinc/pling.png)
+# Pling [![Travis build status of pling](http://travis-ci.org/flinc/pling.png)](http://travis-ci.org/flinc/pling)
 
-Pling is a notification framework that supports multiple gateways.
+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).
 
 
 ## Requirements
 
+This gem has two runtime dependencies
+
+- faraday ~> 0.7
+- json ~> 1.4
+
+On JRuby it also requires the jruby-openssl gem.
 
 
 ## Install
@@ -15,27 +21,39 @@ Add this line to your `Gemfile`:
 
 ## Configuration
 
+The configuration is pretty simple. Just add a configuration block like this to your code:
+
     Pling.configure do |config|
-      config.gateways = [
-        Pling::Gateways::C2DM.new(:options => 'here'),
-        Pling::Gateways::IPhone.new(:options => 'here'),
-        Pling::Gateways::Email.new(:options => 'here')
-      ]
+      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.middleware.use Your::Custom::Middleware, :your => :custom, :configuration => true
+
+      # config.adapter = Your::Custom::Adapter.new
     end
 
 ## Usage
 
+After configuring Pling you can send messages to devices by like this:
+
+    message = Pling::Message.new("Hello from pling!")
+    device  = Pling::Device.new(:identifier => 'XXXXXXXXXX...XXXXXX', :type => :iphone)
+    device.deliver(message)
+
+    # ... or call Pling.delver
+    Pling.deliver(message, device)
+
 Pling has three core components:
 
-* A `Device` describes a concrete receiver such as a smartphone or an email address. 
-* A `Message` wraps the content delivered to a device. 
-* A `Gateway` handles the communication with the service provider used to deliver the message.
+* A _device_ describes a concrete receiver such as a smartphone or an email address. 
+* A _message_ wraps the content delivered to a device. 
+* A _gateway_ handles the communication with the service provider used to deliver the message.
 
-To integrate Pling in your application you have to implement a `to_pling` method on each of your models to convert your data into Pling compatible objects.
+You can easily integrate pling into your existing application by implementing `#to_pling_device` on your device models and `#to_pling_message` on your message models. Use these methods to either convert your models into `Pling::Device` and `Pling::Message` objects or return `self` and make sure your models implement the basic `Pling::Device` and `Pling::Message` interfaces.
 
 ### Devices
 
-Devices store an identifier and a type. 
+Devices store an identifier and a type.
 
   Example:
 
@@ -59,31 +77,74 @@ The Gateway delivers the message in the required format to the service provider.
 
 Currently there are these gateways available:
 
-* Android C2DM (not yet implemented)
-* iPhone Push (not yet implemented)
-* SMS via Mobilant (See `pling-mobilant` gem, not yet implemented)
-* E-Mail (See `pling-actionmailer` gem, not yet implemented)
+* [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)
+* [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.
+
+
+### Middleware
+
+Pling has support for middlewares. Currently pling itself does not provide any middlewares but you can easily implement your own. All you need is a class that responds to `#deliver(message, device)` which yields to call the next middleware on the stack. You might just want to subclass `Pling::Middleware::Base` to get a simple configuration management. 
+
+    class Pling::Middleware::TimeFilter < Pling::Middleware::Base
+      def deliver(message, device)
+        yield(message, device) if configuration[:range].include? Time.now.hour
+      end
+
+      protected
+
+        def default_configuration
+          super.merge({
+            :range => 8..22
+          })
+        end
+    end
+
+You can either add middlewares for all gateways or for specific gateways:
+
+    Pling.configure do |config|
+      config.gateways.use Pling::Gateway::APN, {
+        :certificate => '/path/to/certificate.pem',
+        :middlewares => [
+          [Pling::Middleware::TimeFilter, { :range => 9..17 }] # Don't deliver any messages to iOS devices between 9am and 5pm
+        ]
+      }
+
+      # Don't deliver any messages between 8am and 10pm
+      config.middleware.use Pling::Middleware::TimeFilter
+    end
+
+
+### Adapters
+
+Pling supports different adapters. A adapter is in a way similar to a middleware but is responsible for dispatching a device and a message to a gateway.
+The default adapter simply looks up the first matching gateway for the given device and calls its `#deliver(message, device)` method. Adapters are handy
+when you want to add support for background queues. Have a look at [this example](https://gist.github.com/1308846) of an adapter for Resque.
+
 
 ## Build Status
 
-Pling is on [Travis](http://travis-ci.org/flinc/pling) running the specs on Ruby 1.8.7, Ruby 1.9.2 and Ruby Enterprise Edition.
+Pling is on [Travis](http://travis-ci.org/flinc/pling) running the specs on Ruby 1.8.7, Ruby Enterprise Edition, Ruby 1.9.2, Ruby HEAD, JRuby, Rubinius and Rubinius 2.
 
 
 ## Known issues
 
-See https://github.com/flinc/pling/issues
+See [the issue tracker on GitHub](https://github.com/flinc/pling/issues).
 
 
 ## Repository
 
-See https://github.com/flinc/pling and feel free to fork it!
+See [the repository on GitHub](https://github.com/flinc/pling) and feel free to fork it!
 
 
 ## Contributors
 
-See a list of all contributors at https://github.com/flinc/pling/contributors. Thanks a lot everyone!
+See a list of all contributors on [GitHub](https://github.com/flinc/pling/contributors). Thanks a lot everyone!
 
 
 ## Copyright
 
-Copyright (c) 2010-2011 flinc AG. See LICENSE for details.
+Copyright (c) 2010-2011 [flinc AG](https://flinc.org/). See LICENSE for details.

data/Rakefile

@@ -1,10 +1,15 @@
 require 'bundler/gem_tasks'
 
 require 'rspec/core/rake_task'
-require 'yard/rake/yardoc_task'
+require 'yard'
 
 RSpec::Core::RakeTask.new(:spec)
 
 YARD::Rake::YardocTask.new(:doc)
 
 task :default => :spec
+
+desc "Open an irb session"
+task :console do
+  sh "irb -rubygems -I lib -r pling.rb"
+end

data/lib/pling.rb

@@ -1,5 +1,90 @@
 require "pling/version"
 
 module Pling
-  # Your code goes here...
+
+  autoload :Device,       'pling/device'
+  autoload :Message,      'pling/message'
+  autoload :Gateway,      'pling/gateway'
+  autoload :Middleware,   'pling/middleware'
+  autoload :Adapter,      'pling/adapter'
+  autoload :Configurable, 'pling/configurable'
+  autoload :DelayedInitializer,    'pling/delayed_initializer'
+
+  @gateways = Pling::DelayedInitializer.new
+  @middlewares = Pling::DelayedInitializer.new
+  @adapter = Pling::Adapter::Base.new
+
+  class Error < StandardError; end
+  class AuthenticationFailed < Error; end
+  class DeliveryFailed < Error; end
+  class NoGatewayFound < Error; end
+
+  class << self
+    ##
+    # Stores the list of available gateway instances
+    #
+    # @return [Array] list of available gateways
+    attr_reader :gateways
+
+    def gateways=(gateways)
+      gateways.each { |gateway| @gateways << gateway }
+    end
+
+    ##
+    # Stores the list of avaiable middleware instances
+    #
+    # @return [Array] list of available middleware
+    attr_reader :middlewares
+
+    def middlewares=(middlewares)
+      middlewares.each { |middleware| @middlewares << middleware }
+    end
+
+    ##
+    # Stores the adapter
+    #
+    # @return [Pling::Adapter]
+    attr_accessor :adapter
+
+    ##
+    # Allows configuration of Pling by passing a config object to the given block
+    #
+    # @yield [config]
+    # @raise [ArgumentError] Raised when no block is given
+    def configure
+      raise ArgumentError, 'No block given for Pling.configure' unless block_given?
+      yield self
+    end
+
+    ##
+    # Delivers the given message to the given device using the given stack.
+    #
+    # @param message [#to_pling_message]
+    # @param device [#to_pling_device]
+    # @param stack [Array] The stack to use (Default: middlewares + [adapter])
+    def deliver(message, device, stack = nil)
+      message = Pling._convert(message, :message)
+      device  = Pling._convert(device, :device)
+
+      stack ||= middlewares.initialize! + [adapter]
+
+      stack.shift.deliver(message, device) do |m, d|
+        deliver(m, d, stack)
+      end
+    end
+
+    ##
+    # [INTERNAL METHOD] Converts the given object to the given pling type
+    #
+    # @private
+    # @param object [Object] The object that needs to be converted
+    # @param type [Symbol, String] #to_pling_ method suffix
+    # @raise [ArgumentError] The object does not implement a #to_pling_ + type method
+    def _convert(object, type)
+      method = :"to_pling_#{type}"
+      raise ArgumentError, "Instances of #{object.class} do not implement ##{method}" unless object.respond_to?(method)
+      object && object.send(method)
+    end
+  end
+
 end

data/lib/pling/adapter.rb

@@ -0,0 +1,5 @@
+module Pling
+  module Adapter
+    autoload :Base,   'pling/adapter/base'
+  end
+end

data/lib/pling/adapter/base.rb

@@ -0,0 +1,17 @@
+module Pling
+  module Adapter
+    class Base
+      include Pling::Configurable
+
+      def initialize(configuration = {})
+        setup_configuration(configuration)
+      end
+
+      def deliver(message, device)
+        gateway = Pling::Gateway.discover(device)
+        gateway.deliver(message, device)
+      end
+
+    end
+  end
+end

data/lib/pling/configurable.rb

@@ -0,0 +1,29 @@
+module Pling
+  module Configurable
+
+    protected
+
+      def configuration
+        @configuration ||= default_configuration
+      end
+
+      def default_configuration
+        {}
+      end
+
+      def setup_configuration(config = {}, opts = {})
+        config.each_pair do |key, value|
+          configuration[key.to_sym] = value
+        end
+
+        require_configuration(opts[:require] || [])
+      end
+
+      def require_configuration(keys, message = nil)
+        [keys].flatten.each do |key|
+          raise(ArgumentError, message || "Option :#{key} is missing") unless configuration.key?(key.to_sym)
+        end
+      end
+
+  end
+end

data/lib/pling/delayed_initializer.rb

@@ -0,0 +1,13 @@
+module Pling
+  class DelayedInitializer < Array
+    def use(*args)
+      self << args
+    end
+
+    def initialize!
+      map! do |item|
+        item.kind_of?(Array) ? item.shift.new(*item) : item
+      end
+    end 
+  end
+end

data/lib/pling/device.rb

@@ -0,0 +1,68 @@
+module Pling
+  class Device
+
+    ##
+    # The device identifier
+    #
+    # @overload identifier
+    # @overload identifier=(identifier)
+    #   @param [#to_s] identifier
+    attr_reader :identifier
+
+    def identifier=(identifier)
+      identifier &&= identifier.to_s
+      @identifier = identifier
+    end
+
+    ##
+    # The device type
+    #
+    # @overload type
+    # @overload type=(type)
+    #    @param [#to_sym] type
+    attr_reader :type
+
+    def type=(type)
+      type &&= type.to_sym
+      @type = type
+    end
+
+    ##
+    # Creates a new Pling::Device instance with the given identifier and type
+    #
+    # @param [Hash] attributes
+    # @option attributes [#to_s] :identifier
+    # @option attributes [#to_sym] :type
+    def initialize(attributes = {})
+      attributes.each_pair do |key, value|
+        method = "#{key}="
+        send(method, value) if respond_to?(method)
+      end
+    end
+
+    ##
+    # A device is valid if it has a type and an identifier.
+    #
+    # @return [Boolean]
+    def valid?
+      !!(type && identifier)
+    end
+
+    ##
+    # Delivers the given message using an appropriate gateway.
+    #
+    # @param [#to_pling_message] message
+    def deliver(message)
+      Pling.deliver(message, self)
+    end
+
+    ##
+    # Returns the object itself as it is already a Pling::Device.
+    #
+    # @return [Pling::Device]
+    def to_pling_device
+      self
+    end
+
+  end
+end

data/lib/pling/gateway.rb

@@ -0,0 +1,17 @@
+module Pling
+  module Gateway
+    autoload :Base, 'pling/gateway/base'
+    autoload :C2DM, 'pling/gateway/c2dm'
+    autoload :APN,  'pling/gateway/apn'
+
+    class << self
+      def discover(device)
+        device = Pling._convert(device, :device)
+        Pling.gateways.initialize!
+        Pling.gateways.detect do |gateway|
+          gateway.handles?(device)
+        end or raise(Pling::NoGatewayFound, "Could not find a gateway for #{device.class} with type :#{device.type}")
+      end
+    end
+  end
+end