simple-service 0.1.3

data/lib/simple/service/action.rb

@@ -0,0 +1,203 @@
+module Simple::Service
+  class Action
+  end
+end
+
+require_relative "./action/comment"
+require_relative "./action/parameter"
+require_relative "./action/indie_hash"
+
+module Simple::Service
+  # rubocop:disable Metrics/AbcSize
+  # rubocop:disable Metrics/PerceivedComplexity
+  # rubocop:disable Metrics/CyclomaticComplexity
+  # rubocop:disable Style/GuardClause
+  # rubocop:disable Metrics/ClassLength
+
+  class Action
+    IDENTIFIER_PATTERN = "[a-z][a-z0-9_]*" # :nodoc:
+    IDENTIFIER_REGEXP = Regexp.compile("\\A#{IDENTIFIER_PATTERN}\\z") # :nodoc:
+
+    # determines all services provided by the +service+ service module.
+    def self.enumerate(service:) # :nodoc:
+      service.public_instance_methods(false)
+             .grep(IDENTIFIER_REGEXP)
+             .each_with_object({}) { |name, hsh| hsh[name] = Action.new(service, name) }
+    end
+
+    attr_reader :service
+    attr_reader :name
+
+    def full_name
+      "#{service.name}##{name}"
+    end
+
+    def to_s # :nodoc:
+      full_name
+    end
+
+    # returns an Array of Parameter structures.
+    def parameters
+      @parameters ||= Parameter.reflect_on_method(service: service, name: name)
+    end
+
+    def initialize(service, name) # :nodoc:
+      @service  = service
+      @name     = name
+
+      parameters
+    end
+
+    def short_description
+      comment.short
+    end
+
+    def full_description
+      comment.full
+    end
+
+    private
+
+    # returns a Comment object
+    #
+    # The comment object is extracted on demand on the first call.
+    def comment
+      @comment ||= Comment.extract(action: self)
+    end
+
+    public
+
+    def source_location
+      @service.instance_method(name).source_location
+    end
+
+    # build a service_instance and run the action, with arguments constructed from
+    # args_hsh and params_hsh.
+    def invoke(*args, **named_args)
+      # convert Array arguments into a Hash of named arguments. This is strictly
+      # necessary to be able to apply default value-based type conversions. (On
+      # the downside this also means we convert an array to a hash and then back
+      # into an array. This, however, should only be an issue for CLI based action
+      # invocations, because any other use case (that I can think of) should allow
+      # us to provide arguments as a Hash.
+      args = convert_argument_array_to_hash(args)
+      named_args = named_args.merge(args)
+
+      invoke2(args: named_args, flags: {})
+    end
+
+    # invokes an action with a given +name+ in a service with a Hash of arguments.
+    #
+    # You cannot call this method if the context is not set.
+    def invoke2(args:, flags:)
+      # args and flags are being stringified. This is necessary to not allow any
+      # unchecked input to DOS this process by just providing always changing
+      # key values.
+      args = IndieHash.new(args)
+      flags = IndieHash.new(flags)
+
+      verify_required_args!(args, flags)
+
+      positionals = build_positional_arguments(args, flags)
+      keywords = build_keyword_arguments(args.merge(flags))
+
+      service_instance = Object.new
+      service_instance.extend service
+
+      if keywords.empty?
+        service_instance.public_send(@name, *positionals)
+      else
+        # calling this with an empty keywords Hash still raises an ArgumentError
+        # if the target method does not accept arguments.
+        service_instance.public_send(@name, *positionals, **keywords)
+      end
+    end
+
+    private
+
+    # returns an error if the keywords hash does not define all required keyword arguments.
+    def verify_required_args!(args, flags) # :nodoc:
+      @required_names ||= parameters.select(&:required?).map(&:name).map(&:to_s)
+
+      missing_parameters = @required_names - args.keys - flags.keys
+      return if missing_parameters.empty?
+
+      raise ::Simple::Service::MissingArguments.new(self, missing_parameters)
+    end
+
+    # Enumerating all parameters it puts all named parameters into a Hash
+    # of keyword arguments.
+    def build_keyword_arguments(args)
+      @keyword_names ||= parameters.select(&:keyword?).map(&:name).map(&:to_s)
+
+      keys = @keyword_names & args.keys
+      values = args.fetch_values(*keys)
+
+      # Note that +keys+ now only contains names of keyword arguments that actually exist.
+      # This is therefore not a way to DOS this process.
+      Hash[keys.map(&:to_sym).zip(values)]
+    end
+
+    def variadic_parameter
+      return @variadic_parameter if defined? @variadic_parameter
+
+      @variadic_parameter = parameters.detect(&:variadic?)
+    end
+
+    def positional_names
+      @positional_names ||= parameters.select(&:positional?).map(&:name)
+    end
+
+    # Enumerating all parameters it collects all positional parameters into
+    # an Array.
+    def build_positional_arguments(args, flags)
+      positionals = positional_names.each_with_object([]) do |parameter_name, ary|
+        if args.key?(parameter_name)
+          ary << args[parameter_name]
+        elsif flags.key?(parameter_name)
+          ary << flags[parameter_name]
+        end
+      end
+
+      # A variadic parameter is appended to the positionals array.
+      # It is always optional - but if it exists it must be an Array.
+      if variadic_parameter
+        value = if args.key?(variadic_parameter.name)
+                  args[variadic_parameter.name]
+                elsif flags.key?(variadic_parameter.name)
+                  flags[variadic_parameter.name]
+                end
+
+        positionals.concat(value) if value
+      end
+
+      positionals
+    end
+
+    def convert_argument_array_to_hash(ary)
+      expect! ary => Array
+
+      hsh = {}
+
+      if variadic_parameter
+        hsh[variadic_parameter.name] = []
+      end
+
+      if ary.length > positional_names.length
+        extra_arguments = ary[positional_names.length..-1]
+
+        if variadic_parameter
+          hsh[variadic_parameter.name] = extra_arguments
+        else
+          raise ::Simple::Service::ExtraArguments.new(self, extra_arguments)
+        end
+      end
+
+      ary.zip(positional_names).each do |value, parameter_name|
+        hsh[parameter_name] = value
+      end
+
+      hsh
+    end
+  end
+end

