nxt_pipeline 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 990043f1b6a4cb543090543a45aa103f915db67ad30a682fcf459d4fc582764d
-  data.tar.gz: e3d2af9e6492d930fe196a886d4c53314055fbd4534110d2257ddd5687157bf1
+  metadata.gz: 3b2eac461b1a77771494ee996ece40aece6ec068070fdb282f68192119976d93
+  data.tar.gz: 339d7b6b27ce3b85a95d5a80558d2d4e217e0ce8b1f8965eb573f534caf6bb18
 SHA512:
-  metadata.gz: de30962f57a74e8e3f8f1ef541395bbfac2ed424a58c1638e2b6e83f62fe40529e2d2df9bb6f1b3641894e64f57bc6b02748bef2af018d9cc9262028f7e1b105
-  data.tar.gz: b0170c1be44573b6f9416e01582e7673cc20fb48fccab4aa2492e516f4fde59da92b8c248e157922bdd293c602ce94de209c9b81c81e549b1c0a7ceaf09b276a
+  metadata.gz: fe288cb402d9f354dea2f5d2cf47640f29757b74ed90e187beb74c7fe8fa721177718e6eb052a398c54e97561a2b17dbbe7d93132231f2b285b0b93e3e3fe160
+  data.tar.gz: c0837560b35952dc0744df9f75ae61993910f57c97c777ff3fd28921910b080fcf8cf68f2dc6308a790c9e2bfb9f63a530229a609b2711950e6b81e5dc6eda09

data/.gitignore

@@ -6,6 +6,7 @@
 /pkg/
 /spec/reports/
 /tmp/
+.idea/
 
 # rspec failure tracking
 .rspec_status

data/Gemfile.lock

@@ -1,19 +1,19 @@
 PATH
   remote: .
   specs:
-    nxt_pipeline (0.2.0)
+    nxt_pipeline (0.2.1)
       activesupport
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (5.2.2)
+    activesupport (5.2.2.1)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 0.7, < 2)
       minitest (~> 5.1)
       tzinfo (~> 1.1)
     coderay (1.1.2)
-    concurrent-ruby (1.1.4)
+    concurrent-ruby (1.1.5)
     diff-lcs (1.3)
     ffi (1.10.0)
     formatador (0.2.5)
@@ -31,7 +31,7 @@ GEM
       guard (~> 2.1)
       guard-compat (~> 1.1)
       rspec (>= 2.99.0, < 4.0)
-    i18n (1.5.3)
+    i18n (1.6.0)
       concurrent-ruby (~> 1.0)
     listen (3.1.5)
       rb-fsevent (~> 0.9, >= 0.9.4)
@@ -80,6 +80,7 @@ DEPENDENCIES
   bundler (~> 1.17)
   guard-rspec
   nxt_pipeline!
+  pry
   rake (~> 10.0)
   rspec (~> 3.0)
   rspec_junit_formatter

data/README.md

@@ -22,93 +22,114 @@ Or install it yourself as:
 
 ## Usage
 
-Define a pipeline by defining class inheriting from `NxtPipeline::Pipeline` as shown above. The following examples shows a pipeline which takes an array of strings and passes it through multiple steps.
+### Constructors
+
+First you probably want to configure a pipeline so that it can execute your steps. 
+Therefore you want to define constructors for your steps. Constructors take a name 
+as the first argument and step options as the second. All step options are being exposed
+by the step yielded to the constructor. 
 
 ```ruby
-class MyPipeline < NxtPipeline::Pipeline
-  pipe_attr :words
+pipeline = NxtPipeline::Pipeline.new do |p|
+  # Add a named constructor that will be used to execute your steps later
+  # All options that you pass in your step will be available through accessors in your constructor 
+  p.constructor(:service, default: true) do |step, arg|
+    step.service_class.new(options: arg).call
+  end
   
-  step UppercaseSegment
-  step SortSegment
+  p.constructor(:job) do |step, arg|
+    step.job_class.perform_later(*arg) && arg
+  end
+end
+
+# Once a pipeline was created you can still configure it 
+pipeline.constructor(:call) do |step, arg|
+  step.caller.new(arg).call
+end
+
+# same with block syntax 
+# You can use this to split up execution from configuration  
+pipeline.configure do |p|
+ p.constructor(:call) do |step, arg|
+   step.caller.new(arg).call
+ end
 end
 ```
 
