flows 0.2.0 → 0.6.0

data/lib/flows/plugin/output_contract.rb

@@ -0,0 +1,85 @@
+require_relative 'output_contract/errors'
+require_relative 'output_contract/dsl'
+require_relative 'output_contract/wrapper'
+
+module Flows
+  module Plugin
+    # Allows to make a contract check and transformation for `#call` method execution in any class.
+    #
+    # Plugin applies a wrapper to a `#call` instance method.
+    # This wrapper will do the following:
+    #
+    # * check that {Result} instance is returned by `#call`
+    # * check that returned {Result#status} is expected
+    # * check that returned result data conforms {Contract} assigned
+    #   to a particular result type and status
+    # * applies contract transform to the returned data
+    # * returns {Result} with the same status and type,
+    #   wraps transformed data inside.
+    #
+    # Plugin provides DSL to express expected result statuses and assigned contracts.
+    # Contracts definition reuses {Contract.make} to execute block and get a contract.
+    #
+    # * `success_with(status, &block)` - defines contract for a successful result with status `status`.
+    # * `failure_with(status, &block)` - defines contract for a failure result with status `status`.
+    # * `skip_output_contract` - disables contract check and transformation for current class and children.
+    #
+    # @example with one possible output contract
+    #     class DoJob
+    #       include Flows::Result::Helpers
+    #       include Flows::Plugin::OutputContract
+    #
+    #       success_with :ok do
+    #         Integer
+    #       end
+    #
+    #       def call(a, b)
+    #         ok_data(a + b)
+    #       end
+    #     end
+    #
+    #     DoJob.new.call(1, 2).unwrap
+    #     # => 3
+    #
+    #     DoJob.new.call('a', 'b')
+    #     # Flows::Contract::Error exception raised
+    #
+    # @example with multiple contracts
+    #     class DoJob
+    #       include Flows::Result::Helpers
+    #       include Flows::Plugin::OutputContract
+    #
+    #       success_with :int_sum do
+    #         Integer
+    #       end
+    #
+    #       success_with :float_sum do
+    #         Float
+    #       end
+    #
+    #       failure_with :err do
+    #         hash_of(
+    #           key: Symbol,
+    #           msg: String
+    #         )
+    #       end
+    #
+    #       def call(a, b)
+    #         if a.is_a?(Float) || b.is_a?(Float)
+    #           ok_data(a + b, status: :float_sum)
+    #         elsif a.is_a?(Integer) && b.is_a?(Integer)
+    #           ok_data(a + b, status: :int_sum)
+    #         else
+    #           err(key: :unexpected_type, msg: "Unexpected argument types")
+    #         end
+    #       end
+    #     end
+    module OutputContract
+      # @api private
+      def self.included(mod)
+        mod.extend(DSL)
+        mod.prepend(Wrapper)
+      end
+    end
+  end
+end

data/lib/flows/plugin/output_contract/dsl.rb

@@ -0,0 +1,48 @@
+module Flows
+  module Plugin
+    module OutputContract
+      # DSL for OutputContract plugin.
+      module DSL
+        # Hash of contracts for successful results.
+        attr_reader :success_contracts
+
+        # Hash of contracts for failure results.
+        attr_reader :failure_contracts
+
+        # Is contract check and transformation disabled
+        attr_reader :skip_output_contract_flag
+
+        SingletonVarsSetup = Flows::Util::InheritableSingletonVars::DupStrategy.make_module(
+          '@success_contracts' => {},
+          '@failure_contracts' => {},
+          '@skip_output_contract_flag' => false
+        )
+
+        include SingletonVarsSetup
+
+        # Defines a contract for a successful result with specific status.
+        #
+        # @param status [Symbol] Corresponding result status.
+        # @param contract_block [Proc] This block will be passed to {Contract.make} to get a contract.
+        def success_with(status, &contract_block)
+          success_contracts[status] = Flows::Contract.make(&contract_block)
+        end
+
+        # Defines a contract for a failure result with specific status.
+        #
+        # @param status [Symbol] Corresponding result status.
+        # @param contract_block [Proc] This block will be passed to {Contract.make} to get a contract.
+        def failure_with(status, &contract_block)
+          failure_contracts[status] = Flows::Contract.make(&contract_block)
+        end
+
+        # Disables contract check and transformation for current class and children.
+        #
+        # @param enable [Boolean] if true - contracts are disabled
+        def skip_output_contract(enable: true)
+          @skip_output_contract_flag = enable
+        end
+      end
+    end
+  end
+end

data/lib/flows/plugin/output_contract/errors.rb

