pixeltrix-prowler 1.0.3 → 1.1.0

data/CHANGELOG

@@ -1,3 +1,20 @@
+*1.1.0 (July 10th, 2009)
+
+* Add support for Delayed::Job background processing
+
+* Update documentation for instance level configuration
+
+* Add support for instance level configuration
+
+* Add support for provider key
+
+* Clean up implementation
+
+* Remove unnecessary configuration
+
+* Remove deprecated API
+
+
 *1.0.3 (July 9th, 2009)
 
 * Add verify method for configured API key

data/INSTALL

@@ -32,6 +32,23 @@ To use Prowler within your application just call the notify method, e.g.
 
   Prowler.notify "Event", "Description", Prowler::Priority::NORMAL
 
+If you need to send to multiple accounts from within a single application you
+can create an instance of the Prowler class to override the global settings, e.g.
+
+  prowler = Prowler.new('apikey', 'application')
+  prowler.notify "Event", "Description", Prowler::Priority::NORMAL
+
+If performance is a concern then there is built in support for Delayed::Job.
+This can done either on a global basis, e.g.
+
+  Prowler.configure do |config|
+    config.delayed = true
+  end
+
+or on a individual message basis, e.g.
+
+  Prowler.notify "Event", "Description", Prowler::Priority::NORMAL, true
+
 ABOUT
 
 Prowler relies upon the Prowl iPhone application which is advertised as

data/README

@@ -32,6 +32,23 @@ To use Prowler within your application just call the notify method, e.g.
 
   Prowler.notify "Event", "Description", Prowler::Priority::NORMAL
 
+If you need to send to multiple accounts from within a single application you
+can create an instance of the Prowler class to override the global settings, e.g.
+
+  prowler = Prowler.new('apikey', 'application')
+  prowler.notify "Event", "Description", Prowler::Priority::NORMAL
+
+If performance is a concern then there is built in support for Delayed::Job.
+This can done either on a global basis, e.g.
+
+  Prowler.configure do |config|
+    config.delayed = true
+  end
+
+or on a individual message basis, e.g.
+
+  Prowler.notify "Event", "Description", Prowler::Priority::NORMAL, true
+
 ABOUT
 
 Prowler relies upon the Prowl iPhone application which is advertised as

data/VERSION

@@ -1 +1 @@
-1.0.3
+1.1.0

data/lib/prowler.rb

@@ -29,6 +29,23 @@
 #
 #   Prowler.notify "Event", "Description", Prowler::Priority::NORMAL
 #
+# If you need to send to multiple accounts from within a single application you
+# can create an instance of the Prowler class to override the global settings, e.g.
+#
+#   prowler = Prowler.new('apikey', 'application')
+#   prowler.notify "Event", "Description", Prowler::Priority::NORMAL
+#
+# If performance is a concern then there is built in support for Delayed::Job.
+# This can done either on a global basis, e.g.
+#
+#   Prowler.configure do |config|
+#     config.delayed = true
+#   end
+#
+# or on a individual message basis, e.g.
+#
+#   Prowler.notify "Event", "Description", Prowler::Priority::NORMAL, true
+#
 # === About
 #
 # Prowler relies upon the Prowl iPhone application which is advertised as
@@ -39,15 +56,13 @@
 # For more about the Prowl application see: http://prowl.weks.net/
 
 require 'logger'
-require 'net/http'
 require 'net/https'
+require 'uri'
 
-module Prowler
+class Prowler
 
-  API_PATH = "/publicapi/add"
-  DEPRECATED_API_PATH = "/api/add_notification.php?application=%s&event=%s&description=%s"
-  VERIFY_PATH = "/publicapi/verify?apikey=%s"
-  USER_AGENT = "Prowler/1.0.3"
+  SERVICE_URL = "https://prowl.weks.net/publicapi"
+  USER_AGENT = "Prowler/1.1.0"
 
   module Priority
     VERY_LOW  = -2
