Ask Claude to explain a Rails model and it reads through the file, piecing together what the associations mean, inferring what the enum values map to, and hoping it catches all the scopes. It’s reading text and making educated guesses about structure. Ask it to find all callers of a private method before you delete it and it’s doing a best-effort text scan that can miss dynamic calls or alias references.

That ceiling just got raised. Ruby LSP now has official support in Claude Code.

What Is a Language Server Protocol

LSP is a standard that separates language intelligence from the editor. Before LSP, every editor had to implement its own understanding of every language. After LSP, you write the intelligence once as a language server, and any editor that speaks the protocol gets the benefits.

The language server sits alongside your code and maintains a live semantic model of your project. It tracks definitions, references, and symbol relationships across your entire project. When your editor asks “where is this method defined?” or “what are all the callers of this function?”, the server answers in milliseconds with accurate, complete information.

Ruby LSP is Shopify’s language server for Ruby. It integrates with Standard Ruby for diagnostics. In codebases that use Sorbet or Steep, those tools run as separate language servers and provide type information independently of Ruby LSP. Beyond the core server, there’s a growing community of add-on developers building extensions for it. awesome-ruby-lsp is a good starting point if you want to see what’s available.

What You Get

With Ruby LSP connected, Claude gains semantic code intelligence instead of relying on text search. Here’s what that means in practice.

Go to definition. Claude can jump directly to where a method, class, or constant is defined, including inside gems. No more manually tracking down gem source paths.

Find all references. Before a refactor, Claude can ask the language server for every reference to a symbol across your entire project. Dynamic calls included, because the LSP understands Ruby’s metaprogramming patterns well enough to handle common cases.

Call hierarchy. Claude can trace the full call chain for a method, both incoming callers and outgoing calls, across your entire project. That’s useful when you need to understand the impact of a change before making it.

Hover documentation. Claude can pull the YARD documentation for any method without having to search for it manually.

The difference shows up most in refactoring. When you ask Claude to rename a method or change a signature, it can now ask the LSP for the complete reference list before making a single change. That’s the difference between a confident refactor and a hopeful one.

Installing Ruby LSP in Claude Code

You’ll need Ruby LSP installed as a gem first:

gem install ruby-lsp

If you’re working in a bundled project, add it to your Gemfile in the development group:

group :development do
  gem "ruby-lsp"
end

Then install the plugin from inside Claude Code:

/plugin install ruby-lsp@claude-plugins-official

That’s it. The next time you start a Claude Code session in a Ruby project, the LSP server starts alongside it. You don’t need to configure anything. Install it once and it works.

What Changes in Practice

Here’s what it looks like in a real session. I asked Claude about a model in a Rails app:

❯ Use ruby-lsp and tell me about the membership model

⏺ Searched for 1 pattern (ctrl+o to expand)

⏺ LSP(operation: "documentSymbol", file: "app/models/membership.rb")
  ⎿  Found 6 symbols (ctrl+o to expand)

⏺ Read 1 file (ctrl+o to expand)

⏺ Now let me get hover info on a few key symbols:

⏺ LSP(operation: "hover", symbol: "enum", in: "app/models/membership.rb")
  ⎿  Hover info available (ctrl+o to expand)

⏺ LSP(operation: "findReferences", symbol: "Membership", in: "app/models/membership.rb")
  ⎿  Found 24 references across 12 files (ctrl+o to expand)

⏺ Here's a summary of the Membership model:

  app/models/membership.rb

  A join model representing a user's membership in a tenant (organization).

  Key traits:
  - acts_as_tenant :tenant — multi-tenant scoped via ActsAsTenant
  - belongs_to :tenant, belongs_to :user
  - Roles (integer enum): member (1), admin (2), owner (3)
  - scope :owners — filters members with the owner role
  - Validations: user_id must be unique per tenant (one membership per user per org), role must be present

  Used in 12 files across:
  - Controllers: invitations, memberships, organization settings
  - Services: AcceptInvitation, ConfirmUserEmail
  - Specs: model spec, tenant isolation spec, system specs

  The model is minimal — it's purely a pivot between User and Tenant with role-based access control baked in.

That’s a thorough summary. But I was curious what actually came from the LSP versus what Claude found by reading the file. So I asked:

❯ What information did you get from the lsp vs your own search

