navvy-sequelhooks 0.3.3

data/LICENSE

@@ -0,0 +1,3 @@
+Copyright 2010 Jeff Kreeftmeijer.
+You may use this work without restrictions, as long as this notice is included.
+The work is provided "as is" without warranty of any kind, neither express nor implied.

data/README.textile

@@ -0,0 +1,15 @@
+h1. Navvy "!http://stillmaintained.com/jeffkreeftmeijer/navvy.png!":http://stillmaintained.com/jeffkreeftmeijer/navvy
+
+Navvy is a simple Ruby background job processor inspired by "delayed_job":http://github.com/tobi/delayed_job, but aiming for database agnosticism. Currently Navvy supports ActiveRecord, MongoMapper, Sequel, DataMapper and Mongoid but it's extremely easy to write an adapter for your favorite ORM.
+
+Navvy doesn't depend on Rails, it's a pure Ruby library. There are generators for Rails 2 and Rails 3, though.
+
+??“Navvy is a shorter form of navigator (UK) or navigational engineer (USA) and is particularly applied to describe the manual labourers working on major civil engineering projects. The term was coined in the late 18th century in Britain when numerous canals were being built, which were also sometimes known as "navigations". Canal navvies typically worked with shovels, pickaxes and barrows.”?? - "Wikipedia":http://en.wikipedia.org/wiki/Navvy
+
+h2. Using Navvy
+
+Check out the "Installation Guide":http://wiki.github.com/jeffkreeftmeijer/navvy/installation and the "Getting Started Guide":http://wiki.github.com/jeffkreeftmeijer/navvy/getting-started to get up and running. If you have any questions or problems, don't hesitate to "ask":http://github.com/inbox/new/jeffkreeftmeijer.
+
+h2. Contributing
+
+Found an issue? Have a great idea? Want to help? Great! Create an issue "issue":http://github.com/jeffkreeftmeijer/navvy/issues for it, "ask":http://github.com/inbox/new/jeffkreeftmeijer, or even better; fork the project and fix the problem yourself. Pull requests are always welcome. :)

data/generators/navvy/navvy_generator.rb

@@ -0,0 +1,20 @@
+class NavvyGenerator < Rails::Generator::Base
+  default_options :orm => 'active_record'
+
+  def manifest
+    record do |m|
+      m.migration_template "#{options[:orm]}_migration.rb", 'db/migrate', {:migration_file_name => 'create_jobs'}
+    end
+  end
+
+  def add_options!(opt)
+    opt.separator ''
+    opt.separator 'Options:'
+    opt.on('--active_record', 'Generate a migration file for ActiveRecord. (default)') { options[:orm] = 'active_record' }
+    opt.on('--sequel', 'Generate a migration file for Sequel.') { options[:orm] = 'sequel' }
+  end
+
+  def banner
+    "Usage: #{$0} #{spec.name}"
+  end
+end

data/generators/navvy/templates/active_record_migration.rb

@@ -0,0 +1,22 @@
+class CreateJobs < ActiveRecord::Migration
+  def self.up
+    create_table :jobs, :force => true do |t|
+      t.string    :object
+      t.string    :method_name
+      t.text      :arguments
+      t.integer   :priority, :default => 0
+      t.string    :return
+      t.string    :exception
+      t.integer   :parent_id
+      t.datetime  :created_at
+      t.datetime  :run_at
+      t.datetime  :started_at
+      t.datetime  :completed_at
+      t.datetime  :failed_at
+    end
+  end
+
+  def self.down
+    drop_table :jobs
+  end
+end

data/generators/navvy/templates/sequel_migration.rb

@@ -0,0 +1,23 @@
+Sequel.migration do
+  up do
+    create_table(:jobs) do
+      primary_key :id, :type => Integer
+      String    :object
+      String    :method_name
+      String    :arguments, :text => true
+      Integer   :priority, :default => 0
+      String    :return
+      String    :exception
+      Integer   :parent_id
+      DateTime  :created_at
+      DateTime  :run_at
+      DateTime  :started_at
+      DateTime  :completed_at
+      DateTime  :failed_at
+    end
+  end
+
+  down do
+    drop_table(:jobs)
+  end
+end

data/lib/generators/navvy_generator.rb

@@ -0,0 +1,32 @@
+require 'rails/generators/migration'
+class NavvyGenerator < Rails::Generators::Base
+  include Rails::Generators::Migration
+
+  class_option :active_record,
+    :desc => 'Generate a migration file for ActiveRecord. (default)',
+    :type => 'boolean'
+
+  class_option :sequel,
+    :desc => 'Generate a migration file for Sequel.',
+    :type => 'boolean'
+
+  def self.source_root
+    File.join(File.dirname(__FILE__), '..', '..', 'generators', 'navvy', 'templates')
+  end
+
+  def install_navvy
+    migration_template(
+      "#{orm}_migration.rb",
+      'db/migrate/create_jobs.rb'
+    )
+  end
+
+  def orm
+    options[:sequel] ? 'sequel' : 'active_record'
+  end
+
+  protected
+    def self.next_migration_number(dirname) #:nodoc:
+      "%.3d" % (current_migration_number(dirname) + 1)
+    end
+end