@@ -57,50 +72,50 @@ module Prowler
     EMERGENCY = 2
   end
 
-  class << self
-    attr_accessor :host, :port, :secure
-    attr_accessor :api_key, :username, :password
-    attr_accessor :application, :send_notifications
+  class ConfigurationError < StandardError; end
 
-    # The host to connect to.
-    def host
-      @host ||= 'prowl.weks.net'
-    end
+  class DelayedJob
+    attr_accessor :api_key, :provider_key, :application
+    attr_accessor :event, :message, :priority
 
-    # The port on which the service runs.
-    def port
-      @port || (secure ? 443 : 80)
+    def initialize #:nodoc:
+      yield self if block_given?
     end
 
-    # Whether the service is running over SSL.
-    def secure
-      @secure.nil? ? true : !!@secure
+    # Send notification
+    def perform
+      prowler = Prowler.new(api_key, application, provider_key)
+      prowler.notify(event, message, priority, false)
     end
+  end
+
+  class << self
+    attr_accessor :api_key, :provider_key
+    attr_accessor :application, :send_notifications
+    attr_accessor :read_timeout, :open_timeout #:nodoc:
+    attr_accessor :delayed
 
     # Call this method to configure your account details in an initializer.
     def configure
       yield self
     end
 
-    def username=(value) #:nodoc:
-      logger.warn "The username/password API has been deprecated please switch to using an API key."
-      @username = value
+    def send_notifications #:nodoc:
+      @send_notifications.nil? ? true : !!@send_notifications
     end
 
-    # Whether to send notifications
-    def send_notifications
-      @send_notifications.nil? ? true : !!@send_notifications
+    def delayed #:nodoc:
+      @delayed.nil? ? false : !!@delayed
     end
-    alias :send_notifications? :send_notifications
 
     # Reset configuration
     def reset_configuration
-      @host = @port = @secure = @application = @username = @password = @api_key = nil
+      @application = @api_key = @provider_key = nil
     end
 
     # Whether the library has been configured
     def configured?
-      !@application.nil? && (!@api_key.nil? || !(@username.nil? || @password.nil?))
+      !@application.nil? && !@api_key.nil?
     end
 
     # Returns the default logger or a logger that prints to STDOUT.
@@ -110,75 +125,146 @@ module Prowler
       @logger ||= Logger.new(STDERR)
     end
 
+    def read_timeout #:nodoc:
+      @read_timeout ||= 5
+    end
+
+    def open_timeout #:nodoc:
+      @open_timeout ||= 2
+    end
+
     # Send a notification to your iPhone:
     # * event:    The title of notification you want to send.
     # * message:  The text of the notification message you want to send.
     # * priority: The priority of the notification - see Prowler::Priority. (Optional)
-    def notify(event, message, priority = Priority::NORMAL)
-      raise RuntimeError, "Prowler needs to be configured first before using it" unless configured?
-
-      http = Net::HTTP.new(host, port)
-      http.use_ssl = secure
-      http.verify_mode = OpenSSL::SSL::VERIFY_NONE
-      http.start do
-        headers = {
-          'User-Agent' => USER_AGENT
-        }
-        http.read_timeout = 5 # seconds
-        http.open_timeout = 2 # seconds
-        if api_key
-          request = Net::HTTP::Post.new(API_PATH, headers)
-          request.set_form_data({ 'apikey' => api_key, 'priority' => priority, 'application' => application, 'event' => event, 'description' => message })
-        else
-          request = Net::HTTP::Get.new(sprintf(DEPRECATED_API_PATH, URI.escape(application), URI.escape(event), URI.escape(message)), headers)
-          request.basic_auth(username, password)
-        end
-        response = begin
-                     http.request(request) if send_notifications?
-                   rescue TimeoutError => e
-                     logger.error "Timeout while contacting the Prowl server."
-                     nil
-                   end
-        case response
-        when Net::HTTPSuccess then
-          logger.info "Prowl Success: #{response.class}"
-        when NilClass then
-          # Do nothing
-        else
-          logger.error "Prowl Failure: #{response.class}\n#{response.body if response.respond_to? :body}"
-        end
+    # * delayed:  Whether to use Delayed::Job to send notifications. (Optional)
+    def notify(event, message, priority = Priority::NORMAL, delayed = self.delayed)
+      raise ConfigurationError, "You must provide an API key to send notifications" if api_key.nil?
+      raise ConfigurationError, "You must provide an application name to send notifications" if application.nil?
+      if delayed
+        enqueue_delayed_job(self, event, message, priority)
+      else
+        perform(
+          :add, api_key, provider_key,
+          {
+            :application => application,
+            :event => event,
+            :description => message,
+            :priority => priority
+          }
+        )
       end
     end
 
     # Verify the configured API key is valid
     def verify
