resque-future 0.1.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Rodrigo Kochenburger
+
+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.rdoc

@@ -0,0 +1,23 @@
+= resque-future
+
+Description goes here.
+
+== 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 rakefile, version, or history.
+  (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.
+
+== TODO
+
+* Raise an error when trying to enqueue a item with existing UUID
+* Auto retry generating another UUID if an error is raised when auto generated it
+* Store enqueued_at too
+
+== Copyright
+
+Copyright (c) 2010 Rodrigo Kochenburger. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,49 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name        = "resque-future"
+    gem.summary     = "Resque plugin that allows querying future jobs for it's result"
+    gem.description = <<-DESC
+Resque plugin that allows querying future jobs for it's result, for example:
+
+  job = Resque.enqueue_future(MixerWorker, "yeah")
+  # store job.uuid somewhere
+  
+  # Later on
+  job = Resque.get_future_job(uuid)
+  job.ready?
+  job.result
+  job.finished_at
+    DESC
+    gem.email       = "divoxx@gmail.com"
+    gem.homepage    = "http://github.com/divoxx/resque-future"
+    gem.authors     = ["Rodrigo Kochenburger"]
+    gem.add_dependency "resque", ">= 1.10.0"
+    gem.add_development_dependency "rspec", ">= 1.2.9"
+    gem.add_development_dependency "yard", ">= 0"
+    gem.add_development_dependency "redis", ">= 2.0"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec)
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  task :yardoc do
+    abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
+  end
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/resque-future.rb

@@ -0,0 +1 @@
+load "resque_future.rb"

data/lib/resque/future.rb

@@ -0,0 +1,11 @@
+module Resque
+  # This is the module that should be included in your worker to make it's jobs FutureJob instances.
+  module Future
+    # Wraps the perform method, saving the return statement for the future job.
+    # @see ResqueFuture::FutureJob
+    def around_perform_future(uuid, *args, &block)
+      job = ResqueFuture::FutureJob.get(@queue, uuid)
+      job.result = yield
+    end
+  end
+end

data/lib/resque_future.rb

@@ -0,0 +1,26 @@
+unless defined?(Resque)
+  puts "ResqueFuture requires Resque, please require \"resque\""
+  exit(1)
+end
+
+require "resque_future/future_job"
+require "resque/future"
+
+# Extend Resque namespace to add enqueue_future method.
+module Resque
+  # Same as enqueue excepts it return a FutureJob allowing for later querying the return
+  # value of the processed job.
+  def enqueue_future(klass, *args)
+    enqueue_future_with_uuid(nil, klass, *args)
+  end
+  
+  # Same as enqueue_future excepts it allows manually setting the UUID for the future object.
+  def enqueue_future_with_uuid(uuid, klass, *args)
+    ResqueFuture::FutureJob.create(queue_from_class(klass), uuid, klass, *args)
+  end
+  
+  # Get a future job
+  def get_future_job(uuid, klass)
+    ResqueFuture::FutureJob.get(queue_from_class(klass), uuid)
+  end
+end

data/lib/resque_future/future_job.rb

