DEV Community: Olorondu Chukwuemeka

Adapter Design Pattern: A Guide to Manage Multiple Third-Party Integrations

Olorondu Chukwuemeka — Thu, 02 Nov 2023 01:07:52 +0000

TABLE OF CONTENTS

Introduction
- Introducing the Adapter Pattern
Managing Multiple Third-Party Integrations
Implementing the Adapter Pattern: A Practical Example
- Defining a common interface
- Creating the Adapter class
- Implement custom logic for switching
Benefits
Challenges and Considerations
Real-World Applications
Conclusion

Introduction

Imagine a hectic day at the office. It's lunchtime, and after spending the first three hours in a lengthy and exhausting meeting, you're eager to order food from your favorite vendor. Instinctively, you navigate to the order history and repeat your previous order from yesterday, as you're not in the mood for a culinary adventure. Upon checkout, you select your saved card and click the familiar "Place Order" button, not waiting to see the outcome because you subconsciously expect your order to be placed without any issues. After 10 minutes, you realize that you haven't received the usual push notification confirming your order. You unlock your phone and see an error banner that reads, "Unable to process payment. Please retry in a few minutes." You can't believe your eyes. You retry a couple of times, but nothing changes. Frustrated, you close the app and download a competitor's app because you refuse to go hungry due to a failed payment.

Believe it or not, scenarios like this are quite common across various technology sectors, including failed payments, unsuccessful email or text message deliveries, and the like. As you can infer from the experience described above, customers don't care about service downtimes from your third-party providers. They simply want the app to work seamlessly when they need to use it. Anything less than that compromises the user experience.

To prevent scenarios like these, a typical approach involves integrating multiple providers that offer the same service. One provider acts as the primary source, while the others serve as backup providers. This setup allows for seamless real-time switching between providers in the event of downtime from one of them.

Ideally, you would want to implement a solution that accomplishes this objective in a scalable and efficient manner. How can we achieve this?

Introducing the Adapter Pattern

The Adapter Pattern is a structural design pattern used in software development to enable the interface of one class to work with another interface that would otherwise be incompatible. It is advantageous when you have existing classes or components with different interfaces that need to cooperate. The Adapter Pattern serves as a bridge between these two interfaces, allowing them to collaborate seamlessly.

Managing Multiple Third-Party Integrations

It's not uncommon for applications to perform specific functions by integrating with third-party systems through APIs and SDKs. However, a drawback of this approach is that the part of the system relying on third-party integration becomes tightly coupled with it. This means that if the third-party system experiences downtime, the corresponding functionality will be unavailable to customers.

One way to mitigate the impact of potential downtimes from third-party providers is to have backup options in the form of multiple integrations for similar features. Nevertheless, managing several third-party providers can be a challenging task.

Implementing the Adapter Pattern: A Practical Example

Consider a hypothetical e-commerce company, TrendyWears , which needs to send emails to its users triggered by various actions such as sign-up, email verification, transactions, and orders. For this example, we can make the following assumptions:

In the past, TrendyWears integrated a single email provider that experienced downtimes during critical business periods (flash sales, Black Friday, New Year, etc.).
Having faced disappointment, they decided to integrate three email providers to seamlessly switch between them in real-time.
The company has an internal service for managing various providers for different functions (messaging, payments, logistics, etc.).

Now, let's see how it all fits together.

In this example, we will be using TypeScript.

Defining a common interface

The first step in implementing the Adapter pattern involves defining a common interface. We can establish a unified Notifications interface, which includes a single sendEmail method for sending emails as follows:

interface Notifications {
    sendEmail(template: string): Promise<string>;
}

The Notifications interface establishes a contract to which the Adapter class adheres.

Creating the Adapter class

Recall that we mentioned earlier that the company TrendyWears integrated three fictitious email providers. To ensure consistency, we can have these email providers adhere to the same contract as follows:

// sample email metadata
interface EmailMetadta {
    first_name: string;
    email_address: string;
}

