bcdd-contract 0.1.0

data/Rakefile

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.warning = false
+
+  t.libs += %w[lib test]
+
+  t.test_files = FileList.new('test/**/*_test.rb')
+end
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/Steepfile

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+D = Steep::Diagnostic
+
+target :lib do
+  signature 'sig'
+
+  check 'lib'                       # Directory name
+  # check 'Gemfile'                   # File name
+  # check 'app/models/**/*.rb'        # Glob
+  # ignore 'lib/templates/*.rb'
+
+  library 'singleton'               # Standard libraries
+  # library 'strong_json'             # Gems
+
+  # configure_code_diagnostics(D::Ruby.default)      # `default` diagnostics setting (applies by default)
+  # configure_code_diagnostics(D::Ruby.strict)       # `strict` diagnostics setting
+  # configure_code_diagnostics(D::Ruby.lenient)      # `lenient` diagnostics setting
+  # configure_code_diagnostics(D::Ruby.silent)       # `silent` diagnostics setting
+  # configure_code_diagnostics do |hash|             # You can setup everything yourself
+  #   hash[D::Ruby::NoMethod] = :information
+  # end
+  configure_code_diagnostics(D::Ruby.default.merge(D::Ruby::UnknownConstant => :information))
+end
+
+# target :test do
+#   signature 'sig', 'sig-private'
+#
+#   check 'test'
+#
+#   # library 'pathname'              # Standard libraries
+# end

data/examples/README.md

