DEV Community: Lucas M.

How to set a timeout to RSpec test executions

Lucas M. — Thu, 24 Jul 2025 16:30:42 +0000

TL;DR

Tired of tests hanging indefinitely in your CI pipeline, wasting resources and delaying feedback? I built RspecTimeGuard, a new gem that adds timeout protection to your RSpec test suite. Set time limits on individual tests or globally, and get clear error messages when tests exceed their limits instead of waiting for your CI to time out.

🔗 Check it out: https://github.com/LucasMontorio/rspec-time-guard

This is my first gem, so any stars are more than welcome! ⭐

The article below walks through the technical journey of building this solution, from initial thread-joining approaches to the final single-threaded monitoring implementation.

Introduction / Motivation

On one of the Rails application on which I am working, a Rails monolith, I recently stumbled upon a quite disturbing CI issue: in some of our RSpec runs, it happens that specs timeout in an unpredictable way after having reached the CI environment’s (in our case, CircleCI) built-in “no-output timeout”.

I won’t go in depth into the nature of these tests, but let’s say they are simply browser-centric Capybara tests that sometimes get stuck waiting for a condition that can never be satisfied.

Reasons that could lead to such hangs are multiple: deadlocks, connection pools exhausted, infinite loops…

When these cases happen, the test that hangs terminates with a quite useless output and causes your CI run to wait for up to 10 minutes just to tell you that your test has failed. This can cause important delays and generate extra costs (CI runs being usually billed by the minute).

Error: Task timed out after 10.00 minutes

This made me realise that, some times, it could be good to be able to make a test fail after a certain amount of time, be it to prevent the CI env. from spending too much time (and money) on it, or simply to monitor the efficiency of a test suite.

To my surprise, I didn’t find any simple, RSpec built-in way to do this.

Hence, I started developing my own.

This article will go into the details of the strategy adopted for this solution, and the different phases through which I went before reaching a satisfactory implementation.

First iteration / Thread-joining

In order to achieve this, my first intention was to create a mechanism that could detect that a test has been running for too long, then terminate it with a helpful error message that would appear in the CI’s output.

One way of doing this would be to instantiate a thread responsible of running the test, and monitor its execution from the main thread. When reaching a timeout, we could then kill the running thread and proceed with the rest of the suite.

Ruby’s Thread#join method allows us to make the main thread wait until the thread referenced by the method completes its execution. It also accepts a timeout parameter, which is particularly relevant to our case. When a timeout is provided, the method will wait only up to that many seconds for the thread to complete:

Example:

# Create a new thread that takes 5 seconds
t = Thread.new do
  sleep 5
  puts "Thread completed"
end

# Wait for at most 2 seconds for the thread to complete
if t.join(2)
  puts "Thread completed within timeout"
else
  puts "Thread did not complete within timeout"
  # The thread is still running in the background
end

puts "Main thread continues regardless"

# OUTPUT:
Thread did not complete within timeout
Main thread continues regardless
=> nil

In this example, t.join(2) will return nil because the thread doesn't complete within 2 seconds. If the thread had completed before the timeout, it would have returned the thread object itself, which evaluates to true in a boolean context.

Now that I could identify a thread running for too long, I simply had to add a wrapper (hook) around RSpec examples to plug this behaviour on every running spec, and cleanly terminate the timed-out ones.

This lead to the first, basic implementation of the gem:

RSpec.configure do |config|
  config.around(:each) do |example|
    time_limit_seconds = example.metadata[:time_limit_seconds]

    next example.run unless example.metadata[:time_limit_seconds]

    begin
      thread = Thread.new do
        example.run
      end

      unless thread.join(time_limit_seconds)
        thread.kill
        raise RspecTimeGuard::TimeLimitExceededError,
              "[RspecTimeGuard] Example exceeded timeout of #{time_limit_seconds} seconds"
      end
    end
  end
end

At this stage, a timed-out test generates the following output:
Show error output

Randomized with seed 29957
#<Thread:0x000000015bf7de68 ... exception (report_on_exception is true):
...gems/rspec-core-3.13.3/lib/rspec/core/example.rb:521:in `ensure in run_after_example': undefined method `teardown_mocks_for_rspec' for nil (NoMethodError)

        @example_group_instance.teardown_mocks_for_rspec
                               ^^^^^^^^^^^^^^^^^^^^^^^^^

RspecTimeGuard::TimeLimitExceededError: [RspecTimeGuard] Example exceeded timeout of 1 seconds

0) Processing::Base#call raises a timeout error
   Failure/Error: raise RspecTimeGuard::TimeLimitExceededError, message

   RspecTimeGuard::TimeLimitExceededError:
   [RspecTimeGuard] Example exceeded timeout of 1 seconds
   # ... (2 levels) in setup'
1 example, 1 failure, 0 passed
Finished in 1.033112 seconds

Randomized with seed 29957

Process finished with exit code 1

Cleaning the error trace / better error-handling

Despite being able to make a test fail based on its execution time, this would still generate quite a lot of noise, due to our overwriting some of RSpec’s internal logic.

In order to avoid this, there exists an option that prevents the noisy error output by preventing Ruby from automatically reporting exceptions that occur within the thread.

When using thread.kill to terminate the test thread, Ruby was automatically printing all the internal exceptions that happened during the termination process. This created the extremely verbose and confusing stack trace seen in the example, showing internal RSpec errors like "undefined method teardown_mocks_for_rspec' for nil".

By setting Thread.current.report_on_exception = false at the beginning of our thread creation, I could tell Ruby not to automatically print these internal exceptions to stderr.

