blood_contracts-instrumentation 0.1.0

data/lib/blood_contracts/instrumentation/failed_match.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module BloodContracts
+  module Instrumentation
+    # Wrapper for exception happend during the match instrumentation
+    # Should not be used in the app, to distinguish between expected and
+    # unexpected failures
+    class FailedMatch < ::BC::ContractFailure
+      # Initialize failure type with exception
+      #
+      # @param value [Exception] rescued exception from the type match
+      # @option context [Hash] shared context of matching pipeline
+      #
+      # @return [FailedMatch]
+      #
+      def initialize(exception, context: {})
+        @errors = []
+        @context = context
+        @value = exception
+        @context[:exception] = exception
+      end
+
+      # Predicate, whether the data is valid or not
+      # (for the ExceptionCaught it is always False)
+      #
+      # @return [Boolean]
+      #
+      def valid?
+        false
+      end
+
+      # Reader for the exception caught
+      #
+      # @return [Exception]
+      #
+      def exception
+        @context[:exception]
+      end
+    end
+  end
+end

data/lib/blood_contracts/instrumentation/instrument.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module BloodContracts
+  module Instrumentation
+    # Base class for instrumentation tooling
+    class Instrument
+      class << self
+        # Builds an Instrument class from the proto and before/after callbacks
+        #
+        # When `proto` is just a Proc - we create new Instrument class around
+        # Otherwise - use the `proto` object as an instrument
+        #
+        # Also if before/after is defined we add the definition to the `proto`
+        #
+        # @param proto [#call, Proc] callable object that is used as an
+        #   instrumentation tool
+        # @option before [#call, Proc] definition of before callback, it runs
+        #   right after Session#start in the matching pipeline, the argument
+        #   is Session instance for current BC::Refined#match call
+        # @option before [#call, Proc] definition of before callback, it runs
+        #   right after Session#finish in the matching pipeline, the argument
+        #   is Session instance for current BC::Refined#match call
+        #
+        # @return [Instrument, #call]
+        #
+        def build(proto, before: nil, after: nil)
+          raise ArgumentError unless proto.respond_to?(:call)
+
+          instance = instrument_from_proc(proto)
+
+          if before.respond_to?(:call)
+            inst.define_singleton_method(:before, &before)
+          end
+
+          define_stub(instance, :before)
+
+          if after.respond_to?(:call)
+            instance.define_singleton_method(:after, &after)
+          end
+
+          define_stub(instance, :after)
+
+          instance
+        end
+
+        private def define_stub(instance, name)
+          return if instance.respond_to?(name)
+
+          instance.define_singleton_method(name) { |_| }
+        end
+
+        # @private
+        private def instrument_from_proc(proto)
+          return proto unless proto.is_a?(Proc)
+
+          inst_klass = Class.new(self)
+          inst_klass.define_method(:call, &proto)
+          const_set(:"I_#{SecureRandom.hex(4)}", inst_klass)
+          inst_klass.new
+        end
+      end
+
+      # Predefined interface for Instrument before callback, do-no
+      #
+      # @param _session [Session] to use in callback
+      #
+      # @return [Nothing]
+      #
+      def before(_session); end
+
+      # Predefined interface for Instrument after callback, do-no
+      #
+      # @param _session [Session] to use in callback
+      #
+      # @return [Nothing]
+      #
+      def after(_session); end
+
+      # Predefined interface for Instrument finalization call, do-no
+      #
+      # @param _session [Session] to use in callback
+      #
+      # @return [Nothing]
+      #
+      def call(_session); end
+    end
+  end
+end

