Because OpenAI’s rate limits are more complicated than other APIs, we made sure to proactively avoid rate limits by keeping track of how many tokens we’re using. However, this approach is incomplete in that it does nothing to limit an individual user’s usage.

A chat bot feature is unique in that it can quickly exhaust your organization’s rate limits across multiple dimensions: requests per minute (RPM) and tokens per minute (TPM). This is because…

• Chatting enables the user to send messages in rapid succession, which increases RPM.
• Messages can be long, contain attachments, and as the conversation grows, so does the context window, which increases TPM.

Once a user hits the organization’s limit, everything that uses OpenAI is affected, and will no longer work. In the case of my project, not only does that mean the chat bot feature would be down, but also other tools we use that leverage OpenAI.

In short, one user can trigger a denial of service simply by using a feature as it was intended to be used.

Fortunately, there are a few solutions to this problem.

Our base

For the sake of this demonstration, we’ll use RubyLLM, but the concepts we’ll learn apply to any implementation and platform.

chat = RubyLLM.chat

response = chat.ask "What's a good rate limit strategy for a chat bot?"

puts response.content

Rate limit messages

The first thing we can do is limit the number of messages a user can send in a given time frame. This is known as “fixed-window rate limiting”. Although Rails ships with a rate limit mechanism, that won’t help us when we need to rate limit token usage. Instead, we can rely on a cache store like Redis, since its built-in INCR and EXPIRE APIs lend themselves well to a rate limiting mechanism.

# app/models/usage.rb
class Usage
  MAX_RPM = ENV.fetch("USAGE_MAX_RPM", 10).to_i

  def initialize(user, cache_store = ActiveSupport::Cache::RedisCacheStore.new)
    @user = user
    @cache_store = cache_store
  end

  def track!
    track_rpm!
  end

  def exceeded?
    rpm_exceeded?
  end

  private

  attr_reader :user, :cache_store

  def rpm_key
    "usage:user:#{user.id}:rpm"
  end

  def track_rpm!
    cache_store.increment(rpm_key, 1, expires_in: 1.minute)
  end

  def rpm_exceeded?
    cache_store.read(rpm_key, raw: true).to_i >= MAX_RPM
  end
end

# app/models/user.rb
class User < ApplicationRecord
  def usage
    Usage.new(self)
  end
end

We can create a simple object that tracks user requests per minute simply by incrementing the value by one for each request made, making sure to expire the key after one minute.

Here’s how that might look when used with our chat bot:

chat = RubyLLM.chat
user = User.last!
usage = user.usage

unless usage.exceeded?
  response = chat.ask "What's a good rate limit strategy for a chat bot?"

  usage.track!

  puts response.content
else
  # Alert user that they've exceeded their usage.
end

Before making a request, we check to see if the user has exhausted their individual rate limit. If not, we make the request and track the usage.

Limit token usage

Limiting requests is just half of the problem, since token usage is also a metric that requires rate limiting.

We can’t just validate the length of the message, since token usage doesn’t map 1:1 with character length. Additionally, token usage is also based on output tokens.

Fortunately, OpenAI returns usage data in the response, which RubyLLM exposes in a Message instance.

 class Usage
   MAX_RPM = ENV.fetch("USAGE_MAX_RPM", 10).to_i
+  MAX_TPM = ENV.fetch("USAGE_MAX_TPM", 10_000).to_i

   def initialize(user, cache_store = ActiveSupport::Cache::RedisCacheStore.new)
     @user = user
     @cache_store = cache_store
   end

-  def track!
-    track_rpm!
+  def track!(total_tokens)
+    [ track_rpm!, track_tpm!(total_tokens) ]
   end

   def exceeded?
-    rpm_exceeded?
+    rpm_exceeded? || tpm_exceeded?
   end

   private
@@ -29,4 +30,16 @@ class Usage
   def rpm_exceeded?
     cache_store.read(rpm_key, raw: true).to_i >= MAX_RPM
   end
+
+  def tpm_key
+    "usage:user:#{user.id}:tpm"
+  end
+
+  def track_tpm!(total_tokens)
+    cache_store.increment(tpm_key, total_tokens, expires_in: 1.minute)
+  end
+
+  def tpm_exceeded?
+    cache_store.read(tpm_key, raw: true).to_i >= MAX_TPM
+  end
 end

We can use the same pattern we used for tracking requests to track tokens. The only difference is that we need to supply that information.

Here’s how that would look in our chat bot:

 unless usage.exceeded?
   response = chat.ask "What's a good rate limit strategy for a chat bot?"

-  usage.track!
+  tokens = response.tokens
+  total_tokens = tokens.input + tokens.output + tokens.thinking
+
+  usage.track!(total_tokens)

   puts response.content
 else

After making a request, we extract the token usage from the response, and pass it to our Usage instance to be used in the next request.

Calculating per-user rate limits

Since the rate limits set by OpenAI and other providers are at the organization level, how might we evenly distribute those values on a per-user basis?

A simple approach suitable for most early-stage products would be to divide the organization limit by the expected concurrent users. In order to ensure we account for unexpected spikes in traffic, we can add in a buffer.

Per-user limit = (Organization limit × buffer) / Expected concurrent users

Below is what that looks like using the values in this demonstration.

Additional considerations

The core problem is that a chat bot is inherently expensive. If we stick to these numbers, we’re constrained to 10 concurrent users, which feels pretty limited, even for an early-stage product.

One solution is to queue the requests rather than reject them, which might look something like this:

class ProcessPromptJob < ApplicationJob
  queue_as :default

  MAX_ATTEMPTS = 2

  rescue_from(Usage::RateLimitExhaustedError) do
    if executions < MAX_ATTEMPTS
      retry_job wait: 15.seconds
    else
      # Broadcast failure message to user
    end
  end

  def perform(user, prompt)
    raise Usage::RateLimitExhaustedError if user.usage.exceeded?

    chat = RubyLLM.chat

    response = chat.ask(prompt)

    tokens = response.tokens
    total_tokens = tokens.input + tokens.output + tokens.thinking

    user.usage.track!(total_tokens)

    # Broadcast LLM response to user
  end
end

 class Usage
+  class RateLimitExhaustedError < StandardError; end
+
   MAX_RPM = ENV.fetch("USAGE_MAX_RPM", 10).to_i
   MAX_TPM = ENV.fetch("USAGE_MAX_TPM", 10_000).to_i

The flow would be something like this:

User sends message
  └─▶ Show loading state
        └─▶ Enqueue background job
              └─▶ Rate limit exceeded?
                    ├─ No  ──▶ Process request ──▶ Broadcast response
                    └─ Yes ──▶ Wait 15 seconds
                                 └─▶ Rate limit exceeded?
                                       ├─ No  ──▶ Process request ──▶ Broadcast response
                                       └─ Yes ──▶ Broadcast failure

Wrapping up

Limiting a user’s application usage is not a new problem, but it’s more relevant today with the rise in chat bot features.

The examples above highlight simple solutions, but they’re just a start — a more nuanced approach will likely be needed.

For example, if a user hits their limit, do you attempt to upsell them? Do you flat out block them? Or, should you fall back to a cheaper model? Maybe a combination of these suggestions?

Regardless, these decisions should involve stakeholders such as designers and the product team.

I naively thought this could be achieved in a matter of hours, but soon realized there was a lot of nuance. This is the article I wish existed when I started working on this feature.

Understanding the requirements

A join code needs to be short, easy to type, as well as easy to read or even say aloud (in cases where the user cannot see the code). Because of this, APIs like generate_token_for weren’t going to work, because they’re not meant to be typed, or viewed. They’re meant to be clicked.

Because of this, most join codes are 6 characters long, consisting of numbers, letters, or a combination of the two.

Naive implementation

Knowing this, I figured I would just generate a random 6 character digit and call it a day.

join_code = SecureRandom.random_number(1000000).to_s.rjust(6, "0")

# => "891907"

# Create game
Game.create!(join_code:)

# Find game
Game.find_by(join_code: params[:join_code])

This technique will yield 1,000,000 (10 digits with 6 possible positions = 10^6) possible combinations, which seems like it would be plenty.

But then I got to thinking:

• What happens if the feature is a massive success, and we eventually exhaust all of the possible 1,000,000 combinations?
• How likely are collisions if we can’t recycle join codes?

Understanding collision probability

In order to answer these questions, I found it easier to break the problem down into something simpler.

Let’s assume join codes are 1 character in length, and can only be a digit (0-9).

This means there’s always a 10% chance of randomly generating any number. But, once a value has been used, the probability of colliding increases linearly.

This means that once we have 500,000 rows in the database, there will be a 50% chance of a collision when generating the next join code. As each new row is added, the collision rate will increase.

This is a problem if we can’t recycle join codes, because we’ll need to handle these collisions on each attempt, which could result in an infinite loop.

Alphanumeric implementation

After realizing that 1,000,000 combinations may not be enough, I figured I’d go with an alphanumeric approach, since that would result in more combinations, and more time until a 50% collision rate.

join_code = SecureRandom.alphanumeric(6).upcase

# => "TOAJR7"

# Create game
Game.create!(join_code:)

# Find game
Game.find_by(join_code: params[:join_code])

Now there are 2,176,782,336 (10 digits + 26 letters with 6 possible positions = 36^6) possible combinations.

UX considerations with an alphanumeric join code

I thought the alphanumeric approach would be easy, until I realized there are some UX “gotchas”.

The first “gotcha” is that some numbers look like capitalized letters.

• 0 ↔ O
• 1 ↔ I
• 2 ↔ Z
• 5 ↔ S
• 8 ↔ B
• U ↔ V

The second “gotcha” is there’s a chance the randomly generated join code will contain a profanity or two.

Tools like Sqids Ruby account for both of these concerns.

The third “gotcha” is normalization. It’s a better UX not to have to capitalize individual characters when entering a join code. But this means you’ll want to normalize the value when making the query.

class Game < ActiveRecord::Base
  normalizes :join_code, with: -> join_code { join_code.strip.upcase }
end

join_code = Game.normalize_value_for(join_code: params[:join_code])
Game.find_by(join_code:)

You’ll also want to make the value appears capitalized.