⏺ Good question. Here's the breakdown:

  From LSP:
  - documentSymbol — gave me the class name, method names, and line numbers without reading the file
    (associations, scope, validations)
  - hover on enum — confirmed it's ActiveRecord::Enum#enum with a link to the gem source definition
  - findReferences — found all 24 references across 12 files without me doing any grep search

  From my own file read (Read tool):
  - The actual source code content — the enum values (member: 1, admin: 2, owner: 3), the acts_as_tenant
    call, the uniqueness scope on the validation (scope: :tenant_id)

  In practice:
  - LSP gave me structure and cross-references (what symbols exist, where they're used project-wide)
  - The file read gave me content (the actual values and implementation details)

  The documentSymbol result notably omitted the acts_as_tenant call and the enum values — it only surfaced
  Rails macro calls it recognized as meaningful symbols. So LSP alone would have left me with an incomplete
  picture of the model.

That second turn is the honest answer. LSP and file reads are complementary. The LSP gives Claude structure and cross-references instantly: what symbols exist, where they’re called across the project, without spending context window tokens on file searches. The file read fills in the content: actual values, implementation details, anything the symbol index doesn’t capture. Together they produce a more complete picture than either alone.

That kind of structural understanding also changes how refactoring works. When you ask Claude to rename a class or change how something is called across the project, it queries the LSP for the complete reference list before making a single change. It isn’t guessing at usage patterns. It knows them.

One thing worth knowing: Ruby LSP works well without a type system. In my testing without Sorbet or Steep, the heuristic inference still produced accurate results for associations, method definitions, and references. If your codebase does use Sorbet or Steep, those type checkers can run alongside the LSP to improve accuracy further, but they’re not required to get value from this integration.

Text search got Claude surprisingly far. Semantic understanding gets it the rest of the way.

If you want help getting Claude Code dialed in for your Ruby workflow, whether that’s 1:1 or across your team, take a look at how I work with developers and teams.

Further Reading

• Ruby LSP on GitHub
• Ruby LSP documentation
• awesome-ruby-lsp
• Language Server Protocol specification
• Claude Code plugins documentation

The Problem

The following is adapted from a real production system but generalized for this post.

Take a theoretical SaaS application. The goal: generate a report of users who have low activity and identify those who are likely to churn. Let’s take a look at an example prompt:

require 'anthropic'
require 'json'

class ChurnRiskAnalyzer
  SYSTEM_PROMPT = <<~PROMPT
    You are a customer success analyst. Your job is to analyze user engagement
    data and identify customers at risk of churning.

    When analyzing users, identify which users are recently converted AND at high
    risk of churning due to low engagement. Pay special attention to:
    - Login frequency relative to their plan type
    - Feature adoption breadth
    - Time since trial conversion

    For each user, state:
    1. Days since conversion
    2. Whether they qualify as a "recent conversion"
    3. Your churn risk assessment and reasoning
  PROMPT

  def initialize
    @client = Anthropic::Client.new
  end

  def analyze(low_engagement_users)
    user_prompt = build_user_prompt(low_engagement_users)

    response = @client.messages.create(
      model: 'claude-sonnet-4-20250514',
      max_tokens: 1024,
      system: SYSTEM_PROMPT,
      messages: [
        { role: 'user', content: user_prompt }
      ]
    )

    response.content.first.text
  end

  private

  def build_user_prompt(users)
    <<~PROMPT
      Analyze the following low-engagement users from the past 30 days:

      #{JSON.pretty_generate(users)}
    PROMPT
  end
end

# Example usage
analyzer = ChurnRiskAnalyzer.new

low_engagement_users = [
  {
    engagement_id: 'eng_001',
    last_login: '2025-12-28',
    logins_past_30_days: 2,
    features_used: ['dashboard'],
    user: {
      id: 'usr_4821',
      email: 'sarah@acme.co',
      plan: 'pro',
      trial_converted_at: '2025-02-15',
      company: 'Acme Corp'
    }
  },
  {
    engagement_id: 'eng_002',
    last_login: '2025-12-20',
    logins_past_30_days: 1,
    features_used: [],
    user: {
      id: 'usr_9174',
      email: 'mike@newstartup.io',
      plan: 'pro',
      trial_converted_at: '2025-12-01',
      company: 'NewStartup'
    }
  }
]

puts analyzer.analyze(low_engagement_users)

Let’s assume the date is December 29th, 2025.

In this example we have two users with low engagement. sarah@acme.co converted back in February 2025 and has 2 logins in the past 30 days. mike@newstartup.io converted December 1st, 2025 and has just 1 login.

The expected behavior: flag Mike as at risk since he converted recently and has minimal engagement. What actually happened: both Mike and Sarah were flagged. Let’s look at why.

Lack of guidance

In the first version of our system prompt, we mention that we want to include recent conversions—but we never define what “recent” means. This leaves it up to the model to decide, which leads to non-deterministic and confusing results. The fix is to provide explicit guidance:

class ChurnRiskAnalyzer
  SYSTEM_PROMPT = <<~PROMPT
    You are a customer success analyst. Your job is to analyze user engagement
    data and identify customers at risk of churning.

    A "recent conversion" is defined as a user who converted from
    trial to paid within the past 30 days.

    When analyzing users, identify which users are recently converted AND at high
    risk of churning due to low engagement. Pay special attention to:

    - Login frequency relative to their plan type
    - Feature adoption breadth
    - Time since trial conversion

    For each user, state:
    1. Days since conversion
    2. Whether they qualify as a "recent conversion"
    3. Your churn risk assessment and reasoning
PROMPT

Now the model has explicit guidance on what makes a “recent conversion.” But we can’t stop here.

Providing a reference date

We’ve updated the prompt to provide explicit guidance on what makes a recent conversion, but there’s still one problem—the model doesn’t know what the current date is. LLMs have no system clock access; they only know what you tell them. One way to resolve this is to provide the date as part of the prompt:

  def build_user_prompt(users)
    <<~PROMPT
      Today's date is: #{Date.today.iso8601}.

      Analyze the following low-engagement users from the past 30 days:

      #{JSON.pretty_generate(users)}
    PROMPT
  end

Now the model has everything it needs for accurate reporting. Running this updated version correctly excludes Sarah, who signed up months ago, and flags only Mike.

Conclusion

When working with LLMs and time-sensitive data:

1. Be explicit about definitions - Don’t assume the model interprets terms like “recent” the same way you do.
2. Always provide the current date - LLMs have no awareness of real-time; include today’s date in your prompt.
3. Test with edge cases - Run your prompts with data that spans different time periods to catch these issues early.

These might seem like small details, but in production systems where accuracy matters, they make the difference between useful analysis and misleading results. Subtle errors like these erode trust quickly.

Building LLM features into a Rails app and running into issues like this? My book Building LLM Applications in Rails covers the patterns that hold up in production.

In the ever-evolving world of web development, choosing the right technology stack is crucial for building efficient and maintainable applications. We moved away from React and GraphQL, opting instead for traditional REST APIs and Rails-based views, leveraging the power of the ViewComponents gem.

The initial tech stack: React and GraphQL

Buoy Software’s journey began with a mobile application built using React Native and powered by a GraphQL API in a Ruby on Rails application. The success of this project led us to adopt similar technologies for our web application, resulting in a React based front-end using webpacker. This approach allowed for code reuse and consistency across platforms, which seemed like an ideal solution at the time. For our small team, it was easier to maintain a shared pattern when moving between the React Native application and our web application.

Buoy Hackathon 2023

Buoy is a fully remote company and we have an annual hackathon where we get the entire company together to spend time together in person. This is typically 2-3 days where we work on various hackathon projects pitched by the team. One team pitched an idea to move our stack away from React and GraphQL to Rails views. One of the things we enjoyed about React though, was the component system for building UIs.

Challenges faced with React and GraphQL in Rails

While starting off with GraphQL and React worked very well for our small team to bootstrap our web application, over time we were presented with challenges that made us rethink our approach.

Inherent complexity within the application

Simple tasks which could easily be accomplished in a traditional Ruby on Rails application started to become more and more complex. A simple feature which might only need a REST controller and some views in a traditional Ruby on Rails application would instead need GraphQL types, fields, mutations and resolvers. We leveraged Typescript on the front-end which meant we needed to generate types for all of our queries. Then we needed to create complex React components to bring the whole thing together.

This complexity also appears when attempting to debug any issues that might arise. With so many places to look across the stack, finding the root cause of a problem is not straightforward.

The illusion of sharing an API

When kicking things off, we had grand visions of a single source of truth GraphQL API that powered our donor’s mobile app as well as our donor management system in one single API. Time would prove otherwise. As it turned out APIs that the mobile application relied on were fairly different from those that the donor management system required. The ones that were similar required vastly different permission scopes. We ended up spending more time trying to build a shared API rather than building dedicated APIs as needed.

Complexity in onboarding new team members

At Buoy we believe in hiring full-stack software engineers. This proved more difficult with our complex framework for building out front-ends. While this wasn’t an impossible task to get engineers up and running, it has proven to be a learning curve for sure.

Understanding ViewComponents in Ruby on Rails

What are ViewComponents?

ViewComponents is a framework for building reusable, testable, and encapsulated view components in Ruby on Rails. Inspired by similar concepts in modern JavaScript frameworks such as React, ViewComponents allows developers to create modular, object-oriented views that can be easily composed and reused across an application. Think React components written in Ruby and used in Rails views.

To get started install the gem via gem install view_components or add it to your Bundle file. Now, take the following React component:

import React from 'react';
import PropTypes from 'prop-types';

const VARIANT_STYLES = {
  info: 'bg-blue-100 text-blue-800 border-blue-500',
  success: 'bg-green-100 text-green-800 border-green-500',
  warning: 'bg-yellow-100 text-yellow-800 border-yellow-500',
  error: 'bg-red-100 text-red-800 border-red-500',
};

const Banner = ({ variant = 'info', message, onClose }) => {
  return (
    <div className={`p-4 border-l-4 ${VARIANT_STYLES[variant]}`}>
      <div className="flex justify-between items-center">
        <p>{message}</p>
        {onClose && (
          <button
            onClick={onClose}
            className="text-gray-500 hover:text-gray-700"
            aria-label="Close"
          >
            &times;
          </button>
        )}
      </div>
    </div>
  );
};

Banner.propTypes = {
  variant: PropTypes.oneOf(['info', 'success', 'warning', 'error']),
  message: PropTypes.string.isRequired,
  onClose: PropTypes.func,
};

export default Banner;

To replicate this with ViewComponents we’ll want the following. First we’ll want to create a new directory within our app folder called app/components. The common way to build components is to have 2 files, one is the class to hold any logic behind our component and the other is the erb template. For the example above we’ll have 2 new files.

# app/components/banner_component.rb
class BannerComponent < ViewComponent::Base
  VARIANT_STYLES = {
    info: "bg-blue-100 text-blue-800 border-blue-500",
    success: "bg-green-100 text-green-800 border-green-500",
    warning: "bg-yellow-100 text-yellow-800 border-yellow-500",
    error: "bg-red-100 text-red-800 border-red-500"
  }.freeze

  def initialize(variant: :info, message:, closable: false)
    @variant = variant
    @message = message
    @closable = closable
  end

  def variant_class
    VARIANT_STYLES[@variant]
  end

  private

  attr_reader :variant, :message, :closable
end

Paired with an erb template in app/components/banner_component.html.erb

<!-- app/components/banner_component.html.erb -->
<div class="p-4 border-l-4 <%= variant_class %>">
  <div class="flex justify-between items-center">
    <p><%= message %></p>
    <% if closable %>
      <%= button_to "&times;".html_safe,
                    nil,
                    method: :get,
                    class: "text-gray-500 hover:text-gray-700",
                    aria: { label: "Close" },
                    data: { action: "click->banner#close" } %>
    <% end %>
  </div>
</div>

We can then render our component in a view like so:

<%= render(BannerComponent.new(variant: :success, message: "Operation completed successfully!", closable: true)) %>

Testing our component

To test our component we can utilize Spec.

# spec/components/banner_component_spec.rb
require "rails_helper"

RSpec.describe BannerComponent, type: :component do
  it "renders each variant with the appropriate CSS classes" do
    BannerComponent::VARIANT_STYLES.each do |variant, expected_class|
      component = BannerComponent.new(variant: variant, message: "Test message")
      render_inline(component)
      expect(page).to have_css("div.border-l-4.#{expected_class}")
    end
  end

  it "renders the message" do
    message = "This is a test message"
    component = BannerComponent.new(variant: :info, message: message)
    render_inline(component)
    expect(page).to have_text(message)
  end

  it "renders a close button when closable is true" do
    component = BannerComponent.new(variant: :info, message: "Test", closable: true)
    render_inline(component)
    expect(page).to have_button(class: "text-gray-500 hover:text-gray-700", text: "×")
  end

  it "does not render a close button when closable is false" do
    component = BannerComponent.new(variant: :info, message: "Test", closable: false)
    render_inline(component)
    expect(page).not_to have_button(class: "text-gray-500 hover:text-gray-700", text: "×")
  end

  it "applies the correct variant class" do
    component = BannerComponent.new(variant: :success, message: "Test")
    expect(component.variant_class).to eq("bg-green-100 text-green-800 border-green-500")
  end
end

Note our use of the type: component here.

Benefits of ViewComponents over React components

1. Server-side rendering: ViewComponents are rendered on the server, reducing the client-side JavaScript payload and improving initial page load times.

2. Seamless integration: As a native Rails solution, ViewComponents integrates smoothly with existing Rails patterns and helpers. No more jumping through hoops fighting with a JavaScript build tool like webpacker for simple tasks.

3. Testability: ViewComponents can be unit tested in isolation, improving overall code quality and maintainability using the tools our team was already comfortable in, RSPec.

Buoy Software’s Journey to Adopting ViewComponents

Transitioning an existing Rails application to ViewComponents required careful planning. Our application had grown quite large by the time we decided to move away from React so finding a way to incrementally make this change was of the utmost importance.

Our team began by identifying key areas where React components could be replaced with ViewComponents. At Buoy we leverage feature flags which were a great tool for this. We began by identifying the lowest risk area to introduce our change and began there. The team gradually refactored these components, ensuring that the application’s functionality remained intact throughout the process.

To ensure we did not find ourselves in a migration that stopped feature development for months we took an iterative strategy to roll out the changes. As we made changes to the codebase to update existing features we took it as an opportunity to do a migration to ViewComponents.

To further ensure value was being provided by this migration we paired it with a redesign of our application which moved us to the Tailwind CSS framework. This allowed us to get buy in from all stakeholders including leadership.

We are still not completely done with our migration, but we have found it to be quite successful and are excited to finish our transition.

Advantages of Traditional Rails Architecture

We’ve already seen many advantages as a result of our move away from React to a more traditional Rails application.

Simplified development workflow

Our initial hypothesis for this change was that we could drastically reduce software development time for tasks by moving away from React to traditional Rails views. We can confidently say that this has been true. Features that might have taken weeks now take days. We no longer need to worry about ensuring we have experts in both React and Rails.

With a unified codebase, we no longer need to worry about about context switching between Ruby and JavaScript nearly as much. We can leverage the tools we’ve all grown comfortable with such as testing with RSpec rather than Jest.

Improved collaboration and onboarding

Within our React based application, debugging or simply trying to understand how something worked required traversing a maze of code. Do I need to look at the GraphQL layer? Is it the React application? Local state management in JavaScript? We now have a more traditional application where it’s easier to find things. New engineers on the team can get up to speed much faster now which means providing value quickly.

Conclusion and Future Outlook

One of Buoy’s core values is to prefer simplicity over complexity. We’ve found that this change embodies this as we now have a much simpler architecture leading to better outcomes overall. By embracing server-side rendering and leveraging the power of ViewComponents, we were able to create a more performant, maintainable, and developer-friendly application.

As web development continues to evolve, it’s crucial to periodically reassess your technology choices. What works for one project or team may not be the best solution for another. Buoy’s experience serves as a reminder that there’s no one-size-fits-all approach in our industry.

You’re excited about building a new application which allows users to sign up and host their own blog. You decide that each blog will have their own space by providing a subdomain.

Let’s start off with a feature spec.

require "rails_helper"

feature "user views a blog" do
  scenario "homepage" do
     blog = create(
      :blog,
      subdomain: "bobloblaw",
      title: "Bob Loblaw's Law Blog",
      description: "Welcome to my new blog.",
    )

    visit root_path

    expect(page).to have_content blog.title
    expect(page).to have_content blog.description
  end
end

In our app we render the blog homepage using the following:

# config/routes.rb
Rails.application.routes.draw do
  root to: "blogs#show"
end

# app/controllers/blogs_controller.rb
class BlogsController < ApplicationController
  def show
    @blog = current_blog
  end

  private

  def current_blog
    @_current_blog ||= Blog.find_by(subdomain: request.subdomains.first)
  end
end

<!-- app/views/blogs/show.html.erb -->
<h1><%= @blog.title %></h1>
<p><%= @blog.description %></p>

In order to visit the homepage via a subdomain in our test we need to set the app_host property for Capybara. We could try to use myblog.localhost but Rails will think that localhost is the top level domain and therefore won’t see myblog as a subdomain. Instead we’ll use a fake host name example.com. We can set it by adding the following to our spec before calling visit.

Capybara.app_host = "http://myblog.example.com"

If we run the test with the default Capybara driver, rack-test it should be green. rack-test interacts directly with Rack which means it never uses the external URL. If we need to use a JavaScript driver however we will need to use an actual accessible URL. Add the :js metadata to the scenario and you should see a failure occur.

In order to accommodate a driver like Selenium or capybara-webkit we’ll need to do some more work. To start, we will not be able to use our fake host example.com. Instead we need a host name which will point to 127.0.0.1. There is one readily available to us for use through lvh.me. Its DNS records are set up so that lvh.me and all of its subdomains resolve to your local machine at 127.0.0.1.

So update app_host from http://myblog.example.com to http://myblog.lvh.me. We’re still not done yet though.

Next, we need to instruct Capybara to include the port number for the Capybara server in all requests to work correctly. We can do that by adding the following to spec/rails_helper.rb:

Capybara.configure do |config|
  config.always_include_port = true
end

If you’re using the capybara-webkit driver and configuring it to block all unknown URLs as we do in Suspenders then you’ll need to do one more thing. In the configuration for capybara-webkit you’ll need to add the lvh.me host to the URL whitelist. If you’re using a Suspenders based app then open up spec/support/capybara_webkit.rb or whichever file you have configured capybara-webkit in. Update the configuration to look like:

Capybara::Webkit.configure do |config|
  config.block_unknown_urls
  config.allow_url("myblog.lvh.me")
end

This will allow Capybara to access our blog through lvh.me and not block it. With this in place we can run our tests and things should be green again.

Allowing more subdomains

Things are working great with the above but we realize that we are coupled to the myblog subdomain within all of our tests. We will finish things off by making this more flexible.

Let’s start by updating our capybara-webkit configuration to allow all subdomains on lvh.me and not just limiting it to myblog. We can do this by changing myblog to *.

Capybara::Webkit.configure do |config|¬
  config.block_unknown_urls¬
  config.allow_url("*.lvh.me")¬
end

Next, let’s extract a helper method to make testing subdomains easier.

We’ll add the following method to our feature spec:

def visit_blog(blog, path = '/')
  app_host = URI.join("http://#{blog.subdomain}.lvh.me", path).to_s
  using_app_host(app_host) do
    visit path
  end
end

def using_app_host(host)
  original_host = Capybara.app_host
  Capybara.app_host = host
  yield
ensure
  Capybara.app_host = original_host
end

using_app_host allows us to pass a host for Capybara to use and temporarily overrides the app_host rather then permanently setting it. Our use of ensure makes sure that the app_host is always set back to its original value regardless of exceptions being raised while yielding the block. visit_blog allows us to pass an instance of a blog as well as a path to visit. By default, this path is the root of the blog.

So we can update our spec to look as follows:

require "rails_helper"

feature "user views a blog" do
  scenario "homepage", :js do
     blog = create(
      :blog,
      subdomain: "bobloblaw",
      title: "Bob Loblaw's Law Blog",
      description: "Welcome to my new blog.",
    )

    visit_blog blog

    expect(page).to have_content blog.title
    expect(page).to have_content blog.description
  end

  def visit_blog(blog, path = '/')
    app_host = URI.join("http://#{blog.subdomain}.lvh.me", path).to_s
    using_app_host(app_host) do
      visit path
    end
  end

  def using_app_host(host)
    original_host = Capybara.app_host
    Capybara.app_host = host
    yield
  ensure
    Capybara.app_host = original_host
  end
end

The Rails fresh_when method is a powerful tool for conditionally caching resources via HTTP. However there are some pitfalls. For one, fresh_when only supports the default render flow in a controller; if a client’s cache is not fresh, it will just render the related view. We cannot utilize things like render json:.

Fortunately, Rails provides us with more tools to work with HTTP conditional caching. Some of the basics behind HTTP conditional caching are assumed in this post. If you haven’t already, or you just need a refresher take a look at Introduction to Conditional HTTP Caching with Rails.

Let’s work with a simple Rails blog application which renders posts as JSON.

# app/controllers/posts_controller.rb
class PostsController < ApplicationController
  def show
    @post = Post.find(params[:id])
    render json: @post
  end
end

# config/routes
Rails.application.routes.draw do
  resources :posts, only: [:show]
end

What if we wanted to allow the client to conditionally cache this content? Rails provides us with the stale? method which takes a resource and checks to see if the ETag provided by the client via the If-None-Matches header matches the one which represents the resource’s current state. The stale? method can also work with the If-Modified-Since header. It will check if the resource’s updated_at has been modified since the timestamp provided by If-Modified-Since. To utilize this, we just need to wrap our render call with a call to stale?.

class PostsController < ApplicationController
  def show
    @post = Post.find(params[:id])

    if stale?(@post)
      render json: @post
    end
  end
end

If we make a request to the individual post we’ll get something similar to the following response:

curl -i http://localhost:3000/posts/1

HTTP/1.1 200 OK
Etag: "f049a9825a0239db3d01ead65a5ea522"
Last-Modified: Tue, 02 Dec 2014 18:31:42 GMT
Content-Type: application/json; charset=utf-8
Cache-Control: max-age=0, private, must-revalidate
Server: WEBrick/1.3.1 (Ruby/2.1.5/2014-11-13)
Date: Tue, 02 Dec 2014 18:31:48 GMT
Content-Length: 93
Connection: Keep-Alive

{"post":{"title":"Blog post 0","body":"lorem ipsum","created_at":"2014-11-12T15:30:34.025Z"}}%

If we take a look at our Rails server log, we’ll see something similar to the following:

Started GET "/posts/1" for 127.0.0.1 at 2014-12-02 13:38:18 -0500
Processing by PostsController#show as */*
  Parameters: {"id"=>"1"}
  Post Load (0.2ms)  SELECT  "posts".* FROM "posts"  WHERE "posts"."id" = $1
LIMIT 1  [["id", 1]]
Completed 200 OK in 1ms (Views: 0.3ms | ActiveRecord: 0.2ms)

Now if we make a request with the If-None-Match header set to the ETag that the server provided us with earlier:

curl -i -H 'If-None-Match: "f049a9825a0239db3d01ead65a5ea522"' http://localhost:3000/posts/1

We’ll now receive a 304 Not Modified status for our request.

HTTP/1.1 304 Not Modified
Etag: "f049a9825a0239db3d01ead65a5ea522"
Last-Modified: Tue, 02 Dec 2014 18:31:42 GMT
Cache-Control: max-age=0, private, must-revalidate
Server: WEBrick/1.3.1 (Ruby/2.1.5/2014-11-13)
Date: Tue, 02 Dec 2014 18:32:53 GMT
Connection: Keep-Alive

If we take a look at our Rails log we’ll notice that the server skipped over the process of rendering the JSON all together:

Started GET "/posts/1" for 127.0.0.1 at 2014-12-02 13:38:55 -0500
Processing by PostsController#show as */*
  Parameters: {"id"=>"1"}
  Post Load (0.2ms)  SELECT  "posts".* FROM "posts"  WHERE "posts"."id" = $1
LIMIT 1  [["id", 1]]
Completed 304 Not Modified in 1ms (ActiveRecord: 0.2ms)

In this trivial example our gain is not huge. However with more complicated JSON objects this can be a very useful. A common example is a larger JSON response built via ActiveModel::Serializers. Combined with key-based caching in ActiveModel::Serializers this can be a powerful tool. We can cache individual items with russian doll caching, and then cache the entire response via HTTP caching.

Further Reading

• Fast JSON APIs in Rails with Key-Based Caches and ActiveModel::Serializers
• How to Evaluate Your Rails JSON API for Performance Improvements

HTTP provides developers with a powerful set of tools to cache responses. Often times we don’t want a client to blindly cache content that it has been given. We may not be able to rely on setting specific expiration headers either. Instead we need a way for the client to ask the server whether or not a resource has been updated.

HTTP provides us with the ability to do this with conditional caching. A client can make a request to the server and find out of the server has a new version of the resource available.

Rails provides us with tools to take advantage of this. Before we jump into Rails, let’s discuss some of the common ways to check if a client’s cache is fresh or stale.

ETags

ETags, short for entity tags, are a common way to conditionally verify an HTTP cache. An ETag is a digest which represents the contents of a given resource.

When a response is returned by the server it will include an ETag to represent the resource’s state as part of the HTTP response headers. Subsequent HTTP requests which want to know whether or not the resource has changed since the last request can send along the stored ETag via the If-None-Match header.

The server will then compare the current ETag for the resource to the one provided by the client. If the two ETags match, the client’s cache is considered fresh and the server can respond with a “304 Not Modified” status.

If the resource has changed since the last time the client has requested the resource the server will respond with a new ETag and the updated response.

Last-Modified Timestamp

Another header that a server can supply is the Last-Modified header.

As the name implies, this will return a timestamp of when the resource was last modified. The client can then include an If-Modified-Since header with the Last-Modified timestamp value to ask the server if the resource has been modified since the previous request.

Again, if the resource has not been modified since the last request, the server can respond with a “304 Not Modified” status. Otherwise, it will return an updated representation of the resource and a new Last-Modified timestamp for next time.

Caching with fresh_when

Now that we’ve discussed the ETags and Last-Modified HTTP headers, let’s take a look at how we might use them within our Rails application.

ActionController provides us with a powerful method called fresh_when. It will use either an ETag or a Last-Modified timestamp to determine whether or not a resource is fresh or stale.

Imagine a simple Rails blog application with the following posts route / controller:

# app/controllers/posts_controller.rb
class PostsController < ApplicationController
  def show
    @post = Post.find(params[:id])
  end
end

# config/routes.rb
Rails.application.routes.draw do
  resources :posts
end

If we made a curl request to an individual post we might see something like:

curl -i http://localhost:3000/posts/1

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Etag: "4af7e17fc369c6d1af99f8994d8fd387"
Server: WEBrick/1.3.1 (Ruby/2.1.2/2014-05-08)

<!DOCTYPE html>
<html>
  <body>
    <h1>Blog post 1</h1>
    <p>lorem ipsum</p>
  </body>
</html>

Notice that we have not done anything particularly noteworthy, yet if we take a look at the headers returned as a part of the response we’ll see that Rails has sent along an ETag to represent the resource being returned.

If we keep making the same request via curl we’ll see a different ETag value even though the resource has not been modified since our previous request. This goes against the notion of what an ETag would be used for.

We’ll need to modify our controller to instruct it that a request is fresh when a post has not been modified since the last request.

# app/controllers/posts_controller.rb
class PostsController < ApplicationController
  def show
    @post = Post.find(params[:id])

    fresh_when @post
  end
end

Now if we make our previous request over again we’ll see that our ETag no longer changes on repeated requests:

curl -i http://localhost:3000/posts/1

Content-Length: 667
Content-Type: text/html; charset=utf-8
Etag: "534279bfc931d4236713095ffd3efb28"
Last-Modified: Wed, 12 Nov 2014 15:44:46 GMT
Server: WEBrick/1.3.1 (Ruby/2.1.3/2014-09-19)

Upon closer inspection of the updated HTTP headers returned in the response, we’ll notice that the server has also started returning a Last-Modified timestamp for the post resource.

Our work is not complete.

In order to use our cache we need to verify it against the server with the ETag or last modified timestamp with either the If-None-Match or If-Modified-Since headers respectively.

curl -i -H 'If-None-Match: "534279bfc931d4236713095ffd3efb28"' http://localhost:3000/posts/1

HTTP/1.1 304 Not Modified
Etag: "534279bfc931d4236713095ffd3efb28"
Last-Modified: Wed, 12 Nov 2014 15:44:46 GMT
Server: WEBrick/1.3.1 (Ruby/2.1.3/2014-09-19)

Notice we now receive a 304 Not Modified response, instructing our client that it can use its cached version of the content. Browsers will automatically send a long a stored ETag and Last-Modified timestamp with conditional caching headers for us so we do not actually have to do anything to use this in the browser.

Let’s take a look at the similar request with the If-Modified-Since header:

curl -i -H 'If-Modified-Since: Wed, 12 Nov 2014 15:44:46 GMT' http://localhost:3000/posts/1

HTTP/1.1 304 Not Modified
Etag: "534279bfc931d4236713095ffd3efb28"
Last-Modified: Wed, 12 Nov 2014 15:44:46 GMT
Server: WEBrick/1.3.1 (Ruby/2.1.3/2014-09-19)

You’ll notice that we get the same results, the post has not been modified since the last time and we receive a 304 Not Modified response.

Conclusion

What have we gained through all of this? We are still making requests to our server to see if a resource has been modified before rendering.

To really understand what we’ve achieved we can take a look at our Rails log before we had caching:

Started GET "/posts/1" for 127.0.0.1 at 2014-11-12 11:33:57 -0500
Processing by PostsController#show as */*
  Parameters: {"id"=>"1"}
  Post Load (0.3ms)  SELECT  "posts".* FROM "posts"  WHERE "posts"."id" = $1
LIMIT 1  [["id", 1]]
  Rendered posts/show.html.erb within layouts/application (0.1ms)
  Rendered application/_flashes.html.erb (0.0ms)
  Rendered application/_analytics.html.erb (0.1ms)
  Rendered application/_javascript.html.erb (16.1ms)
Completed 200 OK in 35ms (Views: 33.4ms | ActiveRecord: 0.3ms)

We can see that our request takes about 33ms and has to render our posts/show template within the layout along with some other partials. We can also see that most of our time is spent within that rendering process. ActiveRecord took less than a millisecond to run.

Next, let’s take a look at our log with conditional caching in place, and put it to use by sending over a If-None-Match header:

Started GET "/posts/1" for 127.0.0.1 at 2014-11-12 11:39:52 -0500
Processing by PostsController#show as */*
  Parameters: {"id"=>"1"}
  Post Load (0.3ms)  SELECT  "posts".* FROM "posts"  WHERE "posts"."id" = $1
LIMIT 1  [["id", 1]]
Completed 304 Not Modified in 2ms (ActiveRecord: 0.3ms)

Notice we’ve cut off our entire rendering process from the request. Since the client’s cached response is fresh there is no reason for Rails to go through the rendering process. It can load in the post via ActiveRecord and verify if it has changed since the previous request.

Our requests went from taking about 33ms to complete to 2ms. That’s about a 94% improvement in performance. Not only is Rails skipping the rendering process, but our responses are now much lighter as they have no body to return.

This may not be much in our trivial example but for applications which have a lot of complicated logic behind rendering this can save lots of time.

Furthermore, these requests can be put in front of a public cache such as Rack::Cache to share a common cache for resources as opposed to a private cache which is only utilized by the user’s browser.

Getting more

Our simple fresh_when solution is not without its limitations.

It cannot handle user specific content. If we wanted to display anything different on a per-user basis (even if that’s the name in the header), we won’t be able to cache the content.

Another issue is that the cache is not being shared among users. Our performance gain is only realized when a single user looks at the same post over and over again.

Lastly, we’re limited to a simple render call in our controller. What if we wanted something more customized like render json: or render xml:? We’ll build on top of what we’ve learned next time to overcome these limitations and improve our caching even further.

Organizing our API

Building our API we set out to achieve a few goals:

• Make the API flexibile and decoupled from the front-end implementation
• Leverage HTTP caching whereever possible
• Ensure it could handle high scale

Making the API decoupled from it’s front-end implmentation ensured that any design or data usage changes made would not require a change in 2 areas of our code base, the JavaScript application and the Rails application / API.

Leveraging HTTP caching gave us 2 gains. The first is we wanted to leverage an individual user’s caching in their browser, reducing the amount of data we needed to send back to the user. The 2nd gain, which in my opinion was the bigger gain was the ability to add a caching layer in front of the entire response body through Rack::Cache.

ActiveModel::Serializers

(ActiveModel::Serializers)[https://github.com/rails-api/active_model_serializers] is a great library for encapsulating object serialization for JSON APIs in Rails. It provides a great Object Oriented approach to serialization. If you haven’t seen it before I highly recommend checking it out. Furthermore, it implements caching through Rails.cache to provide the ability to cache serialization of objects using (key based expiration)[http://37signals.com/svn/posts/3113-how-key-based-cache-expiration-works]. This provided us with some very nice, quick and easy caching of our serialized data. Thoughtbot has a great (article on ActiveModel::Serailziers and caching)[http://robots.thoughtbot.com/post/50091183897/fast-json-apis-in-rails-with-key-based-caches-and] so I’m not going to get into the details of it.

With this caching we were able to get a great method of caching our serialization. However we wanted more. Our models have a lot of associations which can be re-used through Russian doll caching. We implemented (this pull request)[https://github.com/rails-api/active_model_serializers/pull/307] in or serializers in order to benefit from side-effect free russian doll caching. With this in mind we could reuse caches just as easily across requests when possbile.

Rack::Cache

Leveraging Rack::Cache in front of the API was one of the biggest wins for us. Rails has Rack::Cache active in production mode by default. However if you aren’t using HTTP caching properly you won’t see the benfits. There are many articles on the details of the various HTTP caching mechanisms that can be used. From cache-control headers, to etags and last-modified time stamps. Before we jump into the details let me explain why Rack::Cache was so useful.

When leveraging russian doll caching for our serialization we were able to get very fast serialization for our objects. However this typically lead to lots of memcached requests for fetcihng the individual pieces of the cache. This was not optimal. Our architecture benefited from the fact that one parent object could be used to determine the freshess of a cache. Think of the classic todo list example. Where individual todos in a list are cached as part of the entire todo list. If any individual todo-item in the list expires, then the list itself is expired. So, if we were using ActiveModel::Serialziers with caching, it would hit a cache for each item in the todo list.

Outline

• Weeks JSON public to all users
• Picks public because it’s route is built from user ID.
• ActiveModel::Serializers
• Rack::Cache

Instead, I set out to build a back end service which would consume our third party API and we could interact with on the front end. However, I did not want to spend a great deal of time on building this midpoint between the services.

Ruby and Sinatra to the Rescue

Armed with the task at hand I set out to build the simplest approach possible to begin consuming our third party API as quickly as possible. I started out with Rails and a look into ActiveResource but quickly found that there was to much overhead and complexity for what I needed. With this in mind I decided to move onto a simple Sinatra application which would aim to mimic the third party services in API methods and forward requests for us.

For our test case, let’s look at the Twitter API. Note, Twitter does in fact support a JSONP service so this isn’t really necessary. We are simply using it as a test case for the post.

Fetching a user’s timeline

require 'sintra'
require 'net/http'

get "/1/statuses/user_timeline" do
    uri = URI::HTTP.build(
        :host => api.twitter.com,
        :path => request.path_info,
        :query => request.query_string
    )

    content_type 'application/json', :charset => 'utf-8'

    Net::HTTP.get(uri)
end

In order to fetch a user’s timeline we will need to make a request to the following API path: /1/statuses/user_timeline. Along with this path the API documentation by twitter specifies that we can send various parameters along in the query string. What we have done here is we created a path which matches twitter’s and from there we access the request information provided by Sinatra. We build a URI using the API URL, request.path, and request.query. This will allow us to quickly forward the request to Twitter’s API through a NET::HTTP.get request.

Now that we’ve done that we can either mount our Sinatra app somewhere in the same domain or proxy requests to it on another domain. In my case, I’ve set up a simple proxy through Apache at /services.

<IfModule mod_proxy.c>
    ProxyRequests Off
    ProxyVia On

    <Proxy *>
        AddDefaultCharset off
        Order deny, allow
        Allow from all
    </Proxy>

    ProxyPass /services http://127.0.0.1:9393
    ProxyPassReverse /services http://127.0.0.1:9393
</IfModule>

So assuming I have my Sinatra application up and running on port 9393. I now have a proxy which will forward all requests to /services in my web application to the Sinatra application. This will then forward all requests to the Twitter API and return the results. Visit the mod_proxy documentation for more information about HTTP proxies with Apache.

Drying up our application

In our case right now we have a single method that we are forwarding, but what if we wanted to support more API methods provided by twitter. Well we could go ahead and write out each method and its block, or we could take advantage of the flexibility we have available to us.

require 'sinatra'
require 'net/http'

def api_request(path, query_string)
    uri = URI::HTTP.build(
        :host => api.twitter.com,
        :path => path,
        :query => query_string
    )

    Net::HTTP.get uri
end

request_handler = -> do
    content_type = 'application/json', :charset => 'utf-8'
    api_request request.path_info, request.query_string
end

%w{
    /1/statues/user_timeline
    /1/statuses/mentions
    /1/statuses/retweeted_by_me
}.each { |route| get route, &request_handler }

This sample is going to be using the paperclip gem by thoughtbot to handle our upload.

The Controller

So we’ve gotten our file uploaded successfully, authentication is passing thanks to our previous work but what now? One of the first issues that you might run into is the content type for the file you uploaded. Our uploadify upload will actually have the content_type set to ‘application/octet-stream’ which is not totally accurate representation of what we’re uploading.

As stated earlier, this example is using paperclip, which will need the true content_type to be set to accurately continue uploading the file. To resolve the ‘application/octet-stream’ issue we can use the mime-type gem and set the content_type of the file afterwards in the controller before trying to save the upload. Add the following to your gem file and run a bundle install:

gem 'mime-types', :require => 'mime/types'

With this in place we can force our controller to set the content type of the upload to the proper value.

We can do this with the following code:

params[:Filedata].content_type = MIME::Types.type_for(params[:Filedata].original_filename).to_s

Below is a full code sample of our Paperclip based model, and the full create controller method for handling our upload. I hope you’ve found this post useful and please feel free to comment below with any questions, as I’ll try to get to them as soon as possible.

GalleryImage Model

class GalleryImage < ActiveRecord::Base

	belongs_to :gallery
	delegate :venue, :to => :gallery

	# Storing photos in /galleries/:venue_name/:gallery_id/...
	has_attached_file :photo,
		:styles => { :thumb => "70x70", :iphone_thumb => "30x30#", :iphone_full => "320x480" },
		:url => '/galleries/:venue/:gallery/:id/:attachment/:style/:basename.:extension',
		:path => ':rails_root/public/galleries/:venue/:gallery/:id/:attachment/:style/:basename.:extension'
end

GalleryImagesController

def create

	@gallery = Gallery.find(params[:gallery_id])
	@gallery_image = GalleryImage.new
	@gallery_image.gallery = @gallery

	# Associate the correct MIME type for the file since Flash will change it
	params[:Filedata].content_type = MIME::Types.type_for(params[:Filedata].original_filename).to_s

	@gallery_image.photo = params[:Filedata]
    if @gallery_image.save
		render :json => { 'status' => 'success'  }
	else
		render :json => { 'status' => 'error' }
	end
end

Well that is until you’re trying to work with a Rails application. There are lots of resources around that go into the details of how to get this to work but the real issue that I had was that they were mostly for Rails 2.3.8 and my application is now using Rails 3 and the methods described in all of these articles don’t completely apply to Rails 3.

Why is this extra work needed?

Before moving forward on how to get everything working let’s take a look at why it’s not working in the first place to better understand what we’re dealing with and how we’re fixing the problem.

Requests made via POST, PUT, DELETE all require a valid authentication token and session information in order to complete the request successfully in order to protect against Cross-site request forgery. When building out forms using Rails form helpers, a hidden input is created which contains the authenticity token to prove the authenticity of the request along with your session cookie data.

This poses 2 problems for us using Flash to upload files.

First, Uploadify is not going to automatically send the authenticity token with the POST request. Second, Flash based requests do not send our session information along with the request. The first situation is pretty easy to fix while the session information requires a little more work on our part.

Sending the Authentication_Token

Let’s start by sending the authenticity token along with the request. In previous versions of Rails we would have had to found a way to get the authenticity token to send but as part of Rails 3 usage of Unobtrusive JavaScript, it now includes a new helper method called csrf_meta_tag. This helper method will provide us with 2 meta tags, csrf-param and csrf-token

<meta name="csrf-param" content="authenticity_token"/>
<meta name="csrf-token" content="s2yuw7u24N9fni1m+Wynr595kTphEeMrNSWPAnMroLM="/>

Once we have the CSRF meta tags in place, we can move forward and add the authenticity to the parameters which are sent with Uploadify’s request. The JavaScript snippet below is an example of pulling the CSRF token information and passing it along with our Uploadify requests using the scriptData configuration parameter.

<script type="text/javascript">
$(function () {
  // Create an empty object to store our custom script data
  var uploadify_script_data = {};

  // Fetch the CSRF meta tag data
  var csrf_token = $('meta[name=csrf-token]').attr('content');
  var csrf_param = $('meta[name=csrf-param]').attr('content');

  // Now associate the data in the config, encoding the data safely
  uploadify_script_data[csrf_token] = encodeURI(csrf_param);

   // Configure Uploadify
  $('#photo-upload').uploadify({
    'uploader' : '/assets/uploadify.swf',
    'script' : '/photos/',
    'scriptData' : uploadify_script_data
  });
});
</script>

Uploadify allows you to pass extra data along with it’s request using the scriptData parameter which accepts an object of properties to send with the request. In our case we are fetching the CSRF and creating a new property in the scriptData object with the name of the CSRF token and setting it’s value to the CSRF param. Using this, we can pass along the authenticity token with the request. It’s important to note that we are encoding the authentication token value using encodeURI to escape any special characters so the data gets sent along to the server correctly.

I actually ran into an issue where even using encodeURI once was not enough and I needed to double encode because + signs were being converted into spaces. So if you are continuing to run into InvalidAuthenticityToken error, check your log to see that the authenticity token is being correctly sent along. While trying to debug the problem a quick look into the log showed that I was receiving

authenticity_token=>"3WB Cj0h7y4St5ZyvlYU xIEVT7yIIr6IRAhOOLCb5w=

The spaces in the above authenticity token should have been + signs instead. In order to resolve this issue I ended up having to double encode the authenticity token before sending it along like so:

uploadify_script_data[csrf_token] = encodeURI(encodeURI(csrf_param));

Now that we have the authenticity token being sent by Uploadify, let’s move forward and get our session information passed along as well.

Passing the Session Cookie

One of the first steps to passing the session cookie along with our Uploadify requests is to add it to the scriptData like we did with the authentication_token. Unfortunately there is no quick way to handle this through JavaScript alone, we need to include it using some ERB to apply it.

In earlier versions of Rails the session cookie key could be accessed via: ActionController::Base.session_options[:key]

As of Rails 3 though we can access the session cookie key using: Rails.application.config.session_options[:key]

Below is a simple example of how to send the session cookie information in the scriptData.

<script type="text/javascript">
<%- session_key = Rails.application.config.session_options[:key] -%>
$(function () {

  var uploadify_script_data = {};

  // Fetch the CSRF meta tag data
  var csrf_token = $('meta[name=csrf-token]').attr('content');
  var csrf_param = $('meta[name=csrf-param]').attr('content');

  // Now associate the data in the config, encoding the data safely
  uploadify_script_data[csrf_token] = encodeURI(csrf_param)

  // Associate the session information
  uploadify_script_data['<%= session_key %>'] = '<%= cookies[session_key] %>';

  $('#upload-photo').uploadify({
    script : '/photos/',
    scriptData : uploadify_script_data
  });
});
</script>

Now that we have the session cookie data being passed with the request we’ll need to move forward and have that information set with the headers of the Flash request, enter Middleware.

Rack Middleware

In order to get the session information to be associated with the request correctly we’ll need to create some custom middleware which will intercept the requests from Flash and inject the cookie information into the header.

Some middleware has been around for accomplishing this but most are not compatible with Rails 3. I’ve posted a Gist on Github which has a working middleware for Rails 3 which I found on metautonomo.us which we can use to accomplish our task.

Create a file in app/middleware/flash_session_cookie_middleware.rb creating the middleware directory if it doesn’t already exist and add the following code in it:

require 'rack/utils'
 
class FlashSessionCookieMiddleware
  def initialize(app, session_key = '_session_id')
    @app = app
    @session_key = session_key
  end
 
  def call(env)
    if env['HTTP_USER_AGENT'] =~ /^(Adobe|Shockwave) Flash/
      req = Rack::Request.new(env)
      env['HTTP_COOKIE'] = [ @session_key,
                             req.params[@session_key] ].join('=').freeze unless req.params[@session_key].nil?
      env['HTTP_ACCEPT'] = "#{req.params['_http_accept']}".freeze unless req.params['_http_accept'].nil?
    end
 
    @app.call(env)
  end
end

Once you’ve created that file we’ll need to add the middleware directory to our autoload’s path if it isn’t already. You can do this by modifying you’re config/application.rb file and add the following in the autoload section:

# Custom directories with classes and modules you want to be autoloadable.
# config.autoload_paths += %W(#{config.root}/
config.autoload_paths += %W(#{config.root}/app/middleware/)

Once that’s done we have one more step to do, inserting the middleware so that it will go to work when we need it.

Place the following code in config/initializers/session_store.rb

Rails.application.config.middleware.insert_before(
  ActionDispatch::Session::CookieStore,
  FlashSessionCookieMiddleware,
  Rails.application.config.session_options[:key]
)

Update

If you are using ActiveRecord based session storage instead of cookie based session storage you will need the following intializer instead:

SampleApp::Application.config.session_store :active_record_store, :key => '_uploader_session'

Rails.application.config.middleware.insert_before(
  Rails.application.config.session_store,
  FlashSessionCookieMiddleware,
  Rails.application.config.session_options[:key]
)

Thanks to reader @fromthought2web for sharing his findings!

With all this in place you should now be ready to successfully upload files via Flash with your Rails project.

Good luck!

Updates

2012-04-03

Included sample middleware when using ActiveRecord for session store, thanks to @fromthought2web for sharing his finds.

<dt>2010-08-26</dt>
<dd>Resolved issue in code sample where session_key_name was being reference instead of session_key. Original sample updated</dd>
<dd>`uploadify_script_data['<%= session_key %>'] = '<%= cookies[session_key] %>';`</dd>