simple-service 0.1.3 → 0.2.0

data/lib/simple/service/action.rb

@@ -1,25 +1,24 @@
 module Simple::Service
+  # rubocop:disable Lint/EmptyClass
   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:
+    IDENTIFIER_PATTERN = "[a-z][a-z0-9_]*" # @private
+    IDENTIFIER_REGEXP = Regexp.compile("\\A#{IDENTIFIER_PATTERN}\\z") # @private
 
     # determines all services provided by the +service+ service module.
-    def self.enumerate(service:) # :nodoc:
+    def self.enumerate(service:) # @private
       service.public_instance_methods(false)
              .grep(IDENTIFIER_REGEXP)
              .each_with_object({}) { |name, hsh| hsh[name] = Action.new(service, name) }
@@ -32,7 +31,7 @@ module Simple::Service
       "#{service.name}##{name}"
     end
 
-    def to_s # :nodoc:
+    def to_s # @private
       full_name
     end
 
@@ -41,7 +40,7 @@ module Simple::Service
       @parameters ||= Parameter.reflect_on_method(service: service, name: name)
     end
 
-    def initialize(service, name) # :nodoc:
+    def initialize(service, name) # @private
       @service  = service
       @name     = name
 
@@ -71,30 +70,11 @@ module Simple::Service
       @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)
+    def invoke(args:, flags:)
+      args = convert_argument_array_to_hash(args) if args.is_a?(Array)
 
       verify_required_args!(args, flags)
 
@@ -116,7 +96,7 @@ module Simple::Service
     private
 
     # returns an error if the keywords hash does not define all required keyword arguments.
-    def verify_required_args!(args, flags) # :nodoc:
+    def verify_required_args!(args, flags) # @private
       @required_names ||= parameters.select(&:required?).map(&:name).map(&:to_s)
 
       missing_parameters = @required_names - args.keys - flags.keys
@@ -135,7 +115,7 @@ module Simple::Service
 
       # 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)]
+      keys.map(&:to_sym).zip(values).to_h
     end
 
     def variadic_parameter
@@ -145,7 +125,7 @@ module Simple::Service
     end
 
     def positional_names
-      @positional_names ||= parameters.select(&:positional?).map(&:name)
+      @positional_names ||= parameters.select(&:positional?).map(&:name).map(&:to_s)
     end
 
     # Enumerating all parameters it collects all positional parameters into
@@ -177,26 +157,34 @@ module Simple::Service
     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
+      # +ary* might contain more, less, or the exact number of positional
+      # arguments. If the number is less, we return a hash with only whart
+      # exists in ary - the action might define default values after all.
+      #
+      # If it contains more the action better supports a variadic parameter;
+      # we otherwise raise a ExtraArguments exception.
+      case ary.length <=> positional_names.length
+      when 1  # i.e. ary.length > positional_names.length
+        extra_arguments = ary[positional_names.length..]
+        ary = ary[0..positional_names.length]
+
+        if !extra_arguments.empty? && !variadic_parameter
           raise ::Simple::Service::ExtraArguments.new(self, extra_arguments)
         end
-      end
 
-      ary.zip(positional_names).each do |value, parameter_name|
-        hsh[parameter_name] = value
+        existing_positional_names = positional_names
+      when 0  # i.e. ary.length == positional_names.length
+        existing_positional_names = positional_names
+      when -1 # i.e. ary.length < positional_names.length
+        existing_positional_names = positional_names[0, ary.length]
       end
 
+      # Build a hash with the existing_positional_names and the values from the array.
+      hsh = existing_positional_names.zip(ary).to_h
+
+      # Add the variadic_parameter, if any.
+      hsh[variadic_parameter.name] = extra_arguments if variadic_parameter
+
       hsh
     end
   end

data/lib/simple/service/errors.rb