<style>
    #join_code {
        text-transform: uppercase;
    }
</style>

<input type="text" id="join_code" name="join_code" />

Scoping to time, not space

We can avoid the collision and UX concerns by limiting when a join code can be used.

Instead of indexing on the join code alone, we can scope it to another column. In most cases, using a join code should be limited to a point of time, since games are temporary.

The simplest way to do this would be with an active boolean column. Here’s what that schema might look like:

class CreateGames < ActiveRecord::Migration[8.0]
  def change
    create_table :games do |t|
      t.string :join_code
      t.boolean :active, default: false, null: false

      t.timestamps
    end

    add_index :games, :join_code, unique: true, where: "active = true AND join_code IS NOT NULL"

    add_check_constraint :games, "join_code IS NOT NULL OR active = false",
      name: "active_games_require_join_code"
  end
end

This would allow join codes to be recycled, while ensuring they’re unique across all “active” games.

# Create game
Game.create!

# Find an active game
Game.active.find_by(join_code: params[:join_code])

This means the probability of a collision would eclipse 50% when there are 500,000 active games, which is far less of a concern. We can actually use our naive number-based implementation from the beginning now that we understand how to scope the join code.

Here’s a complete example:

class Game < ApplicationRecord
  JOIN_CODE_REGEX = /\A\d{6}\z/

  validates :join_code, presence: true, if: :active?
  validates :join_code, uniqueness:  {
    scope: :active,
    conditions: -> { where(active: true) }
  }
  validates :join_code, format: {
    with: JOIN_CODE_REGEX
  }, if: :active?

  before_validation :set_join_code, unless: :join_code?

  scope :active, -> { where(active: true) }

  private

  def set_join_code
    max_attempts = ENV.fetch("JOIN_CODE_GENERATION_MAX_ATTEMPTS")

    max_attempts.times do
      self.join_code = generate_join_code

      next if @existing_game = Game.active.exists?(join_code:)
    end

    raise "Failed to generate unique join_code after #{max_attempts} attempts" if @existing_game
  end

  def generate_join_code
    SecureRandom.random_number(1000000).to_s.rjust(6, "0")
  end
end

Wrapping up

Let’s circle back to the original requirements:

A join code needs to be short, easy to type, as well as easy to read or even say aloud (in cases where the user cannot see the code).

By sticking with digits only, our complete example accounts for all of these requirements. It also provides a better UX because users won’t need to toggle between their number keys and character keys, or concern themselves with capitalization. It also alleviates us from needing to account for profanities or characters that look alike, as well as normalization.

It turns out, our naive implementation from the beginning was mostly right, but we needed to take the scenic route to come to that conclusion.

What happens when you’re dealing with free text? Filtering the entire string may not be an option if an external API needs to process the value. Think chatbots or LLMs.

You could use a regex to filter sensitive information (such as credit card numbers or emails), but that won’t capture everything, since not all sensitive information can be captured with a regex.

Fortunately, named-entity recognition (NER) can be used to identify and classify real-world objects, such as a person, or location. Tools like MITIE Ruby make interfacing with NER models trivial.

By using a combination of regex patterns and NER entities, Top Secret effectively filters sensitive information from free text—here are some real-world examples.

If you want to see Top Secret in action, you might enjoy this live stream. Otherwise, see the examples below.

Working with LLMs

It’s not uncommon to send user data to chatbots. Since the data might be free-form, we should be diligent about filtering it using the approach mentioned above.

However, it’s likely we’ll want to “restore” the filtered values when returning a response from the chatbot. Top Secret returns a mapping that would allow for this.

You’d likely want to provide instructions in the request.

instructions = <<~TEXT
  I'm going to send filtered information to you in the form of free text.
  If you need to refer to the filtered information in a response, just reference it by the filter.
TEXT

The exchange might look something like this.

1. Caller sends filtered text

    result = TopSecret::Text.filter("Ralph lives in Boston.")
   
    # Send this to the API
    result.output # => [PERSON_1] lives in [LOCATION_1].
   
    # Save the mapping to "restore" response
    mapping = result.mapping # => { PERSON_1: "Ralph", LOCATION_1: "Boston" }
   

2. API responds with filter

    "Hi [PERSON_1]! How is the weather in [LOCATION_1] today?"
   

3. Caller can “restore” from the mapping

    response = "Hi [PERSON_1]! How is the weather in [LOCATION_1] today?"
   
    # Restore the response from the mapping
    result = TopSecret::FilteredText.restore(response, mapping: mapping)
   
    result.output
    # => Hi Ralph! How is the weather in Boston today?
   

Filtering conversation history

When working with conversation state you should filter every message before including it in the request. This ensures no sensitive data slips through from previous messages. Here’s what that might look like.

require "openai"
require "top_secret"

openai = OpenAI::Client.new(
  api_key: Rails.application.credentials.openai.api_key!
)

original_messages = [
  "Ralph lives in Boston.",
  "You can reach them at ralph@thoughtbot.com or 877-976-2687"
]

# Filter all messages
result = TopSecret::Text.filter_all(original_messages)
filtered_messages = result.items.map(&:output)

user_messages = filtered_messages.map { {role: "user", content: it} }

# Instruct LLM how to handle filtered messages
instructions = <<~TEXT
  I'm going to send filtered information to you in the form of free text.
  If you need to refer to the filtered information in a response, just reference it by the filter.
TEXT

messages = [
  {role: "system", content: instructions},
  *user_messages
]

chat_completion = openai.chat.completions.create(messages:, model: :"gpt-5")
response = chat_completion.choices.last.message.content

# Restore the response from the mapping
mapping = result.mapping
restored_response = TopSecret::FilteredText.restore(response, mapping:).output

puts(restored_response)

Prevent storing sensitive information with validations

Top Secret can also be used as a validation tool to prevent storing sensitive information in your database.

class Message < ApplicationRecord
  validate :content_cannot_contain_sensitive_information

  private

  def content_cannot_contain_sensitive_information
    result = TopSecret::Text.filter(content)
    return if result.mapping.empty?

    errors.add(:content, "contains the following sensitive information #{result.mapping.values.to_sentence}")
  end
end

If the validation is too strict, you can override or disable any of the filters as needed.

--- a/app/models/message.rb
+++ b/app/models/message.rb
@@ -4,7 +4,7 @@ class Message < ApplicationRecord
   private

   def content_cannot_contain_sensitive_information
-    result = TopSecret::Text.filter(content)
+    result = TopSecret::Text.filter(content, people_filter: nil, location_filter: nil)
     return if result.mapping.empty?

     errors.add(:content, "contains the following sensitive information #{result.mapping.values.to_sentence}")

Wrapping up

It’s our responsibility to protect user data. This is more important than ever given the rise in popularity of chatbots and LLMs. Tools like Top Secret aim to reduce this burden.

# config/initializers/filter_parameter_logging.rb

Rails.application.config.filter_parameters += [
  :passw, :email, :secret, :token, :_key, :crypt, :salt, :certificate, :otp, :ssn, :cvv, :cvc
]

If a request is made that contains a parameter that partially matches any of these values, it will be filtered.

Parameters: {"authenticity_token"=>"[FILTERED]", "email_address"=>"[FILTERED]", "password"=>"[FILTERED]", "commit"=>"Sign in"}

It also filters the associated attributes.

<User:0x000000011f735030
 id: 980190962,
 email_address: "[FILTERED]",
 password_digest: "[FILTERED]",
 created_at: "2025-04-23 13:59:46.324377000 +0000",
 updated_at: "2025-04-23 13:59:46.324377000 +0000">

Don’t just filter sensitive information, encrypt it

There’s a case to be made that you should rarely need to update the default list. This is because if you plan on storing anything worth filtering, it should be encrypted.

class User < ApplicationRecord
  encrypts :phone_number
end

Fortunately, Rails has accounted for this by automatically filtering encrypted attributes.

Note how the phone_number is filtered when logging internal requests.

Parameters: {"authenticity_token"=>"[FILTERED]", "user"=>{"email_address"=>"[FILTERED]", "phone_number"=>"[FILTERED]", "password_digest"=>"[FILTERED]"}, "commit"=>"Create User"}

It’s also filtered when inspecting an object.

<User:0x0000000121282608
 id: 980190962,
 email_address: "[FILTERED]",
 password_digest: "[FILTERED]",
 created_at: "2025-04-23 14:10:49.414784000 +0000",
 updated_at: "2025-04-23 14:10:49.414784000 +0000",
 phone_number: "[FILTERED]">

Filter sensitive information from external network requests

Just because Rails provides a good foundation doesn’t mean it accounts for everything.

For example, if you’re using Faraday, it’s your responsibility to filter sensitive information when logging requests. This does not happen by default.

conn = Faraday.new(url: "http://httpbingo.org") do |builder|
  builder.request :json
  builder.response :json
  builder.response :raise_error
  builder.response :logger, nil, {
    headers: true,
    bodies: true,
    errors: true
  }
end

conn.get("get", api_key: "secret")
conn.post("anything", user: User.last!.as_json)

We’re exposing the api_key when logging both the request and the response when making a GET request.

INFO -- : request: GET http://httpbingo.org/get?api_key=secret
INFO -- : response: {
  "args": {
    "api_key": [
      "secret"
    ]
  },
  "url": "http://httpbingo.org/get?api_key=secret"
}

We’re also exposing all the sensitive attributes on user, even though those are filtered internally.

INFO -- : request: POST http://httpbingo.org/anything
INFO -- : response: {
  "data": "{\"user\":{\"id\":980190962,\"email_address\":\"one@example.com\",\"password_digest\":\"$2a$12$Qo1yNHtJ58InjxM2d3895emekpMVpEzwLTtMJ/piHeDet0oePuKne\",\"created_at\":\"2025-04-23T14:10:49.414Z\",\"updated_at\":\"2025-04-23T14:10:49.414Z\",\"phone_number\":\"555-555-5555\"}}",
  "json": {
    "user": {
      "created_at": "2025-04-23T14:10:49.414Z",
      "email_address": "one@example.com",
      "id": 980190962,
      "password_digest": "$2a$12$Qo1yNHtJ58InjxM2d3895emekpMVpEzwLTtMJ/piHeDet0oePuKne",
      "phone_number": "555-555-5555",
      "updated_at": "2025-04-23T14:10:49.414Z"
    }
  }
}