-The steps are classes themselves which inherit from `NxtPipeline::Step` and have to implement a `#pipe_through` method.
+### Defining steps 
+
+Once your pipeline knows how to execute your steps you can add those.
 
 ```ruby
-class UppercaseSegment < NxtPipeline::Step
-  def pipe_through
-    words.map(&:uppercase)
-  end
+pipeline.step :service, service_class: MyServiceClass, to_s: 'First step'
+pipeline.step service_class: MyOtherServiceClass, to_s: 'Second step' 
+# ^ Since service is the default step you don't have to specify it the step type each time
+pipeline.step :job, job_class: MyJobClass # to_s is optional
+pipeline.step :job, job_class: MyOtherJobClass
+
+pipeline.step :step_name_for_better_log do |_, arg|
+  # ...
 end
 
-class SortSegment < NxtPipeline::Step
-  def pipe_through
-    words.sort
-  end
+pipeline.step to_s: 'This is the same as above' do |step, arg|
+  # ... step.to_s => 'This is the same as above'
 end
 ```
 
-You can access the pipeline attribute defined by `pipe_attr` in the pipeline class by a reader method which is automatically defined by nxt_pipeline. Don't forget to return the pipeline attribute so that subsequent steps in the pipeline can take it up!
+You can also define inline steps, meaning the block will be executed
 
-Here's how our little example pipeline behaves like in action:
+### Execution
 
-```
-MyPipeline.new(words: %w[Ruby is awesome]).run
-# => ["AWESOME", "IS", "RUBY"]
-```
+You can then execute the steps with: 
 
-### Callbacks
+```ruby
+pipeline.execute('initial argument')
 
-You can define callbacks that are automatically invoked for each step in the pipeline.
+# Or run the steps directly using block syntax
 
-```ruby
-class MyPipeline < NxtPipeline::Pipeline
-  before_each_step do
-    # Code run before each step.
-  end
-  
-  after_each_step do
-    # Code run after each step
-  end
-  
-  around_each_step do |pipeline, segment|
-    # Code run before each step
-	segment.call
-	# Code run after each step
-  end
+pipeline.execute do |p|
+  p.step :service, service_class: MyServiceClass, to_s: 'First step'
+  p.step :service, service_class: MyOtherServiceClass, to_s: 'Second step'
+  p.step :job, job_class: MyJobClass # to_s is optional
+  p.step :job, job_class: MyOtherJobClass
 end
-```
-
-The callback methods are syntactic sugar for [ActiveSupport Callbacks](https://api.rubyonrails.org/classes/ActiveSupport/Callbacks.html), so the same rules apply regarding order or execution.
 
-### Error handling
+```
 
-When everything works smoothly the pipeline calls one step after another, passing through the pipeline attribute and returning it as it gets it from the last step. However, you might want to define behavior the pipeline should perform in case one of the steps raises an error.
+You can also directly execute a pipeline with:
 
 ```ruby
-class MyPipeline < NxtPipeline::Pipeline
-  rescue_errors StandardError do |error, failed_step|
-    puts "Step #{failed_step} failed with #{error.class}: #{error.message}"
+NxtPipeline::Pipeline.execute('initial argument') do |p|
+  p.step do |_, arg|
+    arg.upcase
   end
 end
-```
+``` 
 
-Keep in mind though that `rescue_errors` will reraise the error it caught. When you rescue this error in your application, the pipeline remembers if and how it failed.
+### Error callbacks
 
-```ruby
-pipeline = MyPipeline.new(...)
+Apart from defining constructors and steps you can also define error callbacks.
 
