> For the complete documentation index, see [llms.txt](https://docs.digitalapi.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalapi.ai/api-gateway/plugin-reference/plugins-traffic.md).
# Traffic plugins
Plugins in this category shape how traffic moves through the gateway: rate limits, concurrency caps, circuit breakers, request buffering, IP allow- and deny-lists. Use them to protect upstreams from overload and to enforce per-consumer or per-route quotas. The catalogue ships 12 Traffic plugins.
{% hint style="info" %}
**In this category:** [`api-breaker`](#api-breaker), [`client-control`](#client-control), [`limit-conn`](#limit-conn), [`limit-count`](#limit-count), [`limit-req`](#limit-req), [`proxy-cache`](#proxy-cache), [`proxy-control`](#proxy-control), [`proxy-mirror`](#proxy-mirror), [`request-id`](#request-id), [`request-validation`](#request-validation), [`traffic-split`](#traffic-split), [`workflow`](#workflow)
{% endhint %}
### `api-breaker`
The `api-breaker` Plugin implements circuit breaker functionality to protect Upstream services.
{% hint style="info" %}
**Priority** `1005` · **Category** Traffic · **Required** `break_response_code`
{% endhint %}
Configuration and details
:::note
Whenever the Upstream service responds with a status code from the configured `unhealthy.http_statuses` list for the configured `unhealthy.failures` number of times, the Upstream service will be considered unhealthy.
The request is then retried in 2, 4, 8, 16 ... seconds until the `max_breaker_sec`.
In an unhealthy state, if the Upstream service responds with a status code from the configured list `healthy.http_statuses` for `healthy.successes` times, the service is considered healthy again.
:::
| Name | Type | Required | Default | Valid values | Description |
| ------------------------ | --------------- | -------- | ------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| break\_response\_code | integer | True | | \[200, ..., 599] | HTTP error code to return when Upstream is unhealthy. |
| break\_response\_body | string | False | | | Body of the response message to return when Upstream is unhealthy. |
| break\_response\_headers | array\[object] | False | | \[{"key":"header\_name","value":"can contain Nginx $var"}] | Headers of the response message to return when Upstream is unhealthy. Can only be configured when the `break_response_body` attribute is configured. The values can contain AILIX variables. For example, we can use `{"key":"X-Client-Addr","value":"$remote_addr:$remote_port"}`. |
| max\_breaker\_sec | integer | False | 300 | >=3 | Maximum time in seconds for circuit breaking. |
| unhealthy.http\_statuses | array\[integer] | False | \[500] | \[500, ..., 599] | Status codes of Upstream to be considered unhealthy. |
| unhealthy.failures | integer | False | 3 | >=1 | Number of failures within a certain period of time for the Upstream service to be considered unhealthy. |
| healthy.http\_statuses | array\[integer] | False | \[200] | \[200, ..., 499] | Status codes of Upstream to be considered healthy. |
| healthy.successes | integer | False | 3 | >=1 | Number of consecutive healthy requests for the Upstream service to be considered healthy. |
### `client-control`
The `client-control` Plugin can be used to dynamically control the behavior of NGINX to handle a client request, by setting the max size of the request body.
{% hint style="info" %}
**Priority** `22000` · **Category** Traffic
{% endhint %}
Configuration and details
:::info IMPORTANT
This Plugin requires AILIX to run on AILIX-Runtime. See ailix-build-tools for more info.
:::
| Name | Type | Required | Valid values | Description |
| --------------- | ------- | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| max\_body\_size | integer | False | \[0,...] | Set the maximum limit for the client request body and dynamically adjust the size of [`client_max_body_size`](https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size), measured in bytes. If you set the `max_body_size` to 0, then the size of the client's request body will not be checked. |
### `limit-conn`
The `limit-conn` Plugin limits the rate of requests by the number of concurrent connections. Requests exceeding the threshold will be delayed or rejected based on the configuration, ensuring controlled resource usage and preventing overload.
{% hint style="info" %}
**Priority** `1003` · **Category** Traffic · **Required** `conn`, `burst`, `default_conn_delay`, `key`
{% endhint %}
Configuration and details
| Name | Type | Required | Default | Valid values | Description |
| --------------------------- | -------------- | -------- | ------------ | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| conn | integer | True | | > 0 | The maximum number of concurrent requests allowed. Requests exceeding the configured limit and below `conn + burst` will be delayed. |
| burst | integer | True | | >= 0 | The number of excessive concurrent requests allowed to be delayed per second. Requests exceeding the limit will be rejected immediately. |
| default\_conn\_delay | number | True | | > 0 | Processing latency allowed in seconds for concurrent requests exceeding `conn + burst`, which can be dynamically adjusted based on `only_use_default_delay` setting. |
| only\_use\_default\_delay | boolean | False | false | | If false, delay requests proportionally based on how much they exceed the `conn` limit. The delay grows larger as congestion increases. For instance, with `conn` being `5`, `burst` being `3`, and `default_conn_delay` being `1`, 6 concurrent requests would result in a 1-second delay, 7 requests a 2-second delay, 8 requests a 3-second delay, and so on, until the total limit of `conn + burst` is reached, beyond which requests are rejected. If true, use `default_conn_delay` to delay all excessive requests within the `burst` range. Requests beyond `conn + burst` are rejected immediately. For instance, with `conn` being `5`, `burst` being `3`, and `default_conn_delay` being `1`, 6, 7, or 8 concurrent requests are all delayed by exactly 1 second each. |
| key\_type | string | False | var | \["var","var\_combination"] | The type of key. If the `key_type` is `var`, the `key` is interpreted a variable. If the `key_type` is `var_combination`, the `key` is interpreted as a combination of variables. |
| key | string | False | remote\_addr | | The key to count requests by. If the `key_type` is `var`, the `key` is interpreted a variable. The variable does not need to be prefixed by a dollar sign (`$`). If the `key_type` is `var_combination`, the `key` is interpreted as a combination of variables. All variables should be prefixed by dollar signs (`$`). For example, to configure the `key` to use a combination of two request headers `custom-a` and `custom-b`, the `key` should be configured as `$http_custom_a $http_custom_b`. |
| key\_ttl | integer | False | 3600 | | The TTL of the Redis key in seconds. Used when `policy` is `redis` or `redis-cluster`. |
| rejected\_code | integer | False | 503 | \[200,...,599] | The HTTP status code returned when a request is rejected for exceeding the threshold. |
| rejected\_msg | string | False | | non-empty | The response body returned when a request is rejected for exceeding the threshold. |
| allow\_degradation | boolean | False | false | | If true, allow AILIX to continue handling requests without the Plugin when the Plugin or its dependencies become unavailable. |
| policy | string | False | local | \["local","redis","redis-cluster"] | The policy for rate limiting counter. If it is `local`, the counter is stored in memory locally. If it is `redis`, the counter is stored on a Redis instance. If it is `redis-cluster`, the counter is stored in a Redis cluster. |
| redis\_host | string | False | | | The address of the Redis node. Required when `policy` is `redis`. |
| redis\_port | integer | False | 6379 | \[1,...] | The port of the Redis node when `policy` is `redis`. |
| redis\_username | string | False | | | The username for Redis if Redis ACL is used. If you use the legacy authentication method `requirepass`, configure only the `redis_password`. Used when `policy` is `redis`. |
| redis\_password | string | False | | | The password of the Redis node when `policy` is `redis` or `redis-cluster`. |
| redis\_ssl | boolean | False | false | | If true, use SSL to connect to Redis cluster when `policy` is `redis`. |
| redis\_ssl\_verify | boolean | False | false | | If true, verify the server SSL certificate when `policy` is `redis`. |
| redis\_database | integer | False | 0 | >= 0 | The database number in Redis when `policy` is `redis`. |
| redis\_timeout | integer | False | 1000 | \[1,...] | The Redis timeout value in milliseconds when `policy` is `redis` or `redis-cluster`. |
| redis\_keepalive\_timeout | integer | False | 10000 | ≥ 1000 | Keepalive timeout in milliseconds for redis when `policy` is `redis` or `redis-cluster`. |
| redis\_keepalive\_pool | integer | False | 100 | ≥ 1 | Keepalive pool size for redis when `policy` is `redis` or `redis-cluster`. |
| redis\_cluster\_nodes | array\[string] | False | | | The list of the Redis cluster nodes with at least two addresses. Required when policy is redis-cluster. |
| redis\_cluster\_name | string | False | | | The name of the Redis cluster. Required when `policy` is `redis-cluster`. |
| redis\_cluster\_ssl | boolean | False | false | | If true, use SSL to connect to Redis cluster when `policy` is |
| redis\_cluster\_ssl\_verify | boolean | False | false | | If true, verify the server SSL certificate when `policy` is `redis-cluster`. |
### `limit-count`
The `limit-count` plugin uses a fixed window algorithm to limit the rate of requests by the number of requests within a given time interval. Requests exceeding the configured quota will be rejected.
{% hint style="info" %}
**Priority** `1002` · **Category** Traffic · **Required** `count`, `time_window`
{% endhint %}
Configuration and details
You may see the following rate limiting headers in the response:
* `X-RateLimit-Limit`: the total quota
* `X-RateLimit-Remaining`: the remaining quota
* `X-RateLimit-Reset`: number of seconds left for the counter to reset
| Name | Type | Required | Default | Valid values | Description |
| --------------------------- | -------------- | -------- | ------------ | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| count | integer | True | | > 0 | The maximum number of requests allowed within a given time interval. |
| time\_window | integer | True | | > 0 | The time interval corresponding to the rate limiting `count` in seconds. |
| key\_type | string | False | var | \["var","var\_combination","constant"] | The type of key. If the `key_type` is `var`, the `key` is interpreted a variable. If the `key_type` is `var_combination`, the `key` is interpreted as a combination of variables. If the `key_type` is `constant`, the `key` is interpreted as a constant. |
| key | string | False | remote\_addr | | The key to count requests by. If the `key_type` is `var`, the `key` is interpreted a variable. The variable does not need to be prefixed by a dollar sign (`$`). If the `key_type` is `var_combination`, the `key` is interpreted as a combination of variables. All variables should be prefixed by dollar signs (`$`). For example, to configure the `key` to use a combination of two request headers `custom-a` and `custom-b`, the `key` should be configured as `$http_custom_a $http_custom_b`. If the `key_type` is `constant`, the `key` is interpreted as a constant value. |
| rejected\_code | integer | False | 503 | \[200,...,599] | The HTTP status code returned when a request is rejected for exceeding the threshold. |
| rejected\_msg | string | False | | non-empty | The response body returned when a request is rejected for exceeding the threshold. |
| policy | string | False | local | \["local","redis","redis-cluster"] | The policy for rate limiting counter. If it is `local`, the counter is stored in memory locally. If it is `redis`, the counter is stored on a Redis instance. If it is `redis-cluster`, the counter is stored in a Redis cluster. |
| allow\_degradation | boolean | False | false | | If true, allow AILIX to continue handling requests without the plugin when the plugin or its dependencies become unavailable. |
| show\_limit\_quota\_header | boolean | False | true | | If true, include `X-RateLimit-Limit` to show the total quota and `X-RateLimit-Remaining` to show the remaining quota in the response header. |
| group | string | False | | non-empty | The `group` ID for the plugin, such that routes of the same `group` can share the same rate limiting counter. |
| redis\_host | string | False | | | The address of the Redis node. Required when `policy` is `redis`. |
| redis\_port | integer | False | 6379 | \[1,...] | The port of the Redis node when `policy` is `redis`. |
| redis\_username | string | False | | | The username for Redis if Redis ACL is used. If you use the legacy authentication method `requirepass`, configure only the `redis_password`. Used when `policy` is `redis`. |
| redis\_password | string | False | | | The password of the Redis node when `policy` is `redis` or `redis-cluster`. |
| redis\_ssl | boolean | False | false | | If true, use SSL to connect to Redis cluster when `policy` is `redis`. |
| redis\_ssl\_verify | boolean | False | false | | If true, verify the server SSL certificate when `policy` is `redis`. |
| redis\_database | integer | False | 0 | >= 0 | The database number in Redis when `policy` is `redis`. |
| redis\_timeout | integer | False | 1000 | \[1,...] | The Redis timeout value in milliseconds when `policy` is `redis` or `redis-cluster`. |
| redis\_keepalive\_timeout | integer | False | 10000 | ≥ 1000 | Keepalive timeout in milliseconds for redis when `policy` is `redis` or `redis-cluster`. |
| redis\_keepalive\_pool | integer | False | 100 | ≥ 1 | Keepalive pool size for redis when `policy` is `redis` or `redis-cluster`. |
| redis\_cluster\_nodes | array\[string] | False | | | The list of the Redis cluster nodes with at least two addresses. Required when policy is redis-cluster. |
| redis\_cluster\_name | string | False | | | The name of the Redis cluster. Required when `policy` is `redis-cluster`. |
| redis\_cluster\_ssl | boolean | False | false | | If true, use SSL to connect to Redis cluster when `policy` is `redis-cluster`. |
| redis\_cluster\_ssl\_verify | boolean | False | false | | If true, verify the server SSL certificate when `policy` is `redis-cluster`. |
### `limit-req`
The `limit-req` Plugin uses the [leaky bucket](https://en.wikipedia.org/wiki/Leaky_bucket) algorithm to rate limit the number of the requests and allow for throttling.
{% hint style="info" %}
**Priority** `1001` · **Category** Traffic · **Required** `rate`, `burst`, `key`
{% endhint %}
Configuration and details
| Name | Type | Required | Default | Valid values | Description |
| --------------------------- | -------------- | -------- | ------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| rate | integer | True | | > 0 | The maximum number of requests allowed per second. Requests exceeding the rate and below burst will be delayed. |
| burst | integer | True | | >= 0 | The number of requests allowed to be delayed per second for throttling. Requests exceeding the rate and burst will get rejected. |
| key\_type | string | False | var | \["var", "var\_combination"] | The type of key. If the `key_type` is `var`, the `key` is interpreted a variable. If the `key_type` is `var_combination`, the `key` is interpreted as a combination of variables. |
| key | string | True | remote\_addr | | The key to count requests by. If the `key_type` is `var`, the `key` is interpreted a variable. The variable does not need to be prefixed by a dollar sign (`$`). If the `key_type` is `var_combination`, the `key` is interpreted as a combination of variables. All variables should be prefixed by dollar signs (`$`). For example, to configure the `key` to use a combination of two request headers `custom-a` and `custom-b`, the `key` should be configured as `$http_custom_a $http_custom_b`. |
| rejected\_code | integer | False | 503 | \[200,...,599] | The HTTP status code returned when a request is rejected for exceeding the threshold. |
| rejected\_msg | string | False | | non-empty | The response body returned when a request is rejected for exceeding the threshold. |
| nodelay | boolean | False | false | | If true, do not delay requests within the burst threshold. |
| allow\_degradation | boolean | False | false | | If true, allow AILIX to continue handling requests without the Plugin when the Plugin or its dependencies become unavailable. |
| policy | string | False | local | \["local", "redis", "redis-cluster"] | The policy for rate limiting counter. If it is `local`, the counter is stored in memory locally. If it is `redis`, the counter is stored on a Redis instance. If it is `redis-cluster`, the counter is stored in a Redis cluster. |
| redis\_host | string | False | | | The address of the Redis node. Required when `policy` is `redis`. |
| redis\_port | integer | False | 6379 | \[1,...] | The port of the Redis node when `policy` is `redis`. |
| redis\_username | string | False | | | The username for Redis if Redis ACL is used. If you use the legacy authentication method `requirepass`, configure only the `redis_password`. Used when `policy` is `redis`. |
| redis\_password | string | False | | | The password of the Redis node when `policy` is `redis` or `redis-cluster`. |
| redis\_ssl | boolean | False | false | | If true, use SSL to connect to Redis cluster when `policy` is `redis`. |
| redis\_ssl\_verify | boolean | False | false | | If true, verify the server SSL certificate when `policy` is `redis`. |
| redis\_database | integer | False | 0 | >= 0 | The database number in Redis when `policy` is `redis`. |
| redis\_timeout | integer | False | 1000 | \[1,...] | The Redis timeout value in milliseconds when `policy` is `redis` or `redis-cluster`. |
| redis\_keepalive\_timeout | integer | False | 10000 | ≥ 1000 | Keepalive timeout in milliseconds for redis when `policy` is `redis` or `redis-cluster`. |
| redis\_keepalive\_pool | integer | False | 100 | ≥ 1 | Keepalive pool size for redis when `policy` is `redis` or `redis-cluster`. |
| redis\_cluster\_nodes | array\[string] | False | | | The list of the Redis cluster nodes with at least two addresses. Required when policy is redis-cluster. |
| redis\_cluster\_name | string | False | | | The name of the Redis cluster. Required when `policy` is `redis-cluster`. |
| redis\_cluster\_ssl | boolean | False | false | | If true, use SSL to connect to Redis cluster when `policy` is |
| redis\_cluster\_ssl\_verify | boolean | False | false | | If true, verify the server SSL certificate when `policy` is `redis-cluster`. |
### `proxy-cache`
The `proxy-cache` Plugin provides the capability to cache responses based on a cache key. The Plugin supports both disk-based and memory-based caching options to cache for [GET](https://anything.org/learn/serving-over-http/#get-request), [POST](https://anything.org/learn/serving-over-http/#post-request), and [HEAD](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD) requests.
{% hint style="info" %}
**Priority** `1085` · **Category** Traffic
{% endhint %}
Configuration and details
Responses can be conditionally cached based on request HTTP methods, response status codes, request header values, and more.
| Name | Type | Required | Default | Valid values | Description |
| -------------------- | --------------- | -------- | --------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| cache\_strategy | string | False | disk | \["disk","memory"] | Caching strategy. Cache on disk or in memory. |
| cache\_zone | string | False | disk\_cache\_one | | Cache zone used with the caching strategy. The value should match one of the cache zones defined in the [configuration files](#static-configurations) and should correspond to the caching strategy. For example, when using the in-memory caching strategy, you should use an in-memory cache zone. |
| cache\_key | array\[string] | False | \["$host", "$request\_uri"] | | Key to use for caching. Support [NGINX variables](https://nginx.org/en/docs/varindex.html) and constant strings in values. Variables should be prefixed with a `$` sign. |
| cache\_bypass | array\[string] | False | | | One or more parameters to parse value from, such that if any of the values is not empty and is not equal to `0`, response will not be retrieved from cache. Support [NGINX variables](https://nginx.org/en/docs/varindex.html) and constant strings in values. Variables should be prefixed with a `$` sign. |
| cache\_method | array\[string] | False | \["GET", "HEAD"] | \["GET", "POST", "HEAD"] | Request methods of which the response should be cached. |
| cache\_http\_status | array\[integer] | False | \[200, 301, 404] | \[200, 599] | Response HTTP status codes of which the response should be cached. |
| hide\_cache\_headers | boolean | False | false | | If true, hide `Expires` and `Cache-Control` response headers. |
| cache\_control | boolean | False | false | | If true, comply with `Cache-Control` behavior in the HTTP specification. Only valid for in-memory strategy. |
| no\_cache | array\[string] | False | | | One or more parameters to parse value from, such that if any of the values is not empty and is not equal to `0`, response will not be cached. Support [NGINX variables](https://nginx.org/en/docs/varindex.html) and constant strings in values. Variables should be prefixed with a `$` sign. |
| cache\_ttl | integer | False | 300 | >=1 | Cache time to live (TTL) in seconds when caching in memory. To adjust the TTL when caching on disk, update `cache_ttl` in the [configuration files](#static-configurations). The TTL value is evaluated in conjunction with the values in the response headers [`Cache-Control`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) and [`Expires`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Expires) received from the Upstream service. |
### `proxy-control`
The proxy-control Plugin dynamically controls the behavior of the NGINX proxy.
{% hint style="info" %}
**Priority** `21990` · **Category** Traffic
{% endhint %}
Configuration and details
:::info IMPORTANT
This Plugin requires AILIX to run on AILIX-Runtime. See ailix-build-tools for more info.
:::
| Name | Type | Required | Default | Description |
| ------------------ | ------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| request\_buffering | boolean | False | true | When set to `true`, the Plugin dynamically sets the [`proxy_request_buffering`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_request_buffering) directive. |
### `proxy-mirror`
The `proxy-mirror` Plugin duplicates ingress traffic to AILIX and forwards them to a designated upstream, without interrupting the regular services. You can configure the Plugin to mirror all traffic or only a portion. The mechanism benefits a few use cases, including troubleshooting, security inspection, analytics, and more.
{% hint style="info" %}
**Priority** `1010` · **Category** Traffic · **Required** `host`
{% endhint %}
Configuration and details
Note that AILIX ignores any response from the Upstream host receiving mirrored traffic.
| Name | Type | Required | Default | Valid values | Description |
| ------------------ | ------ | -------- | ------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| host | string | True | | | Address of the host to forward the mirrored traffic to. The address should contain the scheme but without the path, such as `http://127.0.0.1:8081`. |
| path | string | False | | | Path of the host to forward the mirrored traffic to. If unspecified, default to the current URI path of the Route. Not applicable if the Plugin is mirroring gRPC traffic. |
| path\_concat\_mode | string | False | replace | \["replace", "prefix"] | Concatenation mode when `path` is specified. When set to `replace`, the configured `path` would be directly used as the path of the host to forward the mirrored traffic to. When set to `prefix`, the path to forward to would be the configured `path`, appended by the requested URI path of the Route. Not applicable if the Plugin is mirroring gRPC traffic. |
| sample\_ratio | number | False | 1 | \[0.00001, 1] | Ratio of the requests that will be mirrored. By default, all traffic are mirrored. |
### `request-id`
The `request-id` Plugin adds a unique ID to each request proxied through AILIX, which can be used to track API requests. If a request carries an ID in the header and is not empty ("") corresponding to `header_name`, the Plugin will use the header value as the unique ID and will not overwrite with the automatically generated ID.
{% hint style="info" %}
**Priority** `12015` · **Category** Traffic
{% endhint %}
Configuration and details
| Name | Type | Required | Default | Valid values | Description |
| --------------------- | ------- | -------- | ---------------------------------------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| header\_name | string | False | "X-Request-Id" | | Name of the header that carries the request unique ID. Note that if a request carries an ID in the `header_name` header, the Plugin will use the header value as the unique ID and will not overwrite it with the generated ID. |
| include\_in\_response | boolean | False | true | | If true, include the generated request ID in the response header, where the name of the header is the `header_name` value. |
| algorithm | string | False | "uuid" | \["uuid","nanoid","range\_id","ksuid"] | Algorithm used for generating the unique ID. When set to `uuid` , the Plugin generates a universally unique identifier. When set to `nanoid`, the Plugin generates a compact, URL-safe ID. When set to `range_id`, the Plugin generates a sequential ID with specific parameters. When set to `ksuid`, the Plugin generates a sequential ID with timestamp and random number. |
| range\_id | object | False | | | Configuration for generating a request ID using the `range_id` algorithm. |
| range\_id.char\_set | string | False | "abcdefghijklmnopqrstuvwxyzABCDEFGHIGKLMNOPQRSTUVWXYZ0123456789" | minimum length 6 | Character set used for the `range_id` algorithm. |
| range\_id.length | integer | False | 16 | >=6 | Length of the generated ID for the `range_id` algorithm. |
### `request-validation`
The `request-validation` Plugin validates requests before forwarding them to Upstream services. This Plugin uses JSON Schema for validation and can validate headers and body of a request.
{% hint style="info" %}
**Priority** `2800` · **Category** Traffic
{% endhint %}
Configuration and details
See [JSON schema specification](https://json-schema.org/specification) to learn more about the syntax.
| Name | Type | Required | Default | Valid values | Description |
| -------------- | ------- | -------- | ------- | -------------- | ---------------------------------------------- |
| header\_schema | object | False | | | Schema for the request header data. |
| body\_schema | object | False | | | Schema for the request body data. |
| rejected\_code | integer | False | 400 | \[200,...,599] | Status code to return when rejecting requests. |
| rejected\_msg | string | False | | | Message to return when rejecting requests. |
### `traffic-split`
The `traffic-split` Plugin directs traffic to various Upstream services based on conditions and/or weights. It provides a dynamic and flexible approach to implement release strategies and manage traffic.
{% hint style="info" %}
**Priority** `966` · **Category** Traffic
{% endhint %}
Configuration and details
:::note
The traffic ratio between Upstream services may be less accurate since round robin algorithm is used to direct traffic (especially when the state is reset).
:::
| Name | Type | Required | Default | Valid values | Description |
| ------------------------------------------------- | -------------- | -------- | ---------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| rules.match | array\[object] | False | | | An array of one or more pairs of matching conditions and actions to be executed. |
| rules.match | array\[object] | False | | | Rules to match for conditional traffic split. |
| rules.match.vars | array\[array] | False | | | An array of one or more matching conditions in the form of lua-resty-expr to conditionally execute the plugin. |
| rules.weighted\_upstreams | array\[object] | False | | | List of Upstream configurations. |
| rules.weighted\_upstreams.upstream\_id | string/integer | False | | | ID of the configured Upstream object. |
| rules.weighted\_upstreams.weight | integer | False | weight = 1 | | Weight for each upstream. |
| rules.weighted\_upstreams.upstream | object | False | | | Configuration of the upstream. Certain configuration options Upstream are not supported here. These fields are `service_name`, `discovery_type`, `checks`, `retries`, `retry_timeout`, `desc`, and `labels`. As a workaround, you can create an Upstream object and configure it in `upstream_id`. |
| rules.weighted\_upstreams.upstream.type | array | False | roundrobin | \[roundrobin, chash] | Algorithm for traffic splitting. `roundrobin` for weighted round robin and `chash` for consistent hashing. |
| rules.weighted\_upstreams.upstream.hash\_on | array | False | vars | | Used when `type` is `chash`. Support hashing on [NGINX variables](https://nginx.org/en/docs/varindex.html), headers, cookie, Consumer, or a combination of [NGINX variables](https://nginx.org/en/docs/varindex.html). |
| rules.weighted\_upstreams.upstream.key | string | False | | | Used when `type` is `chash`. When `hash_on` is set to `header` or `cookie`, `key` is required. When `hash_on` is set to `consumer`, `key` is not required as the Consumer name will be used as the key automatically. |
| rules.weighted\_upstreams.upstream.nodes | object | False | | | Addresses of the Upstream nodes. |
| rules.weighted\_upstreams.upstream.timeout | object | False | 15 | | Timeout in seconds for connecting, sending and receiving messages. |
| rules.weighted\_upstreams.upstream.pass\_host | array | False | "pass" | \["pass", "node", "rewrite"] | Mode deciding how the host name is passed. `pass` passes the client's host name to the upstream. `node` passes the host configured in the node of the upstream. `rewrite` passes the value configured in `upstream_host`. |
| rules.weighted\_upstreams.upstream.name | string | False | | | Identifier for the Upstream for specifying service name, usage scenarios, and so on. |
| rules.weighted\_upstreams.upstream.upstream\_host | string | False | | | Used when `pass_host` is `rewrite`. Host name of the upstream. |
### `workflow`
The `workflow` Plugin supports the conditional execution of user-defined actions to client traffic based a given set of rules, defined using lua-resty-expr. This provides a granular approach to traffic management.
{% hint style="info" %}
**Priority** `1006` · **Category** Traffic · **Required** `rules`
{% endhint %}
Configuration and details
| Name | Type | Required | Default | Valid values | Description |
| ------------- | -------------- | -------- | ------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| rules | array\[object] | True | | | An array of one or more pairs of matching conditions and actions to be executed. |
| rules.case | array\[array] | False | | | An array of one or more matching conditions in the form of lua-resty-expr. For example, `{"arg_name", "==", "json"}`. |
| rules.actions | array\[object] | True | | | An array of actions to be executed when a condition is successfully matched. Currently, the array only supports one action, and it should be either `return`, or `limit-count` or `limit-conn`. When the action is configured to be `return`, you can configure an HTTP status code to return to the client when the condition is matched. When the action is configured to be `limit-count`, you can configure all options of the `limit-count` plugin, except for `group`. When the action is configured to be `limit-conn`, you can configure all options of the `limit-conn` plugin. |
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.digitalapi.ai/api-gateway/plugin-reference/plugins-traffic.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.