congestion.middleware — listora/ring-congestion 0.1.3

add-retry-after-header clj

(add-retry-after-header rsp retry-after)

Add a Retry-After header to the provided response. The retry-after argument is expected to be a clj-time/Joda DateTime.

ip-rate-limit clj

(ip-rate-limit id quota ttl)

Instantiate an IP-based rate-limit where quota number of requests are allowed per IP-address within a timespan of ttl. The id argument is used to differentiate multiple instances of the same limit in the storage (eg two IP-based limits on two different routes that should have independent counters).

Eg. (ip-rate-limit :my-limit 1000 (t/hours 1)) allows 1000 requests per hour per IP-address.

Note: make sure that the incoming ring request has the correct :remote-addr field. Eg Heroku uses a reverse proxy infront of apps which means that by default the :remote-addr in a ring request is that off the reverse proxy. See: https://devcenter.heroku.com/articles/http-routing for more details.

too-many-requests-response clj

(too-many-requests-response retry-after)

(too-many-requests-response rsp retry-after)

Generate a 429 (Too many requests) ring response.

The response will include the X-RateLimit-Limit, X-RateLimit-Remaining and Retry-After headers and either a default response (cf. congestion.responses/default-response) or the provided ring response.

Note: if the provided response specifies a :status field, this will not be overwritten.

wrap-rate-limit clj

(wrap-rate-limit handler {:keys [storage limit response-builder]})

Apply a rate-limit before calling handler.

Eg (wrap-rate-limit app {:storage ... :limit ... :response-builder ...})

:storage is an instance of congestion.storage/Storage and specifies the storage backend to use for storing rate-limit counter between requests (cf. congestion.storage and congestion.redis-storage).

:limit is an instance of congestion.limits/RateLimit and specifies the semantics of the limit that is being applied to handler.

An optional :response-builder can be provided to override the default 429 response. The builder must be a (fn [quota retry-after] ...) function where quota is the number of requests allowed by the limit and retry-after is a clj-time/Joda DateTime specifying when the rate-limit will be reset. The too-many-requests-response fn can be used as a helper in forming a proper 429 response.

wrap-stacking-rate-limit clj

(wrap-stacking-rate-limit handler {:keys [storage limit response-builder]})

Apply a rate-limit before calling handler.

This middleware is like wrap-rate-limit with the exception that multiple instances of this middleware can be stacked together to apply different rate-limis at different points in the ring request handling. Eg an IP-based limit, allowing 100req/h, can be applied before authentication, and a user-based limit, allowing 5000req/h, after authentication.

The earlier middlewares in the ring middleware stack, eg the ip-based limit in the above example, will check whether a rate-limit has already been applied to the ring response and not increment the limit counters for those responses. In the above example the IP-based limit will check if the user-based limit has already been applied to the request.

Note: the downside of incrementing the limit counter only after the request has been handled by handler is that there is a longer period during which concurrent requests would still be allowed. Whereas if the limit counter is incremented immediately, the period during which concurrent requests might pass through with the same counter value is smaller. So wrap-rate-limit should be preferred unless it's necessary to stack rate-limits.