This setting doesn't suppress the exceptions themselves - they still occur and can be caught and handled - it just prevents their automatically being printed to the console, which was cluttering our output with information that wasn't helpful to users of the gem.*
Beyond avoiding noisy process terminations, I also needed to properly handle exceptions and allow them to re-raise in the main thread to allow RSpec to fail for reasons unrelated to timeouts.

If a test fails for reasons unrelated to timeouts (like a failing assertion), we want that original error to be reported clearly, not obscured by our timeout machinery.
To improve thread termination, we explored using thread.exit as a gentler alternative to thread.kill. While thread.kill forces immediate termination and can leave resources in an inconsistent state, thread.exit requests the thread to terminate more cooperatively.

This lead roughly to the following (simplified) implementation:

thread = Thread.new do
  Thread.current.report_on_exception = false

  begin
    example.run
  rescue Exception => e
    Thread.current[:exception] = e
  end
end

# Later in the code:
if thread.join(time_limit_seconds)
  raise thread[:exception] if thread[:exception]
else
  RspecTimeGuard.terminate_thread(thread)
  raise RspecTimeGuard::TimeLimitExceededError, "[RspecTimeGuard] Example exceeded timeout of #{time_limit_seconds} seconds"
end

def terminate_thread(thread)
  return unless thread.alive?

  # Attempt to terminate the thread gracefully
  thread.exit

  # Give the thread a moment to exit gracefully and perform cleanup
  sleep 0.1
  # If it's still alive, kill it
  thread.kill if thread.alive?
end

For the same timed-out spec as mentioned above, we now get the following output:

Show improved error output

RspecTimeGuard::TimeLimitExceededError: [RspecTimeGuard] Example exceeded timeout of 1 seconds

0) Processing::Base#call raises a timeout error
   Failure/Error: raise RspecTimeGuard::TimeLimitExceededError, message

   RspecTimeGuard::TimeLimitExceededError:
   [RspecTimeGuard] Example exceeded timeout of 1 seconds
   # .../lib/rspec_time_guard.rb:53:in `block (2 levels) in setup'
1 example, 1 failure, 0 passed
Finished in 1.127036 seconds

The `RSpec.current_example` issue / better thread handling

Now that I was able to set an example-specific timeout threshold and get a clean error output in case of timeout, the next step was to allow the gem to set a global value for this threshold, thus allowing us to run an entire test suite with the same timing expectations.

In the traditional Ruby gem fashion, I implemented a configuration object responsible for storing the timeout threshold value globally, and ran the test suite locally on a production-ready application with >1000 tests:

time_limit_seconds = example.metadata[:time_limit_seconds] || RspecTimeGuard.configuration.max_execution_time

