navvy 0.0.0 → 0.1.0

data/README.textile

@@ -1,9 +1,17 @@
 h1. Navvy
 
-Navvy is a simple background job processor inspired by "delayed_job":http://github.com/tobi/delayed_job, but aiming for database agnosticism. 
+Navvy is a simple background job processor inspired by "delayed_job":http://github.com/tobi/delayed_job, but aiming for database agnosticism. Currently Navvy supports ActiveRecord, MongoMapper and Sequel but it's extremely easy to write an adapter for your favorite ORM. Also, It completely supports Rails Edge.
 
 ??“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
+
+There's an "Installation Guide":http://wiki.github.com/jeffkreeftmeijer/navvy/installation (also for "Rails 3":http://wiki.github.com/jeffkreeftmeijer/navvy/installation-on-rails-edge) and a "Getting Started Guide":http://wiki.github.com/jeffkreeftmeijer/navvy/getting-started to put you on the right track. Any questions? Don't hesitate to "ask":http://github.com/inbox/new/jeffkreeftmeijer.
+
+h2. Contributing
+
+Found any issues? Have a great idea? Want to help? Great! Create an issue "issue":http://github.com/jeffkreeftmeijer/navvy/issues for it, or even better; "fork the project":http://github.com/jeffkreeftmeijer/navvy/fork. Pull requests are always welcome. :)
+
 h2. License
 
 Copyright (c) 2009 Jeff Kreeftmeijer, released under the MIT license

data/Rakefile

@@ -10,12 +10,13 @@ begin
     gem.email = "jeff@kreeftmeijer.nl"
     gem.homepage = "http://github.com/jeffkreeftmeijer/navvy"
     gem.authors = ["Jeff Kreeftmeijer"]
-    gem.add_dependency             "mongo_mapper",          ">= 0.6.10"
     gem.add_development_dependency "rspec",                 ">= 1.2.9"
     gem.add_development_dependency "yard",                  ">= 0.5.2"
     gem.add_development_dependency "metric_fu",             ">= 1.1.6"
     gem.add_development_dependency "machinist",             ">= 1.0.6"
+    gem.add_development_dependency "mongo_mapper",          ">= 0.6.10"
     gem.add_development_dependency "machinist_mongomapper", ">= 0.9.7"
+    gem.add_development_dependency "sequel",                ">= 3.8.0"
   end
   Jeweler::GemcutterTasks.new
 rescue LoadError
@@ -23,9 +24,25 @@ rescue LoadError
 end
 
 require 'spec/rake/spectask'
-Spec::Rake::SpecTask.new(:spec) do |spec|
-  spec.libs << 'lib' << 'spec'
-  spec.spec_files = FileList['spec/**/*_spec.rb']
+
+task :spec do
+  ['spec:active_record', 'spec:mongo_mapper', 'spec:sequel'].each do |spec|
+    Rake::Task[spec].invoke
+  end
+end
+
+namespace :spec do
+  Spec::Rake::SpecTask.new(:active_record) do |spec|
+    spec.spec_files = FileList['spec/job/active_record_spec.rb', 'spec/*_spec.rb']
+  end
+
+  Spec::Rake::SpecTask.new(:mongo_mapper) do |spec|
+    spec.spec_files = FileList['spec/job/mongo_mapper_spec.rb', 'spec/*_spec.rb']
+  end
+
+  Spec::Rake::SpecTask.new(:sequel) do |spec|
+    spec.spec_files = FileList['spec/job/sequel_spec.rb', 'spec/*_spec.rb']
+  end
 end
 
 Spec::Rake::SpecTask.new(:rcov) do |spec|
@@ -35,7 +52,6 @@ Spec::Rake::SpecTask.new(:rcov) do |spec|
 end
 
 task :spec => :check_dependencies
-
 task :default => :spec
 
 begin

data/VERSION

@@ -1 +1 @@
-0.0.0
+0.1.0

data/generators/navvy/navvy_generator.rb

@@ -0,0 +1,15 @@
+class NavvyGenerator < Rails::Generator::Base
+  def manifest
+    record do |m|
+      options = {
+        :migration_file_name => 'create_jobs'
+      }
+      
+      m.migration_template 'migration.rb', 'db/migrate', options
+    end
+  end
+  
+  def banner
+    "Usage: #{$0} #{spec.name}"
+  end
+end

data/generators/navvy/templates/migration.rb

@@ -0,0 +1,20 @@
+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.string    :return
+      t.string    :exception
+      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/lib/generators/navvy_generator.rb

@@ -0,0 +1,20 @@
+require 'rails/generators/migration'
+class NavvyGenerator < Rails::Generators::Base
+  include Rails::Generators::Migration
+  
+  def self.source_root
+    File.join(File.dirname(__FILE__), '..', '..', 'generators', 'navvy', 'templates')
+  end
+  
+  def install_navvy
+    migration_template(
+      'migration.rb',
+      'db/migrate/create_navvy_table.rb'
+    )
+  end
+  
+  protected
+    def next_migration_number(dirname) #:nodoc:
+      "%.3d" % (current_migration_number(dirname) + 1)
+    end
+end

data/lib/navvy.rb

@@ -1,2 +1,2 @@
-require File.expand_path(File.dirname(__FILE__) + '/navvy/job')
-require File.expand_path(File.dirname(__FILE__) + '/navvy/worker')
+require File.expand_path(File.dirname(__FILE__) + '/navvy/worker')
+require File.expand_path(File.dirname(__FILE__) + '/navvy/log')

data/lib/navvy/job/active_record.rb