// mailer contract
interface Mailer {
    mailMessage(template: string, metadata: EmailMetadata): Promise<void>;
    fetchDeliveryLog(): Promise<any>;
}

class EmailClientA implements Mailer {
    async mailMessage(template: string): Promise<void> {
        // external API call to service provider A
    }

    // purely for demonstration purpose
    async fetchDeliveryLog(): Promise<any> {}
}

class EmailClientB implements Mailer {
    async mailMessage(template: string): Promise<void> {
        // external API call to service provider B
    }
}

class EmailClientC implements Mailer {
    async mailMessage(template: string): Promise<void> {
        // external API call to service provider C
    }
}

Next, we create the initial structure of the Adapter class as follows:

class Notificator implements Notifications {
    private mailClientA: EmaiClientA;
    private mailClientB: EmailCLientB;
    private mailClientC: EmailClientC;

    constructor(mailClientA: EmailClientA, mailClientB: EmailClientB, mailClientC: EmailClientC) {
        this.mailClientA = mailClientA;
        this.mailClientB = mailClientB;
        this.mailClientC = mailClientC;
    }

    async sendEmail(template: string, metadata: any): Promise<void> {
        // we'll develop this in a bit
    }
}

Implement custom logic for switching

Next, we will implement custom logic for switching between email clients. To maintain simplicity, we will base our implementation on the following assumptions:

We have a simple retry method for retrying failed attempts, as follows:

        async function retry<T>(maxRetries: number, timeout: string, fn: (attempt: number) => Promise<T>): Promise<T> {
            // custom logic for retry
        }

The method for switching between providers utilizes a straightforward round-robin approach for n consecutive failed email delivery attempts.

We can implement a simple switching logic as follows:

class Notificator implements Notifications {
    private mailClientA: EmaiClientA;
    private mailClientB: EmailCLientB;
    private mailClientC: EmailClientC;

    private providers: string[];
    private currentProvider: string;

    constructor(mailClientA: EmailClientA, mailClientB: EmailClientB, mailClientC: EmailClientC) {
        this.mailClientA = mailClientA;
        this.mailClientB = mailClientB;
        this.mailClientC = mailClientC;

        // simple hard-coded provider queue
        this.providers = ["mailClientA", "mailClientB", "mailClientC"];
        this.currentProvider = providers[0]; // default provider
    }

    async sendEmail(template: string, metadata: any): Promise<string> {
        // these should be stored as env variables
        const maxRetries = 6;
        const timeout = "15ms";

      return retry(maxRetries, timeout, async(attempt) => {
            try {
                return await this[this.currentProvider].mailMessage(template, metadata);
            } catch(error) {
                // switch to next provider in even intervals
                const isEvenAttempt = attempt % 2 === 0;
                if (isEvenAttempt) {
                    this.resetCurrentProvider();
                }

                // trigger retry
                throw error;
            }
        });
    }

    private resetCurrentProvider() {
        this.providers.push(this.providers.shift());    
        this.currentProvider = this.providers[0];
    }

}

From the above example:

We have a queue of providers, which are references to each of the email clients. In a production app, this can be persisted in an in-memory store like Redis.
The currentProvider variable keeps track of the current email client reference, and this variable is reset after every failed event attempt.
The sendEmail method is retried for a maximum of 6 attempts.

The Notificator class effectively serves as a bridge between the sendEmail function and various email clients, while also providing an abstraction for dynamically switching between email clients in real time.

Benefits

As demonstrated in the previous example, the adapter pattern offers several benefits to software systems, some of which include:

Reliability: The system becomes more dependable as it can seamlessly switch between third-party providers, ensuring uninterrupted service even if one provider encounters issues or downtime.
Separation of Concerns: The Adapter pattern aids in maintaining a clear separation of concerns. Other components of the system that rely on the feature interface don't need to be aware of the intricacies of individual third-party integrations. Instead, they interact with the feature through a common interface, making the system more modular and maintainable.
Service-Level Agreements (SLAs): Businesses can more effectively meet their service-level agreements (SLAs) with customers, as the Adapter pattern allows them to adapt to changing conditions and ensure that commitments are fulfilled.