data/lib/navvy.rb

@@ -0,0 +1,34 @@
+require 'navvy/worker'
+require 'navvy/logger'
+require 'navvy/configuration'
+
+module Navvy
+  class << self
+    attr_writer :configuration
+  end
+
+  def self.logger
+    @logger || Navvy.configuration.logger
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield(self.configuration)
+  end
+end
+
+
+if defined?(Rails)
+
+  module Navvy
+    class Railtie < Rails::Railtie
+      rake_tasks do
+        require 'navvy/tasks.rb'
+      end
+    end
+  end
+
+end

data/lib/navvy/configuration.rb

@@ -0,0 +1,13 @@
+module Navvy
+  class Configuration
+    attr_accessor :job_limit, :keep_jobs, :logger, :sleep_time, :max_attempts
+
+    def initialize
+      @job_limit =    100
+      @keep_jobs =    false
+      @logger =       Navvy::Logger.new
+      @sleep_time =   5
+      @max_attempts = 25
+    end
+  end
+end

data/lib/navvy/job.rb

@@ -0,0 +1,173 @@
+module Navvy
+  class Job
+    class << self
+      attr_writer :limit, :keep, :max_attempts
+    end
+
+    ##
+    # Limit of jobs to be fetched at once. Will use the value stored in
+    # Navvy.configuration (defaults to 100), or -- for backwards compatibility
+    # -- Navvy::Job.limit.
+    #
+    # @return [Integer] limit
+
+    def self.limit
+      @limit || Navvy.configuration.job_limit
+    end
+
+    ##
+    # If and how long the jobs should be kept. Will use the value stored in
+    # Navvy.configuration (defaults to false), or -- for backwards
+    # compatibility -- Navvy::Job.keep.
+    #
+    # @return [Fixnum, true, false] keep
+
+    def self.keep
+      @keep || Navvy.configuration.keep_jobs
+    end
+
+    ##
+    # How often should a job be retried? Will use the value stored in
+    # Navvy.configuration (defaults to 24), or -- for backwards compatibility
+    # -- Navvy::Job.max_attempts.
+    #
+    # @return [Fixnum] max_attempts
+
+    def self.max_attempts
+      @max_attempts || Navvy.configuration.max_attempts
+    end
+
+    ##
+    # Should the job be kept? Will calculate if the keeptime has passed if
+    # @keep is a Fixnum. Otherwise, it'll just return the @keep value since
+    # it's probably a boolean.
+    #
+    # @return [true, false] keep
+
+    def self.keep?
+      return (Time.now + self.keep) >= Time.now if self.keep.is_a? Fixnum
+      self.keep
+    end
+
+    ##
+    # Run the job. Will delete the Navvy::Job record and return its return
+    # value if it runs successfully unless Navvy::Job.keep is set. If a job
+    # fails, it'll call Navvy::Job#failed and pass the exception message.
+    # Failed jobs will _not_ get deleted.
+    #
+    # @example
+    #   job = Navvy::Job.next # finds the next available job in the queue
+    #   job.run               # runs the job and returns the job's return value
+    #
+    # @return [String] return value or exception message of the called method.
+
+    def run
+      begin
+        started
+        result = constantize(object).send(method_name, *args).inspect
+        Navvy::Job.keep? ? completed(result) : destroy
+        result
+      rescue Exception => exception
+        failed(exception.message)
+      end
+    end
+
+    ##
+    # Retry the current job. Will add self to the queue again, giving the clone
+    # a parend_id equal to self.id. Also, the priority of the new job will be
+    # the same as its parent's and it'll set the :run_at date to N ** 4, where
+    # N is the times_failed count.
+    #
+    # @return [Navvy::Job] job the new job it created.
+
+    def retry
+      self.class.enqueue(
+        object,
+        method_name,
+        *(args << {
+          :job_options => {
+            :parent_id => parent_id || id,
+            :run_at => Time.now + times_failed ** 4,
+            :priority => priority
+          }
+        })
+      )
+    end
+
+    ##
+    # Check if the job has been run.
+    #
+    # @return [true, false] ran
+
+    def ran?
+      completed? || failed?
+    end
+
+    ##
+    # Check how long it took for a job to complete or fail.
+    #
+    # @return [Time, Integer] time the time it took.
+
+    def duration
+      ran? ? (completed_at || failed_at) - started_at : 0
+    end
+
+    ##
+    # Check if completed_at is set.
+    #
+    # @return [true, false] set?
+
+    def completed_at?
+      !completed_at.nil?
+    end
+
+    ##
+    # Check if failed_at is set.
+    #
+    # @return [true, false] set?
+
+    def failed_at?
+      !failed_at.nil?
+    end
+
+    ##
+    # Get the job arguments as an array.
+    #
+    # @return [array] arguments
+
+    def args
+      arguments.is_a?(Array) ? arguments : YAML.load(arguments)
+    end
+
+    ##
+    # Get the job status
+    #
+    # @return [:pending, :completed, :failed] status
+
+    def status
+      return :completed if completed?
+      return :failed if failed?
+      :pending
+    end
+
+    alias_method :completed?, :completed_at?
+    alias_method :failed?,    :failed_at?
+
+  private
+
+    ##
+    # Turn a constant with potential namespacing into an object
+    #
+    # @return [Class] class
+
+    def constantize(str)
+      names = str.split('::')
+      names.shift if names.empty? || names.first.empty?
+      constant = Object
+      names.each do |name|
+        constant = constant.const_defined?(name) ? constant.const_get(name) : constant.const_missing(name)
+      end
+      constant
+    end
+  end
+end