@@ -0,0 +1,212 @@
+require 'rubygems'
+require 'active_record'
+require 'yaml'
+
+module Navvy
+  class Job < ActiveRecord::Base
+    class << self
+      attr_writer :limit
+      attr_accessor :keep
+    end
+
+    ##
+    # Default limit of jobs to be fetched
+    #
+    # @return [Integer] limit
+
+    def self.limit
+      @limit || 100
+    end
+
+    ##
+    # Should the job be kept?
+    #
+    # @return [true, false] keep
+
+    def self.keep?
+      keep = (@keep || false)
+      return keep.from_now >= Time.now if keep.is_a? Fixnum
+      keep
+    end
+
+    ##
+    # 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 [true, false]
+
+    def self.enqueue(object, method_name, *args)
+      create(
+        :object =>      object.to_s,
+        :method_name => method_name.to_s,
+        :arguments =>   args,
+        :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 =>    [
+          '`failed_at` IS NULL AND `completed_at` IS NULL AND `run_at` <= ?',
+          Time.now
+        ],
+        :limit =>         limit,
+        :order =>         '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([
+          '`completed_at` <= ?',
+          keep.ago
+        ])
+      else
+        delete_all(
+          '`completed_at` IS NOT NULL'
+        ) unless keep?
+      end
+    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 update the Navvy::Job record to include the exception
+    # message it sent back and set the :failed_at date. Failed jobs never 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 of the called method.
+
+    def run
+      begin
+        update_attributes(:started_at => Time.now)
+        if args.empty?
+          result = object.constantize.send(method_name)
+        else
+          result = object.constantize.send(method_name, *args)
+        end        
+        Navvy::Job.keep? ? completed : destroy
+        result
+      rescue Exception => exception
+        failed(exception.message)
+      end
+    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.
+    #
+    # @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)
+      update_attributes({
+        :failed_at => Time.now,
+        :exception => message
+      })
+    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?
+  end
+end

data/lib/navvy/job/mongo_mapper.rb

@@ -4,29 +4,59 @@ require 'mongo_mapper'
 module Navvy
   class Job
     include MongoMapper::Document
+    class << self
+      attr_writer :limit
+      attr_accessor :keep
+    end
 
-    key :object,    String
-    key :method,    Symbol
-    key :arguments, Array
-    key :exception, String
-    key :run_at,    Time
-    key :failed_at, Time
+    key :object,        String
+    key :method_name,   Symbol
+    key :arguments,     Array
+    key :return,        String
+    key :exception,     String
+    key :created_at,    Time
+    key :run_at,        Time
+    key :started_at,    Time
+    key :completed_at,  Time
+    key :failed_at,     Time
+    
+    ##
+    # Default limit of jobs to be fetched
+    #
+    # @return [Integer] limit
+
+    def self.limit
+      @limit || 100
+    end
+
+    ##
+    # Should the job be kept?
+    #
+    # @return [true, false] keep
+
+    def self.keep?
+      keep = (@keep || false)
+      return keep.from_now >= Time.now if keep.is_a? Fixnum
+      keep
+    end
 
     ##
     # Add a job to the job queue.
     #
     # @param [Object] object the object you want to run a method from
-    # @param [Symbol, String] method the name of the method you want to run
+    # @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 [true, false] 
+    # @return [true, false]
 
-    def self.enqueue(object, method, *args)
+    def self.enqueue(object, method_name, *args)
       create(
-        :object =>    object.name,
-        :method =>    method.to_sym,
-        :run_at =>    Time.now,
-        :arguments => args
+        :object =>      object.to_s,
+        :method_name => method_name.to_sym,
+        :arguments =>   args,
+        :run_at =>      Time.now,
+        :created_at =>  Time.now
       )
     end
 
@@ -35,25 +65,47 @@ module Navvy
     # 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 
+    # @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
-    # jobsn were found.
+    # jobs were found.
 
     def self.next(limit = self.limit)
       all(
-        :failed_at => nil,
-        :run_at => {'$lte', Time.now},
-        :limit => limit
+        :failed_at =>     nil,
+        :completed_at =>  nil,
+        :run_at =>        {'$lte', Time.now},
+        :limit =>         limit,
+        :order =>         '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(
+          :completed_at => {'$lte' => keep.ago}
+        )
+      else
+        delete_all(
+          :completed_at => {'$ne' => nil}
+        ) unless keep?
+      end
+    end
+
     ##
     # Run the job. Will delete the Navvy::Job record and return its return
-    # value if it runs successfully. If a job fails, it'll update the
-    # Navvy::Job record to include the exception message it sent back and set
-    # the :failed_at date. Failed jobs don't get deleted.
+    # value if it runs successfully unless Navvy::Job.keep is set. If a job
+    # fails, it'll update the Navvy::Job record to include the exception
+    # message it sent back and set the :failed_at date. Failed jobs never get
+    # deleted.
     #
     # @example
     #   job = Navvy::Job.next # finds the next available job in the queue
@@ -63,15 +115,82 @@ module Navvy
 
     def run
       begin
-        result = object.constantize.send(method)
-        destroy
+        update_attributes(:started_at => Time.now)
+        if args.empty?
+          result = object.constantize.send(method_name)
+        else
+          result = object.constantize.send(method_name, *args)
+        end
+        Navvy::Job.keep? ? completed : destroy
         result
       rescue Exception => exception
-        update_attributes({
-          :exception => exception.message,
-          :failed_at => Time.now
-        })
+        failed(exception.message)
       end
     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.
+    #
+    # @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)
+      update_attributes({
+        :failed_at => Time.now,
+        :exception => message
+      })
+    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
+    
+    ##
+    # 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?
+    alias_method :args,       :arguments
   end
 end