cmdx 0.1.0

data/lib/cmdx/log_formatters/line.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module CMDx
+  module LogFormatters
+    class Line
+
+      def call(severity, time, progname, message)
+        message = message.map { |k, v| "#{k}=#{v}" }.join(" ")
+        "#{severity[0]}, [#{Utils::DatetimeFormatter.call(time.utc)} ##{Process.pid}] #{severity} -- #{progname || 'CMDx'}: #{message}"
+      end
+
+    end
+  end
+end

data/lib/cmdx/log_formatters/logstash.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module CMDx
+  module LogFormatters
+    class Logstash
+
+      def call(_severity, time, _progname, message)
+        if message.is_a?(Hash)
+          message["@version"]   ||= "1"
+          message["@timestamp"] ||= Utils::DatetimeFormatter.call(time.utc)
+        end
+
+        JSON.dump(message)
+      end
+
+    end
+  end
+end

data/lib/cmdx/log_formatters/raw.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module CMDx
+  module LogFormatters
+    class Raw
+
+      def call(_severity, _time, _progname, message)
+        message
+      end
+
+    end
+  end
+end

data/lib/cmdx/logger.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module CMDx
+  module Logger
+
+    module_function
+
+    def call(task)
+      logger           = task.task_setting(:logger)
+      logger.formatter = task.task_setting(:log_formatter) if task.task_setting?(:log_formatter)
+      logger.level     = task.task_setting(:log_level) if task.task_setting?(:log_level)
+      logger
+    end
+
+  end
+end

data/lib/cmdx/parameter.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module CMDx
+  class Parameter
+
+    __cmdx_attr_delegator :invalid?, :valid?, to: :errors
+
+    attr_accessor :task
+    attr_reader :klass, :parent, :name, :type, :options, :children, :errors
+
+    def initialize(name, **options, &)
+      @klass    = options.delete(:klass) || raise(KeyError, "klass option required")
+      @parent   = options.delete(:parent)
+      @type     = options.delete(:type) || :virtual
+      @required = options.delete(:required) || false
+
+      @name     = name
+      @options  = options
+      @children = []
+      @errors   = Errors.new
+
+      define_attribute(self)
+      instance_eval(&) if block_given?
+    end
+
+    class << self
+
+      def optional(*names, **options, &)
+        if names.none?
+          raise ArgumentError, "no parameters given"
+        elsif !names.one? && options.key?(:as)
+          raise ArgumentError, ":as option only supports one parameter per definition"
+        end
+
+        names.filter_map { |n| new(n, **options, &) }
+      end
+
+      def required(*names, **options, &)
+        optional(*names, **options.merge(required: true), &)
+      end
+
+    end
+
+    def optional(*names, **options, &)
+      parameters = Parameter.optional(*names, **options.merge(klass: @klass, parent: self), &)
+      children.concat(parameters)
+    end
+
+    def required(*names, **options, &)
+      parameters = Parameter.required(*names, **options.merge(klass: @klass, parent: self), &)
+      children.concat(parameters)
+    end
+
+    def required?
+      !!@required
+    end
+
+    def optional?
+      !required?
+    end
+
+    def method_name
+      @method_name ||= Utils::MethodName.call(name, method_source, options)
+    end
+
+    def method_source
+      @method_source ||= options[:source] || parent&.method_name || :context
+    end
+
+    def to_h
+      ParameterSerializer.call(self)
+    end
+
+    def to_s
+      ParameterInspector.call(to_h)
+    end
+
+    private
+
+    def define_attribute(parameter)
+      klass.send(:define_method, parameter.method_name) do
+        @parameters_cache ||= {}
+        return @parameters_cache[parameter.method_name] if @parameters_cache.key?(parameter.method_name)
+
+        begin
+          parameter_value = ParameterValue.new(self, parameter).call
+        rescue CoercionError, ValidationError => e
+          parameter.errors.add(parameter.method_name, e.message)
+          errors.merge!(parameter.errors.to_hash)
+        ensure
+          @parameters_cache[parameter.method_name] = parameter_value
+        end
+
+        @parameters_cache[parameter.method_name]
+      end
+
+      klass.send(:private, parameter.method_name)
+    end
+
+  end
+end

