blood_contracts-core 0.3.5 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b07e48354690944459676628a2a1e954fc39bb3751cb8245c4e66ca9f3bfa71
-  data.tar.gz: db15168f735faead06ebf84ecf46c3554c44bea67da669e2e48d6631f5586cac
+  metadata.gz: 7c89ea50c7af537eb81bfd8f949165ffaffde2bdeb9aec92668e601acc90802c
+  data.tar.gz: 6c85bee20832ba39fc933987823b1dcbc7583ab0f991599837a2f0625d74d826
 SHA512:
-  metadata.gz: 04af6db1580a874e06ed3f1c63bea6741e21cdd6f107e7b44364c3dedf06114ac0d09ad4e9555d1719125c8ed42a5b32b40d35df5e33fcc44da62dec82b0e79f
-  data.tar.gz: 2e21d3eec2392af4729752b5099039eafc9b9709bf240768dd3beec023e03581b02c89dc4fb87f95f0b6b9b601a703e6f3aa3df5ff2386817006638c9cd7f0ad
+  metadata.gz: fe7e788aac1df68e58bd5e28f2dfcf875f5b47deca6b0012cd309b81749f147b712290608d513bf97421f5064813e3a44a14888d63c774ac8f01cfa0027c27c0
+  data.tar.gz: 0a349cdc0f9f668fe7cda58a3531e322f6b76ee8116640ce4aad9e25d7ae58680f8a3c00cadc80c202b525974d6a66637b0c35ec5e7947a93d9e70bb375af061

data/.rubocop.yml

@@ -0,0 +1,31 @@
+---
+
+AllCops:
+  DisplayCopNames:    true
+  DisplayStyleGuide:  true
+  StyleGuideCopsOnly: true
+  TargetRubyVersion:  2.4
+  Exclude:
+    - examples/*
+    - blood_contracts-core.gemspec
+    - vendor/bundle/**/*
+
+Metrics/LineLength:
+  AllowHeredoc: true
+  AllowURI: true
+  URISchemes:
+    - http
+    - https
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Naming/FileName:
+  Exclude:
+    - lib/blood_contracts-core.rb

data/.travis.yml

@@ -1,7 +1,19 @@
 ---
-sudo: false
+sudo:     false
 language: ruby
-cache: bundler
+cache:    bundler
+before_install:
+  - gem install bundler --no-document
+  - gem update --system
+script:
+  - bundle exec rspec
+  - bundle exec rubocop
 rvm:
-  - 2.6.2
-before_install: gem install bundler -v 2.0.1
+  - 2.4.0
+  - 2.6.0
+  - ruby-head
+  - jruby-head
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+    - rvm: jruby-head

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/)
+and this project adheres to [Semantic Versioning](http://semver.org/).
+
+## [0.4.0] - [2019-06-25]
+
+This is a first public release marked in change log with features extracted from production app.
+Includes:
+- Base class BloodContracs::Core::Refined to write your own validations
+- Meta classes BloodContracs::Core::Pipe, BloodContracs::Core::Sum and BloodContracs::Core::Tuple for validations composition in ADT style
+- BloodContracs::Core::Contract meta class as a syntactic sugar to define your own contracts with Refined validations under the hood

data/README.md

@@ -1,7 +1,56 @@
+[![Build Status](https://travis-ci.org/sclinede/blood_contracts-core.svg?branch=master)][travis]
+[![Code Climate](https://codeclimate.com/github/sclinede/blood_contracts-core/badges/gpa.svg)][codeclimate]
+
+[gem]: https://rubygems.org/gems/blood_contracts-core
+[travis]: https://travis-ci.org/sclinede/blood_contracts-core
+[codeclimate]: https://codeclimate.com/github/sclinede/blood_contracts-core
+[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::Core
 
-Simple implementation of Refinement Types and Contract (based on types).
-Would be the basement for the BloodContracts API production testing framework.
+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
+* **Independent**. It have no dependencies and you need nothing more to write your complex validations
+* **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
+
+```ruby
+# Write your "types" as simple as...
+class Email < ::BC::Refined
+  REGEX = /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i
+
+  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
+```
 
 ## Installation
 
@@ -19,15 +68,324 @@ Or install it yourself as:
 
     $ gem install blood_contracts-core
 
-## Usage
+## Refinment Data Type (BC::Refined class)
+
+Refinement type is an Algebraic Data Type (read, you could compose it with other types) with some predicate to check against the data.
+In Ruby we've implemented it as a class with method `.match` which accepts single argument - _value_ which could be any kind of object.
+This method ALWAYS returns ancestor of BC::Refined. So the most common usage would be:
+
+```ruby
+case match = RegistrationFormType.match(params)
+when RegistrationFormType
+  match.to_h # converts your data to valid Ruby hash
+when BC::ContractFailure
+  match.messages # deal with error messages
+else raise # remember the matching should be exhaustive (simplifies debugging, I promise 🙏)
+end
+```
+
+To create your first type just inherit class from BC::Refined and implement method `#match`.
+
+The method should:
+- return self or nil on successful validation
+- return BC::ContractFailure instance by calling method `#failure` and provide error text/symbol
+
+```ruby
+require 'countries' # gem with data about countries
+class Country < BC::Refined
+  def match
+    return if ISO3166::Country.find_country_by_alpha2(context[:country_name] = value.to_s)
+    failure(:unknown_country)
+  end
+end
+```
+
+Also, you could improve the successful outcome by mapping VALID data to something more appropriate, for example you could normalize data. For that you need only implement `#mapped`
+
+```ruby
+require 'countries' # gem with data about countries
+class Country < BC::Refined
+  def match
+    context[:country_string] = value.to_s
+    context[:found_country] = ISO3166::Country.find_country_by_alpha2(context[:country_string])
+    return if context[:found_country]
+    failure(:unknown_country)
+  end
+
+  def mapped
+    context[:found_country].name
+  end
+end
+
+case match = Country.call("CI")
+when Country
+  match.unpack # => "Côte d'Ivoire"
+when BC::ContractFailure
+  match.messages # => [:unknown_country]
+else raise # ... you know why
+end
+```
+
+Okay, we passed through single value validation. How about complex cases?
+
+Imagine you want to validate response from some JSON API, let's write your first API client with refinement types together.
+
+For this example we'll create RubygemsAPI client:
+
+```ruby
+require 'net/http'
+
+module RubygemsAPI
+  class Client
+    ROOT = "https://rubygems.org/api/v1/gems/".freeze
+
+    def self.get(path)
+      uri = URI.parse(File.join(ROOT, path))
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      http.get(uri.request_uri).body
+    end
+
+    def self.gem(name)
+      Validation.call get("#{name}.json")
+    end
+  end
+end
+```
+
+But what is the RubygemsAPI::Validation class?
+
+## "And Then" Composition (BC::Pipe class)
+
+Our API client just reads a document from the Internet, which is why first we need to parse it as JSON and then extract something useful.
+This is where `#and_then` method quite useful. It runs validation over first BC::Refined and only if the first validation was successful calls the other one.
+Otherwise we'll just receive `BC::ContractFailure`, you know.
+
+Our first challenge is to read Ruby gem info from the API, so we need two types: Json (for parsing) and Gem (for gem info)
+
+```ruby
+module RubygemsAPI
+  require 'json'
+
+  class Json < BC::Refined
+    def match
+      # now it's easy to understand why we caught JSON::ParserError
+      context[:response] = value.to_s
+      context[:parsed] = ::JSON.parse(context[:response])
+      self
+    rescue JSON::ParserError => ex
+      context[:exception] = ex # now we could easily playaround with exception and reraise it
+      failure(:invalid_json)
+    end
+
+    # so the next validation in the pipe will receive parsed response, not unparsed string
+    def mapped
+      context[:parsed]
+    end
+  end
+
+  class GemInfo < BC::Refined
+    # I chose some data that is interesing for me
+    INFO_KEYS = %w(name downloads info authors version homepage_uri source_code_uri)
+
+    def match
+      # We have to make sure that result is a hash with appropriate keys
+      is_a_project = value.is_a?(Hash) && (INFO_KEYS - value.keys).empty?
+      return failure(:reponse_is_not_gem_info) unless is_a_project
+
+      context[:gem_info] = value.slice(*INFO_KEYS)
+      self
+    end
+
+    def mapped
+      context[:gem_info]
+    end
+  end
+
+  # Simple "and_then" composition will look like that:
+  Validation = Json.and_then(GemInfo)
+end
+```
+
+Let's test our API client!
+
+```ruby
+gem = RubygemsAPI::Client.gem("rack") # => #<RubygemAPI::GemInfo ...>
+gem.unpack # => {"name" => ..., "authors" => ...}
+```
+
+Nice!
+But wait, what if we misspelled gem name?
+
+```ruby
+gem = RubygemsAPI::Client.gem("big-bada-bum") # => #<BC::ContractFailure ...>
+gem.messages # => [:invalid_json]
+# hmmm, wait... what?
+gem.context[:response] # => "This rubygem could not be found."
+# it is plain text. yes. :(
+```
+
+It would be great to show that original message to our user, but how?
+
+
+## "Or" Composition (BC::Sum class)
+
+Actually, we could add another type in our validation using "Or" composition. Use it by calling `#or_a` / `#or_an` method on your BC::Refined class.
+Let's try:
+
+```ruby
+module RubygemsAPI
+  # ...
+
+  class PlainTextError < BC::Refined
+    def match
+      context[:response] = value.to_s
+      # to avoid multiple parsing of response, we'll try to save it
+      context[:parsed] = JSON.parse(context[:response])
+      failure(:non_plain_text_response)
+    rescue JSON::ParserError
+      self
+    end
+
+    def mapped
+      context[:response]
+    end
+  end
+
+  Validation = PlainTextError.or_a(Json.and_then(GemInfo))
+end
+```
+
+Let's test our API client, again!
+
+```ruby
+gem = RubygemsAPI::Client.gem("rack") # => #<RubygemAPI::GemInfo ...>
+gem.unpack # => {"name" => ..., "authors" => ...}
+
+# good, but how about not found case?
+gem = RubygemsAPI::Client.gem("big-bada-bum") # => #<RubygemAPI::PlainTextError ...>
+gem.unpack # => "This rubygem could not be found."
+```
+
+And of course we could use it in a case statement:
+```ruby
+case gem = RubygemsAPI::Client.gem("rack")
+when GemInfo
+  gem.unpack # show data to user
+when PlaintTextError
+  {message: gem.unpack, status: 400} # wrap it into json response
+when BC::ContractFailure
+  match.messages
+else raise # ... you know why
+end
+```
+
+It was a nice run!
+
+So actually only one other scenario left to show.
+
+Do you remember the Login type from the beginning? Let's try to implement simple registration form validation.
+
+## "And" Composition (BC::Tuple class)
+
+If you'll try to represent complex data with refinement types the best tool is "and" composition or "product" of types. Sounds wierd?
+
+But you actually work with that concept all the time. It's just a record or struct.
+
+Let's write our registration form validation with a Struct:
+
+```ruby
+RegistrationForm = Struct.new(:login, :password) do
+  def self.call(login, password)
+    # validation logic
+  end
+end
+```
+
+So, the BloodContracts version will look the same, except you only need to implement types for login and password:
+
+```ruby
+module Registration
+  class Email < ::BC::Refined
+    REGEX = /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i
+
+    def match
+      context[:email_input] = value.to_s
+      return failure(:invalid_email) unless context[:email_input] =~ REGEX
+      context[:email] = context[:email_input]
+      self
+    end
+  end
+
+  class Phone < ::BC::Refined
+    REGEX = /\A(\+7|8)(9|8)\d{9}\z/i
+
+    def match
+      context[:phone_input] = value.to_s
+      return failure(:invalid_phone) unless context[:phone_input] =~ REGEX
+      context[:phone] = context[:phone_input]
+      self
+    end
+  end
+
+  class Ascii < ::BC::Refined
+    REGEX = /^[[:ascii:]]+$/i
+
+    def match
+      context[:ascii_input] = value.to_s
+      return failure(:not_ascii) unless context[:ascii_input] =~ REGEX
+      context[:ascii_string] = context[:ascii_input]
+      self
+    end
+  end
+
+  # Create meta class as the Struct.new
+  Form = BC::Tuple.new do
+    # defines a reader and applies validation on `.match` call
+    attribute :login, Email.or_a(Phone)
+    attribute :password, Ascii
+  end
+end
+```
+
+And the code that you'll put in your controller is something like that:
+
+```ruby
+class RegistrationController < ActionController::Base
+  def create
+    case match = Registration::Form.match(params)
+    when Registration::Form
+      # login here is either Phone or Email
+      # password here is always ASCII only string
+      user = User.find_or_create!(login: match.login) do |user|
+        user.password = match.password
+        user.email = match.context[:email]
+        user.phone = match.context[:phone]
+      end
+      render json: {code: 200, user_id: user.id, message: "User was successfully created!"}
+    when BC::ContractFailure
+      message = match.messages.map(&I18n.method(:t)).join("\n")
+      render json: {code: 400, message: message}
+    else
+      Honeybadger.notify("Invalid BloodContracts usage", context: match.inspect)
+      render json: {code: 500, message: "Unexpected contract behavior. Fix me ASAP"}
+    end
+  end
+end
+```
+
+Now, you're ready to write any kind of complex data validation with BloodContracts
+
+What are the next steps?
 
-TODO: Write usage instructions here
+Soon we'll announce `blood_contracts-extended` and `blood_contracts-monitoring`, which will help you monitor the data (what types and how often matches in your system) and
+even collect for you unique samples of the communication (up to the types that matched).
 
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `gemspec`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 

data/Rakefile

@@ -3,4 +3,4 @@ require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+task default: :spec

data/blood_contracts-core.gemspec

@@ -1,30 +1,23 @@
+Gem::Specification.new do |gem|
+  gem.name          = "blood_contracts-core"
+  gem.version       = "0.4.0"
+  gem.authors       = ["Sergey Dolganov (sclinede)"]
+  gem.email         = ["sclinede@evilmartians.com"]
 
-lib = File.expand_path("../lib", __FILE__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require "blood_contracts/core/version"
+  gem.summary       = "Core classes for data validation with contracts approach"
+  gem.description   = "Core classes for data validation with contracts approach (using Either + Writer monad combination & ADT for composition)"
+  gem.homepage      = "https://github.com/sclinede/blood_contracts-core"
+  gem.license       = "MIT"
 
-Gem::Specification.new do |spec|
-  spec.name          = "blood_contracts-core"
-  spec.version       = BloodContracts::Core::VERSION
-  spec.authors       = ["Sergey Dolganov"]
-  spec.email         = ["sclinede@evilmartians.com"]
+  gem.files            = `git ls-files`.split($INPUT_RECORD_SEPARATOR)
+  gem.test_files       = gem.files.grep(/^spec/)
+  gem.extra_rdoc_files = Dir["CODE_OF_CONDUCT.md", "README.md", "LICENSE", "CHANGELOG.md"]
 
-  spec.summary       = %q{Core classes for Contracts API validation}
-  spec.description   = %q{Core classes for Contracts API validation}
-  spec.homepage      = "https://github.com/sclinede/blood_contracts-core"
-  spec.license       = "MIT"
+  gem.required_ruby_version = ">= 2.4"
 
-  # Specify which files should be added to the gem when it is released.
-  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
-  end
-  spec.bindir        = "bin/"
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
-
-  spec.add_development_dependency "bundler", "~> 2.0"
-  spec.add_development_dependency "pry"
-  spec.add_development_dependency "rake", "~> 10.0"
-  spec.add_development_dependency "rspec", "~> 3.0"
+  gem.add_development_dependency "bundler", "~> 2.0"
+  gem.add_development_dependency "pry"
+  gem.add_development_dependency "rake", "~> 10.0"
+  gem.add_development_dependency "rspec", "~> 3.0"
+  gem.add_development_dependency "rubocop", "~> 0.49"
 end

data/examples/json_response.rb

@@ -1,57 +1,51 @@
-require 'json'
-require 'blood_contracts/core'
+require "json"
+require "blood_contracts/core"
 
 module Types
   class JSON < BC::Refined
     def match
-      super do
-        begin
-          context[:parsed] = ::JSON.parse(unpack_refined(@value))
-          self
-        rescue StandardError => error
-          failure(error)
-        end
-      end
+      context[:parsed] = ::JSON.parse(value)
+      self
+    rescue StandardError => error
+      failure(error)
     end
 
-    def unpack
-      super { |match| match.context[:parsed] }
+    def mapped
+      context[:parsed]
     end
   end
 
   class Tariff < BC::Refined
     def match
-      super do
-        context[:data] = unpack_refined(@value).slice("cost", "cur").compact
-        context[:tariff_context] = 1
-        return self if context[:data].size == 2
-        failure(:not_a_tariff)
-      end
+      context[:data] = value.slice("cost", "cur").compact
+      context[:tariff_context] = 1
+      return if context[:data].size == 2
+
+      failure(:not_a_tariff)
     end
 
-    def unpack
-      super { |match| match.context[:data] }
+    def mapped
+      context[:data]
     end
   end
 
   class Error < BC::Refined
     def match
-      super do
-        context[:data] = unpack_refined(value).slice("code", "message").compact
-        context[:known_error_context] = 1
-        return self if context[:data].size == 2
-        failure(:not_a_known_error)
-      end
+      context[:data] = unpack_refined(value).slice("code", "message").compact
+      context[:known_error_context] = 1
+      return if context[:data].size == 2
+
+      failure(:not_a_known_error)
     end
 
-    def unpack
-      super { |match| match.context[:data] }
+    def mapped
+      context[:data]
     end
   end
 
   Response = BC::Pipe.new(
     BC::Anything, JSON, (Tariff | Error | Tariff),
-    names: [:raw, :parsed, :mapped]
+    names: %i[raw parsed mapped]
   )
 
   # The same is
@@ -70,14 +64,6 @@ end
 def match_response(response)
   match = Types::Response.match(response)
   case match
-  when BC::ContractFailure
-    puts "Honeybadger.notify 'Unexpected behavior in Russian Post', context: #{match.context}"
-    puts "render json: { errors: 'Ooops! Not working, we've been notified. Please, try again later' }"
-
-    return unless ENV["RAISE"]
-    match.errors.values.flatten.find do |v|
-      raise v if StandardError === v
-    end
   when Types::Tariff
     # работаем с тарифом
     puts "match.context # => #{match.context} \n\n"
@@ -86,8 +72,16 @@ def match_response(response)
     # работаем с ошибкой, e.g. адрес слишком длинный
     puts "match.context # => #{match.context} \n\n"
     puts "render json: { errors: [#{match.unpack['message']}] } }"
+  when BC::ContractFailure
+    puts "Honeybadger.notify 'Unexpected behavior in Russian Post', context: #{match.context}"
+    puts "render json: { errors: 'Ooops! Not working, we've been notified. Please, try again later' }"
+
+    return unless ENV["RAISE"]
+    match.errors.values.flatten.find do |v|
+      raise v if StandardError === v
+    end
   else
-    require'pry';binding.pry
+    raise
   end
 end
 
@@ -98,16 +92,14 @@ valid_response = '{"cost": 1000, "cur": "RUB"}'
 match_response(valid_response)
 puts "#{'=' * 20}================================#{'=' * 20}"
 
-
 puts "\n\n\n"
 puts "#{'=' * 20} WHEN KNOWN API ERROR RESPONSE: #{'=' * 20}"
 error_response = '{"code": 123, "message": "Too Long Address"}'
 match_response(error_response)
 puts "#{'=' * 20}================================#{'=' * 20}"
 
-
 puts "ss => errors }\n\n\n"
 puts "#{'=' * 20} WHEN UNEXPECTED RESPONSE:      #{'=' * 20}"
-invalid_response = '<xml>'
+invalid_response = "<xml>"
 match_response(invalid_response)
 puts "#{'=' * 20}================================#{'=' * 20}"