#Complex Rate Limiting Policy

You can use the Complex Rate Limiting policy to limit the number of requests based on complex counters, based on details of the request or the response

#Configuration

The configuration shows how to configure the policy in the 'policies.json' document.

{
  "name": "my-complex-rate-limit-inbound-policy",
  "policyType": "complex-rate-limit-inbound",
  "handler": {
    "export": "ComplexRateLimitInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "limits": {
        "apples": 2,
        "bananas": 3
      },
      "rateLimitBy": "ip",
      "timeWindowMinutes": 0.6
    }
  }
}

#Policy Configuration

• name <string> - The name of your policy instance. This is used as a reference in your routes.
• policyType <string> - The identifier of the policy. This is used by the Zuplo UI. Value should be complex-rate-limit-inbound.
• handler.export <string> - The name of the exported type. Value should be ComplexRateLimitInboundPolicy.
• handler.module <string> - The module containing the policy. Value should be $import(@zuplo/runtime).
• handler.options <object> - The options for this policy. See Policy Options below.

#Policy Options

The options for this policy are specified below. All properties are optional unless specifically marked as required.

• rateLimitBy (required) <string> - The identifying element of the request that enforces distinct rate limits. For example, you can limit by user, ip, function or all - function allows you to specify a simple function to create a string identifier to create a rate-limit group. Allowed values are user, ip, function, all. Defaults to "user".
• limits (required) <object> - A dictionary (string: number) of limits to be enforced across custom counters for this policy.
• timeWindowMinutes (required) <integer> - The time window in which the requests are rate-limited. The count restarts after each window expires. Defaults to 60.
• identifier <object> - The function that returns dynamic configuration data. Used only with rateLimitBy=function.
  • export (required) <string> - used only with rateLimitBy=function. Specifies the export to load your custom bucket function, e.g. default, rateLimitIdentifier. Defaults to "".
  • module (required) <string> - Specifies the module to load your custom bucket function, in the format $import(./modules/my-module). Defaults to "".
• headerMode <string> - Adds the retry-after header. Allowed values are none, retry-after. Defaults to "retry-after".
• throwOnFailure <boolean> - If true, the policy will throw an error in the event there is a problem connecting to the rate limit service. Defaults to false.
• mode <string> - The mode of the policy. If set to async, the policy will check if the request is over the rate limit without blocking. This can result in some requests allowed over the rate limit. Allowed values are strict, async. Defaults to "strict".

#Using the Policy

This policy allows setting multiple limits that can optionally be overridden them programmatically.

#Set Increments Programmatically

Override the increments for limits in the current request.

If your policy is has a limit set as follows:

"limits": {
  "compute": 10
}

You can use this function to override the increment of the compute unites consumed on a request by calling setIncrements(context, { compute: 5 }) on a custom policy. This can be useful if you want to dynamically change the increment of a limit based on data in the response (say a header).

Read more about how policies work