nxt_pipeline 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 562568995097a8f83c10663f6338404b1aea732d7e65f1c151a1d4a76c32a2bb
-  data.tar.gz: 3494855a43cdbe7a253e9ee5b07c6c1be7bf7be3e52a2a83da99fcd2c612b2cc
+  metadata.gz: 990043f1b6a4cb543090543a45aa103f915db67ad30a682fcf459d4fc582764d
+  data.tar.gz: e3d2af9e6492d930fe196a886d4c53314055fbd4534110d2257ddd5687157bf1
 SHA512:
-  metadata.gz: 6efff78864aa95fa547486c301ab7023fa2b1ed623e6f3e80380efaae9b943dd0d35ae251a079d02be8e07faf34ee2d9e60f19a365c4e5496ac16406a5a5223f
-  data.tar.gz: e27d108c8cd267b61ac4962b2e395957070e580c66482b124e2f4217c27b2f80cbd3a8eb22d2417fd04b91e2a916279edb5cfc5ce2ac89314191c66effc41fef
+  metadata.gz: de30962f57a74e8e3f8f1ef541395bbfac2ed424a58c1638e2b6e83f62fe40529e2d2df9bb6f1b3641894e64f57bc6b02748bef2af018d9cc9262028f7e1b105
+  data.tar.gz: b0170c1be44573b6f9416e01582e7673cc20fb48fccab4aa2492e516f4fde59da92b8c248e157922bdd293c602ce94de209c9b81c81e549b1c0a7ceaf09b276a

data/.circleci/config.yml

@@ -0,0 +1,52 @@
+# Ruby CircleCI 2.0 configuration file
+#
+# Check https://circleci.com/docs/2.0/language-ruby/ for more details
+#
+version: 2
+jobs:
+  build:
+    docker:
+      # specify the version you desire here
+      - image: circleci/ruby:2.6.1-node
+
+    working_directory: ~/repo
+
+    steps:
+      - checkout
+
+      # Download and cache dependencies
+      - restore_cache:
+          keys:
+            - v1-dependencies-{{ checksum "Gemfile.lock" }}
+
+      - run:
+          name: install dependencies
+          command: |
+            bundle install --jobs=4 --retry=3 --path vendor/bundle
+
+      - save_cache:
+          paths:
+            - ./vendor/bundle
+          key: v1-dependencies-{{ checksum "Gemfile.lock" }}
+
+      # run tests!
+      - run:
+          name: run tests
+          command: |
+            mkdir /tmp/test-results
+            TEST_FILES="$(circleci tests glob "spec/**/*_spec.rb" | \
+              circleci tests split --split-by=timings)"
+
+            bundle exec rspec \
+              --format progress \
+              --format RspecJunitFormatter \
+              --out /tmp/test-results/rspec.xml \
+              --format progress \
+              $TEST_FILES
+
+      # collect reports
+      - store_test_results:
+          path: /tmp/test-results
+      - store_artifacts:
+          path: /tmp/test-results
+          destination: test-results

data/CHANGELOG.md