@@ -0,0 +1,74 @@
+module Flows
+  module Plugin
+    module OutputContract
+      # Base error class for output contract errors.
+      class Error < StandardError; end
+
+      # Raised when no single contract for successful results is defined
+      class NoContractError < Error
+        def initialize(klass)
+          @klass = klass
+        end
+
+        def message
+          "No single success contract defined for #{@klass}"
+        end
+      end
+
+      # Raised when result's data violates contract
+      class ContractError < Error
+        def initialize(klass, result, error)
+          @klass = klass
+          @result = result
+          @error = error
+        end
+
+        def message
+          shifted_error = @error.split("\n").map { |str| "  #{str}" }.join("\n")
+
+          "Output contract for #{@klass} is violated.\n" \
+          "Result:\n" \
+          "  `#{@result.inspect}`\n" \
+          "Contract Error:\n" \
+          "#{shifted_error}"
+        end
+      end
+
+      # Raised when no contract found for result
+      class StatusError < Error
+        def initialize(klass, result, allowed_statuses)
+          @klass = klass
+          @result = result
+          @allowed_statuses = allowed_statuses
+        end
+
+        def message
+          allowed_statuses_str = @allowed_statuses.map { |st| "`#{st.inspect}`" }.join(', ')
+
+          "Output contract for #{@klass} is violated.\n" \
+          "Result:\n" \
+          "  `#{@result.inspect}`\n" \
+          "Contract Error:\n" \
+          "  has unexpected status `#{@result.status.inspect}`\n" \
+          "  allowed statuses for `#{@result.class}` are: #{allowed_statuses_str}"
+        end
+      end
+
+      # Raised when not a result object returned
+      class ResultTypeError < Error
+        def initialize(klass, result)
+          @klass = klass
+          @result = result
+        end
+
+        def message
+          "Output contract for #{@klass} is violated.\n" \
+          "Result:\n" \
+          "  `#{@result.inspect}`\n" \
+          "Contract Error:\n" \
+          '  result must be instance of `Flows::Result`'
+        end
+      end
+    end
+  end
+end

data/lib/flows/plugin/output_contract/wrapper.rb

@@ -0,0 +1,55 @@
+module Flows
+  module Plugin
+    module OutputContract
+      # Contains wrappers for initializer and `#call` methods.
+      #
+      # @api private
+      module Wrapper
+        def initialize(*args, &block)
+          super(*args, &block)
+          klass = self.class
+          raise NoContractError, klass if klass.success_contracts.empty? && !klass.skip_output_contract_flag
+        end
+
+        def call(*args, &block)
+          result = super(*args, &block)
+          klass = self.class
+
+          return result if klass.skip_output_contract_flag
+
+          Util.transform_result(klass, result)
+
+          result
+        end
+
+        # Helper methods for {Wrapper} are extracted to this
+        # module as singleton methods to not pollute user classes.
+        #
+        # @api private
+        module Util
+          class << self
+            def transform_result(klass, result)
+              contract = Util.contract_for(klass, result)
+
+              data = result.send(:data)
+
+              transformed_result = contract.transform(data)
+              raise ContractError.new(klass, result, transformed_result.error) if transformed_result.err?
+
+              result.send(:'data=', transformed_result.unwrap)
+            end
+
+            def contract_for(klass, result)
+              raise ResultTypeError.new(klass, result) unless result.is_a?(Flows::Result)
+
+              status = result.status
+              contracts = result.ok? ? klass.success_contracts : klass.failure_contracts
+
+              contracts[status] || raise(StatusError.new(klass, result, contracts.keys))
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/flows/plugin/profiler.rb