Challenges and Considerations

While the Adapter pattern offers numerous benefits, managing multiple third-party integrations and their respective implementations can become increasingly challenging.

As with any decision in software engineering, trade-offs must be made between managing these integrations within a service class inside the system or creating a dedicated integration service for this purpose, while considering the additional costs involved. The choice depends on the number of integrations and the specific needs of the business.

Adapting this concept to our hypothetical TrendyWears company, we could create a separate trendywears-integrations service whose sole responsibility is managing multiple integrations for the company, spanning various domains such as messaging (email and/or push notifications), payments, logistics, and more. For the messaging integrations mentioned in our example, we could expose functionalities as APIs, allowing other services within the system (such as orders, payments, etc.) to interact with them. These include:

A sendEmail API for sending emails: Services interacting with this API remain unaware of the providers being used.
A getCurrentProvider API: This could be helpful for client-facing applications (web/mobile) to determine the appropriate SDKs and implement routing logic.
A resetProvider API for resetting the current provider: Typically, this is called after n consecutive failed attempts.

Real-World Applications

The Adapter pattern has several real-world applications related to managing multiple third-party integrations, some of which include:

Messaging (email and/or push notifications)
Cloud services (switching between multiple cloud providers, cloud storage, etc.)
Payments (supporting multiple payment providers)
API versioning

Conclusion

The power of the Adapter Pattern lies in its ability to enhance system reliability, separate concerns among components, and adapt to changing conditions. It is a tool that empowers businesses to meet their commitments, even in the face of a dynamic and uncertain technological landscape. By understanding and effectively applying the Adapter Pattern, software engineers can unlock new dimensions of robustness and flexibility in their systems, ultimately delivering a more reliable and adaptable experience to users and businesses.

How to setup an automated testing pipeline with Codecov and GitHub Actions.

Olorondu Chukwuemeka — Sun, 26 Sep 2021 16:36:01 +0000

Outline

Scope of the tutorial
Introduction
Prerequisites (optional)
Code coverage with Codecov
Project Setup
Codecov & GitHub Actions
Codecov in action
Metadata (badges)
Conclusion
Helpful links

Scope of the tutorial

This tutorial teaches how to integrate unit testing into a development workflow with Github Actions & Codecov.

Non-scope: This tutorial does not teach about unit testing with PHP.

Introduction

Unit testing in software engineering is a development practice in which individual components (functions, modules, classes, etc) of a software system are tested independently as single units to validate that they function as they're intended to by the software engineer. This practice is very important because it safeguards the software against future breaking changes by acting as an "alerting system" of some sort that notifies the software engineers involved, once the tests are executed. Usually, unit testing is combined with other forms of automated testing such as integration testing, acceptance testing, etc.

Automated testing, in general, is very important, but it's also crucial that tests are written to account for all (or most) possible edge cases that exist. Hence, we are faced with an important question: how do we measure this metric?

In this tutorial, we will learn about code coverage and how to set up an automated testing pipeline with Codecov & GitHub Actions, using PHP for demonstration.

Prerequisites (optional)

The following prerequisites are optional and not required to understand this tutorial:

Knowledge of PHP and automated testing with PHPUnit.
PHP, MySQL & XDebug installed locally.
Composer installed locally.

Code coverage with Codecov

Code coverage in software engineering is an automated testing metric that measures the percentage of lines of code that are covered by the written tests. This gives an insight into the extent to which your codebase is tested. Code coverage is usually determined by a number of criteria such as function coverage, edge coverage, statement coverage, and the likes (helpful link at the end of this tutorial).