@@ -0,0 +1,133 @@
+require "digest/sha2"
+require "time"
+
+module ResqueFuture
+  # A FutureJob is a job schedule to run in the future that you still want to be able to
+  # track it's result and status.
+  class FutureJob < Resque::Job
+    attr_reader :uuid
+    
+    # Override constructor to receive an UUID
+    def initialize(queue, uuid, payload)
+      @uuid = uuid || self.generate_uuid
+      payload["args"].unshift(@uuid)
+      super(queue, payload)
+      set_result('enqueued_at' => Time.now.utc)
+    end
+  
+    # Override Job.create method so that it returns a instance of FutureJob allowing
+    # for late querying for the result.
+    def self.create(queue, uuid, klass, *args)
+      job = self.new(queue, uuid, 'class' => klass, 'args' => args)
+      super(queue, klass, *args)
+      job.persist
+      job
+    end
+    
+    # Query for a FutureJob using it's UUID
+    def self.get(queue, uuid)
+      if payload = self.payload(uuid)
+        self.new(queue, uuid, payload)
+      end
+    end
+    
+    # Persist the job information into redis
+    def persist
+      redis.set(self.payload_key, encode(self.payload))
+    end
+    
+    # Returns true/false if the job has been processed yet
+    def ready?
+      self.result_payload(true).has_key?('finished_at')
+    end
+    
+    # Returns true/false whether it is waiting in the queue or being processed
+    def processing?
+      self.result_payload(true).has_key?('started_at') && !self.result_payload(true).has_key?('finished_at')
+    end
+    
+    # Perform the job
+    def perform
+      set_result("started_at" => Time.now.utc)
+      super
+      set_result("finished_at" => Time.now.utc)
+    end
+    
+    # Returns the result for the job
+    def result
+      self.result_payload["result"] if self.result_payload
+    end
+    
+    def result=(result_value)
+      set_result("result" => result_value)
+    end
+    
+    # Returns the time that the result was written to redis and the job finished processing.
+    def finished_at
+      Time.parse(self.result_payload["finished_at"]) if self.result_payload && self.result_payload["finished_at"]
+    end
+    
+    # Returns the time that the job was enqueued
+    def enqueued_at
+      Time.parse(self.result_payload["enqueued_at"]) if self.result_payload && self.result_payload["enqueued_at"]
+    end
+    
+    # Returns the time that the job has started processing
+    def started_at
+      Time.parse(self.result_payload["started_at"]) if self.result_payload && self.result_payload["started_at"]
+    end
+    
+  protected
+    # Generate a unique identifier
+    def generate_uuid
+      Digest::SHA2.hexdigest("#{@queue}#{encode(payload)}#{Time.now.to_i}")
+    end
+    
+    # Return the redis payload key for the given UUID
+    def self.payload_key(uuid)
+      "meta:#{uuid}:payload"
+    end
+    
+    # Return the payload for the given UUID
+    def self.payload(uuid)
+      decode(redis.get(self.payload_key(uuid)))
+    end
+    
+    # Return the redis payload key for this object
+    def payload_key
+      self.class.payload_key(@uuid)
+    end
+    
+    # Return and cache the payload
+    def payload
+      @payload ||= (super || self.class.payload(@uuid))
+    end
+
+    # Return the redis result key for the given UUID
+    def self.result_payload_key(uuid)
+      "meta:#{uuid}:result_payload"      
+    end
+    
+    # Return the result payload for the given UUID
+    def self.result_payload(uuid)
+      decode(redis.get(self.result_payload_key(uuid)))
+    end
+
+    # Return the redis result key for this object
+    def result_payload_key
+      self.class.result_payload_key(@uuid)
+    end
+    
+    # Return and cache the result payload
+    def result_payload(force = false)
+      @result_payload = nil if force
+      @result_payload ||= self.class.result_payload(@uuid)
+    end
+    
+    def set_result(hsh)
+      hsh = (self.result_payload || {}).merge(hsh)
+      redis.set(self.result_payload_key, encode(hsh))
+      self.result_payload(true)
+    end
+  end
+end

data/resque-future.gemspec

