exel 1.2.1 → 1.5.2

data/lib/exel.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'exel/version'
 require 'exel/logging'
 require 'ostruct'
@@ -18,7 +20,7 @@ module EXEL
 
   # @return The current configuration
   def self.configuration
-    @config ||= OpenStruct.new
+    @config ||= OpenStruct.new(middleware: Middleware::Chain.new)
   end
 
   # Yields the configuration object to the given block. Configuration can include:
@@ -46,6 +48,10 @@ module EXEL
     configuration.remote_provider || Providers::LocalFileProvider
   end
 
+  def self.middleware
+    configuration.middleware
+  end
+
   root = File.expand_path('../..', __FILE__)
   Dir[File.join(root, 'lib/exel/**/*.rb')].each { |file| require file }
 end

data/lib/exel/ast_node.rb

@@ -1,15 +1,19 @@
+# frozen_string_literal: true
+
 module EXEL
   # An abstract class that serves as the parent class of nodes in the AST
   class ASTNode
     attr_reader :instruction, :children
 
-    def initialize(instruction, children = [])
+    def initialize(instruction, children: [])
       @instruction = instruction
       @children = children
     end
 
     def start(context)
-      fail_silently { run(context) }
+      run(context)
+    rescue EXEL::Error::JobTermination => e
+      EXEL.logger.send(e.cmd, "JobTerminationError: #{e.message.chomp}")
     end
 
     def run(_context)
@@ -19,13 +23,5 @@ module EXEL
     def add_child(node)
       @children << node
     end
-
-    private
-
-    def fail_silently(&_block)
-      yield if block_given?
-    rescue EXEL::Error::JobTermination => e
-      EXEL.logger.error "JobTerminationError: #{e.message.chomp}"
-    end
   end
 end

data/lib/exel/context.rb

@@ -1,4 +1,7 @@
+# frozen_string_literal: true
+
 require 'tempfile'
+require 'securerandom'
 
 module EXEL
   # The +Context+ is the shared memory of a running job. It acts as the source of input to processors and the place for
@@ -32,7 +35,7 @@ module EXEL
       file = EXEL::Value.localize(uri)
 
       begin
-        context = Marshal.load(file.read)
+        context = Marshal.load(file.read) # rubocop:disable Airbnb/UnsafeYamlMarshal
       ensure
         file.close
       end

data/lib/exel/deferred_context_value.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module EXEL
   # When +context+ is referenced in a job definition, an instance of +DeferredContextValue+ will be put in its place.
   # At runtime, the first time a +DeferredContextValue+ is read via {EXEL::Context#[]}, it will be replaced by the value
@@ -47,7 +49,7 @@ module EXEL
 
     # Given a context, returns the value that this instance was acting as a placeholder for.
     def get(context)
-      keys.reduce(context) { |a, e| a[e] }
+      keys.reduce(context) { |acc, elem| acc[elem] }
     end
   end
 end

data/lib/exel/error/job_termination.rb

@@ -1,8 +1,20 @@
+# frozen_string_literal: true
+
+# rubocop:disable Lint/InheritException
 module EXEL
   module Error
     # If a processor raises a JobTermination exception, the job will immediately stop running without raising anything.
     # This is useful if you want to stop a job without triggering any kind of retry mechanism, for example.
     class JobTermination < Exception # Inherit from Exception so it won't be rescued and can propagate to ASTNode#start
+      attr_reader :cmd
+
+      CMDS = [:info, :warn, :error].freeze
+
+      def initialize(message = nil, cmd = :error)
+        super(message)
+        @cmd = CMDS.include?(cmd) ? cmd : :error
+      end
     end
   end
 end
+# rubocop:enable Lint/InheritException

data/lib/exel/events.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module EXEL
   # Provides methods for registering and triggering event listeners
   module Events
@@ -11,6 +13,10 @@ module EXEL
       listeners_for_event(event, context).each { |listener| listener.send(event, context, data) }
     end
 
+    def self.included(other)
+      other.class_eval { attr_reader :context }
+    end
+
     private
 
     def listeners_for_event(event, context)

data/lib/exel/instruction.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 module EXEL
   # Represents one step to be executed in the processing of a job
   class Instruction
-    def initialize(processor_class, args, subtree = nil)
+    def initialize(processor_class, args, subtree: nil)
       @processor_class = processor_class
       @args = args || {}
       @subtree = subtree
@@ -9,7 +11,8 @@ module EXEL
 
     def execute(context)
       context.merge!(@args)