@@ -2,8 +2,10 @@ module Simple::Service
   # Will be raised by ::Simple::Service.action.
   class NoSuchAction < ::ArgumentError
     attr_reader :service, :name
+
     def initialize(service, name)
       @service, @name = service, name
+      super()
     end
 
     def to_s
@@ -22,6 +24,7 @@ module Simple::Service
 
     def initialize(action, parameters)
       @action, @parameters = action, parameters
+      super()
     end
 
     def to_s
@@ -35,6 +38,7 @@ module Simple::Service
 
     def initialize(action, arguments)
       @action, @arguments = action, arguments
+      super()
     end
 
     def to_s
@@ -43,9 +47,6 @@ module Simple::Service
     end
   end
 
-  class ContextMissingError < ::StandardError
-  end
-
   class ContextReadOnlyError < ::StandardError
     def initialize(key)
       super "Cannot overwrite existing context setting #{key.inspect}"

data/lib/simple/service/version.rb

@@ -1,8 +1,8 @@
-module Simple # :nodoc:
+module Simple # @private
 end
 
 module Simple::Service
-  module GemHelper # :nodoc:
+  module GemHelper # @private
     extend self
 
     def version(name)

data/lib/simple/service.rb

@@ -1,33 +1,76 @@
-module Simple # :nodoc:
+module Simple # @private
+end
+
+module Simple::Service # @private
 end
 
 require "expectation"
+require "logger"
 
 require_relative "service/errors"
 require_relative "service/action"
-require_relative "service/context"
 require_relative "service/version"
 
-# The Simple::Service module.
+# <b>The Simple::Service interface</b>
+#
+# This module implements the main API of the Simple::Service ruby gem.
+#
+# 1. <em>Marking a service module:</em> To turn a target module as a service module one must include <tt>Simple::Service</tt>
+#    into the target. This serves as a marker that this module is actually intended
+#    to provide one or more services. Example:
+#
+#     module GodMode
+#       include Simple::Service
+#
+#       # Build a universe.
+#       #
+#       # This comment will become part of the full description of the
+#       # "build_universe" service
+#       def build_universe(name, c: , pi: 3.14, e: 2.781)
+#         # at this point I realize that *I* am not God.
+#
+#         42 # Best try approach
+#       end
+#     end
+#
+# 2. <em>Discover services:</em> To discover services in a service module use the #actions method. This returns a Hash
+#    of actions.
+#
+#     Simple::Service.actions(GodMode)
+#     => {:build_universe=>#<Simple::Service::Action...>, ...}
 #
-# To mark a target module as a service module one must include the
-# Simple::Service module into the target module.
+# TODO: why a Hash? It feels much better if Simple::Service.actions returns an array of names.
+#
+#
+# 3. <em>Invoke a service:</em> run <tt>Simple::Service.invoke3</tt> or <tt>Simple::Service.invoke</tt>.
+#
+#     Simple::Service.invoke3(GodMode, :build_universe, "TestWorld", c: 1e9)
+#     => 42
 #
-# This serves as a marker that this module is actually intended
-# to be used as a service.
 module Simple::Service
-  def self.included(klass) # :nodoc:
-    klass.extend ClassMethods
+  module ServiceExpectations
+    def expect!(*args, &block)
+      Expectation.expect!(*args, &block)
+    rescue ::Expectation::Error => e
+      raise ArgumentError, e.to_s
+    end
   end
 
-  # returns true if the passed in object is a service module.
-  def self.service?(service)
-    service.is_a?(Module) && service.include?(self)
+  def self.included(klass) # @private
+    klass.extend ClassMethods
+    klass.include ServiceExpectations
   end
 
