pipeline 0.0.8 → 0.0.9

data/lib/pipeline/core_ext/symbol_attribute.rb

@@ -1,10 +1,24 @@
 module Pipeline
+  # Extends ActiveRecord::Base to save and retrieve symbol attributes as strings.
+  #
+  # Example:
+  #   class Card < ActiveRecord::Base
+  #     symbol_attrs :rank, :suit
+  #   end
+  #
+  #   card = Card.new(:rank => 'jack', :suit => 'hearts')
+  #   card.rank # => :jack
+  #   card.suit # => :hearts
+  #
+  # It also allow symbol attributes to be used on ActiveRecord #find conditions:
+  #
+  #   Card.find(:all, :conditions => ['suit = ?', :clubs])
   module SymbolAttribute
     def self.included(base)
       base.extend(ClassMethods)
     end
 
-    module ClassMethods
+    module ClassMethods #:nodoc:
       def symbol_attrs(*attributes)
         attributes.each do |attribute|
           class_eval <<-EOD
@@ -20,7 +34,7 @@ module Pipeline
   end
 end
 
-class Symbol
+class Symbol #:nodoc:
   def quoted_id
     "'#{ActiveRecord::Base.connection.quote_string(self.to_s)}'"
   end

data/lib/pipeline/core_ext/transactional_attribute.rb

@@ -1,10 +1,27 @@
 module Pipeline
+  # Extends ActiveRecord::Base to provide attributes that are saved in a nested
+  # transaction when updated through a setter.
+  #
+  # NOTE: When the extended attributes are updated, the entire record is saved
+  #
+  # Example:
+  #   class Car < ActiveRecord::Base
+  #     transactional_attrs :state, :engine_state
+  #     
+  #     def run
+  #       self.engine_state = :on if self.state == :on
+  #     end
+  #   end
+  #
+  #   car = Car.new
+  #   car.state = :on # this will save the record in a transaction
+  #   car.run # Record will be saved again, since #run updates :engine_state
   module TransactionalAttribute
     def self.included (base)
       base.extend(ClassMethods)
     end
 
-    module ClassMethods
+    module ClassMethods #:nodoc:
       def transactional_attrs(*attributes)
         attributes.each do |attribute|
           class_eval <<-EOD

data/lib/pipeline/errors.rb

@@ -1,24 +1,40 @@
 module Pipeline
+  # Exception to represents an invalid pipeline. Raised by methods on Pipeline::ApiMethods
   class InvalidPipelineError < StandardError; end
   
+  # Exception to represent an invalid state transition. Raised by execution methods on
+  # Pipeline::Base and Pipeline::Stage::Base. E.g. trying to transition a :failed
+  # pipeline to :in_progress.
   class InvalidStatusError < StandardError
+    # The current status of pipeline or stage
     def initialize(status)
       super("Status is already #{status.to_s.gsub(/_/, ' ')}")
     end
   end
 
+  # Exception to represent an irrecoverable error that can be raised by subclasses of
+  # Pipeline::Stage::Base that override the method <tt>run</tt>. Please refer to
+  # Pipeline::Base for more details about error handling.
   class IrrecoverableError < StandardError; end
 
+  # Exception to represent a recoverable error that can be raised by subclasses of
+  # Pipeline::Stage::Base that override the method <tt>run</tt>. Please refer to
+  # Pipeline::Base for more details about error handling.
   class RecoverableError < StandardError
+    # Instantiates a new instance of RecoverableError.
+    # [msg]             Is a description of the error message
+    # [input_required]  Is a boolean that determines if the error requires user action
+    #                   (<tt>true</tt>, meaning it can not be automatically retried) or
+    #                   not (<tt>false</tt>, meaning it can be automatically retried).
+    #                   Default is <tt>false</tt>
     def initialize(msg = nil, input_required = false)
       super(msg)
       @input_required = input_required
     end
 
+    # Returns <tt>true</tt> if this error requires user action or <tt>false</tt> otherwise.
     def input_required?
       @input_required
     end
   end
-
-  extend(ApiMethods)
 end

data/lib/pipeline/stage/base.rb

@@ -1,5 +1,106 @@
 module Pipeline
