flows 0.1.0 → 0.5.1

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

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

@@ -0,0 +1,43 @@
+module Flows
+  module Plugin
+    module Profiler
+      class Report
+        # @api private
+        Event = Struct.new(:method_class, :method_type, :method_name, :data) do
+          def subject
+            "#{method_class}#{delimeter}#{method_name}"
+          end
+
+          private
+
+          def delimeter
+            case method_type
+            when :instance then '#'
+            when :singleton then '.'
+            end
+          end
+        end
+
+        # @api private
+        #
+        # Method execution start event.
+        class StartEvent < Event
+          def to_s
+            "start: #{subject}"
+          end
+        end
+
+        # @api private
+        #
+        # Method execution finish event.
+        #
+        # Data is an execution time in microseconds.
+        class FinishEvent < Event
+          def to_s
+            "finish(#{data} microseconds): #{subject}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+require_relative 'flat/method_report'
+
+module Flows
+  module Plugin
+    module Profiler
+      class Report
+        # Flat report. Merges similar calls, hides execution structure.
+        #
+        # It's a variation of a {Rport::Tree} where all calls of the same method
+        # are combined into a one first-level entry.
+        #
+        # @example
+        #     Flows::Plugin::Profiler.profile(:flat) do
+        #       # some code here
+        #     end
+        #
+        #     puts Flows::Plugin::Profiler.last_report
+        class Flat < Tree
+          def to_a
+            method_reports.map(&:to_h)
+          end
+
+          def to_s
+            method_reports.map(&:to_s).join("\n")
+          end
+
+          private
+
+          def method_reports
+            @method_reports ||= root_calculated_node
+                                .group_by_subject
+                                .values
+                                .map { |nodes| MethodReport.new(root_calculated_node, *nodes) }
+                                .sort_by(&:total_self_ms)
+                                .reverse
+          end
+        end
+      end
+    end
+  end
+end