Faraday offers an API for filtering sensitive information, but using it would mean you would need to duplicate efforts.

Fortunately, we can create a custom formatter to re-use our Rails configuration.

class ApplicationFormatter < Faraday::Logging::Formatter
  def request(env)
    info("Request") { log_url(env.url) }
    info("Request") { log_body(env.body) } if env.body && log_body?
  end

  def response(env)
    info("Response") { log_url(env.url) }
    info("Response") { log_body(env.body) } if env.body && log_body?
  end

  private

  # Re-uses existing configuration from config/initializers/filter_parameter_logging.rb  
  def filter_parameters
    @filter_parameters ||= Rails.configuration.filter_parameters
  end

  # Filters parameters
  def parameter_filter(**options)
    ActiveSupport::ParameterFilter.new(filter_parameters, **options)
  end

  def parse_json(json)
    JSON.parse(json, object_class: HashWithIndifferentAccess)
  end

  def log_body?
    @options[:bodies]
  end

  def log_body(body)
    result = walk(body)

    parameter_filter.filter(result).pretty_inspect
  end

  def log_url(url)
    filtered_url = filter_url(url)

    filtered_url.to_s
  end

  def filter_url(url)
    return url if url.query.nil?

    params = URI.decode_www_form(url.query).to_h
    filtered_params = parameter_filter(mask: "FILTERED").filter(params)
    url.query = URI.encode_www_form(filtered_params)
  end

  def walk(obj)
    case obj
    when Hash
      obj.transform_values { walk(_1) }
    when Array
      obj.map { walk(_1) }
    when String
      parse_json(obj)
    else
      obj
    end
  rescue JSON::ParserError
    obj
  end
end

--- a/lib/faraday.rb
+++ b/lib/faraday.rb
-   errors: true
+   errors: true,
+   formatter: ApplicationFormatter
+ }
end

Now the api_key is filtered when logging both the response and the request. This is because we’re already filtering against partial matches on _key.

INFO -- Request: api_key=FILTERED
INFO -- Response: {"args"=>{"api_key"=>"FILTERED"},
 "url"=>"http://httpbingo.org/get?api_key=FILTERED"}

We’re also no longer exposing all the sensitive attributes on user.

INFO -- Request: http://httpbingo.org/anything
INFO -- Response: {"args"=>{},
 "data"=>
  {"user"=>
    {"id"=>980190962,
     "email_address"=>"[FILTERED]",
     "password_digest"=>"[FILTERED]",
     "created_at"=>"2025-04-23T14:10:49.414Z",
     "updated_at"=>"2025-04-23T14:10:49.414Z",
     "phone_number"=>"[FILTERED]"}},
 "json"=>
  {"user"=>
    {"created_at"=>"2025-04-23T14:10:49.414Z",
     "email_address"=>"[FILTERED]",
     "id"=>980190962,
     "password_digest"=>"[FILTERED]",
     "phone_number"=>"[FILTERED]",
     "updated_at"=>"2025-04-23T14:10:49.414Z"}}}

Creating an allow list

Let’s imagine we add a name column to the users table. Depending on the application, this could be considered sensitive information, but may not warrant encryption.

In this case, you’d need to remember to update config/initializers/filter_parameter_logging.rb. In my experience, this is almost always forgotten. Instead, what we want is an allow list.

The idea is that you’d filter everything except timestamps and IDs.

# config/initializers/filter_parameter_logging.rb

Rails.application.config.filter_parameters += [
  lambda { |k, v| v.replace("[FILTERED]") unless k.match?(/\A(id|.*_id|.*_at|.*_on)\z/) }
]

This can be confirmed when inspecting a user. Note how the name is also filtered.

#<User:0x00000001306db560
 id: 980190962,
 email_address: [FILTERED],
 password_digest: [FILTERED],
 created_at: "2025-04-23 14:10:49.414784000 +0000",
 updated_at: "2025-06-06 11:45:52.243742000 +0000",
 phone_number: "[FILTERED]",
 name: [FILTERED]>

However, this approach might be a little too aggressive, since it filters everything. Notice how the commit parameter is now filtered from our requests.

Parameters: {"authenticity_token"=>"[FILTERED]", "user"=>{"email_address"=>"[FILTERED]", "phone_number"=>"[FILTERED]", "password_digest"=>"[FILTERED]"}, "commit"=>"[FILTERED]"}

This change also affects our Faraday logging.

Now the entire url is filtered, instead of just the api_key parameter.

INFO -- Request: api_key=%5BFILTERED%5D
INFO -- Response: {"args"=>{"api_key"=>["[FILTERED]"]},
 "url"=>"[FILTERED]"}

And the entire data hash is filtered, instead of just the relevant attributes.

INFO -- Request: http://httpbingo.org/anything
INFO -- Response: {"args"=>{},
 "data"=>"[FILTERED]",
 "json"=>
  {"user"=>
    {"created_at"=>"2025-04-23T14:10:49.414Z",
     "email_address"=>"[FILTERED]",
     "id"=>980190962,
     "name"=>"[FILTERED]",
     "password_digest"=>"[FILTERED]",
     "phone_number"=>"[FILTERED]",
     "updated_at"=>"2025-06-06T11:45:52.243Z"}}}

Depending on your team’s security requirements, this might be desirable, but it can create a poor debugging experience.

Wrapping Up

The Rails defaults are a good foundation, and will serve you well. If you need to store sensitive information, make sure to encrypt it. This not only filters it from logs, but also keeps the data secure in the database.

All that aside, it’s still your responsibility to filter sensitive information from logs when using external APIs, services, and tools.

Finally, using an Allow List might be a better option for applications that need to adhere to strict compliance measures, such as Healthcare.

It didn’t make sense to write a test for this, since I was only exploring the idea, and because our test suite is configured to prevent making HTTP requests.

Because of this, I first tried to do all the work in the Rails console, but found it to be too cumbersome. Then I decided to use the rails runner with a temporary file located at lib/scratchpad.rb.

# lib/scratchpad.rb

# Explore how to craft network request
# Parse response
# Process response

Now that I was back in a proper developer environment, I could leverage all the debugging tools that ship with Rails. The end result was that I created a fast feedback loop that allowed me to explore the idea more effectively.

When I was done, I knew how to build my requests, and was able to re-use that code for both the implementation and for stubbing out the requests and responses in my tests.

Tighten the loop

Since I found this process so valuable, I decided to make it part of my Rails workflow moving forward.

If you’re using Vim, or any editor that supports custom key mappings, you could make a mapping to bin/rails runner lib/scratchpad.rb.

" ~/.vimrc

" Rails Scratchpad
nnoremap <silent> <Leader>xx :!bin/rails runner lib/scratchpad.rb<CR>

Then you can configure Git to ignore this file globally.

# ~/.gitignore

lib/scratchpad.rb

Now executing this file is no different than executing my tests.

Next steps

This approach doesn’t have to be limited to exploring network requests. Since the file has access to the entire Rails application, you could use it to explore new Jobs, Models, Services, and more. This concept was largely inspired by Kasper Timm Hansen’s Riffing on Rails approach.

As it turns out, OpenAI’s rate limits are a little more complicated than other APIs.

Rate limits are measured in five ways: RPM (requests per minute), RPD (requests per day), TPM (tokens per minute), TPD (tokens per day), and IPM (images per minute). Rate limits can be hit across any of the options depending on what occurs first.

In our case, we were hitting our TPM (tokens per minute) rate limit.

Regardless of whether a rate limit is exceeded, OpenAI will return the following headers.

x-ratelimit-reset-requests: 1s
x-ratelimit-reset-tokens: 6m0s

It should be noted that these headers represent the amount of time that needs to pass before the rate limit returns to its initial state.

At the time of this writing, OpenAI does not have a first-party Ruby library, but the community has gravitated towards ruby-openai, which is what our project is using. When a rate limit is hit, it raises Faraday::TooManyRequestsError, which gives us access to those headers via #response_headers.

Because OpenAI will return two headers (one for requests per minute and one for tokens per minute), we play it safe and wait based on the greater of the two values.

Rather than roll our own script to parse the header values, we can use Chronic Duration to do this for us. We can then define our own custom error class in an initializer to build the wait value for us.

In order to use this value, we need to leverage #rescue_from in combination with #retry_job. This is because we need to set the wait value dynamically based on the headers, and #retry_on does not provide a way to do this.

Below is a distilled example.

# app/jobs/send_prompt_job.rb
class SendPromptJob < ApplicationJob
  queue_as :default

  MAX_ATTEMPTS = 2

  rescue_from OpenAI::RateLimitError do |error|
    if executions < MAX_ATTEMPTS
      backoff = Backoff.polynomially_longer(executions:)

      retry_job wait: error.wait.seconds + backoff
    else
      Rails.logger.info "Exhausted attempts"
    end
  end

  def perform()
    OpenAI::Client.new.chat(...)
  rescue Faraday::TooManyRequestsError => error
    raise OpenAI::RateLimitError.new(error)
  end
end

# lib/backoff.rb
class Backoff
  DEFAULT_JITTER = 0.15

  def self.polynomially_longer(executions:, jitter: DEFAULT_JITTER)
    ((executions**4) + (Kernel.rand * (executions**4) * jitter)) + 2
  end
end

# config/initializers/openai.rb
module OpenAI
  class RateLimitError < StandardError
    attr_reader :reset_requests_in_seconds, :reset_tokens_in_seconds

    def initialize(faraday_error)
      headers = faraday_error.response_headers&.with_indifferent_access || {}

      @reset_requests_in_seconds = headers.fetch("x-ratelimit-reset-requests", "0s")
      @reset_tokens_in_seconds = headers.fetch("x-ratelimit-reset-tokens", "0s")

      super("The API has hit the rate limit")
    end

    def wait
      [
        parse_duration(reset_requests_in_seconds),
        parse_duration(reset_tokens_in_seconds)
      ].max
    end

    private

    def parse_duration(value)
      ChronicDuration.parse(value) || 0
    end
  end