data/lib/simple/service/action/comment.rb

@@ -0,0 +1,57 @@
+# returns the comment for an action
+class ::Simple::Service::Action::Comment # :nodoc:
+  attr_reader :short
+  attr_reader :full
+
+  def self.extract(action:)
+    file, line = action.source_location
+    lines = Extractor.extract_comment_lines(file: file, before_line: line)
+    full = lines[2..-1].join("\n") if lines.length >= 2
+    new short: lines[0], full: full
+  end
+
+  def initialize(short:, full:)
+    @short, @full = short, full
+  end
+
+  module Extractor
+    extend self
+
+    # reads the source \a file and turns each non-comment into :code and each comment
+    # into a string without the leading comment markup.
+    def parse_source(file)
+      @parsed_sources ||= {}
+      @parsed_sources[file] = _parse_source(file)
+    end
+
+    def _parse_source(file)
+      File.readlines(file).map do |line|
+        case line
+        when /^\s*# ?(.*)$/ then $1
+        when /^\s*end/ then :end
+        end
+      end
+    end
+
+    def extract_comment_lines(file:, before_line:)
+      parsed_source = parse_source(file)
+
+      # go down from before_line until we see a line which is either a comment
+      # or an :end. Note that the line at before_line-1 should be the first
+      # line of the method definition in question.
+      last_line = before_line - 1
+      last_line -= 1 while last_line >= 0 && !parsed_source[last_line]
+
+      first_line = last_line
+      first_line -= 1 while first_line >= 0 && parsed_source[first_line]
+      first_line += 1
+
+      comments = parsed_source[first_line..last_line]
+      if comments.include?(:end)
+        []
+      else
+        parsed_source[first_line..last_line]
+      end
+    end
+  end
+end

