chutzen 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e078b40512684bbdd04c341199d45ed740749194fa8a1154cc3760afdd9cefeb
-  data.tar.gz: 2eca64fa5545fc9c7722ab06fd5456458b31e7347248bb67f30237616c1c24e7
+  metadata.gz: d5150871b332694272fd6cd676916cc8b710c13e7f4f47cdfd717b0b5517a398
+  data.tar.gz: b47c1877522ef2082e3d507a03c735a817906cd751da307aaa94bf81ae678972
 SHA512:
-  metadata.gz: 2f53fd4ea333c556f30143fc580b8b5c0fb9d2450bf093c29e9c60f97147836c280b6b999ed33c13ff1c807004bb7b132f994fea0881d4ee4f3730300a974cd8
-  data.tar.gz: 943189ce50907777c0d663e4c755277dabe35fbbeadcded292c53dd657b0a766f55aff5d88dc3cee6b47e94bf932694b0849f88fac1fa02c43e6f905c95548c5
+  metadata.gz: 56cbd867e92a2f6bd9e0cc3ce366e84099f7f5f82b1a46f3126c578692c1af764ccecb96156e93fa893975e6e3aad46d34f3c729166da53939faa9fe9525c5ec
+  data.tar.gz: a597dfd4348eddf963d3e815fdb6734a6f545a9c01180524cfff41593fd0e18cdea5f1de0bf5170fc9d3e854c793e81181bff526611e3d523c19066450b0e239

data/README.md

@@ -139,6 +139,10 @@ When *execute* contain a string it will be passed to be executed verbatim. An Ar
 The *fail_when* section can contain any of the following options:
 
 * read_timeout: Check if the stdout or stderr grows and kill the command if this doesn't happen for the specified number of seconds.
+* ~~runtime: Check the runtime of the command and kill it when it runs for more than the specified number of seconds.~~
+* select_timeout: Read and runtime checking use select on the process output. The timeout is normally computed as `[read_timeout, runtime].compact.min / 2.0` but you can force a different value if necessary.
+
+> The runtime option is currently accepted, but not enforced. This may return in the future.
 
 ### Merge description
 
@@ -229,7 +233,7 @@ Now we can schedule the `Chutzen::Signal` worker through the `emit_signal` conve
 
 Downside of using a job is that you can enqueue multiple signals which may keep stopping Chutzen.
 
-    20.times { Chutzen.emit_signal('stop', queue: 'chutzen-13') } 
+    20.times { Chutzen.emit_signal('stop', queue: 'chutzen-13') }
 
 That is why a `Chutzen::Signal` worker will, by default, only process within 30 seconds after is was enqueued. The expiration time can be expressed in a number of ways if you don't like the default.
 
@@ -239,6 +243,38 @@ That is why a `Chutzen::Signal` worker will, by default, only process within 30
       set(queue: 'chutzen-5-test').
       perform_async('stop', (Time.now + 10).to_i)
 
-## New Relic integrations
-
-Chutzen can send custom metrics and exceptions to New Relic. The New Relic gem is ‘dynamically’ loaded so you have to make sure it's installed for this to work. You also have to provide a valid `confg/newrelic.yml` file relative to the working directory where Chutzen is started.
+## Mocking
+
+Chutzen descriptions can get relatively complex and you may want to use a mock to test logic. You can do this by mocking commands:
+
+    Chutzen.mocked(
+      'ls' => lamda do
+        # Generally you only access stdout and stderr from mocks and return
+        # the exit status code.
+        stdout.puts("app test")
+        0
+      end,
+      'unknown' => lambda do
+        # The mock uses the basepath of the executed path to look up the
+        # Proc. So /path/to/unknown becomes unknown. Use the 127 exit status
+        # to simulate a missing binary.
+        127
+      end,
+      # The value returned from the Proc is cast to an integer, so this is
+      # zero.
+      'zero' => -> {},
+      # You have full access to the Chutzen::Command internals, but these
+      # mocks may break when internals change.
+      'hack' => lambda do 
+        @dictionary['width'] = '201'
+      	0
+      end,
+    ) do
+      # Any command executed in the same process/thread will now use the mocked
+      # commands instead of using Open3 to execute it.
+      Command.new(
+      	{ "execute" => "ls" },
+        dictionary:,
+        work_path:
+      ).perform
+    end

data/lib/chutzen/command.rb

@@ -6,7 +6,7 @@ require 'stringio'
 module Chutzen
   # Holds a description for a command and executes it.
   class Command
-    ALLOW_EVAL = /\A[\d<>=\s]+\z/.freeze
+    ALLOW_EVAL = /\A[\d<>=\s]+\z/
 
     autoload :ExecutionFailed, 'chutzen/command/execution_failed'
 