data/lib/blood_contracts/instrumentation/session.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module BloodContracts
+  module Instrumentation
+    # Basic class to hold data about matching process
+    # Start date, finish date, result type name and the validation context
+    class Session
+      # Unique ID of the session
+      #
+      # @return [String]
+      #
+      attr_reader :id
+
+      # Time when session started
+      #
+      # @return [Time]
+      #
+      attr_reader :started_at
+
+      # Time when session finished
+      #
+      # @return [Time]
+      #
+      attr_reader :finished_at
+
+      # Frozen hash of matching pipeline context
+      #
+      # @return [Hash]
+      #
+      attr_reader :context
+
+      # Additional text about scope of the mathc (e.g. "User:12")
+      #
+      # @return [String]
+      #
+      attr_reader :scope
+
+      # Name of the type which owns the session
+      #
+      # @return [String]
+      #
+      attr_reader :matcher_type_name
+
+      # Name of the matching result type
+      #
+      # @return [String]
+      #
+      attr_reader :result_type_name
+
+      # List of matches in the pipeline run
+      #
+      # @return [Array<String>]
+      #
+      attr_reader :path
+
+      # Additional data for instrumentaion stores here
+      #
+      # @return [Hash]
+      #
+      attr_reader :extras
+
+      # Whether the result was valid or not
+      #
+      # @return [Boolean]
+      #
+      def valid?
+        !!@valid
+      end
+
+      # Initialize the session with matcher type name with defaults
+      #
+      # @param type_name [String] name of the type which owns the session
+      #
+      # @return [Nothing]
+      #
+      def initialize(type_name)
+        @id = SecureRandom.hex(10)
+        @matcher_type_name = type_name
+        @extras = {}
+        @context = {}
+      end
+
+      # Marks the session as started
+      # If you inherit the Session this method runs right BEFORE matching start
+      #
+      # @return [Nothing]
+      #
+      def start
+        @started_at = Time.now
+      end
+
+      # Session scope fallback
+      NO_SCOPE = "unscoped"
+
+      # Session validation path fallback
+      NO_VALIDATION_PATH = "undefined"
+
+      # Session result type name fallback
+      NO_TYPE_MATCH = "unmatched"
+
+      # Marks the session as finished (with the type)
+      # If you inherit the Session this method runs right AFTER matching
+      # finished (even if an exception raised the method would be called)
+      #
+      # @param type_match [BC::Refined] result type of matching pipeline
+      #
+      # @return [Nothing]
+      #
+      def finish(type_match)
+        @finished_at = Time.now
+        @context = type_match.context.dup.freeze if type_match
+        @valid = type_match&.valid?
+
+        @result_type_name = type_match&.class&.name || NO_TYPE_MATCH
+        @id =    @context.fetch(:session_id) { @id }
+        @scope = @context.fetch(:scope) { NO_SCOPE }
+        @path =  @context.fetch(:steps) { NO_VALIDATION_PATH }
+      end
+    end
+  end
+end

data/lib/blood_contracts/instrumentation/session_finalizer.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module BloodContracts
+  module Instrumentation
+    # Top-level interface for Instrument finalizers
+    module SessionFinalizer
+      module_function
+
+      require_relative "./session_finalizer/basic.rb"
+      require_relative "./session_finalizer/fibers.rb"
+      require_relative "./session_finalizer/threads.rb"
+
+      # Names of finalizers
+      #
+      # @return [Array<Symbol>]
+      #
+      FINALIZERS = %i[basic fibers threads].freeze
+
+      # @private
+      WRONG_FINALIZER_MSG = "Choose finalizer wisely: #{FINALIZERS.join(', ')}"
+
+      # @private
+      DEFAULT_POOL_SIZE = 13
+
+      # Current thread instance of the Session finalizer
+      #
+      # @return [#finalize!]
+      #
+      def instance
+        Thread.current[:bc_session_finalizer] ||=
+          Instrumentation.reset_session_finalizer!
+      end
+
+      # Reset the finalizer by name
+      #
+      # @param name [Symbol] finalizer to find
+      # @param **opts [Hash] options passed to finalizer constructor
+      #
+      # @return [#finalize!]
+      #
+      def init(name, **opts)
+        Thread.current[:bc_session_finalizer] = find_finalizer_by(name, **opts)
+      end
+
+      # @private
+      private def find_finalizer_by(name, pool_size: DEFAULT_POOL_SIZE)
+        case name
+        when :basic
+          Basic
+        when :fibers
+          Fibers.new(pool_size)
+        when :threads
+          Threads
+        else
+          raise ArgumentError, WRONG_FINALIZER_MSG
+        end
+      end
+    end
+  end
+end

