contr 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83b6121c17aee582566059f1664b3d72a167d458f56f685e754b2baee68c35ee
-  data.tar.gz: 1daa46552ab5bfd252654e608608169d6cd5bad555c9dc3263377fdeb164c534
+  metadata.gz: 270200ede82d457029fffede0c22fd9dc4add6b593b595036bcf3af494b615ac
+  data.tar.gz: 10f2da11660e04cf7c94a402bf4e0111e1a1a7b6879d9e441145f9ea93c657d3
 SHA512:
-  metadata.gz: e8d219a62e8dfc86375875c450294cca263146d4d187bf910824d0b56fa3a15a6208d0719c388dd4f2f5d968f6a310f9f19b0bea24a70af8fb4869316bbe16b1
-  data.tar.gz: 21860bfa5ae3787cfd2ca35b4fe2c26fe5e25ba90e94866c7d56880bd3227cf8d3f7d31335d799fe922918a1f8ea0891669e88bf3b124375b7937e5a32dc1746
+  metadata.gz: a79e20a17786f89df7b4e10339db4718e9a5da6118faedc150ef7aadd17771b941cce44f25d2f63cb356348e4f866c802259a2a29fc9b4837bcc4652bb25886e
+  data.tar.gz: 31046e13a3e23dc558cde4e38919b577fe5583e4d23e451df5a76cf64053d2141607e3a449ce46fd743376297e8197bfdeea75023259ddafca09b7f9ad975c54

data/README.md

@@ -1,5 +1,9 @@
 # Contr
 
