Dynamic rate limiting with feature flags

What is dynamic rate limiting with feature flags?

You change rate limits at runtime without redeploying, driven by a feature flag. The SDK still runs in your process. The flag service supplies the numbers and modes. You rebuild the rule on each request (or on a short cache) with withRule(), then call protect().

That is useful when a paying customer needs a higher ceiling, when an endpoint should allow known bots, or when you normally run open and need to clamp traffic during an incident. You can also load limits from a database or a session. Feature flags are the option that a non-deploying operator can flip from a dashboard.

This guide uses @arcjet/node v1 with Express, plus LaunchDarkly's Node server SDK. The same pattern works in any Arcjet JS adapter. For algorithm choice, see the rate limiting guide. For deciding whether a spike is a customer or an attack, see DoS versus legitimate traffic.

Why put rate limits behind a flag?

A hardcoded slidingWindow({ max: 10, interval: 60 }) is fine until the night you need max: 2 on an anonymous route and max: 200 on a billed integration. A deploy is the wrong control loop for that. Flags give you:

• Instant mode changes between DRY_RUN and LIVE.
• Numeric ceilings you can clamp without a release.
• Per-context targeting so one tenant can stay wide while guests tighten.

Keep per-request cost and identity in code. Keep emergency and experiment knobs in flags. Do not put secrets in flag values.

What runtime should you use?

@arcjet/node v1 requires Node.js 22.21.0 or later and is ESM only. Use Node 22 LTS. Express 5 is the current Express release line; Express 4 still runs, but do not pin express@^4 or @types/node@^20 as if they were the present baseline. The following example is Express 5 on Node 22. The app.get and res.status calls are the same shape on Express 4.

LaunchDarkly's Node server SDK still evaluates flags with client.variation(key, context, defaultValue). That method remains the primary evaluation API. Use a context object (kind plus key), not a deprecated user-only type.

How do you protect an Express route with Arcjet?

Create a small ESM app:

1
npm init -y
2
npm i express @arcjet/node@1.10.0
3
npm i --save-dev @types/node typescript

Set "type": "module" in package.json and start with Node's env-file flag:

1
{
2
  "private": true,
3
  "type": "module",
4
  "scripts": {
5
    "start": "node --env-file .env.local ./index.js"
6
  }
7
}

.env.local holds the site key and, later, the LaunchDarkly SDK key:

1
ARCJET_ENV=development
2
ARCJET_KEY=
3
LAUNCHDARKLY_SDK_KEY=

Create a reusable Arcjet client with an empty rule list. You attach live rules after you read flags:

1
import arcjet from "@arcjet/node";
2

3
export const aj = arcjet({
4
  key: process.env.ARCJET_KEY,
5
  rules: [],
6
});

In the route, call protect(req) and branch on the decision:

1
import express from "express";
2
import { aj } from "./lib/arcjet.js";
3
import { shield, slidingWindow } from "@arcjet/node";
4

5
const app = express();
6

7
app.get("/", async (req, res) => {
8
  const decision = await aj
9
    .withRule(shield({ mode: "LIVE" }))
10
    .withRule(slidingWindow({ mode: "LIVE", max: 10, interval: 60 }))
11
    .protect(req);
12

13
  if (decision.isDenied()) {
14
    if (decision.reason.isRateLimit()) {
15
      return res.status(429).send("Too many requests");
16
    }
17
    return res.status(403).send("Forbidden");
18
  }
19

20
  res.send("Hello World!");
21
});
22

23
app.listen(3000, () => {
24
  console.log("Server started at http://localhost:3000");
25
});

slidingWindow takes interval as a number of seconds. Eleven requests inside 60 seconds return 429. shield denies common application-layer attack patterns with 403. This hardcoded version is the control you will replace with flag values.

How do you define the LaunchDarkly flags?

Create four flags. Use permanent (non-temporary) custom flags so an incident toggle is not cleaned up as an experiment.

The following table is the flag set this example reads:

Turn each flag on after you create it. Copy the server SDK key from the LaunchDarkly environment (the test environment is fine for local work) into LAUNCHDARKLY_SDK_KEY.

You can store the same object in one JSON flag if you prefer a single evaluation. Four typed flags keep the dashboard obvious during an incident.

How do you read flags with client.variation()?

Install the server SDK and evaluate once per request (or cache for a few seconds). variation() is async in the current Node server SDK and needs a context plus a default.

1
npm i @launchdarkly/node-server-sdk

1
import * as ld from "@launchdarkly/node-server-sdk";
2

3
const client = ld.init(process.env.LAUNCHDARKLY_SDK_KEY);
4

5
// The policy that applies when the flag service cannot answer.
6
const DEFAULTS = {
7
  shieldMode: "LIVE",
8
  slidingWindowMode: "LIVE",
9
  slidingWindowMax: 100,
10
  slidingWindowInterval: 60,
11
};
12

13
const MODES = new Set(["LIVE", "DRY_RUN"]);
14
const asMode = (value, fallback) => (MODES.has(value) ? value : fallback);
15