data/lib/simple/service/action/indie_hash.rb

@@ -0,0 +1,37 @@
+class Simple::Service::Action
+  # The IndieHash class defines as much of the Hash interface as necessary for simple-service
+  # to successfully run.
+  class IndieHash
+    def initialize(hsh)
+      @hsh = hsh.each_with_object({}) { |(k, v), h| h[k.to_s] = v }
+    end
+
+    def keys
+      @hsh.keys
+    end
+
+    def fetch_values(*keys)
+      keys = keys.map(&:to_s)
+      @hsh.fetch_values(*keys)
+    end
+
+    def key?(sym)
+      @hsh.key?(sym.to_s)
+    end
+
+    def [](sym)
+      @hsh[sym.to_s]
+    end
+
+    def merge(other_hsh)
+      @hsh = @hsh.merge(other_hsh.send(:__hsh__))
+      self
+    end
+
+    private
+
+    def __hsh__
+      @hsh
+    end
+  end
+end

data/lib/simple/service/action/method_reflection.rb

@@ -0,0 +1,70 @@
+# rubocop:disable Metrics/AbcSize
+
+module ::Simple::Service::Action::MethodReflection # :nodoc:
+  extend self
+
+  #
+  # returns an array with entries like the following:
+  #
+  #  [ :key, name, default_value ]
+  #  [ :keyreq, name [, nil ] ]
+  #  [ :req, name [, nil ] ]
+  #  [ :opt, name [, nil ] ]
+  #  [ :rest, name [, nil ] ]
+  #
+  def parameters(service, method_id)
+    method = service.instance_method(method_id)
+    parameters = method.parameters
+
+    # method parameters with a :key mode are optional named arguments. We only
+    # support defaults for those - if there are none we abort here already.
+    keys = parameters.map { |mode, name| name if mode == :key }.compact
+    return parameters if keys.empty?
+
+    # We are now doing a fake call to the method, with a minimal viable set of
+    # arguments, to let the ruby runtime fill in default values for arguments.
+    # We do not, however, let the call complete. Instead we use a TracePoint to
+    # abort as soon as the method is called, and use the its binding to determine
+    # the default values.
+
+    fake_recipient = Object.new.extend(service)
+    fake_call_args = minimal_arguments(method)
+
+    trace_point = TracePoint.trace(:call) do |tp|
+      throw :received_fake_call, tp.binding if tp.defined_class == service && tp.method_id == method_id
+    end
+
+    bnd = catch(:received_fake_call) do
+      fake_recipient.send(method_id, *fake_call_args)
+    end
+
+    trace_point.disable
+
+    # extract default values from the received binding, and merge with the
+    # parameters array.
+    default_values = keys.each_with_object({}) do |key_parameter, hsh|
+      hsh[key_parameter] = bnd.local_variable_get(key_parameter)
+    end
+
+    parameters.map do |mode, name|
+      [mode, name, default_values[name]]
+    end
+  end
+
+  private
+
+  # returns a minimal Array of arguments, which is suitable for a call to the method
+  def minimal_arguments(method)
+    # Build an arguments array with holds all required parameters. The actual
+    # values for these arguments doesn't matter at all.
+    args = method.parameters.select { |mode, _name| mode == :req }
+
+    # Add a hash with all required named arguments
+    required_keyword_args = method.parameters.each_with_object({}) do |(mode, name), hsh|
+      hsh[name] = :anything if mode == :keyreq
+    end
+    args << required_keyword_args if required_keyword_args
+
+    args
+  end
+end

data/lib/simple/service/action/parameter.rb

