simple-service 0.1.5 → 0.2.1

data/lib/simple/service.rb

@@ -1,11 +1,14 @@
 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"
 
 # <b>The Simple::Service interface</b>
@@ -31,37 +34,43 @@ require_relative "service/version"
 #     end
 #
 # 2. <em>Discover services:</em> To discover services in a service module use the #actions method. This returns a Hash
-#    of actions. [TODO] why a Hash?
+#    of actions.
 #
 #     Simple::Service.actions(GodMode)
 #     => {:build_universe=>#<Simple::Service::Action...>, ...}
 #
-# 3. <em>Invoke a service:</em> run <tt>Simple::Service.invoke3</tt> or <tt>Simple::Service.invoke</tt>. You must set a context first.
+# TODO: why a Hash? It feels much better if Simple::Service.actions returns an array of names.
 #
-#     Simple::Service.with_context do
-#       Simple::Service.invoke3(GodMode, :build_universe, "TestWorld", c: 1e9)
-#     end
+#
+# 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
 #
 module Simple::Service
-  def self.included(klass) # @private
-    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.
-  #
-  # A service must be a module, and it must include the Simple::Service module.
-  def self.service?(service)
-    verify_service! service
-    true
-  rescue ::ArgumentError
-    false
+  def self.included(klass) # @private
+    klass.extend ClassMethods
+    klass.include ServiceExpectations
   end
 
-  # Raises an error if the passed in object is not a service
+  # Raises an error if the passed in object is not a Simple::Service
   def self.verify_service!(service) # @private
-    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.include?(self)
+    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
@@ -73,6 +82,8 @@ 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)
@@ -86,10 +97,8 @@ module Simple::Service
   #
   # As the main purpose of this module is to call services with outside data,
   # the +.invoke+ action is usually preferred.
-  #
-  # *Note:* You cannot call this method if the context is not set.
   def self.invoke3(service, name, *args, **flags)
-    flags = flags.each_with_object({}) { |(k, v), hsh| hsh[k.to_s] = v }
+    flags = flags.transform_keys(&:to_s)
     invoke service, name, args: args, flags: flags
   end
 
@@ -133,14 +142,10 @@ module Simple::Service
   # by the method we raise an ArgumentError.
   #
   # Entries in the +named_args+ Hash that are not defined in the action itself are ignored.
-
-  # <b>Note:</b> You cannot call this method if the context is not set.
   def self.invoke(service, name, args: {}, flags: {})
-    raise ContextMissingError, "Need to set context before calling ::Simple::Service.invoke3" unless context
-
     expect! args => [Hash, Array], flags: Hash
-    args.keys.each { |key| expect! key => String } if args.is_a?(Hash)
-    flags.keys.each { |key| expect! key => String }
+    args.each_key { |key| expect! key => String } if args.is_a?(Hash)
+    flags.each_key { |key| expect! key => String }
 
     action(service, name).invoke(args: args, flags: flags)
   end

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

data/lib/simple/workflow.rb

@@ -0,0 +1,96 @@
+require "simple/service"
+
+require_relative "workflow/context"
+require_relative "workflow/current_context"
+require_relative "workflow/reloader"
+
+if defined?(RSpec)
+  require_relative "workflow/rspec_helper"
+end
+
+module Simple::Workflow
+  class ContextMissingError < ::StandardError
+    def to_s
+      "Simple::Workflow.current_context not initialized; remember to call Simple::Workflow.with_context/1"
+    end
+  end
+
+  module HelperMethods
+    def invoke(*args, **kwargs)
+      Simple::Workflow.invoke(self, *args, **kwargs)
+    end
+  end
+
+  module InstanceHelperMethods
+    private
+
+    def current_context
+      Simple::Workflow.current_context
+    end
+  end
+
+  module ModuleMethods
+    def register_workflow(mod)
+      expect! mod => Module
+
+      mod.extend ::Simple::Workflow::HelperMethods
+      mod.include ::Simple::Workflow::InstanceHelperMethods
+      mod.extend mod
+      mod.include Simple::Service
+    end
+
+    def reload_on_invocation?
+      !!@reload_on_invocation
+    end
+
+    def reload_on_invocation!
+      @reload_on_invocation = true
+    end
+
+    def invoke(workflow, *args, **kwargs)
+      # This call to Simple::Workflow.current_context raises a ContextMissingError
+      # if the context is not set.
+      _ = ::Simple::Workflow.current_context
+
+      expect! workflow => [Module, String]
+
+      workflow_module = lookup_workflow!(workflow)
+
+      # We will reload workflow modules only once per invocation.
+      if Simple::Workflow.reload_on_invocation?
+        Simple::Workflow.current_context.reload!(workflow_module)
+      end
+
+      Simple::Service.invoke(workflow_module, :call, args: args, flags: kwargs.transform_keys(&:to_s))
+    end
+
+    private
+
+    def lookup_workflow!(workflow)
+      workflow_module = lookup_workflow(workflow)
+
+      verify_workflow! workflow_module
+
+      workflow_module
+    end
+
+    def lookup_workflow(workflow)
+      case workflow
+      when Module
+        workflow
+      when String
+        Object.const_get workflow
+      else
+        expect! workflow => [Module, String]
+      end
+    end
+
+    def verify_workflow!(workflow_module)
+      return if Simple::Service.actions(workflow_module).key?(:call)
+
+      raise ArgumentError, "#{workflow_module.name} is not a Simple::Workflow"
+    end
+  end
+
+  extend ModuleMethods
+end

