limiter

A wrapper for limitd-redis.

Why ?

Provides utilities and rollback functionality for our clients.

This module was originally built to work with limitd. The prior solution -- and most of the documentation surrounding our standard rate-limiting Buckets -- can be found in joylife/limitd. That solution is now deprecated.

Buckets

Each client must define the set of rate-limit Buckets that intends to use.

The set of defaultBuckets defines the standard set of ones that we've historically determined that we need. This list may be old, but that's the general idea. Your client can use any subset of these Buckets, but when it does, the Best Practice is to use the exact definition(s) here.

However, for flexibility reasons, this is not strictly enforced.

Bucket modes

There are three ways a bucket refills:

| Mode | Config | Refill behavior | | --- | --- | --- | | Drip | size + a per_* rate (e.g. { size: 500, per_hour: 500 }) | Gradually refills over time. | | Fixed / lifetime | size only (e.g. { size: 3000 }, optionally ttl) | Never refills between takes; the key expires only after ttl seconds of inactivity, so it behaves as a lifetime cap. | | Fixed-window | size + fixed_window: true + ttl (window length in seconds) | Starts full and fully refills exactly ttl seconds after the first take of the window — a true daily-style reset, not a gradual drip and not inactivity-based. |

Fixed-window buckets

const buckets = {
  // 100 sends per rolling 24h window; the window starts on the first send and
  //   the bucket refills to 100 exactly 24h later.
  emailsDailyBasicByEventId: { size: 100, fixed_window: true, ttl: 86400 },
};

The window's TTL is anchored to the first take and is not extended by later takes, so the reset time is stable for the whole window. Do not combine fixed_window with a per_* drip rate.

Tiered daily caps via separate buckets

Per-tier limits are modeled as one bucket per tier (emailsDailyBasicByEventId, emailsDailyPlusByEventId, emailsDailyCxByEventId). Callers pick the bucket that matches the event's tier. Each tier is a distinct Redis key, so a CX goodwill bump (switching to the cx bucket) starts a fresh full window immediately, at the cost of abandoning the prior tier's consumption.

await processor.transfer('emailsDailyBasicByEventId', eventId, 1);
// CX bump -> just call the higher tier:
await processor.transfer('emailsDailyCxByEventId', eventId, 1);

Reading allowance without consuming — peek()

LimiterProcessor#peek(type, id) returns the current allowance without taking a token (and without recording an operation, so it never affects revert() / transferAll rollback):

const { limit, remaining, reset } = await processor.peek('emailsDailyBasicByEventId', eventId);
// reset: unix timestamp (seconds) when a fixed-window bucket refills, or 0 when
//   there is no active window / the bucket does not track a reset.

Why limitd-redis ?

Although this package is available on npm, it's no longer actively maintained. We've observed bugs in the existing published version, but these issues have already been resolved in the limitd-redis gitHub repository. To address this, we've imported the latest stable version(v7.8.1) from there github repository and using it locally in the limiter.

In case we need to update in the future, we can replace the "limitd-redis" directory with the latest version of limitd-redis from their GitHub repository.

Note: We need to add dependency from limitd-redis to limiter package json before publish. We are using limitd-redis as directly not package inside limiter.

Testing:

npm run test will run offline tests using a mock. npm run sanity-check will run against a limitd service configured to run with the test buckets.

Quick Test

node tests/performTestWithTestPerMinute.js