proby 2.0.0

data/.gitignore

@@ -0,0 +1,3 @@
+*.swp
+doc
+.yardoc

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,36 @@
+PATH
+  remote: .
+  specs:
+    proby (2.0.0)
+      chronic (~> 0.6.7)
+      httparty (~> 0.8.1)
+      multi_json (~> 1.2.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    bluecloth (2.1.0)
+    chronic (0.6.7)
+    fakeweb (1.3.0)
+    httparty (0.8.3)
+      multi_json (~> 1.0)
+      multi_xml
+    json (1.6.6)
+    multi_json (1.2.0)
+    multi_xml (0.4.4)
+    rake (0.9.2.2)
+    shoulda (2.11.3)
+    yard (0.6.8)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bluecloth (~> 2.1.0)
+  bundler (>= 1.0.0)
+  fakeweb (~> 1.3.0)
+  json (~> 1.6.6)
+  proby!
+  rake (~> 0.9.0)
+  shoulda (~> 2.11.3)
+  yard (~> 0.6.4)

data/README.md

@@ -0,0 +1,95 @@
+# Proby
+A simple library for working with the Proby task monitoring application.
+
+
+Installation
+------------
+
+### RubyGems ###
+Proby can be installed using RubyGems
+
+    gem install proby
+
+Inside your script, be sure to
+
+    require "rubygems"
+    require "proby"
+
+### Bundler ###
+If you're using Bundler, add the following to your Gemfile
+
+    gem "proby"
+
+and then run
+
+    bundle install
+
+
+Setup
+-----
+Before notifications can be sent, you must tell Proby your API key.  This only needs to be done once,
+and should ideally be done inside your apps initialization code.
+
+    Proby.api_key = "b4fe1200c105012efde3482a1411a947"
+
+In addition, you can optionally give Proby a logger to use.
+
+    Proby.logger = Rails.logger
+
+
+Sending Notifications
+---------------------
+To send a start notification
+
+    Proby.send_start_notification(task_api_id)
+
+To send a finish notification
+
+    Proby.send_finish_notification(task_api_id)
+
+Specifying the `task_api_id` when calling the notification methods is optional.  If it is not provided,
+Proby will use the value of the `PROBY_TASK_ID` environment variable.  If no task id is specified
+in the method call, and no value is set in the `PROBY_TASK_ID` environment variable, then no notification
+will be sent.
+
+
+The Resque Plugin
+-----------------
+The Resque plugin will automatically send start and finish notifications to Proby when your job
+starts and finishes.  Simply `extend Proby::ResquePlugin` in your Resque job.  The task id
+can either be pulled from the `PROBY_TASK_ID` environment variable, or specified in the job itself
+by setting the `@proby_id` attribute to the task id.
+
+    class SomeJob
+      extend Proby::ResquePlugin
+      @proby_id = 'abc123'  # Or simply let it use the value in the PROBY_TASK_ID environment variable
+
+      self.perform
+        do_stuff
+      end
+    end
+
+
+Managing Tasks
+--------------
+The Proby::ProbyTask class can be used to create, read, update, delete, pause, and unpause your
+tasks on Proby.
+
+    my_tasks = Proby::ProbyTask.find(:all)
+    a_specific_task = Proby::ProbyTask.find("the_proby_task_id")
+
+    task = Proby::ProbyTask.create(:name => 'Task name', :crontab => '* * * * *')
+
+    task.name = "New name"
+    task.save
+
+    task.pause
+    task.unpause
+
+    task.delete
+
+
+API Doc
+-------
+[http://rdoc.info/github/signal/proby-ruby/master/frames](http://rdoc.info/github/signal/proby-ruby/master/frames)
+

data/Rakefile

@@ -0,0 +1,38 @@
+require 'rubygems'
+require 'bundler'
+
+Bundler::GemHelper.install_tasks
+
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+
+require 'rake'
+require 'rake/testtask'
+require 'yard'
+
+task :default => :test
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = ENV['TEST'] || "test/**/*_test.rb"
+  test.verbose = true
+end
+
+YARD::Rake::YardocTask.new do |t|
+  t.files = ['lib/**/*.rb']
+end
+
+desc 'Delete yard, and other generated files'
+task :clobber => [:clobber_yard]
+
+desc 'Delete yard generated files'
+task :clobber_yard do
+  puts 'rm -rf doc .yardoc'
+  FileUtils.rm_rf ['doc', '.yardoc']
+end
+

data/lib/proby/exceptions.rb

@@ -0,0 +1,13 @@
+module Proby
+  # Exception raised when a request to Proby fails
+  class ApiException < StandardError; end
+
+  # Exception raised when the api key is not properly set
+  class InvalidApiKeyException < StandardError; end
+
+  # Authentication to Proby failed.  Make sure your API key is correct.
+  class AuthFailedException < StandardError; end
+
+  # An invalid parameter was passed to the given method
+  class InvalidParameterException < StandardError; end
+end

data/lib/proby/notifier.rb

@@ -0,0 +1,28 @@
+module Proby
+  class Notifier < ProbyHttpApi
+
+    def self.send_notification(type, proby_task_id, options={})
+      if Proby.api_key.nil?
+        Proby.logger.warn "Proby: No notification sent because API key is not set"
+        return nil
+      end
+
+      proby_task_id = ENV['PROBY_TASK_ID'] if blank?(proby_task_id)
+      if blank?(proby_task_id)
+        Proby.logger.warn "Proby: No notification sent because task ID was not specified"
+        return nil
+      end
+
+      response = post("/api/v1/tasks/#{proby_task_id}/#{type}.json",
+                      :body => MultiJson.encode(options),
+                      :format => :json,
+                      :headers => default_headers)
+      response.code
+    rescue Exception => e
+      Proby.logger.error "Proby: Proby notification failed: #{e.message}"
+      Proby.logger.error e.backtrace
+    end
+
+  end
+end
+

data/lib/proby/proby_http_api.rb

@@ -0,0 +1,28 @@
+module Proby
+  class ProbyHttpApi
+    include HTTParty
+    base_uri "https://proby.signalhq.com"
+    default_timeout 5
+
+    protected
+
+    def self.handle_api_failure(response)
+      if response.code == 401
+        raise AuthFailedException.new("Authentication to Proby failed.  Make sure your API key is correct.")
+      else
+        message = "API request failed with a response code of #{response.code}.  Respone body: #{response.body}"
+        Proby.logger.error message
+        raise ApiException.new(message)
+      end
+    end
+
+    def self.default_headers
+      { 'api_key' => Proby.api_key, 'Content-Type' => 'application/json' }
+    end
+
+    def self.blank?(s)
+      s.nil? || s.strip.empty?
+    end
+
+  end
+end

data/lib/proby/proby_task.rb

@@ -0,0 +1,278 @@
+module Proby
+
+  # Represents the status of a Proby task
+  class ProbyTaskStatus
+    # The description of the task (OK, ERROR, PAUSED)
+    attr_reader :description
+
+    # Any details (why the task is in the ERROR state)
+    attr_reader :details
+
+    def initialize(attributes={})
+      @description = attributes['description']
+      @details = attributes['details']
+    end
+  end
+
+  # Represents a task in Proby
+  class ProbyTask < ProbyHttpApi
+    # The name of the task
+    attr_accessor :name
+
+    # The schedule for the task, specified in crontab format
+    attr_accessor :crontab
+
+    # The time zone of the machine executing the task
+    attr_accessor :time_zone
+
+    # The name of the machine that is responsible for running this task
+    attr_accessor :machine
+
+    # Should finish alarms be sent when the task runs longer than expected?
+    attr_accessor :finish_alarms_enabled
+
+    # The maximum amount of time the task is allowed to run before Proby sends
+    # a finish alarm. If not specified, Proby will determine when an alarm should
+    # be sent based on past run times
+    attr_accessor :maximum_run_time
+
+    # The number of minutes to wait for a task to send its start notification after it
+    # should have started before sending an alarm
+    attr_accessor :start_notification_grace_period
+
+    # The number of consecutive tasks that must fail before an alarm is sent
+    attr_accessor :consecutive_alarmed_tasks_required_to_trigger_alarm
+
+    # The API Task ID of the task
+    attr_reader :api_id
+
+    # Is the task currently paused?
+    attr_reader :paused
+
+    # The number of consecutive times this task has triggered an alarm
+    attr_reader :consecutive_alarmed_tasks
+
+    # The date and time this task was created
+    attr_reader :created_at
+
+    # The date and time this task was updated
+    attr_reader :updated_at
+
+    # The current status of the task, represented as a ProbyTaskStatus
+    attr_reader :status
+
+    # <b>Should not be called directly</b>
+    def initialize(attributes={})
+      @name = attributes['name']
+      @api_id = attributes['api_id']
+      @crontab = attributes['crontab']
+      @paused = attributes['paused']
+      @time_zone = attributes['time_zone']
+      @machine = attributes['machine']
+      @finish_alarms_enabled = attributes['finish_alarms_enabled']
+      @maximum_run_time = attributes['maximum_run_time']
+      @start_notification_grace_period = attributes['start_notification_grace_period']
+      @consecutive_alarmed_tasks = attributes['consecutive_alarmed_tasks']
+      @consecutive_alarmed_tasks_required_to_trigger_alarm = attributes['consecutive_alarmed_tasks_required_to_trigger_alarm']
+      @created_at = Chronic.parse attributes['created_at']
+      @updated_at = Chronic.parse attributes['updated_at']
+      @status = ProbyTaskStatus.new(attributes['status']) if attributes['status']
+    end
+
+    # Get a single, or all tasks from Proby.
+    #
+    # @param [Object] param :all if you are fetching all tasks, or the api_id of the Proby task you would like to fetch.
+    #
+    # @return If requesting all tasks, an [Array<ProbyTask>] will be returned.  If an api_id was provided, the
+    #           ProbyTask with that api_id will be returned if it exists, or nil if it could not be found.
+    #
+    # @example
+    #   all_of_my_tasks = ProbyTask.find(:all)
+    #   my_task = ProbyTask.find('my_proby_task_api_id')
+    def self.find(param)
+      ensure_api_key_set
+      param == :all ? list : fetch(param)
+    end
+
+    # Create a new Proby task.
+    #
+    # @param [Hash] attributes The attributes for your task.
+    # @option attributes [String] :name A name for your task.
+    # @option attributes [String] :crontab The schedule of the task, specified in cron format.
+    # @option attributes [String] :time_zone <b>(Optional)</b> The time zone of the machine executing the task.
+    # @option attributes [String] :machine <b>(Optional)</b> The name of the machine that is responsible for running this task.
+    #                               Will default to the default time zone configured in Proby if not specified.
+    # @option attributes [Boolean] :finish_alarms_enabled <b>(Optional)</b> true if you would like to receive finish alarms for
+    #                                this task, false otherwise (default: true).
+    # @option attributes [Fixnum] :maximum_run_time <b>(Optional)</b> The maximum amount of time the task is allowed to run before
+    #                               Proby sends a finish alarm. If not specified, Proby will determine when an alarm should be
+    #                               sent based on past run times.
+    # @option attributes [Fixnum] :start_notification_grace_period <b>(Optional)</b> The number of minutes to wait for a task to
+    #                               send its start notification after it should have started before sending an alarm.
+    # @option attributes [Fixnum] :consecutive_alarmed_tasks_required_to_trigger_alarm <b>(Optional)</b> The number of consecutive
+    #                               tasks that must fail before an alarm is sent.
+    #
+    # @return [ProbyTask] The task that was created.
+    #
+    # @example
+    #   proby_task = ProbyTask.create(:name => "My new task", :crontab => "* * * * *")
+    def self.create(attributes={})
+      ensure_api_key_set
+      raise InvalidParameterException.new("attributes are required") if attributes.nil? || attributes.empty?
+      raise InvalidParameterException.new("name is required") unless !blank?(attributes[:name]) || !blank?(attributes['name'])
+      raise InvalidParameterException.new("crontab is required") unless !blank?(attributes[:crontab]) || !blank?(attributes['crontab'])
+
+      Proby.logger.info "Creating task with attributes: #{attributes.inspect}"
+      response = post("/api/v1/tasks.json",
+                      :format => :json,
+                      :body => MultiJson.encode(:task => attributes),
+                      :headers => default_headers)
+
+      if response.code == 201 
+        new(response.parsed_response['task'])
+      else
+        handle_api_failure(response)
+      end 
+    end
+
+    # Saves the task in Proby, updating all attributes to the values stored in the object.  Only the attributes specified in
+    # the ProbyTask.create documentation can be updated.
+    #
+    # @example
+    #   proby_task = ProbyTask.get('my_proby_task_api_id')
+    #   proby_task.name = "Some other name"
+    #   proby_task.crontab = "1 2 3 4 5"
+    #   proby_task.save
+    def save
+      self.class.ensure_api_key_set
+      raise InvalidParameterException.new("name is required") if self.class.blank?(@name)
+      raise InvalidParameterException.new("crontab is required") if self.class.blank?(@crontab)
+
+      attributes = {
+        :name => @name,
+        :crontab => @crontab,
+        :time_zone => @time_zone,
+        :machine => @machine,
+        :finish_alarms_enabled => @finish_alarms_enabled,
+        :maximum_run_time => @maximum_run_time,
+        :start_notification_grace_period => @start_notification_grace_period,
+        :consecutive_alarmed_tasks_required_to_trigger_alarm => @consecutive_alarmed_tasks_required_to_trigger_alarm
+      }
+
+      Proby.logger.info "Updating task #{@api_id} with attributes: #{attributes.inspect}"
+      response = self.class.put("/api/v1/tasks/#{@api_id}.json",
+                                :format => :json,
+                                :body => MultiJson.encode(:task => attributes),
+                                :headers => self.class.default_headers)
+
+      if response.code == 200
+        true
+      else
+        self.class.handle_api_failure(response)
+      end 
+    end
+
+    # Delete a Proby task.  The object will be frozen after the delete.
+    #
+    # @example
+    #   proby_task = ProbyTask.get('my_proby_task_api_id')
+    #   proby_task.delete
+    def delete
+      self.class.ensure_api_key_set
+
+      Proby.logger.info "Deleting task #{@api_id}"
+      response = self.class.delete("/api/v1/tasks/#{@api_id}.json",
+                                   :format => :json,
+                                   :headers => self.class.default_headers)
+
+      if response.code == 200 
+        self.freeze
+        true
+      else
+        self.class.handle_api_failure(response)
+      end 
+    end
+
+    # Pause a Proby task.
+    #
+    # @example
+    #   proby_task = ProbyTask.get('my_proby_task_api_id')
+    #   proby_task.pause
+    def pause
+      self.class.ensure_api_key_set
+
+      Proby.logger.info "Pausing task #{@api_id}"
+      response = self.class.post("/api/v1/tasks/#{@api_id}/pause.json",
+                                 :format => :json,
+                                 :headers => self.class.default_headers)
+
+      if response.code == 200 
+        @paused = true
+        true
+      else
+        self.class.handle_api_failure(response)
+      end 
+    end
+
+    # Unpause a Proby task.
+    #
+    # @example
+    #   proby_task = ProbyTask.get('my_proby_task_api_id')
+    #   proby_task.unpause
+    def unpause
+      self.class.ensure_api_key_set
+
+      Proby.logger.info "Unpausing task #{@api_id}"
+      response = self.class.post("/api/v1/tasks/#{@api_id}/unpause.json",
+                                 :format => :json,
+                                 :headers => self.class.default_headers)
+
+      if response.code == 200 
+        @paused = false
+        true
+      else
+        self.class.handle_api_failure(response)
+      end 
+    end
+
+    private
+
+    def self.list
+      Proby.logger.info "Getting the list of tasks"
+      response = get('/api/v1/tasks.json',
+                     :format => :json,
+                     :headers => default_headers)
+
+      if response.code == 200
+        data = response.parsed_response['tasks']
+        data.map { |task_data| new(task_data) }
+      else
+        handle_api_failure(response)
+      end
+    end
+
+    def self.fetch(api_id)
+      raise InvalidParameterException.new("api_id is required") if api_id.nil? || api_id.strip.empty?
+
+      Proby.logger.info "Fetching task from Proby: #{api_id}"
+      response = get("/api/v1/tasks/#{api_id}.json",
+                     :format => :json,
+                     :headers => default_headers)
+
+      if response.code == 200
+        new(response.parsed_response['task'])
+      elsif response.code == 404
+        nil
+      else
+        handle_api_failure(response)
+      end
+    end
+
+    def self.ensure_api_key_set
+      if Proby.api_key.nil? || Proby.api_key.strip.empty?
+        raise InvalidApiKeyException.new("Your Proby API key has not been set.  Set it using Proby.api_key = 'my_api_key'")
+      end
+    end
+
+  end
+end

data/lib/proby/resque_plugin.rb

@@ -0,0 +1,65 @@
+module Proby
+  # Automatically notifies Proby when this job starts and finishes.
+  #
+  #   class SomeJob
+  #     extend Proby::ResquePlugin
+  #
+  #     self.perform
+  #       do_stuff
+  #     end
+  #   end
+  #
+  # The Proby Task ID can be set in one of two ways. The most common way is to
+  # put the ID in an ENV variable that is set in your crontab. This ID will be
+  # transparently passed to the Resque job via Redis.
+  #
+  #   0 0 * * * PROBY_TASK_ID=abc123 ./queue_some_job
+  #
+  # Alternatively, if you're not using cron and therefore don't want that
+  # support, you can just set the @proby_id ivar in the class, like so.
+  #
+  #   class SomeJob
+  #     extend Proby::ResquePlugin
+  #     @proby_id = 'abc123'
+  #
+  #     self.perform
+  #       do_stuff
+  #     end
+  #   end
+  #
+  # Setting the @proby_id variable will take precendence over the ENV variable.
+  #
+  module ResquePlugin
+    def proby_id_bucket(*args)
+      "proby_id:#{name}-#{args.to_s}"
+    end
+
+    def before_enqueue_proby(*args)
+      return true if @proby_id
+
+      env_proby_id = ENV['PROBY_TASK_ID']
+      Resque.redis.setex(proby_id_bucket(*args), 24.hours, env_proby_id)
+      return true
+    end
+
+    def proby_id(*args)
+      @proby_id || Resque.redis.get(proby_id_bucket(*args))
+    end
+
+    def around_perform_proby(*args)
+      failed = false
+      error_message = nil
+      _proby_id = proby_id(*args)
+      Proby.send_start_notification(_proby_id)
+      yield
+    rescue Exception => e
+      failed = true
+      error_message = "#{e.class.name}: #{e.message}"
+      error_message << "\n#{e.backtrace.join("\n")}" if e.backtrace
+      raise e
+    ensure
+      Proby.send_finish_notification(_proby_id, :failed => failed, :error_message => error_message)
+    end
+  end
+end
+

data/lib/proby/version.rb

@@ -0,0 +1,3 @@
+module Proby
+  VERSION = "2.0.0"
+end

data/lib/proby.rb

@@ -0,0 +1,75 @@
+require 'logger'
+require 'httparty'
+require 'chronic'
+
+require 'proby/exceptions'
+require 'proby/proby_http_api'
+require 'proby/proby_task'
+require 'proby/notifier'
+require 'proby/resque_plugin'
+
+module Proby
+
+  # A simple library for working with the Proby task monitoring application.
+  class << self
+
+    # Set your Proby API key.
+    #
+    # @param [String] api_key Your Proby API key
+    #
+    # @example
+    #   Proby.api_key = '1234567890abcdefg'
+    def api_key=(api_key)
+      @api_key = api_key
+    end
+
+    # Get the api key.
+    def api_key
+      @api_key
+    end
+
+    # Set the logger to be used by Proby.
+    #
+    # @param [Logger] logger The logger you would like Proby to use
+    #
+    # @example
+    #   Proby.logger = Rails.logger
+    #   Proby.logger = Logger.new(STDERR)
+    def logger=(logger)
+      @logger = logger
+    end
+
+    # Get the logger used by Proby.
+    def logger
+      @logger ||= Logger.new("/dev/null")
+    end
+
+    # Send a start notification for this task to Proby.
+    #
+    # @param [String] proby_task_id The id of the task to be notified. If nil, the
+    #                               value of the +PROBY_TASK_ID+ environment variable will be used.
+    #
+    # @return [Fixnum] The HTTP status code that was returned from Proby.
+    def send_start_notification(proby_task_id=nil)
+      Notifier.send_notification('start', proby_task_id)
+    end
+
+    # Send a finish notification for this task to Proby
+    #
+    # @param [String] proby_task_id The id of the task to be notified. If nil, the
+    #                               value of the +PROBY_TASK_ID+ environment variable will be used.
+    # @param [Hash] options The options for the finish notification
+    # @option options [Boolean] :failed true if this task run resulted in some sort of failure. Setting
+    #                                   this parameter to true will trigger a notification to be sent to
+    #                                   the alarms configured for the given task. Defaults to false.
+    # @option options [String] :error_message A string message describing the failure that occurred.
+    #                                         1,000 character limit.
+    #
+    # @return [Fixnum] The HTTP status code that was returned from Proby.
+    def send_finish_notification(proby_task_id=nil, options={})
+      Notifier.send_notification('finish', proby_task_id, options)
+    end
+
+  end
+end
+