Rate Limiting

# Endpoint Rate Limiting

It is possible to rate limit individual endpoints based on the presence of an HTTP header in the incoming request like below:

public override void Configure()
{
    Post("/order/create");
    Throttle(
        hitLimit: 120,
        durationSeconds: 60,
        headerName: "X-Client-Id" // this is optional
    );
}

# Hit Limit & Window Duration

The above for example will only allow 120 requests from each unique client (identified by the header value) within a 60 second window.

If 121 requests are made by a client within 60 seconds, a 429 too many requests response will be automatically sent for the 121st request.

The counter is reset every 60 seconds and the client is able to make another 120 requests in the next 60 seconds, and so on.

# Header Name

The header name can be set to anything you prefer.

If it's not specified, the library will try to read the value of X-Forwarded-For header from the incoming request.

If that's unsuccessful, it will try to read the HttpContext.Connection.RemoteIpAddress in order to uniquely identify the client making the request.

If all attempts are unsuccessful, a 403 Forbidden response will be sent.

# Header Reliability

Both X-Forwarded-For and HttpContext.Connection.RemoteIpAddress could be unreliable for uniquely identifying clients if they are behind a NAT, reverse proxy, or anonymizing vpn/proxy etc.

Therefore, the recommended strategy is to generate a unique identifier such as a GUID in your client application and use that as the header value in each request for the entirety of the session/app cycle.

# Limitations & Warnings

• Should not be used for security or DDOS protection. A malicious client can easily set a unique header value per request in order to circumvent the throttling.

• Should be aware of the slight performance degradation due to resource allocation and amount of work being done.

• Only per endpoint limits can be set. No global limits can be enforced. This won't ever be added due to performance implications.

• Consider a rate limiting solution that is out of process at the gateway level for better performance/security.

public override void Configure()
{
    ...
    Options(x => x.RequireRateLimiting("limiterPolicy"));
}