Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: update documentation for exponential backoff #89

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

feat: update documentation for exponential backoff #89

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a26d72e
feat: update documentation for exponential backoff
stefanhts Mar 6, 2025
e855a89
small fix ✏️
stefanhts Mar 6, 2025
ddda250
include exponential backoff bucket info
stefanhts Mar 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 46 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ It's a fork from [LimitDB](https://github.com/limitd/limitdb).
- [Use of Redis hash tags](#use-of-redis-hash-tags)
- [Breaking changes from `Limitdb`](#breaking-changes-from-limitdb)
- [TAKE](#take)
- [TAKEEXPONENTIAL](#takeexponential)
- [TAKEELEVATED](#takeelevated)
- [Use of fixed window on Take and TakeElevated](#use-of-fixed-window-on-take-and-takeelevated)
- [PUT](#put)
Expand Down Expand Up @@ -77,6 +78,7 @@ const limitd = new Limitd({
- `unlimited` (boolean = false): unlimited requests (skip take).
- `skip_n_calls` (number): take will go to redis every `n` calls instead of going in every take.
- `elevated_limits` (object): elevated limits configuration that kicks in when the bucket is empty. Please refer to the [ERL section](#ERL-Elevated-Rate-Limits) for more details.
- `exponential_backoff` (object): exponential backoff configuration for the use of `takeExponential`. Please refer to the [TAKEEXPONENTIAL section](#takeexponential) for more details.
- `fixed_window` (boolean = false): refill at specified interval instead of granular.

You can also define your rates using `per_second`, `per_minute`, `per_hour`, `per_day`. So `per_second: 1` is equivalent to `per_interval: 1, interval: 1000`.
Expand Down Expand Up @@ -260,6 +262,48 @@ The result object has:
- `limit` (int): the size of the bucket.
- `delta_reset_ms` (int): the time remaining until the bucket is full again, expressed in milliseconds from the current time.

## TAKEEXPONENTIAL


### Configuration
You can configure exponential backoff inside your bucket definitions as follows:

```js
buckets = {
ip: {
size: 10,
per_second: 5,
exponential_backoff: { // Optional. Exp Backoff configuration if needed for the bucket. If not defined, defaults will be used if called with takeExponential.
backoff_factor: 3, // Optional. The exponential backoff factor used as the base (n) for n<sup>i</sup>. Default: the value 2 will be used if nothing is specified..
multiple_unit: 6, // Optional. The factor used for backoff offset. Used as (m) for m*n<sup>i</n>. Default: the value 1000 in miliseconds will be used if nothing is specified.
}
}
}
```

This take operation allows the use of exponential backoff rate limits.

```js
limitd.takeExponential(type, key, { count, configOverride }, (err, result) => {
console.log(result);
});
```

`limitd.takeExponential` takes the following arguments:
- `type`: the bucket type.
- `key`: the identifier of the bucket.
- `count`: the amount of tokens you need. This is optional and the default is 1.
- `configOverride`: caller-provided bucket configuration for this operation

The result options has:
- `conformant` (boolean): true if the requested amount is conformant to the limit.
- `remaining` (int): the amount of remaining tokens in the bucket.
- `reset` (int / unix timestamp): unix timestamp of the date when the bucket will be full again.
- `limit` (int): the size of the bucket.
- `delta_reset_ms` (int): the time remaining until the bucket is full again, expressed in milliseconds from the current time.
- `backoff_factor` (int): the base exponential factor used for exponential backoff
- `delta_backoff_time` (int): the amount of time until next allowed request expressed in milliseconds from the current time.

## TAKEELEVATED

This take operation allows the use of elevated rate limits if it corresponds.
Expand Down Expand Up @@ -310,12 +354,12 @@ if erl_triggered // quota left in the quotaKey bucket
if !erl_triggered // ERL wasn't triggered in this call, so we haven't identified the remaining quota.
```

### Use of fixed window in Take and TakeElevated
### Use of fixed window in Take, TakeExponential and TakeElevated
By default, the bucket uses the sliding window algorithm to refill tokens. For example, if the bucket is set to 100 tokens per second, it refills 1 token every 10 milliseconds (1000ms / 100 tokens per second).

With the fixed window algorithm, the bucket refills at the specified interval. For instance, if set to 100 tokens per second, it refills 100 tokens every second.

To use the fixed window algorithm on `Take` or `TakeElevated`, set the `fixed_window` property in the bucket configuration to `true` (default is `false`). This will refill the bucket at the specified interval
To use the fixed window algorithm on `Take` `TakeExponential` or `TakeElevated`, set the `fixed_window` property in the bucket configuration to `true` (default is `false`). This will refill the bucket at the specified interval

Additionally, you can use the `fixed_window` flag in the configOverride parameter. This acts as a feature flag for safe deployment, but it cannot activate the fixed window algorithm if the bucket configuration is set to false.

Expand Down