@@ -58,11 +58,19 @@ module Chutzen
     def perform
       return if skip?
 
-      result = @execute ? perform_command : self
+      result = @execute ? perform_command_or_mock : self
       merge_remember_into_dictionary
       result
     end
 
+    def perform_command_or_mock
+      if Chutzen.mock
+        perform_mock
+      else
+        perform_command
+      end
+    end
+
     def perform_command
       trace_execution do
         # We use the STOP signal to instruct Sidekiq to stop reading from the queue and the TERM
@@ -87,6 +95,13 @@ module Chutzen
       end
     end
 
+    def perform_mock
+      @exit_status = ExitStatus.new(Chutzen.mock.perform(self).to_i)
+      verify_exit_status
+      merge_output_into_dictionary
+      self
+    end
+
     # Returns the result expressed by the result section but with its variables
     # instantiated.
     def result
@@ -137,18 +152,17 @@ module Chutzen
     end
 
     def monitor(stdout, stderr, thread)
-      watcher = Watcher.new(fail_when: @fail_when, files: [@stdout, @stderr])
-      wait_until_done(
-        Demux.new(
-          stdout, $stdout, @stdout, select_timeout: watcher.select_timeout
-        ),
-        Demux.new(
-          stderr, $stderr, @stderr, select_timeout: watcher.select_timeout
-        ),
-        watcher
-      )
-    rescue Chutzen::Watcher::Error => e
-      Process.kill('KILL', thread.pid)
+      fail_when = FailWhen.new(@fail_when)
+      [
+        Demux.thread(stdout, $stdout, @stdout, select_timeout: fail_when.select_timeout),
+        Demux.thread(stderr, $stderr, @stderr, select_timeout: fail_when.select_timeout)
+      ].each(&:join)
+    rescue Chutzen::Demux::Error => e
+      begin
+        Process.kill('KILL', thread.pid)
+      rescue Errno::ESRCH
+        # Means the process doesn't exist so it already stopped.
+      end
       raise ExecutionFailed.new(e.message, command: self) unless optional?
     end
 
@@ -198,19 +212,9 @@ module Chutzen
       end
     end
 
