blood_contracts 0.2.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28ac2afbaaff105357ceefb2e96e4812f5689ceca47fecc4eeffd5c51c45d3a9
-  data.tar.gz: 3d14390aa3ea943b3ad53495b3855c673d2c87da925b3230071d22c555de506c
+  metadata.gz: d2c47ef6538d2aa19e88887ae50e12dd59518fa31077b75dbdf8c5d143cea7a2
+  data.tar.gz: 1bc58ec7ce70d3490454a123cf10dcdee4f97b9a94dc1129a1177319ec11d02a
 SHA512:
-  metadata.gz: 8850f7821e11d0b3ed3acf837569b7ada9b45f0844fb8491a9e212bda1e1599035635f849e28acb0f7966933fe5cb0e4d865266012ce0148a37a2d6afe3679e9
-  data.tar.gz: 8e7e070351a3dc36d63bf6f0817176489350c0ea361dc3deb8cc48f5e578909bb2b62379e421d82b3d27267c9892d5965f788648a64f8b0bb86db10421d37ffc
+  metadata.gz: 6b8a1a15937a6b35cdce7223d15efad1c5bc06edcb1eaabfcc34d0cf22ccceeb273ba0b6ed8da2c92ba7896fc0dc33fc20840a8c4f8f9b0f1329c2c9086d732c
+  data.tar.gz: a82397121b167e929cae791fcfefccf6aa90509606ca7836ca9640b580720a993ee4cd046c23e74a688540447878bf4a7b4ee8fb6e3f51439e7b8640c2fcf9ab

data/README.md

@@ -1,14 +1,68 @@
+[adt_wiki]: https://en.wikipedia.org/wiki/Algebraic_data_type
+[functional_programming_wiki]: https://en.wikipedia.org/wiki/Functional_programming
+[refinement_types_wiki]: https://en.wikipedia.org/wiki/Refinement_type
+[ebaymag]: https://ebaymag.com/
+
 # BloodContracts
 
-Ruby gem to define and validate behavior of API using contract.
+Simple and agile Ruby data validation tool inspired by refinement types and functional approach
+
+* **Powerful**. [Algebraic Data Type][adt_wiki] guarantees that gem is enough to implement any kind of complex data validation, while [Functional Approach][functional_programming_wiki] gives you full control over validation outcomes
+* **Simple**. You could write your first [Refinment Type][refinement_types_wiki] as simple as single Ruby method in single class
+* **Brings transparency**. Comes with instrumentation tools, so now you will exactly know how often each type matches in your production
+* **Rubyish**. DSL is inspired by Ruby Struct. If you love Ruby way you'd like the BloodContracts types
+* **Born in production**. Created on basis of [eBaymag][ebaymag] project, used as a tool to control and monitor data inside API communication
 