16
// Wait for the client once, at module scope, not on every request. The
17
// timeout is in seconds and the promise rejects when it expires, so swallow
18
// the rejection here rather than letting it reach a handler.
19
const ready = client
20
  .waitForInitialization({ timeout: 5 })
21
  .then(() => true)
22
  .catch(() => false);
23

24
export async function getArcjetConfig() {
25
  if (!(await ready)) {
26
    return DEFAULTS;
27
  }
28

29
  const context = { kind: "user", key: "guest" };
30

31
  const shieldMode = await client.variation("shieldMode", context, "LIVE");
32
  const slidingWindowMode = await client.variation(
33
    "slidingWindowMode",
34
    context,
35
    "LIVE",
36
  );
37
  const slidingWindowMax = await client.variation(
38
    "slidingWindowMax",
39
    context,
40
    100,
41
  );
42
  const slidingWindowInterval = await client.variation(
43
    "slidingWindowInterval",
44
    context,
45
    60,
46
  );
47

48
  return {
49
    // A flag value is external input. `shield({ mode })` throws on anything
50
    // that is not exactly "LIVE" or "DRY_RUN", so a stray "live" typed into
51
    // the dashboard mid-incident would 500 every request.
52
    shieldMode: asMode(shieldMode, DEFAULTS.shieldMode),
53
    slidingWindowMode: asMode(slidingWindowMode, DEFAULTS.slidingWindowMode),
54
    slidingWindowMax: Number.isInteger(slidingWindowMax)
55
      ? slidingWindowMax
56
      : DEFAULTS.slidingWindowMax,
57
    slidingWindowInterval: Number.isInteger(slidingWindowInterval)
58
      ? slidingWindowInterval
59
      : DEFAULTS.slidingWindowInterval,
60
  };
61
}

The third argument to variation() is the fallback when the client is not ready or the key is missing. Fail toward the safer default for the route: LIVE and a low max on login, DRY_RUN and a high max on a public marketing page.

Two failure modes deserve those extra lines. waitForInitialization takes an options object whose timeout is in seconds, and it rejects when the timeout expires rather than resolving with defaults, so an unguarded await turns a flag-service outage into a failed request. Resolve it once at module scope: awaiting it per request pays the timeout on every call during a slow start and gives you nothing the first await did not. And the whole point of this design is that someone edits these values from a dashboard while under pressure, which is exactly when a typo happens, so coerce what comes back before you hand it to a rule constructor.

Wire the values into withRule():

1
import _arcjet, { shield, slidingWindow } from "@arcjet/node";
2
import { getArcjetConfig } from "./launchdarkly.js";
3

4
const base = _arcjet({
5
  key: process.env.ARCJET_KEY,
6
  rules: [],
7
});
8

9
export default async function arcjet() {
10
  const config = await getArcjetConfig();
11

12
  return base.withRule(shield({ mode: config.shieldMode })).withRule(
13
    slidingWindow({
14
      mode: config.slidingWindowMode,
15
      max: config.slidingWindowMax,
16
      interval: config.slidingWindowInterval,
17
    }),
18
  );
19
}

The route stays the same: const aj = await arcjet(); const decision = await aj.protect(req);. You still construct base once. You add rules per request from the flag payload you just read.

Pass a real user or tenant key in the LaunchDarkly context when you want targeted ceilings. Then one customer can keep the regular variation while guests receive the clamped values.

What do you do in an emergency traffic surge?

Treat the flag dashboard as the incident control, not a deploy pipeline. Work through this runbook:

1. Confirm what is growing. One authenticated customer, one API key, or one path is often legitimate load. Many unrelated IPs on login or checkout is closer to an attack. See DoS versus legitimate traffic before you clamp everyone.
2. If Shield or the limiter is in DRY_RUN, switch shieldMode and slidingWindowMode to LIVE and save. Wait for the SDK stream to land (usually a few seconds).
3. If anonymous or expensive routes are still too hot, serve the clamped number variations: drop slidingWindowMax (for example 100 to 2) and, if you need a faster reset, drop slidingWindowInterval (for example 60 to 10).
4. Target the clamp. Apply the tight numbers to guests, a suspect segment, or a single route's context key. Leave known high-volume customers on the regular variation so you do not create an SLA incident.
5. Watch 429 rate, error budgets, and support load. If paying traffic is the surge, raise that segment's max instead of fighting it with a global clamp.
6. After the event, restore regular variations, write down what you changed, and decide whether the new numbers belong in code as the default.

Do not invent new flag keys in the middle of an incident. Pre-create LIVE / DRY_RUN and regular / clamped variations so the only action is targeting and save.

How do you run this in production?

Initialize one LaunchDarkly client for the process. Do not call ld.init per request. The client holds the flag store and serves variation() locally after the first handshake.

Start rules in DRY_RUN, watch the Arcjet dashboard, then flip the mode flag to LIVE. Log the flag values you applied, the decision conclusion, and the characteristic. When LaunchDarkly is down, your defaults run. Pick those defaults per route: fail open on a public catalog, fail closed on password reset.

Dynamic limits do not replace identity. Key the sliding window on userId or an API key when you have one, and keep IP as the guest fallback. Flags change the numbers. Characteristics decide who shares the budget.