resque-exceptional 0.0.1

data/HISTORY.md

@@ -0,0 +1,3 @@
+## 0.0.1 (2010-10-13)
+
+* Initial release.

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Luke Antins
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+Software), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,82 @@
+resque-exceptional
+==================
+
+resque-exceptional provides a Resque failure backend that sends exceptions
+raised by jobs to http://getexceptional.com
+
+Install & Quick Start
+---------------------
+
+Before you jump into code, you'll need a http://getexceptional.com account.
+
+To install:
+
+    $ gem install resque-exceptional
+
+### Example: Single Failure Backend
+
+Using only the exceptional failure backend:
+
+    require 'resque'
+    require 'resque-exceptional'
+
+    Resque::Failure::Exceptional.configure do |config|
+      config.api_key = '505f2518c41866bb0be7ba434bb2b079'
+      config.use_ssl = false
+    end
+
+    Resque::Failure.backend = Resque::Failure::Exceptional
+
+### Example: Multiple Failure Backends
+
+Using both the redis and exceptional failure backends:
+
+    require 'resque'
+    require 'resque-exceptional'
+
+    require 'resque/failure/multiple'
+    require 'resque/failure/redis'
+
+    Resque::Failure::Exceptional.configure do |config|
+      config.api_key = '505f2518c41866bb0be7ba434bb2b079'
+    end
+
+    Resque::Failure::Multiple.classes = [Resque::Failure::Redis, Resque::Failure::Exceptional]
+    Resque::Failure.backend = Resque::Failure::Multiple
+
+Configuration Options
+---------------------
+
+**Required**
+
+  * `api_key` - your getexceptional.com api key.
+
+**HTTP Proxy Options** *(optional)*
+
+  * `proxy_host` - proxy server ip / hostname.
+  * `proxy_port` - proxy server port.
+  * `proxy_user` - proxy server username.
+  * `proxy_pass` - proxy server password.
+
+**HTTP Client Options** *(optional)*
+
+  * `use_ssl` - set `true` if your plan supports ssl. (default: `false`)
+  * `http_open_timeout` - timeout in seconds to establish the connection. (default: `2`)
+  * `http_read_timeout` - timeout in seconds to wait for a reply. (default: `5`)
+
+Note on Patches/Pull Requests
+-----------------------------
+
+  * Fork the project.
+  * Make your feature addition or bug fix.
+  * Add tests for it. This is important so I don't break it in a future
+    version unintentionally.
+  * Commit, do not mess with the version. (if you want to have your own
+    version, that is fine but bump version in a commit by itself I can ignore
+    when I pull)
+  * Send me a pull request. Bonus points for topic branches.
+
+Author
+------
+
+Luke Antins :: http://lividpenguin.com :: @lantins

data/Rakefile

@@ -0,0 +1,25 @@
+$LOAD_PATH.unshift 'lib'
+
+require 'rake/testtask'
+require 'fileutils'
+require 'yard'
+require 'yard/rake/yardoc_task'
+
+task :default => :test
+
+##
+# Test task.
+Rake::TestTask.new(:test) do |task|
+  task.test_files = FileList['test/*_test.rb']
+  task.verbose = true
+end
+
+##
+# docs task.
+YARD::Rake::YardocTask.new :yardoc do |t|
+    t.files   = ['lib/**/*.rb']
+    t.options = ['--output-dir', "doc/",
+                 '--files', 'LICENSE HISTORY.md',
+                 '--readme', 'README.md',
+                 '--title', 'resque-exceptional documentation']
+end

data/lib/resque/failure/exceptional.rb