-  module Stage
+  module Stage # :nodoc:
+    # A stage represents one of the steps in a pipeline. Stages can be reused by
+    # different pipelines. The behaviour of a stage is determined by subclasses of
+    # Pipeline::Stage::Base implementing the method #run:
+    #
+    #   class PrepareIngredients < Pipeline::Stage::Base
+    #     def run
+    #       Ingredients.each do |ingredient|
+    #         ingredient.wash
+    #         ingredient.slice!
+    #       end
+    #     end
+    #   end
+    #
+    # If a stage need access to its associated pipeline, it can call the association
+    # <tt>pipeline</tt>.
+    #
+    # == Stage Name
+    #
+    # By default, a stage will have a standard name that corresponds to its fully
+    # qualified class name (e.g. Pipeline::Stage::Base or SamplePipeline::SampleStage).
+    # You can provide a more descriptive name by calling <tt>default_name</tt>:
+    #
+    #   class PrepareIngredients < Pipeline::Stage::Base
+    #     self.default_name = "Prepare Ingredients for Cooking"
+    #   end
+    #
+    # You can retrieve the name of a stage using the <tt>name</tt> attribute:
+    #
+    #   stage = PrepareIngredients.new
+    #   stage.name # => "Prepare Ingredients for Cooking"
+    #
+    # == Error Handling
+    #
+    # In case of failure, a stage can raise special exceptions (RecoverableError or
+    # IrrecoverableError) to determine what happens to the pipeline. Please refer to
+    # Pipeline::Base for a description of the possible outcomes. Any failure will
+    # persist the Exception's message on the <tt>message</tt> attribute and will move
+    # the stage to a :failed state.
+    #
+    # == State Transitions
+    # 
+    # The following diagram represents the state transitions a stage instance can
+    # go through during its life-cycle:
+    #
+    # :not_started ---> :in_progress ---> :completed
+    #                       ^ |
+    #                       | v
+    #                     :failed
+    #
+    # [:not_started] The stage was instantiated but not started yet.
+    # [:in_progress] After started or retried, the stage remains on this state while
+    #                executing.
+    # [:completed]   After successfully executing, the stage is completed.
+    # [:failed]      If an error occurs, the stage goes into this stage.
+    #
+    # == Callbacks
+    # 
+    # You can define custom callbacks to be called before (+before_stage+) and after
+    # (+after_stage+) executing a stage. Example:
+    #
+    #   class PrepareIngredients < Pipeline::Stage::Base
+    #     before_stage :wash_ingredients
+    #
+    #     def run
+    #       puts "Slicing..."
+    #     end
+    #     
+    #     protected
+    #     def wash_ingredients
+    #       puts "Washing..."
+    #     end
+    #   end
+    #
+    #   class Cook < Pipeline::Stage::Base
+    #     after_stage :serve
+    #
+    #     def run
+    #       puts "Cooking..."
+    #     end
+    #
+    #     protected
+    #     def serve
+    #       puts "bon appetit!"
+    #     end
+    #   end
+    #
+    #   class MakeDinnerPipeline < Pipeline::Base
+    #     define_stages PrepareIngredients >> Cook
+    #   end
+    #
+    #   Pipeline.start(MakeDinnerPipeline.new)
+    # 
+    # Outputs:
+    #   Washing...
+    #   Slicing...
+    #   Cooking...
+    #   bon appetit!
+    #
+    # Callbacks can be defined as a symbol that calls a private/protected method (like the
+    # example above), as an inline block, or as a +Callback+ object, as a regular
+    # +ActiveRecord+ callback.
     class Base < ActiveRecord::Base
       set_table_name :pipeline_stages
       
@@ -10,23 +111,40 @@ module Pipeline
       symbol_attr :status
       transactional_attr :status
       private :status=
-
-      belongs_to :pipeline, :class_name => "Pipeline::Base", :foreign_key => 'pipeline_instance_id'
       
+      # Allows access to the associated pipeline
+      belongs_to :pipeline, :class_name => "Pipeline::Base", :foreign_key => 'pipeline_instance_id'
+            
+      class_inheritable_accessor :default_name, :instance_writer => false
+
+      define_callbacks :before_stage, :after_stage
+
       @@chain = []
+      # Method used for chaining stages on a pipeline sequence. Please refer to
+      # Pipeline::Base for example usages.
       def self.>>(next_stage)
         @@chain << self
         next_stage
       end
       
+      # Method used by Pipeline::Base to construct its chain of stages. Please
+      # refer to Pipeline::Base
       def self.build_chain
         chain = @@chain + [self]
         @@chain = []
         chain
       end
       
-      class_inheritable_accessor :default_name, :instance_writer => false
-      
+      # Standard ActiveRecord callback to setup initial name and status
+      # when a new stage is instantiated. If you override this callback, make
+      # sure to call +super+:
+      #
+      #   class SampleStage < Pipeline::Stage::Base
+      #     def after_initialize
+      #       super
+      #       self[:special_attribute] ||= "standard value"
+      #     end
+      #   end
       def after_initialize
         if new_record?
           self[:status] = :not_started
@@ -34,10 +152,19 @@ module Pipeline
         end
       end
       
+      # Returns <tt>true</tt> if the stage is in a :completed state, <tt>false</tt>
+      # otherwise.
       def completed?
         status == :completed
       end
       
+      # Standard method called when executing this stage. Raises   
+      # InvalidStatusError if stage is in an invalid state for execution (e.g.
+      # already completed, or in progress).
+      #
+      # <b>NOTE:</b> Do not override this method to determine the behaviour of a
+      # stage. This method will be called by the executing pipeline. Please override
+      # #run instead.
       def perform
         reload unless new_record?
         raise InvalidStatusError.new(status) unless [:not_started, :failed].include?(status)
@@ -51,17 +178,23 @@ module Pipeline
           self.message = e.message
           self.status = :failed
           raise e
+        ensure
+          run_callbacks(:after_stage)
         end
       end
