Anti-Corruption Layers Are Good

??? words · ??? min read

This is a work in progress from The Pipeline. It will likely change before it is published to the main listing of articles. It is currently at the "detailed" stage.

TODO: intro

What Is An Anti-Corruption Layer?

Anti-corruption layers are a design pattern for integrating external systems, in a nice, structured way. The term comes from the Domain Driven Design (DDD) community, but it is similar to the concept of “ports and adapters” or “hexagonal architecture,” which might be more familiar to the Ruby community.

The idea is to completely encapsulate all of the implementation details of the integration, underneath a simplified application-specific interface. All interactions with the external system are done through this interface, instead of being spread across the whole application in a haphazard way.

Anti-corruption layers make good use of OOP buzzwords like encapsulation, polymorphism, and duck typing. These concepts have a tendency to be overused and misapplied in inappropriate situations, but this is a situation where they can provide tangible benefits.

Example Implementation

For this article, we’ll be using DNS hosting as an example of an external system. Let’s say our app allows users to choose their own subdomain, like fred.example.com. To implement this, we need to add a DNS record to our example.com domain for each subdomain. Let’s also say that our domain is hosted on Cloudflare, so we will need to use their API.

Our anti-corruption layer would look something like this:

class CloudflareDNSProvider
  BASE_URL = "https://api.cloudflare.com/client/v4"

  attr_reader :zone, :auth_key

  # configuration is passed in through #initialize
  def initialize(zone:, auth_key:)
    @zone = zone
    @auth_key = auth_key
  end

  # this is the interface that the application uses
  def create_subdomain(subdomain)
    response = HTTP
      .headers('X-Auth-User-Service-Key' => auth_key)
      .accept(:json)
      .post("#{BASE_URL}/zones/#{zone}/dns_records", json: {
        type: 'CNAME',
        name: "#{subdomain}.example.com.",
        content: 'www.example.com.',
      })

    body = response.body.parse

    # the return value is a result object
    if body.fetch('success')
      Resonad.Success
    else
      Resonad.Failure(error_message(body))
    end
  end

  private

    def error_message(body)
      body.fetch('errors').map do |error|
        "Error #{error.fetch('code')}: #{error.fetch('message')}"
      end.join('. ')
    end
end

This object is usually created when the app boots up. There are a few places this could happen, here is one simple approach for Rails apps:

# config/environments/production.rb

DNS_PROVIDER = CloudflareDNSProvider.new(
  zone: ENV.fetch('CLOUDFLARE_ZONE'),
  auth_key: ENV.fetch('CLOUDFLARE_AUTH_KEY'),
)

Then the constant can be used from anywhere within the app.

class UsersController < ApplicationController
  def create
    #...
    result = DNS_PROVIDER.create_subdomain(user.slug)
    if result.ok?
      render json: { success: true }
    else
      render json: { error: result.error }, status: 422
    end
  end
end

Lastly, we will want a stub provider, which implements the same interface, with extra methods to help out during testing.

class StubDNSProvider
  def initialize
    @created_subdomains = []
    @always_fail_message = nil
  end

  # this is the same interface as CloudflareDNSProvider
  def create_subdomain(subdomain)
    if @always_fail_message
      return Resonad.Failure(@always_fail_message)
    end

    if @created_subdomains.include?(subdomain)
      Resonad.Failure("Error 1234: Subdomain already exists")
    else
      @created_subdomains << subdomain
      Resonad.Success
    end
  end

  # this method is used to test our apps logic
  def has_created_subdomain?(subdomain)
    @create_subdomains.include?(subdomain)
  end

  # this method is used to test the failure cases of our app
  def always_fail!(message)
    @always_fail_message = message
  end
end

The stub provider takes the place of the real provider during testing.

RSpec.describe "Creating a user" do
  before { stub_const('DNS_PROVIDER', dns_provider) }
  let(:dns_provider) { StubDNSProvider.new }

  it "creates a subdomain" do
    post "/users", name: "Marge Simpson"

    # nice, descriptive expectations
    expect(dns_provider).to have_created_subdomain('marge-simpson')
  end

  it "handles failure gracefully" do
    # force the stub to return a failure
    dns_provider.always_fail!("Monorail!")

    post "/users", name: "Maggie Simpson"

    expect(last_response.status).to eq(422)
    expect(JSON.parse(last_response.body)).to eq({
      error: "Monorail!",
    })
  end
end