data/lib/cmdx/parameter_inspector.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module CMDx
+  module ParameterInspector
+
+    ORDERED_KEYS = %i[
+      name type source required options children
+    ].freeze
+
+    module_function
+
+    def call(parameter, depth = 1)
+      ORDERED_KEYS.filter_map do |key|
+        value = parameter[key]
+        next "#{key}=#{value}" unless key == :children
+
+        spaces = " " * (depth * 2)
+        value.map { |h| "\n#{spaces}↳ #{call(h, depth + 1)}" }.join
+      end.unshift("Parameter:").join(" ")
+    end
+
+  end
+end

data/lib/cmdx/parameter_serializer.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module CMDx
+  module ParameterSerializer
+
+    module_function
+
+    def call(parameter)
+      {
+        source: parameter.method_source,
+        name: parameter.method_name,
+        type: parameter.type,
+        required: parameter.required?,
+        options: parameter.options,
+        children: parameter.children.map(&:to_h)
+      }
+    end
+
+  end
+end

data/lib/cmdx/parameter_validator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module CMDx
+  module ParameterValidator
+
+    module_function
+
+    def call(task)
+      task.class.cmd_parameters.validate!(task)
+      return if task.errors.empty?
+
+      task.fail!(
+        reason: task.errors.full_messages.join(". "),
+        messages: task.errors.messages
+      )
+    end
+
+  end
+end

data/lib/cmdx/parameter_value.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module CMDx
+  class ParameterValue
+
+    __cmdx_attr_delegator :parent, :method_source, :name, :options, :required?, :optional?, :type, to: :parameter, private: true
+
+    attr_reader :task, :parameter
+
+    def initialize(task, parameter)
+      @task      = task
+      @parameter = parameter
+    end
+
+    def call
+      coerce!.tap { validate! }
+    end
+
+    private
+
+    def source_defined?
+      task.respond_to?(method_source, true) || task.__cmdx_try(method_source)
+    end
+
+    def source
+      return @source if defined?(@source)
+
+      unless source_defined?
+        raise ValidationError, I18n.t(
+          "cmdx.parameters.undefined",
+          default: "delegates to undefined method #{method_source}",
+          source: method_source
+        )
+      end
+
+      @source = task.__cmdx_try(method_source)
+    end
+
+    def source_value?
+      return false if source.nil?
+
+      source.__cmdx_respond_to?(name, true)
+    end
+
+    def source_value_required?
+      return false if parent&.optional? && source.nil?
+
+      required? && !source_value?
+    end
+
+    def value
+      return @value if defined?(@value)
+
+      if source_value_required?
+        raise ValidationError, I18n.t(
+          "cmdx.parameters.required",
+          default: "is a required parameter"
+        )
+      end
+
+      @value = source.__cmdx_try(name)
+      return @value unless @value.nil? && options.key?(:default)
+
+      @value = task.__cmdx_yield(options[:default])
+    end
+
+    def coerce!
+      types = Array(type)
+      tsize = types.size - 1
+
+      types.each_with_index do |t, i|
+        break case t.to_sym
+              when :array then Coercions::Array
+              when :big_decimal then Coercions::BigDecimal
+              when :boolean then Coercions::Boolean
+              when :complex then Coercions::Complex
+              when :date then Coercions::Date
+              when :datetime then Coercions::DateTime
+              when :float then Coercions::Float
+              when :hash then Coercions::Hash
+              when :integer then Coercions::Integer
+              when :rational then Coercions::Rational
+              when :string then Coercions::String
+              when :time then Coercion::Time
+              when :virtual then Coercions::Virtual
+              else raise UnknownCoercionError, "unknown coercion #{t}"
+              end.call(value, options)
+      rescue CoercionError => e
+        next if tsize != i
+
+        raise(e) if tsize.zero?
+
+        values = types.map(&:to_s).join(", ")
+        raise CoercionError, I18n.t(
+          "cmdx.coercions.into_any",
+          values:,
+          default: "could not coerce into one of: #{values}"
+        )
+      end
+    end
+
+    def skip_validations_due_to_optional_missing_argument?
+      optional? && value.nil? && !source.nil? && !source.__cmdx_respond_to?(name, true)
+    end
+
+    def skip_validator_due_to_conditional?(key)
+      opts = options[key]
+      opts.is_a?(Hash) && !task.__cmdx_eval(opts)
+    end
+
+    def skip_validator_due_to_allow_nil?(key)
+      opts = options[key]
+      opts.is_a?(Hash) && opts[:allow_nil] && value.nil?
+    end
+
+    def validate!
+      return if skip_validations_due_to_optional_missing_argument?
+
+      options.each_key do |key|
+        next if skip_validator_due_to_allow_nil?(key)
+        next if skip_validator_due_to_conditional?(key)
+
+        case key.to_sym
+        when :custom then Validators::Custom
+        when :exclusion then Validators::Exclusion
+        when :format then Validators::Format
+        when :inclusion then Validators::Inclusion
+        when :length then Validators::Length
+        when :numeric then Validators::Numeric
+        when :presence then Validators::Presence
+        end&.call(value, options)
+      end
+    end
+
+  end
+end