-  def self.verify_service!(service) # :nodoc:
-    raise ::ArgumentError, "#{service.inspect} must be a Simple::Service, but is not even a Module" unless service.is_a?(Module)
-    raise ::ArgumentError, "#{service.inspect} must be a Simple::Service, did you 'include Simple::Service'" unless service?(service)
+  # Raises an error if the passed in object is not a Simple::Service
+  def self.verify_service!(service) # @private
+    expect! service => Module
+
+    # rubocop:disable Style/GuardClause
+    unless service.include?(::Simple::Service)
+      raise ::ArgumentError,
+            "#{service.name} is not a Simple::Service, did you 'include Simple::Service'"
+    end
+    # rubocop:enable Style/GuardClause
   end
 
   # returns a Hash with all actions in the +service+ module
@@ -39,19 +82,58 @@ module Simple::Service
 
   # returns the action with the given name.
   def self.action(service, name)
+    expect! name => Symbol
+
     actions = self.actions(service)
     actions[name] || begin
       raise ::Simple::Service::NoSuchAction.new(service, name)
     end
   end
 
-  # invokes an action with a given +name+ in a service with +arguments+ and +params+.
+  # invokes an action with a given +name+ in a service with +args+ and +flags+.
+  #
+  # This is a helper method which one can use to easily call an action from
+  # ruby source code.
+  #
+  # As the main purpose of this module is to call services with outside data,
+  # the +.invoke+ action is usually preferred.
+  def self.invoke3(service, name, *args, **flags)
+    flags = flags.transform_keys(&:to_s)
+    invoke service, name, args: args, flags: flags
+  end
+
+  # invokes an action with a given +name+.
+  #
+  # This is the general form of invoking a service. It accepts the following
+  # arguments:
+  #
+  # - args: an Array of positional arguments OR a Hash of named arguments.
+  # - flags: a Hash of flags.
+  #
+  # Note that the keys in both the +flags+ and the +args+ Hash must be strings.
+  #
+  # The service is being called with a parameters built out of those like this:
   #
-  # You cannot call this method if the context is not set.
+  # - The service's positional arguments are being built from the +args+ array
+  #   parameter or from the +named_args+ hash parameter.
+  # - The service's keyword arguments are being built from the +named_args+
+  #   and +flags+ arguments.
   #
-  # When calling #invoke using positional arguments they will be matched against
-  # positional arguments of the invoked method - but they will not be matched
-  # against named arguments.
+  # In other words:
+  #
+  # 1. You cannot set both +args+ and +named_args+ at the same time.
+  # 2. The +flags+ arguments are only being used to determine the
+  #    service's keyword parameters.
+  #
+  # So, if the service X implements an action "def foo(bar, baz:)", the following would
+  # all invoke that service:
+  #
+  # - +Service.invoke3(X, :foo, "bar-value", baz: "baz-value")+, or
+  # - +Service.invoke3(X, :foo, bar: "bar-value", baz: "baz-value")+, or
+  # - +Service.invoke(X, :foo, args: ["bar-value"], flags: { "baz" => "baz-value" })+, or
+  # - +Service.invoke(X, :foo, args: { "bar" => "bar-value", "baz" => "baz-value" })+.
+  #
+  # (see spec/service_spec.rb)
   #
   # When there are not enough positional arguments to match the number of required
   # positional arguments of the method we raise an ArgumentError.
@@ -59,23 +141,16 @@ module Simple::Service
   # When there are more positional arguments provided than the number accepted
   # by the method we raise an ArgumentError.
   #
-  # Entries in the named_args Hash that are not defined in the action itself are ignored.
-  def self.invoke(service, name, *args, **named_args)
-    raise ContextMissingError, "Need to set context before calling ::Simple::Service.invoke" unless context
-
-    action(service, name).invoke(*args, **named_args)
-  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 self.invoke2(service, name, args: {}, flags: {})
-    raise ContextMissingError, "Need to set context before calling ::Simple::Service.invoke" unless context
+  # Entries in the +named_args+ Hash that are not defined in the action itself are ignored.
+  def self.invoke(service, name, args: {}, flags: {})
+    expect! args => [Hash, Array], flags: Hash
+    args.each_key { |key| expect! key => String } if args.is_a?(Hash)
+    flags.each_key { |key| expect! key => String }
 