data/lib/blood_contracts/instrumentation/session_finalizer/basic.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module BloodContracts
+  module Instrumentation
+    module SessionFinalizer
+      # Basic implementation of Session finaliazer
+      module Basic
+        # Run the instruments against the session in a loop
+        # Pros:
+        #   - simplest, obvious logic
+        # Cons:
+        #   - failure in one instrument affects the others
+        #
+        # @param instruments [Array<Instrument>] list of Instruments to run
+        #   against the session
+        # @param session [Session] object that hold information about matching
+        #   process, argument for Instrument#call
+        #
+        # @return [Nothing]
+        #
+        def self.finalize!(instruments, session)
+          instruments.each { |i| i.call(session) }
+        end
+      end
+    end
+  end
+end

data/lib/blood_contracts/instrumentation/session_finalizer/fibers.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "fiber"
+
+module BloodContracts
+  module Instrumentation
+    module SessionFinalizer
+      # Threads over fibers implementation of Session finaliazer
+      class Fibers
+        # Error message when fibers pool is not enough to run all the
+        # instruments
+        STARVATION_MSG = "WARNING! BC::Instrumentation fiber starvation!"
+
+        # Pool of Fibers to finalize instrumentation session
+        #
+        # @return [Array<Fiber>]
+        #
+        attr_reader :fibers
+
+        # Initialize the fibers pool
+        #
+        # @param pool_size [Integer] number of fibers to use in a single run
+        def initialize(pool_size)
+          @fibers = pool_size.times.map { create_fiber_with_a_thread }
+        end
+
+        # Run the instruments against the session in a loop (each in a separate
+        # fiber on separate thread)
+        #
+        # Pros:
+        #   - Each instrument call don't affect the others
+        #   - Each instrument run in parallel (up to GIL)
+        #   - Runs in parallel to the matching process, so should have
+        #     minimum impact on BC::Refined#match speed
+        # Cons:
+        #   - thread creation have costs
+        #   - the pool size is limited, so if you use number of instruments
+        #     more the pool size  you have to update Config#finalizer_pool_size
+        #     properly
+        #
+        # @param instruments [Array<Instrument>] list of Instruments to run
+        #   against the session
+        # @param session [Session] object that hold information about matching
+        #   process, argument for Instrument#call
+        #
+        # @return [Nothing]
+        #
+        def finalize!(instruments, session)
+          instruments.each do |instrument|
+            raise STARVATION_MSG unless (fiber = @fibers.shift)
+
+            fiber.resume instrument, session if fiber.alive?
+          end
+        end
+
+        # @private
+        #
+        # Create a fiber which holds a Thread to run next Instrument#call
+        # against the session
+        #
+        # @return [Fiber]
+        protected def create_fiber_with_a_thread
+          Fiber.new do |instrument, session|
+            loop do
+              thread = Thread.new(instrument, session) { |i, s| i.call(s) }
+              @fibers.unshift Fiber.current
+              instrument, session = Fiber.yield
+              thread.join
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/blood_contracts/instrumentation/session_finalizer/threads.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module BloodContracts
+  module Instrumentation
+    module SessionFinalizer
+      # Multi-threaded implementation of Session finalizer
+      module Threads
+        # Run the instruments against the session in a Thread in a loop
+        # Pros:
+        #   - parallel execution of instruments (up to GIL)
+        #   - one failed instrument do not affect the others
+        # Cons:
+        #   - creating a thread has costs
+        #   - do not parallel with the BC::Refined matching, as we need to
+        #     finish the threads, join them to main Thread
+        #
+        # @param instruments [Array<Instrument>] list of Instruments to run
+        #   against the session
+        # @param session [Session] object that hold information about matching
+        #   process, argument for Instrument#call
+        #
+        # @return [Nothing]
+        #
+        def self.finalize!(instruments, session)
+          threads = instruments.map do |i|
+            Thread.new { i.call(session) }
+          end
+          threads.map(&:join)
+        end
+      end
+    end
+  end
+end