skip to content

Per-Action Throttling

The rate_limit macro caps how often a client may hit an action, counting in the cache store and answering 429 by default. Interviewers ask about the shared store, the key and tests that never trip.

part ofRuby on Railsread it →
on this pageshow

explore

questions

5

In a Rails 8.1 controller, what does rate_limit to: 10, within: 3.minutes, only: :create do, and what does a client get when it trips?

level: juniorimportance: must knowfreq 45%

answer

  1. a before_action with a counter
  2. keyed by request.remote_ip
  3. counts in the controller's cache store
  4. 11th request inside the window
  5. TooManyRequests rescued to 429

basics

~20 s

rate_limit adds a before_action that increments a per-IP counter in the cache store on each create request; the eleventh request within three minutes raises ActionController::TooManyRequests, which Action Dispatch turns into a 429 Too Many Requests response.

solid answer

~40 s

`rate_limit` is a class macro that registers a `before_action`, so `only:` and `except:` work as usual. On each matching request it computes an identity with `by:`, by default `request.remote_ip`, builds the key `rate-limit:<controller_path>:<by>`, and calls `increment` on the store with `expires_in: within`. The store defaults to the controller's cache store, normally `config.cache_store`. When the returned count exceeds `to:`, it runs `with:`; in Rails 8.1 the default raises `ActionController::TooManyRequests`, which Action Dispatch maps to **429 Too Many Requests**. So requests 1 to 10 in the window reach the action and the eleventh does not. The generated authentication controllers pass `with:` to redirect back to the form with "Try again later." instead. Exceeding a limit also publishes a `rate_limit.action_controller` notification.

code

ruby · 9 lines
ruby
class QuotesController < ApplicationController
  # Fare quotes: 30 per minute per client IP, then 429
  rate_limit to: 30, within: 1.minute, only: :create

  def create
    @quote = FareQuote.for(pickup: params[:pickup], dropoff: params[:dropoff])
    render json: @quote
  end
end

go deeper

for a junior

Know that rate_limit to:, within: and only: cap requests per client IP for chosen actions, and that the default refusal is a 429.

for a middle

Explain the before_action, the cache key built from scope and by, increment with expires_in, and the 8.1 TooManyRequests exception and its 429 mapping.

for a senior

Choose the refusal behaviour per endpoint: a redirect with a flash for forms, JSON for APIs, and confirm production's store is shared before trusting the number.

for a principal

Decide which endpoints need per-action limits at all, and how limits are tuned and monitored through the rate_limit notification.

