burner 0.0.0 → 1.0.0.pre.alpha.4

data/lib/burner/jobs/serialize/json.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2020-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Burner
+  class Jobs
+    module Serialize
+      # Treat value like a Ruby object and serialize it using JSON.
+      class Json < Job
+        def perform(_output, payload)
+          payload.value = payload.value.to_json
+
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/burner/jobs/serialize/yaml.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2020-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Burner
+  class Jobs
+    module Serialize
+      # Treat value like a Ruby object and serialize it using YAML.
+      class Yaml < Job
+        def perform(_output, payload)
+          payload.value = payload.value.to_yaml
+
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/burner/jobs/set.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2020-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Burner
+  class Jobs
+    # Arbitrarily set value
+    class Set < Job
+      attr_reader :value
+
+      def initialize(name:, value: nil)
+        super(name: name)
+
+        @value = value
+
+        freeze
+      end
+
+      def perform(_output, payload)
+        payload.value = value
+
+        nil
+      end
+    end
+  end
+end

data/lib/burner/jobs/sleep.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2020-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Burner
+  class Jobs
+    # Arbitrarily put thread to sleep for X number of seconds
+    class Sleep < Job
+      attr_reader :seconds
+
+      def initialize(name:, seconds: 0)
+        super(name: name)
+
+        @seconds = seconds.to_f
+
+        freeze
+      end
+
+      def perform(output, _payload)
+        output.detail("Going to sleep for #{seconds} second(s)")
+
+        Kernel.sleep(seconds)
+
+        nil
+      end
+    end
+  end
+end

data/lib/burner/modeling.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2020-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+require_relative 'modeling/key_index_mapping'

data/lib/burner/modeling/key_index_mapping.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2020-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Burner
+  module Modeling
+    # Generic relationship between a numeric index and a key.
+    class KeyIndexMapping
+      acts_as_hashable
+
+      attr_reader :index, :key
+
+      def initialize(index:, key:)
+        raise ArgumentError, 'index is required' if index.to_s.empty?
+        raise ArgumentError, 'key is required'   if key.to_s.empty?
+
+        @index = index.to_i
+        @key   = key.to_s
+
+        freeze
+      end
+    end
+  end
+end

data/lib/burner/output.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2020-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Burner
+  # A Pipeline execution can write main output, which is really an outline to whats happening,
+  # step-by-step.  This is not meant to replace or be true logging, but serve more as a summary
+  # for each of the jobs.  Each job can decide what it would like to include in this summary
+  # and leverage an instance of this class for inclusion of that information.
+  class Output
+    RULER_LENGTH = 80
+
+    attr_reader :id, :job_count, :outs
+
+    def initialize(id: SecureRandom.uuid, outs: [$stdout])
+      @id        = id
+      @outs      = Array(outs)
+      @job_count = 1
+    end
+
+    def ruler
+      write('-' * RULER_LENGTH)
+
+      self
+    end
+
+    def title(message)
+      write("[#{job_count}] #{message}")
+
+      @job_count += 1
+
+      self
+    end
+
+    def detail(message)
+      write("  - #{message}")
+
+      self
+    end
+
+    def write(message)
+      raw("[#{id} | #{Time.now.utc}] #{message}")
+
+      self
+    end
+
+    def complete(time_in_seconds)
+      detail("Completed in: #{time_in_seconds.round(3)} second(s)")
+
+      self
+    end
+
+    private
+
+    def raw(message)
+      outs.each { |out| out.puts(message) }
+
+      self
+    end
+  end
+end

data/lib/burner/payload.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2020-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+require_relative 'written_file'
+
+module Burner
+  # The input for all Job#perform methods.  The main notion of this object is its "value"
+  # attribute.  This is dynamic and weak on purpose and is subject to whatever the Job#perform
+  # methods decides it is.  This definitely adds an order-of-magnitude complexity to this whole
+  # library and lifecycle, but I am not sure there is any other way around it: trying to build
+  # a generic, open-ended object pipeline to serve almost any use case.
+  class Payload
+    attr_accessor :value
+
+    attr_reader :params,
+                :time,
+                :written_files
+
+    def initialize(
+      params: {},
+      time: Time.now.utc,
+      value: nil,
+      written_files: []
+    )
+      @params        = params || {}
+      @time          = time || Time.now.utc
+      @value         = value
+      @written_files = written_files || []
+    end
+
+    def add_written_file(written_file)
+      tap { written_files << WrittenFile.make(written_file) }
+    end
+  end
+end