-      
-      # Subclass must implement this as part of the contract
-      def run; end
+
+      # Abstract method to be implemented by all subclasses that represents the
+      # action to be performed by this stage
+      def run
+        raise "This method must be implemented by any subclass of Pipeline::Stage::Base"
+      end
       
       private
       def _setup
         self.attempts += 1
         self.message = nil
         self.status = :in_progress
+        run_callbacks(:before_stage)
       end
     end
   end

data/pipeline.gemspec

@@ -1,12 +1,15 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
 # -*- encoding: utf-8 -*-
 
 Gem::Specification.new do |s|
   s.name = %q{pipeline}
-  s.version = "0.0.8"
+  s.version = "0.0.9"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Danilo Sato"]
-  s.date = %q{2009-08-20}
+  s.date = %q{2009-12-14}
   s.description = %q{Pipeline is a Rails plugin/gem to run asynchronous processes in a configurable pipeline.}
   s.email = %q{danilo@dtsato.com}
   s.extra_rdoc_files = [
@@ -37,6 +40,7 @@ Gem::Specification.new do |s|
      "lib/pipeline/stage/base.rb",
      "pipeline.gemspec",
      "spec/database_integration_helper.rb",
+     "spec/models.rb",
      "spec/pipeline/api_methods_spec.rb",
      "spec/pipeline/base_spec.rb",
      "spec/pipeline/core_ext/symbol_attribute_spec.rb",
@@ -51,10 +55,11 @@ Gem::Specification.new do |s|
   s.rdoc_options = ["--main", "README.rdoc", "--inline-source", "--line-numbers"]
   s.require_paths = ["lib"]
   s.rubyforge_project = %q{pipeline}
-  s.rubygems_version = %q{1.3.4}
+  s.rubygems_version = %q{1.3.5}
   s.summary = %q{A Rails plugin/gem to run asynchronous processes in a configurable pipeline}
   s.test_files = [
     "spec/database_integration_helper.rb",
+     "spec/models.rb",
      "spec/pipeline",
      "spec/pipeline/api_methods_spec.rb",
      "spec/pipeline/base_spec.rb",
@@ -68,6 +73,7 @@ Gem::Specification.new do |s|
      "spec/spec.opts",
      "spec/spec_helper.rb",
      "spec/database_integration_helper.rb",
+     "spec/models.rb",
      "spec/pipeline",
      "spec/rcov.opts",
      "spec/spec.opts",
@@ -80,13 +86,14 @@ Gem::Specification.new do |s|
 
     if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
       s.add_runtime_dependency(%q<activerecord>, [">= 2.0"])
-      s.add_runtime_dependency(%q<collectiveidea-delayed_job>, [">= 1.8.0"])
+      s.add_runtime_dependency(%q<delayed_job>, [">= 1.8.0"])
     else
       s.add_dependency(%q<activerecord>, [">= 2.0"])
-      s.add_dependency(%q<collectiveidea-delayed_job>, [">= 1.8.0"])
+      s.add_dependency(%q<delayed_job>, [">= 1.8.0"])
     end
   else
     s.add_dependency(%q<activerecord>, [">= 2.0"])
-    s.add_dependency(%q<collectiveidea-delayed_job>, [">= 1.8.0"])
+    s.add_dependency(%q<delayed_job>, [">= 1.8.0"])
   end
 end
+

data/spec/database_integration_helper.rb

@@ -22,6 +22,7 @@ ActiveRecord::Schema.define do
     t.string :type
     t.string :status
     t.integer :attempts, :default => 0
+    t.references :external
     t.timestamps
   end
 

data/spec/models.rb

@@ -0,0 +1,72 @@
+class StubStage < Pipeline::Stage::Base
+  def run
+    @executed = true
+  end
+  
+  def executed?
+    !!@executed
+  end
+end
+
+class FirstStage < StubStage; end
+
+class SecondStage < StubStage; end
+
+class FailedStage < StubStage
+  def run
+    super
+    raise StandardError.new
+  end
+end
+
+class IrrecoverableStage < StubStage
+  def run
+    super
+    raise Pipeline::IrrecoverableError.new("message")
+  end
+end
+
+class RecoverableInputRequiredStage < StubStage
+  def run
+    super
+    raise Pipeline::RecoverableError.new("message", true)
+  end
+end
+
+class RecoverableStage < StubStage
+  def run
+    super
+    raise Pipeline::RecoverableError.new("message")
+  end
+end
+
+class GenericErrorStage < StubStage
+  def run
+    super
+    raise Exception.new
+  end
+end
+
+class SamplePipeline < Pipeline::Base
+  define_stages FirstStage >> SecondStage
+  
+  before_pipeline :before_pipeline_callback
+  after_pipeline :after_pipeline_callback
+  
+  private
+  def before_pipeline_callback; end
+  def after_pipeline_callback; end
+end
+
+class SampleStage < Pipeline::Stage::Base
+  before_stage :before_stage_callback
+  after_stage :after_stage_callback
+  
+  def run
+    # nothing...
+  end
+  
+  private
+  def before_stage_callback; end
+  def after_stage_callback; end
+end