activejob 4.2.0.beta1 → 4.2.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f5b4155049f893704d35f9712dacadac5c6a63a3
-  data.tar.gz: c072445cde94c55babc2a55489e877ff7930529e
+  metadata.gz: a1959ada2768247a24b82a496e71ea52185e0f44
+  data.tar.gz: b0144f92ff3b44c8cecb1d94ee55d668911f9a42
 SHA512:
-  metadata.gz: 563242f9567f12e8cb4ecb8204fc9a0956c93507ddea5eca3d3fe824157aca34afacfd47eff94e73aadadedbfb8972e058af16cb226f9ca53959cab3b8cf2de3
-  data.tar.gz: fbc34e79c27f8ce715d350c740b149b8fe02decf1d3175a6c1ab3a859b93caf963a094c1c5c5d01c6b22f8f5bb9cd093504f2263d10f4ca50b0319ef334f66c6
+  metadata.gz: 06e70d712da50b7a14d683f3c53f4a57e0d88eada98c9a720d5d57be0e364f82b2b9bf6e53ad5bcbaf503e0b2fdde3fcbca49cf26fff0ee9cbebad6442a3e5ee
+  data.tar.gz: 853811e9c3e1102f8beed9e8a9b02ccb1346524c57125dce72dcd6b87b80c3810130bd287dd81467b27a34e2bd499edea1175c754f7057adf94684ffb41879b1

data/README.md

@@ -2,7 +2,7 @@
 
 Active Job is a framework for declaring jobs and making them run on a variety
 of queueing backends. These jobs can be everything from regularly scheduled
-clean-ups, billing charges, or mailings. Anything that can be chopped up into
+clean-ups, to billing charges, to mailings. Anything that can be chopped up into
 small units of work and run in parallel, really.
 
 It also serves as the backend for ActionMailer's #deliver_later functionality
@@ -24,9 +24,9 @@ Set the queue adapter for Active Job:
 
 ``` ruby
 ActiveJob::Base.queue_adapter = :inline # default queue adapter
-# Adapters currently supported: :backburner, :delayed_job, :qu, :que, :queue_classic,
-#                               :resque, :sidekiq, :sneakers, :sucker_punch
 ```
+Note: To learn how to use your preferred queueing backend see its adapter
+documentation at ActiveJob::QueueAdapters.
 
 Declare a job like so:
 
@@ -43,15 +43,15 @@ end
 Enqueue a job like so:
 
 ```ruby
-MyJob.enqueue record  # Enqueue a job to be performed as soon the queueing system is free.
+MyJob.perform_later record  # Enqueue a job to be performed as soon the queueing system is free.
 ```
 
 ```ruby
-MyJob.enqueue_at Date.tomorrow.noon, record  # Enqueue a job to be performed tomorrow at noon.
+MyJob.set(wait_until: Date.tomorrow.noon).perform_later(record)  # Enqueue a job to be performed tomorrow at noon.
 ```
 
 ```ruby
-MyJob.enqueue_in 1.week, record # Enqueue a job to be performed 1 week from now.
+MyJob.set(wait: 1.week).perform_later(record) # Enqueue a job to be performed 1 week from now.
 ```
 
 That's it!
@@ -88,18 +88,9 @@ by default has been mixed into Active Record classes.
 
 ## Supported queueing systems
 