-Possible use-cases:
-- Automated external API status check (shooting with critical requests and validation that behavior meets the contract);
-- Automated detection of unexpected external API behavior (Rack::request/response pairs that don't match contract);
-- Contract definition assistance tool (generate real-a-like requests and iterate through oddities of your system behavior)
+```ruby
+# Write your "types" as simple as...
+class Email < ::BC::Refined
+  REGEX = /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i
 
-<a href="https://evilmartians.com/">
-<img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54"></a>
+  def match
+    return if (context[:email] = value.to_s) =~ REGEX
+    failure(:invalid_email)
+  end
+end
+
+class Phone < ::BC::Refined
+  REGEX = /\A(\+7|8)(9|8)\d{9}\z/i
+
+  def match
+    return if (context[:phone] = value.to_s) =~ REGEX
+    failure(:invalid_phone)
+  end
+end
+
+# ... compose them...
+Login = Email.or_a(Phone)
+
+# ... and match!
+case match = Login.match("not-a-login")
+when Phone, Email
+  match # use as you wish, you exactly know what kind of login you received
+when BC::ContractFailure # translate error message
+  match.messages # => [:no_matches, :invalid_phone, :invalid_email]
+else raise # to make sure you covered all scenarios (Functional Way)
+end
+
+# And then in
+# config/initializers/contracts.rb
+
+module Contracts
+  class YabedaInstrument
+    def call(session)
+      valid_marker = session.valid? ? "V" : "I"
+      result = "[#{valid_marker}] #{session.result_type_name}"
+      Yabeda.api_contract_matches.increment(result: result)
+    end
+  end
+end
+
+BloodContracts::Instrumentation.configure do |cfg|
+  # Attach to every BC::Refined ancestor with Login in the name
+  cfg.instrument "Login", Contracts::YabedaInstrument.new
+end
+```
 
 ## Installation
 
@@ -28,120 +82,10 @@ Or install it yourself as:
 
 ## Usage
 
-```ruby
-# define contract
-def contract
-  Hash[
-    success: {
-      check: ->(_input, output) do
-        data = output.data
-        shipping_cost = data.dig(
-          "BkgDetails", "QtdShp", "ShippingCharge"
-        )
-        output.success? && shipping_cost.present?
-      end,
-      threshold: 0.98,
-    },
-    data_missing_error: {
-      check: ->(_input, output) do
-        output.error_codes.present? &&
-        (output.error_codes - ["111"]).empty?
-      end,
-      limit: 0.01,
-    },
-    data_invalid_error: {
-      check: ->(_input, output) do
-        output.error_codes.present? &&
-        (output.error_codes - ["4300", "123454"]).empty?
-      end,
-      limit: 0.01,
-    },
-    strange_weight: {
-      check: ->(input, output) do
-        input.weight > 100 && output.error_codes.empty? && !output.success?
-      end,
-      limit: 0.01,
-    }
-  ]
-end
-
-# define the API input
-def generate_data
-  DHL::RequestData.new(
-    data_source.origin_addresses.sample,
-    data_source.destinations.sample,
-    data_source.prices.sample,
-    data_source.products.sample,
-    data_source.weights.sample,
-    data_source.dates.sample.days.since.to_date.to_s(:iso8601),
-    data_source.accounts.sample,
-  ).to_h
-end
-
-def data_source
-  Hashie::Mash.new(load_fixture("dhl/obfuscated-production-data.yaml"))
-end
-
-# initiate contract suite
-# with default storage (in tmp/blood_contracts/ folder of the project)
-contract_suite = BloodContract::Suite.new(
-  contract: contract,
-  data_generator: method(:generate_data),
-)
-
-# with custom storage backend (e.g. Postgres DB)
-conn = PG.connect( dbname: "blood_contracts" )
-conn.exec(<<~SQL);
-  CREATE TABLE runs (
-    created_at timestamp DEFAULT current_timestamp,
-    contract_name text,
-    rules_matched array text[],
-    input text,
-    output text
-  );
-SQL
-
-contract_suite = BloodContract::Suite.new(
-  contract: contract,
-  data_generator: method(:generate_data),
-
-  storage_backend: ->(contract_name, rules_matched, input, output) do
-    conn.exec(<<~SQL, contract_name, rules_matched, input, output)
-      INSERT INTO runs (contract_name, rules_matched, input, output) VALUES (?, ?, ?, ?);
-    SQL
-  end
-)
-
-# run validation
-runner = BloodContract::Runner.new(
-           ->(input) { DHL::Client.call(input) }
-           suite: contract_suite,
-           time_to_run: 3600, # seconds
-           # or
-           # iterations: 1000
-         ).tap(&:call)
-
-# chech the results
-runner.valid? # true if behavior was aligned with contract or false in any other case
-runner.run_stats # stats about each contract rule or exceptions occasions during the run
-
-```
-
-## TODO
-- Add rake task to run contracts validation
-- Add executable to run contracts validation
-
-## Possible Features
-- Store the actual code of the contract rules in Storage (gem 'sourcify')
-- Store reports in Storage
-- Export/import contracts to YAML, JSON....
-- Contracts inheritance (already exists using `Hash#merge`?)
-- Export `Runner#run_stats` to CSV
-- Create simple web app, to read the reports
+This gem is just facade for the whole data validation and monitoring toolset.
 
-## Other specific use cases
+For deeper understanding see [BloodContracts::Core](https://github.com/sclinede/blood_contracts-core), [BloodContracts::Ext](https://github.com/sclinede/blood_contracts-ext) and [BloodContracts::Instrumentation](https://github.com/sclinede/blood_contracts-instrumentation)
 
-For Rack request/response validation use: `blood_contracts-rack`
 
 ## Development
 

data/Rakefile

@@ -4,3 +4,33 @@ require "rspec/core/rake_task"
 RSpec::Core::RakeTask.new(:spec)
 
 task default: :spec
+task "db:prepare" do
+  require "dotenv"
+  Dotenv.load(".env.development")
+  sh "createdb #{env_database_name}" do
+    # Ignore errors
+  end
+
+  Dotenv.overload(".env.test")
+  sh "createdb #{env_database_name}" do
+    # Ignore errors
+  end
+end
+
+task "db:drop" do
+  require "dotenv"
+  Dotenv.load(".env.development")
+  sh "dropdb #{env_database_name}" do
+    # Ignore errors
+  end
+
+  Dotenv.overload(".env.test")
+  sh "dropdb #{env_database_name}" do
+    # Ignore errors
+  end
+end
+
+def env_database_name
+  require "uri"
+  ENV.fetch("DATABASE_URL").split("/").last
+end

data/bin/console

@@ -3,9 +3,10 @@
 require "bundler/setup"
 require "blood_contracts"
 
+
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
 
 # (If you use this, don't forget to add pry to your Gemfile!)
-require "pry"
-Pry.start
+require "irb"
+IRB.start

data/blood_contracts.gemspec

@@ -1,37 +1,20 @@
-
-lib = File.expand_path("../lib", __FILE__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require "blood_contracts/version"
-
 Gem::Specification.new do |spec|
   spec.name          = "blood_contracts"
 
-  spec.version       = BloodContracts::VERSION
-  spec.authors       = ["Sergey Dolganov"]
-  spec.email         = ["dolganov@evl.ms"]
+  spec.version       = "1.0.0"
+  spec.authors       = ["Sergey Dolganov (sclinede)"]
+  spec.email         = ["sclinede@evilmartians.com"]
 
-  spec.summary       = "Ruby gem to define and validate behavior of API using contracts."
-  spec.description   = "Ruby gem to define and validate behavior of API using contracts."
+  spec.summary       = " Ruby gem for runtime data validation and monitoring using the contracts approach."
+  spec.description   = " Ruby gem for runtime data validation and monitoring using the contracts approach."
   spec.homepage      = "https://github.com/sclinede/blood_contracts"
   spec.license       = "MIT"
 
-  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
-    f.match(%r{^(test|spec|features)/})
-  end
-
-  # Will be introduced soon
-  # spec.bindir        = "exe"
-  # spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
-
-  spec.required_ruby_version = '>= 2.2.0'
+  spec.files         = `git ls-files`.split($INPUT_RECORD_SEPARATOR)
 
-  spec.add_runtime_dependency "dry-initializer", "~> 2.0"
-  spec.add_runtime_dependency "nanoid", "~> 0.2"
-  spec.add_runtime_dependency "hashie", "~> 3.0"
+  spec.required_ruby_version = ">= 2.4"
 
-  spec.add_development_dependency "bundler", "~> 1.16"
-  spec.add_development_dependency "rake", "~> 10.0"
-  spec.add_development_dependency "rspec", "~> 3.0"
-  spec.add_development_dependency "pry", "~> 0.9"
+  spec.add_runtime_dependency "blood_contracts-core", "~> 0.4"
+  spec.add_runtime_dependency "blood_contracts-ext", "~> 0.1"
+  spec.add_runtime_dependency "blood_contracts-instrumentation", "~> 0.1"
 end

data/lib/blood_contracts.rb

@@ -1,38 +1,3 @@
-require "blood_contracts/version"
-
-require_relative "extensions/string.rb"
-require "dry-initializer"
-require "hashie/mash"
-
-require_relative "blood_contracts/suite"
-require_relative "blood_contracts/storage"
-require_relative "blood_contracts/runner"
-require_relative "blood_contracts/debugger"
-require_relative "blood_contracts/base_contract"
-
-module BloodContracts
-  def run_name
-    @__contracts_run_name
-  end
-  module_function :run_name
-
-  def run_name=(run_name)
-    @__contracts_run_name = run_name
-  end
-  module_function :run_name=
-
-  if defined?(RSpec) && RSpec.respond_to?(:configure)
-    require_relative "rspec/meet_contract_matcher"
-
-    RSpec.configure do |config|
-      config.include ::RSpec::MeetContractMatcher
-      config.filter_run_excluding contract: true
-      config.before(:suite) do
-        BloodContracts.run_name = ::Nanoid.generate(size: 10)
-      end
-      config.define_derived_metadata(file_path: %r{/spec/contracts/}) do |meta|
-        meta[:contract] = true
-      end
-    end
-  end
-end
+require "blood_contracts/core"
+require "blood_contracts/ext"
+require "blood_contracts/instrumentation"

data/spec/blood_contracts_spec.rb

@@ -0,0 +1,36 @@
+RSpec.describe BloodContracts do
+  describe ".run_name" do
+    before { BloodContracts.run_name = "External run name" }
+
+    it { expect(BloodContracts.run_name).to eq("External run name") }
+  end
+
+  describe ".storage" do
+    context "when default configuration" do
+      let(:expected_backend) { BloodContracts::Storages::FileBackend }
+      it "has assigned storage" do
+        expect(BloodContracts.storage.backend).to be_kind_of(expected_backend)
+      end
+    end
+
+    context "when custom storage configured" do
+      before do
+        BloodContracts.config { |config| config.storage[:type] = :postgres }
+      end
+      let(:expected_backend) { BloodContracts::Storages::PostgresBackend }
+
+      it "has assigned custom storage" do
+        expect(BloodContracts.storage.backend).to be_kind_of(expected_backend)
+      end
+    end
+  end
+
+  context "when custom storage configured" do
+  end
+
+  context "when custom sampling configured" do
+  end
+
+  context "when RSpec is defined" do
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,16 @@
+require "bundler/setup"
+require "blood_contracts"
+require "dotenv"
+Dotenv.load(".env.test")
+
+RSpec.configure do |config|
+  # Enable flags like --only-failures and --next-failure
+  config.example_status_persistence_file_path = ".rspec_status"
+
+  # Disable RSpec exposing methods globally on `Module` and `main`
+  config.disable_monkey_patching!
+
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+end

metadata

@@ -1,122 +1,66 @@
 --- !ruby/object:Gem::Specification
 name: blood_contracts
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 1.0.0
 platform: ruby
 authors:
-- Sergey Dolganov
+- Sergey Dolganov (sclinede)
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-03-07 00:00:00.000000000 Z
+date: 2019-08-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: dry-initializer
+  name: blood_contracts-core
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '0.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '0.4'
 - !ruby/object:Gem::Dependency
-  name: nanoid
+  name: blood_contracts-ext
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.1'
 - !ruby/object:Gem::Dependency
-  name: hashie
+  name: blood_contracts-instrumentation
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '0.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.16'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.16'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '10.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '10.0'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-- !ruby/object:Gem::Dependency
-  name: pry
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.9'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.9'
-description: Ruby gem to define and validate behavior of API using contracts.
+        version: '0.1'
+description: " Ruby gem for runtime data validation and monitoring using the contracts
+  approach."
 email:
-- dolganov@evl.ms
+- sclinede@evilmartians.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
-- ".travis.yml"
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
@@ -126,22 +70,8 @@ files:
 - bin/setup
 - blood_contracts.gemspec
 - lib/blood_contracts.rb
-- lib/blood_contracts/base_contract.rb
-- lib/blood_contracts/contracts/description.rb
-- lib/blood_contracts/contracts/iterator.rb
-- lib/blood_contracts/contracts/matcher.rb
-- lib/blood_contracts/contracts/statistics.rb
-- lib/blood_contracts/contracts/validator.rb
-- lib/blood_contracts/debugger.rb
-- lib/blood_contracts/runner.rb
-- lib/blood_contracts/storage.rb
-- lib/blood_contracts/storages/base_backend.rb
-- lib/blood_contracts/storages/file_backend.rb
-- lib/blood_contracts/storages/serializer.rb
-- lib/blood_contracts/suite.rb
-- lib/blood_contracts/version.rb
-- lib/extensions/string.rb
-- lib/rspec/meet_contract_matcher.rb
+- spec/blood_contracts_spec.rb
+- spec/spec_helper.rb
 homepage: https://github.com/sclinede/blood_contracts
 licenses:
 - MIT
@@ -154,16 +84,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.2.0
+      version: '2.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
-summary: Ruby gem to define and validate behavior of API using contracts.
+summary: Ruby gem for runtime data validation and monitoring using the contracts approach.
 test_files: []