end

Since we can’t leverage retry_on, we need to ensure we eventually stop retrying the job if it continues to fail.

executions < MAX_ATTEMPTS

Additionally, you’ll also note that we add a “backoff” mechanism per OpenAI’s recommendation.

backoff = Backoff.polynomially_longer(executions:)

retry_job wait: error.wait.seconds + backoff

Avoid rate limits by being proactive

We took a reactive approach to the problem, but I do want to highlight that there’s an opportunity to be proactive by examining the headers that return the amount of remaining requests or tokens that are permitted before exhausting the rate limit.

x-ratelimit-remaining-requests
x-ratelimit-remaining-tokens

Unfortunately, ruby-openai does not return response headers, but there is a workaround. You can create a custom Faraday middleware, and pass it to the client in a block.

class ExtractRateLimitHeaders< Faraday::Middleware
  def on_complete(env)
    # Store these values somewhere
    remaining_requests = env.response_headers["x-ratelimit-remaining-requests"]
    remaining_tokens = env.response_headers["x-ratelimit-remaining-tokens"]
  end
end

client = OpenAI::Client.new do |faraday|
  faraday.use ExtractRateLimitHeaders
end

You could then use this information to reduce the number of tokens you plan on sending to OpenAI by comparing its size with remaining_tokens. Or, if you’re keeping track of how many requests you’re making, you could compare that value with remaining_requests.

# Ensure you're within the request and/or token limit before making a request
if (current_requests < remaining_requests && current_tokens < remaining_tokens)
  client.chat(...)
end

Alternatively, you could temporarily switch to a model with higher token and request limits, or temporarily reduce the amount of tokens sent in the request.

Feel free to follow along below, or view the final code which lives in our Hotwire Example Template.

Create a faux drawer

Since Hotwire encourages the use of server-rendered templates, why not just make a page that looks like a drawer?

For our example, we’ll use Tailwind CSS to create an application-level partial to store our drawer component.

<% #app/views/application/_drawer.html.erb %>
<%# locals: (title: )%>

<div class="relative z-10" aria-labelledby="slide-over-title" role="dialog" aria-modal="true">
  <div class="fixed inset-0 bg-gray-500 bg-opacity-75 transition-opacity"
       aria-hidden="true"></div>

  <div class="fixed inset-0 overflow-hidden">
    <div class="absolute inset-0 overflow-hidden">
      <div class="pointer-events-none fixed inset-y-0 right-0 flex max-w-full pl-10">
        <div class="pointer-events-auto relative w-screen max-w-md">
          <div class="absolute left-0 top-0 -ml-8 flex pr-2 pt-4 sm:-ml-10 sm:pr-4">
            <%= link_to :back, class: "relative rounded-md text-gray-300 hover:text-white focus:outline-none focus:ring-2 focus:ring-white" do %>
              <span class="absolute -inset-2.5"></span>
              <span class="sr-only">Close panel</span>
              <svg class="h-6 w-6" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" aria-hidden="true" data-slot="icon">
                <path stroke-linecap="round" stroke-linejoin="round" d="M6 18 18 6M6 6l12 12" />
              </svg>
            <% end %>
          </div>

          <div class="flex h-full flex-col overflow-y-scroll bg-white py-6 shadow-xl">
            <div class="px-4 sm:px-6">
              <h2 class="text-base font-semibold text-gray-900" id="slide-over-title"><%= title %></h2>
            </div>
            <div class="relative mt-6 flex-1 px-4 sm:px-6">
              <%= yield %>
            </div>
          </div>
        </div>
      </div>
    </div>
  </div>
</div>

We can even conditionally render the drawer template using variants in an effort to reuse our existing controller and views.

<%# app/views/products/edit.html+drawer.erb %>

<%= render "drawer", title: "Edit product" do %>
  <%= render "form", product: @product %>
<% end %>

<%# app/views/products/new.html+drawer.erb %>

<%= render "drawer", title: "New product" do %>
  <%= render "form", product: @product %>
<% end %>

--- a/app/controllers/products_controller.rb
+++ b/app/controllers/products_controller.rb
@@ -1,5 +1,6 @@
 class ProductsController < ApplicationController
   before_action :set_product, only: %i[ show edit update destroy ]
+  before_action :set_variant, only: %i[ new edit update create ]

   def index
     @products = Product.all
@@ -9,10 +10,12 @@ class ProductsController < ApplicationController
   end

   def new
+    request.variant = @variant
     @product = Product.new
   end

   def edit
+    request.variant = @variant
   end

   def create
@@ -21,7 +24,7 @@ class ProductsController < ApplicationController
     if @product.save
       redirect_to products_path, notice: "Product was successfully created."
     else
-      render :new, status: :unprocessable_entity
+      render :new, variants: @variant, status: :unprocessable_entity
     end
   end

@@ -29,7 +32,7 @@ class ProductsController < ApplicationController
     if @product.update(product_params)
       redirect_to products_path, notice: "Product was successfully updated."
     else
-      render :edit, status: :unprocessable_entity
+      render :edit, variants: @variant, status: :unprocessable_entity
     end
   end

@@ -48,4 +51,8 @@ class ProductsController < ApplicationController
   def product_params
     params.require(:product).permit(:name, :description)
   end
+
+  def set_variant
+    @variant ||= :drawer if params[:variant] == "drawer"
+  end
 end

--- a/app/views/products/index.html.erb
+++ b/app/views/products/index.html.erb
@@ -8,7 +8,7 @@
   <div class="flex justify-between items-center">
     <h1 class="font-bold text-4xl">Products</h1>
     <%= link_to "New product",
-      new_product_path,
+      new_product_path(variant: :drawer),
       class: "rounded-lg py-3 px-5 bg-blue-600 text-white block font-medium" %>
   </div>

--- a/app/views/products/_product.html.erb
+++ b/app/views/products/_product.html.erb
@@ -11,7 +11,7 @@

   <p>
     <%= link_to "Edit this product",
-      edit_product_path(product),
+      edit_product_path(product, variant: :drawer),
       class: "ml-2 rounded-lg py-3 px-5 bg-gray-100 inline-block font-medium" %>
   </p>

--- a/app/views/products/_form.html.erb
+++ b/app/views/products/_form.html.erb
@@ -21,6 +21,8 @@
     <%= form.text_area :description, rows: 4, class: "block shadow rounded-md border border-gray-400 outline-none px-3 py-2 mt-2 w-full" %>
   </div>

+  <%= hidden_field_tag :variant, @variant %>
+
   <div class="inline">
     <%= form.submit class: "rounded-lg py-3 px-5 bg-blue-600 text-white inline-block font-medium cursor-pointer" %>
   </div>

Because Turbo Drive “…updates the page without doing a full reload”, the experience is pretty snappy.

Animate the drawer with View Transitions

As snappy as this experience is, a certain level of fidelity is expected when interacting with drawers.

Fortunately, we can leverage the View Transition API to animate the drawer between page requests.

All we need to do is enable the feature by adding a meta tag.

--- a/app/views/layouts/application.html.erb
+++ b/app/views/layouts/application.html.erb
@@ -3,6 +3,7 @@
   <head>
     <title>HotwireExampleTemplate</title>
     <meta name="viewport" content="width=device-width,initial-scale=1">
+    <meta name="view-transition" content="same-origin" />
     <%= csrf_meta_tags %>
     <%= csp_meta_tag %>
     <%= stylesheet_link_tag "tailwind", "inter-font", "data-turbo-track": "reload" %>

From there, we can customize the animations.

@keyframes fade-out {
  from {
    opacity: 100%;
  }

  to {
    opacity: 0%;
  }
}

@keyframes fade-in {
  from {
    opacity: 0%;
  }

  to {
    opacity: 100%;
  }
}

@keyframes slide-out {
  from {
    transform: translateX(0%);
  }

  to {
    transform: translateX(100%);
  }
}

@keyframes slide-in {
  from {
    transform: translateX(100%);
  }

  to {
    transform: translateX(0%);
  }
}

::view-transition-old(backdrop) {
  animation: 0.4s ease-in both fade-out;
}

::view-transition-new(backdrop) {
  animation: 0.4s ease-in both fade-in;
}

::view-transition-old(panel) {
  animation: 0.4s ease-in both slide-out;
}

::view-transition-new(panel) {
  animation: 0.4s ease-in both slide-in;
}

#panel {
  view-transition-name: panel;
}

#backdrop {
  view-transition-name: backdrop;
}

We just need to be sure to identify the relevant drawer elements we want to animate.

--- a/app/views/application/_drawer.html.erb
+++ b/app/views/application/_drawer.html.erb
@@ -1,13 +1,15 @@
 <%# locals: (title: )%>

 <div class="relative z-10" aria-labelledby="slide-over-title" role="dialog" aria-modal="true">
-  <div class="fixed inset-0 bg-gray-500 bg-opacity-75 transition-opacity"
+  <div id="backdrop"
+       class="fixed inset-0 bg-gray-500 bg-opacity-75 transition-opacity"
        aria-hidden="true"></div>

   <div class="fixed inset-0 overflow-hidden">
     <div class="absolute inset-0 overflow-hidden">
       <div class="pointer-events-none fixed inset-y-0 right-0 flex max-w-full pl-10">
-        <div class="pointer-events-auto relative w-screen max-w-md">
+        <div id="panel"
+             class="pointer-events-auto relative w-screen max-w-md">
           <div class="absolute left-0 top-0 -ml-8 flex pr-2 pt-4 sm:-ml-10 sm:pr-4">
             <%= link_to :back, class: "relative rounded-md text-gray-300 hover:text-white focus:outline-none focus:ring-2 focus:ring-white" do %>
               <span class="absolute -inset-2.5"></span>

With that, our drawer animates in and out. You’ll also note that it does not animate when there’s a form error.

Render the drawer on the current page

At this point, I’d argue that we have a fully functioning drawer component, but there’s still an opportunity to take it a step further by rendering it on the current page. One way to achieve this is to render the drawer in a Turbo Frame.

First, we’ll need to wrap the existing drawer component in a turbo_frame_tag.