-We currently have adapters for:
-
-* [Backburner](https://github.com/nesquena/backburner)
-* [Delayed Job](https://github.com/collectiveidea/delayed_job)
-* [Qu](https://github.com/bkeepers/qu)
-* [Que](https://github.com/chanks/que)
-* [QueueClassic](https://github.com/ryandotsmith/queue_classic)
-* [Resque 1.x](https://github.com/resque/resque)
-* [Sidekiq](https://github.com/mperham/sidekiq)
-* [Sneakers](https://github.com/jondot/sneakers)
-* [Sucker Punch](https://github.com/brandonhilkert/sucker_punch)
-
+Active Job has built-in adapters for multiple queueing backends (Sidekiq,
+Resque, Delayed Job and others). To get an up-to-date list of the adapters
+see the API Documentation for [ActiveJob::QueueAdapters](http://api.rubyonrails.org/classes/ActiveJob/QueueAdapters.html).
 
 ## Auxiliary gems
 

data/lib/active_job.rb

@@ -30,4 +30,8 @@ module ActiveJob
   extend ActiveSupport::Autoload
 
   autoload :Base
-end
+  autoload :QueueAdapters
+  autoload :ConfiguredJob
+  autoload :TestCase
+  autoload :TestHelper
+end

data/lib/active_job/arguments.rb

@@ -1,14 +1,25 @@
 module ActiveJob
+  # Raised when an exception is raised during job arguments deserialization.
+  #
+  # Wraps the original exception raised as +original_exception+.
   class DeserializationError < StandardError
     attr_reader :original_exception
 
-    def initialize(e)
-      super ("Error while trying to deserialize arguments: #{e.message}")
+    def initialize(e) #:nodoc:
+      super("Error while trying to deserialize arguments: #{e.message}")
       @original_exception = e
       set_backtrace e.backtrace
     end
   end
 
+  # Raised when an unsupported argument type is being set as job argument. We
+  # currently support NilClass, Fixnum, Float, String, TrueClass, FalseClass,
+  # Bignum and object that can be represented as GlobalIDs (ex: Active Record).
+  # Also raised if you set the key for a Hash something else than a string or
+  # a symbol.
+  class SerializationError < ArgumentError
+  end
+
   module Arguments
     extend self
     TYPE_WHITELIST = [ NilClass, Fixnum, Float, String, TrueClass, FalseClass, Bignum ]
@@ -19,43 +30,75 @@ module ActiveJob
 
     def deserialize(arguments)
       arguments.map { |argument| deserialize_argument(argument) }
+    rescue => e
+      raise DeserializationError.new(e)
     end
 
     private
+      GLOBALID_KEY = '_aj_globalid'.freeze
+      private_constant :GLOBALID_KEY
+
       def serialize_argument(argument)
         case argument
-        when GlobalID::Identification
-          argument.global_id.to_s
         when *TYPE_WHITELIST
           argument
+        when GlobalID::Identification
+          { GLOBALID_KEY => argument.to_global_id.to_s }
         when Array
-          serialize(argument)
+          argument.map { |arg| serialize_argument(arg) }
         when Hash
-          Hash[ argument.map { |key, value| [ serialize_hash_key(key), serialize_argument(value) ] } ]
+          argument.each_with_object({}) do |(key, value), hash|
+            hash[serialize_hash_key(key)] = serialize_argument(value)
+          end
         else
-          raise "Unsupported argument type: #{argument.class.name}"
+          raise SerializationError.new("Unsupported argument type: #{argument.class.name}")
         end
       end
 
       def deserialize_argument(argument)
         case argument
+        when String
+          GlobalID::Locator.locate(argument) || argument
+        when *TYPE_WHITELIST
+          argument
         when Array
-          deserialize(argument)
+          argument.map { |arg| deserialize_argument(arg) }
         when Hash
-          Hash[ argument.map { |key, value| [ key, deserialize_argument(value) ] } ].with_indifferent_access
+          if serialized_global_id?(argument)
+            deserialize_global_id argument
+          else
+            deserialize_hash argument
+          end
         else
-          GlobalID::Locator.locate(argument) || argument
+          raise ArgumentError, "Can only deserialize primitive arguments: #{argument.inspect}"
         end
-      rescue => e
-        raise DeserializationError.new(e)
       end
 
+      def serialized_global_id?(hash)
+        hash.size == 1 and hash.include?(GLOBALID_KEY)
+      end
+
+      def deserialize_global_id(hash)
+        GlobalID::Locator.locate hash[GLOBALID_KEY]
+      end
+
+      def deserialize_hash(serialized_hash)
+        serialized_hash.each_with_object({}.with_indifferent_access) do |(key, value), hash|
+          hash[key] = deserialize_argument(value)
+        end
+      end
+
+      RESERVED_KEYS = [GLOBALID_KEY, GLOBALID_KEY.to_sym]
+      private_constant :RESERVED_KEYS
+
       def serialize_hash_key(key)
         case key
+        when *RESERVED_KEYS
+          raise SerializationError.new("Can't serialize a Hash with reserved key #{key.inspect}")
         when String, Symbol
           key.to_s
         else
-          raise "Unsupported hash key type: #{key.class.name}"
+          raise SerializationError.new("Only string and symbol hash keys may be serialized as job arguments, but #{key.inspect} is a #{key.class}")
         end
       end
   end

data/lib/active_job/base.rb

@@ -1,20 +1,19 @@
+require 'active_job/core'
 require 'active_job/queue_adapter'
 require 'active_job/queue_name'
 require 'active_job/enqueuing'
 require 'active_job/execution'
 require 'active_job/callbacks'
-require 'active_job/identifier'
 require 'active_job/logging'
 
 module ActiveJob
   class Base
-    extend QueueAdapter
-
+    include Core
+    include QueueAdapter
     include QueueName
     include Enqueuing
     include Execution
     include Callbacks
-    include Identifier
     include Logging
 
     ActiveSupport.run_load_hooks(:active_job, self)

data/lib/active_job/callbacks.rb

@@ -3,8 +3,8 @@ require 'active_support/callbacks'
 module ActiveJob
   # = Active Job Callbacks
   #
-  # Active Job provides hooks during the lifecycle of a job. Callbacks allows you to trigger
-  # logic during the lifecycle of a job. Available callbacks:
+  # Active Job provides hooks during the lifecycle of a job. Callbacks allow you
+  # to trigger logic during the lifecycle of a job. Available callbacks are:
   #
   # * <tt>before_enqueue</tt>
   # * <tt>around_enqueue</tt>
@@ -36,7 +36,7 @@ module ActiveJob
       #     def perform(video_id)
       #       Video.find(video_id).process
       #     end
-      # end
+      #   end
       #
       def before_perform(*filters, &blk)
         set_callback(:perform, :before, *filters, &blk)
@@ -55,7 +55,7 @@ module ActiveJob
       #     def perform(video_id)
       #       Video.find(video_id).process
       #     end
-      # end
+      #   end
       #
       def after_perform(*filters, &blk)
         set_callback(:perform, :after, *filters, &blk)
@@ -75,7 +75,7 @@ module ActiveJob
       #     def perform(video_id)
       #       Video.find(video_id).process
       #     end
-      # end
+      #   end
       #
       def around_perform(*filters, &blk)
         set_callback(:perform, :around, *filters, &blk)
@@ -94,7 +94,7 @@ module ActiveJob
       #     def perform(video_id)
       #       Video.find(video_id).process
       #     end
-      # end
+      #   end
       #
       def before_enqueue(*filters, &blk)
         set_callback(:enqueue, :before, *filters, &blk)
@@ -113,7 +113,7 @@ module ActiveJob
       #     def perform(video_id)
       #       Video.find(video_id).process
       #     end
-      # end
+      #   end
       #
       def after_enqueue(*filters, &blk)
         set_callback(:enqueue, :after, *filters, &blk)
@@ -134,7 +134,7 @@ module ActiveJob
       #     def perform(video_id)
       #       Video.find(video_id).process
       #     end
-      # end
+      #   end
       #
       def around_enqueue(*filters, &blk)
         set_callback(:enqueue, :around, *filters, &blk)

data/lib/active_job/configured_job.rb

@@ -0,0 +1,16 @@
+module ActiveJob
+  class ConfiguredJob #:nodoc:
+    def initialize(job_class, options={})
+      @options = options
+      @job_class = job_class
+    end
+
+    def perform_now(*args)
+      @job_class.new(*args).perform_now
+    end
+
+    def perform_later(*args)
+      @job_class.new(*args).enqueue @options
+    end
+  end
+end

data/lib/active_job/core.rb

@@ -0,0 +1,89 @@
+module ActiveJob
+  module Core
+    extend ActiveSupport::Concern
+
+    included do
+      # Job arguments
+      attr_accessor :arguments
+      attr_writer :serialized_arguments
+
+      # Timestamp when the job should be performed
+      attr_accessor :scheduled_at
+
+      # Job Identifier
+      attr_accessor :job_id
+
+      # Queue in which the job will reside.
+      attr_writer :queue_name
+    end
+
+    module ClassMethods
+      # Creates a new job instance from a hash created with +serialize+
+      def deserialize(job_data)
+        job                      = job_data['job_class'].constantize.new
+        job.job_id               = job_data['job_id']
+        job.queue_name           = job_data['queue_name']
+        job.serialized_arguments = job_data['arguments']
+        job
+      end
+
+      # Creates a job preconfigured with the given options. You can call
+      # perform_later with the job arguments to enqueue the job with the
+      # preconfigured options
+      #
+      # ==== Options
+      # * <tt>:wait</tt> - Enqueues the job with the specified delay
+      # * <tt>:wait_until</tt> - Enqueues the job at the time specified
+      # * <tt>:queue</tt> - Enqueues the job on the specified queue
+      #
+      # ==== Examples
+      #
+      #    VideoJob.set(queue: :some_queue).perform_later(Video.last)
+      #    VideoJob.set(wait: 5.minutes).perform_later(Video.last)
+      #    VideoJob.set(wait_until: Time.tomorroe).perform_later(Video.last)
+      #    VideoJob.set(queue: :some_queue, wait: 5.minutes).perform_later(Video.last)
+      #    VideoJob.set(queue: :some_queue, wait_until: Time.tomorroe).perform_later(Video.last)
+      def set(options={})
+        ConfiguredJob.new(self, options)
+      end
+    end
+
+    # Creates a new job instance. Takes as arguments the arguments that
+    # will be passed to the perform method.
+    def initialize(*arguments)
+      @arguments  = arguments
+      @job_id     = SecureRandom.uuid
+      @queue_name = self.class.queue_name
+    end
+
+    # Returns a hash with the job data that can safely be passed to the
+    # queueing adapter.
+    def serialize
+      {
+        'job_class'  => self.class.name,
+        'job_id'     => job_id,
+        'queue_name' => queue_name,
+        'arguments'  => serialize_arguments(arguments)
+      }
+    end
+
+    private
+      def deserialize_arguments_if_needed
+        if defined?(@serialized_arguments) && @serialized_arguments.present?
+          @arguments = deserialize_arguments(@serialized_arguments)
+          @serialized_arguments = nil
+        end
+      end
+
+      def serialize_arguments(serialized_args)
+        Arguments.serialize(serialized_args)
+      end
+
+      def deserialize_arguments(serialized_args)
+        Arguments.deserialize(serialized_args)
+      end
+  end
+end
+
+
+

data/lib/active_job/enqueuing.rb

@@ -5,67 +5,71 @@ module ActiveJob
     extend ActiveSupport::Concern
 
     module ClassMethods
-      # Push a job onto the queue.  The arguments must be legal JSON types
+      # Push a job onto the queue. The arguments must be legal JSON types
       # (string, int, float, nil, true, false, hash or array) or
-      # GlobalID::Identification instances.  Arbitrary Ruby objects
+      # GlobalID::Identification instances. Arbitrary Ruby objects
       # are not supported.
       #
       # Returns an instance of the job class queued with args available in
       # Job#arguments.
-      def enqueue(*args)
-        new(args).tap do |job|
-          job.run_callbacks :enqueue do
-            queue_adapter.enqueue self, job.job_id, *Arguments.serialize(args)
-          end
-        end
-      end
-
-      # Enqueue a job to be performed at +interval+ from now.
-      #
-      #   enqueue_in(1.week, "mike")
-      #
-      # Returns an instance of the job class queued with args available in
-      # Job#arguments and the timestamp in Job#enqueue_at.
-      def enqueue_in(interval, *args)
-        enqueue_at interval.seconds.from_now, *args
+      def perform_later(*args)
+        job_or_instantiate(*args).enqueue
       end
 
-      # Enqueue a job to be performed at an explicit point in time.
-      #
-      #   enqueue_at(Date.tomorrow.midnight, "mike")
-      #
-      # Returns an instance of the job class queued with args available in
-      # Job#arguments and the timestamp in Job#enqueue_at.
-      def enqueue_at(timestamp, *args)
-        new(args).tap do |job|
-          job.enqueued_at = timestamp
-
-          job.run_callbacks :enqueue do
-            queue_adapter.enqueue_at self, timestamp.to_f, job.job_id, *Arguments.serialize(args)
-          end
+      protected
+        def job_or_instantiate(*args)
+          args.first.is_a?(self) ? args.first : new(*args)
         end
-      end
-    end
-
-    included do
-      attr_accessor :arguments
-      attr_accessor :enqueued_at
-    end
-
-    def initialize(arguments = nil)
-      @arguments = arguments
     end
 
-    def retry_now
-      self.class.enqueue(*arguments)
+    # Reschedule the job to be re-executed. This is useful in combination
+    # with the +rescue_from+ option. When you rescue an exception from your job
+    # you can ask Active Job to retry performing your job.
+    #
+    # ==== Options
+    # * <tt>:wait</tt> - Enqueues the job with the specified delay
+    # * <tt>:wait_until</tt> - Enqueues the job at the time specified
+    # * <tt>:queue</tt> - Enqueues the job on the specified queue
+    #
+    # ==== Examples
+    #
+    #  class SiteScrapperJob < ActiveJob::Base
+    #    rescue_from(ErrorLoadingSite) do
+    #      retry_job queue: :low_priority
+    #    end
+    #    def perform(*args)
+    #      # raise ErrorLoadingSite if cannot scrape
+    #    end
+    #  end
+    def retry_job(options={})
+      enqueue options
     end
 
-    def retry_in(interval)
-      self.class.enqueue_in interval, *arguments
-    end
-
-    def retry_at(timestamp)
-      self.class.enqueue_at timestamp, *arguments
+    # Enqueues the job to be performed by the queue adapter.
+    #
+    # ==== Options
+    # * <tt>:wait</tt> - Enqueues the job with the specified delay
+    # * <tt>:wait_until</tt> - Enqueues the job at the time specified
+    # * <tt>:queue</tt> - Enqueues the job on the specified queue
+    #
+    # ==== Examples
+    #
+    #    my_job_instance.enqueue
+    #    my_job_instance.enqueue wait: 5.minutes
+    #    my_job_instance.enqueue queue: :important
+    #    my_job_instance.enqueue wait_until: Date.tomorrow.midnight
+    def enqueue(options={})
+      self.scheduled_at = options[:wait].seconds.from_now.to_f if options[:wait]
+      self.scheduled_at = options[:wait_until].to_f if options[:wait_until]
+      self.queue_name   = self.class.queue_name_from_part(options[:queue]) if options[:queue]
+      run_callbacks :enqueue do
+        if self.scheduled_at
+          self.class.queue_adapter.enqueue_at self, self.scheduled_at
+        else
+          self.class.queue_adapter.enqueue self
+        end
+      end
+      self
     end
   end
 end