Forem: Vlad Hilko

Introduction to Rails API: How to Create Your First Endpoint in Less Than a Minute?

Vlad Hilko — Tue, 29 Aug 2023 21:53:19 +0000

Overview

This is the first article in the Clean Rails API series. In this piece, we will provide a brief introduction to Rails API. We'll discuss what it is, how it looks, its key components, and share simple examples. We'll also demonstrate how request specs can be added. Furthermore, we'll provide a direction for API evolution and highlight the problems that have to be solved in the future to provide a high-quality solution.

Introduction

API (Application Programming Interface) is a set of rules and protocols that allow one application to interact with another application. There are several API paradigms that fall into two main categories: Request–Response APIs and Event-Driven APIs:

Request–Response APIs
- REST API (Representational State Transfer)
- RPC (Remote Procedure Call)
- GraphQL
Event-Driven APIs
- Polling
- WebHooks
- WebSockets
- HTTP Streaming

In the context of this introduction to Rails API, we will be working with REST API. The name REST ("Representational State Transfer") encapsulates the essence of this architectural style: representing resources and their states and transferring data between clients and servers using HTTP.

Implementation

Let's review our plan for the Rails API introduction. We'll begin with the Primitive Implementation. Following that, we will add several CRUD Endpoints and cover them using RSpec Request Tests. Finally, we will highlight areas for Improvements that we'll consider in the next article of this series.

Primitive Implementation

At this part, we're going to add a very simple endpoint just to demonstrate how the API may look. We'll add this endpoint to the existing Rails application, but if you want to start from scratch, just create a new app with the rails new api_sample --api command. We will start by providing the Desired Interface, then we will add the Implementation, and after that, check that everything works as expected.

Desired Interface

First of all, let's decide how our interface should look like and what data we expect to receive. Let's assume that we want to send a GET request to http://localhost:3000/api/hello-world and expect to receive the following response:



// Status: 200 OK

{
  "data": "Hello World!"
}

Implementation

To add such an API endpoint, we have to follow two simple steps:

Create a new controller and method that will return "data": "Hello World!" in JSON format.
Add a new route to bind our HTTP request to the created controller method.

To implement the first step, we will add a new HelloWorldController with a hello_world method inside:



# app/controllers/api/hello_world_controller.rb

# frozen_string_literal: true

module Api
  class HelloWorldController < ApplicationController

    def hello_world
      render json: { data: 'Hello World!' }
    end

  end
end

To implement the second step, we will add get 'api/hello-world' to config/routes.rb, which will bind the HTTP request and the controller method.



# config/routes.rb

# frozen_string_literal: true

Rails.application.routes.draw do
  get 'api/hello-world', action: :hello_world, controller: 'api/hello_world'
end

Verify Functionality

After completing our implementation, we can run the server and check its functionality:



rails s

When you open your browser and visit http://localhost:3000/api/hello-world, you should see the following:



// Status: 200 OK

{
  "data": "Hello World!"
}

That's it! The simplest API has been added. In the next chapter, we will try to add more HTTP requests to cover CRUD actions.

Adding CRUD Endpoints

In this chapter, we are going to add new API endpoints for CRUD HTTP requests. We'll strive to keep everything as simple as possible, focusing solely on the core components. We will begin by defining the Desired Interface, then proceed with the Implementation, and finally, we'll verify that everything works as expected and cover all endpoints with Request Specs.

Desired Interface

We've demonstrated how to create the simplest API in the Hello World example. Let's go further and create more endpoints with different HTTP methods. I'd like to have the following 4 endpoints and expect them to return the following data:

GET http://localhost:3000/api/countries



// Status: 200 OK

[
  {
    "id": 1,
    "name": "Spain"
  }
]

POST http://localhost:3000/api/countries



// Status: 201 Created

{
    "id": 1,
    "name": "Spain"
}

PUT http://localhost:3000/api/countries



// Status: 204 No Content

DELETE http://localhost:3000/api/countries/1



// Status: 204 No Content

Implementation

To add these 4 endpoints, we will need to follow the same 2 steps as in the previous part, plus one improvement. Let's start with the improvement. In our enhancement, we want to create a new wrapper class that we will use as the parent class for all our API controllers. This new class will look like this:



# app/controllers/api/application_controller.rb

# frozen_string_literal: true

module Api
  class ApplicationController < ActionController::API
  end
end

Then, instead of inheriting from the ApplicationController class, we'll have all API controllers inherit from Api::ApplicationController. This change will provide us with more flexibility and reduce the risk of breaking non-API controllers if we have any.



# app/controllers/api/hello_world_controller.rb

# frozen_string_literal: true

module Api
  class HelloWorldController < Api::ApplicationController

    def hello_world
      render json: { data: 'Hello World!' }
    end

  end
end

Now let's create a new controller with 4 methods to handle all the requests mentioned above:



# app/controllers/api/countries_controller.rb

# frozen_string_literal: true

module Api
  class CountriesController < Api::ApplicationController

    def index
      render json: [ { id: 1, name: 'Spain' } ]
    end

    def create
      render json: { id: 1, name: 'Spain' }, status: :created
    end

    def update
      head :no_content
    end

    def destroy
      head :no_content
    end

  end
end

And update the routes.rb file to bind HTTP requests and controller methods:



# frozen_string_literal: true

Rails.application.routes.draw do
  get 'api/countries', action: :index, controller: 'api/countries'
  post 'api/countries', action: :create, controller: 'api/countries'
  put 'api/countries', action: :update, controller: 'api/countries'
  delete 'api/countries', action: :destroy, controller: 'api/countries'
end

Verify Functionality

After everything has been implemented, let's check if it works:

GET http://localhost:3000/api/countries



// Status: 200 OK

[
  {
    "id": 1,
    "name": "Spain"
  }
]

The first one works as expected, and we know how to check it in the browser, but what about the others? How can we send different HTTP requests? To solve this problem, we're going to use Postman. Postman is like an extended browser version that can send any HTTP request based on your instructions. Postman looks like this:

Let's check our other HTTP requests:

POST http://localhost:3000/api/countries



// Status: 201 Created

{
    "id": 1,
    "name": "Spain"
}

PUT http://localhost:3000/api/countries



// Status: 204 No Content

DELETE http://localhost:3000/api/countries



// Status: 204 No Content

As you can see, everything works as expected.

Adding Request Tests

After all requests have been added, we need to cover them using request specs to ensure that everything will work as expected in the future as well. To add specs, we will use the rspec-rails gem. Our plan is to cover the 4 HTTP request methods that have been added above:

GET http://localhost:3000/api/countries



# spec/requests/countries/list_spec.rb

# frozen_string_literal: true

require 'rails_helper'

RSpec.describe 'Listing Countries' do
  subject(:send_request) { get request_uri }

  let(:request_uri) { '/api/countries' }

  it 'lists all countries' do
    send_request

    expect(response).to have_http_status(:successful)
    expect(JSON.parse(response.body)).to eq([{ 'id' => 1, 'name' => 'Spain' }])
  end
end

POST http://localhost:3000/api/countries



# spec/requests/countries/create_spec.rb 

# frozen_string_literal: true

require 'rails_helper'

RSpec.describe 'Creating Countries' do
  subject(:send_request) { post request_uri }

  let(:request_uri) { '/api/countries' }

  it 'creates a country and returns it' do
    send_request

    expect(response).to have_http_status(:created)
    expect(JSON.parse(response.body)).to eq({ 'id' => 1, 'name' => 'Spain' })
  end
end

PUT http://localhost:3000/api/countries



# spec/requests/countries/update_spec.rb

# frozen_string_literal: true

require 'rails_helper'

RSpec.describe 'Updating Countries' do
  subject(:send_request) { put request_uri }

  let(:request_uri) { '/api/countries' }

  it 'updates the country and returns nothing' do
    send_request

    expect(response).to have_http_status(:no_content)
    expect(response.body).to be_empty
  end
end

DELETE http://localhost:3000/api/countries



# spec/requests/countries/destroy_spec.rb 

# frozen_string_literal: true

require 'rails_helper'

RSpec.describe 'Destroying Countries' do
  subject(:send_request) { delete request_uri }

  let(:request_uri) { '/api/countries' }

  it 'deletes the country and returns nothing' do
    send_request

    expect(response).to have_http_status(:no_content)
    expect(response.body).to be_empty
  end
end

That's it. You can run rspec spec/requests to ensure that they work.

Improvements

We have demonstrated the simplest examples, but there's room for many improvements. I would consider at least the following points:

Update Routing
Add Representers/Serializers
Add logic to Create/Update/Delete resources
Add Error Handling
Add Request Tests/RSwag Documentation
Apply Authorization/Authentication rules
Support URL queries (limits/pagination/filtering)
Set up Middleware (Rate Limits/CORS/etc...)
Add API Versioning

Conclusion

To sum it up, this article is the beginning of our Clean Rails API series. We've talked about what Rails API is, shown some examples, and explained how to test it. In the future, we will improve our solution by addressing each improvement point one by one.

How to Conduct High-Quality Code Review?

Vlad Hilko — Sat, 26 Aug 2023 10:28:27 +0000

Overview

In this article, we are going to declare the structure of a code review process that will help you build a product with better code quality in less time. We will begin by explaining the main reasons for code reviews and the benefits they can provide to your team. Next, we will identify the key participants in code reviews, their responsibilities, and the workflow. After that, we will delve into a detailed discussion of the plans for the organization, code authors, and reviewers that will help them get the most out of code reviews and achieve excellent results.

Why do we need code review?

Code review is a process where someone other than the author(s) of a piece of code examines that code. It is mostly used for the following reasons:

Minimizing mistakes and their impacts:

This includes making sure bugs and defects are prevented as much as possible and that the source code is of high quality.

Maintaining norms:

This involves ensuring that there are adequate tests, consistency in style, design, and implementation.

Meeting requirements:

Based on Acceptance Criteria.

Improving code quality/performance/security.
Learning and sharing:

Both domain and coding knowledge.

Tracing and tracking decisions:

Understanding the evolution of the code and why and how changes have happened.

Gatekeeping:

Ensuring security and having an additional safety net so that a single developer cannot commit arbitrary code.

Finding Alternative Solutions.

Structure Overview

Actors

First of all, let's define the main actors of code review. I would choose the following:

Organization
Code Author
Core Reviewer

Responsibilities

Let's define their responsibilities:

Organization

The organization's responsibility is to simplify life for Code Authors and Reviewers by defining rules and processes. Every question related to the code review process should have answers provided by the organization. Here are examples of questions that can be raised and should have answers:

How to encourage team members to participate in code reviews?
How to resolve conflicts?
How to determine when a review is complete and it's okay to approve?
How to encourage team members to follow the process?
What to do if you have a strict deadline or need to merge a critical bug fix as soon as possible?
How to respond when someone says 'No' during the review?
Who will perform code reviews?
How often should code reviews take place?
Who is responsible for assigning tickets/code reviews to relevant engineers?
What should you do if no one wants to review your PR?
etc.

Code Author

The Code Author's main responsibility is to implement a high-quality solution and to simplify the life of the reviewer as much as possible.

Code Reviewer

The Code Reviewer's main responsibility is to double-check the author's work and identify improvements that the author may not have noticed.

Flows

Let's define the flow for each of them:

Organization

The Organization should create a document with answers to all possible questions that may arise and ensure that teams adhere to the established rules.

Code Author

There are 5 points that every Code Author should follow:

Create a Pull Request (PR) and describe the changes to provide more context for reviewers.
Perform a self-check and review your code before submitting it.
Find the best reviewer.
Collaborate with the Reviewer to resolve all issues and obtain approval.
Follow the organization's process to merge the changes.

Code Reviewer

There are 5 points that every Code Reviewer should check before giving approval:

Ensure that the code follows business requirements.
Ensure that complexity has been reduced.
Ensure that the design is good.
Ensure that reliability is at the appropriate level.
Check that the code doesn't have any hidden risks.

In addition, the reviewer should know how to collaborate with the author to resolve all issues.

Let's discuss these responsibilities and flows for each actor more precisely.

The Standard of Code Review

Organization-Wide Practices

During code reviews, many issues can arise, and we need to know how to handle them. To address these problems and ensure that everyone is on the same page and at the same position, the organization should create a document outlining engineering practices and rules to document and standardize the code review process. This document should cover the following main points:

Ensure that the purpose of code reviews is clear to everyone.
Ensure that the "Definition of Done" is documented and clear to everyone.

This is an essential point because we need to establish boundaries. We can't attain perfection, so we need to define minimum rules required for a PR to be considered good enough. For example, the following criteria could be considered:

Test coverage is sufficient and correct; all border cases are covered.

CI is green, and all tests have passed.

Rubocop and other style linters have passed.

Etc.

Encourage team members to actively participate in code reviews.
Define a process for conflict resolution during code reviews.

P.S. You can read Google's process for conflict resolution here: Resolving Conflicts.

Set clear expectations for code review turnaround times.
Prioritize code reviews as an essential task.
Leverage code reviews as opportunities for knowledge sharing and learning.
Encourage reviewing code in unfamiliar areas to promote cross-functional knowledge.
Continuously monitor and improve the code review process.
Recognize and reward those with a track record of providing quality feedback.
Conduct regular code review sessions to discuss broader trends or issues that arise during the review process.
Encourage authors to seek feedback during development before submitting a formal code review.
Ensure that you have proper processes in place to speed up reviews.

P.S. Learn more about how Google accelerates reviews here: Fast Review.

Determine how to handle emergencies

P.S. Learn more about how Google handles emergencies here: Emergencies.

Here's the full document from the Google team outlining their practices: Google Engineering Practices Documentation.

Code Author

Your goal as an author of code seeking review is to simplify the reviewer's life as much as possible. You are the one in need of the review and who should receive the review, not the reviewer who wishes to spend their time reviewing your code. Therefore, ensure that you do not compel them to perform tasks that you could handle yourself.

There are 5 steps that every Code Author should follow:

Create a Pull Request (PR) and describe the changes to provide more context for reviewers.
Perform a self-check and review your code before submitting it.
Find the best reviewer.
Collaborate with the Reviewer to resolve all issues and obtain approval.
Follow the organization's process to merge the changes.

Providing Context for Reviewers

Ensure that you include a proper title, description, any screenshots, relevant links, configuration changes, etc., in the PR.

P.S. You can read Google's requirements for the description here: Google PR Description Guidelines.

Make sure to add a very clear reason for why you're making these changes

Achieving code perfection is challenging because every code change introduces a risk of breaking something. Without code, there's no risk. Therefore, it's crucial to ensure that there are no alternative solutions to the problem. If you only describe the code changes without providing the reason, you're depriving the reviewer of the opportunity to suggest a completely different solution to the problem. While the reason may be clear to you, keep in mind that reviewers may not have your context, so it's essential to add it.

Even if you and your reviewers currently understand the reason, consider adding it for historical purposes. In a few years, you may forget the initial rationale, making it much harder to replace or refactor the solution. For example, if someone later introduces a new global solution that could solve the problem more efficiently, they might struggle to replace the code because they expected your code to perform additional functions.

Take notes on any questions or concerns about the change to discuss them during the review.
Identify any potential performance, security, or scalability concerns and note them for discussion during the review.
Avoid attempting to sneak something past reviewers; highlight questionable elements instead.
Consider the impact of the change on other parts of the system and express your concerns to others.
Provide context for your design choices by explaining why you chose a particular approach.
If there are any alternative solutions that were considered and why they were not chosen, briefly mention them.

Self-Check: Review Your Code Before Submitting

Before submitting a PR, thoroughly test your changes locally to identify and address any obvious issues.
Write automated/unit tests to validate the functionality.
Double-check for spelling mistakes.
Perform code cleanup, removing comments, todos, and unnecessary artifacts.
Confirm that the code passes all tests, including unit, integration, and system tests.
Review the code to ensure it aligns with the project's coding standards, team guidelines, and best practices.
Maintain consistency with the overall project design and architecture.
Write or update documentation for the changes if required.
Keep your code changes concise and focused. Avoid overwhelming reviewers with extensive code in a single review session.

It has been proven that we get more value from code reviews when the PR is smaller rather than big. If you are struggling to keep them small, try pairing with a teammate (or engineers from other teams).

P.S. You can read about why Google prefers to keep PRs small here: Google Engineering Practices.

Finding the Best Reviewer

Who to Choose:
- Someone capable of responding to your review within a reasonable period of time.
- Someone who can provide the most thorough and accurate review for the piece of code you are writing.
- Look for reviewers who have expertise in the domain or specific functionality related to your code changes.
- Reviewers who have been involved in previous discussions or decisions related to the code you are changing may have valuable historical context.
Tools to find:
- Check the codeowners file.
- Use git blame to identify potential reviewers.
- Document which teams are responsible for specific areas to facilitate reviewer selection.

Collaboration

Approach the review process with an open mind and be willing to learn from and collaborate with other team members.
Address all the feedback received, including any concerns or questions raised.
Don't dismiss or resolve a comment without explanation. Every comment is valid; as a code author, even if you feel the comment isn't relevant, please address it so the reviewer can understand the context and why you've done something in a certain way.
Seek feedback from other team members if you are unsure about the changes.
If you're unsure about a review comment or suggestion, don't hesitate to ask for clarification.
Don't take it personally. It's the code under review, not you.
View each review as a chance to learn and grow as a developer. Embrace feedback as a path to improvement.
Be open to new suggested approaches, even if you consider them not too important; it's a good opportunity to learn a new way of doing things.
Do not make every change that is suggested if you still believe your approach is better. Have a conversation and agree with the reviewer if possible.
Treat everyone's opinion the same, regardless of seniority. Ensure you don't apply a change if someone senior told you to do so without understanding the reasons.
Take ownership of your code and its quality. Be accountable for the changes you make.
Ensure that all code review discussions, comments, and decisions are documented within the code review platform. This creates a historical record and helps other team members understand the rationale behind the code changes.
Create a positive and collaborative atmosphere by expressing your gratitude to the reviewer

Good: 'Thank you!'

Good: 'Nice catch!'

Good: 'Thanks for pointing that out'

Good: 'Thanks for taking the time to review'

After Review

Express Gratitude

Code reviews are, in large part, about having others watch your back. Don't hesitate to express your gratitude with a simple "Thank you" once the review is completed. If you're new to code reviews, take a moment to reflect on what went well and what didn't.

Approval Checks:
- Ensure that you have received enough approvals for your code changes.
- If you've made changes to unfamiliar areas, ensure you've received approval from the code owner.
Testing and QA:
- Ensure that your ticket will be tested by Quality Assurance (QA).
- Provide clear and comprehensive descriptions of all places you've modified in the ticket description.
Continuous Integration (CI):
- Verify that the CI pipeline has successfully passed for your code changes.
- Confirm that the main branch's CI pipeline is not failing.
Confirm that it's an appropriate time to merge your changes:
- Not too late or too early to ensure support if issues arise.
- Not during holidays
- Ensure that you do not merge code during the process of fixing critical issues to avoid additional problems.
Merge the approved code changes into the main branch.
Post-Merge Checks:
- Ensure that the main branch's CI pipeline remains green after merging your changes.
- Verify that the code changes are functioning as expected in the production environment.
- Keep an eye on monitoring tools to promptly address any issues that may arise due to your code changes.
- Review and update documentation, such as README files, API documentation, or user guides, to reflect any changes made in the code.
Celebrate

Reviewer

The main goal and priority of a review are:

Reduce the risk of breaking existing logic and introducing new bugs.
Avoid complicating the lives of other programmers in the future.

We can split the reviewer's task into two parts:

Hard Skills (What Do Code Reviewers Look For?):
- Meeting business requirements (based on Acceptance Criteria)
- Reduce Complexity(Style, Consistency, Readability)
- Improve Design (Maintainability/Testability/Stability/Reusability)
- Improve Reliability (Performance/Security)
- Mitigate Risks
Soft Skills (How should Code Reviewers behave to address the problems they find?):
- Collaboration
- Respectful Comments

So, if your code doesn't break anything and simplifies the lives of other developers, it's okay to approve it. Below, we will discuss the main points on how to achieve this.

Hard Skills (What Do Code Reviewers Look For?)

Code reviewers should consider the following points:

Meeting business requirements
Reduce Complexity
Improve Design
Improve Reliability
Mitigate Risks

Meeting business requirements

If the author hasn't implemented what should be done according to the business requirements, then all other reviews will be a waste of time. So, your priority here is to identify this issue as soon as possible.

Review any documentation or design specifications related to the change (JIRA story, design document, etc.) and compare them with the author's description of the changes.
Based on the requirements, prepare a list of items that should have been covered in the changes.
Review Functionality Based on Acceptance Criteria
- Do we really need it? Does the change make sense? Does it have a good description?
- What problem do we want to solve?
- Is the business logic correct?
- Are the Acceptance Criteria satisfied?
- Are there any potential edge cases or scenarios not covered by the acceptance criteria that should be considered?
- Does the code behave as the author likely intended?
Review Usability and User Experience
- Are error messages clear and user-friendly?
- Does the UI gracefully handle unexpected errors or input?
- Does the UI support multiple languages and locales?
- Does the UI provide a good user experience on mobile devices?

Reduce Complexity

If you can't understand the code, it's very likely that other developers won't either. So you're also helping future developers understand this code when you ask the developer to clarify it.

"Too complex" usually means "can't be understood quickly by code readers." It can also mean "developers are likely to introduce bugs when they try to call or modify this code."

