Skip to content

Rate Limiting

David Ciulla edited this page Nov 7, 2026 · 1 revision

Rate Limiting

Laravex provides rate limiting through the throttle middleware alias and named limiters registered with Laravex.Http.RateLimiter. Named limiters are defined once and referenced by name in route or middleware group definitions.


Named Limiters

Register a named limiter anywhere before your routes are matched — typically in a Service-Providers or in bootstrap/app.ex:

# Named limiter with a fixed rate
Laravex.Http.RateLimiter.for("api", fn _request ->
  [max: 60, decay: 1]
end)

# Named limiter that varies by user
Laravex.Http.RateLimiter.for("uploads", fn request ->
  if request.user && request.user.role == "premium" do
    [max: 1000, decay: 1]
  else
    [max: 100, decay: 1]
  end
end)

The callback receives the current %Laravex.Http.Request{} struct and must return a keyword list with:

Key Type Description
:max integer Maximum number of requests allowed within the :decay window
:decay integer Window duration in minutes

If no limiter is registered for a given name, the system defaults to [max: 60, decay: 1].


Throttle Middleware

Apply rate limiting with the throttle middleware alias. It resolves to Laravex.Http.Middleware.ThrottleRequests.

Inline Limits

Router.middleware("throttle:60,1", fn ->
  # 60 requests per 1 minute
  Router.get("/api/posts", &App.Http.Controllers.PostController.index/1)
end)

# shorthand: throttle:{max},{decay}
"throttle:100,1"   # 100 per minute
"throttle:30"      # 30 per minute (decay defaults to 1)
"throttle"         # 60 per minute (global default)

Named Limiter Reference

# Applies the "api" named limiter
Router.middleware("throttle:api", fn ->
  Router.get("/api/resource", &handler/1)
end)

In the API Middleware Group

The default api middleware group already includes throttling with the "api" named limiter:

# lib/laravex/http/middleware.ex (api group)
{Laravex.Http.Middleware.ThrottleRequests, [limiter: "api"]}

This applies whatever rate you registered for "api" to all routes in the api group.


Resolving Limits

You can resolve the computed limit for a given limiter name programmatically:

# Without a request (limiter callbacks that accept 0 arguments)
Laravex.Http.RateLimiter.resolve("api")
# => [max: 60, decay: 1]

# With a request (limiter callbacks that accept 1 argument)
Laravex.Http.RateLimiter.resolve("uploads", request)
# => [max: 1000, decay: 1]

Looking Up a Registered Limiter

# Returns the registered callback function (or nil if not found)
Laravex.Http.RateLimiter.get("api")

How Rate Limiting Works

The ThrottleRequests middleware:

  1. Resolves the limiter (by name or inline max/decay values).
  2. Builds a cache key from the limiter name and the request's remote IP (or authenticated user ID).
  3. Checks the Cache for the current request count.
  4. If the count exceeds max, returns a 429 Too Many Requests response with a Retry-After header.
  5. Otherwise, increments the count (with a TTL of decay minutes) and continues.

Example: Per-User Limits

Laravex.Http.RateLimiter.for("orders", fn request ->
  case request.user do
    nil  -> [max: 10, decay: 1]
    user -> [max: user.daily_order_limit, decay: 60]
  end
end)
Router.middleware("throttle:orders", fn ->
  Router.post("/orders", &App.Http.Controllers.OrderController.store/1)
end)

See Also

  • Middleware — throttle alias resolution
  • Cache — rate limiter state is stored in the cache
  • Routing — attaching middleware to route groups

Clone this wiki locally