--- a/app/views/application/_drawer.html.erb
+++ b/app/views/application/_drawer.html.erb
@@ -1,5 +1,6 @@
 <%# locals: (title: )%>

+<%= turbo_frame_tag :drawer do %>
   <div class="relative z-10" aria-labelledby="slide-over-title" role="dialog" aria-modal="true">
     <div id="backdrop"
          class="fixed inset-0 bg-gray-500 bg-opacity-75 transition-opacity"
@@ -33,3 +34,4 @@
       </div>
     </div>
   </div>
+<% end %>

Next, we’ll want to add the corresponding turbo_frame_tag to the relevant page, and ensure all existing links point to that frame.

--- a/app/views/products/index.html.erb
+++ b/app/views/products/index.html.erb
@@ -9,7 +9,8 @@
     <h1 class="font-bold text-4xl">Products</h1>
     <%= link_to "New product",
       new_product_path(variant: :drawer),
-      class: "rounded-lg py-3 px-5 bg-blue-600 text-white block font-medium" %>
+      class: "rounded-lg py-3 px-5 bg-blue-600 text-white block font-medium",
+      data: { turbo_frame: :drawer } %>
   </div>

   <div id="products" class="min-w-full">
@@ -18,3 +19,5 @@
     <% end %>
   </div>
 </div>
+
+<%= turbo_frame_tag :drawer %>

--- a/app/views/products/_product.html.erb
+++ b/app/views/products/_product.html.erb
@@ -12,7 +12,8 @@
   <p>
     <%= link_to "Edit this product",
       edit_product_path(product, variant: :drawer),
-      class: "ml-2 rounded-lg py-3 px-5 bg-gray-100 inline-block font-medium" %>
+      class: "ml-2 rounded-lg py-3 px-5 bg-gray-100 inline-block font-medium",
+      data: {turbo_frame: :drawer} %>
   </p>

 </div>

Because we’re now operating in the context of a Turbo Frame when submitting the form, we need to refresh the page to ensure the newly created or modified product appears on the page. This is because requests made from within a Turbo Frame replace the content of just that frame, not the entire page.

We can do this by conditionally triggering a page refresh when the request is coming from within a Turbo Frame.

--- a/app/controllers/products_controller.rb
+++ b/app/controllers/products_controller.rb
@@ -22,7 +22,10 @@ class ProductsController < ApplicationController
     @product = Product.new(product_params)

     if @product.save
-      redirect_to products_path, notice: "Product was successfully created."
+      respond_to do |format|
+        format.turbo_stream if turbo_frame_request?
+        format.html { redirect_to products_path, notice: "Product was successfully created." }
+      end
     else
       render :new, variants: @variant, status: :unprocessable_entity
     end
@@ -30,7 +33,10 @@ class ProductsController < ApplicationController

   def update
     if @product.update(product_params)
-      redirect_to products_path, notice: "Product was successfully updated."
+      respond_to do |format|
+        format.turbo_stream if turbo_frame_request?
+        format.html { redirect_to products_path, notice: "Product was successfully updated." }
+      end
     else
       render :edit, variants: @variant, status: :unprocessable_entity
     end

<%# app/views/products/create.turbo_stream.erb %>

<turbo-stream action="refresh"></turbo-stream>

<%# app/views/products/update.turbo_stream.erb %>

<turbo-stream action="refresh"></turbo-stream>

If we examine the current behavior, we’ll notice that the animations are broken. The drawer no longer animates in, but does animate out on form submission. It also no longer animates out when dismissed.

This is because the drawer is now being inserted into the page, rather than being navigated to. Conversely, dismissing the drawer removes it from the DOM. In each case, this means the view transitions do not have an opportunity to render.

However, submitting the form still results in a page navigation, which triggers the view transitions.

In order to account for this, we’ll need to introduce el-transition and write a custom Stimulus Controller.

We can use lifecycle callbacks to animate the drawer in when we detect that it’s entered that page.

On the flip side, we can pause rendering so that we can animate those elements off the page before they’re removed from the DOM.

// app/javascript/controllers/drawer_controller.js

import { Controller } from "@hotwired/stimulus";
import { enter, leave } from "el-transition";

// Connects to data-controller="drawer"
export default class extends Controller {
  static targets = ["backdrop", "panel"];

  #isEntering;
  #isLeaving;