@@ -0,0 +1,159 @@
+module Resque
+  module Failure
+
+    # A resque failure backend that sends exception data to getexceptional.com
+    class Exceptional < Base
+      # Raised if the api_key is not set.
+      class APIKeyError < StandardError
+      end
+
+      # Our version number =)
+      Version = '0.0.1'
+
+      class << self
+        # API Settings.
+        attr_accessor :api_key
+        # HTTP Proxy Options.
+        attr_accessor :proxy_host, :proxy_port, :proxy_user, :proxy_pass
+        # HTTP Client Options.
+        attr_accessor :use_ssl, :http_open_timeout, :http_read_timeout
+      end
+
+      # Configures the failure backend. At a minimum you will need to set
+      # an api_key.
+      def self.configure
+        yield self
+      end
+
+      # Sends the exception data to the exceptional api.
+      #
+      # When a job fails, a new instance is created and #save is called.
+      def save
+        return unless response = http_post_request
+
+        if response.code == '200'
+          log "success - api accepted the exception data."
+        else
+          body = response.body if response.respond_to? :body
+          log "fail - expected: 200 OK, received: #{response.code} #{response.message}"
+        end
+      end
+
+      # Sends a HTTP Post to the exceptional api.
+      #
+      # @return [Net::HTTPResponse] http response data.
+      # @return [nil] if something went wrong.
+      def http_post_request
+        begin
+          return http_client.post(http_path_query, compressed_request, http_headers)
+        rescue APIKeyError
+          log 'error - you must set your api_key.'
+        rescue TimeoutError
+          log 'fail - timeout while contacting the api server.'
+        rescue Exception => e
+          log "fail - exception raised during http post. (#{e.class.name}: #{e.message})"
+        end
+        nil
+      end
+
+      # HTTP headers to send.
+      #
+      # @return [Hash] http headers.
+      def http_headers
+        { 'Content-Type' => 'application/json', 'Accept' => 'application/json' }
+      end
+
+      # Returns the compressed request data.
+      def compressed_request
+        Zlib::Deflate.deflate(api_request.to_json, Zlib::BEST_SPEED)
+      end
+
+      # Path & query options used by the HTTP Post.
+      #
+      # @raise [APIKeyError] if the api_key is not set.
+      # @return [String] http path & query options.
+      def http_path_query
+        raise APIKeyError, 'api key must be set.' unless self.class.api_key
+        hash_param = uniqueness_hash.nil? ? nil : "&hash=#{uniqueness_hash}"
+        "/api/errors?api_key=#{self.class.api_key}&protocol_version=5#{hash_param}"
+      end
+
+      # Calculates a uniqueness md5sum of the exception backtrace if available.
+      #
+      # nb. this isn't documented in the public api... not sure if we should
+      # use it or not...
+      def uniqueness_hash
+        return nil if (exception.backtrace.nil? || exception.backtrace.empty?)
+        Digest::MD5.hexdigest(exception.backtrace.join)
+      end
+
+      # Configures a HTTP client.
+      #
+      # @return [Net::HTTP] http client.
+      def http_client
+        # pass any proxy settings.
+        proxy = Net::HTTP::Proxy(self.class.proxy_host, self.class.proxy_port,
+                                 self.class.proxy_user, self.class.proxy_pass)
+        http = proxy.new('api.getexceptional.com', http_port)
+
+        # set http client options.
+        http.read_timeout = self.class.http_read_timeout || 5
+        http.open_timeout = self.class.http_open_timeout || 2
+        http.use_ssl = use_ssl?
+
+        http
+      end
+
+      # Helper method to return the correct HTTP port number.
+      def http_port
+        use_ssl? ? 443 : 80
+      end
+
+      # Helper method to check if were using SSL or not.
+      def use_ssl?
+        self.class.use_ssl || false
+      end
+
+      # Adds a prefix to log messages.
+      def log(msg)
+        super("resque-exception - #{msg}")
+      end
+
+      # API request data structure.
+      #
+      # @return [Hash] data structure expected by the api.
+      def api_request
+        {
+          'request' => {
+            'parameters' => {
+              'queue' => queue.to_s,
+              'job_class' => payload['class'].to_s,
+              'job_args' => payload['args'],
+              'worker' => worker.to_s
+            }
+          },
+          'application_environment' => {
+            'env' => ENV.to_hash,
+            'application_root_directory' => ENV['PWD']
+          },
+          'exception' => {
+            'occurred_at' => Time.now.iso8601,
+            'message' => "#{exception.class.name}: #{exception.message}",
+            'backtrace' => Array(exception.backtrace),
+            'exception_class' => exception.class.name
+          },
+          'rescue_block' => {
+            'name' => 'Resque Failure'
+          },
+          'client' => {
+            'name' => 'resque-exceptional',
+            'version' => Resque::Failure::Exceptional::Version,
+            'protocol_version' => 5
+          }
+        }
+      end
+
+    end
+
+  end
+end