data/lib/navvy/job/active_record.rb

@@ -0,0 +1,136 @@
+require 'active_record'
+
+module Navvy
+  class Job < ActiveRecord::Base
+
+    ##
+    # Add a job to the job queue.
+    #
+    # @param [Object] object the object you want to run a method from
+    # @param [Symbol, String] method_name the name of the method you want to run
+    # @param [*] arguments optional arguments you want to pass to the method
+    #
+    # @return [Job, false] created Job or false if failed
+
+    def self.enqueue(object, method_name, *args)
+      options = {}
+      if args.last.is_a?(Hash)
+        options = args.last.delete(:job_options) || {}
+         args.pop if args.last.empty?
+      end
+
+      create(
+        :object =>      object.to_s,
+        :method_name => method_name.to_s,
+        :arguments =>   args.to_yaml,
+        :priority =>    options[:priority] || 0,
+        :parent_id =>   options[:parent_id],
+        :run_at =>      options[:run_at] || Time.now,
+        :created_at =>  Time.now
+      )
+    end
+
+    ##
+    # Find the next available jobs in the queue. This will not include failed
+    # jobs (where :failed_at is not nil) and jobs that should run in the future
+    # (where :run_at is greater than the current time).
+    #
+    # @param [Integer] limit the limit of jobs to be fetched. Defaults to
+    # Navvy::Job.limit
+    #
+    # @return [array, nil] the next available jobs in an array or nil if no
+    # jobs were found.
+
+    def self.next(limit = self.limit)
+      all(
+        :conditions => [
+          "#{connection.quote_column_name('failed_at')} IS NULL AND #{connection.quote_column_name('completed_at')} IS NULL AND #{connection.quote_column_name('run_at')} <= ?",
+          Time.now
+        ],
+        :limit =>         limit,
+        :order =>         'priority desc, created_at'
+      )
+    end
+
+    ##
+    # Clean up jobs that we don't need to keep anymore. If Navvy::Job.keep is
+    # false it'll delete every completed job, if it's a timestamp it'll only
+    # delete completed jobs that have passed their keeptime.
+    #
+    # @return [true, false] delete_all the result of the delete_all call
+
+    def self.cleanup
+      if keep.is_a? Fixnum
+        delete_all([
+          "#{connection.quote_column_name('completed_at')} <= ?",
+          keep.ago
+        ])
+      else
+        delete_all(
+          "#{connection.quote_column_name('completed_at')} IS NOT NULL"
+        ) unless keep?
+      end
+    end
+
+    ##
+    # Mark the job as started. Will set started_at to the current time.
+    #
+    # @return [true, false] update_attributes the result of the
+    # update_attributes call
+
+    def started
+      update_attributes({
+        :started_at =>  Time.now
+      })
+    end
+
+    ##
+    # Mark the job as completed. Will set completed_at to the current time and
+    # optionally add the return value if provided.
+    #
+    # @param [String] return_value the return value you want to store.
+    #
+    # @return [true, false] update_attributes the result of the
+    # update_attributes call
+
+    def completed(return_value = nil)
+      update_attributes({
+        :completed_at =>  Time.now,
+        :return =>        return_value
+      })
+    end
+
+    ##
+    # Mark the job as failed. Will set failed_at to the current time and
+    # optionally add the exception message if provided. Also, it will retry
+    # the job unless max_attempts has been reached.
+    #
+    # @param [String] exception the exception message you want to store.
+    #
+    # @return [true, false] update_attributes the result of the
+    # update_attributes call
+
+    def failed(message = nil)
+      self.retry unless times_failed >= self.class.max_attempts
+      update_attributes(
+        :failed_at => Time.now,
+        :exception => message
+      )
+    end
+
+    ##
+    # Check how many times the job has failed. Will try to find jobs with a
+    # parent_id that's the same as self.id and count them
+    #
+    # @return [Integer] count the amount of times the job has failed
+
+    def times_failed
+      i = parent_id || id
+      self.class.count(
+        :conditions => "(#{connection.quote_column_name('id')} = '#{i}' OR #{connection.quote_column_name('parent_id')} = '#{i}') AND #{connection.quote_column_name('failed_at')} IS NOT NULL"
+      )
+    end
+  end
+end
+
+require 'navvy/job'