To my surprise, I ran into several issues that led to a significant proportion of my examples ending with the following error when setting the global max_execution_time param: tests that had previously worked fine suddenly began failing with puzzling errors indicating that RSpec.current_example was nil. This was particularly perplexing since the tests had worked correctly when using per-example time limits through metadata.

      NoMethodError:
        undefined method `metadata' for nil

Further investigation revealed that some of our tests were trying to access RSpec.current_example.metadata as part of their business, which caused the error. The intention behind these tests will not be described here, but let’s just say that they needed to access the current example’s metadata to conditionally load certain fixtures. It turned out this getter was actually broken because of my RspecTimeGuard implementation. Here’s why:

The root cause lay in how RSpec manages the current example context. RSpec uses thread-local storage to track the currently executing example, making it available via RSpec.current_example. This works well in standard RSpec usage where tests run in the main thread, but our implementation was breaking this fundamental assumption by running each test in a separate thread so that the main thread could monitor its execution time:

thread = Thread.new do
  Thread.current.report_on_exception = false
  begin
    example.run
  rescue Exception => e
    Thread.current[:exception] = e
  end
end

unless thread.join(time_limit_seconds)
  # Handle timeout...
end

This design created a disconnection: when the test called RSpec.current_example, it returned nil because the thread-local reference only existed in RSpec's original thread, not in my custom thread where the test was actually running. I had to update the gem’s design and invert the approach.

Since I had to keep the test running in RSpec’s main thread where all the context was properly set up, I could now use a separate thread solely for timeout monitoring.
This inverted design became the new implementation:

RSpec.configure do |config|
  config.around(:each) do |example|
    time_limit_seconds = example.metadata[:time_limit_seconds] || RspecTimeGuard.configuration.global_time_limit_seconds

    next example.run unless time_limit_seconds

    completed = false

    # NOTE: We instantiate a monitoring thread, to allow the example to run in the main RSpec thread.
    # This is required to keep the RSpec context.
    monitor_thread = Thread.new do
      Thread.current.report_on_exception = false

      # NOTE: The following logic:
      #  - Waits for the duration of the time limit
      #  - If the main thread is still running at that stage, raises a TimeLimitExceededError
      sleep time_limit_seconds

      unless completed
        message = "[RspecTimeGuard] Example exceeded timeout of #{time_limit_seconds} seconds"
        if RspecTimeGuard.configuration.continue_on_timeout
          warn "#{message} - Running the example anyway (:continue_on_timeout option set to TRUE)"
          example.run
        else
          Thread.main.raise RspecTimeGuard::TimeLimitExceededError, message
        end
      end
    end

    # NOTE: Main RSpec thread execution
    begin
      example.run
      completed = true
    ensure
      # NOTE: We explicitly clean up the monitoring thread in case the example completes before the time limit.
      monitor_thread.kill if monitor_thread.alive?
    end
  end
end

The monitoring thread simply sleeps for the duration of the timeout and then checks if the test is still running. If it is, it raises an error in the main thread to terminate the test.

A key component of this implementation is the completed flag that provides communication between the main thread and the monitoring thread. When the test finishes successfully, the main thread sets this flag to true, signaling to the monitoring thread that it shouldn't take any action even if it wakes up after its sleep period.

This redesign solved the RSpec.current_example issue!

Second iteration / single-thread monitoring implementation

Now that the the RSpec example context issue was fixed, I was finally able to finalise a first (WIP) version of the gem: add specs, a CI suite, a proper README, … And finally test it on a production app’s CI run.

Although this was a nice milestone, the latest implementation at this staged still was unsatisfying in a way: Each test was creating its own monitoring thread, and in test suites with thousands of examples, this could potentially create thousands of threads over the course of execution. This proliferation of threads could impact system resources and overall performance.

To address this issue, my idea was to reimagine the current implementation to use a a single, persistent monitoring thread that would track all active tests. Instead of each test creating its own monitor, tests would register themselves with this central monitor when they started and unregister when they completed.

I encapsulated this functionality in a TimeoutMonitor class with a clean API:

class TimeoutMonitor
  def register_test(example, timeout, thread)
    # Add test to the active test list with its metadata
  end

  def unregister_test(example)
    # Remove test from the active test list
  end
end

This approach required careful attention to thread safety, as multiple tests could be registering and unregistering concurrently. I used a mutex to ensure that updates to the active tests list were atomic:

def register_test(example, timeout, thread)
  @mutex.synchronize do
    @active_tests[example.object_id] = {
      example: example,
      start_time: Time.now,
      timeout: timeout,
      thread_id: thread.object_id,
      warned: false
    }

    start_monitor_thread if @monitor_thread.nil? || !@monitor_thread.alive?
  end
end

The backbone of the monitoring system was now a single thread that periodically checked the list of active tests to see if they have reached their respective time limits. This thread would be initiated in our RSpec around block as follows:

def start_monitor_thread
  @monitor_thread = Thread.new do
    Thread.current[:name] = 'rspec_time_guard_monitor'

    loop do
      check_for_timeouts
      sleep 0.5 # Check every half second

      # Exit thread if no more tests to monitor
      break if @mutex.synchronize { @active_tests.empty? }
    end
  end
end

For each active test, the monitor compared its elapsed running time against its specified timeout limit. If a test had exceeded its limit, the monitor would take appropriate action, either raising an error or outputting a warning depending on configuration:

def check_for_timeouts
  now = Time.now
  timed_out_examples = []

  @mutex.synchronize do
    @active_tests.each do |_, info|
      elapsed = now - info[:start_time]
      timed_out_examples << info if elapsed > info[:timeout]
    end
  end

  # Handle timeouts outside the mutex to avoid deadlocks
  timed_out_examples.each do |info|
    # Create error message and handle timeout...
  end
end

One challenge I faced was how to track thread objects across different contexts. Storing direct references to thread objects could lead to memory leaks, so I instead stored thread IDs and used ObjectSpace._id2ref to retrieve the actual thread when needed:

thread = begin
  ObjectSpace._id2ref(@active_tests[example.object_id][:thread_id])
rescue
  nil
end

next unless thread&.alive?

To improve the user experience when using the continue_on_timeout option, I added a warned flag to track which tests had already received timeout warnings. This prevented the monitor from outputting repeated warnings for the same test.

Finally, a tiny bit of resource conservation logic. The monitor thread automatically terminates itself when there are no more active tests to monitor, and it only starts when needed:

# Exit thread if no more tests to monitor
break if @mutex.synchronize { @active_tests.empty? }

This single-threaded monitoring approach dramatically reduced the number of threads created during test suite execution, from potentially thousands to just one.

Notes / final comments

RspecTimeGuard was developed and tested primarily with MRI/CRuby, but we gave careful consideration to compatibility with other Ruby interpreters. The gem's core functionality relies on standard Ruby libraries and APIs that are implemented across different Ruby interpreters, making it broadly compatible in most scenarios.

However, there are some potential compatibility considerations worth noting. The gem's use of Thread.raise behavior can vary between interpreters - while it works reliably in MRI/CRuby, JRuby and TruffleRuby may exhibit different timing characteristics and reliability patterns.

Eventually, RspecTimeGuard represents a new gem that provides a simple, focused solution to a quite common problem in Ruby test suites - the need to prevent tests from hanging indefinitely and wasting CI resources. Through its evolution from a basic thread-joining approach to a sophisticated single-threaded monitoring system, it taught me a lot of interesting things and made me want to share this project, which is the point of this whole article!

The gem doesn't pretend to be perfect, and we actively welcome challenging comments, issues, and contributions from the community. Real-world usage will undoubtedly reveal edge cases and improvement opportunities that we haven't yet encountered.

In the coming months, RspecTimeGuard will undergo more intensive testing across different Ruby applications, environments, and use cases. I plan to write more on the outcome of such usage. In the meantime, I hope you enjoyed reading this as much as I enjoyed writing it!

Cheers,

Lucas

Rails transactional callbacks beyond models

Lucas M. — Tue, 10 Dec 2024 17:35:23 +0000

In this previous post, we discussed non-atomic interactions in transactions and their potential impact on data integrity.
One of the workarounds proposed for the issue described there was to use a transactional callback.

Let’s deep-dive into this feature, see how to make maximum profit of it, and how to extend its principle outside of the ActiveRecord with the help of a gem.

Legacy / Model Callbacks

Rails callbacks (or, more precisely, ActiveRecord callbacks) have been a common and handy practice for triggering logic on a range of events that can occur on a given model.
However, it's important to note that some of them rely on potentially risky patterns that are sometimes overlooked, despite posing risks to data integrity.

According to the official definition,

“Callbacks are hooks into the life cycle of an Active Record object that allow you to trigger logic before or after a change in the object state”.

Here is the list of “classic” supported callbacks available on ActiveRecord:

before_validation
after_validation
before_save
before_create
after_create
after_save

The principle here is simple: when firing a create , save or a validation event on the ActiveRecord model at stake, the event will be preceded or followed by the execution of the block passed to the callback definition.

Hence, their use-cases can be multiple: sending an email after an object is created, formatting a user’s phone number before persisting it, updating relations subsequently to a successful action…

Here is the example we saw in the previous article:

class User < ApplicationRecord
  after_save :do_something_asynchronous

  private

  def do_something_asynchronous
    SyncUser.perform_later(user: self) # Some business logic there...
  end
end

We observed that doing this represents a non-atomic interaction that, when run inside a transaction (which can implicitly happen as soon as a transaction is opened that includes manipulations on the user here), can lead to race conditions.

Transactional Callbacks

To avoid this type of race condition, we can replace this after_save callback with an after_commit callback, which will only fire after the transaction is completed.

This is called a transactional callback.

The available transactional callbacks to date are:

after_commit
after_rollback

Transactional callbacks are native to ActiveRecord models and follow a simple principle: instead of relying on a model-related event, they rely on the state of an ActiveRecord transaction, meaning that any block of logic passed to it will be registered and called only when the transaction is closed.

It is important to note that an after_commit statement is not specific to transactions on the current model, but will wait for every level of nested transactions around it to be closed.

Let’s see an example, involving two models and an asynchronous job:

class User < ApplicationRecord
  after_commit :do_something_asynchronous

  private

  def do_something_asynchronous
    SyncUser.perform_later(user_id: self.id)
  end
end

class Post < ApplicationRecord
  after_commit :log_something

  private

  def log_something
    Rails.logger.info("Post with ID #{id} was committed")
  end
end

class SyncUser < ApplicationJob
  def perform(user_id:)
    user = User.find(user_id)
    Post.first.update(content: 'NEW CONTENT')

    sleep(5)

    # Some business logic on the user and post...

    puts "ASYNC action on user with ID: #{user_id}"
  end
end

When executing the following code in a console...

# Rails console
Post.transaction do
  user = User.new(name: 'John DOE')
  user.save

  # We wait for 5 sec to simulate a (very) long transaction
  sleep 5
end

#  TRANSACTION (1.0ms)  BEGIN
#  User Create (1.1ms)  INSERT INTO "users" ("name", "created_at", "updated_at") VALUES ($1, $2, $3) RETURNING "id"  [["name", "John DOE"], ["created_at", "2024-12-05 18:10:51.580199"], ["updated_at", "2024-12-05 18:21:24.721670"]]
#  TRANSACTION (0.9ms)  COMMIT

# Sidekiq server
# Performing SyncUserJob [...] from Sidekiq [...] enqueued at 2024-12-05T18:21:29Z with arguments: {:user_id=>1}
# Post with ID 1 was committed at: 2024-12-05T19:21:30+01:00
# Performed SyncUserJob [...] in 5071.17ms

Based on the timestamps of user update, job enqueuing, Post's callback logging, and job ending, we can deduce that:

The user was persisted while the transaction on Post was still open (you don't have the timestamp of my tapping ENTER in my console, but believe me, this DB operation was instantly committed)
The after_commit callback on User waited 5 seconds before being triggered, resulting in the Sidekiq job being enqueued 5 seconds later than the user's creation date. We can deduce from this part that the transactional callback is not restricted to a DB transaction on the table linked to the model bearing the callback, but waits for any open transaction to be closed.
The job was quickly performed (~1 second after being enqueued), and the callback on Post was triggered right away, as a result of the Post.first.update(...) operation it contains
The job then slept for 5 seconds before ending. At this stage, no ongoing transaction remained open

Breaking down this example on a classic ActiveRecord model highlights the benefits of transactional callbacks to ensure data integrity throughout your model’s lifecycle.

I would add that relying on callbacks remains a tricky practice, and shouldn’t be generalised. In many cases, using an interaction pattern or a simple service object to encapsulate DB manipulations and their side-effects might be the most efficient and straightforward move.

Now, what if we wanted to run a callback on the event of the successful execution of some service object, outside of a specific model?

The after_commit_everywhere gem

Let's illustrate this case with the following example of a service that manipulates posts and users simultaneously:

class BusinessLogicService
  def call(user_id)
    user = User.find(user_id)

    Post.transaction do
      user.posts.update_all(active: false)

      user.update!(active: false)
    end

    puts 'transaction ongoing'
  end
end

What if I want to send an email (or perform any other action) as soon as this transaction is committed?

Since we are not in an ActiveRecord model, we can't use the after_commit callback mentioned above.

Fortunately, a great gem called after_commit_everywhere (GitHub project here) offers a plug-and-play solution to tackle this case.

The principle is simple: include the AfterCommitEverywhere module, and you'll have access to after_commit, after_rollback, and before_commit "callbacks" wherever you need them:

include AfterCommitEverywhere

class BusinessLogicService
  def call(user_id)
    user = User.find(user_id)

    Post.transaction do
      user.posts.update_all(active: false)

      user.update!(active: false)

      after_commit do
        puts 'transaction over!'
        # do something
      end

      puts 'transaction ongoing'
    end
  end
end

Okay, but how does this work under the hood?

Let's see what a call to after_commit does, in the gem's source code

It "registers a callback" in the form of a block or proc
- Checks if a transaction is active
  - Gets the active ActiveRecord::Base.connection if any, defines one otherwise
  - Calls ActiveRecord::ConnectionAdapters::DatabaseStatements#transaction_open? on the connection
- If a transaction is active
  - If prepend option is passed
    - Fetches the array of records (models with callbacks defined on them) on the connection's current_transaction
  - else (general case)
    - Wraps the callback in an ActiveRecord model-like class called Wrap, to be able to register transactional callbacks on it. This is the trick that allows usage of ActiveRecord's native callbacks.
    - Calls ActiveRecord::ConnectionAdapters::DatabaseStatements#add_transaction_record on the connection with the wrapped callback
- If no transaction is active
  - Yields the callback or raises, depending on config

As you can see, what I like about this gem is that it relies only on ActiveRecord's internals and simply exposes them in a simple, plug-and-play module.

As a conclusion, transactional callbacks offer a powerful tool for maintaining data integrity and ensuring atomicity in complex DB operations.

With the help of after_commit_everywhere, we can take this concept further and use them outside of ActiveRecord models, but, it's important to remember that over-reliance on callbacks can lead to tightly coupled code and potential performance issues.

Transaction Safety in Rails: Identifying and Addressing Non-Atomic Interactions

Lucas M. — Thu, 21 Nov 2024 17:23:37 +0000

Database transactions are a crucial mechanism for maintaining data integrity in the face of unexpected errors or failures. They ensure that multiple related operations are treated as a single, indivisible unit of work.

While transactions are very common and often implicit in many Rails operations, in some cases mixing them with asynchronous actions might lead to unexpected results.

Let's consider a practical example to illustrate potential issues, with a simple model and an asynchronous job (in our case, a Sidekiq job):

class User < ApplicationRecord
  after_save :do_something_asynchronous

  private

  def do_something_asynchronous
    SyncUser.perform_later(user: self)
  end
end

class SyncUser < ApplicationJob
  def perform(user_id:)
    user = User.find(user_id)

    # Some business logic on the user...

    puts "ASYNC action on user with ID: #{user_id}"
  end
end

In normal circumstances, this code works as expected:

# Rails console
user = User.new(name: 'John DOE')
user.save
# => true

# Sidekiq server
## Performing SyncUserJob [...] from Sidekiq [...] with arguments: {:user_id=>1}
## ASYNC action on user with name: John DOE
## Performed SyncUserJob [...] in 37.25ms

However, let’s see what happens if a wrapping transaction prevents my save call to be committed immediately to the DB:

# Rails console
User.transaction do
  user = User.new(name: 'John DOE')
  user.save

  # We wait for 5 sec to simulate a (very) long transaction
  sleep 5
end

# Sidekiq server
# Performing SyncUserJob [...] from Sidekiq [...] with arguments: {:user_id=>2}
# Discarded SyncUserJob due to a ActiveRecord::RecordNotFound.
# Performed SyncUserJob [...] in 37.25ms

We can see here that the job was performed in Sidekiq with an ActiveRecord::RecordNotFound error.

This is due to the fact that, at the time of executing the job’s logic (in the Sidekiq server’s runtime), the DB operation hasn’t been committed yet (in the Rails app’s runtime), meaning the object does not exist in the DB.

Non-atomic interactions in transactions

Non-atomic interactions occur when asynchronous actions are triggered within a transaction that hasn't been committed yet. This situation can lead to race conditions on the executed async job due to the following reasons:

The transaction can potentially rollback, causing data inconsistencies
Even in successful operations, the transaction might take longer than expected to commit due to additional tasks being executed, leading to unexpected behaviours

In a Rails environment, a common source of implicit non-atomic interactions is ActiveRecord's native after_save callback, which wraps its content in a transaction and runs side actions regardless of the transaction's outcome.

While identifying them manually can sometimes be cumbersome, fortunately a great tool has been developed for this exact purpose...

The Isolator gem

Isolator is a great 'plug-n-play' gem designed to detect non-atomic interactions within database transactions automatically.

It raises an error every time it detects such an interaction, helping you identify and address these issues as early as possible in your development process.

It supports multiple adapters to catch operations in different contexts that are at risk of non-atomic interactions.

Using Isolator locally

The gem needs little to no configuration to work, depending on your context.

In our case, let’s Install the gem, and add minimal config:

# Gemfile

group :development, :test do
  gem 'isolator'
end

# initializers/isolator.rb

Isolator.configure do |config|
  # Specify a custom logger to log offenses
  config.logger = nil

  # Raise exception on offense
  config.raise_exceptions = true # true in test env

  # Send notifications to uniform_notifier
  config.send_notifications = false

  # Customize backtrace filtering (provide a callable)
  # By default, just takes the top-5 lines
  config.backtrace_filter = ->(backtrace) { backtrace.take(5) }

  # Define a custom ignorer class (must implement .prepare)
  # uses a row number based list from the .isolator_todo.yml file
  config.ignorer = Isolator::Ignorer
end

Let’s now re-run the same example:

# Rails console
User.transaction do
  user = User.new(name: 'John DOE')
  user.save

  # We wait for 5 sec to simulate a (very) long transaction
  sleep 5
end

# Isolator::BackgroundJobError: You are trying to enqueue background job inside db transaction. In case of transaction failure, this may lead to data inconsistency and unexpected bugs
# Details: SyncUserJob ({:user_id=>2})

We now get an Isolator::BackgroundJobError error that prevents SyncUserJob from being enqueued, hence protecting data consistency.

In this specific case, several simple solutions exist to prevent this behaviour:

Use a transactional callback
- Transactional callbacks like after_commit or after_rollback are native Rails tools that work the same as the standard callbacks, except that they don’t execute until after database changes have either been committed or rolled back.
Avoid the use of callbacks for such sequential actions, and favour an interaction (as in the Interaction Pattern) or other kinds of service objects to encapsulate and sequentially run the logic of user creation followed by its job scheduling.

Conclusion

While the aforementioned example describes a simple case of non-atomic interaction wrapped in a transaction, real-world applications can obviously involve far more complex scenarios, where identifying these issues manually can be very tricky.

Although it is important to note that it won’t fix all your issues, Isolator is a great tool to help with such concerns. It is recommended for use in both test and development environments, preferably in a ‘whiny’ mode that raises errors when detecting dangerous operations. While it can be plugged into staging environments, extra careful consideration should be given to this approach.

Streamlining Rails Controllers with Simple PORO Validators

Lucas M. — Fri, 08 Nov 2024 11:50:10 +0000

Disclaimer: This article proposes a straightforward approach to request validation in Rails controllers. While it doesn't claim to be a perfect solution for every scenario, it presents a simple pattern that can be applied to many cases and help simplify controller responsibilities.

Observation

When dealing with complex Rails controllers, finding an elegant and maintainable way to perform validations on incoming requests can be challenging, be it to simply check the presence of mandatory attributes or to deal with more intricate business-logic checks.

Let’s consider this basic controller as an example:

class SimpleController < ApplicationController
  def perform_computation
    service = MyBusinessLogicService(
      param1: params[:param1],
      param2: params[:param2],
      param3: params[:param3]
    ).new
    result = service.perform

    respond_to do |format|
      format.json { render json: result }
      format.html { render text: result.to_s }
    end
  end
end

It defines a simple action that calls a business-logic service and returns the result.

Now, suppose we need to perform various validations, of different natures:

Check that param1 and param2 are present
Check that the current user has the permission to perform this action, depending on its role (RBAC)
Check that the current user has an attribute active set to true

Given the nature of the validations at stake here (input-related validation, session-related validation, and business-logic validation), we are likely to come to the conclusion that the controller is not the ideal place to perform them.

The controller's primary role should focus on instantiating/updating/deleting objects, invoking services or libraries containing business logic, and formatting output data before rendering.

Disclaimer: In real-life cases, parameter validation and authorisation checks are likely to be split and/or factored out of the controllers. I am including them in the same validator here for the sake of the example, by lack of more business logic checks.

The validator pattern

Instead of cluttering the controller action with validation-related code, let’s define the following ‘validator’ class:

class RequestValidator
  class UnauthorizedError < StandardError; end
  class InactiveUserError < StandardError; end

  def initialize(param1:, param2:, param3:, user:)
    @param1 = param1
    @param2 = param2
    @param3 = param3
    @user = user
  end

  def call!
    validate_required_params!
    validate_user_role!
    validate_user_is_active!
  end

  private

      def validate_required_params!
        raise ParameterMissing, :param1 if @param1.blank?
        raise ParameterMissing, :param2 if @param2.blank?
      end

      def validate_user_role!
        raise UnauthorizEderror, 'User not allowed to perform this action' unless RoleChecker(user: user).allowed?
      end

      def validate_user_is_active!
        raise InactiveUserError, "User is not active" unless @user.active?
      end
end

Instead of having a bloated controller, we can now plug validations in a very light fashion:

class SimpleController < ApplicationController
  def perform_computation
    validate_computational_request!

    service = MyBusinessLogicService(
      param1: params[:param1],
      param2: params[:param2],
      param3: params[:param3]
    ).new
    result = service.perform

    respond_to do |format|
      format.json { render json: result }
      format.html { render text: result.to_s }
    end

  rescue RequestValidator::UnauthorizedError => e
    render json: { error: e.message }, status: :unauthorized
  rescue RequestValidator::InactiveUserError => e
    # Some custom logic
    # ...
  end

  private

    def validate_computational_request!
      RequestValidator.new(
        param1: params[:param1],
        param2: params[:param2],
        param3: params[:param3],
        user: current_user
      ).call!
    end
end

Principle / Benefits

PORO Object: The validator is implemented as a Plain Old Ruby Object (PORO), avoiding dependencies and complex designs.
Single Responsibility: Each validator object has a single responsibility and a single instance method (call!), adhering to the Single Responsibility Principle.
Separation of Concerns: The validation logic is clearly separated from the business logic, improving maintainability and readability.
Straightforward Error Handling:
- Sequential validations allow each step to raise specific errors with more informative context, aiding in debugging.
- Namespaced errors enable targeted exception handling, whether in individual actions or parent controllers. This can help logging relevant information prior to rendering custom messages.
Modularity and Reusability: Validator classes can be easily reused across different controllers or actions, promoting code reuse and consistency.
Improved Testability: With validations isolated in separate objects, unit testing becomes more focused and efficient.
Reduced Controller Complexity: By moving validations out of controllers into dedicated objects, we achieve thinner, more manageable controllers.

This approach to request validation using simple PORO objects offers a clean, maintainable way to handle complex validation scenarios in Rails applications, leading to more organised and scalable codebases.

Ruby exception Handling Pitfall: Understanding Rescue Clause Hierarchy

Lucas M. — Wed, 30 Oct 2024 17:17:25 +0000

Context

Let's consider the following code, defining basic classes and one custom error:

class CustomError < StandardError; end

class Parent
  def raise_custom_error
    raise CustomError
  rescue StandardError
    puts "StandardError rescued"
  end
end

class Child < Parent
  def call
    raise_custom_error
  rescue CustomError
    puts "CustomError rescued"
  end
end

Now, let's examine the following method call::

Child.new.call

To summarize, this code does the following:

Defines a CustomError class that inherits from StandardError
Creates a Child class with a #call method that invokes raise_custom_error from its parent class Parent
Implements exception handling in both Child#call and Parent#raise_custom_error

Given this setup, we might expect the exception handling mechanism in Child#call to be triggered, as it appears to be the most specific. However, the actual output of the call is:

StandardError rescued

Surprisingly, we end up executing the more generic error handling defined in Parent#raise_custom_error.

How Rescuing Works

When Ruby encounters a raise statement, it looks up the call stack for matching rescue clauses. It checks whether the raised exception is a subclass of any exception specified in the rescue clause.

Explanation of the behaviour

The output "StandardError rescued" occurs because:

When Parent#raise_custom_error raises CustomError, Ruby looks for matching rescue clauses in the method where the exception was raised
It finds the rescue StandardError clause in Parent#raise_custom_error
Since CustomError inherits from StandardError, this rescue clause matches and handles the exception
By the time execution returns to Child#call, the exception has already been handled, so the rescue CustomError clause in Child#call never gets a chance to execute

Conclusion

Error-rescuing blocks cannot be written completely agnostically of the current class hierarchy. The order and specificity of rescue clauses matters due to exception inheritance.
When dealing with exceptions raised in parent classes, the rescue block in the parent class may catch exceptions before they reach the child class.

To avoid such scenarios, we can apply a principle related to exception hierarchy, which is closely tied to the Liskov Substitution Principle (LSP). The LSP states that subtypes should be substitutable for their base types, meaning that any code using a parent class should be able to work with a child class without knowing the difference.

In the context of exception handling specifically:

More general exceptions should be caught at lower levels in the call stack or inheritance hierarchy.
More specific exceptions should be caught closer to where they are raised.

Adding a Rubocop config to an old repository | step-by-step guide

Lucas M. — Wed, 23 Oct 2024 07:59:37 +0000

While using Rubocop as a linter/formatter is a no-brainer for most Rails developers these days, it wasn’t always the case. This means that there are probably tons of repositories of applications or gems out there still not benefitting from any linter configuration, and solving this issue might sometimes be cumbersome, especially on old code.

Here’s a little step-by-step guide on how to do it, based on a recent update I made on an open-source lib I was working on, on which some files are more than 10 years old.

Disclaimer: this guide assumes that the code under scrutiny has a proper test suite, which is a requirement for serene code-refactoring of any nature.

Install Rubocop & relevant extensions

First, I recommend installing the Rubocop gem and a few extensions, by adding them to your Gemfile and running bundle install:

rubocop (required)
rubocop-performance
rubocop-rails
rubocop-rspec

Each one of these extensions comes with a specific set of cops (=linting rules) addressing specific needs. Check out their respective documentations on the Rubocop doc, and do not hesitate to add more of them if it suits your needs.

Check for existing .rubocop.yml config, or create one

In my case, there was an existing Rubocop config in the form of a .rubocop.yml file, that had not been updated for years and had never been enforced, meaning that most of the cops were out-of-date or just not respected.

In this case, you can add minimal configuration by updating this file as follows:

inherit_from: .rubocop_todo.yml

# The behavior of RuboCop can be controlled via the .rubocop.yml
# configuration file. It makes it possible to enable/disable
# certain cops (checks) and to alter their behavior if they accept
# any parameters. The file can be placed either in your home
# directory or in some project directory.
#
# RuboCop will start looking for the configuration file in the directory
# where the inspected file is and continue its way up to the root directory.
#
# See https://docs.rubocop.org/rubocop/configuration

require:
  - rubocop-performance
  - rubocop-rake
  - rubocop-rspec

AllCops:
  TargetRubyVersion: 3.3 # To be changed to suit your needs
  NewCops: enable
  Exclude:
    - tmp/**/*
    - vendor/bundle/**/* # Recommended if you are using Github Actions
  DisplayCopNames: true

# … 
# Here comes the config specific to each of the cops. If starting from scratch, you shouldn’t have any.

If not already existing, you can simply create this file manually.

You will then need to create an empty .rubocop_todo.yml file at the root of your directory for this file to load properly. We will see in an upcoming step what to do with this file.

You can now run bundle exec rubocop in your terminal to check that the config file is correctly loaded. In my case, some errors occurred because of a few of the cops mentioned in the config being outdated. I simply followed the prompted instructions to fix these, and ended up with a clean config file.

Run `rubocop —autocorrect`

Now that you have a proper Rubocop config, you can run the rubocop command with the --safe-auto-correct option in order for the gem to safely refactor every piece of code that doesn’t respect the imported list of cops:

bundle exec rubocop --safe-auto-correct

Note: This command might result in a numerous amount of changes, hence I suggest committing your previous changes in the first place in order to be able to separate autocorrection changes from configuration ones in your VCS.

Fix Potential Broken Code

Once the changes are made, ensure no logic has been broken. Run your test suite and inspect the results of the previous command by carefully reading the diff before committing anything.

If you need to disable a misbehaving cop, add it to the .rubocop.yml file as follows, and re-run the autocorrect command:

Style/MultilineBlockChain: # Replace with the cop to be deactivated
  Enabled: false

Once satisfied with the results and confident that the code will run, commit your changes before proceeding to the next step.

Whitelist desired cops autocorrectable with rubocop -A

After autocorrecting the safe offenses, you can either stop here or address the unsafe ones. Unsafe cop corrections are more likely to break your code but can sometimes be autocorrected by the gem. To retain only the ones that do not break any logic, follow these steps:

Run the following command:

bundle exec rubocop -A

Run your test suite and identify the changes that broke it
In Rubocop’s logs, find the precise cops responsible for the changes
Add them to the list of ignored cops in the .rubocop_todo.yml file by running:

rubocop --auto-gen-config --only <YourCopName>

Checkout the previously committed version of every file except .rubocop_todo.yml
Repeat the steps until your test suite succeeds

Inspect the results of the previous operation by carefully reading the diff before committing anything. Once satisfied with the results and confident that the code will run, commit your changes.

You have now run unsafe autocorrection on your entire repository while excluding the non-autocorrectable cops by adding them to a ‘TODO’ file, where you can address them later.

Run rubocop --auto-gen-config to complete the .rubocop_todo.yml file

At this stage, we have covered every autocorrection Rubocop can make. However, some offenses might remain. You can either fix them manually or temporarily append them to the .rubocop_todo.yml file as a TODO list to handle later. The following command will add all remaining offenses’ associated cops to the file:

bundle exec rubocop --auto-gen-config

You can now commit these changes as well, and your repository should subsequently be offence-free. 🎉

Bonus: Ignore the Resulting Revisions in Your git blame

Running autocorrection commands can result in hundreds of lines of diff being committed, polluting the git blame results for other contributors.
To avoid this, use the git --ignore-revs-file feature (documentation here), which lists the revision numbers (or commit SHAs) to be ignored by git blame in a designated file, thus not taking them into account when displaying the future.

Bonus #2: Add a CI step (recommended)

The best way to avoid upcoming offenses is to add a CI task running the Rubocop command and preventing anyone from merging code that contains offenses.

If you are using Github Actions, basic actions exist to ensure this in the simplest way.

The importance of the environment in Regex pattern matching

Lucas M. — Wed, 16 Oct 2024 11:49:34 +0000

Here’s a small discovery I made regarding Ruby regex rules and whitespace characters, that made me scratch my head for a moment:

Let’s have a look the following string, extracted from an email body:

From :     John DOE <test@test.com>

Please note that the space character between 'From' and the column (‘:’) is a Non-Breaking Space Character (U+00A0 in Unicode), while the other spaces in this string are regular whitespaces (U+0020).

Let’s now consider the following regex rule, defined in a Ruby constant:

REGEX = /(?:From)\s*:\s*(?:.*?<)?([^<>\s]+@[^>\s]+)(?:>)?/i

When testing the mentioned string against this regex in a Ruby console, we don’t get any match:

REGEX.match(‘From :  John DOE <test@test.com>’)
=> nil

Why, you may wonder?
The reason for this is that the \s matcher does not look for Non-Breaking Space Characters. In order to make it work, we need to update the regex to explicitly expect NBSC characters, as follows:

REGEX = /(?:From)[\s\u00A0]*:\s*(?:.*?<)?([^<>\s]+@[^>\s]+)(?:>)?/i

Everything looks fine up to that point.

However - here it becomes weird - when testing the original regex rule (the first one, without the \u00A0 part) on the same string in an interactive visualiser (https://regexr.com/ for instance), there is a match:

My understanding of the situation is that the interactive Regex visualiser actually converts the NBSC to regular whitespace when copy-pasting the string into its text input, simply because the browser interprets it as a regular whitespace in its HTML rendering.

This little experiment highlights the importance of testing regex patterns in the exact environment where they will be used. While online tools can be helpful for quick tests, they don't always accurately represent how the regex will behave in your production environment.

PS: It is worth mentioning that the string under scrutiny was copy-pasted from the original email at every stage of this experiment, meaning that the string itself wasn’t transformed by the copy-pasting operation.

DEV Community: Lucas M.

How to set a timeout to RSpec test executions

TL;DR

Introduction / Motivation

First iteration / Thread-joining

Cleaning the error trace / better error-handling

The RSpec.current_example issue / better thread handling

Second iteration / single-thread monitoring implementation

Notes / final comments

Rails transactional callbacks beyond models

Legacy / Model Callbacks

Transactional Callbacks

The after_commit_everywhere gem

Transaction Safety in Rails: Identifying and Addressing Non-Atomic Interactions

Non-atomic interactions in transactions

The Isolator gem

Using Isolator locally

Conclusion

Streamlining Rails Controllers with Simple PORO Validators

Observation

The validator pattern

Principle / Benefits

Ruby exception Handling Pitfall: Understanding Rescue Clause Hierarchy

Context

How Rescuing Works

Explanation of the behaviour

Conclusion

Adding a Rubocop config to an old repository | step-by-step guide

Install Rubocop & relevant extensions

Check for existing .rubocop.yml config, or create one

Run rubocop —autocorrect

Fix Potential Broken Code

Whitelist desired cops autocorrectable with rubocop -A

Run rubocop --auto-gen-config to complete the .rubocop_todo.yml file

Bonus: Ignore the Resulting Revisions in Your git blame

Bonus #2: Add a CI step (recommended)

The importance of the environment in Regex pattern matching

The `RSpec.current_example` issue / better thread handling

Run `rubocop —autocorrect`