Codecov is a tool that helps to measure code coverage and automatically generates reports based on the result obtained. It comes with features that help to enforce a minimum code coverage percentage in your project and can be integrated with a number of Continuous Integration (CI) tools.

In the sections below, we would learn how to set up Codecov in a software development project using GitHub Actions as our CI tool.

Project setup

The sample project is a simple API built with vanilla PHP and is framework agnostic. Clone the project from this repo and follow the guidelines detailed in the Readme file for the local development setup.

The structure of the project is as shown below:

php_crud_app
├─ .env
├─ .github
│  ├─ PULL_REQUEST_TEMPLATE.md
│  └─ workflows
│     └─ test.yml
├─ .gitignore
├─ api
│  ├─ AlternativeUserRepository.php
│  ├─ DbConnection.php
│  ├─ UserController.php
│  └─ UserRepository.php
├─ bootstrap.php
├─ codecov.yml
├─ composer.json
├─ composer.lock
├─ envLoader.php
├─ phpunit.xml
├─ public
│  └─ index.php
├─ README.md
├─ setup.sql
└─ tests
   └─ Feature
      └─ UserTest.php

Codecov & GitHub Actions

In order to setup Codecov with GitHub Actions, the following secret tokens are required:

GitHub Personal Access Token (PAT): This is a secret token unique to every GitHub account, which allows its owners to perform actions that require authentication such as repository-actions (clone, push & pull), setting up C pipelines with GitHub Actions, etc.
Codecov token: This is required for granting GitHub Actions access to upload the coverage metrics to Codecov.

Creating a GitHub PAT

To create a personal access token for GitHub, follow the steps below:

Step 1: Login to your GitHub account and click on "settings"

Step 2: Click on Developer settings

Step 3: Click on Personal access tokens

Step 4: If you haven't created a PAT before, click on 'Create token'. Else, choose an existing PAT and click on "Edit token".

Step 5: Select the checkbox labeled "workflows" and click on "Update token"

That's it. Ensure you save the PAT in a secure location and do not expose it to anyone.
Next, we will set up Codecov.

Setting up Codecov for the project

In order to setup Codecov for the project, follow the steps below:

Step 1: Log in to Codecov with your GitHub account.

Step 2: On the Codecov tab, click on "Analytics" and click on "Add new repository"

Step 3: Scroll down to the repo of your choice and click on "setup repo"

Step 4: Copy the "Upload token" and keep it safe. We would use it soon.

Creating repo secrets

We need to save the GitHub PAT and Codecov token earlier generated as repo secrets in order for GitHub Actions to have access to it.

To create a new secret for the repo, follow the steps below:

Step 1: Navigate to the target repo on GitHub and click on the Settings tab

Step 2: Click on "New repository secret"

Step 3: Name the GitHub PAT as "MY_PAT", paste its value, and click on "Add secret" to save. Follow the same steps for "CODECOV_TOKEN".

Setting up an automated testing pipeline with GitHub Actions

Now that we've successfully generated the required PAT and Codecov tokens, we can set up the testing pipeline.

In the root of your project folder, create the directory: .github/workflows. Next, create a file in the workflows directory called test.yml. Copy the contents below and paste them into the file:

name: Test Suite
on: [push]

jobs:
  test:
    runs-on: ubuntu-18.04
    steps:
      - name: Checkout to code repo
        uses: actions/checkout@v2
        with:
          token: ${{ secrets.MY_PAT }}

      - name: Setup PHP with Xdebug
        uses: shivammathur/setup-php@v2
        with:
          php-version: "7.4"
          coverage: xdebug

      - name: Update dependencies in lock file
        run: composer update

      - name: Install dependencies
        run: composer install

      - name: Run tests
        run: composer test

      - name: Upload Code Coverage to Codecov
        uses: codecov/codecov-action@v2
        with:
          token: ${{ secrets.CODECOV_TOKEN }}
          file: ./coverage.xml
          flags: unit_tests
          name: codecov-umbrella
          fail_ci_if_error: true
          verbose: true