  backdropTargetConnected(target) {
    if (this.#isEntering) enter(target);
  }

  panelTargetConnected(target) {
    if (this.#isEntering) enter(target);
  }

  async animate(event) {
    const {
      detail: { newFrame },
    } = event;

    const currentChildCount = this.element.children.length;
    const newChildCount = newFrame.children.length;

    this.#isEntering = currentChildCount == 0 && newChildCount > 0;
    this.#isLeaving = currentChildCount > 0 && newChildCount == 0;

    if (this.#isLeaving) {
      event.preventDefault();

      await Promise.all([
        leave(this.backdropTarget).then(() => this.backdropTarget.remove()),
        leave(this.panelTarget).then(() => this.panelTarget.remove()),
      ]);

      event.detail.resume();
    }
  }
}

The key is that we need to inspect the newFrame dispatched from turbo:before-frame-render to determine if the drawer is entering or leaving.

const {
  detail: { newFrame },
} = event;

const currentChildCount = this.element.children.length;
const newChildCount = newFrame.children.length;

Now we need to wire up our controller to our existing Turbo Frame.

--- a/app/views/products/index.html.erb
+++ b/app/views/products/index.html.erb
@@ -21,4 +21,4 @@
   </div>
 </div>
 
-<%= turbo_frame_tag :drawer %>
+<%= turbo_frame_tag :drawer, data: {controller: "drawer", action: "turbo:before-frame-render->drawer#animate"} %>

Finally, we just need to set the targets and add the expected dataset attributes.

--- a/app/views/application/_drawer.html.erb
+++ b/app/views/application/_drawer.html.erb
@@ -4,13 +4,27 @@
   <div class="relative z-10" aria-labelledby="slide-over-title" role="dialog" aria-modal="true">
     <div id="backdrop"
          class="fixed inset-0 bg-gray-500 bg-opacity-75 transition-opacity"
+         data-drawer-target="backdrop"
+         data-transition-enter="ease-in-out duration-500"
+         data-transition-enter-start="opacity-0"
+         data-transition-enter-end="opacity-100"
+         data-transition-leave="ease-in-out duration-500"
+         data-transition-leave-start="opacity-100"
+         data-transition-leave-end="opacity-0"
          aria-hidden="true"></div>
 
     <div class="fixed inset-0 overflow-hidden">
       <div class="absolute inset-0 overflow-hidden">
         <div class="pointer-events-none fixed inset-y-0 right-0 flex max-w-full pl-10">
           <div id="panel"
-               class="pointer-events-auto relative w-screen max-w-md">
+               class="pointer-events-auto relative w-screen max-w-md"
+               data-transition-enter="transform transition ease-in-out duration-500 sm:duration-700"
+               data-transition-enter-start="translate-x-full"
+               data-transition-enter-end="translate-x-0"
+               data-transition-leave="transform transition ease-in-out duration-500 sm:duration-700"
+               data-transition-leave-start="translate-x-0"
+               data-transition-leave-end="translate-x-full"
+               data-drawer-target="panel">
             <div class="absolute left-0 top-0 -ml-8 flex pr-2 pt-4 sm:-ml-10 sm:pr-4">
               <%= link_to :back, class: "relative rounded-md text-gray-300 hover:text-white focus:outline-none focus:ring-2 focus:ring-white" do %>
                 <span class="absolute -inset-2.5"></span>

And with that, our drawer now animates in and out of the current page.

Wrapping up

I hope this tutorial highlighted the power of server-side rendering coupled with emerging web APIs. By simply creating a page that looks like a drawer and using the View Transition API, we were able to create a fully functioning drawer component without using any JavaScript. I hope you found it as compelling as I did.

At first, I was a little overwhelmed because I didn’t know exactly how to do this. The response was mapped to a Ruby object, and was not Active Record backed, so I wasn’t sure how to leverage Turbo. However, I found it to be surprisingly easy, and I wanted to share the highlights through a distilled example.

Although we’ll be focusing on network requests, I want to highlight that this approach works for all types of slow operations.

Here’s an outline of what we’re trying to accomplish.

1. A request is made that triggers a slow operation that normally would result in a timeout.
2. Move that slow operation to a background job to be processed asynchronously.
3. Render a loading screen while the job is being processed.
4. Once the background job is finished processing, update the client accordingly.

Feel free to follow along below, or view the final code which lives in our Hotwire Example Template.

Our base

We’ll start with a simple Active Model backed form where the user enters the ID for a record stored in an external system. Since the record is stored in an external system, we issue a network request to retrieve it. Note that the page can’t respond until the request is processed, resulting in a poor user experience.

The controller and corresponding model aren’t particularly interesting. The only thing worth mentioning is that we’re calling OrderSearch#process in our controller, which issues the network request in-line.

# app/controllers/orders_controller.rb

class OrdersController < ApplicationController
  def index
    @order_search = OrderSearch.new(order_id: params[:order_id])
    @order_search.process
  end
end

# app/models/order_search.rb

class OrderSearch
  include ActiveModel::Model
  include ActiveModel::Attributes

  attribute :order_id, :big_integer
  attribute :result

  alias_method :processed?, :result

  def processing?
    order_id && result.nil?
  end

  def process
    return unless processing?

    # Simulate network request
    sleep 1

    # Simulate building result from response
    self.result = Order.new(id: order_id, product: "Some Widget", quantity: 1)
  end
end

It’s worth highlighting that we’re mapping the response from our network request to a non-persisted Active Model object.

# Simulate building result from response
self.result = Order.new(id: order_id, product: "Some Widget", quantity: 1)

The corresponding views are just as unremarkable.

<% # app/views/orders/index.html.erb %>

<%= form_with model: @order_search, scope: "", method: :get do |form| %>
  <%= form.label :order_id, "Order ID" %>
  <%= form.number_field :order_id, required: true %>

  <%= form.submit "Find order" %>
<% end %>

<%= render @order_search %>

<% # app/views/order_searches/_order_search.html.erb %>

<% if order_search.processing? %>
  <p>Searching...</p>
<% elsif order_search.processed? %>
  <%= render order_search.result %>
<% end %>

Process request in the background

With our setup out of the way, we can improve the UX by backgrounding the network request in a job which will allow the controller to respond immediately.

--- a/app/models/order_search.rb
+++ b/app/models/order_search.rb
@@ -14,10 +14,6 @@ class OrderSearch
   def process
     return unless processing?

-    # Simulate network request
-    sleep 1
-
-    # Simulate building result from response
-    self.result = Order.new(id: order_id, product: "Some Widget", quantity: 1)
+    GetOrderJob.perform_later(self)
   end
 end

Our job is not only responsible for processing the request, but also for broadcasting the response back to the page.

In order to do this, we’ll need to rely on some lower-level APIs provided by Turbo Rails and Rails.

First, we’ll use Turbo::StreamsChannel which is extended by Turbo::Streams::Broadcasts and Turbo::Streams::StreamName to broadcast the response back to the page by passing the order_search as the first argument.

We use dom_id to generate an identifier from the order_search instance. We’re not required to use dom_id, but we are required to ensure the view we’re broadcasting to has an element with the same identifier.

Finally, we need to ensure we actually broadcast something to the page. We could build up the HTML by hand, but since we already have an existing partial, we can just call render and pass in the partial path and object to build the content.

# app/jobs/get_order_job.rb

class GetOrderJob < ActiveJob::Base
  def perform(order_search)
    # Simulate network request
    sleep 1

    # Simulate building result from response
    order_search.result = Order.new(id: order_search.order_id, product: "Some Widget", quantity: 1)

    Turbo::StreamsChannel.broadcast_replace_to(
      order_search,
      target: ActionView::RecordIdentifier.dom_id(order_search),
      content: build_content(order_search)
    )
  end

  private

  def build_content(order_search)
    ApplicationController.render(
      partial: "order_searches/order_search",
      locals: { order_search: }
    )
  end
end

Creating a custom serializer

Since Active Job does not support Active Model instances as a type of argument, we’ll need to create a custom serializer and make some changes to our application’s configuration.

# app/serializers/order_search_serializer.rb

class OrderSearchSerializer < ActiveJob::Serializers::ObjectSerializer
  def serialize(order_search)
    super(
      "order_id" => order_search.order_id,
      "result" => order_search.result
    )
  end

  def deserialize(hash)
    OrderSearch.new(order_id: hash["order_id"], result: hash["result"])
  end

  private

  def klass
    OrderSearch
  end
end

--- a/config/application.rb
+++ b/config/application.rb
@@ -23,5 +23,6 @@ module HotwireExamples
     #
     # config.time_zone = "Central Time (US & Canada)"
     # config.eager_load_paths << Rails.root.join("extras")
+    config.autoload_once_paths << "#{root}/app/serializers"
   end
 end

# config/initializers/custom_serializers.rb

Rails.application.config.active_job.custom_serializers << OrderSearchSerializer

Finally, we need to add a corresponding identifier to our view to map to the target option from above. We also need to add a turbo_stream_from element to the page so that it can receive the broadcast from our job.

--- a/app/views/order_searches/_order_search.html.erb
+++ b/app/views/order_searches/_order_search.html.erb
@@ -1,5 +1,8 @@
-<% if order_search.processing? %>
-  <p>Searching...</p>
-<% elsif order_search.processed? %>
-  <%= render order_search.result %>
-<% end %>
+<div id="<%= dom_id(order_search) %>">
+  <% if order_search.processing? %>
+    <%= turbo_stream_from order_search %>
+    <p>Searching...</p>
+  <% elsif order_search.processed? %>
+    <%= render order_search.result %>
+  <% end %>
+</div>

With these changes in place, we should have a much smoother user experience.

Leverage Turbo::Broadcastable

If you were reading the last section and thought it was a smell to leverage all those low level APIs, you’re right.

What we did was essentially recreate the Turbo::Broadcastable API. We did this because we didn’t have access to it, since it’s only included in Active Record, and we’re using Active Model.

We can dramatically improve our implementation simply by including it in our model, and calling broadcast_replace.

diff --git a/app/models/order_search.rb b/app/models/order_search.rb
index da22b7c..3621101 100644
--- a/app/models/order_search.rb
+++ b/app/models/order_search.rb
@@ -1,6 +1,7 @@
 class OrderSearch
   include ActiveModel::Model
   include ActiveModel::Attributes
+  include Turbo::Broadcastable

   attribute :order_id, :big_integer
   attribute :result

--- a/app/jobs/get_order_job.rb
+++ b/app/jobs/get_order_job.rb
@@ -6,19 +6,6 @@ class GetOrderJob < ActiveJob::Base
     # Simulate building result from response
     order_search.result = Order.new(id: order_search.order_id, product: "Some Widget", quantity: 1)

-    Turbo::StreamsChannel.broadcast_replace_to(
-      order_search,
-      target: ActionView::RecordIdentifier.dom_id(order_search),
-      content: build_content(order_search)
-    )
-  end
-
-  private
-
-  def build_content(order_search)
-    ApplicationController.render(
-      partial: "order_searches/order_search",
-      locals: { order_search: }
-    )
+    order_search.broadcast_replace
   end
 end

I want to highlight that this works so seamlessly because we closely adhered to Rails conventions from the start. Most notably, regarding where we placed our partials, and the inclusion of ActiveModel::Model in OrderSearch.

However, even if we hadn’t, we could still have leveraged broadcast_replace_to to control the broadcast without all the ceremony from before.

Scope broadcast to the current user

Finally, I wanted to share some pragmatic advice in regards to scoping the broadcast to the current user.

Since it’s more than likely your application is using authentication, you’ll want to scope these broadcasts to the user that issued them.

Below is what that might look like.

--- a/app/models/order_search.rb
+++ b/app/models/order_search.rb
@@ -5,6 +5,7 @@ class OrderSearch

   attribute :order_id, :big_integer
   attribute :result
+  attribute :user

   alias_method :processed?, :result

--- a/app/controllers/orders_controller.rb
+++ b/app/controllers/orders_controller.rb
@@ -1,6 +1,6 @@
 class OrdersController < ApplicationController
   def index
-    @order_search = OrderSearch.new(params.permit!.slice(:order_id))
+    @order_search = OrderSearch.new(params.permit!.slice(:order_id).with_defaults(user: current_user))
     @order_search.process
   end
 end

The key is that we now pass the user and the object to turbo_stream_from, and ensure we’re broadcasting to that stream by using broadcast_replace_to which also accepts the user and the object.

--- a/app/views/order_searches/_order_search.html.erb
+++ b/app/views/order_searches/_order_search.html.erb
@@ -1,6 +1,6 @@
 <div id="<%= dom_id(order_search) %>">
   <% if order_search.processing? %>
-    <%= turbo_stream_from order_search %>
+    <%= turbo_stream_from order_search.user, order_search %>
     <p>Searching...</p>
   <% elsif order_search.processed? %>
     <%= render order_search.result %>

--- a/app/jobs/get_order_job.rb
+++ b/app/jobs/get_order_job.rb
@@ -6,6 +6,6 @@ class GetOrderJob < ActiveJob::Base
     # Simulate building result from response
     order_search.result = Order.new(id: order_search.order_id, product: "Some Widget", quantity: 1)

-    order_search.broadcast_replace
+    order_search.broadcast_replace_to order_search.user, order_search
   end
 end

We just need to make sure to update our serializer too.

--- a/app/serializers/order_search_serializer.rb
+++ b/app/serializers/order_search_serializer.rb
@@ -2,12 +2,13 @@ class OrderSearchSerializer < ActiveJob::Serializers::ObjectSerializer
   def serialize(order_search)
     super(
       "order_id" => order_search.order_id,
-      "result" => order_search.result
+      "result" => order_search.result,
+      "user" => order_search.user
     )
   end

   def deserialize(hash)
-    OrderSearch.new(order_id: hash["order_id"], result: hash["result"])
+    OrderSearch.new(order_id: hash["order_id"], result: hash["result"], user: hash["user"])
   end

   private

Wrapping up

I used to think of Turbo as something that was exclusive to Active Record. However, as we just demonstrated, that’s not the case.

Turbo can work just as seamlessly with Active Model-like objects, especially when you’re closely adhering to Rails conventions.

Finally, this approach doesn’t need to be limited to network requests. We can use the same pattern to handle any type of process that needs to be run in the background, such as a large calculation or query.

Our base

We’ll start with all logic placed in the controller and view.

def index
  @posts = sort_posts(Post.all).then { filter_posts(_1) }
end

private

  def sort_posts(scope)
    if (order = params.dig(:query, :sort))
      column, direction = order.split(" ")

      if column.presence_in(%w[title created_at]) && direction.presence_in(%w[asc desc])
        scope.order("#{column} #{direction}")
      else
        []
      end
    else
      scope.order(created_at: :desc)
    end
  end

  def filter_posts(scope)
    filter_by_title_or_body(scope)
      .then { filter_by_status(_1) }
      .then { filter_by_author(_1) }
  end

  def filter_by_title_or_body(scope)
    if (title_or_body = params.dig(:query, :title_or_body_contains).presence)
      scope.where("title LIKE ? or body LIKE ?", "%#{title_or_body}%", "%#{title_or_body}%")
    else
      scope
    end
  end

  def filter_by_status(scope)
    if (status = params.dig(:query, :status_in)&.compact_blank&.presence)
      scope.where(status:)
    else
      scope
    end
  end

  def filter_by_author(scope)
    if (author_id = params.dig(:query, :author_id_eq).presence)
      scope.where(author_id:)
    else
      scope
    end
  end

Note that the controller is responsible for validating the parameters to ensure they aren’t tampered with.

if column.presence_in(%w[title created_at]) && direction.presence_in(%w[asc desc])

It also sets default sort values.

if (order = params.dig(:query, :sort))
  # ..
else
  scope.order(created_at: :desc)
end

Now let’s take a look at the corresponding form:

<h1>Posts</h1>

<%= form_with scope: :query, url: posts_path, method: :get do |form| %>
  <div>
    <%= form.label :title_or_body_contains, "Title or body contains" %>
    <%= form.search_field :title_or_body_contains, value: params.dig(:query, :title_or_body_contains) %>
  </div>

  <div>
    <%= form.label :sort, "Sort by" %>
    <%= form.select :sort, options_for_select(
      [
        ["Title - A to Z", "title asc"],
        ["Title - Z to A", "title desc"],
        ["Created At - Newest to Oldest", "created_at desc"],
        ["Created At - Oldest to Newest", "created_at asc"]
      ], params.dig(:query, :sort) || "created_at desc"
    ) %>
  </div>

  <div>
    <%= form.label :author_id_eq, "Authored by" %>
    <%= form.select :author_id_eq, options_from_collection_for_select(Author.all, "id", "name", params.dig(:query, :author_id_eq).to_i), {prompt: "Any"}  %>
  </div>

  <%= field_set_tag "Status" do %>
    <%= form.collection_check_boxes(:status_in, Post.statuses.keys, :to_s, :capitalize) do |builder| %>
      <%= builder.label { builder.check_box(checked: params.dig(:query, :status_in)&.include?(builder.value)) + builder.text } %>
    <% end %>
  <% end %>

  <%= submit_tag "Search" %>
  <%= link_to "Reset", posts_path %>
<% end %>

Note that it’s responsible for setting the value based on the params. Additionally, the options for sort, author_id_eq, and status_in are rendered directly in the view.

Although this code works, we can simplify it while improving ergonomics by extracting it into a model.

Extract logic into a model

As mentioned before, the controller is responsible for validation and setting default values. Those sound like the responsibilities of a model.

Let’s start by extracting the logic, and mapping the parameters to attributes.

# app/models/post/query.rb

class Post::Query
  include ActiveModel::Model
  include ActiveModel::Attributes

  attribute :author_id_eq, :big_integer
  attribute :column, :string
  attribute :direction, :string
  attribute :sort, :string, default: "created_at desc"
  attribute :status_in, default: []
  attribute :title_or_body_contains, :string

  validates :column, inclusion: { in: %w[created_at title] }
  validates :direction, inclusion: { in: %w[asc desc] }

  def initialize(...)
    super
    self.sort = sort
  end

  def sort=(value)
    super
    column, direction = sort.split(" ")
    assign_attributes(column:, direction:)
  end

  def results
    if valid?
      sort_posts.then { filter_posts(_1) }
    else
      []
    end
  end

  private
    def sort_posts(scope = Post.all)
      scope.order("#{column} #{direction}")
    end

    def filter_posts(scope)
      filter_by_title_or_body(scope)
        .then { filter_by_status(_1) }
        .then { filter_by_author(_1) }
    end

    def filter_by_title_or_body(scope)
      if (title_or_body = title_or_body_contains.presence)
        scope.where("title LIKE ? or body LIKE ?", "%#{title_or_body}%", "%#{title_or_body}%")
      else
        scope
      end
    end

    def filter_by_status(scope)
      if (status = status_in.compact_blank.presence)
        scope.where(status:)
      else
        scope
      end
    end

    def filter_by_author(scope)
      if (author_id = author_id_eq.presence)
        scope.where(author_id:)
      else
        scope
      end
    end
end

Now we can effectively validate our attributes through the ActiveModel::Validations API instead of doing this in the controller.

We’re also able to set default values thanks to the ActiveModel::Attributes API. Note that we assign the column and direction attributes from the sort value on initialization, or when setting the sort value directly.

Before

def sort_posts(scope)
  if (order = params.dig(:query, :sort))
    column, direction = order.split(" ")

    if column.presence_in(%w[title created_at]) && direction.presence_in(%w[asc desc])
      scope.order("#{column} #{direction}")
    else
     []
    end
  else
    scope.order(created_at: :desc)
  end
end

After

def results
  if valid?
    sort_posts.then { filter_posts(_1) }
  else
    []
  end
end

With our logic extracted, we’re now able to refactor our controller.

--- a/app/controllers/posts_controller.rb
+++ b/app/controllers/posts_controller.rb
@@ -3,7 +3,8 @@ class PostsController < ApplicationController

   # GET /posts or /posts.json
   def index
-    @posts = sort_posts(Post.all).then { filter_posts(_1) }
+    @query = Post::Query.new(params.fetch(:query, {}).permit(:author_id_eq, :sort, :title_or_body_contains, status_in: []))
+    @posts = @query.results
   end

   # GET /posts/1 or /posts/1.json
@@ -67,48 +68,4 @@ class PostsController < ApplicationController
     def post_params
       params.require(:post).permit(:title, :body, :status, :author_id)
     end
-
-    def sort_posts(scope)
-      if (order = params.dig(:query, :sort))
-        column, direction = order.split(" ")
-
-        if column.presence_in(%w[title created_at]) && direction.presence_in(%w[asc desc])
-          scope.order("#{column} #{direction}")
-        else
-          []
-        end
-      else
-        scope.order(created_at: :desc)
-      end
-    end
-
-    def filter_posts(scope)
-      filter_by_title_or_body(scope)
-        .then { filter_by_status(_1) }
-        .then { filter_by_author(_1) }
-    end
-
-    def filter_by_title_or_body(scope)
-      if (title_or_body = params.dig(:query, :title_or_body_contains).presence)
-        scope.where("title LIKE ? or body LIKE ?", "%#{title_or_body}%", "%#{title_or_body}%")
-      else
-        scope
-      end
-    end
-
-    def filter_by_status(scope)
-      if (status = params.dig(:query, :status_in)&.compact_blank&.presence)
-        scope.where(status:)
-      else
-        scope
-      end
-    end
-
-    def filter_by_author(scope)
-      if (author_id = params.dig(:query, :author_id_eq).presence)
-        scope.where(author_id:)
-      else
-        scope
-      end
-    end
 end

Update the form

Since form_with pairs well with model objects, we can simplify our existing form by passing in our new model to the model option.

This will alleviate the need to manually set the value based on the params. Whatever values are set to the Post::Query during initialization will automatically be set to the corresponding field’s value.

--- a/app/views/posts/index.html.erb
+++ b/app/views/posts/index.html.erb
@@ -4,33 +4,24 @@

 <h1>Posts</h1>

-<%= form_with scope: :query, url: posts_path, method: :get do |form| %>
+<%= form_with model: @query, scope: :query, url: posts_path, method: :get do |form| %>
   <div>
     <%= form.label :title_or_body_contains, "Title or body contains" %>
-    <%= form.search_field :title_or_body_contains, value: params.dig(:query, :title_or_body_contains) %>
+    <%= form.search_field :title_or_body_contains %>
   </div>

   <div>
     <%= form.label :sort, "Sort by" %>
-    <%= form.select :sort, options_for_select(
-      [
-        ["Title - A to Z", "title asc"],
-        ["Title - Z to A", "title desc"],
-        ["Created At - Newest to Oldest", "created_at desc"],
-        ["Created At - Oldest to Newest", "created_at asc"]
-      ], params.dig(:query, :sort) || "created_at desc"
-    ) %>
+    <%= form.select :sort, @query.options_for_sort %>
   </div>

   <div>
     <%= form.label :author_id_eq, "Authored by" %>
-    <%= form.select :author_id_eq, options_from_collection_for_select(Author.all, "id", "name", params.dig(:query, :author_id_eq).to_i), {prompt: "Any"}  %>
+    <%= form.select :author_id_eq, @query.options_for_authored_by, {prompt: "Any"}  %>
   </div>

   <%= field_set_tag "Status" do %>
-    <%= form.collection_check_boxes(:status_in, Post.statuses.keys, :to_s, :capitalize) do |builder| %>
-      <%= builder.label { builder.check_box(checked: params.dig(:query, :status_in)&.include?(builder.value)) + builder.text } %>
-    <% end %>
+    <%= form.collection_check_boxes(:status_in, @query.options_for_status, :to_s, :capitalize) %>
   <% end %>

   <%= submit_tag "Search" %>

You’ll also note that we were able to simplify how the sort, author_id_eq and status_in options are set by placing that logic in the model.

--- a/app/models/post/query.rb
+++ b/app/models/post/query.rb
@@ -12,6 +12,23 @@ class Post::Query
   validates :column, inclusion: { in: %w[created_at title] }
   validates :direction, inclusion: { in: %w[asc desc] }

+  def options_for_sort
+    [
+      [ "Title - A to Z", "title asc" ],
+      [ "Title - Z to A", "title desc" ],
+      [ "Created At - Newest to Oldest", "created_at desc" ],
+      [ "Created At - Oldest to Newest", "created_at asc" ]
+    ]
+  end
+
+  def options_for_authored_by
+    Author.all.collect { [ _1.name, _1.id ] }
+  end
+
+  def options_for_status
+    Post.statuses.keys
+  end
+
   def initialize(...)
     super
     self.sort = sort

A final touch

With our refactor nearly complete, there’s still an opportunity to make a minor improvement by having the url generated for us.

To achieve this, we’ll need to reach for resolve. What this does is map Post::Query to posts_url, so that form_with knows how to build the url automatically. This happens by default with Active Record objects.

--- a/config/routes.rb
+++ b/config/routes.rb
@@ -12,4 +12,8 @@ Rails.application.routes.draw do

   # Defines the root path route ("/")
   root "posts#index"
+
+  resolve "Post::Query" do |model|
+    route_for :posts
+  end
 end

With the change to our routes, we can remove the url from our form, and rely on record identification.

--- a/app/views/posts/index.html.erb
+++ b/app/views/posts/index.html.erb
@@ -4,7 +4,7 @@

 <h1>Posts</h1>

-<%= form_with model: @query, scope: :query, url: posts_path, method: :get do |form| %>
+<%= form_with model: @query, scope: :query, method: :get do |form| %>
   <div>
     <%= form.label :title_or_body_contains, "Title or body contains" %>
     <%= form.search_field :title_or_body_contains %>

Wrapping up

What we’ve done here is created a form object, but for a GET request.

While this concept isn’t new and extends beyond search forms, the key takeaway is how effectively form_with integrates with model objects. By using a model object, we were able to drastically simplify our controller and form, and create something that better adheres to Rails’ conventions.

Because Rails encourages the reuse of partials and views, this can lead to situations where you need to conditionally render a Turbo Frame. One such example is inline editing, which we’ll explore in this tutorial.

Our Base

Our starting point does not yet warrant the need to conditionally render any of the Turbo Frames because all three instances use the same HTML. Most notably between the show and index views. This is because both of those views render the _post partial.

# app/views/posts/index.html.erb

<% @posts.each do |post| %>
  <%= turbo_frame_tag dom_id(post) do %>
    <%= render post %>
    <%= link_to "Edit", edit_post_path(post) %>
  <% end %>
<% end %>

# app/views/posts/_post.html.erb

<div>
  <p>
    <strong>Title:</strong>
    <%= post.title %>
  </p>

  <p>
    <strong>Body:</strong>
    <%= post.body %>
  </p>

</div>

When we click the “Edit” link from the index view, we load the corresponding turbo-frame from the edit view. When the form is submitted, the #update action redirects to the show view, which also contains a corresponding turbo-frame.

# app/views/edit.html.erb

<%= turbo_frame_tag dom_id(@post) do %>
  <%= render "form", post: @post %>
  <%= link_to "Cancel", :back %>
<% end %>

def update
  if @post.update(post_params)
    redirect_to post_url(@post), notice: "Post was successfully updated."
  else
    render :edit, status: :unprocessable_entity
  end
end

# app/views/posts/show.html.erb

<%= turbo_frame_tag dom_id(@post) do %>
  <%= render @post %>
  <%= link_to "Edit", edit_post_path(@post) %>
<% end %>

The key here is that the index and show views are both using the same _post partial. This makes for a seamless experience. The only “gotcha” is that this also means we’ve inadvertently enabled inline editing on the show page too.

However, this is a contrived example and does not reflect a real-world design. It’s common to render content differently when viewed in different contexts.

Let’s explore that next.

The Problem

Let’s update our _post partial and show view so that we see a teaser of the post on the index page, and the full post on the show page.

--- a/app/views/posts/_post.html.erb
+++ b/app/views/posts/_post.html.erb
@@ -1,12 +1,12 @@
-<div>
-  <p>
-    <strong>Title:</strong>
-    <%= post.title %>
-  </p>
+<article>
+  <h2><%= post.title %></h2>

   <p>
-    <strong>Body:</strong>
-    <%= post.body %>
+    <%= post.body.truncate(20) %>
   </p>

-</div>
+  <td>
+    <%= link_to "Edit", edit_post_path(post) %>
+    <%= link_to "Show this post", post, data: { turbo_frame: "_top" } %>
+  </td>
+</article>

--- a/app/views/posts/index.html.erb
+++ b/app/views/posts/index.html.erb
@@ -8,11 +8,7 @@
   <% @posts.each do |post| %>
     <%= turbo_frame_tag dom_id(post) do %>
       <%= render post %>
-      <%= link_to "Edit", edit_post_path(post) %>
     <% end %>
-    <p>
-      <%= link_to "Show this post", post %>
-    </p>
   <% end %>
 </div>

--- a/app/views/posts/show.html.erb
+++ b/app/views/posts/show.html.erb
@@ -1,7 +1,10 @@
 <p style="color: green"><%= notice %></p>

 <%= turbo_frame_tag dom_id(@post) do %>
-  <%= render @post %>
+  <h1><%= @post.title %></h1>
+  <p>
+    <%= @post.body %>
+  </p>
   <%= link_to "Edit", edit_post_path(@post) %>
 <% end %>

Now that we’re no longer sharing the same markup between the index view and the show view, we end up rendering the markup for the show view when we edit a post from the index view. Instead of rendering a teaser, we render the whole post.

However, this is not an issue when editing from the edit page, since we expect to see the whole post after making an edit.

A Simple Solution

Here’s where we need introduce the concept of conditionally rendering a Turbo Frame.

What we want to do is render the simple _post partial when a request is made from the index view. Otherwise, if the request is made from the edit view, we want to render the show view.

Fortunately, this can be easily solved with redirect_back_or_to.

Redirects the browser to the page that issued the request (the referrer) if possible, otherwise redirects to the provided default fallback location.

--- a/app/controllers/posts_controller.rb
+++ b/app/controllers/posts_controller.rb
@@ -33,7 +33,7 @@ class PostsController < ApplicationController
   # PATCH/PUT /posts/1 or /posts/1.json
   def update
     if @post.update(post_params)
-      redirect_to post_url(@post), notice: "Post was successfully updated."
+      redirect_back_or_to post_url(@post), notice: "Post was successfully updated."
     else
       render :edit, status: :unprocessable_entity
     end

In this case, when we edit a post from the index view, it will respond with index which already has a turbo-frame rendering the _post partial. The same concept applies for when editing a post from the edit view.

A More Complex Example

Our current implementation only works because there’s a turbo-frame on the index, show and edit views. What if we didn’t have that luxury? For example, what if we didn’t want to inline edit on the show page?

We can’t use redirect_back_or_to because we want to redirect to the show view when making an edit on the edit view, but still maintain inline editing on the index view.

Fortunately, we can leverage variants in concert with parameters to conditionally render our Turbo Frames based on specific context.

First, we can update our _post partial by having it link to the edit view, but with a query string of ?variant=inline.

--- a/app/views/posts/_post.html.erb
+++ b/app/views/posts/_post.html.erb
@@ -6,7 +6,7 @@
   </p>

   <td>
-    <%= link_to "Edit", edit_post_path(post) %>
+    <%= link_to "Edit", edit_post_path(post, variant: :inline) %>
     <%= link_to "Show this post", post, data: { turbo_frame: "_top" } %>
   </td>
 </article>

This means that when the request is made, we’ll have the additional context about how we want to render this response.

Now that we’ve encoded the context into the URL, we need to do something with it. We can start by first creating a new variant for the edit view that will include the turbo-frame.

# app/views/posts/edit.html+inline.erb

<% content_for :title, "Editing post" %>

<h1>Editing post</h1>

<%= turbo_frame_tag dom_id(@post) do %>
  <%= render "form", post: @post %>
  <%= link_to "Cancel", :back %>
<% end %>

Since we’re loading the form on this page, we can conditionally set a hidden field to capture this value and pass it over to the #update action so it is informed of the context as well.

--- a/app/views/posts/_form.html.erb
+++ b/app/views/posts/_form.html.erb
@@ -21,6 +21,10 @@
     <%= form.text_area :body %>
   </div>

+  <% if params[:variant] == "inline" %>
+    <%= hidden_field_tag :variant, "inline", readonly: true %>
+  <% end %>
+
   <div>
     <%= form.submit %>
   </div>

Now that we have a variant responsible for including the turbo-frame in a variant, we can remove it from the base edit view.

--- a/app/views/posts/edit.html.erb
+++ b/app/views/posts/edit.html.erb
@@ -2,11 +2,7 @@

 <h1>Editing post</h1>

-
-<%= turbo_frame_tag dom_id(@post) do %>
-  <%= render "form", post: @post %>
-  <%= link_to "Cancel", :back %>
-<% end %>
+<%= render "form", post: @post %>

 <br>

Now we just need to apply the same changes to the show views so that the update action can conditionally render the appropriate variant based on the query parameter.

Similar to the above, we can create a variant for the show view that will contain a turbo-frame.

# app/views/posts/show.html+inline.erb

<%= turbo_frame_tag dom_id(@post) do %>
  <%= render @post %>
<% end %>

This means we can remove it from the base show view.

--- a/app/views/posts/show.html.erb
+++ b/app/views/posts/show.html.erb
@@ -1,12 +1,10 @@
 <p style="color: green"><%= notice %></p>

-<%= turbo_frame_tag dom_id(@post) do %>
-  <h1><%= @post.title %></h1>
-  <p>
-    <%= @post.body %>
-  </p>
-  <%= link_to "Edit", edit_post_path(@post) %>
-<% end %>
+<h1><%= @post.title %></h1>
+<p>
+  <%= @post.body %>
+</p>
+<%= link_to "Edit", edit_post_path(@post) %>

 <div>
   <%= link_to "Back to posts", posts_path %>

Now that we’ve modified the views, we need to update our controller to conditionally chose the correct variant based on the parameters.

--- a/app/controllers/posts_controller.rb
+++ b/app/controllers/posts_controller.rb
@@ -1,5 +1,6 @@
 class PostsController < ApplicationController
   before_action :set_post, only: %i[ show edit update destroy ]
+  before_action :set_variant, only: %i[ show edit update ]

   # GET /posts or /posts.json
   def index
@@ -8,6 +9,7 @@ class PostsController < ApplicationController

   # GET /posts/1 or /posts/1.json
   def show
+    request.variant = @variant
   end

   # GET /posts/new
@@ -17,6 +19,7 @@ class PostsController < ApplicationController

   # GET /posts/1/edit
   def edit
+    request.variant = @variant
   end

   # POST /posts or /posts.json
@@ -33,7 +36,7 @@ class PostsController < ApplicationController
   # PATCH/PUT /posts/1 or /posts/1.json
   def update
     if @post.update(post_params)
-      redirect_back_or_to post_url(@post), notice: "Post was successfully updated."
+      redirect_to post_url(@post, variant: @variant), notice: "Post was successfully updated."
     else
       render :edit, status: :unprocessable_entity
     end
@@ -56,4 +59,8 @@ class PostsController < ApplicationController
     def post_params
       params.require(:post).permit(:title, :body)
     end
+
+    def set_variant
+      @variant ||= :inline if params[:variant] == "inline"
+    end
 end

With this change in place, making edits on the index view returns the teaser content.

This change also means making edits from the edit page no longer happen inline, as made evident by the presence of the flash message.

Wrapping Up

Turbo Frames require a new mental model when it comes to managing the state of a page. That, plus that fact that it’s a relatively new technology means that we’re still exploring solutions to common problems as a community.

In this case, Turbo does not offer an off-the-shelf solution to conditionally rendering Frames, but Rails does. I hope that moving forward, this post will serve as guide when others are faced with the same problem.