data/lib/burner/pipeline.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2020-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+require_relative 'jobs'
+require_relative 'output'
+require_relative 'payload'
+require_relative 'step'
+
+module Burner
+  # The root package.  A Pipeline contains the job configurations along with the steps.  The steps
+  # referens jobs and tell you the order of the jobs to run.
+  class Pipeline
+    acts_as_hashable
+
+    class JobNotFoundError < StandardError; end
+
+    attr_reader :steps
+
+    def initialize(jobs: [], steps: [])
+      jobs_by_name = Jobs.array(jobs).map { |job| [job.name, job] }.to_h
+
+      @steps = Array(steps).map do |step_name|
+        job = jobs_by_name[step_name.to_s]
+
+        raise JobNotFoundError, "#{step_name} was not declared as a job" unless job
+
+        Step.new(job)
+      end
+    end
+
+    # The main entry-point for kicking off a pipeline.
+    def execute(output: Output.new, payload: Payload.new)
+      output.write("Pipeline started with #{steps.length} step(s)")
+
+      output_params(payload.params, output)
+      output.ruler
+
+      time_in_seconds = Benchmark.measure do
+        steps.each do |step|
+          return_value = step.perform(output, payload)
+
+          if return_value.is_a?(FalseClass)
+            output.detail('Job returned false, ending pipeline.')
+            break
+          end
+        end
+      end.real.round(3)
+
+      output.ruler
+      output.write("Pipeline ended, took #{time_in_seconds} second(s) to complete")
+
+      payload
+    end
+
+    private
+
+    def output_params(params, output)
+      if params.keys.any?
+        output.write('Parameters:')
+      else
+        output.write('No parameters passed in.')
+      end
+
+      params.each { |key, value| output.detail("#{key}: #{value}") }
+    end
+  end
+end

data/lib/burner/step.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2020-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Burner
+  # A wrapper to execute a job (in the context of a Pipeline.)
+  class Step
+    extend Forwardable
+
+    SEPARATOR = '::'
+
+    private_constant :SEPARATOR
+
+    attr_reader :job
+
+    def_delegators :job, :name
+
+    def initialize(job)
+      raise ArgumentError, 'job is required' unless job
+
+      @job = job
+
+      freeze
+    end
+
+    def perform(output, payload)
+      return_value = nil
+
+      output.title("#{job.class.name}#{SEPARATOR}#{job.name}")
+
+      time_in_seconds = Benchmark.measure do
+        return_value = job.perform(output, payload)
+      end.real.round(3)
+
+      output.complete(time_in_seconds)
+
+      return_value
+    end
+  end
+end

data/lib/burner/string_template.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2020-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Burner
+  # Can take in a string and an object and use the object for formatting string interpolations
+  # using tokens of form: {attribute_name}.  This templating class does not understand nested
+  # structures, so input should be a flat object/hash in the form of key-value pairs.  A benefit of
+  # using Objectable for resolution is that it can understand almost any type of
+  # object: Hash, Struct, OpenStruct, custom objects, etc.
+  # For more information see underlying libraries:
+  #   * Stringento: https://github.com/bluemarblepayroll/stringento
+  #   * Objectable: https://github.com/bluemarblepayroll/objectable
+  class StringTemplate
+    include Singleton
+
+    attr_reader :resolver
+
+    def initialize
+      @resolver = Objectable.resolver(separator: '')
+
+      freeze
+    end
+
+    # For general consumption
+    def evaluate(expression, input)
+      Stringento.evaluate(expression, input, resolver: self)
+    end
+
+    # For Stringento consumption
+    def resolve(value, input)
+      resolver.get(input, value)
+    end
+  end
+end

data/lib/burner/version.rb

@@ -8,5 +8,5 @@
 #
 
 module Burner
-  VERSION = '0.0.0'
+  VERSION = '1.0.0-alpha.4'
 end

data/lib/burner/written_file.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2020-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Burner
+  # Describes a file that was generated by a Job.  If a Job emits a file, it should also add the
+  # file details to the Payload#written_files array using the Payload#add_written_file method.
+  class WrittenFile
+    acts_as_hashable
+
+    attr_reader :logical_filename,
+                :physical_filename,
+                :time_in_seconds
+
+    def initialize(logical_filename:, physical_filename:, time_in_seconds:)
+      @logical_filename  = logical_filename.to_s
+      @physical_filename = physical_filename.to_s
+      @time_in_seconds   = time_in_seconds.to_f
+
+      freeze
+    end
+  end
+end