## The macro Rails' **`rate_limit`** caps how often one client may hit some actions of a controller. It lives in `ActionController::RateLimiting`, which both `ActionController::Base` and `ActionController::API` include. A ride-hailing app's sign-in controller uses exactly the line the generator writes: ```ruby class SessionsController < ApplicationController rate_limit to: 10, within: 3.minutes, only: :create end ``` Under the hood the macro calls `before_action` with a lambda and passes `only:` / `except:` through, so it composes with the controller's other callbacks like any filter. ## What happens on each request For every `create` request the filter: 1. Computes the client identity with `by:`. The default is `-> { request.remote_ip }`. 2. Builds the cache key `rate-limit:<scope>:<name>:<by>`, dropping `name` when it is nil. The scope defaults to `controller_path`, here `sessions`, so the key looks like `rate-limit:sessions:203.0.113.7`. 3. Calls `store.increment(key, 1, expires_in: within)`. The store returns the new count, starting a counter at 1 when none exists. 4. If the count is greater than `to:`, it calls `with:` inside a `rate_limit.action_controller` notification. Requests 1 to 10 within the window pass. The eleventh is refused, and so is every later one until the counter expires. ## What the client sees In Rails 8.1 the default `with:` is `-> { raise TooManyRequests }`. The exception is `ActionController::TooManyRequests`, and Action Dispatch's exception wrapper maps it to `:too_many_requests`: | Request | Response in production | |---|---| | HTML | status 429; a new app has no `public/429.html`, so the body is empty | | JSON | status 429 with `{"status":429,"error":"Too Many Requests"}` | | any, with `rescue_from ActionController::TooManyRequests` | whatever your handler renders | Because the exception is a mapped "rescue response", it is not treated as an unexpected error. The 8.1 changelog lists raising as a change; it means you can handle the limit centrally with `rescue_from`. ## Custom responses `with:` takes a lambda or, since 8.1, a method name, evaluated in the controller: ```ruby rate_limit to: 10, within: 3.minutes, only: :create, with: -> { redirect_to new_session_path, alert: "Try again later." } ``` That is what the authentication generator writes into both `SessionsController` and `PasswordsController`. For an API, `with: -> { render json: { error: "slow down" }, status: :too_many_requests }` keeps the 429 but controls the body. A `with:` that neither renders, redirects nor raises lets the action run, so make sure it halts. ## Where the counter lives The default `store:` is the controller's `cache_store`, which is `config.action_controller.cache_store` or, if unset, `Rails.cache`. That has consequences: - In a new app's production environment this is Solid Cache, a database-backed store shared by every server. - In development it is `:memory_store`, private to each process; the count works even when `bin/rails dev:cache` is off, because rate limiting calls the store directly. - In the generated test environment it is `:null_store`, whose `increment` returns `nil`, so the limit never trips. ## Mistakes that weaken it - **No `only:`**: the limit then counts every action of the controller, including the `new` form, so a rider who reloads the sign-in page burns attempts. - **Declared below expensive filters**: callbacks run in declaration order, so a limit declared after a filter that loads records or calls another service lets refused requests pay for that work first. - **A `with:` that does not halt**: logging and returning lets the action run anyway. - **Trusting the number without checking the store**: in development each Puma worker has its own memory store, so local experiments can disagree with production. ## Observing it Each refusal publishes `rate_limit.action_controller` with `count`, `to`, `within`, `by`, `name`, `scope` and `cache_key`. Subscribing to it is the cheapest way to see who is being throttled before users complain.

  • With rate_limit to: 10, which request is the first one refused?
    The eleventh. The filter increments first and compares afterwards: the count returned for the eleventh request is 11, and `with:` runs only when the count is greater than `to:`. Requests 1 to 10 within the window reach the action.
  • How would you render a JSON error body instead of the default 429 page?
    Either pass `with: -> { render json: { error: "Too many quote requests" }, status: :too_many_requests }` on that limit, or keep the default and add `rescue_from ActionController::TooManyRequests` in a base API controller so every limit answers the same way. The rescue_from route works in 8.1 because the default now raises.

  • rate_limit is Rack middleware that runs before routing
  • The tenth request within the window is the one refused
  • The default response in 8.1 is a 503 Service Unavailable
  • Counts live in the session, so each browser has its own limit
  • rate_limit is only available in ActionController::Base

Assumes Rails 8.1: rate_limit's default with: raises ActionController::TooManyRequests (rescued to 429), and with:/by: accept method names, both changes in 8.1.0.

open as a page

In Rails 8.1's rate_limit macro, how do the by:, name: and scope: options change which requests share a counter?

level: middleimportance: should knowfreq 30%

basics

~20 s

Each option fills one part of the cache key rate-limit:<scope>:<name>:<by>: by: chooses the identity counted, name: lets one controller keep several limits apart, and scope:, new in 8.1, replaces controller_path so different controllers can share one counter.

open as a page

Why does a rate_limit never trip in a generated Rails 8.1 test suite, and how do you test the limit anyway?

level: middleimportance: should knowfreq 30%

basics

~20 s

The generated test environment sets config.cache_store = :null_store, whose increment returns nil, so the count never exceeds to:; test it by giving the limit a real store, such as a memory store in test, and clearing it between tests.

open as a page

A Rails 8.1 ride-hailing app runs on several servers with Puma workers behind a load balancer; what must its rate_limit store and client identity be for the limit to hold?

level: seniorimportance: should knowfreq 30%

basics

~20 s

The counter needs a store every process shares, such as the generated Solid Cache store, and by: must name the real client: request.remote_ip does so only when every proxy hop is trusted, so key signed-in endpoints on the account.

open as a page

In a Rails 8.1 app, what can the rate_limit macro not protect that a Rack middleware limiter can, and what does each layer know about the request?

level: seniorimportance: nice to knowfreq 20%

basics

~20 s

rate_limit is a before_action, so it guards only actions that declare it, after middleware, routing and controller setup; a Rack middleware limiter sees every request earlier and more cheaply, but without the controller's knowledge of the user.

open as a page