-      raise RuntimeError, "Prowler needs to be configured first before using it" unless api_key
-
-      http = Net::HTTP.new(host, port)
-      http.use_ssl = secure
-      http.verify_mode = OpenSSL::SSL::VERIFY_NONE
-      http.start do
-        headers = {
-          'User-Agent' => USER_AGENT
-        }
-        http.read_timeout = 5 # seconds
-        http.open_timeout = 2 # seconds
-        request = Net::HTTP::Get.new(sprintf(VERIFY_PATH, api_key), headers)
-        response = begin
-                     http.request(request) if send_notifications?
-                   rescue TimeoutError => e
-                     logger.error "Timeout while contacting the Prowl server."
-                     nil
-                   end
-        case response
-        when Net::HTTPSuccess then
-          logger.info "Prowl Success: #{response.class}"
-          true
-        else
-          logger.error "Prowl Failure: #{response.class}\n#{response.body if response.respond_to? :body}"
-          false
+      raise ConfigurationError, "You must provide an API key to verify" if api_key.nil?
+      perform(:verify, api_key, provider_key, {}, :get)
+    end
+
+    def perform(command, api_key, provider_key, data = {}, method = :post) #:nodoc:
+      params = { :apikey => api_key, :provider_key => provider_key }.merge(data).delete_if { |k,v| v.nil? }
+      case method
+      when :post
+        perform_post(command, params)
+      else
+        perform_get(command, params)
+      end
+    end
+
+    def enqueue_delayed_job(config, event, message, priority) #:nodoc:
+      record = Delayed::Job.enqueue(DelayedJob.new do |job|
+        job.api_key = config.api_key
+        job.provider_key = config.provider_key
+        job.application = config.application
+        job.event = event
+        job.message = message
+        job.priority = priority
+      end)
+      !record.new_record?
+    end
+
+    private
+      def headers(extra_headers = {}) #:nodoc:
+        { 'User-Agent' => USER_AGENT }.merge(extra_headers)
+      end
+
+      def perform_get(command, params) #:nodoc:
+        url = URI.parse("#{SERVICE_URL}/#{command}?#{params.map{ |k,v| %(#{URI.encode(k.to_s)}=#{URI.encode(v.to_s)}) }.join('&')}")
+        request = Net::HTTP::Get.new("#{url.path}?#{url.query}", headers)
+        perform_request(url, request)
+      end
+
+      def perform_post(command, params) #:nodoc:
+        url = URI.parse("#{SERVICE_URL}/#{command}")
+        request = Net::HTTP::Post.new(url.path, headers)
+        request.form_data = params
+        perform_request(url, request)
+      end
+
+      def perform_request(url, request) #:nodoc:
+        http = Net::HTTP.new(url.host, url.port)
+        http.use_ssl = true
+        http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+        http.read_timeout = read_timeout
+        http.open_timeout = open_timeout
+        http.start do
+          begin
+            return true unless send_notifications
+            response = http.request(request)
+            case response
+            when Net::HTTPSuccess then
+              logger.info "Prowl Success: #{response.class}"
+              true
+            else
+              logger.error "Prowl Failure: #{response.class}\n#{response.body if response.respond_to? :body}"
+              false
+            end
+          rescue TimeoutError => e
+            logger.error "Timeout while contacting the Prowl server."
+            false
+          end
         end
       end