data/lib/cmdx/parameters.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module CMDx
+  class Parameters < Array
+
+    def invalid?
+      !valid?
+    end
+
+    def valid?
+      all?(&:valid?)
+    end
+
+    def validate!(task)
+      each { |p| recursive_validate!(task, p) }
+    end
+
+    def to_h
+      ParametersSerializer.call(self)
+    end
+
+    def to_s
+      ParametersInspector.call(self)
+    end
+
+    private
+
+    def recursive_validate!(task, parameter)
+      task.send(parameter.method_name)
+      parameter.children.each { |cp| recursive_validate!(task, cp) }
+    end
+
+  end
+end

data/lib/cmdx/parameters_inspector.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module CMDx
+  module ParametersInspector
+
+    module_function
+
+    def call(parameters)
+      parameters.map(&:to_s).join("\n")
+    end
+
+  end
+end

data/lib/cmdx/parameters_serializer.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module CMDx
+  module ParametersSerializer
+
+    module_function
+
+    def call(parameters)
+      parameters.map(&:to_h)
+    end
+
+  end
+end

data/lib/cmdx/railtie.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module CMDx
+  class Railtie < Rails::Railtie
+
+    CONCEPTS = %w[batches tasks].freeze
+
+    railtie_name :cmdx
+
+    initializer("cmdx.configure_locales") do |app|
+      Array(app.config.i18n.available_locales).each do |locale|
+        path = File.expand_path("../../../lib/locales/#{locale}.yml", __FILE__)
+        next unless File.file?(path)
+
+        I18n.load_path << path
+      end
+
+      I18n.reload!
+    end
+
+    initializer("cmdx.configure_rails_auto_load_paths") do |app|
+      app.config.autoload_paths += %w[app/cmds]
+      app.autoloaders.each do |autoloader|
+        CONCEPTS.each do |concept|
+          dir = app.root.join("app/cmds/#{concept}")
+          autoloader.collapse(dir)
+        end
+      end
+    end
+
+  end
+end