+[![Gem Version](https://badge.fury.io/rb/contr.svg)](https://badge.fury.io/rb/contr)
+[![Test](https://github.com/ocvit/contr/workflows/Test/badge.svg)](https://github.com/ocvit/contr/actions)
+[![Coverage Status](https://coveralls.io/repos/github/ocvit/contr/badge.svg?branch=main)](https://coveralls.io/github/ocvit/contr?branch=main)
+
 Minimalistic contracts in plain Ruby.
 
 ## Installation
@@ -28,57 +32,61 @@ Contract is called *__matched__* when:
 - *__at least one__* expectation is matched (if present)
 
 Rule is *__matched__* when it returns *__truthy__* value.\
-Rule is *__not matched__* when it returns *__falsey__* value (`nil`, `false`) or *__raises an error__*.
+Rule is *__not matched__* when it returns *__falsy__* value (`nil`, `false`) or *__raises an error__*.
 
-Contract is triggered *__after__* operation under guard is succesfully executed.
+Contract is triggered *__after__* operation under guard is successfully executed.
 
 ## Usage
 
 Example of basic contract:
 
 ```ruby
-class PostRemovalContract < Contr::Act # or Contr::Base if you're a boring person
-  guarantee :verified_via_api do |user_id, post_id, _|
-    !API.post_exists?(user_id, post_id)
+class SumContract < Contr::Act # or Contr::Base if you're a boring person
+  guarantee :result_is_positive_float do |(_), result|
+    result.is_a?(Float) && result > 0
   end
 
-  guarantee :verified_via_web do |*, post_url|
-    !Web.post_exists?(post_url)
+  guarantee :args_are_numbers do |args|
+    args.all?(Numeric)
   end
 
-  expect :removed_from_user_feed do |user_id, post_id, _|
-    !Feed::User.post_exists?(user_id, post_id)
+  expect :arg_1_is_float do |(arg_1, _)|
+    arg_1.is_a?(Float)
   end
 
-  expect :removed_from_global_feed do |user_id, post_id, _|
-    !Feed::Global.post_exists?(user_id, post_id)
+  expect :arg_2_is_float do |(_, arg_2)|
+    arg_2.is_a?(Float)
   end
 end
 
-contract = PostRemovalContract.new
+args = [1, 2.0]
+contract = SumContract.new
+
+contract.check(*args) { args.inject(:+) }
+# => 3.0
 ```
 
 Contract check can be run in 2 modes: `sync` and `async`.
 
 ### Sync
 
-In `sync` mode all rules are executed sequentially in the same thread with the operation.
+In `sync` mode rules are executed sequentially in the same thread with the operation.
 
-If contract is matched - operation result is returned.
+If contract matched - operation result is returned afterwards:
 
 ```ruby
-api_response = contract.check(user_id, post_id, post_url) { API.delete_post(*some_args) }
-# => {data: {deleted: true}}
+contract.check(*args) { 1 + 1 }
+# => 2
 ```
 
-If contract fails - the contract state is dumped via [Sampler](#Sampler), logged via [Logger](#Logger) and match error is raised:
+If contract failed - contract state is dumped via [Sampler](#Sampler), logged via [Logger](#Logger) and match error is raised:
 
 ```ruby
-contract.check(*args) { operation }
-# if one of the guarantees failed
+contract.check(*args) { 1 + 1 }
+# when one of the guarantees failed
 # => Contr::Matcher::GuaranteesNotMatched: failed rules: [...], args: [...]
 
-# if all expectations failed
+# when all expectations failed
 # => Contr::Matcher::ExpectationsNotMatched: failed rules: [...], args: [...]
 ```
 
@@ -87,11 +95,102 @@ If operation raises an error it will be propagated right away, without triggerin
 ```ruby
 contract.check(*args) { raise StandardError, "some error" }
 # => StandardError: some error
+# (no state dump, no log)
 ```
 
 ### Async
 
-WIP
+In `async` mode rules are executed in a separate thread. Operation result is returned immediately regardless of contract match status:
+
+```ruby
+contract.check_async(*args) { 1 + 1 }
+# => 2
+# (contract is still being checked in a background)
+#
+# if contract matched - nothing additional happens
+# if contract failed - state is dumped and logged as with `#check`
+```
+
+If operation raises an error it will be propagated right away, without triggering the contract itself:
+
+```ruby
+contract.check_async(*args) { raise StandardError, "some error" }
+# => StandardError: some error
+# (no state dump, no log)
+```
+
+Each contract instance can work with 2 dedicated thread pools:
+
+- `main` - to execute contract checks asynchronously (always present)
+- `rules` - to execute rules asynchronously (not set by default)
+
+There are couple of predefined pool primitives that can be used:
+
+```ruby
+# fixed
+# - works as a fixed pool of size: 0..max_threads
+# - max_threads == vCPU cores, but can be overridden
+# - similar to `fast` provided by `concurrent-ruby`, but is not global
+Contr::Async::Pool::Fixed.new
+Contr::Async::Pool::Fixed.new(max_threads: 9000)
+
+# io (global)
+# - provided by `concurrent-ruby`
+# - works as a dynamic pool of almost unlimited size (danger!)
+Contr::Async::Pool::GlobalIO.new
+```
+
+Default contract `async` config looks like this:
+
+```ruby
+class SomeContract < Contr::Act
+  async pools: {
+    main: Contr::Async::Pool::Fixed.new,
+    rules: nil # disabled, rules are executed synchronously
+  }
+end
+```
+
+To enable asynchronous execution of rules:
+
+```ruby
+class SomeContract < Contr::Act
+  async pools: {
+    rules: Contr::Async::Pool::GlobalIO.new # or any other pool
+  }
+end
+```
+
+> [!NOTE]
+> Asynchronous execution of rules forces to check them all - not the smallest scope possible as with the sequential one. Make sure that potential extra calls to DB/network are OK (if they have place).
+
+It's also possible to define custom pool:
+
+```ruby
+class CustomPool < Contr::Async::Pool::Base
+  # optional
+  def initialize(*some_args)
+    # ...
+  end
+
+  # required!
+  def create_executor
+    Concurrent::ThreadPoolExecutor.new(
+      min_threads: 0,
+      max_threads: 1234
+      # ...other opts
+    )
+  end
+end
+
+class SomeContract < Contr::Act
+  async pools: {
+    main: CustomPool.new(*some_args)
+  }
+end
+```
+
+Comparison of different pools configurations can be checked in [Benchmarks](#Benchmarks) section.
 
 ## Sampler
 
@@ -101,29 +200,29 @@ Default sampler creates marshalized dumps of contract state in specified folder
 # state structure
 {
   ts:            "2024-02-26T14:16:28.044Z",
-  contract_name: "PostRemovalContract",
+  contract_name: "SumContract",
   failed_rules: [
-    {type: :expectation, name: :removed_from_user_feed, status: :unexpected_error, error: error_instance},
-    {type: :expectation, name: :removed_from_global_feed, status: :failed}
+    {type: :expectation, name: :arg_1_is_float, status: :failed},
+    {type: :expectation, name: :arg_2_check_that_raises, status: :unexpected_error, error: error_instance}
   ],
   ok_rules: [
-    {type: :guarantee, name: :verified_via_api, status: :ok},
-    {type: :guarantee, name: :verified_via_web, status: :ok}
+    {type: :guarantee, name: :result_is_positive_float, status: :ok},
+    {type: :guarantee, name: :args_are_numbers, status: :ok}
   ],
   async:  false,
-  args:   [1, 2, "url"],
-  result: {data: {deleted: true}}
+  args:   [1, 2.0],
+  result: 3.0
 }
 
 # default sampler can be reconfigured
-ConfigedSampler = Contr::Sampler::Default.new(
-  folder: "/tmp/contract_dumps",                       # default: "/tmp/contracts"
-  path_template: "%<contract_name>_%<period_id>i.bin", # default: "%<contract_name>s/%<period_id>i.dump"
-  period: 3600                                         # default: 600 (= 10 minutes)
+ConfiguredSampler = Contr::Sampler::Default.new(
+  folder: "/tmp/contract_dumps",                         # default: "/tmp/contracts"
+  path_template: "%<contract_name>s_%<period_id>i.bin",  # default: "%<contract_name>s/%<period_id>i.dump"
+  period: 3600                                           # default: 600 (= 10 minutes)
 )
 
 class SomeContract < Contr::Act
-  sampler ConfigedSampler
+  sampler ConfiguredSampler
 
   # ...
 end
@@ -156,7 +255,7 @@ class CustomSampler < Contr::Sampler::Base
     # ...
   end
 
-  # required
+  # required!
   def sample!(state)
     # ...
   end
@@ -195,7 +294,7 @@ contract.sampler.read(contract_name: "SomeContract", period_id: "474750")
 
 ## Logger
 
-Default logger logs contract state to specified stream in JSON format. State structure is the same as for sampler with a small addition of `tag` field.
+Default logger logs contract state to specified stream in JSON format. State structure is the same as in sampler plus additional `tag` field:
 
 ```ruby
 # state structure
@@ -205,14 +304,14 @@ Default logger logs contract state to specified stream in JSON format. State str
 }
 
 # default logger can be reconfigured
-ConfigedLogger = Contr::Logger::Default.new(
+ConfiguredLogger = Contr::Logger::Default.new(
   stream: $stderr,     # default: $stdout
   log_level: :warn,    # default: :debug
   tag: "shit-happened" # default: "contract-failed"
 )
 
 class SomeContract < Contr::Act
-  logger ConfigedLogger
+  logger ConfiguredLogger
 
   # ...
 end
@@ -240,7 +339,7 @@ class CustomLogger < Contr::Sampler::Base
     # ...
   end
 
-  # required
+  # required!
   def log(state)
     # ...
   end
@@ -263,6 +362,31 @@ end
 
 ## Configuration
 
+Contract can be configured using arguments passed to `.new` method:
+
+```ruby
+class SomeContract < Contr::Act
+end
+
+contract = SomeContract.new(
+  async: {pools: {main: OtherPool.new, rules: AnotherPool.new}},
+  sampler: CustomSampler.new,
+  logger: CustomLogger.new
+)
+
+contract.main_pool
+# => #<OtherPool:...>
+
+contract.rules_pool
+# => #<AnotherPool:...>
+
+contract.sampler
+# => #<CustomSampler:...>
+
+contract.logger
+# => #<CustomLogger:...>
+```
+
 Contracts can be deeply inherited:
 
 ```ruby
@@ -275,58 +399,58 @@ class SomeContract < Contr::Act
     # ...
   end
 end
-# guarantees:  check_1
-# expecations: check_2
-# sampler:     Contr::Sampler::Default
-# logger:      Contr::Logger:Default
+# guarantees:   check_1
+# expectations: check_2
+# async:        pools: {main: <fixed>, rules: nil}
+# sampler:      Contr::Sampler::Default
+# logger:       Contr::Logger:Default
 
 class OtherContract < SomeContract
+  async pools: {rules: Contr::Async::Pool::GlobalIO.new}
   sampler CustomSampler.new
 
   guarantee :check_3 do
     # ...
   end
 end
-# guarantees:  check_1, check_3
-# expecations: check_2
-# sampler:     CustomSampler
-# logger:      Contr::Logger:Default
+# guarantees:   check_1, check_3
+# expectations: check_2
+# async         pools: {main: <fixed>, rules: <global_io>}
+# sampler:      CustomSampler
+# logger:       Contr::Logger:Default
 
 class AnotherContract < OtherContract
+  async pools: {main: Contr::Async::Pool::GlobalIO.new}
   logger nil
 
   expect :check_4 do
     # ...
   end
 end
-# guarantees:  check_1, check_3
-# expecations: check_2, check_4
-# sampler:     CustomSampler
-# logger:      nil
+# guarantees:   check_1, check_3
+# expectations: check_2, check_4
+# async         pools: {main: <global_io>, rules: <global_io>}
+# sampler:      CustomSampler
+# logger:       nil
 ```
 
-Contract can be configured using args passed to `.new` method:
+Rule block arguments can be accessed in different ways:
 
 ```ruby
 class SomeContract < Contr::Act
-end
-
-contract = SomeContract.new(sampler: CustomSampler.new, logger: CustomLogger.new)
-
-contract.sampler
-# => #<CustomSampler:...>
-
-contract.logger
-# => #<CustomLogger:...>
-```
+  guarantee :all_args_used do |(arg_1, arg_2), result|
+    arg_1  # => 1
+    arg_2  # => 2
+    result # => 3
+  end
 
-Rule block arguments are optional:
+  guarantee :result_ignored do |(arg_1, arg_2)|
+    arg_1  # => 1
+    arg_2  # => 2
+  end
 
-```ruby
-class SomeContract < Contr::Act
-  guarantee :args_used do |arg_1, arg_2|
-    arg_1 # => 1
-    arg_2 # => 2
+  guarantee :check_args_ignored do |(_), result|
+    result # => 3
   end
 
   guarantee :args_not_used do
@@ -334,33 +458,15 @@ class SomeContract < Contr::Act
   end
 end
 
-SomeContract.new.check(1, 2) { operation }
-```
-
-Each rule has access to contract variables:
-
-```ruby
-class SomeContract < Contr::Act
-  guarantee :check_1 do
-    @args         # => [1, [2, 3], {key: :value}]
-    @result       # => 2
-    @contract     # => #<SomeContract:...>
-    @guarantees   # => [{type: :guarantee, name: :check_1, block: #<Proc:...>}]
-    @expectations # => []
-    @sampler      # => #<Contr::Sampler::Default:...>
-    @logger       # => #<Contr::Logger::Default:...>
-  end
-end
-
-SomeContract.new.check(1, [2, 3], {key: :value}) { 1 + 1 }
+SomeContract.new.check(1, 2) { 1 + 2 }
 ```
 
-Having access to `@result` can be really useful in contracts where operation produces a data that should be used inside the rules:
+Having access to `result` can be really useful in contracts where operation produces a data that must be used inside the rules:
 
 ```ruby
 class PostCreationContract < Contr::Act
-  guarantee :verified_via_api do |user_id|
-    post_id = @result["id"]
+  guarantee :verified_via_api do |(user_id), result|
+    post_id = result["id"]
     API.post_exists?(user_id, post_id)
   end
 
@@ -368,56 +474,32 @@ class PostCreationContract < Contr::Act
 end
 
 contract = PostCreationContract.new
-
 contract.check(user_id) { API.create_post(*some_args) }
 # => {"id":1050118621198921700, "text":"Post text", ...}
 ```
 
-Having access to `@guarantees` and `@expectations` makes possible building dynamic contracts (in case you really need it):
+Contract instances are fully isolated from check invocations and can be safely cached:
 
 ```ruby
-class SomeContract < Contr::Act
-  guarantee :guarantee_1 do
-    # add new guarantee to the end of guarantees list
-    @guarantees << {
-      type: :guarantee,
-      name: :guarantee_2,
-      block: proc do
-        puts "guarantee 2"
-        true
-      end
-    }
-
-    puts "guarantee 1"
-    true
-  end
+module Contracts
+  PostRemoval         = PostRemovalContract.new
+  PostRemovalNoLogger = PostRemovalContract.new(logger: nil)
 
-  expect :expect_1 do
-    # add new expectation to the end of expectations list
-    @expectations << {
-      type: :expectation,
-      name: :expect_2,
-      block: proc do |*args|
-        puts "expect 2, args: #{args}"
-        true
-      end
-    }
-
-    puts "expect 1"
-    false
-  end
+  # ...
 end
 
-SomeContract.new.check(1, 2) { operation }
-
-# it will print:
-# => guarantee 1
-# => guarantee 2
-# => expect 1
-# => expect 2, args: [1, 2]
+posts.each do |post|
+  Contracts::PostRemovalNoLogger.check_async(*args) { delete_post(post) }
+end
 ```
 
-Other instance variables (e.g. `@args`, `@logger` etc.) can be modified on the fly too but make sure you really know what you do.
+## Examples
+
+Examples can be found [here](https://github.com/ocvit/contr/tree/main/examples).
+
+## Benchmarks
+
+Comparison of different pool configs for [I/O blocking](https://github.com/ocvit/contr/blob/main/benchmarks/io_task.rb) and [CPU intensive](https://github.com/ocvit/contr/blob/main/benchmarks/cpu_task.rb) tasks can be found in [benchmarks](https://github.com/ocvit/contr/tree/main/benchmarks) folder.
 
 ## TODO
 
@@ -425,8 +507,9 @@ Other instance variables (e.g. `@args`, `@logger` etc.) can be modified on the f
 - [x] Sampler  
 - [x] Logger  
 - [x] Sync matcher  
-- [ ] Async matcher  
-- [ ] Add `before` block for contract definition  
+- [x] Async matcher  
+- [ ] Add `before` block for rules variables pre-initialization
+- [ ] Add `meta` hash to have ability to capture additional debug data from within the rules
 
 ## Development
 
@@ -445,3 +528,8 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/ocvit/
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Credits
+
+- [simple_contracts](https://github.com/bibendi/simple_contracts) by [bibendi](https://github.com/bibendi)
+- [poro_contract](https://github.com/sclinede/poro_contract/) by [sclinede](https://github.com/sclinede)

data/lib/contr/async/pool/fixed.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Contr
+  module Async
+    module Pool
+      class Fixed < Pool::Base
+        def initialize(max_threads: Concurrent.processor_count)
+          @max_threads = max_threads
+        end
+
+        def create_executor
+          Concurrent::ThreadPoolExecutor.new(
+            min_threads:     0,
+            max_threads:     @max_threads,
+            auto_terminate:  true,
+            idletime:        60,           # 1 minute
+            max_queue:       0,            # unlimited
+            fallback_policy: :caller_runs  # doesn't matter - max_queue 0
+          )
+        end
+      end
+    end
+  end
+end

data/lib/contr/async/pool/global_io.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Contr
+  module Async
+    module Pool
+      class GlobalIO < Pool::Base
+        def create_executor
+          Concurrent.global_io_executor
+        end
+      end
+    end
+  end
+end

data/lib/contr/async/pool.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "concurrent-ruby"
+
+module Contr
+  module Async
+    module Pool
+      class Base
+        def executor
+          @executor ||= create_executor
+        end
+
+        def create_executor
+          raise NotImplementedError, "pool should implement `#create_executor` method"
+        end
+
+        def future(*args, &block)
+          Concurrent::Promises.future_on(executor, *args, &block)
+        end
+
+        def zip(*futures)
+          Concurrent::Promises.zip_futures_on(executor, *futures)
+        end
+      end
+    end
+  end
+end

data/lib/contr/base.rb

@@ -5,6 +5,10 @@ module Contr
     class << self
       attr_reader :config, :guarantees, :expectations
 
+      def async(async)
+        set_config(:async, async)
+      end
+
       def logger(logger)
         set_config(:logger, logger)
       end
@@ -39,14 +43,20 @@ module Contr
       end
     end
 
-    attr_reader :logger, :sampler
+    attr_reader :config, :logger, :sampler, :main_pool, :rules_pool, :guarantees, :expectations
 
     def initialize(instance_config = {})
-      @logger = choose_logger(instance_config)
-      @sampler = choose_sampler(instance_config)
+      @config = merge_configs(instance_config)
+
+      init_logger!
+      init_sampler!
+      init_main_pool!
+      init_rules_pool!
 
-      validate_logger!
-      validate_sampler!
+      aggregate_guarantees!
+      aggregate_expectations!
+
+      freeze
     end
 
     def check(*args)
@@ -55,72 +65,98 @@ module Contr
       result
     end
 
+    def check_async(*args)
+      result = yield
+      Matcher::Async.new(self, args, result).match
+      result
+    end
+
     def name
       self.class.name
     end
 
-    def guarantees
-      @guarantees ||= aggregate_rules(:guarantees)
-    end
+    private
 
-    def expectations
-      @expectations ||= aggregate_rules(:expectations)
-    end
+    using Refines::Hash
 
-    private
+    def merge_configs(instance_config)
+      configs = contracts_chain.filter_map(&:config)
+      configs << instance_config
 
-    def choose_logger(instance_config)
-      parent_config = find_parent_config(:logger)
-
-      case [instance_config, self.class.config, parent_config]
-      in [{logger: }, *]
-        logger
-      in [_, {logger: }, _]
-        logger
-      in [*, {logger: }]
-        logger
-      else
-        Logger::Default.new
-      end
+      merged = configs.inject(&:deep_merge) || {}
+      merged.freeze
     end
 
-    def choose_sampler(instance_config)
-      parent_config = find_parent_config(:sampler)
-
-      case [instance_config, self.class.config, parent_config]
-      in [{sampler: }, *]
-        sampler
-      in [_, {sampler: }, _]
-        sampler
-      in [*, {sampler: }]
-        sampler
-      else
-        Sampler::Default.new
-      end
+    def init_logger!
+      @logger =
+        case config
+        in logger: nil | false
+          nil
+        in logger: Logger::Base => custom_logger
+          custom_logger
+        in logger: invalid_logger
+          raise ArgumentError, "logger should be inherited from Contr::Logger::Base or be falsy, received: #{invalid_logger.inspect}"
+        else
+          Logger::Default.new
+        end
     end
 
-    def find_parent_config(key)
-      parents = self.class.ancestors.take_while { |klass| klass != Contr::Base }.drop(1)
-      parents.detect { |klass| klass.config&.key?(key) }&.config
+    def init_sampler!
+      @sampler =
+        case config
+        in sampler: nil | false
+          nil
+        in sampler: Sampler::Base => custom_sampler
+          custom_sampler
+        in sampler: invalid_sampler
+          raise ArgumentError, "sampler should be inherited from Contr::Sampler::Base or be falsy, received: #{invalid_sampler.inspect}"
+        else
+          Sampler::Default.new
+        end
     end
 
-    def aggregate_rules(rule_type)
-      contracts_chain = self.class.ancestors.take_while { |klass| klass != Contr::Base }.reverse
-      contracts_chain.flat_map(&rule_type).compact
+    def init_main_pool!
+      @main_pool =
+        case config.dig(:async, :pools)
+        in main: nil | false
+          raise ArgumentError, "main pool can't be disabled"
+        in main: Async::Pool::Base => custom_pool
+          custom_pool
+        in main: invalid_pool
+          raise ArgumentError, "main pool should be inherited from Contr::Async::Pool::Base, received: #{invalid_pool.inspect}"
+        else
+          Async::Pool::Fixed.new
+        end
     end
 
-    def validate_logger!
-      return unless logger
-      return if logger.class.ancestors.include?(Logger::Base)
+    def init_rules_pool!
+      @rules_pool =
+        case config.dig(:async, :pools)
+        in rules: nil | false
+          nil
+        in rules: Async::Pool::Base => custom_pool
+          custom_pool
+        in rules: invalid_pool
+          raise ArgumentError, "rules pool should be inherited from Contr::Async::Pool::Base or be falsy, received: #{invalid_pool.inspect}"
+        else
+          nil
+        end
+    end
 
-      raise ArgumentError, "logger should be inherited from Contr::Logger::Base or be falsey, received: #{logger.inspect}"
+    def aggregate_guarantees!
+      @guarantees = aggregate_rules(:guarantees).freeze
     end
 
-    def validate_sampler!
-      return unless sampler
-      return if sampler.class.ancestors.include?(Sampler::Base)
+    def aggregate_expectations!
+      @expectations = aggregate_rules(:expectations).freeze
+    end
+
+    def aggregate_rules(rule_type)
+      contracts_chain.flat_map(&rule_type).compact
+    end
 
-      raise ArgumentError, "sampler should be inherited from Contr::Sampler::Base or be falsey, received: #{sampler.inspect}"
+    def contracts_chain
+      @contracts_chain ||= self.class.ancestors.take_while { |klass| klass != Contr::Base }.reverse
     end
   end
 

data/lib/contr/matcher/async.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Contr
+  class Matcher
+    class Async < Matcher::Base
+      def initialize(*)
+        super
+
+        @async = true
+        @ok_rules = Concurrent::Array.new
+        @failed_rules = Concurrent::Array.new
+      end
+
+      def match
+        contract_future = main_pool.future do
+          contract_failed = rules_pool ? check_with_async_rules : check_with_sync_rules
+
+          dump_state! if contract_failed
+        end
+
+        contract_future.wait! if inline?
+      end
+
+      private
+
+      def check_with_async_rules
+        checked_rules = rules_pool.zip(
+          *futures_from(guarantees),
+          *futures_from(expectations)
+        ).value!
+
+        checked_guarantees, checked_expectations = checked_rules.partition { |rule| rule[:type] == :guarantee }
+
+        guarantees_failed   = any_failed?(checked_guarantees)
+        expectations_failed = all_failed?(checked_expectations)
+
+        guarantees_failed || expectations_failed
+      end
+
+      def check_with_sync_rules
+        any_failed?(guarantees) || all_failed?(expectations)
+      end
+
+      def futures_from(rules)
+        rules.map do |rule|
+          rules_pool.future(rule) do |rule|
+            check_rule(rule)
+          end
+        end
+      end
+
+      # for testing purposes
+      def inline?
+        false
+      end
+    end
+  end
+end

data/lib/contr/matcher/sync.rb

@@ -12,37 +12,12 @@ module Contr
       end
 
       def match
-        guarantees_matched?   || dump_state_and_raise(GuaranteesNotMatched)
-        expectations_matched? || dump_state_and_raise(ExpectationsNotMatched)
+        any_failed?(guarantees)   && dump_state_and_raise(GuaranteesNotMatched)
+        all_failed?(expectations) && dump_state_and_raise(ExpectationsNotMatched)
       end
 
       private
 
-      def guarantees_matched?
-        return true if @guarantees.empty?
-
-        @guarantees.all? { |rule| ok_rule?(rule) }
-      end
-
-      def expectations_matched?
-        return true if @expectations.empty?
-
-        @expectations.any? { |rule| ok_rule?(rule) }
-      end
-
-      def ok_rule?(rule)
-        match_result = match_rule(rule)
-        checked_rule = rule.slice(:type, :name).merge!(match_result)
-
-        if match_result[:status] == :ok
-          @ok_rules << checked_rule
-          true
-        else
-          @failed_rules << checked_rule
-          false
-        end
-      end
-
       def dump_state_and_raise(error_class)
         dump_state!
 

data/lib/contr/matcher.rb

@@ -23,17 +23,14 @@ module Contr
     end
 
     class Base
+      extend Forwardable
+
+      def_delegators :@contract, :logger, :sampler, :main_pool, :rules_pool, :guarantees, :expectations
+
       def initialize(contract, args, result)
         @contract = contract
-        @args     = args
-        @result   = result
-
-        # def_delegators would be slickier but it breaks consistency of
-        # variables names when used within the rules definitions
-        @guarantees   = @contract.guarantees
-        @expectations = @contract.expectations
-        @sampler      = @contract.sampler
-        @logger       = @contract.logger
+        @args     = args.freeze
+        @result   = result.freeze
       end
 
       def match
@@ -42,28 +39,51 @@ module Contr
 
       private
 
-      def match_rule(rule)
+      def any_failed?(rules)
+        rules.any? { |rule| rule_failed?(rule) }
+      end
+
+      def all_failed?(rules)
+        !rules.empty? && rules.all? { |rule| rule_failed?(rule) }
+      end
+
+      def rule_failed?(rule)
+        rule = check_rule(rule) unless rule.key?(:status)
+
+        if rule[:status] == :ok
+          @ok_rules << rule
+          false
+        else
+          @failed_rules << rule
+          true
+        end
+      end
+
+      def check_rule(rule)
+        status_data = call_rule(rule)
+        rule.slice(:type, :name).merge(status_data)
+      end
+
+      def call_rule(rule)
         block = rule[:block]
 
-        block_result = instance_exec(*@args, &block)
+        block_result = block.parameters.empty? ? block.call : block.call(@args, @result)
         block_result ? {status: :ok} : {status: :failed}
       rescue => error
         {status: :unexpected_error, error: error}
       end
 
       def dump_state!
-        state = compile_state
-
-        if @sampler
-          dump_info = @sampler.sample!(state)
+        if sampler
+          dump_info = sampler.sample!(state)
           state[:dump_info] = dump_info if dump_info
         end
 
-        @logger&.log(state)
+        logger&.log(state)
       end
 
-      def compile_state
-        {
+      def state
+        @state ||= {
           ts:            Time.now.utc.iso8601(3),
           contract_name: @contract.name,
           failed_rules:  @failed_rules,

data/lib/contr/refines/hash.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Refines
+  module Hash
+    refine ::Hash do
+      def deep_merge(other_hash)
+        merge(other_hash) do |_key, this_value, other_value|
+          if this_value.is_a?(::Hash) && other_value.is_a?(::Hash)
+            this_value.deep_merge(other_value)
+          else
+            other_value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/contr/sampler/default.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "fileutils"
+
 module Contr
   class Sampler
     class Default < Sampler::Base

data/lib/contr/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Contr
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/contr.rb

@@ -1,12 +1,17 @@
 # frozen_string_literal: true
 
 require_relative "contr/version"
+require_relative "contr/refines/hash"
+require_relative "contr/async/pool"
+require_relative "contr/async/pool/fixed"
+require_relative "contr/async/pool/global_io"
 require_relative "contr/logger"
 require_relative "contr/logger/default"
 require_relative "contr/sampler"
 require_relative "contr/sampler/default"
 require_relative "contr/matcher"
 require_relative "contr/matcher/sync"
+require_relative "contr/matcher/async"
 require_relative "contr/base"
 
 module Contr

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: contr
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Dmytro Horoshko
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-02-28 00:00:00.000000000 Z
-dependencies: []
+date: 2024-03-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 description: Minimalistic contracts in plain Ruby.
 email:
 - electric.molfar@gmail.com
@@ -21,11 +35,16 @@ files:
 - LICENSE.txt
 - README.md
 - lib/contr.rb
+- lib/contr/async/pool.rb
+- lib/contr/async/pool/fixed.rb
+- lib/contr/async/pool/global_io.rb
 - lib/contr/base.rb
 - lib/contr/logger.rb
 - lib/contr/logger/default.rb
 - lib/contr/matcher.rb
+- lib/contr/matcher/async.rb
 - lib/contr/matcher/sync.rb
+- lib/contr/refines/hash.rb
 - lib/contr/sampler.rb
 - lib/contr/sampler/default.rb
 - lib/contr/version.rb