+  end
+
+  attr_accessor :api_key, :provider_key #:nodoc:
+  attr_accessor :application, :send_notifications #:nodoc:
+
+  # Create an instance for sending to different accounts within a single Rails application
+  # * api_key:      Your API key.
+  # * application:  The name of your application.
+  # * provider_key: Key to override the rate limit of 1000 requests per hour. (Optional)
+  def initialize(api_key, application, provider_key = nil)
+    @api_key, @application, @provider_key = api_key, application, provider_key
+  end
+
+  # Send a notification to your iPhone:
+  # * event:    The title of notification you want to send.
+  # * message:  The text of the notification message you want to send.
+  # * priority: The priority of the notification - see Prowler::Priority. (Optional)
+  # * delayed:  Whether to use Delayed::Job to send notifications. (Optional)
+  def notify(event, message, priority = Priority::NORMAL, delayed = self.class.delayed)
+    raise ConfigurationError, "You must provide an API key to send notifications" if api_key.nil?
+    raise ConfigurationError, "You must provide an application name to send notifications" if application.nil?
+    if delayed
+      self.class.enqueue_delayed_job(self, event, message, priority)
+    else
+      self.class.perform(
+        :add, api_key, provider_key,
+        {
+          :application => application,
+          :event => event,
+          :description => message,
+          :priority => priority
+        }
+      )
     end
   end
+
+  # Verify the configured API key is valid
+  def verify
+    raise ConfigurationError, "You must provide an API key to verify" if api_key.nil?
+    self.class.perform(:verify, api_key, provider_key, {}, :get)
+  end
 end

data/prowler.gemspec

