Preserving Flash Messages in Rails: A Deep Dive

Rails' flash messages provide a convenient way to display temporary information across requests. However, their behavior can be surprising, especially when dealing with redirects and logging. This post explores the intricacies of Rails flash messages, focusing on a scenario involving flash sales and logging user journeys. We'll uncover why flash messages might disappear unexpectedly and present a robust solution to reliably preserve them.

Flash Sale!

Imagine an e-commerce site with a flash sale. Links to this sale are scattered across various pages. The call-to-action (CTA) displayed on the flash sale page should reflect the originating page. We'll store this CTA in a flash message.

class ContactsController < ApplicationController
  def index
    if FlashSale.on?
      flash[:sale] = "Thanks to you for looking to contact us"
    end
  end
end

The sale might end between a user navigating from, say, the contact page to the flash sale. In this case, we redirect to the general products page but still want to display the CTA indicating the user's origin.

We also sample requests to log information. If the sale is over and the request is sampled, we log the CTA to track user paths.

class FlashSalesController < ApplicationController
  def index
    if FlashSale.off?
      if AttemptLogger.log?
        Rails.logger.info "CTA '#{flash[:sale]}' used to access flash sale after it's over"
      end

      redirect_to products_path and return
    end

    @products = [
      donner_red_hss_starter_kit,
      martin_junior_acoustic,
      squier_affinity_strat_junior_hss,
    ]
  end
end

The products page view displays the flash message, maintaining context even if the flash sale has concluded.

<h1>All Products</h1>

<% if flash[:sale].present? %>
  <p> <%= flash[:sale] %> </p>
<% end %>

Gone In A Flash (Testing)

Let's write system tests to validate this behavior. First, we verify the redirect when the flash sale ends before the user views it.

it "redirects to the products page with the flash message when the flash sale has ended" do
  allow(FlashSale).to receive(:on?).and_return(true)
  visit contacts_path

  allow(FlashSale).to receive(:off?).and_return(true)
  click_link "View Deals"

  expect(page).to have_selector "h1", text: "All Products"
  expect(page).to have_content "Thanks to you for looking to contact us"
end

This test passes. However, a similar test that logs the CTA fails.

it "logs the flash message when the flash sale has ended and the log sampler wants the message" do
  allow(FlashSale).to receive(:on?).and_return(true)
  visit contacts_path

  allow(FlashSale).to receive(:off?).and_return(true)
  allow(AttemptLogger).to receive(:log?).and_return(true)
  click_link "View Deals"

  expect(page).to have_selector "h1", text: "All Products"
  expect(page).to have_content "Thanks to you for looking to contact us"
end

The flash message is missing. The Rails documentation states: "Anything you place in the flash will be exposed to the very next action and then cleared out." This is not clear-cut, as our initial test passed despite multiple actions.

Viewing Source In A Flash

The Rails source code provides clarity. Using bundle open actionpack, we examine actionpack/lib/action_dispatch/middleware/flash.rb, specifically the commit_flash method. We add a breakpoint to observe its behavior during our tests.

def commit_flash
+  binding.irb # Added by us!
   return unless session.enabled?

   if flash_hash && (flash_hash.present? || session.key?("flash"))
     session["flash"] = flash_hash.to_session_value
     self.flash = flash_hash.dup
   end

   if session.loaded? && session.key?("flash") && session["flash"].nil?
     session.delete("flash")
   end
end

Debugging reveals that when logging the message, flash_hash is not nil, but the flash message still disappears. This stems from how flash_hash is obtained (via flash=) and its conversion to a session value in to_session_value. Examining this method and the related flash method clarifies the circular dependency and how flash_hash ultimately gets set.

Flash Back (Analysis)

Let's examine the commit_flash conditions.

if flash_hash && (flash_hash.present? || session.key?("flash"))
  session["flash"] = flash_hash.to_session_value
  self.flash = flash_hash.dup
end

Without logging, flash_hash is nil because flash is not called. When logging, flash_hash has a value, but to_session_value discards all keys, resulting in a nil session value for "flash", and the second conditional deletes it.

if session.loaded? && session.key?("flash") && session["flash"].nil?
  session.delete("flash")
end

Logging requires accessing the session, which loads it. The nil value causes the flash to be removed.

Flash Forward (Solution)

The solution is to prevent the flash from being removed. The `keep` method allows us to retain specific flash keys.

class FlashSalesController < ApplicationController
  def index
    if FlashSale.off?
      if AttemptLogger.log?
        Rails.logger.info "CTA '#{flash[:sale]}' used to access flash sale after it's over"
+       flash.keep(:sale)
      end

      redirect_to products_path and return
    end

    @products = [
      donner_red_hss_starter_kit,
      martin_junior_acoustic,
      squier_affinity_strat_junior_hss,
    ]
  end
end

By calling flash.keep(:sale), we ensure the flash message persists, resolving the issue.

An Illuminating Flash (Conclusion)

This exploration revealed the subtleties of Rails flash message handling and how seemingly simple actions can have complex consequences. Directly examining the source code proved invaluable in understanding the underlying mechanics and devising a solution. Remember to leverage tools like bundle open and debugging techniques to unravel similar challenges. Understanding these intricacies can lead to more robust and predictable applications.