Let's try to break down critical aspects of the test.yml file:

on "push": This line instructs GitHub Action to run every time a commit is pushed to the repo
Setup PHP with XDebug: This section installs PHP with XDebug, which is a PHP extension that is critical to generating the coverage report file labeled "coverage.xml". For projects written in other programming languages, this section of the CI pipeline is usually where necessary setup for running the unit tests is done.
Run tests: This is the section in which the command required for running unit tests is inserted.
Upload Code Coverage to Codecov: This section uploads the coverage report to Codecov, which is generated after running unit tests.

Codecov config file

The Codecov config file controls critical aspects of Codecov features to be applied in your project, which is available through the Codecov bot.

In your project's root directory, create a file called codecov.yml and past the content below:

comment:
  layout: "reach, diff, flags, files"
  behavior: default
  require_changes: false
  require_base: no
  require_head: yes

coverage:
  range: "70..100"
  round: down
  precision: 2
  status:
    project:
      default:
        # basic
        target: 60%
        threshold: 0%
        # advanced settings
        if_ci_failed: error
        informational: false
        only_pulls: false

This config file controls important features such as pull request comment, target coverage percentage amongst others. For a more detailed understanding of this file, check out the official documentation.

Codecov in action.

For every pull request made, the GitHub Actions pipeline runs for every commit pushed to the repo, and a coverage report is commented by the Codecov bot, as shown below:

The pipeline is currently failing because the overall code coverage for the project is 0.00%, and we set the minimum code coverage to be 60%, from the codecov.yml file. This is a result of the lack of adequate tests in the project.

Once adequate unit tests have been added to the project, and the minimum code coverage percentage is met, the pipeline passes as demonstrated below:

This is how the summary looks like on the Codecov dashboard:

With that, we've successfully set up the unit testing pipeline for a project.

Metadata (badges)

Displaying badges on your project's Readme is a good way to track metrics (code coverage, CI status) at a glance.
Let's add badges for Codecov and GitHub Actions.

Codecov badge

To add a Codecov badge, visit the link: https://codecov.io/gh/<your-organisation>/<your-project>/settings/badge.

As an example, for the sample project in this tutorial, the link will be: https://codecov.io/gh/olorondu-emeka/php_crud_app/settings/badge.

Copy the markdown link and paste it into your Readme file.

GitHub Actions badge

Toadd a badge for GitHub Actions, follow this template: ![pipeline-name](https://github.com/<your-organisation>/<your-project>/actions/workflows/<pipeline-file>/badge.svg).

For example, the link for the GitHub badge for this project is:
![Github Actions](https://github.com/olorondu-emeka/php_crud_app/actions/workflows/test.yml/badge.svg).

The final result on the ReadMe file is as shown below:

Conclusion

So far, we've seen the importance of unit testing. Using a continuous integration tool (such as GitHub Actions) and Codecov is definitely an important step in ensuring code quality in any project, as the process is fully automated and feedback via metrics(badges and codecov comment) is displayed for every commit made.

DEV Community: Olorondu Chukwuemeka

Adapter Design Pattern: A Guide to Manage Multiple Third-Party Integrations

Introduction

Introducing the Adapter Pattern

Managing Multiple Third-Party Integrations

Implementing the Adapter Pattern: A Practical Example

Defining a common interface

Creating the Adapter class

Implement custom logic for switching

Benefits

Challenges and Considerations

Real-World Applications

Conclusion

How to setup an automated testing pipeline with Codecov and GitHub Actions.

Outline

Scope of the tutorial

Introduction

Prerequisites (optional)

Code coverage with Codecov

Project setup

Codecov & GitHub Actions

Creating a GitHub PAT

Setting up Codecov for the project

Creating repo secrets

Setting up an automated testing pipeline with GitHub Actions

Codecov config file

Codecov in action.

Metadata (badges)

Codecov badge

GitHub Actions badge

Conclusion

Helpful Links