@@ -0,0 +1,11 @@
+## `BCDD::Contact` Examples
+
+> **Attention:** Each example has its own **README** with more details.
+
+1. [Ports and Adapters](ports_and_adapters) - Implements the Ports and Adapters pattern. It uses **`BCDD::Contract::Interface`** to provide an interface from the application's core to other layers.
+
+2. [Anti-Corruption Layer](anti_corruption_layer) - Implements the Anti-Corruption Layer pattern. It uses the **`BCDD::Contract::Proxy`** to define an inteface for a set of adapters, which will be used to translate an external interface (`vendors`) to the application's core interface.
+
+3. [Business Processes](business_processes) - Implements a business process using the [`bcdd-result`](https://github.com/B-CDD/result) gem and uses the `bcdd-contract` to define its contract.
+
+4. [Design by Contract](design_by_contract) - Shows how the `bcdd-contract` can be used to establish pre-conditions, post-conditions, and invariants in a class.

data/examples/anti_corruption_layer/README.md

@@ -0,0 +1,212 @@
+- [🛡️ Anti-Corruption Layer Example](#️-anti-corruption-layer-example)
+- [The ACL](#the-acl)
+  - [🤔 How does it work?](#-how-does-it-work)
+    - [📜 The Contract](#-the-contract)
+    - [🔄 The Adapters](#-the-adapters)
+- [⚖️ What is the benefit of doing this?](#️-what-is-the-benefit-of-doing-this)
+  - [How much to do this (create ACL)?](#how-much-to-do-this-create-acl)
+  - [Is it worth the overhead of contract checking at runtime?](#is-it-worth-the-overhead-of-contract-checking-at-runtime)
+- [🏃‍♂️ How to run the application?](#️-how-to-run-the-application)
+
+## 🛡️ Anti-Corruption Layer Example
+
+The **Anti-Corruption Layer**, or ACL, is a pattern that isolates and protects a system from legacy or dependencies out of its control. It acts as a mediator, translating and adapting data between different components, ensuring they communicate without corrupting each other's data or logic.
+
+To illustrate this pattern, let's see an example of an application that uses  third-party API to charge a credit card.
+
+Let's start seeing the code structure of this example:
+
+```
+├── Rakefile
+├── config.rb
+├── app
+│  └── models
+│     └── payment
+│        └── charge_credit_card.rb
+├── lib
+│  ├── payment_gateways
+│  │  ├── adapters
+│  │  │  ├── circle_up.rb
+│  │  │  └── pay_friend.rb
+│  │  ├── contract.rb
+│  │  └── response.rb
+│  └── payment_gateways.rb
+└── vendor
+   ├── circle_up
+   │  └── client.rb
+   └── pay_friend
+      └── client.rb
+```
+
+The files and directories are organized as follows:
+
+- `Rakefile` runs the application.
+- `config.rb` file contains the configurations.
+- `app` directory contains the domain model where the business process to charge a credit card is implemented.
+- `lib` directory contains the payment gateways contract and adapters.
+- `vendor` directory contains the third-party API clients.
+
+## The ACL
+
+The ACL is implemented in the `PaymentGateways` module (see `lib/payment_gateways.rb`). It translates the third-party APIs (see `vendor`) into something known by the application's domain model. Through this module, the application can charge a credit card without knowing the details/internals of the vendors.
+
+### 🤔 How does it work?
+
+The `PaymentGateways::ChargeCreditCard` class (see `app/models/payment/charge_credit_card.rb`) uses`PaymentGateways::Contract` to ensure the `payment_gateway` object implements the required and known interface (input and output) to charge a credit card.
+
+```ruby
+module Payment
+  class ChargeCreditCard
+    include ::BCDD::Result::Context.mixin(config: { addon: { continue: true } })
+
+    attr_reader :payment_gateway
+
+    def initialize(payment_gateway)
+      @payment_gateway = ::PaymentGateways::Contract.new(payment_gateway)
+    end
+
+    def call(amount:, details: {})
+      Given(amount:)
+        .and_then(:validate_amount)
+        .and_then(:charge_credit_card, details:)
+        .and_expose(:payment_charged, %i[payment_id])
+    end
+
+    private
+
+    def validate_amount(amount:)
+      return Continue() if amount.is_a?(::Numeric) && amount.positive?
+
+      Failure(:invalid_amount, erros: ['amount must be positive'])
+    end
+
+    def charge_credit_card(amount:, details:)
+      response = payment_gateway.charge_credit_card(amount:, details:)
+
+      Continue(payment_id: ::SecureRandom.uuid) if response.success?
+    end
+  end
+end
+```
+
+#### 📜 The Contract
+
+The `PaymentGateways::Contract` defines the interface of the payment gateways. It is implemented by the `PaymentGateways::Adapters::CircleUp` and `PaymentGateways::Adapters::PayFriend` adapters.
+
+```ruby
+module PaymentGateways
+  class Contract < ::BCDD::Contract::Proxy
+    def charge_credit_card(params)
+      params => { amount: Numeric, details: Hash }
+
+      outcome = object.charge_credit_card(params)
+
+      outcome => Response[true | false]
+
+      outcome
+    end
+  end
+end
+```
+
+In this case, the contract will ensure the input by using the `=>` pattern-matching operator, which will raise an exception if it does not match the expected types. After that, it calls the adapter's `charge_credit_card` method and ensures the output is a `PaymentGateways::Response` by using the `=>` operator again.
+
+The response (see `lib/payment_gateways/response.rb`) will ensure the ACL, as it is the object known/exposed to the application.
+
+```ruby
+module PaymentGateways
+  Response = ::Struct.new(:success?)
+end
+```
+
+#### 🔄 The Adapters
+
+Let's see the payment gateways adapters:
+
+`lib/payment_gateways/adapters/circle_up.rb`
+
+```ruby
+module PaymentGateways
+  class Adapters::CircleUp
+    attr_reader :client
+
+    def initialize
+      @client = ::CircleUp::Client.new
+    end
+
+    def charge_credit_card(params)
+      params => { amount:, details: }
+
+      response = client.charge_cc(amount, details)
+
+      Response.new(response.ok?)
+    end
+  end
+end
+```
+
+`lib/payment_gateways/adapters/pay_friend.rb`
+
+```ruby
+module PaymentGateways
+  class Adapters::PayFriend
+    attr_reader :client
+
+    def initialize
+      @client = ::PayFriend::Client.new
+    end
+
+    def charge_credit_card(params)
+      params => { amount:, details: }
+
+      response = client.charge(amount:, payment_data: details, payment_method: 'credit_card')
+
+      Response.new(response.status == 'success')
+    end
+  end
+end
+```
+
+You can see that each third-party API has its way of charging a credit card, so the adapters are responsible for translating the input/output from the third-party APIs to the output known by the application (the `PaymentGateways::Response`).
+
+## ⚖️ What is the benefit of doing this?
+
+The benefit of doing this is that the core business logic is decoupled from the legacy/external dependencies, which makes it easier to test and promote changes in the code.
+
+Using this example, if the third-party APIs change, we just need to implement a new adapter and make the business processes (`Payment::ChargeCreditCard`) use it. The business processes will not be affected as it is protected by the ACL.
+
+### How much to do this (create ACL)?
+
+Use this pattern when there is a real need to decouple the core business logic from external dependencies.
+
+You can start with a simple implementation (without ACL) and refactor it to use this pattern when the need arises.
+
+### Is it worth the overhead of contract checking at runtime?
+
+You can eliminate the overhead by disabling the `BCDD::Contract::Proxy` class, which is a proxy that forwards all the method calls to the object it wraps.
+
+When it is disabled, the `BCDD::Contract::Proxy.new` returns the given object so that the method calls are made directly to it.
+
+To disable it, set the configuration to false:
+
+```ruby
+BCDD::Contract.configuration do |config|
+  config.proxy_enabled = false
+end
+```
+
+## 🏃‍♂️ How to run the application?
+
+In the same directory as this `README`, run:
+
+```bash
+rake
+
+# --  CircleUp  --
+#
+# #<BCDD::Result::Context::Success type=:payment_charged value={:payment_id=>"aa794f93-bab5-4b88-b098-4472a4aa2d33"}>
+#
+# --  PayFriend  --
+#
+# #<BCDD::Result::Context::Success type=:payment_charged value={:payment_id=>"a2519a45-8bfc-471b-b07c-85f4e601de1b"}>
+```

data/examples/anti_corruption_layer/Rakefile

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+if RUBY_VERSION <= '3.1'
+  puts 'This example requires Ruby 3.1 or higher.'
+  exit! 1
+end
+
+require_relative 'config'
+
+task :default do
+  puts '====================='
+  puts 'Anti Corruption Layer'
+  puts '====================='
+
+  puts
+  puts '--  CircleUp  --'
+  puts
+
+  circle_up_gateway = PaymentGateways::Adapters::CircleUp.new
+
+  p Payment::ChargeCreditCard.new(circle_up_gateway).call(amount: 100)
+
+  puts
+  puts '--  PayFriend  --'
+  puts
+
+  pay_friend_gateway = PaymentGateways::Adapters::PayFriend.new
+
+  p Payment::ChargeCreditCard.new(pay_friend_gateway).call(amount: 200)
+end

data/examples/anti_corruption_layer/app/models/payment/charge_credit_card.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Payment
+  class ChargeCreditCard
+    include ::BCDD::Result::Context.mixin(config: { addon: { continue: true } })
+
+    attr_reader :payment_gateway
+
+    def initialize(payment_gateway)
+      @payment_gateway = ::PaymentGateways::Contract.new(payment_gateway)
+    end
+
+    def call(amount:, details: {})
+      Given(amount:)
+        .and_then(:validate_amount)
+        .and_then(:charge_credit_card, details:)
+        .and_expose(:payment_charged, %i[payment_id])
+    end
+
+    private
+
+    def validate_amount(amount:)
+      return Continue() if amount.is_a?(::Numeric) && amount.positive?
+
+      Failure(:invalid_amount, erros: ['amount must be positive'])
+    end
+
+    def charge_credit_card(amount:, details:)
+      response = payment_gateway.charge_credit_card(amount:, details:)
+
+      Continue(payment_id: ::SecureRandom.uuid) if response.success?
+    end
+  end
+end

data/examples/anti_corruption_layer/config.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'bundler/inline'
+
+$LOAD_PATH.unshift(__dir__)
+
+gemfile do
+  source 'https://rubygems.org'
+
+  gem 'bcdd-result', '>= 0.12.0'
+  gem 'bcdd-contract', path: '../../'
+end
+
+require 'vendor/pay_friend/client'
+require 'vendor/circle_up/client'
+
+require 'lib/payment_gateways'
+
+require 'app/models/payment/charge_credit_card'
+

data/examples/anti_corruption_layer/lib/payment_gateways/adapters/circle_up.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module PaymentGateways
+  class Adapters::CircleUp
+    attr_reader :client
+
+    def initialize
+      @client = ::CircleUp::Client.new
+    end
+
+    def charge_credit_card(params)
+      params => { amount:, details: }
+
+      response = client.charge_cc(amount, details)
+
+      Response.new(response.ok?)
+    end
+  end
+end

data/examples/anti_corruption_layer/lib/payment_gateways/adapters/pay_friend.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module PaymentGateways
+  class Adapters::PayFriend
+    attr_reader :client
+
+    def initialize
+      @client = ::PayFriend::Client.new
+    end
+
+    def charge_credit_card(params)
+      params => { amount:, details: }
+
+      response = client.charge(amount:, payment_data: details, payment_method: 'credit_card')
+
+      Response.new(response.status == 'success')
+    end
+  end
+end

data/examples/anti_corruption_layer/lib/payment_gateways/contract.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module PaymentGateways
+  class Contract < ::BCDD::Contract::Proxy
+    def charge_credit_card(params)
+      params => { amount: Numeric, details: Hash }
+
+      outcome = object.charge_credit_card(params)
+
+      outcome => Response[true | false]
+
+      outcome
+    end
+  end
+end

data/examples/anti_corruption_layer/lib/payment_gateways/response.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PaymentGateways
+  Response = ::Struct.new(:success?)
+end

data/examples/anti_corruption_layer/lib/payment_gateways.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module PaymentGateways
+  require_relative 'payment_gateways/contract'
+  require_relative 'payment_gateways/response'
+
+  module Adapters
+    require_relative 'payment_gateways/adapters/circle_up'
+    require_relative 'payment_gateways/adapters/pay_friend'
+  end
+end

data/examples/anti_corruption_layer/vendor/circle_up/client.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module CircleUp
+  class Client
+    Resp = ::Struct.new(:ok?)
+
+    def charge_cc(_amount, _credit_card_data)
+      Resp.new(true)
+    end
+  end
+end

data/examples/anti_corruption_layer/vendor/pay_friend/client.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module PayFriend
+  class Client
+    APIResponse = ::Struct.new(:status)
+
+    def charge(amount:, payment_method:, payment_data:)
+      APIResponse.new('success')
+    end
+  end
+end