-    def trace_execution(&block)
-      if defined?(::NewRelic)
-        NewRelic::Agent::MethodTracer.trace_execution_scoped(
-          transaction_scope,
-          &block
-        )
-      else
-        yield
-      end
-    end
-
-    def transaction_scope
-      %W[Custom/Command/#{name}]
+    # Placeholder for plugging an exception handler.
+    def trace_execution
+      yield
     end
   end
 end

data/lib/chutzen/demux.rb

@@ -8,28 +8,38 @@ module Chutzen
   #     demux.tick
   #   end
   class Demux
-    BUFFER_SIZE = 1024
-
-    def initialize(input, *output, select_timeout: nil)
-      @input = input
-      @output = output
-      @select_timeout = select_timeout
-      @done = false
+    class Error < StandardError
     end
 
-    def done?
-      @done
-    end
+    BUFFER_SIZE = 4096
 
-    def tick
-      readable = IO.select([@input], nil, nil, @select_timeout)
-      return unless readable
+    def self.thread(...)
+      thread = Thread.new { copy(...) }
+      thread.abort_on_exception = true
+      thread
+    end
 
-      buffer = readable.first.first.read_nonblock(BUFFER_SIZE)
-      @done = buffer.nil?
-      @output.each { |stream| stream.write(buffer) }
-    rescue IOError
-      @done = true
+    # rubocop:disable Metrics/MethodLength
+    def self.copy(input, *output, select_timeout: nil)
+      done = false
+      until done
+        result = input.read_nonblock(BUFFER_SIZE, exception: false)
+        case result
+        when String
+          output.each do |stream|
+            stream.write(result)
+            stream.flush
+          end
+        when :wait_readable
+          IO.select([input], nil, nil, select_timeout)
+        when nil
+          # End of file.
+        else
+          raise Error, "Demuxer encountered unsupported read_nonblock return value `#{result}'"
+        end
+        done = input.eof?
+      end
     end
+    # rubocop:enable Metrics/MethodLength
   end
 end

data/lib/chutzen/dictionary.rb

@@ -82,7 +82,7 @@ module Chutzen
       else
         data.each do |name, value|
           path = search(value, key)
-          return (path << name) if path
+          return path << name if path
         end
         nil
       end
@@ -91,7 +91,7 @@ module Chutzen
     def self.search_array(data, key)
       data.each.with_index do |item, index|
         path = search(item, key)
-        return (path << index) if path
+        return path << index if path
       end
       nil
     end

data/lib/chutzen/exit_status.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'parslet'
+
+module Chutzen
+  # Used to mock an exit status normally provided by executing something through Open3.
+  ExitStatus = Data.define(:status) do
+    def to_i
+      status.to_i
+    end
+
+    def success?
+      status.zero?
+    end
+  end
+end

data/lib/chutzen/expression.rb

@@ -9,7 +9,7 @@ module Chutzen
     autoload :SyntaxError, 'chutzen/expression/syntax_error'
     autoload :LookupError, 'chutzen/expression/lookup_error'
 
-    INTEGER_RE = /\A\d+\z/.freeze
+    INTEGER_RE = /\A\d+\z/
     OPERATIONS = {
       '=' => ->(left, right) { left == right },
       '&' => ->(left, right) { left & right },

data/lib/chutzen/fail_when.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Chutzen
+  # Value class to contain details about when to fail a command.
+  #
+  #   FailWhen.new(
+  #     {
+  #       'read_timeout' => 2,
+  #       'runtime' => 60
+  #     }
+  #   )
+  class FailWhen
+    attr_reader :read_timeout, :runtime
+
+    def initialize(fail_when = nil)
+      fail_when&.each do |name, value|
+        instance_variable_set("@#{name}", value)
+      end
+    end
+
+    def select_timeout
+      return @select_timeout if defined?(@select_timeout)
+
+      minimal_timeout = [read_timeout, runtime].compact.min
+      return unless minimal_timeout
+
+      minimal_timeout / 2.0
+    end
+  end
+end

data/lib/chutzen/mock.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Chutzen
+  # Keeps mocked commands and executes Command instances against them.
+  class Mock
+    attr_reader :mocks
+
+    def initialize(mocks)
+      @mocks = mocks
+    end
+
+    def perform(command)
+      name = File.basename(command.to_s.split(' ', 2).first.to_s)
+      command.instance_exec(&mocks.fetch(name))
+    end
+  end
+end

data/lib/chutzen/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Chutzen
-  VERSION = '0.8.0'
+  VERSION = '0.9.0'
 end

data/lib/chutzen.rb

@@ -3,23 +3,18 @@
 require 'json'
 require 'sidekiq/api'
 
-# Disabled to allow optional loading of the New Relic gem.
-# rubocop:disable Lint/SuppressedException
-begin
-  require 'newrelic_rpm'
-rescue LoadError
-end
-# rubocop:enable Lint/SuppressedException
-
 # Implements a toolkit to perform batch processing.
 module Chutzen
   autoload :Apply, 'chutzen/apply'
   autoload :Command, 'chutzen/command'
   autoload :Demux, 'chutzen/demux'
   autoload :Dictionary, 'chutzen/dictionary'
+  autoload :ExitStatus, 'chutzen/exit_status'
   autoload :Expression, 'chutzen/expression'
   autoload :ExpressionParser, 'chutzen/expression_parser'
+  autoload :FailWhen, 'chutzen/fail_when'
   autoload :Job, 'chutzen/job'
+  autoload :Mock, 'chutzen/mock'
   autoload :Notification, 'chutzen/notification'
   autoload :RuntimeError, 'chutzen/runtime_error'
   autoload :Shell, 'chutzen/shell'
@@ -28,18 +23,29 @@ module Chutzen
   autoload :Template, 'chutzen/template'
   autoload :TemplateParser, 'chutzen/template_parser'
   autoload :VERSION, 'chutzen/version'
-  autoload :Watcher, 'chutzen/watcher'
   autoload :Worker, 'chutzen/worker'
 
   class << self
-    attr_accessor :sidekiq_queue
+    attr_accessor :sidekiq_queue, :mock
   end
   self.sidekiq_queue = 'chutzen'
+  self.mock = nil
 
   # Enqueue a Sidekiq job that will eventually perform the job in the
   # description.
-  def self.perform_async(description)
-    Chutzen::Worker.perform_async(JSON.dump(description))
+  #
+  # * +queue+: Override +Chutzen.sidekiq_queue+.
+  def self.perform_async(description, queue: nil)
+    async_worker(queue: queue).perform_async(JSON.dump(description))
+  end
+
+  # Configures a worker class for asynchronous processing.
+  #
+  # * +queue+: Override +Chutzen.sidekiq_queue+.
+  def self.async_worker(queue: nil)
+    worker = Chutzen::Worker
+    worker = worker.set(queue: queue) if queue
+    worker
   end
 
   # Enqueue a Sidekiq job that will eventually process the signal. It's
@@ -63,8 +69,11 @@ module Chutzen
   end
 
   # Dequeue all jobs that match the query. Uses Chutzen's own query format.
-  def self.dequeue(query)
-    Sidekiq::Queue.new(sidekiq_queue).each do |job|
+  #
+  # * +queue+: Override +Chutzen.sidekiq_queue+.
+  def self.dequeue(query, queue: nil)
+    queue ||= sidekiq_queue
+    Sidekiq::Queue.new(queue).each do |job|
       dictionary = Chutzen::Dictionary.new(JSON.parse(job.args.first))
       expression = Chutzen::Expression.new(query, dictionary)
       job.delete if expression.result
@@ -84,4 +93,12 @@ module Chutzen
     expires_in ||= 30
     (Time.now + expires_in).to_i
   end
+
+  # Sets the global mock instance for the duration of the block.
+  def self.mocked(**)
+    self.mock = Chutzen::Mock.new(**)
+    yield
+  ensure
+    self.mock = nil
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: chutzen
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Manfred Stienstra
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-04-02 00:00:00.000000000 Z
+date: 2026-09-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: parslet
@@ -30,28 +30,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '7.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
-- !ruby/object:Gem::Dependency
-  name: newrelic_rpm
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">"
-      - !ruby/object:Gem::Version
-        version: '6.10'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">"
-      - !ruby/object:Gem::Version
-        version: '6.10'
+        version: '7.0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -95,11 +81,14 @@ files:
 - lib/chutzen/command/execution_failed.rb
 - lib/chutzen/demux.rb
 - lib/chutzen/dictionary.rb
+- lib/chutzen/exit_status.rb
 - lib/chutzen/expression.rb
 - lib/chutzen/expression/lookup_error.rb
 - lib/chutzen/expression/syntax_error.rb
 - lib/chutzen/expression_parser.rb
+- lib/chutzen/fail_when.rb
 - lib/chutzen/job.rb
+- lib/chutzen/mock.rb
 - lib/chutzen/notification.rb
 - lib/chutzen/runtime_error.rb
 - lib/chutzen/shell.rb
@@ -109,7 +98,6 @@ files:
 - lib/chutzen/template/syntax_error.rb
 - lib/chutzen/template_parser.rb
 - lib/chutzen/version.rb
-- lib/chutzen/watcher.rb
 - lib/chutzen/worker.rb
 homepage:
 licenses: []
@@ -122,14 +110,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.7'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: Toolkit to implement batch processing.

data/lib/chutzen/watcher.rb

@@ -1,111 +0,0 @@
-# frozen_string_literal: true
-
-module Chutzen
-  # Watches the current process to make sure it's still running as intended.
-  #
-  # You can set a watcher to make sure a list of files increases in size at
-  # least every ‘read_timeout’ seconds.
-  #
-  #   watcher = Watcher.new(
-  #     fail_when: {
-  #       'read_timeout' => 2,
-  #       'runtime' => 60
-  #     },
-  #     files: [file]
-  #   )
-  #   until watcher.done?
-  #     watcher.tick
-  #   end
-  class Watcher
-    class Error < StandardError
-    end
-
-    attr_reader :read_timeout, :runtime
-
-    def initialize(fail_when: nil, files: nil)
-      fail_when&.each do |name, value|
-        instance_variable_set("@#{name}", value)
-      end
-      @started_at = now
-      @files = files
-      reset
-    end
-
-    def select_timeout
-      return @select_timeout if defined?(@select_timeout)
-
-      minimal_timeout = [read_timeout, runtime].compact.min
-      return unless minimal_timeout
-
-      minimal_timeout / 2.0
-    end
-
-    def done?
-      # Because demuxers and the watcher share an interface we need to the
-      # watcher to explain the thread doesn't have to wait for it.
-      true
-    end
-
-    # Raises an exception when any of the failure conditions is reached.
-    def tick
-      compute_last_read
-      verify_last_read
-      verify_runtime
-    end
-
-    private
-
-    def total_bytes_read
-      return unless @files
-
-      @files.inject(0) { |total, file| total + file.size }
-    end
-
-    def last_read_ago
-      now - @last_read_at
-    end
-
-    def compute_last_read
-      return unless read_timeout && @files
-
-      bytes_read = total_bytes_read
-      @last_read_at = now if bytes_read != @bytes_read
-      @bytes_read = bytes_read
-    end
-
-    def verify_last_read
-      return unless read_timeout && @files
-      return if last_read_ago < read_timeout
-
-      raise(
-        Error,
-        "Command did not write to its output for more than #{read_timeout} " \
-        'seconds.'
-      )
-    end
-
-    def ran
-      now - @started_at
-    end
-
-    def verify_runtime
-      return unless runtime
-      return if ran < runtime
-
-      raise(
-        Error,
-        "Command did not finish within the alotted runtime #{runtime} " \
-        'seconds.'
-      )
-    end
-
-    def reset
-      @last_read_at = now
-      @bytes_read = 0
-    end
-
-    def now
-      Process.clock_gettime(Process::CLOCK_MONOTONIC)
-    end
-  end
-end