data/lib/cmdx/result.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module CMDx
+  class Result
+
+    __cmdx_attr_delegator :context, :run, to: :task
+
+    attr_reader :task, :state, :status, :metadata
+
+    def initialize(task)
+      raise ArgumentError, "must be a Task or Batch" unless task.is_a?(Task)
+
+      @task     = task
+      @state    = INITIALIZED
+      @status   = SUCCESS
+      @metadata = {}
+    end
+
+    STATES = [
+      INITIALIZED = "initialized",
+      EXECUTING   = "executing",
+      COMPLETE    = "complete",
+      INTERRUPTED = "interrupted"
+    ].freeze
+
+    STATES.each do |s|
+      # eg: executing?
+      define_method(:"#{s}?") { state == s }
+    end
+
+    def executed?
+      complete? || interrupted?
+    end
+
+    def executing!
+      return if executing?
+
+      raise "can only transition to #{EXECUTING} from #{INITIALIZED}" unless initialized?
+
+      @state = EXECUTING
+    end
+
+    def complete!
+      return if complete?
+
+      raise "can only transition to #{COMPLETE} from #{EXECUTING}" unless executing?
+
+      @state = COMPLETE
+    end
+
+    def interrupt!
+      return if interrupted?
+
+      raise "cannot transition to #{INTERRUPTED} from #{COMPLETE}" if complete?
+
+      @state = INTERRUPTED
+    end
+
+    STATUSES = [
+      SUCCESS = "success",
+      SKIPPED = "skipped",
+      FAILED  = "failed"
+    ].freeze
+
+    STATUSES.each do |s|
+      # eg: skipped?
+      define_method(:"#{s}?") { status == s }
+    end
+
+    def good?
+      !failed?
+    end
+
+    def bad?
+      !success?
+    end
+
+    def skip!(**metadata)
+      return if skipped?
+
+      raise "can only transition to #{SKIPPED} from #{SUCCESS}" unless success?
+
+      @status   = SKIPPED
+      @metadata = metadata
+
+      halt! unless metadata[:original_exception]
+    end
+
+    def fail!(**metadata)
+      return if failed?
+
+      raise "can only transition to #{FAILED} from #{SUCCESS}" unless success?
+
+      @status   = FAILED
+      @metadata = metadata
+
+      halt! unless metadata[:original_exception]
+    end
+
+    def halt!
+      return if success?
+
+      raise Fault.build(self)
+    end
+
+    def throw!(result)
+      raise ArgumentError, "must be a Result" unless result.is_a?(Result)
+
+      skip!(**result.metadata) if result.skipped?
+      fail!(**result.metadata) if result.failed?
+    end
+
+    def caused_failure
+      return unless failed?
+
+      run.results.reverse.find(&:failed?)
+    end
+
+    def caused_failure?
+      return false unless failed?
+
+      caused_failure == self
+    end
+
+    def threw_failure
+      return unless failed?
+
+      results = run.results.select(&:failed?)
+      results.find { |r| r.index > index } || results.last
+    end
+
+    def threw_failure?
+      return false unless failed?
+
+      threw_failure == self
+    end
+
+    def thrown_failure?
+      failed? && !caused_failure?
+    end
+
+    def index
+      run.index(self)
+    end
+
+    def outcome
+      initialized? || thrown_failure? ? state : status
+    end
+
+    def runtime(&block)
+      return @runtime unless block_given?
+
+      timeout_type = is_a?(Batch) ? :batch_timeout : :task_timeout
+      timeout_secs = task.task_setting(timeout_type)
+
+      Timeout.timeout(timeout_secs, TimeoutError, "execution exceeded #{timeout_secs} seconds") do
+        @runtime = Utils::Runtime.call(&block)
+      end
+    end
+
+    def to_h
+      ResultSerializer.call(self)
+    end
+
+    def to_s
+      ResultInspector.call(to_h)
+    end
+
+  end
+end

data/lib/cmdx/result_inspector.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module CMDx
+  module ResultInspector
+
+    ORDERED_KEYS = %i[
+      class type index id state status outcome metadata
+      tags pid runtime caused_failure threw_failure
+    ].freeze
+
+    module_function
+
+    def call(result)
+      ORDERED_KEYS.filter_map do |key|
+        next unless result.key?(key)
+
+        value = result[key]
+
+        case key
+        when :class
+          "#{value}:"
+        when :caused_failure, :threw_failure
+          "#{key}=<[#{value[:index]}] #{value[:class]}: #{value[:id]}>"
+        else
+          "#{key}=#{value}"
+        end
+      end.join(" ")
+    end
+
+  end
+end

data/lib/cmdx/result_logger.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module CMDx
+  module ResultLogger
+
+    STATUS_TO_LEVEL = {
+      Result::SUCCESS => :info,
+      Result::SKIPPED => :warn,
+      Result::FAILED => :error
+    }.freeze
+
+    module_function
+
+    def call(result)
+      logger = result.task.send(:logger)
+      status = STATUS_TO_LEVEL[result.status]
+
+      logger.send(status) { result.to_h }
+    end
+
+  end
+end