-    action(service, name).invoke2(args: args, flags: flags)
+    action(service, name).invoke(args: args, flags: flags)
   end
 
-  module ClassMethods # :nodoc:
+  module ClassMethods # @private
     # returns a Hash of actions provided by the service module.
     def __simple_service_actions__
       @__simple_service_actions__ ||= Action.enumerate(service: self)

data/lib/simple/workflow/context.rb

@@ -0,0 +1,105 @@
+require "simple/immutable"
+
+module Simple::Workflow
+  # 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 < Simple::Immutable
+    SELF = self
+
+    # returns a new Context object.
+    #
+    # Parameters:
+    #
+    # - hsh (Hash or nil): sets values for this context
+    # - previous_context (Context or nil): if +previous_context+ is provided,
+    #   values that are not defined in the \a +hsh+ argument are read from the
+    #   +previous_context+ instead (or the previous context's +previous_context+,
+    #   etc.)
+    def initialize(hsh, previous_context = nil)
+      expect! hsh => [Hash, nil]
+      expect! previous_context => [SELF, nil]
+
+      @previous_context = previous_context
+      super(hsh || {})
+    end
+
+    def reload!(a_module)
+      if @previous_context
+        @previous_context.reload!(a_module)
+        return a_module
+      end
+
+      @reloaded_modules ||= []
+      return if @reloaded_modules.include?(a_module)
+
+      ::Simple::Workflow::Reloader.reload(a_module)
+      @reloaded_modules << a_module
+      a_module
+    end
+
+    def fetch_attribute!(sym, raise_when_missing:)
+      unless @previous_context
+        return super(sym, raise_when_missing: raise_when_missing)
+      end
+
+      first_error = nil
+
+      # check this context first. We catch any NameError, to be able to look up
+      # the attribute also in the previous_context.
+      begin
+        return super(sym, raise_when_missing: true)
+      rescue NameError => e
+        first_error = e
+      end
+
+      # check previous_context
+      begin
+        return @previous_context.fetch_attribute!(sym, raise_when_missing: raise_when_missing)
+      rescue NameError
+        :nop
+      end
+
+      # Not in +self+, not in +previous_context+, and +raise_when_missing+ is true:
+      raise(first_error)
+    end
+
+    # def inspect
+    #   if @previous_context
+    #     "#{object_id} [" + @hsh.keys.map(&:inspect).join(", ") + "; #{@previous_context.inspect}]"
+    #   else
+    #     "#{object_id} [" + @hsh.keys.map(&:inspect).join(", ") + "]"
+    #   end
+    # end
+
+    private
+
+    IDENTIFIER = "[a-z_][a-z0-9_]*" # @private
+
+    def method_missing(sym, *args, &block)
+      raise ArgumentError, "#{self.class.name}##{sym}: Block given" if block
+      raise ArgumentError, "#{self.class.name}##{sym}: Extra args #{args.inspect}" unless args.empty?
+
+      if sym !~ /\A(#{IDENTIFIER})(\?)?\z/
+        raise ArgumentError, "#{self.class.name}: Invalid context key '#{sym}'"
+      end
+
+      # rubocop:disable Lint/OutOfRangeRegexpRef
+      fetch_attribute!($1, raise_when_missing: $2.nil?)
+      # rubocop:enable Lint/OutOfRangeRegexpRef
+    end
+
+    def respond_to_missing?(sym, include_private = false)
+      super || @previous_context&.respond_to_missing?(sym, include_private)
+    end
+  end
+end

data/lib/simple/workflow/current_context.rb

@@ -0,0 +1,33 @@
+module Simple::Workflow
+  module CurrentContext
+    # Returns the current context.
+    #
+    # This method never returns nil - it raises a ContextMissingError exception if
+    # the context was not initialized (via <tt>Simple::Workflow.with_context</tt>).
+    def current_context
+      Thread.current[:"Simple::Workflow.current_context"] || raise(ContextMissingError)
+    end
+
+    # Returns a logger
+    #
+    # Returns a logger if a context is set and contains a logger.
+    def logger
+      current_context = Thread.current[:"Simple::Workflow.current_context"]
+      current_context&.logger?
+    end
+
+    # yields a block with a given context, and restores the previous context
+    # object afterwards.
+    def with_context(ctx = nil, &block)
+      old_ctx = Thread.current[:"Simple::Workflow.current_context"]
+
+      Thread.current[:"Simple::Workflow.current_context"] = Context.new(ctx, old_ctx)
+
+      block.call
+    ensure
+      Thread.current[:"Simple::Workflow.current_context"] = old_ctx
+    end
+  end
+
+  extend CurrentContext
+end

data/lib/simple/workflow/reloader.rb

@@ -0,0 +1,84 @@
+# The Simple::Workflow::Reloader provides a way to locate and reload a module
+module Simple::Workflow::Reloader
+  extend self
+
+  def reload(a_module)
+    source_paths = locate(a_module)
+    if source_paths.empty?
+      logger&.warn "#{a_module}: cannot reload module: cannot find sources"
+      return
+    end
+
+    source_paths.each do |source_path|
+      logger&.debug "#{a_module}: reload #{source_path}"
+    end
+
+    logger&.info "#{a_module}: reloaded module"
+  end
+
+  # This method tries to identify source files for a module's functions.
+  def locate(a_module)
+    expect! a_module => Module
+
+    @registered_source_paths ||= {}
+    @registered_source_paths[a_module.name] ||= locate_source_paths(a_module)
+  end
+
+  private
+
+  def logger
+    ::Simple::Workflow.logger
+  end
+
+  def locate_source_paths(a_module)
+    source_paths = []
+
+    source_paths.concat locate_by_instance_methods(a_module)
+    source_paths.concat locate_by_methods(a_module)
+    source_paths.concat locate_by_name(a_module)
+
+    source_paths.uniq
+  end
+
+  def locate_by_instance_methods(a_module)
+    method_names = a_module.instance_methods(false)
+    methods = method_names.map { |sym| a_module.instance_method(sym) }
+    methods.map(&:source_location).map(&:first)
+  end
+
+  def locate_by_methods(a_module)
+    method_names = a_module.methods(false)
+    methods = method_names.map { |sym| a_module.method(sym) }
+    methods.map(&:source_location).map(&:first)
+  end
+
+  def locate_by_name(a_module)
+    source_file = "#{underscore(a_module.name)}.rb"
+
+    $LOAD_PATH.each do |dir|
+      full_path = File.join(dir, source_file)
+      return [full_path] if File.exist?(full_path)
+    end
+
+    []
+  end
+
+  # Makes an underscored, lowercase form from the expression in the string.
+  #
+  # Changes '::' to '/' to convert namespaces to paths.
+  #
+  # This is copied and slightly changed (we don't support any custom
+  # inflections) from activesupport's  lib/active_support/inflector/methods.rb
+  #
+  def underscore(camel_cased_word)
+    return camel_cased_word unless /[A-Z-]|::/.match?(camel_cased_word)
+
+    word = camel_cased_word.to_s.gsub("::", "/")
+
+    word.gsub!(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
+    word.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
+    word.tr!("-", "_")
+    word.downcase!
+    word
+  end
+end

data/lib/simple/workflow/rspec_helper.rb

@@ -0,0 +1,15 @@
+module ::Simple::Workflow::RSpecHelper
+  def self.included(base)
+    base.let(:current_context) { {} }
+
+    base.around do |example|
+      if (ctx = current_context)
+        ::Simple::Workflow.with_context(ctx) do
+          example.run
+        end
+      else
+        example.run
+      end
+    end
+  end
+end