@@ -0,0 +1,32 @@
+## Unreleased
+
+## nxt_pipeline 0.2.0 (March 10, 2019)
+
+* Added pipeline callback support.
+
+  *Nils Sommer*
+
+* Renamed class and method names
+
+  Renamed `NxtPipeline::Segment` to `NxtPipeline::Step`.
+  Renamed `NxtPipeline::Pipeline::segment` to `NxtPipeline::Pipeline::step`.
+  Renamed `NxtPipeline::Pipeline#call` to `NxtPipeline::Pipeline#run`.
+  Renamed `NxtPipeline::Pipeline#burst?` to `NxtPipeline::Pipeline#failed?`.
+  Renamed `NxtPipeline::Pipeline#burst_segment` to `NxtPipeline::Pipeline#failed_step`.
+  Renamed `NxtPipeline::Pipeline::rescue_segment_burst` to `NxtPipeline::Pipeline::rescue_errors`.
+  
+  *Nils Sommer*
+
+* Setup [guard](https://github.com/guard/guard) to run specs upon file changes during development.
+
+  *Nils Sommer*
+
+* Added CHANGELOG file.
+
+  *Nils Sommer*
+
+## nxt_pipeline 0.1.0 (February 25, 2019)
+
+* Initial Release.
+
+  *Nils Sommer*

data/Gemfile

@@ -5,4 +5,6 @@ git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
 # Specify your gem's dependencies in nxt_pipeline.gemspec
 gemspec
 
-gem 'activesupport'
+group :test do
+  gem 'rspec_junit_formatter' # for CircleCI
+end

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    nxt_pipeline (0.1.0)
+    nxt_pipeline (0.2.0)
       activesupport
 
 GEM
@@ -12,12 +12,45 @@ GEM
       i18n (>= 0.7, < 2)
       minitest (~> 5.1)
       tzinfo (~> 1.1)
+    coderay (1.1.2)
     concurrent-ruby (1.1.4)
     diff-lcs (1.3)
+    ffi (1.10.0)
+    formatador (0.2.5)
+    guard (2.15.0)
+      formatador (>= 0.2.4)
+      listen (>= 2.7, < 4.0)
+      lumberjack (>= 1.0.12, < 2.0)
+      nenv (~> 0.1)
+      notiffany (~> 0.0)
+      pry (>= 0.9.12)
+      shellany (~> 0.0)
+      thor (>= 0.18.1)
+    guard-compat (1.2.1)
+    guard-rspec (4.7.3)
+      guard (~> 2.1)
+      guard-compat (~> 1.1)
+      rspec (>= 2.99.0, < 4.0)
     i18n (1.5.3)
       concurrent-ruby (~> 1.0)
+    listen (3.1.5)
+      rb-fsevent (~> 0.9, >= 0.9.4)
+      rb-inotify (~> 0.9, >= 0.9.7)
+      ruby_dep (~> 1.2)
+    lumberjack (1.0.13)
+    method_source (0.9.2)
     minitest (5.11.3)
+    nenv (0.3.0)
+    notiffany (0.1.1)
+      nenv (~> 0.1)
+      shellany (~> 0.0)
+    pry (0.12.2)
+      coderay (~> 1.1.0)
+      method_source (~> 0.9.0)
     rake (10.5.0)
+    rb-fsevent (0.10.3)
+    rb-inotify (0.10.0)
+      ffi (~> 1.0)
     rspec (3.8.0)
       rspec-core (~> 3.8.0)
       rspec-expectations (~> 3.8.0)
@@ -31,6 +64,11 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.8.0)
     rspec-support (3.8.0)
+    rspec_junit_formatter (0.4.1)
+      rspec-core (>= 2, < 4, != 2.12.0)
+    ruby_dep (1.5.0)
+    shellany (0.0.1)
+    thor (0.20.3)
     thread_safe (0.3.6)
     tzinfo (1.2.5)
       thread_safe (~> 0.1)
@@ -39,11 +77,12 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
-  activesupport
   bundler (~> 1.17)
+  guard-rspec
   nxt_pipeline!
   rake (~> 10.0)
   rspec (~> 3.0)
+  rspec_junit_formatter
 
 BUNDLED WITH
    1.17.2

data/Guardfile

@@ -0,0 +1,31 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+## Uncomment and set this to only include directories you want to watch
+# directories %w(app lib config test spec features) \
+#  .select{|d| Dir.exist?(d) ? d : UI.warning("Directory #{d} does not exist")}
+
+## Note: if you are using the `directories` clause above and you are not
+## watching the project directory ('.'), then you will want to move
+## the Guardfile to a watched dir and symlink it back, e.g.
+#
+#  $ mkdir config
+#  $ mv Guardfile config/
+#  $ ln -s config/Guardfile .
+#
+# and, you'll have to watch "config/Guardfile" instead of "Guardfile"
+
+# Note: The cmd option is now required due to the increasing number of ways
+#       rspec may be run, below are examples of the most common uses.
+#  * bundler: 'bundle exec rspec'
+#  * bundler binstubs: 'bin/rspec'
+#  * spring: 'bin/rspec' (This will use spring if running and you have
+#                          installed the spring binstubs per the docs)
+#  * zeus: 'zeus rspec' (requires the server to be started separately)
+#  * 'just' rspec: 'rspec'
+
+guard :rspec, cmd: 'bundle exec rspec' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/nxt_pipeline/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end

data/README.md

