# Rate limit

Deny or suspend a connection that sends or receives more messages or bytes than allowed within an interval. Each connection gets its own allowance.

Rate limits do not slow traffic down. NATS request-reply is timing sensitive, and a throttled client fails in confusing ways. Instead, a connection that exhausts its allowance is disconnected or suspended with the rule's message attached, which the application can observe and handle.

**Type:** message

**Variants:**

Each variant combines a direction, a unit, and an action:

* **Direction** — `ingress` counts messages the client sends toward the backend (`to_backend`). `egress` counts messages the backend delivers to the client (`from_backend`).
* **Unit** — `messages` counts protocol messages. `bytes` counts payload bytes.
* **Action** — `deny` closes the connection. `suspend` keeps it open but stops forwarding traffic.

| Action  | Direction | Unit     | ID                                                                                      |
| ------- | --------- | -------- | --------------------------------------------------------------------------------------- |
| deny    | ingress   | messages | `com.synadia.protect.builtins.v1.deny.ratelimit.connection.ingress.messages.message`    |
| deny    | ingress   | bytes    | `com.synadia.protect.builtins.v1.deny.ratelimit.connection.ingress.bytes.message`       |
| deny    | egress    | messages | `com.synadia.protect.builtins.v1.deny.ratelimit.connection.egress.messages.message`     |
| deny    | egress    | bytes    | `com.synadia.protect.builtins.v1.deny.ratelimit.connection.egress.bytes.message`        |
| suspend | ingress   | messages | `com.synadia.protect.builtins.v1.suspend.ratelimit.connection.ingress.messages.message` |
| suspend | ingress   | bytes    | `com.synadia.protect.builtins.v1.suspend.ratelimit.connection.ingress.bytes.message`    |
| suspend | egress    | messages | `com.synadia.protect.builtins.v1.suspend.ratelimit.connection.egress.messages.message`  |
| suspend | egress    | bytes    | `com.synadia.protect.builtins.v1.suspend.ratelimit.connection.egress.bytes.message`     |

## Configuration

An object with an `interval` and a cap. Message variants take `messages`, byte variants take `bytes`:

```
activations:

  com.synadia.protect.builtins.v1.deny.ratelimit.connection.ingress.messages.message: true

  com.synadia.protect.builtins.v1.suspend.ratelimit.connection.egress.bytes.message: true



configurations:

  com.synadia.protect.builtins.v1.deny.ratelimit.connection.ingress.messages.message:

    interval: 1s # disconnect a client that publishes more than 5000 messages per second

    messages: 5000

  com.synadia.protect.builtins.v1.suspend.ratelimit.connection.egress.bytes.message:

    interval: 10s # suspend a client that receives more than 50 MB in 10 seconds

    bytes: 50mb
```

| Field      | Type     | Required | Description                                                                                                                                                                                                                          |
| ---------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `interval` | duration | yes      | window duration, such as `1s`, `500ms`, or `5m`. A bare number is treated as seconds                                                                                                                                                 |
| `messages` | integer  | yes      | maximum messages per interval (message variants only). Must be greater than zero                                                                                                                                                     |
| `bytes`    | string   | yes      | maximum payload bytes per interval (byte variants only), such as `100kb`, `1mb`, or a plain number of bytes. `kb`, `mb` and `gb` are multiples of 1,000; use `kib`, `mib` or `gib` for multiples of 1,024. Must be greater than zero |

Egress variants only run on a port that evaluates backend traffic, so the egress rule above needs that port's `default_rule_direction` set to `both` or `from_backend` in the [rules configuration](/protect/1.0/reference/configuration.md#rules). With the default, `to_backend`, it never trips.

Configuration is validated when the bundle is installed. An invalid value is rejected before it reaches a gateway.

## Behavior

The cap is a token bucket that refills continuously. A limit of `5000` messages per `1s` gives the connection 5000 tokens, refilling at 5000 per second. Each message spends one token; a byte limit spends one token per payload byte. A connection that has been quiet can send its whole allowance at once, then continue at the steady rate. A connection that stays above the steady rate long enough drains the bucket and trips the rule.

* **Limits are per connection, not per account or subject.** Ten clients each get their own allowance.
* **Egress limits act on the receiving client.** A subscriber on a busy subject can trip an egress limit because of what the backend sends it. Use egress caps to bound what a leaf or client is allowed to consume.
* **Bytes means payload bytes.** Subjects, headers, and protocol framing are not counted.
* **A single message larger than the byte cap always trips the rule.** Set byte caps above the largest expected message.
* **Existing connections keep their original limits.** Changing the configuration and reinstalling the bundle affects new connections only. Reconnect a client to pick up new values.
* **Suspended connections stay parked for the gateway's suspend timeout,** five minutes by default. The client still receives `PING` responses, so it believes it is connected. Requests time out and subscriptions go quiet until the timeout releases it. Once suspended, the rule engine stops evaluating that connection's traffic. The timeout is set with `default_suspend_timeout` in the [rules configuration](/protect/1.0/reference/configuration.md#rules) and applies to every port.

warning

Activate one action per direction and unit. Enabling both the `deny` and `suspend` variant for the same direction and unit makes them share one allowance and charge every message twice.

note

Bundle evaluation does not simulate rate limits, so rate limit rules never trip when evaluating a bundle against scenarios. Verify them against a running gateway with a [trace](/protect/1.0/traces.md) or the [audit log](/protect/1.0/audit.md).

## Choosing deny or suspend

`deny` is the right default. The client gets a clean disconnect with the rule's message attached, reconnects, and starts with a fresh allowance.

`suspend` is for cases where a misbehaving client should be held off the backend for a while rather than immediately retrying. From the client's side, a suspended connection looks healthy but silent.

## Custom rules

The built-ins wrap two functions available to any `expr` message rule.

| Function                                            | Returns | Description                                                             |
| --------------------------------------------------- | ------- | ----------------------------------------------------------------------- |
| `connectionMessageRateExceeded(interval, messages)` | bool    | true when the connection has exceeded `messages` per `interval`         |
| `connectionBytesRateExceeded(interval, bytes)`      | bool    | true when the connection has exceeded `bytes` of payload per `interval` |

Direction comes from the rule's `direction` condition, so the same function serves ingress and egress rules. Combine it with facts and conditions to scope the limit, for example to leaf connections only, or to messages on a given subject prefix:

```
name: leaf_ingress_limit

description: Disconnect leafnodes that publish too fast on telemetry subjects.



facts:

  - connection_kind: leaf



conditions:

  - rule_type: message

  - direction: to_backend

  - subject_match: 'telemetry.>'



default: allow



rules:

  - success: deny

    message: ingress message rate exceeded

    expression: |

      connectionMessageRateExceeded("1s", 1000)
```

## Schema (messages)

```
{

  "type": "object",

  "properties": {

    "interval": { "type": "string" },

    "messages": { "type": "integer", "minimum": 1 }

  },

  "required": ["interval", "messages"],

  "additionalProperties": false

}
```

## Schema (bytes)

```
{

  "type": "object",

  "properties": {

    "interval": { "type": "string" },

    "bytes": { "type": "string" }

  },

  "required": ["interval", "bytes"],

  "additionalProperties": false

}
```