data/lib/resque-exceptional.rb

@@ -0,0 +1,8 @@
+require 'zlib'
+require 'net/http'
+require 'net/https'
+require 'time'
+require 'digest/md5'
+require 'resque'
+
+require 'resque/failure/exceptional'

data/test/exceptional_test.rb

@@ -0,0 +1,118 @@
+require File.dirname(__FILE__) + '/test_helper'
+
+# Tests the failure backend works with resque, does not contact the api.
+class ExceptionalTest < Test::Unit::TestCase
+  def setup
+    @exception = TestApp.grab_exception
+    @worker = FakeWorker.new
+    @queue = 'test_queue'
+    @payload = { 'class' => 'TestJob', 'args' => ['foo', 'bar'] }
+    @failure = Resque::Failure::Exceptional.new(@exception, @worker, @queue, @payload)
+  end
+
+  # test we can build a hash to send to the api.
+  def test_can_build_api_request_data_hash
+    data = @failure.api_request
+    assert_kind_of Hash, data, 'should build a hash'
+  end
+
+  # include the minimum entries required by the api.
+  def test_api_request_includes_minimum_api_entries
+    data = @failure.api_request
+
+    assert_kind_of Hash,   data['application_environment']
+    assert_kind_of Hash,   data['application_environment']['env']
+    assert_kind_of String, data['application_environment']['application_root_directory']
+
+    assert_kind_of Hash, data['exception']
+    # test occurred_at that starts like: 2010-10-13T01:56:49
+    assert_match /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/, data['exception']['occurred_at']
+    assert_kind_of String, data['exception']['message']
+    assert_kind_of Array, data['exception']['backtrace']
+    assert_equal 'TestApp::Error', data['exception']['exception_class']
+  end
+
+  # include the resque information, we sneak it in as request data so we can
+  # view it via the web interface.
+  def test_api_request_includes_resque_info
+    data = @failure.api_request
+
+    assert_kind_of Hash,   data['request']
+    assert_kind_of Hash,   data['request']['parameters']
+    assert_kind_of String, data['request']['parameters']['queue']
+    assert_kind_of String, data['request']['parameters']['job_class']
+    assert_kind_of Array,  data['request']['parameters']['job_args']
+    assert_kind_of String, data['request']['parameters']['worker']
+  end
+
+  # make it more obvious in the web interface this was a resque failure.
+  def test_api_request_includes_resque_block
+    data = @failure.api_request
+
+    assert_kind_of Hash, data['rescue_block']
+    assert_equal 'Resque Failure', data['rescue_block']['name']
+  end
+
+  # let them know who we are.
+  def test_api_request_includes_client_info
+    data = @failure.api_request
+
+    assert_equal 'resque-exceptional', data['client']['name'], 'should use the gem name'
+    assert_match /^\d+\.\d+\.\d+$/, data['client']['version'], 'should have a version number'
+    assert_kind_of Fixnum, data['client']['protocol_version']
+  end
+
+  # we need the ability to configure the failure backend before its created.
+  # config settings should be class variables.
+  def test_configure
+    Resque::Failure::Exceptional.configure do |config|
+      config.api_key = 'my api key.'
+      # everything below are http client options.
+      config.proxy_host = 'host.name.com'
+      config.proxy_port = 8080
+      config.proxy_user = 'foo'
+      config.proxy_pass = 'bar'
+      config.use_ssl = true
+      config.http_open_timeout = 5
+      config.http_read_timeout = 10
+    end
+
+    # reset everything to nil...
+    Resque::Failure::Exceptional.configure do |config|
+      options = %w{api_key proxy_host proxy_port proxy_user proxy_pass use_ssl
+                   http_open_timeout http_read_timeout}
+      options.each { |opt| config.send("#{opt}=", nil) }
+    end
+  end
+
+  # failure backends need to define a save method.
+  def test_save_defined
+    assert_equal true, @failure.respond_to?(:save)
+  end
+
+  # we need a Net::HTTP client setup to send the data.
+  def test_http_client
+    
+  end
+
+  # perform a test with the real api.
+  def test_live_fire
+    #omit 'comment this line, set your api key, test with real api!'
+    Resque::Failure::Exceptional.configure { |c| c.api_key = 'e6bee67c9a45ae41c8318e7d9a0e9d8d0dd9bc20' }
+    @failure.save
+    assert_match /^(resque-exception).*(success).*$/, @worker.log_history.first
+    # reset.
+    Resque::Failure::Exceptional.configure { |c| c.api_key = nil }
+  end
+
+  # we should fail if the api_key is not set.
+  def test_fail_if_api_key_nil
+    # should already be nil, but lets just be sure...
+    Resque::Failure::Exceptional.configure { |c| c.api_key = nil }
+    @failure.save
+    assert_match /^(resque-exception).*(error).*(api_key).*$/, @worker.log_history.first
+  end
+
+  # should handle exceptions raised during the HTTP Post.
+  # should return and not raise anything if we were successful.
+end