-begin
-  pipeline.run
-rescue => e
-  pipeline.failed?
-  #=> true
+```ruby
+NxtPipeline::Pipeline.new do |p|
+  p.step do |_, arg|
+    arg.upcase
+  end
+  
+  p.on_error MyCustomError do |step, arg, error|
+    # First matching error callback will be executed!
+  end
+  
+  p.on_errors ArgumentError, KeyError do |step, arg, error|
+    # First matching error callback will be executed!
+  end
   
-  pipeline.failed_step
-  #=> :underscored_class_name_of_failed_step
+  p.on_errors do |step, arg, error|
+    # This will match all errors inheriting from StandardError
+  end
 end
-```
+``` 
+
 
 ## Development
 

data/lib/nxt_pipeline.rb

@@ -1,10 +1,7 @@
-require 'active_support'
-require 'active_support/core_ext'
-
 require 'nxt_pipeline/version'
-require 'nxt_pipeline/step'
 require 'nxt_pipeline/pipeline'
+require 'nxt_pipeline/step'
+require 'nxt_pipeline/error_callback'
 
 module NxtPipeline
-  class Error < StandardError; end
 end

data/lib/nxt_pipeline/error_callback.rb

@@ -0,0 +1,18 @@
+module NxtPipeline
+  class ErrorCallback
+    def initialize(errors, callback)
+      @errors = errors
+      @callback = callback
+    end
+
+    attr_accessor :errors, :callback
+
+    def applies_to_error?(error)
+      (error.class.ancestors & errors).any?
+    end
+
+    def call(step, arg, error)
+      callback.call(step, arg, error)
+    end
+  end
+end

data/lib/nxt_pipeline/pipeline.rb

@@ -1,81 +1,97 @@
 module NxtPipeline
   class Pipeline
-    include ActiveSupport::Callbacks
-    define_callbacks :each_step_pipe_through
-    
-    attr_reader :failed_step
+    def self.execute(opts, &block)
+      new(&block).execute(opts)
+    end
+
+    def initialize(&block)
+      @steps = []
+      @error_callbacks = []
+      @log = {}
+      @current_step = nil
+      @default_constructor = nil
+      @registry = {}
+      configure(&block) if block_given?
+    end
+
+    attr_reader :log
+
+    # register steps with name and block
+    def constructor(name, **opts, &constructor)
+      name = name.to_sym
+      raise StandardError, "Already registered step :#{name}" if registry[name]
+
+      registry[name] = constructor
 
-    def initialize(*attrs)
-      extract_pipe_attr_from_init_params(*attrs)
+      return unless opts.fetch(:default, false)
+      default_constructor ? (raise ArgumentError, 'Default step already defined') : self.default_constructor = constructor
     end
 
-    def run
-      self.class.steps.reduce(pipe_attr) do |transformed_pipe_attr, step|
-        run_callbacks :each_step_pipe_through do
-          step[self.class.pipe_attr_name].new(self.class.pipe_attr_name => transformed_pipe_attr).pipe_through
-        rescue => error
-          handle_segment_burst(error, step)
+    def step(type = nil, **opts, &block)
+      constructor = if block_given?
+        # make first argument the to_s of step if given
+        opts.merge!(to_s: type) if type && !opts.key?(:to_s)
+        block
+      else
+        if type
+          registry.fetch(type) { raise KeyError, "No step :#{type} registered" }
+        else
+          default_constructor || (raise StandardError, 'No default step registered')
         end
       end
-    end
 
-    def failed?
-      failed_step.present?
+      steps << Step.new(constructor, **opts)
     end
 
-    class << self
-      def pipe_attr(name)
-        @pipe_attr_name = name
+    def execute(arg, &block)
+      reset_log
+      configure(&block) if block_given?
+      steps.inject(arg) do |argument, step|
+        execute_step(step, argument)
       end
+    end
 
-      def step(name)
-        self.steps << name
-      end
+    def on_errors(*errors, &callback)
+      error_callbacks << ErrorCallback.new(errors, callback)
+    end
 
-      def rescue_errors(*errors, &block)
-        @rescueable_errors = errors
-        self.rescueable_block = block
-      end
-      
-      def before_each_step(*filters, &block)
-        set_callback :each_step_pipe_through, :before, *filters, &block
-      end
-      
-      def after_each_step(*filters, &block)
-        set_callback :each_step_pipe_through, :after, *filters, &block
-      end
-      
-      def around_each_step(*filters, &block)
-        set_callback :each_step_pipe_through, :around, *filters, &block
-      end
-      
-      attr_reader :pipe_attr_name
-      attr_accessor :rescueable_block
-      
-      def steps
-        @steps ||= []
-      end
-      
-      def rescueable_errors
-        @rescueable_errors ||= []
-      end
+    alias :on_error :on_errors
+
+    def configure(&block)
+      block.call(self)
     end
 
     private
 
-    attr_reader :pipe_attr
+    attr_reader :error_callbacks, :registry
+    attr_accessor :steps, :current_step, :default_constructor
+    attr_writer :log
 
-    def extract_pipe_attr_from_init_params(*attrs)
-      raise ArgumentError, 'You need to pass a keyword param as argument to #new' unless attrs.first.is_a?(Hash)
-      @pipe_attr = attrs.first.fetch(self.class.pipe_attr_name)
-    end
+    def execute_step(step, arg)
+      self.current_step = step.to_s
+      result = step.execute(arg)
 
-    def handle_segment_burst(error, step)
-      @failed_step = step.name.split('::').last.underscore
+      if result # step was successful
+        log[current_step] = { status: :success }
+        return result
+      else # step was not successful if nil or false
+        log[current_step] = { status: :skipped }
+        return arg
+      end
+    rescue StandardError => error
+      log[current_step] = { status: :failed, reason: "#{error.class}: #{error.message}" }
+      callback = find_error_callback(error)
 
-      self.class.rescueable_block.call(error, failed_step) if error.class.in?(self.class.rescueable_errors)
+      raise unless callback
+      callback.call(step, arg, error)
+    end
+
+    def find_error_callback(error)
+      error_callbacks.find { |callback| callback.applies_to_error?(error) }
+    end
 
-      raise
+    def reset_log
+      self.log = {}
     end
   end
-end
+end

data/lib/nxt_pipeline/step.rb

@@ -1,47 +1,32 @@
 module NxtPipeline
   class Step
-    def initialize(*args)
-      validate_initialize_args(*args).each do |key, value|
-        send("#{key}=", value)
-      end
-    end
-
-    def pipe_through
-      # Public interface of Step, to be implemented by subclasses.
-      raise NotImplementedError
+    def initialize(constructor, **opts)
+      define_attr_readers(opts)
+      @opts = opts
+      @constructor = constructor
     end
 
-    def self.[](*args)
-      raise ArgumentError, 'Arguments missing' if args.empty?
+    attr_accessor :constructor
 
-      Class.new(self) do
-        self.step_args = args.map(&:to_sym)
+    def execute(arg)
+      constructor.call(self, arg)
+      # instance_exec(arg, &constructor)
+    end
 
-        self.step_args.each do |step_arg|
-          attr_accessor step_arg
-        end
-      end
+    def to_s
+      "#{self.class} opts => #{opts}"
     end
 
     private
 
-    cattr_accessor :step_args, instance_writer: false, default: []
+    attr_reader :opts
 
-    def validate_initialize_args(*args)
-      raise ArgumentError, arguments_missing_msg(self.step_args) if args.empty?
-
-      keyword_args = args.first
-      missing_keyword_args = self.step_args.reject do |arg|
-        keyword_args.include?(arg)
+    def define_attr_readers(opts)
+      opts.each do |key, value|
+        define_singleton_method key.to_s do
+          value
+        end
       end
-
-      raise ArgumentError, arguments_missing_msg(missing_keyword_args) if missing_keyword_args.any?
-
-      keyword_args.slice(*self.step_args)
-    end
-
-    def arguments_missing_msg(missing_arg_keys)
-      "Arguments missing: #{missing_arg_keys.map { |a| "#{a}:" }.join(', ')}"
     end
   end
 end

data/lib/nxt_pipeline/version.rb

@@ -1,3 +1,3 @@
 module NxtPipeline
-  VERSION = "0.2.0".freeze
+  VERSION = "0.2.1".freeze
 end

data/nxt_pipeline.gemspec

@@ -39,4 +39,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "guard-rspec"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "pry"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nxt_pipeline
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Nils Sommer
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-03-10 00:00:00.000000000 Z
+date: 2019-04-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -82,6 +82,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: 
 email:
 - mail@nilssommer.de
@@ -106,6 +120,7 @@ files:
 - bin/rspec
 - bin/setup
 - lib/nxt_pipeline.rb
+- lib/nxt_pipeline/error_callback.rb
 - lib/nxt_pipeline/pipeline.rb
 - lib/nxt_pipeline/step.rb
 - lib/nxt_pipeline/version.rb