@@ -0,0 +1,73 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{resque-future}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Rodrigo Kochenburger"]
+  s.date = %q{2011-03-17}
+  s.description = %q{Resque plugin that allows querying future jobs for it's result, for example:
+
+  job = Resque.enqueue_future(MixerWorker, "yeah")
+  # store job.uuid somewhere
+  
+  # Later on
+  job = Resque.get_future_job(uuid)
+  job.ready?
+  job.result
+  job.finished_at
+}
+  s.email = %q{divoxx@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+    "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+    "LICENSE",
+    "README.rdoc",
+    "Rakefile",
+    "VERSION",
+    "lib/resque-future.rb",
+    "lib/resque/future.rb",
+    "lib/resque_future.rb",
+    "lib/resque_future/future_job.rb",
+    "resque-future.gemspec",
+    "spec/resque_future/future_job_spec.rb",
+    "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/divoxx/resque-future}
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.5.2}
+  s.summary = %q{Resque plugin that allows querying future jobs for it's result}
+  s.test_files = [
+    "spec/resque_future/future_job_spec.rb",
+    "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<resque>, [">= 1.10.0"])
+      s.add_development_dependency(%q<rspec>, [">= 1.2.9"])
+      s.add_development_dependency(%q<yard>, [">= 0"])
+      s.add_development_dependency(%q<redis>, [">= 2.0"])
+    else
+      s.add_dependency(%q<resque>, [">= 1.10.0"])
+      s.add_dependency(%q<rspec>, [">= 1.2.9"])
+      s.add_dependency(%q<yard>, [">= 0"])
+      s.add_dependency(%q<redis>, [">= 2.0"])
+    end
+  else
+    s.add_dependency(%q<resque>, [">= 1.10.0"])
+    s.add_dependency(%q<rspec>, [">= 1.2.9"])
+    s.add_dependency(%q<yard>, [">= 0"])
+    s.add_dependency(%q<redis>, [">= 2.0"])
+  end
+end
+

data/spec/resque_future/future_job_spec.rb

@@ -0,0 +1,140 @@
+require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+include ResqueFuture
+
+describe FutureJob do
+  before :each do
+    @queue    = :some_queue
+    @klass    = SomeWorker
+    @uuid     = "some_uuid"
+    @args     = [:some_argument]
+    @job_mock = mock(:future_job, :persist => true)
+  end
+  
+  describe "creating a future job" do
+    def create_job
+      FutureJob.create(@queue, @uuid, @klass, *@args)
+    end
+    
+    it "should create a new instance" do
+      FutureJob.should_receive(:new).with(@queue, @uuid, {"class" => @klass, "args" => @args}).and_return(@job_mock)
+      create_job
+    end
+  end
+  
+  describe "instantiating a future job" do
+    def instantiate_job
+      FutureJob.new(@queue, @uuid, {"class" => @klass, "args" => @args})
+    end
+    
+    it "should set attributes" do
+      job = instantiate_job
+      %w(queue payload uuid).should be_all { |attr| job.instance_variable_get("@#{attr}") }
+    end
+    
+    it "should autogenerate uuid if not provided" do
+      @uuid = nil
+      job = instantiate_job
+      job.uuid.should_not be_nil
+      job.uuid.should_not eql("some_uuid")
+    end
+  end
+  
+  shared_examples_for "querying a processed job" do
+    it "should be ready" do
+      @job.should be_ready
+    end
+    
+    it "should not be processing" do
+      @job.should_not be_processing
+    end
+    
+    it "should have a result" do
+      @job.result.should_not be_nil
+      @job.result.should be(true)
+    end
+    
+    it "should have finished_at set" do
+      @job.finished_at.should_not be_nil
+      @job.finished_at.should be_instance_of(Time)
+    end
+    
+    it "should have enqueued_at set" do
+      @job.enqueued_at.should_not be_nil
+      @job.enqueued_at.should be_instance_of(Time)
+    end
+    
+    it "should have started_at set" do
+      @job.started_at.should_not be_nil
+      @job.started_at.should be_instance_of(Time)
+    end
+  end
+  
+  describe "querying a processed job with same instance" do 
+    before :each do
+      @job = FutureJob.create(@queue, @uuid, @klass, *@args)
+      @job.perform
+    end
+
+    it_should_behave_like "querying a processed job"
+  end
+  
+  describe "querying a processed job with different instance" do
+    before :each do
+      orig_job = FutureJob.create(@queue, @uuid, @klass, *@args)
+      orig_job.perform
+      @job = FutureJob.get(@queue, @uuid)
+    end
+
+    it_should_behave_like "querying a processed job"
+  end
+  
+  shared_examples_for "querying a unprocessed job" do
+    it "should be ready" do
+      @job.should_not be_ready
+    end
+    
+    it "should be processing" do
+      @job.should be_processing
+    end
+    
+    it "should not have a result" do
+      @job.result.should be_nil
+    end
+    
+    it "should not have finished_at set" do
+      @job.finished_at.should be_nil
+    end
+    
+    it "should not have started_at set" do
+      @job.started_at.should be_nil
+    end
+    
+    it "should have enqueued_at set" do
+      @job.enqueued_at.should_not be_nil
+      @job.enqueued_at.should_not be_instance_of(Time)
+    end    
+  end
+  
+  describe "querying a unprocessed job with same instance" do 
+    before :each do
+      @job = FutureJob.create(@queue, @uuid, @klass, *@args)
+    end
+
+    it_should_behave_like "querying a unprocessed job"
+  end
+  
+  describe "querying a unprocessed job with different instance" do
+    before :each do
+      orig_job = FutureJob.create(@queue, @uuid, @klass, *@args)
+      @job = FutureJob.get(@queue, @uuid)
+    end
+
+    it_should_behave_like "querying a unprocessed job"
+  end
+  
+  describe "querying an unexisting job" do
+    it "should return nil" do
+      FutureJob.get(@queue, "unexisting uuid").should be_nil
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,22 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require "resque"
+require 'resque_future'
+require 'rspec'
+
+Resque.redis = "redis://localhost/1"
+
+class SomeWorker
+  extend Resque::Future
+  @queue = :some_queue
+  
+  def self.perform(uuid, some_arg)
+    return true
+  end
+end
+
+RSpec.configure do |config|
+  config.before(:each) do
+    Resque.redis.flushdb
+  end
+end

metadata

@@ -0,0 +1,123 @@
+--- !ruby/object:Gem::Specification 
+name: resque-future
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Rodrigo Kochenburger
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-03-17 00:00:00 -03: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 
+        version: 1.10.0
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.2.9
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: redis
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "2.0"
+  type: :development
+  version_requirements: *id004
+description: |
+  Resque plugin that allows querying future jobs for it's result, for example:
+  
+    job = Resque.enqueue_future(MixerWorker, "yeah")
+    # store job.uuid somewhere
+    
+    # Later on
+    job = Resque.get_future_job(uuid)
+    job.ready?
+    job.result
+    job.finished_at
+
+email: divoxx@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- .document
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- lib/resque-future.rb
+- lib/resque/future.rb
+- lib/resque_future.rb
+- lib/resque_future/future_job.rb
+- resque-future.gemspec
+- spec/resque_future/future_job_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/divoxx/resque-future
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.5.2
+signing_key: 
+specification_version: 3
+summary: Resque plugin that allows querying future jobs for it's result
+test_files: 
+- spec/resque_future/future_job_spec.rb
+- spec/spec_helper.rb