Complexity
- Could the code be made simpler?
- Can the solution be simplified?
- Does similar functionality already exist in the codebase? If yes, why isn’t it reused?
- Is the PR more complex than it should be? Could it be split into parts?
- Could some parts be moved to another ticket?
- Are there redundant or outdated comments? Is there any commented-out code?
- Is the developer not implementing things they might need in the future but don't need now?
Readability
- Would another developer be able to easily understand and use this code when they come across it in the future?
- Does your code tell the story clearly? Or does it clearly explain the business flow?
- Did the developer choose clear names for variables, classes, methods, etc.?
- Are there excessive abbreviations or cryptic variable names that could be made more descriptive?
Style
- Does the code follow the company-defined style guides?
- Is code formatting consistent, including indentation, spacing, and line breaks?
Consistency
- Is there a consistent approach to coding within your company's rules?
- Does the code change adhere to the project's coding standards and best practices?
- Are naming conventions consistent with the project's coding standards?

Improve Design

In fact, reviewing the rest of the PR might be a waste of time because if the design problems are significant enough, a lot of the other code under review is going to disappear and not matter anyway.

Design
- Is the code well-designed and appropriate for your system?
- Are there any best practices, design patterns, or language-specific patterns that could substantially improve this code?
- Can we improve the code via design patterns?
- Does this code adhere to Design Principles? (KISS, SOLID, YAGNI, etc.)
- Have you found any code smells in the code?
Is the code well-designed?
Will it be easy to change the code for other developers in the future?
Are architectural or major design changes approved by a Principal or an Architect?
Are you sure that no new unit/gem/architecture/etc. is introduced into the codebase without the prior approval process (tech leadership meeting) or at least being discussed with a Principal?

Improve Reliability

This step allows you to identify any potential performance, security, or scalability concerns and discuss them with the author.

Perfomance
- Do you think this code change will negatively impact system performance?
- Do you see potential for significant code performance improvement?
- Are database queries optimized for efficiency, with proper use of indexes and joins?
- Are N+1 query problems addressed by using eager loading where needed?
- Are computationally expensive tasks offloaded to background jobs, preventing slow responses or request timeouts for users?
- Does this code utilize memoization for methods that are called multiple times?
Security
- Which user roles are expected to gain access to the added resources?
- Are passwords securely stored using strong encryption, such as bcrypt?
- Are file uploads properly validated, restricted to safe file types, and securely stored?
- Does this code change expose any sensitive information, such as API keys, passwords, or usernames?
- Is sensitive data, like user data or credit card information, securely handled and stored?
- Are user inputs validated and sanitized to prevent SQL injection and XSS attacks?
- Are authorization and authentication correctly implemented?
- Are third-party libraries and gems regularly reviewed for known security vulnerabilities?
- Are API endpoints authenticated and authorized correctly?
- Are you sure that users cannot access API resources that do not belong to them?

Risk Management

The main goal of this step is to mitigate the risk and do everything you can to reduce the chances of breaking the product.

Preemptively draw attention to any areas of the code where you feel unsure.
Determine the appropriate level of review needed based on the scope and impact of the code change.
How risky is the PR? Is the feature actively used, or is it hidden and hasn't been realized yet? How critical is it?
Is there any impact on other domains? Could the owner of the PR lack knowledge about how their work might impact other domains or code?
How experienced is the PR author? Do you need to spend extra time re-checking the author's code, or can you trust it?
Make a list of potential risks or issues that could arise from this change.
It might be helpful to try running the code locally to ensure there are no issues.
Tests
- Review any tests included with the code change to verify they adequately cover the functionality and edge cases.
- Is test coverage sufficient and correct? Are all border cases covered?
- Do the code changes have appropriate unit tests?
- Is the code designed to be easily testable?
- Have automated tests been added or relevant ones updated to cover the new functionality?
- Do the existing tests reasonably cover the code change, including unit, integration, and system tests?
- Are there additional test cases, inputs, or edge cases that should be considered?
Logic Errors and Bugs
- Can you envision any use cases in which the code does not behave as intended?
- Can you identify any inputs or external events that could potentially break the code?
- Ensure a failing test is written if the change is for a bug fix.

Soft Skills (How should Code Reviewers behave to address the problems they find?)

Collaboration

Be willing to collaborate with the author to resolve any issues or concerns that arise during the review process.
Seek continuous improvement, not perfection.
Consider using pair programming as an alternative or supplement to code reviews.
Resolve conflicting opinions in a timely manner; don't let a PR sit around due to disagreement.
Allocate time for code reviews - everyone really appreciates reviews. You get to know the people and the codebase too.
Articulate your intention behind the feedback (suggestion vs request for a change vs improvement that can be done in a different ticket).
Keep all the discussion online. If you contacted the reviewer by chat or email, bring relevant comments online.
Be kind and empathetic.
Reply within a reasonable timeframe.
Avoid Gold Plating. Yes, we strive for code excellence but at some point, we have to be pragmatic (create a refactor ticket) and ship code.
If you review only certain files that are part of a larger change or only certain aspects of the PR, such as the high-level design, privacy or security implications, etc., note in a comment what you reviewed.
Discuss in person

If there is a disagreement, have a quick in-person/video/IM chat to sort out what is going on - it‘s much easier to address all the little "Oh, I didn’t know"s in a single face-to-face, instead of back-and-forth via e-mail with long delays. “In person” doubly applies if you are disagreeing with another reviewer. And please make sure to record the outcomes on the review.

Find an end

If you like things neat, it‘s tempting to go over a code review over and over until it’s perfect, dragging it out for longer than necessary. It‘s soul-deadening for the recipient, though. Keep in mind that “LGTM” does not mean “I vouch my immortal soul this will never fail”, but “looks good to me”. If it looks good, move on. (That doesn’t mean you shouldn‘t be thorough. It’s a judgment call.) And if there are bigger refactorings to be done, move them to a new PR.

Always ask yourself if this decision really matters in the long run or if you're enforcing a subjective preference.

How to provide respectful and professional feedback?

Use "we" instead of "you"

Bad: "Why do you add this function?"

Good: "Why do you think we should add this function?"

Use questions instead of commands or orders

Bad: "We need tests for this."

Good: "I don't see any unit tests for this function. Could we add some test cases to ensure it behaves as expected under various conditions?"

Suggest, rather than instruct

Bad: "Change the variable name to 'total_price'."

Good: "Consider changing the variable name to 'total_price'. It might make the code more descriptive."

Good: "Perhaps it would be better to rename the variable as 'total_price' for improved code clarity."

If you add something not very important, feel free to prefix it with something like 'Nit' to let the author know that it's just a point of polish that they could choose to ignore

Bad: "The formatting here is inconsistent."

Good: "Nit: I noticed a minor inconsistency in the formatting. Could we align the indentation for consistency?"

Good: "Optional: I noticed a minor inconsistency in the formatting. Could we align the indentation for consistency?"

Good: "FYI: I noticed a minor inconsistency in the formatting. Aligning the indentation for consistency is something to consider."

This makes the reviewer's intent explicit and helps authors prioritize the importance of different comments. It also helps prevent misunderstandings. For instance, without comment labels, authors might interpret all comments as mandatory, even if some are intended to be purely informational or optional.

Don’t be afraid to ask questions about how or why a thing works.

Good: "Could you provide some context on why you decided to use this specific algorithm instead of a more straightforward approach?"

Keep it light-hearted and use emojis

Good: "What do you think about this approach? 🤔 But I'm not sure if it works 😅"

Try to find positives and provide positive remarks

Good: "Great work on this feature! 🚀"

Good: "Excellent job! ✅"

Good: "Well done 💪"

Good: "Thanks for fixing it so quickly 🎉"

Raise concerns in a polite and constructive manner

Bad: "This is wrong"

Good: "Maybe I'm missing something, but ..."

Good: "I might be mistaken, but ...?

Good: "I could be wrong, but ..."

Be respectful and professional in your feedback, avoiding personal attacks, blame, or derogatory comments

Bad: "This code is so sloppy and careless. Are you even trying?"

Bad: "You're making the same mistake again."

Bad: "This code is terrible."

Bad: "You clearly don't understand how this works."

Bad: "You always forget to add comments."

Bad: "How could you not see this mistake? It's so obvious."

Bad: "Are you sure that software engineering is the right career path for you?"

Conclusion

To wrap it up, this article has introduced a clear code review process that can enhance code quality and speed up product development. We've talked about why code reviews matter and how they help teams. We've also pointed out who does what in code reviews and how it all works. These ideas are here to support organizations, code authors, and reviewers in making the most of code reviews and getting excellent outcomes.

Understanding Transaction Isolation Levels in Rails with Simple Examples

Vlad Hilko — Sat, 29 Jul 2023 14:06:27 +0000

Overview

In this article, we will discuss the usage of database transactions in a Rails application, with a particular focus on one of the ACID principles - Isolation - and its four levels. We will explore what these isolation levels are, why they are necessary, and the problems they aim to solve. Additionally, we will provide a straightforward working example of each isolation level using the Rails console. By the end of the article, you will have a decent understanding of isolation levels, and you will be able to verify their behavior on your own to ensure how they work.

Definition

In simple terms, a transaction is a mechanism that allows you to execute a group of operations in such a way that either they all execute (commit), or the system state will be as if they have not started to execute at all (rollback). In Rails, to use a transaction, you need to write your operations into the following block:

ActiveRecord::Base.transaction { # ... }

Introduction

To better understand transactions, we will explain what the ACID principles are and the kind of problems they aim to solve. Afterward, we will delve deeply into one of these principles called Isolation, and we will explain why we need it and the problem-solving strategies that isolation suggests. Additionally, we will provide Rails examples to better grasp this concept.

ACID

ACID is an acronym that stands for Atomicity, Consistency, Isolation, and Durability. These four principles highlight the potential problems that may occur and what we should be aware of. For two of them (Consistency and Durability), we don't have any control, and we should rely on the database implementation and trust it. For the other two (Atomicity and Isolation), we can have more control, and we will be focusing on them more.

Atomicity

The first principle is Atomicity. To remember this, we can think about the atom. You can't split the atom. The same goes for an atomicity transaction; you can't just split it. It should be all or nothing. Let's provide an example of breaking this principle:

# rails c

animal = Animal.first
# => #<Animal:0x00000001112ad408 id: 1, name: nil, status: nil>

def check_transaction_atomicity(animal)
  animal.update!(name: 'Cat')
  raise 'Error'
  animal.update!(status: 'created')
end

check_transaction_atomicity(animal)
# RuntimeError: Error

animal.reload
# #<Animal:0x00000001112ad408 id: 1, name: "Cat", status: nil>

As you can see, our data is now saved in an inconsistent state. The name was saved, but the status wasn't. This is why we violate the atomicity principle because we must commit all or nothing.

Consistency

The second principle is Consistency. Consistency means that the database must always move from one valid state to another, ensuring that data meets all defined rules and constraints after a transaction is completed. Consistency ensures that any illegal states resulting from the transaction are automatically rolled back to the previous valid state.

If Consistency doesn't exist during the database transaction, then the following code would successfully work even if a strict NOT NULL constraint was present on the id column.

animal = Animal.first

def check_transaction_consistency(animal)
  animal.update(id: nil)
end

check_transaction_consistency(animal)

# => ActiveRecord::NotNullViolation: Mysql2::Error: Column 'id' cannot be null

animal.reload.id
# => 1

We can't control this principle; that's why we should fully rely on the database.

Isolation

The isolation principle doesn't allow interference with any data inside the transaction until the transaction is released. There are three potential problems that may occur and break isolation, all of them are connected with reading data during transaction execution, here they are:

Dirty Read
Non-Repeatable Read
Phantom Read

To remember these problems, you can think about the CRUD operations (create, read, update, and delete):

Dirty Read may appear when we READ data
Non-Repeatable Read may appear when we UPDATE data
Phantom Read. may appear when we CREATE data

Let's discuss some abstract examples to gain a rough understanding of the problems. In the next chapter, we will provide a real example to illustrate these concepts more concretely.

Dirty Read

When a transaction reads data from another uncommitted transaction, we call this violation a Dirty Read. This problem has such a name because it allows us to read 'Dirty' data that is unfinished and may not be accurate. An abstract example to demonstrate this violation would look as follows:

# rails c

Animal.first
# => #<Animal:0x00000001112ad408 id: 1, name: "Cat", status: nil>

def dirty_read_transaction
  Animal.first.update!(status: 'dirty_read')

  sleep 5

  raise 'Unexpected Error'
end

def try_to_read_data_inside_transaction_during_execution
  sleep 1

  puts Animal.first.status
end

Thread.new { dirty_read_transaction }
Thread.new { try_to_read_data_inside_transaction_during_execution }

# => 'dirty_read'

As you can see, the problem here is that we have access to the updated data even if the data is not fully committed and may be rolled back later.

Non-Repeatable Read

A non-repeatable read occurs when, during the course of a transaction, a row is retrieved twice, and the values within the row differ between reads. This problem has such a name because the same data inside the transaction may not be equal ("not repeated") by the end of the transaction execution. To demonstrate it, we can use the following snippet:

# rails c

Animal.first
# => #<Animal:0x00000001112ad408 id: 1, name: "Cat", status: 'repeatable_read'>

def non_repeatable_read_transaction
  puts "Current value is: #{Animal.first.status}"

  sleep 5

  puts "Current value is: #{Animal.first.status}"
end

def try_to_update_data_inside_transaction_during_execution
  sleep 1

  Animal.last.update(status: 'non_repeatable_read')
end

Thread.new { non_repeatable_read_transaction }
Thread.new { try_to_update_data_inside_transaction_during_execution }

# => 'Current value is: repeatable_read'
# => 'Current value is: non_repeatable_read'

As you may notice, the value between the two reads is different ("not repeated").

Phantom Read

A phantom read occurs when, in the course of a transaction, new rows are added by another transaction to the records being read. It has such a name because the new record appears in the middle of transaction execution out of nowhere, like a 'phantom', because there were no such records when we just started the transaction execution.

Let's provide an example of breaking this principle:


Animal.all
# [
#  #<Animal:0x000000010b7ca748 id: 1, name: "Cat", status: nil>,
#  #<Animal:0x000000010b7ca680 id: 2, name: "Dog", status: nil>
# ]

def phantom_read_transaction
  puts "We have the following animals #{Animal.ids}"

  sleep 5

  puts "We have the following animals #{Animal.ids}"
end

def try_to_create_data_inside_transaction_during_execution
  sleep 1

  Animal.create(name: 'Wolf')
end

Thread.new { phantom_read_transaction }
Thread.new { try_to_create_data_inside_transaction_during_execution }

# => We have the following animals [1, 2]
# => We have the following animals [1, 2, 3]

That's it.

Durability

The final aspect of the ACID approach to database management is durability.

Durability ensures that changes made to the database (transactions) that are successfully committed will survive permanently, even in the case of system failures. This ensures that the data within the database will not be corrupted by:

Service outages
Crashes
Other cases of failure

Let's take a look at the following example:

# rails c

animal = Animal.first
# => #<Animal:0x00000001112ad408 id: 1, name: nil, status: nil>

def check_transaction_durability(animal)
  animal.update!(name: 'Cat')
end

check_transaction_durability(animal)

# power outage

animal.reload.name
# => 'Cat'

If we didn't apply the Durability principle here, then after some unexpected crashes, we would lose the data that was already committed. We can't control this; that's why we should fully rely on the database.

Transaction Isolation Levels

To solve the problems that were mentioned above in the ACID isolation chapter, the Database provides 4 isolation levels:

Read Uncommitted
Read Committed
Repeatable Read
Serializable

Each of these levels is stronger than the previous one and solves all previous problems by default.

Read Uncommitted

At this level, we can just rollback the transaction; everyone can update and read data inside during execution. At this level, there's no isolation at all. And as the name suggests, this isolation level is allowed to read the data from the transaction that hasn't been committed. Let's take a look at the example:

# rails c

Animal.first
# => #<Animal:0x00000001112ad408 id: 1, name: "Cat", status: nil>

def read_uncommitted_transaction
  Animal.first.update!(status: 'read_uncommitted')

  sleep 5

  raise 'Unexpected Error'
end

def try_to_read_data_inside_transaction_during_execution
  sleep 1

  puts "We have access to the uncommitted value inside the transaction, and the status value is: #{Animal.first.status}"
end

Thread.new { ActiveRecord::Base.transaction(isolation: :read_uncommitted) { read_uncommitted_transaction } }
Thread.new { ActiveRecord::Base.transaction(isolation: :read_uncommitted) { try_to_read_data_inside_transaction_during_execution } }

# => We have access to the uncommitted value inside the transaction, and the status value is: read_uncommitted
# => Error (RuntimeError)

Animal.first.status
# => 'nil'

As you can see, we had access to the uncommitted status inside the transaction, but after rollback, the final status value is still nil.

Read Committed

The second isolation level allows us to solve the Dirty Read problem but doesn't solve the other two (Non-Repeatable Read and Phantom Read). As the name of this isolation level suggests, now we can't read uncommitted data, only the committed one. First of all, let's try to run the same example but we'll change the isolation level from :read_uncommitted to :read_committed:

# rails c

Animal.first
# => #<Animal:0x00000001112ad408 id: 1, name: "Cat", status: nil>

def read_committed_transaction
  Animal.first.update!(status: 'read_committed')

  sleep 5

  raise 'Unexpected Error'
end

def try_to_read_data_inside_transaction_during_execution
  sleep 1

  puts "We don't have access to uncommitted value inside the transaction, and the status value is still: #{Animal.first.status}"
end

Thread.new { ActiveRecord::Base.transaction(isolation: :read_committed) { read_committed_transaction } }
Thread.new { ActiveRecord::Base.transaction(isolation: :read_committed) { try_to_read_data_inside_transaction_during_execution } }

# => We don't have access to uncommitted value inside the transaction, and the status value is still:
# => Error (RuntimeError)

Animal.first.status
# => 'nil'

As you can see here, we don't have access to the value that has been updated inside the other transaction because the second transaction can't read the data from the first one. Do we have any other problems with this isolation level? Yes, as I said, this transaction can solve only the Dirty Read problem, and Non-Repeatable Read Read and Phantom Read still exist. Let's take a look:

# rails c

Animal.first
# => #<Animal:0x00000001112ad408 id: 1, name: "Cat", status: 'initial'>

def read_committed_transaction
  puts "Current value is: #{Animal.first.status}"

  sleep 5

  puts "Current value is: #{Animal.first.status}"
end

def try_to_update_data_inside_transaction_during_execution
  sleep 1

  Animal.first.update!(status: 'non_repeatable_read')
end

Thread.new { ActiveRecord::Base.transaction(isolation: :read_committed) { read_committed_transaction } }
Thread.new { ActiveRecord::Base.transaction(isolation: :read_committed) { try_to_update_data_inside_transaction_during_execution } }

# => 'Current value is: initial'
# => 'Current value is: non_repeatable_read'

As you can see, the second transaction is changing the value inside the first one, and we receive non-repeatable values.

Repeatable Read

The third isolation level allows us to solve the Dirty Read and Non-Repeatable Read problems, but still can't handle the Phantom Read. Let's run the code from the previous example to make sure that Non Repeatable Read won't be present here:

# rails c

Animal.first
# => #<Animal:0x00000001112ad408 id: 1, name: "Cat", status: 'initial'>

def repeatable_read_transaction
  puts "Current value is: #{Animal.first.status}"

  sleep 5

  puts "Current value is: #{Animal.first.status}"
end

def try_to_update_data_inside_transaction_during_execution
  sleep 1

  Animal.first.update!(status: 'non_repeatable_read')
end

Thread.new { ActiveRecord::Base.transaction(isolation: :repeatable_read) { repeatable_read_transaction } }
Thread.new { ActiveRecord::Base.transaction(isolation: :repeatable_read) { try_to_update_data_inside_transaction_during_execution } }

# => 'Current value is: initial'
# => 'Current value is: initial'

As you can see, the previous problem disappeared here, and we have "repeatable" values.

Now, let's take a look if we really have the Phantom Read problem here:

# rails c 

Animal.all
# [
#  #<Animal:0x000000010b7ca748 id: 1, name: "Cat", status: nil>,
#  #<Animal:0x000000010b7ca680 id: 2, name: "Dog", status: nil>
# ]

def repeatable_read_transaction
  puts "Inside the current transaction, we have the following animals: #{Animal.ids}"

  sleep 5

  puts "After the time gap, we still have the following animals: #{Animal.ids}"
  Animal.update_all(status: 'phantom_read_triggered')
  puts "After we triggered the update all operation, we have the following animals: #{Animal.ids}"
end

def try_to_create_data_inside_transaction_during_execution
  sleep 1

  Animal.create(name: 'Wolf')
end

Thread.new { ActiveRecord::Base.transaction(isolation: :repeatable_read) { repeatable_read_transaction } }
Thread.new { ActiveRecord::Base.transaction(isolation: :repeatable_read) { try_to_create_data_inside_transaction_during_execution } }

# => Inside the current transaction, we have the following animals [1, 2]
# => After the time gap, we still have the following animals [1, 2]
# => After we triggered the update all operation, we have the following animals [1, 2, 3]

As you can see, a new ID has been added, and it was not expected. Let's try to fix it using the latest isolation level.

Serializable

The Serializable isolation level is the strongest among all the isolation levels. It provides the highest level of isolation and ensures that the transactions are executed in a way that is equivalent to running them sequentially, one after the other. This means that no concurrent execution of transactions can result in anomalies like Dirty Read, Non-Repeatable Read, or Phantom Read.

Let's use the Serializable isolation level to fix the Phantom Read problem in the previous example:

# rails c

Animal.all
# [
#  #<Animal:0x000000010b7ca748 id: 1, name: "Cat", status: nil>,
#  #<Animal:0x000000010b7ca680 id: 2, name: "Dog", status: nil>
# ]

def serializable_transaction
  puts "Inside the current transaction, we have the following animals: #{Animal.ids}"

  sleep 5

  puts "After the time gap, we still have the following animals: #{Animal.ids}"
  Animal.update_all(status: 'phantom_read_fixed')
  puts "After we triggered the update all operation, we have the following animals: #{Animal.ids}"
end

def try_to_create_data_inside_transaction_during_execution
  sleep 1

  Animal.create(name: 'Wolf')
end

Thread.new { ActiveRecord::Base.transaction(isolation: :serializable) { serializable_transaction } }
Thread.new { ActiveRecord::Base.transaction(isolation: :serializable) { try_to_create_data_inside_transaction_during_execution } }

# => Inside the current transaction, we have the following animals [1, 2]
# => After the time gap, we still have the following animals [1, 2]
# => After we triggered the update all operation, we have the following animals [1, 2]

As you can see there's no phantom records and all data were properly isolated inside the transaction.

Conclusion

Transaction isolation levels are essential in managing data consistency and concurrency in databases. We discussed four isolation levels: Read Uncommitted, Read Committed, Repeatable Read, and Serializable. Each level offers different degrees of isolation and addresses specific problems related to concurrent transactions. We demonstrated how each isolation level affects transactions through practical examples. By carefully choosing the appropriate isolation level, developers can strike a balance between data integrity and performance, ensuring that transactions behave predictably and maintain data consistency even in a multi-user environment.

How to Add Database Triggers in Ruby on Rails?

Vlad Hilko — Wed, 26 Jul 2023 14:45:25 +0000

Overview

In this article, we are going to discuss the usage of database triggers in Ruby on Rails applications. We will cover what they are, why they are essential, the problems they solve, their pros and cons, when they are allowed to be used, and when they are not. Additionally, we will provide three simple examples of how to add these triggers in a Rails application. By the end of this article, you will have a better understanding and a broader perspective on using DB triggers in Rails applications.

Introduction

In simple terms, a database trigger is a function that is automatically invoked when an INSERT, UPDATE, or DELETE operation is performed on a table. You can think of it as an ActiveRecord callback that is executed at the database level. Sometimes, they are even referred to as SQL callbacks.

Use cases

We usually use triggers to solve the following problems:

Auditing and Logging
Database schema refactoring (denormalization, renaming columns, splitting a column into two columns, etc.)
Populating Summary Tables

Pros/Cons

Pros:

Data Accuracy and Consistency
Reduced Complexity in Application Code

Cons:

When you use triggers, ActiveRecord has no way of knowing when your records have changed. This means ActiveRecord objects will retain outdated data until they are reloaded.
Don't overdo it. Delegating too much business logic to triggers can create problems in the future (Debugging Difficulties, Testing Challenges, Performance Impact, etc.)

While triggers can be useful for certain functionalities, it's essential to use them judiciously and consider alternative approaches for implementing business logic within the application code when possible.

Example 1: Adding a Trigger Inside Rails Console

In this first example, we will create a DB trigger directly in the Rails console and observe how it works. Let's consider two database tables, animals and removed_animals, each containing only two columns - id and name. Our goal is to add a trigger that duplicates an animal record into the removed_animals table every time we delete a record from the main animals table.

Let's see the current state:

# rails c

Animal.create(name: 'Animal')
Animal.last.delete

RemovedAnimal.all
# => []

Currently, the removed_animals table is empty and doesn't contain any removed records.

Now, let's execute a manual insertion into removed_animals to see what we expect to run in the trigger:

# rails c

ActiveRecord::Base.connection.execute("INSERT INTO `removed_animals` (`id`, `name`) VALUES (1, 'animal_name')")

RemovedAnimal.all
# =>  [#<RemovedAnimal:0x000000010bc4be98 id: 1, name: "animal_name">]

As seen above, we manually inserted a record into removed_animals.

Now, let's implement the trigger and check how it works:

# rails c

ActiveRecord::Base.connection.execute(
"
CREATE TRIGGER save_removed_animal_trigger
AFTER DELETE ON animals
FOR EACH ROW
INSERT INTO `removed_animals` (`id`, `name`) VALUES (OLD.`id`, OLD.`name`)
"
)

With the trigger in place, let's test it further:

Animal.create(name: 'Animal')
Animal.create(name: 'Another Animal')

Animal.all
# => [#<Animal:0x000000010dc41f18 id: 10, name: "Animal">, #<Animal:0x000000010dc41e50 id: 11, name: "Another Animal">]

RemovedAnimal.all
# => []

Animal.destroy_all

Animal.all
# => []

RemovedAnimal.all
# => [#<RemovedAnimal:0x000000010de6b550 id: 10, name: "Animal">, #<RemovedAnimal:0x000000010de6b488 id: 11, name: "Another Animal">]

As shown above, all our destroyed animal records have been saved to the removed_animals table.

Now, let's drop this trigger and recreate the same logic using the correct Rails approach in Example 2:

# rails c

ActiveRecord::Base.connection.execute("DROP TRIGGER save_removed_animal_trigger")
# => nil

Example 2: Adding Triggers Using the hair_trigger Gem

In this second example, we will achieve the same functionality using a clearer approach by utilizing the hair_trigger gem. Let's start by installing it:

# Gemfile

gem 'hairtrigger'

And run:

bundle install

After installing the gem, we can declare triggers in our models and use a rake task to auto-generate the appropriate migration:

# app/models/animal.rb

class Animal < ApplicationRecord
  trigger.after(:delete) do
    "INSERT INTO `removed_animals` (`id`, `name`) VALUES (OLD.`id`, OLD.`name`)"
  end
end

To generate the migration, run the following command:

rake db:generate_trigger_migration

This task will generate the migration file for us:

# db/migrate/20230725122552_create_trigger_animals_delete.rb

# This migration was auto-generated via `rake db:generate_trigger_migration'.
# While you can edit this file, any changes you make to the definitions here
# will be undone by the next auto-generated trigger migration.

class CreateTriggerAnimalsDelete < ActiveRecord::Migration[7.0]
  def up
    create_trigger("animals_after_delete_row_tr", :generated => true, :compatibility => 1).
        on("animals").
        after(:delete) do
      "INSERT INTO `removed_animals` (`id`, `name`) VALUES (OLD.`id`, OLD.`name`);"
    end
  end

  def down
    drop_trigger("animals_after_delete_row_tr", "animals", :generated => true)
  end
end

Now, execute the migration:

rails db:migrate

And test if the trigger works as expected, similar to what we did in Example 1:

# rails c

Animal.create(name: 'Animal')
Animal.create(name: 'Another Animal')

Animal.all
# => [#<Animal:0x000000010bbb1730 id: 12, name: "Animal">, #<Animal:0x000000010bbb15c8 id: 13, name: "Another Animal">]

RemovedAnimal.all
# => []

Animal.destroy_all

Animal.all
# => []

RemovedAnimal.all
# => [#<RemovedAnimal:0x000000010bd81498 id: 12, name: "Animal">, #<RemovedAnimal:0x000000010bd813d0 id: 13, name: "Another Animal">]

As you can see, everything works as expected.

Example 3: Adding a Trigger to Support Column Renaming

In this third example, we will add a trigger that allows us to rename a column with zero downtime. To achieve this, we'll follow these steps:

Add a new column.
Add a trigger to dual-write to both columns.
Backfill the new column with a copy of the old column’s values.
Start using the new column throughout the whole application.
Drop the old column.

For now, we're focused on step 2 - creating a new trigger to write to both columns simultaneously. Let's examine what we want to achieve. Suppose we have an animals table with two columns -> id and name, and we decide to rename the name column to full_name, for example. So, we need to add this new column and observe the current behavior:

# rails c

Animal.create(name: 'Animal')
Animal.last

# => #<Animal:0x000000010e823980 id: 14, name: "Animal", full_name: nil>

Animal.last.update(name: 'Updated Animal')
Animal.last

# => #<Animal:0x000000010e9f9d90 id: 14, name: "Updated Animal", full_name: nil>

As seen above, when we create or update an animal's name, the full_name column remains blank. However, if we replace the name column with full_name, all values should synchronize. This is where a trigger can be immensely helpful:

# app/models/animal.rb

class Animal < ApplicationRecord
  trigger.before(:insert) do
    "SET NEW.full_name = NEW.name;"
  end

  trigger.before(:update).of(:name) do
    "SET NEW.full_name = NEW.name;"
  end
end

After adding the triggers to the model, we need to run the following command to generate the migration:

rake db:generate_trigger_migration

This rake task generates the migration file for us:

# db/migrate/20230725154353_create_triggers_animals_insert_or_animals_update.rb

# This migration was auto-generated via `rake db:generate_trigger_migration'.
# While you can edit this file, any changes you make to the definitions here
# will be undone by the next auto-generated trigger migration.

class CreateTriggersAnimalsInsertOrAnimalsUpdate < ActiveRecord::Migration[7.0]
  def up
    create_trigger("animals_before_insert_row_tr", :generated => true, :compatibility => 1).
        on("animals").
        before(:insert) do
      "SET NEW.full_name = NEW.name;"
    end

    create_trigger("animals_before_update_of_name_row_tr", :generated => true, :compatibility => 1).
        on("animals").
        before(:update).
        of(:name) do
      "SET NEW.full_name = NEW.name;"
    end
  end

  def down
    drop_trigger("animals_before_insert_row_tr", "animals", :generated => true)

    drop_trigger("animals_before_update_of_name_row_tr", "animals", :generated => true)
  end
end

Let's run this migration:

rails db:migrate

And check if it works:

# rails c

animal = Animal.create(name: 'Animal')
# => #<Animal:0x000000010e5723f8 id: 21, name: "Animal", full_name: nil>
animal.reload
# => #<Animal:0x000000010e5723f8 id: 21, name: "Animal", full_name: "Animal">

animal.update(name: 'New Name')
animal
# => #<Animal:0x000000010e5723f8 id: 21, name: "New Name", full_name: "Animal">

As you can see, everything works as expected, and all name values are duplicated into the full_name column.

Conclusion

In this article, we explored three examples of adding triggers to a Rails application. From creating simple triggers in the Rails console to using the hair_trigger gem for a clearer approach. Triggers offer data accuracy and automation but should be used judiciously to avoid potential challenges.

Data Migration Strategies in Ruby on Rails: The Right Way to Manage Missing Data

Vlad Hilko — Sat, 22 Jul 2023 16:13:09 +0000

Overview

In this article, we're going to discuss the possible strategies for migrating, generating, and backfilling data in a Rails application. We'll implement them, improve them, consider their pros and cons, and discuss which ones are better to use in different scenarios. By the end of the article, we will have a full picture of the different ways to solve data migration problems.

Introduction

In simple terms, data migration is the process of adding, updating, or transferring some data inside your application. The most popular cases for data migration are as follows:

Backfilling column data
Moving column data from one table to another
Generating new database records
Updating corrupted or invalid data with correct values
Removing unused data

We'll consider 3 different ways to do it:

Direct Data Manipulation
Rake Task
Data Migration Gem

Direct Data Manipulation

The first option is the simplest one: we'll just add missing data via rails c or through a direct database connection in production.

Advantages:

Easy
No need to implement anything new
It's fast because data migration can be done in minutes.

Problems:

Too risky; changes may not end up as intended
Possible access and security problems
There are no tests and code reviews, so we can't be sure of the quality
Lack of control; you don't know who ran the migration or why they ran it.

Rake Task

The second option is the rake task. In this chapter, we will try to understand how to properly add rake tasks, ensure that they work correctly, learn their pros and cons, and explore how they can be used for data migration. We will start by adding the simplest rake task, and then we will proceed to improve its structure, cover the logic with tests, and consider using best practices for writing data migration using rake tasks.

Let's imagine that we have an Animal model with the following fields:

id
kind
status
created_at
updated_at

And we need to change the status value from nil to reserved for all animals that we created before today. How can we do it? Let's start by adding a simple rake task template.

# frozen_string_literal: true

# lib/tasks/animals/backfill_statuses.rake

namespace :animals do
  desc "Update animal status to 'reserved' for animals created before today"
  task backfill_statuses: [:environment] do
    puts 'Updating animal status...'
  end
end

And check that it works:

rake animals:backfill_statuses
# => Updating animal status...

The task has been executed and works as expected. Now, let's add the actual code with the database update. It will look like the following:

# frozen_string_literal: true

# lib/tasks/animals/backfill_statuses.rake

namespace :animals do
  desc "Update animal status to 'reserved' for animals created before today"
  task backfill_statuses: [:environment] do
    Animal.where(status: nil).where('created_at < ?', Time.zone.today).update_all(status: 'reserved')
  end
end

Now, let's check if it works:

rake animals:backfill_statuses

The rake task has been executed, and the database values are updated accordingly. That's it. Our main scenario works as expected, but there's still some room for improvements. Let's take a look at what we can do to make our task more reliable.

Improvements

There are 5 areas that we can potentially improve:

Display results in the console for visibility
Ensure data consistency with transactions
Optimize DB requests
Isolate the rake task code
Add tests

Display results in the console for visibility

As you may have noticed, the rake task above hasn't shown any output. It can be a real problem because you don't know whether it was run successfully or not, and you will spend much time trying to check it by yourself on production data. Let's fix this problem:

# frozen_string_literal: true

# lib/tasks/animals/backfill_statuses.rake

namespace :animals do
  desc "Update animal status to 'reserved' for animals created before today"
  task backfill_statuses: [:environment] do
    puts "Before running the rake task, there were #{Animal.where(status: 'reserved').count} animals in the 'reserved' state."

    Animal.where(status: nil).where('created_at < ?', Time.zone.today).update_all(status: 'reserved')

    puts "After running the rake task, there are now #{Animal.where(status: 'reserved').count} animals in the 'reserved' state."
  end
end

Now, let's run the rake task:

rake animals:backfill_statuses

# => Before running the rake task, there were 0 animals in the 'reserved' state.
# => After running the rake task, there are now 101 animals in the 'reserved' state.

With the updated code, we display the number of animals in the 'reserved' state both before and after running the rake task, providing better visibility and ensuring that the task is executed successfully.

Ensure data consistency with transactions

What happens if some unexpected errors appear in the middle of data migration? Right now, we don't handle it. Even if it's not critical for the example that we've provided, in general, we should not forget to wrap such kind of data manipulation into a transaction to keep a consistent data state.

# frozen_string_literal: true

# lib/tasks/animals/backfill_statuses.rake

namespace :animals do
  desc "Update animal status to 'reserved' for animals created before today"
  task backfill_statuses: [:environment] do
    ActiveRecord::Base.transaction do
      Animal.where(status: nil).where('created_at < ?', Time.zone.today).update_all(status: 'reserved')
    end
  end
end

By adding the ActiveRecord::Base.transaction block, we ensure that all the updates are executed as a single atomic operation. If any error occurs during the data migration, the transaction will be rolled back, and the data will remain unchanged, maintaining data consistency and integrity.

P.S. If you have very large tables, you need to keep in mind that simply UPDATE all rows would cause a lock against writes on the whole table. That is why updates must be done in batches. The migration must not run within a transaction for the same reason.

Optimize DB requests

We have already handled this problem in our rake task, but it's important to mention that we should use the optimal database solution if possible. For example, someone could write our task like this:

# frozen_string_literal: true

# lib/tasks/animals/backfill_statuses.rake

namespace :animals do
  desc "Update animal status to 'reserved' for animals created before today"
  task backfill_statuses: [:environment] do
    Animal.where(status: nil).where('created_at < ?', Time.zone.today).each do |animal|
      animal.update(status: 'reserved')
    end
  end
end

The following code will trigger an SQL update request for every animal from the list, making it non-optimal:

D, [2023-07-21T09:50:58.346040 #67787] DEBUG -- :   Animal Load (1.6ms)  SELECT `animals`.* FROM `animals` WHERE `animals`.`status` IS NULL AND (created_at < '2023-07-21')
D, [2023-07-21T09:50:58.346735 #67787] DEBUG -- :   ↳ lib/tasks/animals/backfill_statuses.rake:10:in `block (2 levels) in <main>'
D, [2023-07-21T09:50:58.371908 #67787] DEBUG -- :   TRANSACTION (2.2ms)  BEGIN
D, [2023-07-21T09:50:58.372737 #67787] DEBUG -- :   ↳ lib/tasks/animals/backfill_statuses.rake:11:in `block (3 levels) in <main>'
D, [2023-07-21T09:50:58.375091 #67787] DEBUG -- :   Animal Update (2.2ms)  UPDATE `animals` SET `animals`.`status` = 'reserved', `animals`.`updated_at` = '2023-07-21 07:50:58.368697' WHERE `animals`.`id` = 1
D, [2023-07-21T09:50:58.375713 #67787] DEBUG -- :   ↳ lib/tasks/animals/backfill_statuses.rake:11:in `block (3 levels) in <main>'
D, [2023-07-21T09:50:58.381169 #67787] DEBUG -- :   TRANSACTION (5.0ms)  COMMIT
D, [2023-07-21T09:50:58.381524 #67787] DEBUG -- :   ↳ lib/tasks/animals/backfill_statuses.rake:11:in `block (3 levels) in <main>'
D, [2023-07-21T09:50:58.383624 #67787] DEBUG -- :   TRANSACTION (1.3ms)  BEGIN
D, [2023-07-21T09:50:58.384250 #67787] DEBUG -- :   ↳ lib/tasks/animals/backfill_statuses.rake:11:in `block (3 levels) in <main>'
D, [2023-07-21T09:50:58.385792 #67787] DEBUG -- :   Animal Update (1.4ms)  UPDATE `animals` SET `animals`.`status` = 'reserved', `animals`.`updated_at` = '2023-07-21 07:50:58.381901' WHERE `animals`.`id` = 2

...

That's why it always makes sense to try to find a way to do it in a single DB operation, as we did with the following code:

# frozen_string_literal: true

# lib/tasks/animals/backfill_statuses.rake

namespace :animals do
  desc "Update animal status to 'reserved' for animals created before today"
  task backfill_statuses: [:environment] do
    Animal.where(status: nil).where('created_at < ?', Time.zone.today).update_all(status: 'reserved')
  end
end

This code will trigger only one DB request:

Animal Update All (6.8ms)  UPDATE `animals` SET `animals`.`status` = 'reserved' WHERE `animals`.`status` IS NULL AND (created_at < '2023-07-21')

If there's no way to update something in a single DB request, at least you should consider using batches as a good practice:

# frozen_string_literal: true

# lib/tasks/animals/backfill_statuses.rake

namespace :animals do
  desc "Update animal status to 'reserved' for animals created before today"
  task backfill_statuses: [:environment] do
    Animal.where(status: nil).where('created_at < ?', Time.zone.today).find_each do |animal|
      animal.update(status: 'reserved')
    end
  end
end

P.S. To see SQL logs from the rake task, you can add the following code inside:

# frozen_string_literal: true

# lib/tasks/animals/backfill_statuses.rake

namespace :animals do
  desc "Update animal status to 'reserved' for animals created before today"
  task backfill_statuses: [:environment] do
    ActiveRecord::Base.logger = Logger.new(STDOUT)

    # ...
  end
end

Isolate the rake task code

One not so obvious problem that can occur when you have many rake tasks is a lack of encapsulation. Let's take a look at the following two rake tasks and try to guess what can be wrong here:

rake animals:task1

# frozen_string_literal: true

# lib/tasks/animals/task1.rake

namespace :animals do
  task task1: [:environment] do
    puts message
  end

  def message
    'Hello world from Task 1!'
  end
end

rake animals:task2

# frozen_string_literal: true

# lib/tasks/animals/task2.rake

namespace :animals do
  task task2: [:environment] do
    puts message
  end

  def message
    'Hello world from Task 2!'
  end
end

Now let's run both of them:

rake animals:task1
# => Hello world from Task 2!
rake animals:task2
# => Hello world from Task 2!

Have you noticed? That's not what we expected! The second rake task overrode the method value from the first one! And that's quite dangerous and unexpected if you were to use something like this:

rake animals:task1

# frozen_string_literal: true

# lib/tasks/animals/task1.rake

namespace :animals do
  task task1: [:environment] do
    query.destroy_all
  end

  def query
    Animal.where(status: nil)
  end
end

lib/tasks/animals/task2.rake

# frozen_string_literal: true

# lib/tasks/animals/task2.rake

namespace :animals do
  task task2: [:environment] do
    query.destroy_all
  end

  def query
    Animal.all
  end
end

And run:

rake animals:task1

You would remove all your records instead of the desired subset!

How can we fix it?

We need to wrap our rake tasks into the Rake::DSL class like this:

rake animals:task1

# frozen_string_literal: true

# lib/tasks/animals/task1.rake

module Tasks
  module Animals
    class Task1

      include Rake::DSL

      def initialize
        namespace :animals do
          task task1: [:environment] do
            puts message
          end
        end
      end

      private

      def message
        'Hello world from Task 1!'
      end
    end
  end
end

Tasks::Animals::Task1.new

rake animals:task2

# frozen_string_literal: true

# lib/tasks/animals/task2.rake

module Tasks
  module Animals
    class Task2

      include Rake::DSL

      def initialize
        namespace :animals do
          task task2: [:environment] do
            puts message
          end
        end
      end

      private

      def message
        'Hello world from Task 2!'
      end
    end
  end
end

Tasks::Animals::Task2.new

And let's execute:

rake animals:task1
# => Hello world from Task 1!
rake animals:task2
# => Hello world from Task 2!

Now everything works as expected. Let's apply the same isolation for our backfill_statuses rake task.

# frozen_string_literal: true

# lib/tasks/animals/backfill_statuses.rake

module Tasks
  module Animals
    class BackfillStatuses

      include Rake::DSL

      def initialize
        namespace :animals do
          desc "Update animal status to 'reserved' for animals created before today"
          task backfill_statuses: [:environment] do
            Animal.where(status: nil).where('created_at < ?', Time.zone.today).update_all(status: 'reserved')
          end
        end
      end

    end
  end
end

Tasks::Animals::BackfillStatuses.new

That's it.

Add tests

The last thing that we're going to do to ensure quality is to add tests. Let's see how we can test the rake tasks.

First of all, we need to define some code to load our tasks:

# spec/support/tasks.rb

# frozen_string_literal: true

RSpec.configure do |_config|
  Rails.application.load_tasks
end

And include it in the spec/rails_helper.rb:

# spec/rails_helper.rb

require 'support/tasks'

Then let's add our test:

# spec/tasks/animals/backfill_statuses_spec.rb

# frozen_string_literal: true

require 'rails_helper'

RSpec.describe 'rake animals:backfill_statuses', type: :task do
  subject { Rake::Task['animals:backfill_statuses'].execute }

  let(:expected_output) do
    <<~TEXT
      Before running the rake task, there were 1 animals in the 'reserved' state.
      After running the rake task, there are now 2 animals in the 'reserved' state.
    TEXT
  end

  let(:animal_1) { create(:animal, created_at: 10.days.ago, status: nil) }
  let(:animal_2) { create(:animal, created_at: 10.days.ago, status: 'reserved') }
  let(:animal_3) { create(:animal, created_at: 10.days.ago, status: 'another_status') }
  let(:animal_4) { create(:animal, created_at: 10.days.from_now, status: nil) }

  before do
    animal_1
    animal_2
    animal_3
    animal_4
  end

  it "update animal status to 'reserved' for animals created before today" do
    expect { subject }.to change { animal_1.reload.status }.from(nil).to('reserved')
      .and output(expected_output).to_stdout

    expect(animal_2.reload.status).to eq('reserved')
    expect(animal_3.reload.status).to eq('another_status')
    expect(animal_4.reload.status).to be_nil
  end
end

That's it.

Data Migration Gem

The third option is to use the data-migrate gem.

Let's add this gem to our project:

# Gemfile

gem 'data_migrate'

And execute:

bundle install

Now you can generate a data migration as you would generate a schema migration:

rails g data_migration backfill_animal_statuses

# => db/data/20230721111716_backfill_animal_statuses.rb

Let's add some code to the generated file to check if it actually works:

# frozen_string_literal: true

class BackfillAnimalStatuses < ActiveRecord::Migration[7.0]
  def up
    puts 'Test Data Migration'
  end

  def down
    # do nothing
  end
end

To run the migration, we need to use the following command:

rake data:migrate
# or
rake db:migrate:with_data

And we get the following output:

== 20230721111716 BackfillAnimalStatuses: migrating ===========================
Test Data Migration
== 20230721111716 BackfillAnimalStatuses: migrated (0.0000s) ==================

This migration can be run only once. So let's remove it and generate another one and add real code inside:

rails g data_migration backfill_animal_statuses

# => db/data/20230721112534_backfill_animal_statuses.rbb

Here's what we get after adding our business logic code:

# db/data/20230721112534_backfill_animal_statuses.rb

# frozen_string_literal: true

class BackfillAnimalStatuses < ActiveRecord::Migration[7.0]
  def up
    Animal.where(status: nil).where('created_at < ?', Time.zone.today).update_all(status: 'reserved')
  end

  def down
    # do nothing
  end
end

And let's run:

rake data:migrate

Here's what we get:

== Data =======================================================================
== 20230721112534 BackfillAnimalStatuses: migrating ===========================
== 20230721112534 BackfillAnimalStatuses: migrated (0.0221s) ==================

Basically, data migration works by the same logic as scheme migration, but instead of saving the last running migration version into the schema_migrations table, data migration saves the version into another table called data_migrations.

It's important to mention that data migration should be irreversible in most cases, but we don't want to raise an explicit error as it would prevent rollback for the scheme structure changes. Instead, we just leave the down method empty. For this reason, it would be better to design the migration in an idempotent way, to be able to run it several times if possible.

Data Migration doesn't provide any additional advantages except for what we discussed above. Therefore, we still need to think about the problems that we solved for the rake task, such as displaying output, adding transactions, optimizing DB requests, etc.

Comparison of Rake Task and Data Migration Gem

Let's compare these two solutions and decide which one we should use and under what conditions:

When does a rake task fit better?

When you want to have the ability to select the exact time and day when you want to run it.
When you want to have the ability to select the platform where you want to run it (for example, staging or production).
When you want to run the same rake task several times.

When does the data migration gem fit better?

When you want to make sure that data will be added automatically and no one forgets to run something.
When schema migration order is important for you (for example, schema migration adds a new column and data migration backfills this column).
When you want to run it on all environments without additional effort.
When you need to run the migration only once.

So, in general, the rake task is much more flexible and testable and can cover the same tasks as the data migration but may require more effort. Data migrations are much more strict but provide some automations and strict execution order that are connected with schema changes.

For example, the data migration gem suits very well if you need to support some database schema restructurization and you don't want to miss the data during these changes. For instance, if you need to rename a column and you want to copy the values from the old one to a new one, then set NULL=false constraint to the new one, and then completely remove the old one, the data migration gem will make this process much easier compared to using a rake task.

On the other hand, if the task is unrelated to database schema changes, a rake task might be a more suitable choice. It offers greater flexibility and testability, making it easier to manage tasks that are not directly tied to schema alterations.

Conclusion

Throughout this article, we have explored various strategies for data migration, generation, and backfilling in a Rails application. We have implemented and improved these strategies, carefully considering their advantages and disadvantages. Additionally, we have compared two primary solutions, the rake task and data migration gem, and examined their suitability in different scenarios.

How to implement Adapter pattern in Ruby on Rails?

Vlad Hilko — Mon, 17 Jul 2023 07:44:20 +0000

Overview

In this article, we are going to discuss the adapter pattern. We will explore what the adapter pattern is, why we need it, and how it can be implemented in a Rails application. We will also examine the benefits and drawbacks it provides. Additionally, we will provide three different examples to help better understand the concept and the reasons behind it.

Definition

In simple terms, the Adapter pattern allows you to transform the interface of a class into a different interface that clients expect. By doing so, it enables classes with incompatible interfaces to collaborate and work together seamlessly. We usually use the Adapter pattern for the following purposes:

Integrating incompatible components

When you need to integrate two components that have incompatible interfaces, Adapter can bridge the gap by providing a common interface that allows them to work together seamlessly.

Implementing backward compatibility

If you need to make changes to an existing class or component but want to maintain compatibility with code that relies on the old interface, Adapter can be used to translate between the old and new interfaces.

Working with external libraries, services, or legacy systems

When integrating with external libraries or services that have their own specific interfaces, Adapter can be used to adapt their interface to fit the interface expected by your application. Adapters are also particularly useful when working with legacy systems or third-party components that have outdated or incompatible interfaces.

The Adapter pattern has the following pros and cons:

Advantages:

Enhanced flexibility

The Adapter pattern makes it easier to switch between implementations or integrate new components without modifying existing code.

Enhanced testability

The Adapter pattern enhances testability by isolating components, facilitating the use of mocking and dependency injection, and providing a clear interface for the adapted components.

Encapsulation of complexity

The Adapter pattern encapsulates complexity by simplifying complex logic, hiding implementation details, and separating concerns.

Independence from external solutions

The Adapter pattern enables you to switch or replace the external solution without affecting the rest of your codebase. This flexibility allows you to choose the most suitable external solution for your needs without the need for extensive modifications throughout your codebase.

Problems:

Potential increase in code complexity:

Introducing adapters can add complexity to the codebase, especially when dealing with a large number of adapters or complex adaptation logic.

Higher learning curve for developers:

Developers who are not familiar with the Adapter pattern may require additional time and effort to understand the purpose, design, and usage of adapters in the codebase. This learning curve can slow down development and onboarding processes for new team members.

Implementation

Let's start by implementing our first adapter. We'll begin with a simple abstract example to help us grasp the concept. Afterward, we'll provide two additional examples and demonstrate how to integrate them into a Rails application.

Example 1: Cat and Dog

In this example, we will discuss how two different objects with different interfaces can collaborate. Let's imagine that we have the following two classes:

class Cat
  def self.meow!
    p 'Meow!'
  end
end

class Dog 
  def self.woof!
    p 'Woof!'
  end
end

Cat.meow!
# => 'Meow!'
Dog.woof!
# => 'Woof!'

For example, let's say we would like to use one of them based on a certain condition, like the one shown below:


if Rails.env.test? 
  Cat.meow!
else
  Dog.woof!
end

Having many such conditions scattered throughout the code makes it difficult to maintain and less manageable. Therefore, we need to find a solution to address this issue. The main goal of the Adapter Pattern is to solve this problem by creating a common interface without altering the initial implementation. Let's explore how we can achieve it.

Firstly, we need to create a new Adapter class for each class that we intend to adopt with a new interface.

class CatAdapter
  def self.speak!
    Cat.meow!
  end
end

class DogAdapter
  def self.speak!
    Dog.woof!
  end
end

CatAdapter.speak!
# => 'Meow!'
DogAdapter.speak!
# => 'Woof!'

We have created a common interface for the two objects, which allows us to choose which one to use in a single location, without the need for additional changes throughout the application. For instance, we can implement the following code at the Rails configuration level:

AnimalAdapter = Rails.env.test? ? CatAdapter : DogAdapter

Now we can utilize AnimalAdapter throughout the entire application, and this adapter will encapsulate the logic of Cat under the hood

AnimalAdapter.speak!
# => 'Meow!'

Example 2. Temporary Data Storage

In this example, we are going to implement a temporary data storage that should perform the following functions:

Add the given data by key
Retrieve the data by key
Remove the data by key

Such temporary data storage can be useful in various scenarios, including:

Tracking the status of asynchronous jobs

For example, if we have a button that sends multiple emails, we can use temporary data storage to block the button and prevent duplicate sends until the job is finished and all emails are sent.

Storing intermediate results during data processing

In data-intensive applications, temporary storage is often used to store intermediate results during data processing pipelines. This enables efficient data transformation, aggregation, or analysis before generating the final output.

Temporary storage for any other purpose

Temporary data storage can be employed for various other use cases where we need to temporarily store data.

To demonstrate this adapter pattern, we will create three different implementations for each Rails environment:

For the Test environment, we will create a Memory-Based Temporary Data Storage.
For the Development environment, we will create an ActiveRecord-Based Temporary Data Storage.
For the Production environment, we will create a Redis-Based Temporary Data Storage.

Let's proceed with implementing each of them to gain a better understanding of the main purpose behind the adapter pattern.

Memory-Based Temporary Data Storage

The first solution will be the simplest one - we will create a Memory-Based Temporary Data Storage using a Ruby Hash. We will only use this solution for testing purposes, so we don't need to be concerned about data storage reliability.

First, let's add a new adapter file and define the common interface:

# app/adapters/temporary_data_store_adapter/memory.rb

# frozen_string_literal: true

module TemporaryDataStoreAdapter
  class Memory

    def set(key, value)
    end

    def get(key)
    end

    def delete(key)
    end

  end
end

For our data storage, we have defined three required methods:

set
get
delete

Now, let's implement these methods:

# app/adapters/temporary_data_store_adapter/memory.rb

# frozen_string_literal: true

module TemporaryDataStoreAdapter
  class Memory

    def initialize
      @store = {}
    end

    def set(key, value)
      @store[key.to_s] = value.to_json
      'OK'
    end

    def get(key)
      return nil unless (value = @store[key.to_s])

      JSON.parse(value)
    end

    def delete(key)
      return nil unless (value = @store[key.to_s])

      @store.delete key.to_s
      JSON.parse(value)
    end

  end
end

Let's check how it actually works in the Rails console:

# rails c

adapter = TemporaryDataStoreAdapter::Memory.new
# =>  #<TemporaryDataStoreAdapter::Memory:0x00000001166b1b80 @store={}>

adapter.set('key', {example: 'example'})
# => "OK"
adapter.get('key')
# => {"example"=>"example"}
adapter.delete('key')
# => {"example"=>"example"}
adapter.get('key')
# => nil

That's it!

P.S. It also makes sense to add a clear method to remove all data from the Hash. You can run this command after every test that uses this adapter to avoid any global value problems in the specs:

def clear
  @store.clear
end

ActiveRecord-Based Temporary Data Storage

Our second implementation of Temporary Data Storage utilizes ActiveRecord. I have mainly added this implementation to enhance our understanding of the Adapter concept, rather than for real-life usage.

Firstly, to use ActiveRecord, we need to create a new model and generate a migration to set up the data storage. Let's create the following model:

# app/models/temporary_data_entry.rb

# frozen_string_literal: true

class TemporaryDataEntry < ApplicationRecord
end

And the corresponding migration:

# db/migrate/20230714142730_create_temporary_data_entries.rb

class CreateTemporaryDataEntries < ActiveRecord::Migration[7.0]
  def change
    create_table :temporary_data_entries do |t|
      t.string :key, null: false
      t.json :data

      t.timestamps
      t.index :key, unique: true
    end
  end
end

Afterward, execute the following command:

rails db:migrate

Now, everything is set up, and we can proceed to create a new adapter. Let's take a look at how this adapter will be implemented:

# app/adapters/temporary_data_store_adapter/active_record.rb

# frozen_string_literal: true

module TemporaryDataStoreAdapter
  class ActiveRecord

    def set(key, data)
      temp_data_entry = TemporaryDataEntry.find_by(key: key)

      if temp_data_entry.present?
        temp_data_entry.update(data: data)
      else
        TemporaryDataEntry.create(key: key, data: data)
      end
      'OK'
    end

    def get(key)
      TemporaryDataEntry.find_by(key: key)&.data
    end

    def delete(key)
      TemporaryDataEntry.find_by(key: key)&.delete&.data
    end

  end
end

Let's test these methods in the console:

# rails c


adapter = TemporaryDataStoreAdapter::ActiveRecord.new
# => #<TemporaryDataStoreAdapter::ActiveRecord:0x000000010ec64800>
adapter.set('key', {example: 'example'})
# => "OK"
adapter.get('key')
# => {"example"=>"example"}
adapter.delete('key')
# => {"example"=>"example"}
adapter.get('key')
# => nil

That's it.

Redis-Based Temporary Data Storage

Our final implementation will be based on Redis. First of all, let's install the Redis gem and ensure that we are connected to the server. Add the following gem to your Gemfile:

# Gemfile 

gem 'redis'

Then execute:

bundle install

Next, start the Redis server and verify if the connection is successful:

# REDIS_URL='redis://127.0.0.1:6379'
# rails c 

Redis.new(url: ENV.fetch('REDIS_URL')).info
# => {"redis_version"=>"7.0.5" ... }

As we can see, the Redis connection is successful. Now, let's proceed with adding a new Redis-based temporary data storage adapter:

# app/adapters/temporary_data_store_adapter/redis.rb

# frozen_string_literal: true

module TemporaryDataStoreAdapter
  class Redis

    def set(key, value)
      redis.set key, value.to_json
    end

    def get(key)
      return nil unless (value = redis.get(key))

      JSON.parse(value)
    end

    def delete(key)
      return nil unless (value = redis.getdel(key))

      JSON.parse(value)
    end

    private

    def redis
      @redis ||= ::Redis.new(url: ENV.fetch('REDIS_URL'))
    end

  end
end

Let's check if it works:


adapter = TemporaryDataStoreAdapter::Redis.new
# =>  #<TemporaryDataStoreAdapter::Redis:0x0000000112017c60>

adapter.set('key', {example: 'example'})
# => "OK"
adapter.get('key')
# => {"example"=>"example"}
adapter.delete('key')
# => {"example"=>"example"}
adapter.get('key')
# => nil

That's it. All adapters have been successfully added. Now, let's take a look at how we can choose the one that is suitable for our needs.

Initialize Adapter

We're going to use different adapters depending on the Rails environment:

For the TEST environment, we'll use the Memory-Based Temporary Data Storage Adapter.
For the DEVELOPMENT environment, we'll use the ActiveRecord-Based Temporary Data Storage Adapter.
For the PRODUCTION environment, we'll use the Redis-Based Temporary Data Storage Adapter.

To solve this problem, we'll initialize each adapter in their respective environments in the config/environments directory:

Memory-Based Temporary Data Storage Adapter

# config/environments/test.rb

# frozen_string_literal: true

Rails.application.configure do
  # ...
  config.after_initialize do
    config.temporary_data_store_adapter = TemporaryDataStoreAdapter::Memory.new
  end
end

ActiveRecord-Based Temporary Data Storage Adapter

# config/environments/development.rb

# frozen_string_literal: true

Rails.application.configure do
  # ...
  config.after_initialize do
    config.temporary_data_store_adapter = TemporaryDataStoreAdapter::ActiveRecord.new
  end
end

Redis-Based Temporary Data Storage Adapter

# config/environments/production.rb

# frozen_string_literal: true

Rails.application.configure do
  # ...
  config.after_initialize do
    config.temporary_data_store_adapter = TemporaryDataStoreAdapter::Redis.new
  end
end

Once initialized, we can call this adapter like this:

# rails c

Rails.application.config.temporary_data_store_adapter
# => #<TemporaryDataStoreAdapter::ActiveRecord:0x0000000114816ec8>

However, this doesn't look too convenient, so let's add a wrapper:

# app/adapters/adapter.rb

# frozen_string_literal: true

module Adapter
  class << self

    def method_missing(method, *args, &block)
      Rails.application.config.public_send("#{method}_adapter")
    rescue NameError
      super
    end

  end
end

Now, we can call the adapter like this:

# rails c -e development

Adapter.temporary_data_store
# => #<TemporaryDataStoreAdapter::ActiveRecord:0x0000000107634c98>

# rails c -e test

Adapter.temporary_data_store
# => #<TemporaryDataStoreAdapter::Memory:0x00000001101743a8 @store={}>

# rails c -e production

Adapter.temporary_data_store
# => #<TemporaryDataStoreAdapter::Redis:0x0000000112ef9698>

That's it. We now have an identical interface, and our previous incompatible solution becomes interchangeable.

Example 3. Datadog.

In the last example, we will add an Abstract Monitoring Adapter to consolidate what we've already learned. Let's imagine that we have DataDog monitoring, and we want to disable it for the development and test environments. How would we do it? Let's create the following:

# app/adapters/monitoring_adapter/datadog.rb

# frozen_string_literal: true

module MonitoringAdapter
  class Datadog

    def call
      puts 'Send a real API request to DataDog'
    end

  end
end

And the Fake one:

# frozen_string_literal: true

module MonitoringAdapter
  class Fake

    def call
      puts 'Pretend that the request to DataDog has been sent'
    end

  end
end

Let's initialize them:

Fake

# config/environments/test.rb

# frozen_string_literal: true

Rails.application.configure do
  # ...
  config.after_initialize do
    config.monitoring_adapter = MonitoringAdapter::Fake.new
  end
end

Datadog

# config/environments/production.rb

# frozen_string_literal: true

Rails.application.configure do
  # ...
  config.after_initialize do
    config.monitoring_adapter = MonitoringAdapter::Datadog.new
  end
end

And let's check:

# rails c -e production

Adapter.monitoring.call
# => Send a real API request to DataDog

# rails c -e test

Adapter.monitoring.call
# => Pretend that the request to DataDog has been sent

That's it.

Conclusion

In summary, the adapter pattern proves to be a valuable tool in Rails applications, enabling the integration of components with different interfaces without modifying existing code. By creating adapter classes for each component, we can achieve a common interface and easily switch between implementations. This approach enhances code maintainability, reduces complexity, and improves testability by isolating components and providing clear contracts. With adapters, developers can seamlessly integrate external libraries or services, adapt to legacy systems, and handle compatibility issues efficiently.

How to add Feature Flags in Ruby on Rails?

Vlad Hilko — Wed, 12 Jul 2023 11:21:05 +0000

Overview

In this article, we are going to delve into the area of Feature Flags. We will explain what a feature flag is, why we need it, and how we can use it. We will discuss how to create feature flags and explore the advantages and disadvantages they offer. Additionally, we will explore different feature release strategies that can be safely employed in your Rails application. Finally, we will consider various improvements that can be applied to enhance the reliability of feature flags.

Definition

In simple terms, a feature flag is a technique used in software development to enable or disable specific features at runtime. Feature flags act as switches that control the availability and visibility of certain features within an application without the need for redeploying or modifying the code. Using feature flags has its pros and cons, let's consider them:

Advantages:

Risk Mitigation

Easily disable features in case of unexpected problems or errors.

A/B Testing and Experimentation

Conduct experiments and compare different feature variations to make informed decisions.

Controlled Rollouts

Allows testing the feature on different platforms (staging/sandbox) before enabling it in production.

Speed of merging

Developers can work on small pull requests that are merged frequently into the main code branch.

Problems:

Increased Complexity

Increases code loading and cognitive load due to the need for additional conditional checks in the code.

Technical Debt

If feature flags are not appropriately managed and cleaned up, they can become deprecated or unnecessary, resulting in increased code complexity and maintenance overhead.

Testing Overhead

The presence of multiple feature variations requires thorough testing of each flag's behavior and interactions, potentially increasing the testing effort and complexity.

It's important to remember that a feature flag is a temporary solution that should be removed after the feature is fully implemented, tested, delivered, and approved by clients.

Implementation

We're going to use the flipper gem. Let's take a look at how to use it properly.

Installation

First of all, we need to install this gem.

# Gemfile

gem 'flipper'

And then execute:

bundle

The gem provides interfaces for the following most important features:

Enabling/Disabling the feature
Checking if the feature is enabled or not
Showing the list of all features

# rails c 

Flipper.features
# #<Set: {}>
Flipper.enable :search
# #<Set: {#<Flipper::Feature:72040 name=:search, state=:on, enabled_gate_names=[:boolean], adapter=:memoizable>}>
Flipper.enabled? :search
# true
Flipper.disable :search
# #<Set: {#<Flipper::Feature:72040 name=:search, state=:off, enabled_gate_names=[], adapter=:memoizable>}>
Flipper.enabled? :search
# false

The problem with the current approach is that the data stored in memory will be lost after reloading the Rails console. Therefore, we need to determine where exactly we want to store this data. Flipper provides several available options for storing the value, called adapters. In this case, we're going to use flipper-active_record as it is the most familiar one.

Add ActiveRecord adapter

To use the ActiveRecord adapter, we need to install the gem:

# Gemfile

gem 'flipper-active_record'

And then execute:

bundle

After the gem is installed, we need to generate a migration where our data will be stored:

rails g flipper:active_record

And then execute:

rails db:migrate

Let's see how it works in the Rails console:

# rails c 

Flipper.features
# #<Set: {}>
Flipper.enable :search
# This command creates the following records in the database:

# [
#   #<Flipper::Adapters::ActiveRecord::Feature:0x000000011672da78
#   id: 1,
#   key: "search",
#   created_at: Sun, 09 Jul 2023 13:08:14.499774000 UTC +00:00,
#   updated_at: Sun, 09 Jul 2023 13:08:14.499774000 UTC +00:00>
# ]
# [
#   #<Flipper::Adapters::ActiveRecord::Gate:0x00000001166ddbb8
#   id: 1,
#   feature_key: "search",
#   key: "boolean",
#   value: "true",
#   created_at: Sun, 09 Jul 2023 13:08:14.527445000 UTC +00:00,
#   updated_at: Sun, 09 Jul 2023 13:08:14.527445000 UTC +00:00>
# ]

Flipper.enabled? :search
# true

That's it.

Feature Release Strategies

Feature release strategies refer to the approaches and techniques used to release new features or updates in software development.

Here are some common feature release strategies:

Big Bang Release
Incremental Release
Feature Flags/Toggles
Canary Release
Phased Rollout
Fault tolerance

We will discuss these strategies using a simple abstract example of changing the background color of our website to red. Let's take a closer look at each of them and provide examples of their implementation in Ruby.

Big Bang Release

The Big Bang Release strategy states that all changes need to be deployed at once as a single, comprehensive update. This strategy does not require the use of feature flags. For example, if you had the following code in your application:

# change_background_color.rb

ChangeBackgroundColor.call('blue')

The Big Bang Strategy will replace this code all at once wherever it is used, in a single move

# change_background_color.rb

ChangeBackgroundColor.call('red')

Incremental Release

The Incremental Release strategy states that you should deliver your code piece by piece to catch possible errors as soon as possible. For example, if we have the following code:

# change_background_color_1.rb

ChangeBackgroundColor1.call('blue')

and

# change_background_color_2.rb

ChangeBackgroundColor2.call('blue')

The Incremental Release Strategy suggests updating and deploying the first file first, and only after that, update and deploy the second one. For example, in the first deployment, we update the first file as follows:

# change_background_color_1.rb

ChangeBackgroundColor1.call('red')

Then, in the second deployment, we update the second file as follows:

# change_background_color_2.rb

ChangeBackgroundColor2.call('red')

So, when we have multiple changes, they should be split and gradually updated and deployed.

Feature Flags/Toggles

This is the first strategy where Feature Flags fit perfectly. In this strategy, we choose the behavior depending on whether the feature flag is enabled or not:

# change_background_color.rb

if Flipper.enabled? :red_background_color
  ChangeBackgroundColor.call('red')
else
  ChangeBackgroundColor.call('blue')
end

It allows us to disable the feature if something goes wrong.

Canary Release

The Canary Release Strategy allows us to enable a feature for specific percentages of users. This enables us to perform slow rollouts. For example, if we want to enable the feature only for one user, we can do the following:

user = User.first

Flipper.enabled?(:red_background_color)
# => false
Flipper.enabled?(:red_background_color, user)
# => false

Flipper.enable(:red_background_color, user)

Flipper.enabled?(:red_background_color)
# => false

Flipper.enabled?(:red_background_color, user)
# => true

But if we want to enable the :red_background_color feature for only 25% of users, we need to do the following:

Flipper.enable_percentage_of_actors(:red_background_color, 25)

user = User.first

Flipper.enabled?(:red_background_color, user)

# => true/false

Please note that you can read more about how the algorithm actually works here.

Phased Rollout

The Phased Rollout Strategy allows us to enable a feature for specific groups, such as by country, role, or status etc. To enable this feature, we need to define the criteria or conditions for determining when the enabling should occur:

user = User.first 
# => <User id: 1, role: "admin">

Flipper.register(:admins) do |actor, context|
  actor.respond_to?(:role) && actor.role == 'admin'
end

Flipper.enable_group(:red_background_color, :admins)

Flipper.enabled?(:red_background_color, user)
# true

Let's consider another example where we want to enable the feature for all users from the USA. It would look like this:

user = User.first 
# => <User id: 1, country: "USA">

Flipper.register(:from_usa) do |actor, context|
  actor.respond_to?(:country) && actor.country == 'USA'
end

Flipper.enable_group(:red_background_color, :from_usa)

Flipper.enabled?(:red_background_color, user)
# => true

However, we have one problem. Where should we store Flipper.register(:admins)? Since we don't save the value of the block in the database, this block should be placed somewhere at the configuration level. Let's add it to the initializer:

# config/initializers/flipper.rb

# frozen_string_literal: true

require 'flipper'

Rails.application.reloader.to_prepare do
  Flipper.register(:admins) do |actor, context|
    actor.respond_to?(:role) && actor.role == 'admin'
  end
end

That's it.

Fault Tolerance

In this strategy, we run the new version of the code, but if something unexpected happens, we fallback to the previous version. It can be implemented as follows:

begin
  ChangeBackgroundColor.call('red')
rescue UnexpectedError
  ChangeBackgroundColor.call('blue')
end

Improvements

Our solution is not perfect; there is still some room for improvement. Let's explore how we can enhance the following aspects:

Removing the feature flag
Optimizing requests using caching
Providing a user interface (UI)
Adding an API
Adding validations for Feature Flags
Including information about the Feature Flags
Improving Spec Performance

Removing the feature flag

It's important to remember that every feature flag is a temporary solution for safe rollouts, and sooner or later they should be removed from the codebase. How can we do it? To remove a Feature Flag, we need to follow these steps:

Flipper.remove(:red_background_color)
# => true

Optimizing requests using caching

To optimize the retrieval of feature flag information and avoid unnecessary database calls, Flipper provides the option to enable caching. To implement caching, you need to install the flipper-active_support_cache_store gem by adding it to your Gemfile:

# Gemfile

gem 'flipper-active_support_cache_store'

After adding the gem, you need to update the configuration file as follows:

# config/initializers/flipper.rb

# frozen_string_literal: true

require 'flipper/adapters/active_record'
require 'flipper/adapters/active_support_cache_store'

Rails.application.reloader.to_prepare do
  Flipper.configure do |config|
    config.adapter do
      Flipper::Adapters::ActiveSupportCacheStore.new(
        Flipper::Adapters::ActiveRecord.new,
        ActiveSupport::Cache::MemoryStore.new,
        expires_in: 5.minutes
      )
    end
  end
end

With this configuration in place, you can now check if a feature is enabled without triggering a database call for the next 5 minutes:

# rails console

Flipper.enabled?(:red_background_color)
# triggers a database call

Flipper.enabled?(:red_background_color)
# does not trigger a database call

Providing a user interface (UI)

To add a user interface (UI) for managing feature flags, you can follow these steps:

Add the flipper-ui gem to your application's Gemfile:

# Gemfile

gem 'flipper-ui'

Execute the bundle command to install the gem:

bundle

Update your config/routes.rb file to mount the Flipper UI:

# config/routes.rb

YourRailsApp::Application.routes.draw do
  mount Flipper::UI.app(Flipper) => '/flipper'
end

After updating the routes, the new UI will be available at http://localhost:3000/flipper (assuming your application is running on localhost and port 3000). You can find more information about using the Flipper UI here.

Adding an API

What if you want to expose the list of feature flags as an API? This can be useful when your client and API are separated, making it easier to retrieve the data. To add the Flipper API to your project, follow these steps:

First, install the flipper-api gem by adding it to your Gemfile:

# Gemfile

gem 'flipper-api'

Next, execute the bundle command to install the gem:

bundle

Update your config/routes.rb file to include the Flipper API:

# config/routes.rb

YourRailsApp::Application.routes.draw do
  mount Flipper::Api.app(Flipper) => '/flipper/api'
end

With this configuration, you can make a GET request to http://localhost:3000/flipper/api/features to retrieve the list of feature flags. The response will be in JSON format, as shown below:

{
  "features":[
    {
      "key":"red_background_color",
      "state":"on",
      "gates":[
        {
          "key":"boolean",
          "value":"true",
          "name":"boolean"
        },
        {
          "key":"actors",
          "value":[

          ],
          "name":"actor"
        },
        {
          "key":"percentage_of_actors",
          "value":null,
          "name":"percentage_of_actors"
        },
        {
          "key":"percentage_of_time",
          "value":null,
          "name":"percentage_of_time"
        },
        {
          "key":"groups",
          "value":[

          ],
          "name":"group"
        }
      ]
    }
  ]
}

For more details on adding an API, refer to the Flipper documentation here

Adding validations for Feature Flags

As you may have noticed, our current implementation allows adding flags with any names and removing flags without restrictions. However, this approach is not reliable, as someone could make a typo and mistakenly enable/disable the wrong flag or accidentally remove a flag that is actively being used in production. Let's explore a possible solution to prevent such issues.

First, we can create a value object to keep track of all available feature flags. This will help us ensure that only valid flags are used. Let's create the FeatureFlag value object:

# app/value_objects/feature_flag.rb

# frozen_string_literal: true

class FeatureFlag

  class << self

    def all
      [
        'search',
        'red_background_color'
      ]
    end

    def supported?(flag_name)
      all.include?(flag_name.to_s)
    end

  end

end

This value object provides a list of all available feature flags and allows us to check if a specific flag is supported:

FeatureFlag.all
# => ['search', 'red_background_color']
FeatureFlag.supported?(:red_background_color)
# => true

Next, we can create a custom adapter that will enforce the availability of feature flags before enabling or adding them. The adapter can be implemented as follows:

# lib/feature_flags/adapters/active_record_based.rb

# frozen_string_literal: true

require 'flipper'

module FeatureFlags
  module Adapters
    class ActiveRecordBased < Flipper::Adapters::ActiveRecord

      def add(feature)
        return false unless supported_feature_flag?(feature.name)

        super
      end

      def enable(feature, gate, thing)
        return false unless supported_feature_flag?(feature.name)

        super
      end

      def remove(feature)
        return false if supported_feature_flag?(feature.name)

        super
      end

      private

      def supported_feature_flag?(feature)
        FeatureFlag.supported?(feature)
      end

    end
  end
end

In this adapter, we check if the given feature flag is supported before performing actions such as adding, enabling, or removing it.

To include this custom adapter in the Flipper configuration, we can update the initializer file:

# config/initializers/flipper.rb

# frozen_string_literal: true

require 'flipper/adapters/active_record'

Rails.application.reloader.to_prepare do
  Flipper.configure do |config|
    config.adapter { FeatureFlags::Adapters::ActiveRecordBased.new }
  end
end

Now, with these validations in place, the restrictions prevent performing actions with unsupported flags:

Flipper.enable(:not_supported)
# => false
Flipper.enable(:red_background_color)
# => true
Flipper.remove(:red_background_color)
# => false

Including information about the Feature Flags

As we mentioned earlier, feature flags should eventually be removed. It would be beneficial to have more information about each flag beyond just the name. Let's add additional fields to the feature flag value object, such as:

Description
Expected expiration date
Owner

To achieve this, we can update the FeatureFlag value object:

# frozen_string_literal: true

class FeatureFlag

  class << self

    def all
      [
        {
          name: 'search',
          description: 'Search description',
          expected_expiration_date: 2024-01-01,
          owner: 'Backend team'
        },
        {
          name: 'red_background_color',
          description: 'Red background color description',
          expected_expiration_date: 2024-01-02,
          owner: 'Frontend team'
        }
      ]
    end

    def supported?(flag_name)
      all.map { _1[:name] }.include?(flag_name.to_s)
    end

  end

end

Now, each feature flag includes additional information such as description, expected expiration date, and owner.

Note: You can also consider defining constants in a YAML file to simplify the interface and keep the information organized.

Improving Spec Performance

To improve the performance of your tests, it is recommended to avoid unnecessary database hits when working with feature flags. You can achieve this by replacing the Active Record adapter with the Memory Adapter for your test environment.

Here's what you need to do:

Update your config/initializers/flipper.rb file as follows:

# config/initializers/flipper.rb

# frozen_string_literal: true

require 'flipper/adapters/active_record'

Rails.application.reloader.to_prepare do
  Flipper.configure do |config|
    config.adapter do
      Rails.env.test? ? Flipper::Adapters::Memory.new : Flipper::Adapters::ActiveRecord.new
    end
  end
end

With this configuration, the Memory Adapter will be used for the test environment, while the Active Record Adapter will be used for other environments.

Now, when you run rails console in the test environment (rails c -e test), you can verify that the database is not being triggered when working with feature flags:

# rails c -e t

Flipper.enable(:red_background_color)
Flipper.enable?(:red_background_color)

This change will help improve the performance of your test suite by eliminating unnecessary database hits.

Conclusion

In this article, we've been diving deep into the world of feature flags. We explored the benefits of using feature flags, including risk mitigation, A/B testing, controlled rollouts, and faster development cycles.

We discussed different feature release strategies, such as the Big Bang Release, Incremental Release, Feature Flags/Toggles, Canary Release, Phased Rollout, and Fault Tolerance. Each strategy offers a unique approach to releasing new features or updates, providing flexibility and control over the rollout process.

To enhance our feature flag implementation, we made several improvements. We added validations to ensure that only supported flags can be enabled or added, preventing potential errors. We integrated caching to optimize performance by reducing unnecessary database hits. Additionally, we explored the options of providing a user interface and adding an API to expose feature flag information to clients.

How to add Concern in Ruby on Rails?

Vlad Hilko — Fri, 07 Jul 2023 15:56:45 +0000

Overview:

In this article, we will discuss the usage of ActiveSupport::Concern. We will delve into what it is, why we need it, and the problems it can solve. Additionally, we will explore the pros and cons associated with its usage. To illustrate its practical implementation, we will provide three examples.

Definition:

In simple terms, Concern allows you to extract common logic from different models into a reusable module. You may ask, "Why can't we just use a module? Why do we need to define something else?" Here are the main differences: Essentially, Concern is an ordinary module, but it allows you to include any ActiveRecord behaviors that you can define on the model. Therefore, we can consider it as a module for encapsulating and reusing ActiveRecord methods.

Advantages:

Code Reusability: ActiveSupport Concern allows us to follow the DRY principle by extracting common logic into reusable modules.

Problems:

Complex Dependencies: Overusing concerns can result in a complex web of dependencies, making the code harder to understand and maintain.
Difficulty in Code Search: Finding the definition of a specific behavior or functionality can be more challenging due to the dispersed nature of concerns.

In essence, concerns are well-suited for storing technical components, such as:

Adding file helpers to facilitate handling files with a clear interface.
Creating wrappers for existing attributes and values to enhance interface clarity.
Implementing technical features like change history tracking, logging, and more.
etc...

However, concerns are not well suitable for storing business logic.

Implementation

In the following section, we will discuss the key elements of concerns. To understand concerns, we only need to know what a module is and the included and class_methods methods from ActiveSupport::Concern.

Module

A module in Ruby is a container that groups together related methods, constants, and other module or class definitions. It provides a way to organize and reuse code in a modular manner. And Сoncern is just a module, so we need to know how to create it.

# app/models/concerns/concern_sample.rb

# frozen_string_literal: true

module ConcernSample
  def hello_world
    puts 'Hello World!'
  end
end

ActiveSupport::Concern methods

So, what is the main difference between a simple Ruby module and a concern? The main differences are that when you include ActiveSupport::Concern in a module, two new methods are added. These methods are:

included

This method enables us to add Active Record logic directly to the module and reuse it at the model level. For example:

# app/models/concerns/concern_sample.rb

# frozen_string_literal: true

module ConcernSample
  extend ActiveSupport::Concern

  included do
    # Define class methods here
    def self.my_class_method
      # Class method logic
    end

    # Define instance methods here
    def my_instance_method
      # Instance method logic
    end

    # Define associations here
    has_many :comments
    belongs_to :category

    # Define validations here
    validates_presence_of :name
    validates_uniqueness_of :email

    # Define callbacks here
    before_save :do_something
    after_create :do_something_else

    # Define scopes here
    scope :active, -> { where(active: true) }
    scope :recent, -> { order(created_at: :desc) }
  end
end

class_methods

This method allows us to add methods that can be called from the class itself:

# app/models/concerns/concern_sample.rb

# frozen_string_literal: true

module ConcernSample
  extend ActiveSupport::Concern

  class_methods do
    def my_class_method
      # Class method logic
    end
  end
end

Let's consider three examples to gain a better understanding of this concept.

Example 1: FullDescription.

In the first example, we will consider a very basic scenario to gain an understanding of how this actually works. For instance, let's assume we have the following model:

# app/models/animal.rb

class Animal < ApplicationRecord
end

Then we decided to add a method to the model that would provide the full description of this animal.

# app/models/animal.rb

class Animal < ApplicationRecord
  def full_description
    "Name: #{name}. Kind: #{kind}. Status: #{status}."
  end
end

Here's how it works:

animal = Animal.first
animal.full_description
# => "Name: Simba. Kind: Cat. Status: Adopted"

animal = Animal.second
animal.full_description
# => "Name: Rocky. Kind: Rabbit. Status: Available"

What do we need to do if we want to move this logic to the concern? First of all, we need to create a new concern:

# app/models/concerns/full_description.rb

# frozen_string_literal: true

module FullDescription
  def full_description
    "Name: #{name}. Kind: #{kind}. Status: #{status}"
  end
end

And include this concern at the model level:

# app/models/animal.rb

class Animal < ApplicationRecord
  include FullDescription
end

So the same interface is still available:

animal = Animal.first
animal.full_description
# => "Name: Simba. Kind: Cat. Status: Adopted"

We didn't include ActiveSupport::Concern here just to highlight that for simple methods without ActiveRecord logic, it will still work fine. However, it will also work with ActiveSupport::Concern:

# app/models/concerns/full_description.rb

# frozen_string_literal: true

module FullDescription
  extend ActiveSupport::Concern

  included do
    def full_description
      "Name: #{name}. Kind: #{kind}. Status: #{status}."
    end
  end

end

Like this:

animal = Animal.first
animal.full_description
# => "Name: Simba. Kind: Cat. Status: Adopted."

And if you want to add class methods, we can do the following:

# app/models/concerns/full_description.rb

# frozen_string_literal: true

module FullDescription
  extend ActiveSupport::Concern

  class_methods do
    def full_description
      all.map { _1.full_description }.join(' ')
    end
  end

end

Now the full_description method is available on the Animal class:

Animal.full_description
# => "Name: Simba. Kind: Cat. Status: Adopted. Name: Rocky. Kind: Rabbit. Status: Available."

Example 2: UUID

In the second example, we will create a concern that generates and saves a unique UUID value before creating a new database record. To achieve this, we will define a new concern as follows:

# app/models/concerns/uuid.rb

# frozen_string_literal: true

module UUID
  extend ActiveSupport::Concern

  included do
    before_create :set_uuid

    private

    def set_uuid
      self.uuid ||= SecureRandom.uuid
    end
  end
end

And we will include it at the model level:

# app/models/animal.rb

class Animal < ApplicationRecord
  include UUID
end

Then, every time we create a new Animal record in the database, the UUID will be automatically generated for us:

animal = Animal.create
animal.uuid
# => '7f934646-bc67-446c-920d-ca5415d28b94'

P.S. To use the UUID acronym, you need to add the following code to config/initializers/inflections.rb:

# config/initializers/inflections.rb

ActiveSupport::Inflector.inflections do |inflect|
  inflect.acronym 'UUID'
end

Example 3: PredicateMethods

In the last example, let's consider adding a concern that allows us to simplify the interface for attributes with a fixed number of available values. For instance, if an animal record has a status attribute with the following available values: ['available', 'adopted', 'pending'], then we would like to have the following interface:

animal = Animal.create(status: 'available')

animal.available?
# => true
animal.adopted?
# => false
animal.pending?
# => false 

# or with prexix

animal.status_available?
# => true
animal.status_adopted? 
# => flase

# etc ..

What do we need to do to implement it? Let's create a new concern called PredicateMethods and add its method to the model:

# app/models/animal.rb

class Animal < ApplicationRecord
  include PredicateMethods

  define_predicate_methods attribute: :status,
                           available_values: ['available', 'adopted', 'pending'],
                           prefix: false
end

So how is this concern implemented? It's quite simple. We just need to define a new method called define_predicate_methods, and this method will generate new methods on the model for every available value that you pass as an argument. Inside this method, we will check if the current status value is equal to the given value or not. Here's the implementation:

# app/models/concerns/predicate_methods.rb

# frozen_string_literal: true

module PredicateMethods
  extend ActiveSupport::Concern

  MethodAlreadyDefined = Class.new(ArgumentError)

  class_methods do
    def define_predicate_methods(attribute:, available_values:, prefix: false)
      available_values.each do |value|
        method_name = [(prefix ? "#{attribute}_" : ''), value, '?'].join.to_sym
        raise MethodAlreadyDefined, "#{method_name} already defined" if instance_methods.include?(method_name)

        define_method(method_name) do
          public_send(attribute) == value
        end
      end
    end
  end
end

Now our interface works as desired:

animal = Animal.last

animal.available?
# => true
animal.adopted?
# => false

If you'd like to add the status prefix, you just need to change the value of the prefix attribute from false to true:

animal = Animal.last

animal.status_available?
# => true

animal.status_adopted?
# => false

That's it! Now we can add this concern to any of our models and make their interfaces more readable and simplified.

Conclusion

In conclusion, in this article we delved into the usage of ActiveSupport::Concern in Rails. We explored what it was, why we needed it, and the problems it could solve. We examined the pros and cons of utilizing this approach, considering different perspectives. Furthermore, to enhance our understanding of the concept, we provided three examples that illustrated its practical implementation.

Managing Platform-Specific Features in Rails: The Right Way to Customize App Behavior

Vlad Hilko — Wed, 05 Jul 2023 11:07:39 +0000

Overview:

In this article, we will discuss the usage of Platform Settings in a Rails application. We will explore why we need them and the specific problems they aim to solve. Additionally, we will consider four different available options, examining the pros and cons of each. Furthermore, we will fully implement the most suitable approach and explore how to ensure the quality of platform settings through contracts and tests. By the end of the article, we will have a production-ready solution to this problem.

Definition:

In simple terms, platform settings in a Rails application allow us to configure different behaviors for various platforms within the same application. To provide clarity, let's consider three different examples.

Example 1: McDonald's Franchise

Let's imagine that you're creating an application for a McDonald's franchise. After the initial version is ready, they approach you with a request for adjustments specific to another country. These adjustments may include a different menu, enabling specific promotional actions, implementing logic for alcohol sales, and so on. You successfully implement these changes. However, they approach you again, this time requesting adjustments for a third customer who has purchased their own franchise. This scenario prompts you to seek a more generalized solution, as potentially every franchise could have hundreds of differences, and the number of franchise customers can grow rapidly.

Example 2: Betting Sites

Let's consider the example of a betting site. You have created the initial fully functional version of the site. However, after some time, a customer approaches you with a request for changes because they intend to run the site on a different platform in another market with distinct regulatory rules. These changes may include implementing rules that prohibit registration for individuals under 18, sending information about profits to the government, and enforcing restrictions for addicted gamblers, among other requirements. With numerous new markets and diverse regulations, you realize the necessity of developing a robust solution to handle these various issues and simplify your workflow.

Example 3: Digital Banking Service

Let's explore the example of digital banking services. You have developed a bank application that functions effectively within your local market. However, you recognize the opportunity to offer this banking service to other customers, enabling them to create their own banks using your core platform. Consequently, you realize the need to introduce logic that allows for flexibility in accommodating different customers. This realization prompts you to implement platform settings within your application, ensuring the adaptability and customization required to support various banking institutions.

Exploring Implementation Options: Choosing the Right Approach

In this chapter, we will explore four different possible approaches to solving the problems discussed in the previous examples. Let's examine each of them in detail:

Option 1. Create a Separate Branch to Implement the New Logic
Option 2. Applying Conditional Operators
Option 3. Setting Up a Database Configuration Table
Option 4. Adding Platform Settings YAML File Configurations

Option 1. Create a Separate Branch to Implement the New Logic

One possible solution that might initially come to mind is to create a separate branch for each new platform and make all the necessary changes there.

Advantages:

No need to implement additional logic to support platform differentiation.
Code remains clear and does not include unnecessary conditional operators.

Problems:

Synchronization with the core platform:
- Resolving conflicts becomes a complex task when changes overlap in the same location.
- There is a high risk of introducing errors or disrupting functionality.
- Maintenance becomes more challenging.

Option 2. Applying Conditional Operators

The second solution that you can consider is to create multiple if/else conditions directly in the code. For example, something like this:

if platform == "Platform A"
  # Platform A specific code
elsif platform == "Platform B"
  # Platform B specific code
elsif platform == "Platform C"
  # Platform C specific code
# Add more conditions for additional platforms as needed
else
  # Default code for unsupported platforms
end

Advantages:

Straightforward implementation without the need for separate branches.

Problems:

Code complexity and readability:
- The code can become cluttered and harder to understand as the number of platforms and conditions grows.
Maintenance challenges:
- Modifying or adding platform-specific logic requires modifying the main codebase, which can introduce errors and make maintenance more difficult.
Lack of flexibility:
- Adding or removing platforms requires modifying the code, potentially leading to more significant changes and potential regressions.

Option 3. Setting Up a Database Configuration Table

The third option is to create a separate table to store all configurations. For example, if we have platform settings for the admin page, it might look like this:

platform_settings = PlatformSettings.create(
  admin_enabled: true, 
  admin_show_page_1: true,
  admin_show_page_2: true,
  admin_available_pages: ['system', 'companies', 'configurations']
)

platform_settings.admin_enabled
# => true
platform_settings.admin_show_page_1
# => true
platform_settings.admin_show_page_2
# => true
platform_settings.admin_available_pages
# => ['system', 'companies', 'configurations']

Advantages:

Provides a user-friendly interface for managing platform settings.
Offers ease of modification and updates to platform settings configurations.

Problems:

Direct dependency on the database:
- Relying solely on the database for configuration settings may not be the most efficient approach, especially if the settings only need to be set once during the platform's launch.
- Overreliance on the database can potentially impact performance.
- In some cases, it may be necessary to check settings before establishing a database connection.
- Increases complexity in writing tests.

Option 4. Adding Platform Settings YAML File Configurations

The last option, which we are going to implement, is a configuration YAML file. We will create multiple .yml files, similar to this example:

first_platform:
  enabled: true
second_platform:
  enabled: true
third_platform:
  enabled: false

And transform them into an appropriate interface, like this:

platform.enabled?

Advantages:

Provides a clear and accessible interface for working with platform-specific configurations.
Separates configurations from the business logic, consolidating them in one central location.
Offers flexibility for extending and modifying configurations as needed.

Problems:

Requires additional logic to load and parse the YAML files.
Potential for inconsistencies if the YAML files and the codebase are not synchronized.
Platform setting changes can only be performed by developers, restricting customer access to configuration modifications.

Let's examine this option more precisely.

Adding Platform Settings YAML File Configurations. Implementation.

In this chapter, we will explore the implementation of platform settings using a YAML configuration file. As always, we will start with the simplest solution and gradually enhance it. We will begin by implementing the initial solution and then progress to make it more flexible and convenient. Additionally, we will incorporate logic to ensure the validity of our configuration files and explore options for writing specifications for these settings.

Here is our plan:

Creating the basic solution
Improving the basic solution
Adding contracts to guarantee integrity and synchronization
Integrating the solution with tests

Creating the basic solution

Let's explore the basic solution and outline the steps required for its implementation:

Step 1: Add a new environment variable that indicates the current platform.
Step 2: Add YAML files containing configurations for each platform.
Step 3: Develop the necessary code to handle the YAML files and create a suitable interface.

Now, let's begin the implementation process.

Step 1: Add a new environment variable that indicates the current platform.

We need to add CURRENT_PLATFORM to the list of environment variables.

# .env

CURRENT_PLATFORM='first_platform'

Step 2: Add YAML files containing configurations for each platform.

Let's examine the platform settings for the admin, as mentioned earlier, across the three available platforms: first_platform, second_platform, and third_platform. To accomplish this, we need to create a dedicated file named config/settings/platform/admin.yml. In this file, we will define the configuration options.

# config/settings/platform/admin.yml

first_platform:
  enabled: true
  show_page_1: true
  show_page_2: true
  available_pages:
    - system
    - companies
    - configurations
second_platform:
  enabled: true
  show_page_1: false
  show_page_2: false
  available_pages:
    - system
third_platform:
  enabled: false
  show_page_1: false
  show_page_2: false
  available_pages: []

Additionally, let's create a second file for the sake of clarity:

# config/settings/platform/animal.yml

first_platform:
  enabled: true
second_platform:
  enabled: true
third_platform:
  enabled: false

Step 3: Develop the necessary code to handle the YAML files and create a suitable interface.

My objective is to load the content from the YAML files and retrieve data exclusively for the current platform (first_platform). The expected interface should resemble the following:

Settings::Platform::Repository.admin
# => {"enabled"=>true, "show_page_1"=>true, "show_page_2"=>true, "available_pages"=>["system", "companies", "configurations"]}
Settings::Platform::Repository.animal
# => {"enabled"=>true}

Let's explore the necessary steps for implementation:

Step 1: Retrieve a list of all files from the config/settings/platform directory.
Step 2: Iterate through the obtained list and define a class method for each file within the Settings::Platform::Repository, such as Settings::Platform::Repository.admin, Settings::Platform::Repository.animal, and so on.
Step 3: Ensure that the method created in Step 2 returns the YAML file's hash content exclusively for the current platform.
Step 4: Execute these steps within the Rails initializer.

Below is the code implementation:

# frozen_string_literal: true

module Settings
  module Platform
    class Repository

      CONFIG_DIRECTORY = 'config/settings/platform'
      CONFIG_FILE_EXTENSION = '.yml'
      DEFAULT_PLATFORM = 'first_platform'

      class << self

        def load!
          all_platform_settings_config_files.each do |file_path|
            define_platform_setting_method(
              method_name: File.basename(file_path, CONFIG_FILE_EXTENSION),
              content: YAML.load_file(file_path)
            )
          end
        end

        def current_platform
          ENV.fetch('CURRENT_PLATFORM', DEFAULT_PLATFORM)
        end

        private

        def all_platform_settings_config_files
          Dir.glob(File.join(CONFIG_DIRECTORY, "*#{CONFIG_FILE_EXTENSION}"))
        end

        def define_platform_setting_method(method_name:, content:)
          deep_freeze(content)
          define_singleton_method(method_name) { content[current_platform] }
        end

        def deep_freeze(enum)
          enum.freeze.each { |item| item.respond_to?(:each) ? deep_freeze(item) : item.freeze }
        end

      end

    end
  end
end

I have added a load! method to facilitate the initialization process, and I have also included a deep_freeze method to prevent modifications to the hash after initialization.

Let's verify if it works as intended. We will execute the load! method within the Rails configuration before_initialize block, as illustrated below:

# config/initializers/platform_settings.rb

# frozen_string_literal: true

require 'settings/platform/repository'

Rails.application.config.before_initialize do
  Settings::Platform::Repository.load!
end

Now, let's take a look at the updated interface:

Settings::Platform::Repository.admin.fetch('enabled')
# => true
Settings::Platform::Repository.admin.fetch('show_page_1')
# => true
Settings::Platform::Repository.animal.fetch('enabled')
# => true

What can we improve in the interface described above?

There are two main problems with the current implementation:

Problem 1: Requiring the full name every time
Problem 2: Unoptimized interface with hash usage

Let's describe them more precisely.

Problem 1: Requiring the full name every time

In the given example, we have to use Settings::Platform::Repository every time we want to access the platform configuration. This can become cumbersome and repetitive, requiring us to create helper methods each time, such as:

def platform_admin
  @platform_admin ||= Settings::Platform::Repository.admin
end

platform_admin.fetch('enabled')
# => true
platform_admin.fetch('show_page_1')
# => true

However, it can be quite cumbersome and tedious to define these helper methods every time, particularly when dealing with numerous platform settings. It would be ideal if we could find a solution that eliminates the need for creating such helpers altogether.

Problem 2:Unoptimized interface with hash usage

The current implementation utilizes a hash-based interface for accessing the platform settings, which can make the code less readable and more error-prone.

So, what can we do to address this issue? What kind of interface would be more desirable? Ideally, we would like to have a simplified and intuitive interface that allows us to access the platform settings without the need for explicit helper methods. Here's an example of the desired interface:

platform_admin.enabled?
# => true
platform_admin.show_page_1?
# => true 
platform_admin.available_pages
# => ['system', 'companies', 'configurations']

However, I prefer not to have a global variable accessible throughout the entire application. Instead, I would like to include these settings only in the specific context where I actually intend to use them, similar to how we utilize modules or mixins. Therefore, my desired interface should look like this

include Settings::Platform[:admin]

platform_admin.enabled? # => true

Let's delve into the implementation of this approach.

Improving the basic solution

How can we achieve the desired interface above? What do we need? Let's take a closer look. We need to make three improvements:

Improvement 1: Including the module with all platform settings helpers inside.
Improvement 2: Returning an object with the appropriate interface instead of a hash.
Improvement 3: Combining Improvements 1 and 2 together.

Improvement 1: Including the module with all platform settings helpers inside.

Let's consider the following code. In this code, we create a module with our helpers inside so that we can include it instead of defining new helpers every time.

module PlatformAdmin
  def platform_admin
    @platform_admin ||= Settings::Platform::Repository.admin
  end
end

include PlatformAdmin

But this approach is not flexible; we would have to create too many modules for every platform setting file. I'd like these modules to be created automatically just by the platform setting name. How can we do it? Actually, it's quite simple. We need to define a method that will create a new module instance based on the platform name and dynamically define methods inside. Here's how it may look:

# lib/settings/platform/mixin.rb

# frozen_string_literal: true

module Settings
  module Platform
    module Mixin

      def self.platform_module(name)
        Module.new do
          define_method "platform_#{name}".to_sym do
            Settings::Platform::Repository.public_send(name)
          end
        end
      end

    end
  end
end

Now we can do the following:

include Settings::Platform::Mixin.platform_module(:admin)

platform_admin
# => {"show_profit_calculation_page"=>true}

So instead of creating a helper method every time, we can include them via the module.

Improvement 2: Returning an object with the appropriate interface instead of a hash.

Returning the raw hash from the configuration doesn't seem convenient. So let's change it and return a new object that transforms the hash into an object with the appropriate interface. To achieve this, we need to do the following:

Create a separate class that accepts the platform settings name and performs the following actions:
- Loads the platform setting hash by name
- Iterates through every hash key
- Defines suitable methods instead of fetch for every hash key

Here's the implementation:

class PlatformStruct < SimpleDelegator

  def initialize(name)
    super(Settings::Platform::Repository.public_send(name))

    generate_methods
  end

  private

  def generate_methods
    keys.each do |key|
      define_singleton_method(key) { self[key] }
      define_singleton_method("#{key}?") { self[key] }
    end
  end

end

And now we can do the following:

platform_struct = PlatformStruct.new('admin')

platform_struct.enabled
# => true 
platform_struct.enabled?
# => true
platform_struct.available_pages
# => ["system", "companies", "configurations"]

Improvement 3: Combining Improvements 1 and 2 together.

The last step is to combine Improvements 1 and 2 together. We will also change the name from platform_module to [] to make it more readable. Instead of using the Settings::Platform::Repository class, we will use the PlatformStruct class from Improvement 2. Here's the updated code:

# lib/settings/platform/mixin.rb

# frozen_string_literal: true

module Settings
  module Platform
    module Mixin
      def self.[](name)
        Module.new do
          define_method "platform_#{name}".to_sym do
            PlatformStruct.new(name)
          end
        end
      end

      class PlatformStruct < SimpleDelegator

        def initialize(name)
          super(Settings::Platform::Repository.public_send(name))

          generate_methods
        end

        private

        def generate_methods
          keys.each do |key|
            define_singleton_method(key) { self[key] }
            define_singleton_method("#{key}?") { self[key] }
          end
        end

      end
    end
  end
end

And here's our new interface:

include Settings::Platform::Mixin[:admin]
include Settings::Platform::Mixin[:animal]

platform_admin.enabled?
# => true
platform_animal.enabled?
# => true

Adding contracts to guarantee integrity and synchronization

There's still one problem with our approach. What happens if someone makes a mistake and adds incorrect configuration? For example, if the configuration has a different structure or incorrect data types:

first_platform:
  enabled: true
  show_page_1: true
  show_page_2: true
  available_pages:
    - system
    - companies
    - configurations
second_platform:
  enabled: true
  show_page_1: 'yes' # Incorrect data type
  show_page_2: 'no'  # Incorrect data type
third_platform:
  show_page_1: 'enabled' # Incorrect data type
  available_pages: 'Text' # Incorrect data type

That's not appropriate, and we need to ensure that the structure is the same for every platform and that all attributes are mirrored and have valid types. To achieve this, we can use the dry-validation gem, which provides a powerful validation library for Ruby.

To install the dry-validation gem, you can add it to your Gemfile and run bundle install. Here's an example of how to install it:

# Gemfile

gem 'dry-validation'

Contract implementation

Once the gem is installed, we can use it to define a schema for validating the platform settings configuration. The schema will specify the expected structure, attribute types, and any other validation rules.

Here's an example of how we can use dry-validation to define a schema and validate the platform settings configuration:

Admin

# spec/lib/settings/platform/contracts/admin.rb

# frozen_string_literal: true

module Settings
  module Platform
    module Contracts
      class Admin < Dry::Validation::Contract

        schema do
          required(:enabled).filled(:bool)
          required(:show_page_1).filled(:bool)
          required(:show_page_2).filled(:bool)
          required(:available_pages).array(:string, included_in?: %w[system companies configurations])
        end

      end
    end
  end
end

Animal

# spec/lib/settings/platform/contracts/animal.rb

# frozen_string_literal: true

module Settings
  module Platform
    module Contracts
      class Animal < Dry::Validation::Contract

        schema do
          required(:enabled).filled(:bool)
        end

      end
    end
  end
end

After we have defined our contracts, let's test how they actually work by validating some sample data against the schema. Here's an example

Settings::Platform::Contracts::Admin.new.call({show_page_1: 'enabled', available_pages: 'Text'}).errors.to_h
# => { :enabled=>["is missing"], :show_page_1=>["must be boolean"], :show_page_2=>["is missing"], :available_pages=>["must be an array"] }

Settings::Platform::Contracts::Animal.new.call({enabled: true}).errors.to_h
# => {}

Basically, we pass a hash as an argument to the contract, and the contract checks the hash against its defined conditions. If any errors or inconsistencies are found, it will return a result object containing the specific error messages.

Contract validations

To ensure that the configuration data adheres to the defined contracts, we can create a test spec that iterates over all platform settings files and performs the contract validation. Here's how the spec may look:

# spec/lib/settings/platform/contracts_spec.rb

# frozen_string_literal: true

require 'rails_helper'

Dir[Rails.root.join('spec', 'lib', 'settings', 'platform', 'contracts', '**', '*.rb')].sort.each(&method(:require))

RSpec.describe Settings::Platform::Contracts do
  Dir.glob('config/settings/platform/*.yml').each do |settings_file|
    ['first_platform', 'second_platform', 'third_platform'].each do |platform|
      context "when checking #{settings_file} for #{platform}" do
        subject { contract_class.new.call(platform_settings_content).errors.to_h }

        let(:contract_class) { "#{described_class}::#{File.basename(settings_file, '.yml').camelize}".constantize }
        let(:platform_settings_content) { YAML.load_file(settings_file).fetch(platform).deep_symbolize_keys }

        it { is_expected.to be_empty }
      end
    end
  end

  context 'when checking existing spec files' do
    let(:spec_contract_file_name_list) do
      Dir.glob(Rails.root.join('spec', 'lib', 'settings', 'platform', 'contracts', '*.rb'))
        .map { File.basename(_1, '.rb') }
    end

    let(:platform_settings_file_name_list) do
      Dir.glob(Rails.root.join('config', 'settings', 'platform', '*.yml'))
        .map { File.basename(_1, '.yml') }
    end

    it 'every contract is expected to have a matching platform settings file' do
      expect(spec_contract_file_name_list).to match_array(platform_settings_file_name_list)
    end
  end
end

That's it. Now we can be confident that the structure and content of our platform settings are valid. The last aspect I want to highlight is writing specs and manipulating these settings. We aim to make our tests as flexible and straightforward as possible.

Integrating the solution with tests

There are two strategies that we can consider during testing to manipulate the platform settings and obtain different content:

Option 1. Stubbing Platform Settings with Custom Values
Option 2: Overriding ENV Variable to Use Content from Another Platform

Option 1. Stubbing Platform Settings with Custom Values

In this approach, we can use stubbing techniques to override the behavior of the platform settings and return custom values. This allows us to simulate different scenarios and test our code under various configurations. For example, we can stub a specific setting to return a different value than what is defined in the actual configuration file. To make this work, we are going to define a shared context with the following interface:

include_context 'when platform settings are', admin: {
  'enabled' => false,
  'show_page_1' => false,
  'available_pages' => ['system']
}

Here's how we can use it in the spec:

# spec/lib/settings/platform/sample_spec.rb

# frozen_string_literal: true

require 'rails_helper'

RSpec.describe 'Sample' do
  describe '#platform_admin' do
    subject(:platform_admin) { klass.new.platform_admin }

    let(:klass) do
      Class.new do
        include Settings::Platform::Mixin[:admin]
      end
    end

    include_context 'when platform settings are', admin: {
      'enabled' => false,
      'show_page_1' => false,
      'available_pages' => ['system']
    }

    it 'returns correct platform specific values' do
      expect(platform_admin.enabled).to be false
      expect(platform_admin.enabled?).to be false

      expect(platform_admin.show_page_1).to be false
      expect(platform_admin.show_page_1?).to be false

      expect(platform_admin.available_pages).to eq(['system'])
    end
  end
end

In the shared context definition, we stubbed Settings::Platform::Repository by replacing it with a custom hash value that is sent as an argument in the spec.

# spec/support/shared_contexts/platform_settings.rb

# frozen_string_literal: true

RSpec.shared_context 'when platform settings are' do |name_and_settings|
  before do
    name_and_settings.each do |name, settings_data|
      allow(Settings::Platform::Repository).to receive(name).and_return(settings_data)
    end
  end
end

Also, don't forget to include this shared context in spec/rails_helper.rb. This ensures that the shared context is available for all specs in your Rails application.

# spec/rails_helper.rb

require 'support/shared_contexts/platform_settings'

That's it. Now we can test more easily and not depend on the settings.

Option 2: Overriding ENV Variable to Use Content from Another Platform

Another strategy is to override the ENV variable that determines the current platform. By changing the value of the ENV variable, we can force the code to load platform settings from a different platform's configuration file. This approach allows us to test how our code behaves with different platform settings without modifying the actual configuration files. We'll achieve this by utilizing the Climate Controle gem. It allows us to temporarily modify environment variables within the scope of our tests, ensuring that our code behaves correctly under different platform configurations. By using Climate Control, we can simulate different platform environments without affecting the actual system-wide environment variables.

To make it work, we will add metadata named current_platform with the desired platform value. This metadata will be associated with our test example or test suite, depending on how we want to configure it:

# spec/lib/settings/platform/sample_spec.rb

# frozen_string_literal: true

require 'rails_helper'

RSpec.describe 'Sample' do
  describe '#admin' do
    subject(:platform_admin) { klass.new.platform_admin }

    let(:klass) do
      Class.new do
        include Settings::Platform::Mixin[:admin]
      end
    end

    it 'returns correct platform specific values', current_platform: 'third_platform'  do
      expect(platform_admin.enabled).to be false
      expect(platform_admin.enabled?).to be false

      expect(platform_admin.show_page_1).to be false
      expect(platform_admin.show_page_1?).to be false

      expect(platform_admin.available_pages).to eq([])
    end
  end
end

Our current_platform RSpec metadata logic looks like this:

# spec/support/current_platform.rb

# frozen_string_literal: true

RSpec.configure do |config|
  config.around(:example, :current_platform) do |example|
    ClimateControl.modify CURRENT_PLATFORM: example.metadata[:current_platform] do
      example.run
    end
  end
end

Also, don't forget to include it in your spec/rails_helper.rb file.

# spec/rails_helper.rb

require 'support/current_platform'

That's it!

Conclusion

In this article, we have explored the concept of Platform Settings in a Rails application and delved into the reasons behind their necessity. We have identified the specific problems they aim to solve and discussed four different available options to implement them, weighing their respective advantages and disadvantages. Based on our analysis, we have chosen the most suitable approach and implemented it in detail, addressing the issues encountered along the way.

Say Goodbye to Messy Constants: A New Approach to Moving Constants Away from Your Model!

Vlad Hilko — Sun, 30 Apr 2023 09:40:38 +0000

Overview:

In this article, we will discuss the usage of constants in a Rails application. We'll take a deep dive into the existing approaches of defining constants in Rails, including the use of configuration files, initializers, and model files. We'll also examine the pros and cons of each approach.

We'll then provide a better approach to defining constants in Rails. We'll discuss the benefits, including how they can help prevent errors and make it easier to change values throughout the application. We'll also consider best practices for using constants in Rails, such as using meaningful names and limiting the scope of constants.

Finally, we'll implement a production-ready solution that solves most of the problems associated with the standard approach. By the end of the article, we will have a clear understanding of how to use constants in our Rails application and we'will be able to implement a more efficient and effective approach to defining constants.

Definition

In simple terms, a constant is a special kind of value that never changes while a program is running.

What standard options do we have for defining constants in Rails? 🤷🏻‍♂️

When it comes to defining constants in Rails, we have a few standard options to choose from. Let's take a closer look at three of them:

Option 1. Don't define constants at all and just use simple primitive data types such as strings, numbers, or symbols.
Option 2. Define constants within the classes or modules where they are used.
Option 3. Define global constants either in initializers or at the Rails configuration level.

Option 1. Don't define constants at all and just use simple primitive data types such as strings, numbers, or symbols.

As an example, let's consider the following scenario:

def update
  animal = Animal.update(type: 'cat')

  render json: animal
end

In this example, we're just using the string 'cat' instead of defining a new constant. The main advantage of this approach is its simplicity, but there are many potential problems that may appear in the future. Let's discuss them more closely:

Problems:

Typos and errors. When using strings instead of constants, it's easy to make typos or use slightly different string literals, which can lead to errors that are difficult to debug.
Maintenance and refactoring. If you use the same string literal in multiple places throughout your code, it can be difficult to change or update the value later on. This can make your code harder to maintain and refactor.
Inconsistency. If different parts of your code use different string literals to represent the same value, it can lead to inconsistencies and make your code harder to understand.
Lack of systematization. It's not clear to which domain or model this string belongs, nor what other options are available. As a result, everything is scattered throughout the app, leading to disorganization and difficulties in maintenance and modification.

Option 2. Define constants within the classes or modules where they are used.

The second option suggests defining a new constant somewhere on the business logic level, for example, in the model, service, or module. Let's take a look at this code:

# frozen_string_literal: true

class Animal < ApplicationRecord
  TYPES = ['cat', 'dog', 'pig']
  COLORS = ['green', 'red', 'white', 'blue']
end

We've defined a constant array on the model level. It solves some problems that were introduced in Option 1 such as Typos and errors, Inconsistency, and Lack of systematization. However, we still have the following problems:

Problems:

The interface is not user-friendly. You cannot access a green color, for example, by simply doing Animal::COLORS.green. Therefore, you have to define a new constant (for example, COLOR_GREEN = 'green', COLOR_WHITE = 'white') for each color or use a hash.
Having a large number of constants in your model increases the model's complexity and reduces its readability, ultimately making it harder to maintain.
You cannot define and use something that is not related to the business logic in the model. For instance, default system data such as limit, offset, and pagination cannot be defined in the model. This increases cognitive load and you have to always think about the best place to keep such data.
When you define a constant within a class or module in your Rails model, it will only be accessible within that class or module. This can be problematic if you need to use the constant elsewhere in your code, as you may have to duplicate it or use an unattractive model prefix to access it.

Option 3. Define global constants either in initializers or at the Rails configuration level.

In this option, we will consider defining constants at the global level. There are two ways to do it:

Define constants in the initializer file
Define constants in the configuration file

Define constants in the initializer file

We can define the constant in the initializer file, for example in config/initializers/animal.rb:

# config/initializers/animal.rb

TYPES = ['cat', 'dog', 'pig']
COLORS = ['green', 'red', 'white', 'blue']

This way, the constants will be loaded with the Rails application and can be accessed globally throughout the application. The main problems of this approach are:

Non-user-friendly interface
Lack of namespaces
Difficulty in maintenance and scalability

Define constants in the configuration file

To overcome the disadvantages mentioned above, we can try using the following approach: creating separate YAML files containing all of our data for each model. Here's an example:

# config/animal.yml

types:
  - cat
  - dog
  - pig
colors:
  - green
  - red
  - white
  - blue

Then we will load this data in the config/application.rb:


# config/application.rb

# ...
config.animal = YAML.load_file("#{Rails.root}/config/animal.yml")

After that all data will be available by using the following interface:

Rails.configuration.animal

# {"types"=>["cat", "dog", "pig"], "colors"=>["green", "red", "white", "blue"]}

Although it solved some of the problems, it still looks strange. Therefore, we are going to implement a new approach that will gather all the advantages from every approach we discussed here.

A new approach for defining constants

In this section, we'll consider creating a custom approach for defining constants to solve the problems that were mentioned above. We will start by gathering requirements, then we will define the interface. After that, we will implement three approaches to show the evaluation from the simplest to the production-ready approach.

Requirements

Let's describe what we want to achieve in the end. Our custom constant should meet the following 5 requirements:

The constant should be available globally.
The constant should have a clear and straightforward interface.
The constant should be easily extendable and maintainable.
The constant should be frozen and not modifiable after initialization.
The constant should be namespaced to avoid overwriting.

Interface

What interface do we want for our custom implementation? Personally, I would like to have something that looks like Rails.configuration.animal from Option 3 that we discussed earlier, but with 4 additional features:

Direct access to any array element:

Rails.configuration.animal.types.cat
# => cat
Rails.configuration.animal.types.dog
# => dog

Ability to return all values from the defined array:

Rails.configuration.animal.types.values
# => ['cat', 'dog', 'pig']
Rails.configuration.animal.colors.values
# => ['green', 'red', 'white', 'blue']

Using a name that is related to constant instead of Rails.configuration:

Constants.animal.types.cat
# => cat

Keep constants namespaced for each separated model:

Constants.animal.types.cat
# => cat 
Constants.car.types.truck
# => truck

Putting it all together, we get the following interface:

Constants.animal.types.cat
# => cat 
Constants.animal.colors.green
# => green
Constants.car.types.truck
# => truck
Constants.animal.colors.values
# => ['green', 'red', 'white', 'blue']
Constants.car.types.values
# => ['sedan', 'minivan', 'truck']

Implementation

We'll look at three different options for addressing the issue, beginning with the most straightforward and ending with the most comprehensive solution.

Option 1. One class/module that contains all the methods.

In this option, we will initiate a new module called Constants and add methods for each model that will return us OpenStruct objects with all required data. So, we would have something like this:

# lib/constants.rb

# frozen_string_literal: true

module Constants
  def self.animal
    types = {
      cat: 'cat',
      dog: 'dog',
      pig: 'pig'
    }

    colors = {
      green: 'green',
      red: 'red',
      white: 'white',
      blue: 'blue'
    }

    OpenStruct.new(
      types: OpenStruct.new(values: types.values, **types).freeze,
      colors: OpenStruct.new(values: colors.values, **colors).freeze
    ).freeze
  end

  def self.car
    types = {
      sedan: 'sedan',
      minivan: 'minivan',
      truck: 'truck'
    }

    OpenStruct.new(
      types: OpenStruct.new(values: types.values, **types).freeze
    ).freeze
  end
end

And our interface would look like this:

Constants.animal.types.values
# => ["cat", "dog", "pig"]
Constants.car.types.values
# => ["sedan", "minivan", "truck"]
Constants.car.types.truck
# => "truck"

The interface looks good, but we still have many open issues that don't align with our requirements, like these ones:

It is hard to maintain and extend because everything is in one place.
There is a high risk of breaking something because we have to create every method from scratch.
There is a high risk of invalid methods because no error is raised if a non-existent constant value is requested.

Constants.car.types.not_exist
# => nil

That's why we need to build a more scalable and reliable solution. Let's consider Option 2.

Option 2. Storing constants in YAML files

In this option, we will improve scalability and move all our constant data to YAML files, as we did in the example with Rails configuration above. Here is our plan:

Step 1. Create a new YAML file for each model.
Step 2. Load all these YAML files and combine them into one big hash.
Step 3. Transform this hash into a nested OpenStruct object.
Step 4. Assign this new OpenStruct object to a single constant.

Step 1. Create a new YAML file for each model.

In this example, we will create 2 files: animal.yml and car.yml

animal.yml

# config/constants/animal.yml

animal:
  types:
    - cat
    - dog
    - pig
  colors:
    - green
    - red
    - white
    - blue
  ages:
    one_week: 1 week
    one_month: 1 month
    one_year: 1 year

car.yml

# config/constants/car.yml

car:
  types:
    - sedan
    - minivan
    - truck

Step 2. Load all these YAML files and combine them into one big hash.

To achieve this, we can do the following:

constant_hash = Dir.glob(File.join('config/constants', '*.yml')).reduce({}) do |hash, file_path|
  hash.merge(YAML.load_file(file_path))
end
# => 
{
 "animal"=>
  { 
    "types"=>["cat", "dog", "pig"],
    "colors"=>["green", "red", "white", "blue"],
    "ages"=>{
      "one_week"=>"1 week",
      "one_month"=>"1 month", 
      "one_year"=>"1 year"
     }
  },
 "car"=>
 {
   "types"=>["sedan", "minivan", "truck"]
 }
}

Step 3. Transform this hash into a nested OpenStruct object.

To transform the hash into a nested OpenStruct object, we can define the following method in the Hash class:

class Hash
  def to_open_struct
    JSON.parse to_json, object_class: OpenStruct
  end
end

And then use this method on the hash:

constant_open_struct = constant_hash.to_open_struct

constant_open_struct.animal.types
# => ["cat", "dog", "pig"]
constant_open_struct.animal.ages.one_week
# => "1 week"

Step 4. Assign this new OpenStruct object to a single constant.

Finally, we need to create a new constant and assign this new OpenStruct to it in the Rails initializer:

# config/initializers/constants.rb

# frozen_string_literal: true

Rails.application.config.after_initialize do
  # ...

  Kernel.const_set('Constants', constant_hash.to_open_struct)
end

Now we have the following interface:

Constants.animal.ages.one_month
# => "1 month"
Constants.animal.types
# => ["cat", "dog", "pig"]
Constants.car.types
# => ["sedan", "minivan", "truck"]

This solution is much more flexible now, but there are still many open problems:

Constant values are not frozen.
Without the hash, it is not possible to access elements from an array. For example, the following constant Constants.animal.types.cat doesn't work.
The OpenStruct performance is not good.

That's why we need to consider Option 3 to fix these problems.

Option 3. Production Ready Solution

In the final solution, we aim to preserve all the advantages and address the drawbacks of the previous solution. This solution will be nearly identical to the previous one, except for one difference: we will create a new custom class instead of using OpenStruct. To implement this, we need to follow these four steps:

Step 1. Create a new YAML file for each model.
Step 2. Load all these YAML files and combine them into one big hash.
Step 3. Create a new custom class to store our core logic for the new constant object.
Step 4. Transform the hash from Step 2 into an instance of the class created in Step 3. Then, assign this object to a new constant.

Step 1. Create a new YAML file for each model.

As a first step, we'll add YAML files just like we did in the previous option:

animal.yml

# config/constants/animal.yml

animal:
  limit: 10
  types:
    - cat
    - dog
    - pig
  colors:
    - green
    - red
    - white
    - blue
  ages:
    one_week: 1 week
    one_month: 1 month
    one_year: 1 year

car.yml

# config/constants/car.yml

car:
  types:
    - sedan
    - minivan
    - truck

Step 2. Load all these YAML files and combine them into one big hash.

At the second step, we will load all YAML files and combine them into one big hash, as we did in the previous option. Additionally, we will wrap it in a separate class for our convenience:

# lib/constant/load.rb

# frozen_string_literal: true

module Constant
  class Load

    def initialize(path)
      @path = path
    end

    def call
      Dir.glob(File.join(path, '*.yml')).reduce({}) do |hash, file_path|
        hash.merge(YAML.load_file(file_path))
      end
    end

    private

    attr_reader :path

  end
end

Step 3. Create a new custom class to store our core logic for the new constant object.

Let's take a look at the implementation, here's how our new class will look like. Don't worry if it seems complicated; we'll go over how this class works later:

# lib/constant/model.rb

# frozen_string_literal: true

module Constant
  class Model

    def initialize(constant_hash = {})
      @constant_hash = constant_hash.deep_symbolize_keys.freeze
    end

    def deep_transform
      tap { constant_hash.each { |key, value| define_singleton_method(key) { initialize_value(value) } } }
    end

    # provides missing hash methods ( for example '.values' etc. )
    delegate_missing_to :constant_hash

    private

    attr_reader :constant_hash

    def initialize_value(value)
      case value
      when Hash then Model.new(value).deep_transform
      when Array then Model.new(value.index_by(&:itself)).deep_transform
      else value.freeze
      end
    end

  end
end

The idea behind this class is as follows:

We send a hash from Step 2 as an argument.
We iterate over each key of this hash and define a new method for each key, for example:

# hash = { animal: { limit: 10 } }

def animal
  # ...
end

In this method, there are three options that we can return depending on the value of the key:

1. Primitive type. If the hash value for this key is a primitive type, for example, a string/symbol/integer, then we return this value.

# hash = { limit: 10 }

def limit
  10
end

2. Hash. If the value for this key is a Hash, then we return an instance of our new class with this value as an argument:

# hash = { animal: { limit: 10 } }

def animal
  Constant::Model.new({ limit: 10 }).deep_transform
end

3. Array. If the value for this key is an Array, we transform this array into a hash and return an instance of our new class with this value as an argument:

# hash_with_array = { types: ['cat', 'dog'] }
# hash_with_hash = { types: { cat: 'cat', dog: 'dog' } } 

def types
  Constant::Model.new({ cat: 'cat', dog: 'dog' }).deep_transform
end

And don't forget to freeze everything. That's it.

Step 4. Transform the hash from Step 2 into an instance of the class created in Step 3. Then, assign this object to a new constant.

Our final step is to bind Step 2 and Step 3, and save the result to a new constant. We will move this initialization into a separate class:

# lib/constant/initialize.rb

# frozen_string_literal: true

require_relative 'load'
require_relative 'model'

module Constant
  class Initialize

    def initialize(path:, constant_name:)
      @path = path
      @constant_name = constant_name
    end

    def call
      Kernel.const_set(constant_name, Model.new(load_hash_from_yml).deep_transform)
    end

    private

    attr_reader :path, :constant_name

    def load_hash_from_yml
      Constant::Load.new(path).call
    end

  end
end

And we will run this class in the initializer:

# config/initializers/constants.rb

# frozen_string_literal: true

require 'constant/initialize'

Rails.application.config.before_initialize do
  Constant::Initialize.new(path: 'config/constants', constant_name: 'Constants').call
end

Alright, now we have our desired interface:

Constants.animal.types.cat
# => cat 
Constants.animal.colors.green
# => green
Constants.animal.limit
# => 10
Constants.animal.ages.values
# => ["1 week", "1 month", "1 year"]
Constants.animal.colors.values
# => ['green', 'red', 'white', 'blue']
Constants.car.types.truck
# => truck
Constants.car.types.values
# => ['sedan', 'minivan', 'truck']

Conclusion

Here's the main benefit that we receive using this new approach:

Clear Interface.
Maintenance and refactoring.
DRY code.
Data validity.

You can prevent typos and invalid data from being saved.

Systematization.

It's easy to understand which domain/model a value belongs to and what other options are available.

Immutability.

Immutable values prevent accidental changes and ensure that the value remains consistent throughout your application.

Consistency.

You can ensure that the same value is represented consistently throughout your code.

How to implement Pub/Sub pattern in Ruby on Rails?

Vlad Hilko — Mon, 10 Apr 2023 18:22:43 +0000

Overview:

In this article we'll provide a comprehensive guide to understanding and implementing the Pub/Sub pattern. We will explore the evolution of this pattern from a primitive implementation to three product-ready solutions: ActiveSupport::Notifications, Wisper, and Dry-Events. We will begin by discussing the core concept of the Pub/Sub pattern. Then:

We will provide a step-by-step guide on how to implement the Pub/Sub pattern using the basic Ruby language constructs.
We will introduce the ActiveSupport::Notifications library.
We will delve into the Wisper gem.
Finally, we will examine the Dry-Events gem.

By the end of this article, we will have a solid understanding of the Pub/Sub pattern and the different options available for implementing it in their Ruby on Rails applications.

Definition

In simple terms, the Pub/Sub (Publish/Subscribe) pattern is a way of decoupling components in a system by providing an alternative method of communication between them. Rather than sending messages directly to specific components, a publisher broadcasts messages to any subscribers that are interested in receiving them. In other words, the Pub/Sub pattern enables communication between different components of a system without these components having any knowledge of each other.

Why do we need it and what problems can this pattern solve? 🤷🏻‍♂️

Let's take a look at the following piece of code from the rails controller.

def create
  animal = Animal.create(animal_params)
  # send_email
  # send_mobile_notification
  # save_logs

  render json: animal
end

What are we doing here?

We want to create an Animal record and show this record in the response
PLUS send an email about it
PLUS send a mobile notification about it
PLUS save this action to the logs

Do we have any problems with this approach? 🤔

Yes, we have. This code can lead to several problems, including:

Reduced maintainability: With multiple unrelated tasks in the same controller action, it can be difficult to maintain or modify the code in the future.
Reduced testability: Testing the create action becomes more complicated due to the additional responsibilities it has. It also makes it more challenging to test these other responsibilities in isolation.
Reduced scalability: If additional functionality needs to be added, it would likely be added to the create action, which can make the controller even more complicated and challenging to maintain.
Reduced readability: Mixing unrelated functionality in the same controller action can make it difficult to understand the overall purpose of the action.

How can we solve this problem? 🤔

Some developers solve this problem by using callbacks on the model to handle it. So, they might use something like this::

# app/models/animal.rb

# frozen_string_literal: true

class Animal < ApplicationRecord
  after_create :send_email, :send_mobile_notification, :save_logs

  private

  def send_email
    puts 'Email will be sent'
  end

  def send_mobile_notification
    puts 'Mobile Notification will be sent'
  end

  def save_logs
    puts 'Logs will be saved'
  end
end

But callbacks can potentially lead to significant issues, so it is better to avoid them.

Potentially, we could create a separate service object and place all this logic inside it. For example:

# app/units/create_animal_service.rb

class CreateAnimalService
  def self.call
    # do something
    send_email
    send_mobile_notification
    save_logs
  end

  private

  def send_email
    puts 'Email will be sent'
  end

  def send_mobile_notification
    puts 'Mobile Notification will be sent'
  end

  def save_logs
    puts 'Logs will be saved'
  end
end

While this approach is an improvement over using model callbacks, there is still a significant amount of cohesion between the core business logic and non-critical secondary logic. As a result, developers must understand the secondary logic, which is closely tied to the core logic, leading to increased cognitive load and a shift in focus from the primary part to technical details.

To address these issues, we can use the Pub/Sub pattern to separate the core business logic from non-critical secondary logic. Let's discuss this further:

How pub/sub actually works?

There are three key elements that must be implemented to make Pub/Sub work for you:

Send/Publish/Broadcast an event.
Define the logic that can potentially react to this event.
Bind the event with the logic ("subscribe to the event").

And we would like to have something like this as our new interface:

def create
  animal = Animal.create(animal_params).tap { send_event('animal_created') }

  render json: animal
end

This interface would allow us to concentrate on the core business logic and delegate all 'secondary' logic to somewhere else.

With the key elements above in mind, let's try to build a primitive Pub/Sub logic using plain Ruby to understand the concept behind it.

Primitive Ruby implementation

In this implementation, we'll use the same three main elements: 'Publishing an event', 'Defining logic' and 'Binding the event to the logic'.

Publishing an Event

For example, let's consider an event named animal_created, which is represented as a string. Whenever this event is sent, we simply add this string to an array

events = []
events << 'animal_created'

Defining logic to react to the event (subcriptions)

To react to the event, we need to define some actions that can potentially happen when the event occurs. These actions are called subscriptions or listeners. We can use a simple hash with two keys: event_name and action. event_name is a string that identifies the event, and action is a proc that is executed when the event is received.

subscriptions = []
subscriptions << { event_name: 'animal_created', action: -> { puts 'hello animal!' } }
subscriptions << { event_name: 'animal_created', action: -> { puts 'hello animal 2!' } }

Binding events and subscriptions

We have defined two main elements, but there is a problem - events and subscriptions are not connected and do not know about each other. To address this, we need to introduce some logic that will iterate over new events and match them with the appropriate action defined in the subscriptions.

events.each do |event_name|
  subscriptions.select { |subscription| subscription[:event_name] == event_name }.each { |subscription| subscription[:action].call }
end
events.clear

So, that is the basic idea. Let's try to improve our implementation by encapsulating some logic in a class.

Primitive Ruby implementation using class

We will create a class called Notification, which will have 3 methods: publish, subscribe and initialize. In this implementation, we will immediately react to the published event as soon as it is sent.

class Notification
  def initialize
    # We are initializing a Hash with empty arrays as default values for any new key
    @notifications = Hash.new { |hash, key| hash[key] = [] }
  end

  def subscribe(event_name, action:)
    notifications[event_name] << action
  end

  def publish(event_name)
    notifications[event_name].each { |action| action.call }
  end

  private

  attr_reader :notifications
end

Here is a usage example:

# Initialize the class
notification = Notification.new

# Subscribe to the event "animal_created" with two actions.
notification.subscribe('animal_created', action: -> { puts 'hello animal!' })
notification.subscribe('animal_created', action: -> { puts 'hello animal 2!' })

# Publish the 'animal_created' event, which will trigger both actions.
notification.publish('animal_created')

Out three key elements have also been used in this implementation.

This is a very simple example of how pub/sub can work. However, there are many ready-made solutions that we can use in our application. Let's consider three of them:

ActiveSupport::Notification
Wisper
Dry-events

They're pretty much the same and have very similar interfaces. Let's look at each of these options one by one to better understand the concept.

ActiveSupport::Notification

ActiveSupport::Notification has the same three key elements that we discussed earlier

Send/Publish/Broadcast an event.
Define the logic that can potentially react to this event.
Bind the event with the logic ("subscribe to the event").

Let's consider three ways of implementing the pub/sub pattern using ActiveSupport::Notification, starting from the simplest and progressing to the most complex, in order to better understand the concept:

ActiveSupport::Notification with blocks
ActiveSupport::Notification with classes
ActiveSupport::Notification in a Rails application

Let's start with the most basic one

`ActiveSupport::Notification` with blocks

# Define the logic
ActiveSupport::Notifications.subscribe('animal_created') do |*args|
  puts "New animal created 1"
end

ActiveSupport::Notifications.subscribe('animal_created') do |*args|
  puts "New animal created 2"
end

# Send the event
ActiveSupport::Notifications.instrument('animal_created')

# => New animal created 1
# => New animal created 2

So, here everything looks obvious. Basically, we have the same interface as we described in the primitive Ruby implementation. Let's go further.

`ActiveSupport::Notification` with classes

Instead of a block, we can also send a class that has a call method. This can be useful when your logic becomes too complex, and using classes can greatly simplify testing.

# Define the logic
class Subscription1
  def call(name, started, finished, unique_id, payload)
    puts "New animal created 1"
  end
end

class Subscription2
  def call(name, started, finished, unique_id, payload)
    puts "New animal created 2"
  end
end

# Bind the event with the logic
ActiveSupport::Notifications.subscribe('animal_created', Subscription1.new)
ActiveSupport::Notifications.subscribe('animal_created', Subscription2.new)

# Send the event
ActiveSupport::Notifications.instrument('animal_created')

# => New animal created 1
# => New animal created 2

Here's how ActiveSupport::Notification basically works. Let's try to add it to a real Rails application.

`ActiveSupport::Notification` in a Rails application

For example, we have a service object that performs some actions and sends the 'animal_created' event.

Publishing an Event

# app/units/service.rb

class Service
  def self.call
    # perform some actions
    ActiveSupport::Notifications.instrument('animal_created', payload: {})
  end
end

Defining logic to react to the event

Additionally, we need to create subscriptions to react to these events. We want to send an email, send a mobile notification, and log this action somewhere. To accomplish this, we'll create three subscription classes, each of which will handle one of these tasks.

EmailSubscription

# app/subscriptions/email_subscription.rb

# frozen_string_literal: true

class EmailSubscription < Subscription

  def animal_created(payload)
    puts "Email will be sent #{payload}"
  end

end

MobileNotificationSubscription

# app/subscriptions/mobile_notification_subscription.rb

# frozen_string_literal: true

class MobileNotificationSubscription < Subscription

  def animal_created(payload)
    puts "Mobile Notification will be sent #{payload}"
  end

end

LoggerSubscription

# app/subscriptions/logger_subscription.rb

# frozen_string_literal: true

class LoggerSubscription < Subscription

  def animal_created(payload)
    puts "Logs will be saved #{payload}"
  end

end

Every subscription class should include the desired reaction to the event and a method call to actually run this reaction. That's why we've created a parent class Subscription.

Subscription

# lib/subscription.rb

# frozen_string_literal: true

class Subscription

  def call(event_name, _, _, _, payload)
    send(event_name, payload)
  end

end

Binding events and logic

We've created an event that can be sent and classes with the appropriate reaction to the event. However, these classes aren't currently connected to the event, meaning they won't react to it. To establish the connection, we'll use the following logic after Rails initialization.

# config/initializers/subscriptions.rb

# frozen_string_literal: true

Rails.application.config.after_initialize do
  subscriptions = {
    EmailSubscription: ['animal_created'],
    LoggerSubscription: ['animal_created'],
    MobileNotificationSubscription: ['animal_created']
  }

  # We iterate over each subscription class and bind its logic with the event name, similar to what we did in the example with blocks.
  subscriptions.each do |subscription_class, events|
    events.each do |event|
      ActiveSupport::Notifications.subscribe(event, subscription_class.to_s.constantize.new)
    end
  end
end

So now we can call Service.call and this code will send the 'animal_created' event, triggering all subscriptions:

Email will be sent {:payload=>{}}
Logs will be saved {:payload=>{}}
Mobile Notification will be sent {:payload=>{}}

Adding a new event

To add a new event, you need to update the subscription classes with the desired logic and then bind them to the new event. This ensures that the subscription logic will be executed whenever the event is triggered.

For example, if you would like to add the car_created event to the EmailSubscription, then you should do the following:

# app/subscriptions/email_subscription.rb

# frozen_string_literal: true

class EmailSubscription < Subscription

  def animal_created(payload)
    puts "Email will be sent #{payload}"
  end

  def car_created(payload)
    puts "Car email will be sent #{payload}"
  end

end

It's important not to forget to subscribe to this event in the initializer after adding the logic to the EmailSubscription class for the car_created event.

# config/initializers/subscriptions.rb

# frozen_string_literal: true

Rails.application.config.after_initialize do
  subscriptions = {
    EmailSubscription: ['animal_created', 'car_created'],
    LoggerSubscription: ['animal_created'],
    MobileNotificationSubscription: ['animal_created']
  }
  # ...
end

When we call car_created, the subscribed logic in EmailSubscription will be triggered as expected.

ActiveSupport::Notifications.instrument('car_created', payload: {})

# => Car email will be sent {:payload=>{}}

Wisper gem

The second option is to use Wisper gem.

First of all, we need to add the wisper gem to the Gemfile and then run bundle install:

gem 'wisper'

This gem has the same three key elements:

Send/Publish/Broadcast an event.
Define the logic that can potentially react to this event.
Bind the event with the logic ("subscribe to the event").

Send an event.

To send an event we need to do the following:

# app/units/create_animal_service.rb

# frozen_string_literal: true

class CreateAnimalService
  include Wisper::Publisher

  def call
    # do something
    broadcast(:animal_created, payload: {})
  end
end

CreateAnimalService.new.call

Define the logic

To add logic for our events, we need to do the following:

EmailSubscription

# app/subscriptions/email_subscription.rb

# frozen_string_literal: true

class EmailSubscription

  def animal_created(payload)
    puts "Email will be sent #{payload}"
  end

end

LoggerSubscription

# app/subscriptions/logger_subscription.rb

# frozen_string_literal: true

class LoggerSubscription

  def animal_created(payload)
    puts "Logs will be saved #{payload}"
  end

end

MobileNotificationSubscription

# app/subscriptions/mobile_notification_subscription.rb

# frozen_string_literal: true

class MobileNotificationSubscription

  def animal_created(payload)
    puts "Mobile Notification will be sent #{payload}"
  end

end

Bind the event with the logic

To bind the event and subscription, we need to do the following

# config/initializers/subscriptions.rb

# frozen_string_literal: true

Rails.application.config.after_initialize do
  Wisper.subscribe(EmailSubscription.new)
  Wisper.subscribe(LoggerSubscription.new)
  Wisper.subscribe(MobileNotificationSubscription.new)
end

As you can see, the interface is quite similar to what we had in ActiveSupport::Notifications.

Dry-event

Our third option is to create a Pub/Sub system using the dry-rb gems. To be more precise, we are going to use the dry-events gem.

To get started, we need to add the dry-events gem to our Gemfile and run bundle install:

gem 'dry-events'

This gem has the same 3 key elements plus an additional one - we need to register an event. Let's take a look at the example below:

Register an event

# lib/events.rb

# frozen_string_literal: true

require 'dry/events/publisher'

class Events
  include Singleton
  include Dry::Events::Publisher[:my_publisher]

  register_event('animal.created')
end

We included Singleton here because dry-event requires us to work with an instance, but we don't want to create a new instance every time.

Send an event

# app/units/create_animal_service.rb

# frozen_string_literal: true

class CreateAnimalService
  def self.call
    # do something
    Events.instance.publish('animal.created', payload: {})
  end
end

Defining logic to react to the event (Subscriptions)

EmailSubscription

# app/subscriptions/email_subscription.rb

# frozen_string_literal: true

class EmailSubscription

  def on_animal_created(event)
    puts "Email will be sent #{event[:payload]}"
  end

end

LoggerSubscription

# app/subscriptions/logger_subscription.rb

# frozen_string_literal: true

class LoggerSubscription

  def on_animal_created(event)
    puts "Logs will be saved #{event[:payload]}"
  end

end

MobileNotificationSubscription

# app/subscriptions/mobile_notification_subscription.rb

# frozen_string_literal: true

class MobileNotificationSubscription

  def on_animal_created(event)
    puts "Mobile Notification will be sent #{event[:payload]}"
  end

end

Bind the event with the logic

# config/initializers/subscriptions.rb

# frozen_string_literal: true

Rails.application.config.after_initialize do
  events = Events.instance

  events.subscribe(EmailSubscription.new)
  events.subscribe(LoggerSubscription.new)
  events.subscribe(MobileNotificationSubscription.new)
end

Conclusion

The final solution may look like this or be placed under the Service object which sends an event inside:

def create
  animal = Animal.create(animal_params).tap { ActiveSupport::Notifications.instrument('animal_created') }

  render json: animal
end

In conclusion, Pub/Sub pattern is a useful design pattern in Ruby on Rails applications for managing communication between different parts of the system. The advantages of using Pub/Sub are numerous, including the most important ones:

Advantages

Decoupling

One of the main advantages of the pub/sub pattern is that it allows publishers and subscribers to be decoupled from each other. Publishers do not need to know about the subscribers, and subscribers do not need to know about the publishers. This makes it easy to add or remove components from the system without affecting the other components.
Scalability

The pub/sub pattern is highly scalable, since it allows multiple subscribers to receive the same message at the same time. This makes it easy to distribute messages to a large number of subscribers, without overloading the publishers or the subscribers.
Flexibility

The pub/sub pattern provides a flexible way to implement communication between different components of an application, as well as between different applications. Since publishers and subscribers do not need to know about each other, it is easy to add new features or change existing ones without having to modify existing code.
Asynchronous

The pub/sub pattern is asynchronous, which means that publishers and subscribers do not need to be active at the same time. Publishers can publish messages at any time, and subscribers can consume messages whenever they are ready. This makes it easy to implement real-time notifications and messaging systems.

Disadvatages

Complexity

Implementing the pub/sub pattern can be complex, especially when dealing with a large number of publishers and subscribers. This pattern can add an additional layer of complexity to the system, which can make it harder to debug and maintain.
Reduction of application flow visibility

Another potential disadvantage of using the Pub/Sub pattern is that it can result in a reduction of application flow visibility. This means that the overall flow of the system may be harder to understand, as the primary action and its secondary effects may be implemented in different parts of the codebase, making it difficult for future readers to comprehend the system's operation.

How to implement Authorizer pattern in Ruby on Rails?

Vlad Hilko — Thu, 29 Dec 2022 22:22:34 +0000

Overview

In this article, we will explore the Authorizer pattern in Ruby on Rails applications. We will provide a definition of the Authorizer pattern and discuss its use cases and examples. We will also delve into the need for this pattern and how it helps to solve certain problems in Rails applications.

Definition

In simple terms, the Authorizer pattern allows us to define and encapsulate complex business rule in our Rails applications. If the requirement specified by this rule is not met, an error will be raised. You can think of an Authorizer as a custom ActiveRecord Validator, but instead of validating input data, it is used to enforce business requirements.

Why do we need it and what problems can this pattern solve? 🤷🏻‍♂️

Let's take a look at the following example.

def create
  user = User.first
  raise 'User is not active' if user.status != 'active' || user.approved_at.blank?

  article = Aricle.create(user: user, title: 'title', body: 'body')
  render json: article
end

In the following example, we want to ensure that certain requirements are fully met before calling the business logic.

Do we have any problems with this approach? 🤔

Yes, we have.

It is not possible to test separately from the controller.
It is not reusable.
We violate the Single Responsibility Principle because the controller becomes responsible for business rules validation.
The following code increases 'cognitive load' and requires more time to understand.
The following code is not scalable and it is difficult to add more rules.

How can we solve these problems? 🤔

We can move this logic to the model level and use before_create callback.
We can create Athorizer class and move the logic there.

Let's take a look at these options one by one.

Model with callback

This is the easiest option, we just need to extend our model in the following way:

# app/models/article.rb

class Aricle < ApplicationRecord

  before_save :check_user_status!

  def check_user_status!
    raise 'User is not active' if user.status != 'active' || user.approved_at.blank?
  end

end

user = User.last
Aricle.create(user: user, article_params)

Are there any disadvantages to this approach?

There're 2 problems:

We violate the Single responsibility SOLID principle. The model becomes too FAT and responsible for too many things.
Using callbacks in Rails models can make the code more difficult to understand and maintain due to their tight coupling with the model and lack of transparency. Therefore, it is generally considered to be a bad pattern.

So it would be nice to encapsulate this logic in a separate class. How can we do that?

Authorizer Pattern

We're going to implement Athorizer Pattern via plain Ruby object because it's the clearest and the most straightforward solution.

Let's take a look at the following example.

# app/authorizers/has_active_user_authorizer.rb

class HasActiveUserAuthorizer

  def initialize(user)
    @user = user
  end

  def authorize!
    raise 'User is not active' unless active?
  end

  private

  attr_reader :user

  def active?
    user.status == 'active' && user.approved_at.present?
  end

end

HasActiveUserAuthorizer.new(user).authorize!

We just encapsulated our rules inside a separate class, and that's it. This code adheres to the SOLID principles and is much easier to understand and maintain.

Naming convention

There are two common ways to name authorizers:

Inside a namespace (for example, Authorizers::HasActiveUser)
With a postfix (for example, HasActiveUserAuthorizer)

But they have one rule in common - the authorizer must clearly reflect in its name the rule it introduces. Let's take a look at other possible names that are commonly used for the Authorizer Pattern to get a wider picture:

CompanyHasNoEmployeesAuthorizer

Raises an error if the company has at least one employee

ArticleNotApprovedAuthorizer

Raises an error if the article is approved

Authorizers::HasAtLeastOneComment

Raises an error if there are no comments

Authorizers::NotPopulated

Raises an error if the table is already populated with records

UserHasActiveSubscriptionAuthorizer

Raises an error if the user does not have an active subscription

CustomerAgeApprovedAuthorizer

Raises an error if the customer's age is not approved

etc ...

Comparing the Authorizer Pattern to Other Patterns

Similar to Form Object

Form objects and Authorizers both perform validation and raise errors before running business logic. So, what are the differences? The key differences are:

Form objects validate data from the user input
Authorizers validate general business logic rules

P.S.. To learn more about using Form object pattern in Ruby on Rails, you can check out this article.

Similar to Policy Object

Authorizers are also similar to Policy objects because both encapsulate business rules. The key differences are:

Authorizers may contain only one business rule, but Policy objects can contain many.
Authorizers are more strict and demand that a business rule be followed, whereas a Policy object will only ask if the rule is true or false. This difference is reflected in the use of ! by Authorizers and ? by Policy objects at the end of their methods.

P.S.. To learn more about using Policy object pattern in Ruby on Rails, you can check out this article.

Similar to Custom Validators

Authorizers are similar to custom ActiveRecord validations in terms of their responsibility, but custom validators validate one data field, while Authorizers validate general rules for the whole model.

Note:

Don't confuse the Authorizer pattern with authorization logic. Authorizers ask if the service is authorized to perform the action under the current conditions, while authorization logic happens at a higher level (usually on the controller level).

Bonus Chapter: Adding Authorizers to Service Objects

In the previous chapter, we mentioned that Authorizers are similar to custom validators. Let's take a look at the example of custom validators:

# app/models/article.rb

class Article < ApplicationRecord
  # ...
  validate :name_presence
  # ...
  def name_presence
    errors.add :base, "Name is empty" if name.blank?
  end
end

Or in a separate class:

# app/models/article.rb

class Article < ApplicationRecord
  # ...
  validates_with NamePresenceValidator
  # ...
end

# app/validators/name_presence.rb

class NamePresenceValidator < ActiveModel::Validator
  def validate(record)
    record.errors.add :base, "Name is empty" if record.name.blank?
  end
end

Essentially, we want to have a similar interface for our Authorizers within Service objects, something like this:

# app/services/create_article_service.rb

class CreateArticleService
  # ...
  authorize 'has_active_user_authorizer'
  authorize 'another_authorizer'
  authorize 'one_more_authorizer'
  # ...
end

How can we do this? Let's consider what we need:

Service (to keep the authorize method)
A module with the authorize method definition (to be able to include it in every service)
Authorizer (to encapsulate complex business rule)
A base Authorizer (to avoid repeating the same code for every new Authorizer)

Let's add them one by one.

Note: We will only provide code snippets without explanation to keep it brief.

Service

# app/services/create_article_service.rb

class CreateArticleService

  include Authorizable

  authorize 'has_active_user_authorizer'

  attr_reader :user, :params

  def initialize(user: , params:)
    @user = user
    @params = params
  end

  def call
    authorize!
    # main logic
  end

end

Authorizable module

# lib/authorizable.rb

module Authorizable
  extend ActiveSupport::Concern

  included do
    class_attribute :authorizers, default: []
  end

  class_methods do
    def authorize(authorizer_name)
      self.authorizers += [authorizer_name]
    end
  end

  def authorize!
    authorizers.each do |authorizer|
      authorizer.to_s.classify.constantize.new(self).authorize!
    end
  end
end

Authorizer

# app/authorizers/has_active_user_authorizer.rb

class HasActiveUserAuthorizer < BaseAuthorizer

  def authorize!
    raise 'User is not active' unless active?
  end

  private

  def active?
    service_object.user.status == 'active' && service_object.user.approved_at.present?
  end

end

BaseAuthorizer

# lib/base_authorizer.rb

class BaseAuthorizer

  def initialize(service_object)
    @service_object = service_object
  end

  def authorize!
    raise 'NotImplementedError'
  end

  private

  attr_reader :service_object

end

That's it! Now you can use the Authorizer pattern in your service objects to encapsulate complex business rules and ensure that they are followed before the main logic is executed. To learn more about using the Service object pattern in Ruby on Rails, you can check out my other article.

So the final solution may look like this:

def create
  user = User.first
  UserIsActiveAuthorizer.new(user).authorize!

  article = Aricle.create(user: user, title: 'title', body: 'body')
  render json: article
end

Or using a service object:

def create
  user = User.first

  article = CreateArticleService.new(user: user, params: { title: 'title', body: 'body' }).call
  render json: article
end

Conclusion

The Authorizer Pattern helps us better separate logic, making it easier to test our code.
It is DRY and reusable.
The Authorizer Pattern allows us to avoid having a "fat" model and adhere to SOLID principles.
It reduces "cognitive overhead", making the code easier to understand.
It ensures that any necessary requirements are met as soon as possible by raising an error before running any form validations or business logic calculations.