@@ -2,11 +2,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{prowler}
-  s.version = "1.0.3"
+  s.version = "1.1.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Andrew White"]
-  s.date = %q{2009-07-09}
+  s.date = %q{2009-07-10}
   s.description = %q{A simple wrapper class that provides basic access to the Prowl API.}
   s.email = %q{andyw@pixeltrix.co.uk}
   s.extra_rdoc_files = [

data/test/prowler_test.rb

@@ -13,32 +13,14 @@ class ProwlerTest < Test::Unit::TestCase
 
     should "be done with a block" do
       Prowler.configure do |config|
-        config.host = "prowler"
-        config.port = 666
-        config.secure = false
         config.api_key = "apikey"
         config.application = "application"
       end
 
-      assert_equal "prowler",     Prowler.host
-      assert_equal 666,           Prowler.port
-      assert_equal false,         Prowler.secure
       assert_equal "apikey",      Prowler.api_key
       assert_equal "application", Prowler.application
     end
 
-    should "set a default host" do
-      assert_equal "prowl.weks.net", Prowler.host
-    end
-
-    should "set a default port" do
-      assert_equal 443, Prowler.port
-    end
-
-    should "default to secure" do
-      assert_equal true, Prowler.secure
-    end
-
     should "not set a default application" do
       assert_equal nil, Prowler.application
     end
@@ -47,55 +29,63 @@ class ProwlerTest < Test::Unit::TestCase
       assert_equal nil, Prowler.api_key
     end
 
-    should "raise an exception if not configured" do
-      assert_raises RuntimeError do
-        Prowler.notify("Event", "Description", Prowler::Priority::NORMAL)
-      end
+    should "override class configuration when using an instance" do
+      prowler = Prowler.new("apikey2", "application2")
+      assert_equal "apikey2",      prowler.api_key
+      assert_equal "application2", prowler.application
     end
   end
 
-  context "Prowler deprecated configuration" do
+  context "Sending a notification" do
     setup do
-      Logger.any_instance.stubs(:warn)
       Prowler.reset_configuration
+      Prowler.configure do |config|
+        config.api_key = "apikey"
+        config.application = "Application Name"
+      end
       Prowler.send_notifications = false
     end
 
-    should "be done with a block" do
-      Prowler.configure do |config|
-        config.host = "prowler"
-        config.port = 666
-        config.secure = false
-        config.application = "application"
-        config.username = "username"
-        config.password = "password"
+    should "raise an exception if API key not configured" do
+      Prowler.reset_configuration
+      assert_raises Prowler::ConfigurationError do
+        Prowler.notify("Event", "Description", Prowler::Priority::NORMAL)
       end
 
-      assert_equal "username",    Prowler.username
-      assert_equal "password",    Prowler.password
+      prowler = Prowler.new(nil, nil)
+      assert_raises Prowler::ConfigurationError do
+        prowler.notify("Event", "Description", Prowler::Priority::NORMAL)
+      end
     end
 
-    should "log a warning when using the deprecated API" do
-      Logger.any_instance.expects(:warn).with("The username/password API has been deprecated please switch to using an API key.")
-      Prowler.configure { |config| config.username = "username" }
-    end
+    should "raise an exception if application not configured" do
+      Prowler.reset_configuration
+      Prowler.configure do |config|
+        config.api_key = "apikey"
+      end
+      assert_raises Prowler::ConfigurationError do
+        Prowler.notify("Event", "Description", Prowler::Priority::NORMAL)
+      end
 
-    should "not set a default username" do
-      assert_equal nil, Prowler.username
+      prowler = Prowler.new("apikey", nil)
+      assert_raises Prowler::ConfigurationError do
+        prowler.notify("Event", "Description", Prowler::Priority::NORMAL)
+      end
     end
 
-    should "not set a default password" do
-      assert_equal nil, Prowler.password
+    should "not verify SSL certificates" do
+      Net::HTTP.any_instance.expects(:use_ssl=).with(true)
+      Net::HTTP.any_instance.expects(:verify_mode=).with(OpenSSL::SSL::VERIFY_NONE)
+      Prowler.notify("Event Name", "Message Text", Prowler::Priority::NORMAL)
     end
 
-    should "raise an exception if not configured" do
-      assert_raises RuntimeError do
-        Prowler.notify("Event", "Description", Prowler::Priority::NORMAL)
-      end
+    should "not send notifications if send_notifications is false" do
+      Net::HTTP.any_instance.expects(:request).never
+      Prowler.notify("Event Name", "Message Text", Prowler::Priority::NORMAL)
     end
   end
 
-  context "Sending a notification" do
+  context "Verifying an API key" do
     setup do
       Prowler.reset_configuration
       Prowler.configure do |config|
@@ -105,15 +95,27 @@ class ProwlerTest < Test::Unit::TestCase
       Prowler.send_notifications = false
     end
 
+    should "raise an exception if API key not configured" do
+      Prowler.reset_configuration
+      assert_raises Prowler::ConfigurationError do
+        Prowler.verify
+      end
+
+      prowler = Prowler.new(nil, nil)
+      assert_raises Prowler::ConfigurationError do
+        prowler.verify
+      end
+    end
+
     should "not verify SSL certificates" do
       Net::HTTP.any_instance.expects(:use_ssl=).with(true)
       Net::HTTP.any_instance.expects(:verify_mode=).with(OpenSSL::SSL::VERIFY_NONE)
-      Prowler.notify("Event Name", "Message Text", Prowler::Priority::NORMAL)
+      Prowler.verify
     end
 
     should "not send notifications if send_notifications is false" do
       Net::HTTP.any_instance.expects(:request).never
-      Prowler.notify("Event Name", "Message Text", Prowler::Priority::NORMAL)
+      Prowler.verify
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: pixeltrix-prowler
 version: !ruby/object:Gem::Version 
-  version: 1.0.3
+  version: 1.1.0
 platform: ruby
 authors: 
 - Andrew White
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-07-09 00:00:00 -07:00
+date: 2009-07-10 00:00:00 -07:00
 default_executable: 
 dependencies: []