@@ -0,0 +1,114 @@
+require_relative 'profiler/report'
+require_relative 'profiler/injector'
+require_relative 'profiler/wrapper'
+
+module Flows
+  module Plugin
+    # Allows to record execution count and time of particular method on class or singleton class.
+    #
+    # Recorded data can be displayed in a different ways.
+    # See {Profiler::Report} implementations for possible options.
+    #
+    # To do a measurement you have call your classes inside {.profile} block.
+    #
+    # @note even without calling {.profile} using this module has some performance
+    #   impact. Don't left this module used in production environments.
+    #
+    # @example
+    #     class MyClass
+    #       CallProfiler = Flows::Plugin::Profiler.for_method(:call)
+    #       include CallProfiler
+    #
+    #       def call(a, b)
+    #         # some work here
+    #       end
+    #     end
+    #
+    #     class AnotherClass
+    #       CallProfiler = Flows::Plugin::Profiler.for_method(:perform)
+    #       extend CallProfiler
+    #
+    #       def self.perform(x)
+    #         MyClass.new.call(x, x)
+    #       end
+    #     end
+    #
+    #     last_result = Flows::Plugin::Profiler.profile do
+    #       AnotherClass.perform(2)
+    #       AnotherClass.perform(6)
+    #     end
+    #
+    #     Profiler.last_report.to_a
+    #     # => [
+    #     #   [:started,  AnotherClass, :singleton, :perform, nil],
+    #     #   [:started,  MyClass,      :instance,  :call,    nil],
+    #     #   [:finished, MyClass,      :instance,  :call,    7.3],
+    #     #   [:finished, AnotherClass, :singleton, :perform, 10.5],
+    #     #   [:started,  AnotherClass, :singleton, :perform, nil],
+    #     #   [:started,  MyClass,      :instance,  :call,    nil],
+    #     #   [:finished, MyClass,      :instance,  :call,    8.8],
+    #     #   [:finished, AnotherClass, :singleton, :perform, 14.2]
+    #     # ]
+    module Profiler
+      THREAD_VAR_FLAG = :flows_profiler_flag
+      THREAD_VAR_REPORT = :flows_profiler_report
+
+      class << self
+        # Generates profiler module for a particular method.
+        #
+        # Use `include` for instance methods and `extend` for singleton ones.
+        #
+        # @param method_name [Symbol] method to wrap with profiling.
+        # @return [Module] module to include or extend.
+        def for_method(method_name)
+          Module.new.tap do |mod|
+            injector_mod = Injector.make_module(method_name)
+            mod.const_set(:Injector, injector_mod)
+            mod.extend injector_mod
+          end
+        end
+
+        # Profiles a block execution.
+        #
+        # @param report [Report, Symbol]
+        #   desired {Report} to be used.
+        #   In case of symbol `:some_name` the `Flows::Plugin::Profiler::Report::SomeName.new` will be used.
+        # @yield code to profile
+        # @return block result
+        def profile(report = :raw)
+          thread = Thread.current
+
+          thread[THREAD_VAR_FLAG] = true
+          thread[THREAD_VAR_REPORT] = make_report(report)
+
+          yield
+        ensure
+          thread[THREAD_VAR_FLAG] = false
+        end
+
+        # Resets thread-local variables used for reporting.
+        def reset
+          thread = Thread.current
+          thread[THREAD_VAR_FLAG] = false
+          thread[THREAD_VAR_REPORT] = nil
+        end
+
+        # @return [Report, nil] last generated report if some.
+        def last_report
+          Thread.current[THREAD_VAR_REPORT]
+        end
+
+        private
+
+        def make_report(report_or_sym)
+          case report_or_sym
+          when Report then report_or_sym
+          when Symbol
+            const_name = report_or_sym.to_s.split('_').map(&:capitalize).join
+            Report.const_get(const_name).new
+          end
+        end
+      end
+    end
+  end
+end

data/lib/flows/plugin/profiler/injector.rb

@@ -0,0 +1,35 @@
+module Flows
+  module Plugin
+    module Profiler
+      # @api private
+      module Injector
+        class << self
+          def make_module(method_name)
+            Module.new.tap do |mod|
+              add_included(mod, method_name)
+              add_extended(mod, method_name)
+            end
+          end
+
+          private
+
+          def add_included(mod, method_name)
+            mod.define_method(:included) do |target|
+              raise 'must be included into class' unless target.is_a?(Class)
+
+              target.prepend Wrapper.make_instance_wrapper(method_name)
+            end
+          end
+
+          def add_extended(mod, method_name)
+            mod.define_method(:extended) do |target|
+              raise 'must be extended into class' unless target.is_a?(Class)
+
+              target.singleton_class.prepend(Wrapper.make_singleton_wrapper(method_name))
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/flows/plugin/profiler/report.rb

@@ -0,0 +1,48 @@
+require_relative 'report/events'
+require_relative 'report/raw'
+require_relative 'report/tree'
+require_relative 'report/flat'
+
+module Flows
+  module Plugin
+    module Profiler
+      # Base class for {Profiler} reports.
+      #
+      # @!method to_s
+      #   @abstract
+      #   @return [String] human-readable representation.
+      class Report
+        # @return [Array<Array>] raw profiler events
+        attr_reader :raw_data
+
+        def initialize
+          @raw_data = []
+        end
+
+        # Add event to profile report.
+        #
+        # @param event_type [:started, :finished] event type
+        # @param klass [Class] class where called method is placed
+        # @param method_type [:instance, :singleton] method type
+        # @param method_name [Symbol] name of the called method
+        # @param data [nil, Float] event data, time represented as
+        #   a Float microseconds value.
+        def add(*args)
+          raw_data << args
+        end
+
+        # @return [Array<Event>] array of events
+        def events
+          raw_data.map do |raw_event|
+            klass = case raw_event.first
+                    when :started then StartEvent
+                    when :finished then FinishEvent
+                    end
+
+            klass.new(*raw_event[1..-1])
+          end
+        end
+      end
+    end
+  end
+end