-      @processor_class.new(context).process(@subtree)
+      processor = @processor_class.new(context)
+      EXEL.middleware.invoke(@processor_class, context, @args) { processor.process(@subtree) }
     end
   end
 end

data/lib/exel/instruction_node.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative './ast_node'
 
 module EXEL

data/lib/exel/job.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module EXEL
   # The +Job+ module provides the main interface for defining and running EXEL jobs
   module Job
@@ -25,7 +27,9 @@ module EXEL
       # @raise If no job has been registered with the given name
       def run(dsl_code_or_name, context = {})
         context = EXEL::Context.new(context) if context.instance_of?(Hash)
-        (ast = parse(dsl_code_or_name)) ? ast.start(context) : raise(%(Job "#{dsl_code_or_name}" not found))
+        ast = parse(dsl_code_or_name)
+        ast ? ast.start(context) : raise(%(Job "#{dsl_code_or_name}" not found))
+        context
       end
 
       private
@@ -90,9 +94,9 @@ module EXEL
         block.nil? ? nil : Parser.parse(block)
       end
 
-      def add_instruction_node(processor, sub_tree, args = {})
-        instruction = EXEL::Instruction.new(processor, args, sub_tree)
-        node = sub_tree.nil? ? InstructionNode.new(instruction) : InstructionNode.new(instruction, [sub_tree])
+      def add_instruction_node(processor, subtree, args = {})
+        instruction = EXEL::Instruction.new(processor, args, subtree: subtree)
+        node = subtree.nil? ? InstructionNode.new(instruction) : InstructionNode.new(instruction, children: [subtree])
         @ast.add_child(node)
       end
     end

data/lib/exel/listen_instruction.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'events'
 
 module EXEL

data/lib/exel/logging.rb

@@ -1,9 +1,18 @@
+# frozen_string_literal: true
+
 require 'logger'
 
 module EXEL
   module Logging
     DEFAULT_LEVEL = :info
 
+    # Formats log messages with timestamp, severity and Logging prefix (if set via {Logging.with_prefix})
+    class PrefixFormatter < Logger::Formatter
+      def call(severity, time, _program_name, message)
+        "#{time.utc} severity=#{severity}, #{Logging.prefix}#{message}\n"
+      end
+    end
+
     def self.logger
       @logger || initialize_logger
     end
@@ -11,6 +20,7 @@ module EXEL
     def self.initialize_logger
       @logger = Logger.new(log_filename)
       @logger.level = log_level
+      @logger.formatter = PrefixFormatter.new
       @logger
     end
 
@@ -24,7 +34,20 @@ module EXEL
     end
 
     def self.logger=(logger)
-      @logger = logger || Logger.new('/dev/null')
+      @logger = logger ? LoggerWrapper.new(logger) : Logger.new('/dev/null')
+    end
+
+    # Sets a prefix to be added to any messages sent to the EXEL logger in the given block.
+    def self.with_prefix(prefix)
+      Thread.current[:exel_log_prefix] ||= []
+      Thread.current[:exel_log_prefix].push(prefix)
+      yield
+    ensure
+      Thread.current[:exel_log_prefix].pop
+    end
+
+    def self.prefix
+      Thread.current[:exel_log_prefix]&.last
     end
   end
 end

data/lib/exel/logging/logger_wrapper.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module EXEL
+  module Logging
+    # Wraps calls to a logger to add {Logging} prefix to log messages
+    class LoggerWrapper < SimpleDelegator
+      LOG_LEVELS = %i(debug info warn error fatal unknown).freeze
+
+      LOG_LEVELS.each do |level|
+        define_method level do |progname = nil, &block|
+          prefix_block = nil
+
+          if block
+            prefix_block = proc { "#{Logging.prefix}#{block.call}" }
+          else
+            progname = "#{Logging.prefix}#{progname}"
+          end
+
+          __getobj__.send(level, progname, &prefix_block)
+        end
+      end
+
+      def add(severity, message = nil, progname = nil)
+        if message.nil? && block_given?
+          message = yield
+        end
+        __getobj__.add(severity, "#{Logging.prefix}#{message}", progname)
+      end
+    end
+  end
+end