@@ -1,6 +1,8 @@
+[![CircleCI](https://circleci.com/gh/nxt-insurance/nxt_pipeline.svg?style=svg)](https://circleci.com/gh/nxt-insurance/nxt_pipeline)
+
 # NxtPipeline
 
-nxt_pipeline provides a DSL to structure the processing of an object (oil) through multiple steps by defining pipelines (which process the object) and segments (reusable steps used by the pipeline).
+nxt_pipeline provides a DSL to define pipeline classes which take an object and pass it through multiple steps which can read or modify the object.
 
 ## Installation
 
@@ -20,66 +22,102 @@ Or install it yourself as:
 
 ## Usage
 
-Look how easy it is.
+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.
+
+```ruby
+class MyPipeline < NxtPipeline::Pipeline
+  pipe_attr :words
+  
+  step UppercaseSegment
+  step SortSegment
+end
+```
+
+The steps are classes themselves which inherit from `NxtPipeline::Step` and have to implement a `#pipe_through` method.
 
 ```ruby
-class UppercaseSegment < NxtPipeline::Segment
+class UppercaseSegment < NxtPipeline::Step
   def pipe_through
     words.map(&:uppercase)
   end
 end
 
-class SortSegment < NxtPipeline::Segment
+class SortSegment < NxtPipeline::Step
   def pipe_through
     words.sort
   end
 end
+```
 
-class MyPipeline < NxtPipeline::Pipeline
-  pipe_attr :words
-  
-  segment UppercaseSegment
-  segment SortSegment
-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!
 
-MyPipeline.new(words: %w[Ruby is awesome]).call
+Here's how our little example pipeline behaves like in action:
+
+```
+MyPipeline.new(words: %w[Ruby is awesome]).run
 # => ["AWESOME", "IS", "RUBY"]
 ```
 
-Basically you create a pipeline class that inherits from `NxtPipeline::Pipeline` and name the attribute you want to pass through the pipeline's segments with the `pipe_attr` class method.
+### Callbacks
 
-You can add segments to the pipeline by using the `segment` class method in the pipeline class body. The segment classes inherit from `NxtPipeline::Segment` and have to implement a method `#pipe_through`. Inside of it, you can access the pipeline attr by its reader method (see example above).
-
-You can also define behavior to execute when one of the pipelines raises an error.
+You can define callbacks that are automatically invoked for each step in the pipeline.
 
 ```ruby
 class MyPipeline < NxtPipeline::Pipeline
-  pipe_attr :words
+  before_each_step do
+    # Code run before each step.
+  end
   
-  segment UppercaseSegment
-  segment SortSegment
+  after_each_step do
+    # Code run after each step
+  end
   
-  rescue_from StandardError do |error, segment_failed_upon|
-    puts "Failed in segment #{segment_failed_upon} with #{error.class}: #{error.message}"
+  around_each_step do |pipeline, segment|
+    # Code run before each step
+	segment.call
+	# Code run after each step
   end
 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
 
-pipeline = MyPipeline.new(words: %w[Ruby is awesome])
-pipeline.call
-# => 'Failed in segment uppercase_segment with StandardError: Lorem ipsum'
+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.
 
-pipeline.burst?
-# => true
-pipeline.burst_segment
-# => 'uppercase_segment'
+```ruby
+class MyPipeline < NxtPipeline::Pipeline
+  rescue_errors StandardError do |error, failed_step|
+    puts "Step #{failed_step} failed with #{error.class}: #{error.message}"
+  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.
+
+```ruby
+pipeline = MyPipeline.new(...)
+
+begin
+  pipeline.run
+rescue => e
+  pipeline.failed?
+  #=> true
+  
+  pipeline.failed_step
+  #=> :underscored_class_name_of_failed_step
+end
 ```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
+You can also run `bin/guard` to automatically run specs when files are saved.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/nxt-insurance/nxt_pipeline.

data/bin/guard

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'guard' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("guard", "guard")

data/bin/rspec

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rspec-core", "rspec")

data/lib/nxt_pipeline/pipeline.rb

@@ -1,56 +1,79 @@
 module NxtPipeline
   class Pipeline
-    attr_reader :burst_segment
+    include ActiveSupport::Callbacks
+    define_callbacks :each_step_pipe_through
+    
+    attr_reader :failed_step
 
     def initialize(*attrs)
       extract_pipe_attr_from_init_params(*attrs)
     end
 
-    def call
-      self.segments.reduce(pipe_attr) do |transformed_pipe_attr, segment|
-        segment[pipe_attr_name].new(pipe_attr_name => transformed_pipe_attr).pipe_through
-      rescue => error
-        handle_segment_burst(error, segment)
+    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)
+        end
       end
     end
 
-    def burst?
-      burst_segment.present?
+    def failed?
+      failed_step.present?
     end
 
     class << self
       def pipe_attr(name)
-        self.pipe_attr_name = name
+        @pipe_attr_name = name
       end
 
-      def mount_segment(name)
-        self.segments << name
+      def step(name)
+        self.steps << name
       end
 
-      def rescue_segment_burst(*errors, &block)
-        self.rescueable_segment_bursts = errors
+      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
     end
 
     private
 
     attr_reader :pipe_attr
 
-    cattr_accessor :pipe_attr_name
-    cattr_accessor :segments, instance_writer: false, default: []
-    cattr_accessor :rescueable_segment_bursts, instance_writer: false, default: []
-    cattr_accessor :rescueable_block, instance_writer: false
-
     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(pipe_attr_name)
+      @pipe_attr = attrs.first.fetch(self.class.pipe_attr_name)
     end
 
-    def handle_segment_burst(error, segment)
-      @burst_segment = segment.name.split('::').last.underscore
+    def handle_segment_burst(error, step)
+      @failed_step = step.name.split('::').last.underscore
 
-      self.rescueable_block.call(error, burst_segment) if error.class.in?(rescueable_segment_bursts)
+      self.class.rescueable_block.call(error, failed_step) if error.class.in?(self.class.rescueable_errors)
 
       raise
     end

data/lib/nxt_pipeline/{segment.rb → step.rb}

@@ -1,5 +1,5 @@
 module NxtPipeline
-  class Segment
+  class Step
     def initialize(*args)
       validate_initialize_args(*args).each do |key, value|
         send("#{key}=", value)
@@ -7,7 +7,7 @@ module NxtPipeline
     end
 
     def pipe_through
-      # Public interface of Segment, to be implemented by subclasses.
+      # Public interface of Step, to be implemented by subclasses.
       raise NotImplementedError
     end
 
@@ -15,29 +15,29 @@ module NxtPipeline
       raise ArgumentError, 'Arguments missing' if args.empty?
 
       Class.new(self) do
-        self.segment_args = args.map(&:to_sym)
+        self.step_args = args.map(&:to_sym)
 
-        self.segment_args.each do |segment_arg|
-          attr_accessor segment_arg
+        self.step_args.each do |step_arg|
+          attr_accessor step_arg
         end
       end
     end
 
     private
 
-    cattr_accessor :segment_args, instance_writer: false, default: []
+    cattr_accessor :step_args, instance_writer: false, default: []
 
     def validate_initialize_args(*args)
-      raise ArgumentError, arguments_missing_msg(self.segment_args) if args.empty?
+      raise ArgumentError, arguments_missing_msg(self.step_args) if args.empty?
 
       keyword_args = args.first
-      missing_keyword_args = self.segment_args.reject do |arg|
+      missing_keyword_args = self.step_args.reject do |arg|
         keyword_args.include?(arg)
       end
 
       raise ArgumentError, arguments_missing_msg(missing_keyword_args) if missing_keyword_args.any?
 
-      keyword_args.slice(*self.segment_args)
+      keyword_args.slice(*self.step_args)
     end
 
     def arguments_missing_msg(missing_arg_keys)

data/lib/nxt_pipeline/version.rb

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

data/lib/nxt_pipeline.rb

@@ -2,7 +2,7 @@ require 'active_support'
 require 'active_support/core_ext'
 
 require 'nxt_pipeline/version'
-require 'nxt_pipeline/segment'
+require 'nxt_pipeline/step'
 require 'nxt_pipeline/pipeline'
 
 module NxtPipeline

data/nxt_pipeline.gemspec

@@ -36,6 +36,7 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency "activesupport"
   spec.add_development_dependency "bundler", "~> 1.17"
+  spec.add_development_dependency "guard-rspec"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nxt_pipeline
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Nils Sommer
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-02-24 00:00:00.000000000 Z
+date: 2019-03-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -40,6 +40,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.17'
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  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'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -75,20 +89,25 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".circleci/config.yml"
 - ".gitignore"
 - ".rspec"
 - ".ruby-version"
 - ".travis.yml"
+- CHANGELOG.md
 - Gemfile
 - Gemfile.lock
+- Guardfile
 - LICENSE.txt
 - README.md
 - Rakefile
 - bin/console
+- bin/guard
+- bin/rspec
 - bin/setup
 - lib/nxt_pipeline.rb
 - lib/nxt_pipeline/pipeline.rb
-- lib/nxt_pipeline/segment.rb
+- lib/nxt_pipeline/step.rb
 - lib/nxt_pipeline/version.rb
 - nxt_pipeline.gemspec
 homepage: https://github.com/nxt-insurance/nxt_pipeline