data/lib/simple-workflow.rb

@@ -0,0 +1,3 @@
+# rubocop:disable Naming/FileName
+
+require "simple/workflow"

data/scripts/test

@@ -0,0 +1,2 @@
+#!/bin/bash
+rspec "$@"

data/simple-service.gemspec

@@ -22,4 +22,5 @@ Gem::Specification.new do |gem|
   gem.required_ruby_version = '~> 2.5'
 
   gem.add_dependency "expectation", "~> 1"
+  gem.add_dependency "simple-immutable", "~> 1", ">= 1.1"
 end

data/spec/simple/service/action_invoke3_spec.rb

@@ -3,14 +3,6 @@
 require "spec_helper"
 
 describe "Simple::Service.invoke3" do
-  # the context to use in the around hook below. By default this is nil -
-  # which gives us an empty context.
-  let(:context) { nil }
-
-  around do |example|
-    ::Simple::Service.with_context(context) { example.run }
-  end
-
   let(:service) { InvokeTestService }
   let(:action)  { nil }
 

data/spec/simple/service/action_invoke_spec.rb

@@ -1,21 +1,12 @@
 # rubocop:disable Style/WordArray
-
 require "spec_helper"
 
 describe "Simple::Service.invoke" do
-  # the context to use in the around hook below. By default this is nil -
-  # which gives us an empty context.
-  let(:context) { nil }
-
-  around do |example|
-    ::Simple::Service.with_context(context) { example.run }
-  end
-
   let(:service) { InvokeTestService }
   let(:action)  { nil }
 
   # a shortcut
-  def invoke!(args = {}, flags: {})
+  def invoke!(args: {}, flags: {})
     @actual = ::Simple::Service.invoke(service, action, args: args, flags: flags)
     # rescue ::StandardError => e
   rescue ::Simple::Service::ArgumentError => e
@@ -42,7 +33,14 @@ describe "Simple::Service.invoke" do
 
     context "calling with extra named args" do
       it "ignores extra args" do
-        invoke!("foo" => "foo", "bar" => "bar")
+        invoke!(args: { "foo" => "foo", "bar" => "bar" })
+        expect(actual).to eq("service2 return")
+      end
+    end
+
+    context "calling with extra flags" do
+      it "ignores extra args" do
+        invoke!(flags: { "foo" => "foo", "bar" => "bar" })
         expect(actual).to eq("service2 return")
       end
     end
@@ -67,21 +65,28 @@ describe "Simple::Service.invoke" do
 
     context "with the required number of args" do
       it "runs" do
-        invoke!("a" => "foo", "b" => "bar")
+        invoke!(args: { "a" => "foo", "b" => "bar" })
+        expect(actual).to eq(["foo", "bar", "speed-of-light", 2.781])
+      end
+    end
+
+    context "with the required number of args and flags" do
+      it "merges flags and args to provide arguments" do
+        invoke!(args: { "a" => "foo" }, flags: { "b" => "bar" })
         expect(actual).to eq(["foo", "bar", "speed-of-light", 2.781])
       end
     end
 
     context "with the allowed number of args" do
       it "runs" do
-        invoke!("a" => "foo", "b" => "bar", "c" => "baz", "e" => "number4")
+        invoke!(args: { "a" => "foo", "b" => "bar", "c" => "baz", "e" => "number4" })
         expect(actual).to eq(%w[foo bar baz number4])
       end
     end
 
     context "calling with extra named args" do
       it "ignores extra args" do
