refrakt/rate_limit

Rate limiting middleware using a sliding window counter.

Experimental. This module is lightly used and may change or move to its own package; see https://github.com/raskell-io/refrakt/issues/28.

A single OTP actor keeps the request timestamps per client. Clients whose requests have all left their window are dropped by a periodic cleanup, so memory stays bounded by the number of recently active clients.

Usage

import refrakt/rate_limit

// Start the rate limiter (once at app startup)
let assert Ok(limiter) = rate_limit.start()

fn middleware(req, next) {
  use <- rate_limit.check(
    req,
    limiter,
    max: 100,          // max requests
    window_ms: 60_000, // per minute
    key: rate_limit.by_forwarded_for(trusted_proxies: 1),
  )
  next(req)
}

Choosing the client key

Requests are counted per key, so the key must be something a client cannot change at will. Wisp does not expose the socket peer address, so you say where the client address comes from:

• Behind a reverse proxy (nginx, Caddy, a load balancer), use by_forwarded_for(trusted_proxies: n) where n is the number of proxies in front of the app. Each proxy appends the address it saw to X-Forwarded-For, so the client is the nth entry from the right. Anything further left was sent by the client and is ignored. Set n correctly: too high and clients can pick their own key, too low and every client shares the proxy’s key.
• Behind a proxy that sets a single header it always overwrites (CF-Connecting-IP on Cloudflare, Fly-Client-IP on Fly.io, X-Real-IP with nginx’s proxy_set_header), use by_header("cf-connecting-ip"). Only do this when every request passes through that proxy; otherwise clients can send the header themselves.
• Directly exposed (no proxy), forwarding headers come from the client and must not be trusted. Read the peer address from Mist before handing the request to Wisp and pass a key function that returns it:

// In main()
let handler = fn(req: request.Request(mist.Connection)) {
  let client_ip = case mist.get_connection_info(req.body) {
    Ok(info) -> mist.ip_address_to_string(info.ip_address)
    Error(_) -> "unknown"
  }
  wisp_mist.handler(
    router.handle_request(_, ctx, client_ip),
    cfg.secret_key_base,
  )(req)
}

// In the router
use <- rate_limit.check(req, limiter, max: 100, window_ms: 60_000, key: fn(_) {
  client_ip
})

Any fn(Request) -> String works as a key, so you can also limit per user or per API token.

pub opaque type RateLimitMessage

pub type RateLimiter =
  process.Subject(RateLimitMessage)

pub fn by_forwarded_for(
  trusted_proxies trusted_proxies: Int,
) -> fn(request.Request(wisp.Connection)) -> String

pub fn by_header(
  name: String,
) -> fn(request.Request(wisp.Connection)) -> String

pub fn check(
  req: request.Request(wisp.Connection),
  limiter: process.Subject(RateLimitMessage),
  max max: Int,
  window_ms window_ms: Int,
  key key: fn(request.Request(wisp.Connection)) -> String,
  next next: fn() -> response.Response(wisp.Body),
) -> response.Response(wisp.Body)

pub fn start() -> Result(
  process.Subject(RateLimitMessage),
  actor.StartError,
)

pub fn start_with_cleanup_interval(
  every interval_ms: Int,
) -> Result(process.Subject(RateLimitMessage), actor.StartError)

pub fn tracked_keys(
  limiter: process.Subject(RateLimitMessage),
) -> Int