@@ -0,0 +1,42 @@
+require_relative "method_reflection"
+
+class ::Simple::Service::Action::Parameter
+  def self.reflect_on_method(service:, name:)
+    reflected_parameters = ::Simple::Service::Action::MethodReflection.parameters(service, name)
+    @parameters = reflected_parameters.map { |ary| new(*ary) }
+  end
+
+  def keyword?
+    [:keyreq, :key].include? @kind
+  end
+
+  def positional?
+    [:req, :opt].include? @kind
+  end
+
+  def required?
+    [:req, :keyreq].include? @kind
+  end
+
+  def variadic?
+    @kind == :rest
+  end
+
+  attr_reader :name
+  attr_reader :kind
+
+  # The parameter's default value (if any)
+  attr_reader :default_value
+
+  def initialize(kind, name, *default_value)
+    # The parameter list matches the values returned from MethodReflection.parameters,
+    # which has two or three entries: <tt>kind, name [ . default_value ]</tt>
+
+    expect! kind => [:req, :opt, :keyreq, :key, :rest]
+    expect! default_value.length => [0, 1]
+
+    @kind = kind
+    @name = name
+    @default_value = default_value[0]
+  end
+end

data/lib/simple/service/context.rb

@@ -0,0 +1,94 @@
+module Simple::Service
+  # Returns the current context.
+  def self.context
+    Thread.current[:"Simple::Service.context"]
+  end
+
+  # yields a block with a given context, and restores the previous context
+  # object afterwards.
+  def self.with_context(ctx = nil, &block)
+    old_ctx = Thread.current[:"Simple::Service.context"]
+    new_ctx = old_ctx ? old_ctx.merge(ctx) : Context.new(ctx)
+
+    Thread.current[:"Simple::Service.context"] = new_ctx
+
+    block.call
+  ensure
+    Thread.current[:"Simple::Service.context"] = old_ctx
+  end
+end
+
+module Simple::Service
+  # A context object
+  #
+  # Each service executes with a current context. The system manages a stack of
+  # contexts; whenever a service execution is done the current context is reverted
+  # to its previous value.
+  #
+  # A context object can store a large number of values; the only way to set or
+  # access a value is via getters and setters. These are implemented via
+  # +method_missing(..)+.
+  #
+  # Also, once a value is set in the context it is not possible to change or
+  # unset it.
+  class Context
+    def initialize(hsh = {}) # :nodoc:
+      @hsh = hsh
+    end
+
+    # returns a new Context object, which merges the values in the +overlay+
+    # argument (which must be a Hash or nil) with the values in this context.
+    #
+    # The overlay is allowed to change values in the current context.
+    #
+    # It does not change this context.
+    def merge(overlay)
+      expect! overlay => [Hash, nil]
+
+      overlay ||= {}
+      new_context_hsh = @hsh.merge(overlay)
+      ::Simple::Service::Context.new(new_context_hsh)
+    end
+
+    private
+
+    IDENTIFIER_PATTERN = "[a-z][a-z0-9_]*" # :nodoc:
+    IDENTIFIER_REGEXP = Regexp.compile("\\A#{IDENTIFIER_PATTERN}\\z") # :nodoc:
+    ASSIGNMENT_REGEXP = Regexp.compile("\\A(#{IDENTIFIER_PATTERN})=\\z") # :nodoc:
+
+    def method_missing(sym, *args, &block)
+      raise ArgumentError, "Block given" if block
+
+      if args.count == 0 && sym =~ IDENTIFIER_REGEXP
+        self[sym]
+      elsif args.count == 1 && sym =~ ASSIGNMENT_REGEXP
+        self[$1.to_sym] = args.first
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(sym, include_private = false)
+      # :nocov:
+      return true if IDENTIFIER_REGEXP.match?(sym)
+      return true if ASSIGNMENT_REGEXP.match?(sym)
+
+      super
+      # :nocov:
+    end
+
+    def [](key)
+      @hsh[key]
+    end
+
+    def []=(key, value)
+      existing_value = @hsh[key]
+
+      unless existing_value.nil? || existing_value == value
+        raise ::Simple::Service::ContextReadOnlyError, key
+      end
+
+      @hsh[key] = value
+    end
+  end
+end