-        invoke!("a" => "foo", "b" => "bar", "c" => "baz", "e" => "number4", "extra3" => 3)
+        invoke!(args: { "a" => "foo", "b" => "bar", "c" => "baz", "e" => "number4", "extra3" => 3 })
         expect(actual).to eq(%w[foo bar baz number4])
       end
     end
@@ -106,21 +111,21 @@ describe "Simple::Service.invoke" do
 
     context "with the required number of args" do
       it "runs" do
-        invoke!("a" => "foo", "b" => "bar")
+        invoke!(args: { "a" => "foo", "b" => "bar" })
         expect(actual).to eq(["foo", "bar", "speed-of-light", 2.781])
       end
     end
 
     context "with the allowed number of args" do
       it "runs" do
-        invoke!("a" => "foo", "b" => "bar", "c" => "baz", "e" => "number4")
+        invoke!(args: { "a" => "foo", "b" => "bar", "c" => "baz", "e" => "number4" })
         expect(actual).to eq(%w[foo bar baz number4])
       end
     end
 
     context "with extra named args" do
       it "ignores extra args" do
-        invoke!("a" => "foo", "b" => "bar", "c" => "baz", "extra3" => 3)
+        invoke!(args: { "a" => "foo", "b" => "bar", "c" => "baz", "extra3" => 3 })
         expect(actual).to eq(["foo", "bar", "baz", 2.781])
       end
     end
@@ -144,23 +149,80 @@ describe "Simple::Service.invoke" do
 
     context "with the required number of args" do
       it "runs" do
-        invoke!("a" => "foo")
+        invoke!(args: { "a" => "foo" })
         expect(actual).to eq(["foo", "default-b", "speed-of-light", 2.781])
       end
     end
 
     context "with the allowed number of args" do
       it "runs" do
-        invoke!("a" => "foo", "b" => "bar", "c" => "baz", "e" => "number4")
+        invoke!(args: { "a" => "foo", "b" => "bar", "c" => "baz", "e" => "number4" })
         expect(actual).to eq(%w[foo bar baz number4])
       end
     end
 
     context "with extra named args" do
       it "ignores extra args" do
-        invoke!("a" => "foo", "b" => "bar", "c" => "baz", "e" => "number4", "extra3" => 3)
+        invoke!(args: { "a" => "foo", "b" => "bar", "c" => "baz", "e" => "number4", "extra3" => 3 })
         expect(actual).to eq(["foo", "bar", "baz", "number4"])
       end
     end
   end
+
+  context "calling an action w/mixed and variadic parameters" do
+    # reminder: this is the definition of variadic_params
+    #
+    # def variadic_params(a, b = "queen bee", *args, e: 2.781)
+    #   [a, b, args, e]
+    # end
+
+    let(:action) { :variadic_params }
+
+    context "without args" do
+      it "raises MissingArguments" do
+        invoke!
+        expect(actual).to be_a(::Simple::Service::MissingArguments)
+      end
+    end
+
+    context "with the required number of args" do
+      it "runs" do
+        invoke!(args: { "a" => "foo" })
+        expect(actual).to eq(["foo", "queen bee", [], 2.781])
+      end
+    end
+
+    context "with the allowed number of args" do
+      it "runs" do
+        invoke!(args: { "a" => "foo", "b" => "bar", "args" => ["baz"] }, flags: { "e" => "number4" })
+        expect(actual).to eq(["foo", "bar", ["baz"], "number4"])
+      end
+    end
+
+    context "with variadic args" do
+      it "sends the variadic args from the args: parameter" do
+        invoke!(args: { "a" => "foo", "b" => "bar", "args" => ["baz", "extra"] }, flags: { "e" => "number4", "extra3" => 2 })
+        expect(actual).to eq(["foo", "bar", ["baz", "extra"], "number4"])
+      end
+
+      it "sends the variadic args from the flags: parameter" do
+        invoke!(args: { "a" => "foo", "b" => "bar" }, flags: { "args" => ["baz", "extra"], "e" => "number4", "extra3" => 2 })
+        expect(actual).to eq(["foo", "bar", ["baz", "extra"], "number4"])
+      end
+    end
+  end
+
+  describe "calling with symbolized Hashes" do
+    it "raises ArgumentError" do
+      hsh = { a: "foo", "b" => "KJH" }
+
+      expect do
+        invoke!(args: hsh)
+      end.to raise_error(Expectation::Matcher::Mismatch)
+
+      expect do
+        invoke!(flags: hsh)
+      end.to raise_error(Expectation::Matcher::Mismatch)
+    end
+  end
 end