data/test/resque_test.rb

@@ -0,0 +1,10 @@
+require File.dirname(__FILE__) + '/test_helper'
+
+# make sure the worlds not fallen from beneith us.
+class ResqueTest < Test::Unit::TestCase
+  def test_resque_version
+    major, minor, patch = Resque::Version.split('.')
+    assert_equal 1, major.to_i, 'major version does not match'
+    assert_operator minor.to_i, :>=, 8, 'minor version is too low'
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,60 @@
+dir = File.dirname(File.expand_path(__FILE__))
+$LOAD_PATH.unshift dir + '/../lib'
+$TESTING = true
+
+require 'test/unit'
+require 'rubygems'
+require 'simplecov'
+require 'rr'
+
+SimpleCov.start do
+  add_filter "/test/"
+end
+
+class Test::Unit::TestCase
+  include RR::Adapters::TestUnit
+end
+
+# require our failure backend to test.
+require 'resque-exceptional'
+
+# fake worker.
+class FakeWorker
+  attr_reader :log_history
+
+  def initialize
+    @log_history = []
+  end
+
+  def log(msg)
+    @log_history << msg
+    p msg
+  end
+
+  def to_s
+    'mr. fake resque worker.'
+  end
+end
+
+# test exceptions.
+module TestApp
+  class Error < StandardError
+  end
+
+  def self.method_bar
+    raise Error, 'example exception message. bar.'
+  end
+
+  def self.method_foo
+    method_bar
+  end
+
+  def self.grab_exception
+    begin
+      method_foo
+    rescue => e
+      return e
+    end
+  end
+
+end

metadata

@@ -0,0 +1,150 @@
+--- !ruby/object:Gem::Specification 
+name: resque-exceptional
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Luke Antins
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-10-13 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: resque
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 55
+        segments: 
+        - 1
+        - 8
+        - 0
+        version: 1.8.0
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: test-unit
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rr
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 1
+        - 0
+        - 0
+        version: 1.0.0
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: simplecov
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 19
+        segments: 
+        - 0
+        - 3
+        - 0
+        version: 0.3.0
+  type: :development
+  version_requirements: *id005
+description: "  resque-exceptional provides a Resque failure backend that sends exceptions\n  raised by jobs to getexceptional.com.\n"
+email: luke@lividpenguin.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- LICENSE
+- Rakefile
+- README.md
+- HISTORY.md
+- test/exceptional_test.rb
+- test/resque_test.rb
+- test/test_helper.rb
+- lib/resque/failure/exceptional.rb
+- lib/resque-exceptional.rb
+has_rdoc: false
+homepage: http://github.com/lantins/resque-exceptional
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: A Resque failure backend for getexceptional.com
+test_files: []
+