data/lib/exel/logging_helper.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module EXEL
+  # Logging related helper methods for processors
+  module LoggingHelper
+    # @return [Logger] Returns the EXEL logger
+    def logger
+      EXEL.logger
+    end
+
+    # Logs a message with DEBUG severity
+    def log_debug(message)
+      logger.debug(message)
+    end
+
+    # Logs a message with INFO severity
+    def log_info(message)
+      logger.info(message)
+    end
+
+    # Logs a message with WARN severity
+    def log_warn(message)
+      logger.warn(message)
+    end
+
+    # Logs a message with ERROR severity
+    def log_error(message)
+      logger.error(message)
+    end
+
+    # Logs a message with FATAL severity
+    def log_fatal(message)
+      logger.fatal(message)
+    end
+  end
+end

data/lib/exel/middleware/chain.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module EXEL
+  # Middleware is code configured to run around each processor execution. Custom middleware can be added as follows:
+  #
+  #   EXEL.configure do |config|
+  #     config.middleware.add(MyMiddleware)
+  #     config.middleware.add(AnotherMiddleware, 'constructor arg')
+  #   end
+  #
+  # Middleware can be any class that implements a +call+ method that includes a call to +yield+:
+  #
+  #   class MyMiddleware
+  #     def call(processor, context, args)
+  #       puts 'before process'
+  #       yield
+  #       puts 'after process'
+  #     end
+  #   end
+  #
+  # The +call+ method will be passed the class of the processor that will be executed, the current context, and any args
+  # that were passed to the processor in the job definition.
+  module Middleware
+    # Chain of middleware to be invoked in sequence around each processor execution.
+    class Chain
+      attr_reader :entries
+
+      Entry = Struct.new(:klass, :args)
+
+      def initialize
+        @entries = []
+      end
+
+      # Adds a middleware class to the chain. If it is already in the chain it will be removed and added to the end.
+      # Any additional arguments will be passed to +new+ when the middleware is created.
+      def add(klass, *args)
+        remove(klass)
+        @entries << Entry.new(klass, args)
+      end
+
+      # Removes a middleware class from the chain.
+      def remove(klass)
+        @entries.delete_if { |entry| entry.klass == klass }
+      end
+
+      # Returns true if the given class is in the chain.
+      def include?(klass)
+        @entries.any? { |entry| entry.klass == klass }
+      end
+
+      # Calls each middleware in the chain.
+      def invoke(*args)
+        chain = @entries.map { |entry| entry.klass.new(*entry.args) }
+
+        traverse_chain = lambda do
+          if chain.empty?
+            yield
+          else
+            chain.shift.call(*args, &traverse_chain)
+          end
+        end
+
+        traverse_chain.call
+      end
+    end
+  end
+end

data/lib/exel/middleware/logging.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module EXEL
+  module Middleware
+    # Middleware to add a prefix to all messages logged during processor execution. The prefix is specified by the
+    # +:log_prefix+ key in the context. Also logs start, finish, and failure of the processor execution.
+    class Logging
+      def call(processor_class, context, _args, &block)
+        EXEL::Logging.with_prefix("#{context[:log_prefix]}[#{processor_class}] ") { log_process(&block) }
+      end
+
+      private
+
+      def log_process
+        start_time = Time.now
+
+        yield
+
+        EXEL.logger.info "Finished in #{duration(start_time)} seconds"
+      rescue Exception # rubocop:disable Lint/RescueException
+        EXEL.logger.info "Failed in #{duration(start_time)} seconds"
+        raise
+      end
+
+      def duration(start_time)
+        (Time.now - start_time).round(3)
+      end
+    end
+  end
+end

data/lib/exel/null_instruction.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module EXEL
   # An {Instruction} that does nothing when executed
   class NullInstruction

data/lib/exel/processor_helper.rb

@@ -1,6 +1,14 @@
+# frozen_string_literal: true
+
 module EXEL
   # Helper methods useful to processors
+  # @deprecated Most functionality replaced by {EXEL::Middleware::Logging} middleware.
   module ProcessorHelper
+    def self.included(other)
+      warn "DEPRECATION WARNING: [#{other}] EXEL::ProcessorHelper will be removed. For process logging, please use "\
+           'EXEL::Middleware::Logging instead'
+    end
+
     def tag(*tags)
       tags.map { |t| "[#{t}]" }.join('')
     end
@@ -56,7 +64,7 @@ module EXEL
     def ensure_transaction_duration(duration, start_time)
       elapsed_time = Time.now.to_f - start_time.to_f
       time_to_sleep = duration.second.to_f - elapsed_time
-      sleep(time_to_sleep) if time_to_sleep > 0
+      sleep(time_to_sleep) if time_to_sleep.positive?
     end
   end
 end