@lunora/ratelimit enforces named rate limits over a pluggable store. You build
one RateLimiter per app from a config map, then either attach the rateLimit
middleware to a procedure's .use(...) chain or call limiter.limit(...)
directly. On rejection the middleware throws a structural LunoraError that the
runtime maps to 429 Too Many Requests (or 403 Forbidden for a deny-list hit),
carrying data.retryAfterMs — the retry hint the client and every SDK read off
a TOO_MANY_REQUESTS envelope (protocol/README.md §4.3).
import type { RateLimitConfigMap } from "@lunora/ratelimit";
import { dbRateLimit } from "@lunora/ratelimit";
import { mutation } from "./_generated/server";
// `satisfies` is load-bearing: a bare `const` widens each `kind` to `string`,
// and the config map needs the literal to pick the algorithm.
const config = {
login: { kind: "fixed window", period: 60_000, rate: 5 },
send: { kind: "token bucket", period: 1_000, rate: 10, capacity: 20 },
} satisfies RateLimitConfigMap;
// `key` returns `string | undefined` (omit it for a global limit), while
// `ctx.auth.userId` is `string | null` — collapse the null yourself.
export const send = mutation.use(dbRateLimit(config, "send", { key: (ctx) => ctx.auth.userId ?? "anonymous" })).mutation(async ({ ctx }) => {
// …
});A RateLimiter built with no explicit store falls back to createMemoryStore — a per-Durable-Object-instance in-memory Map. That's correct for a limit
that only ever needs to hold within one DO instance, but it stops enforcing the configured rate the moment the instance is sharded, replicated
(.global()), or recreated after eviction. dbRateLimit above sidesteps the question by building the limiter per call, backed by a Lunora table via
ctx.db — see Pluggable stores. Construction without an explicit store now warns once so the choice is visible instead of silent.
Like row-level security and data masking,
it rides the .use(...) chain and is opt-in per procedure: a bare
query/mutation is never rate-limited.
Algorithms
Each named limit declares a kind. Pick by the burst behavior you want:
kind | Behavior | Pick it when |
|---|---|---|
"token bucket" | Tokens refill continuously at rate / period per ms up to capacity; a fresh key starts full, so a burst is allowed. | You want smooth throughput that tolerates short bursts (API calls). |
"fixed window" | rate tokens granted at the start of each window aligned to start + n * period. With capacity > rate, unused tokens roll over and a fresh key starts at capacity. | You want a hard cap per discrete window (e.g. 5 logins per minute). |
"sliding window" | A weighted estimate blending the current and previous window's counts; always caps at rate per period. | You want fixed-window's simplicity without its boundary-burst spike. |
const limiter = new RateLimiter({
config: {
api: { kind: "token bucket", period: 1_000, rate: 10 },
login: { kind: "fixed window", period: 60_000, rate: 5 },
search: { kind: "sliding window", period: 10_000, rate: 30 },
},
});Limit config
Each entry in the config map is a RateLimitConfig:
| Field | Type | Default | Notes |
|---|---|---|---|
kind | RateLimitKind | — | "token bucket", "fixed window", or "sliding window". Required. |
rate | number | — | Tokens granted per period. Required; must be a positive number. |
period | number | — | Window/refill period in milliseconds. Required; must be a positive number. |
capacity | number | rate | Rollover ceiling. Caps a token-bucket burst; for fixed windows enables cross-window rollover. Ignored by sliding windows. |
start | number | 0 | Phase offset in epoch ms for windowed algorithms; windows align to start + n * period. Ignored by token buckets. |
The constructor validates every config up front: a non-positive period or rate, or a negative capacity throws at construction rather than corrupting
accounting later.
Consuming a limit
limiter.limit(name, args) consumes capacity and returns a RateLimitStatus
({ ok, reason?, retryAfter }). limiter.check(name, args) peeks without
consuming. limiter.reset(name, { key }) clears accounting for a pair (e.g. on a
successful login).
import { RateLimiter, RateLimitError, createDbStore } from "@lunora/ratelimit";
import { action } from "./_generated/server";
// An action, not a mutation: see the callout below.
export const login = action.action(async ({ ctx, args }) => {
const limiter = new RateLimiter({ config, store: createDbStore({ db: ctx.db }) });
const status = await limiter.limit("login", { key: args.email });
if (!status.ok) {
// Stop here. `limit` has already consumed capacity; carrying on would
// authenticate the attempt the limiter just rejected.
// status.retryAfter is milliseconds until the request would succeed.
// status.reason is "rate" or "deny".
throw new RateLimitError(status);
}
await authenticate(args);
// Only AFTER a successful login — resetting on the way past a failed one
// hands the attacker a fresh budget on every wrong password.
await limiter.reset("login", { key: args.email });
});DB-store consumption commits with the mutation. A mutation's ctx.db writes ride its storage transaction, and a throw rolls all of them back —
including the unit that limit() consumed. Written as a mutation, the example above charges nothing for a wrong password (authenticate throws), so only
successful logins count and an attacker gets an unlimited number of guesses. Consume from an action when failed attempts must count: its writes commit
on their own, so the unit stays spent whether or not the handler throws. The same applies to .use(dbRateLimit(...)) on a mutation whose handler rejects. A
mutation that must keep the charge can return a failure value instead of throwing.
Per-call RateLimitArgs:
| Option | Type | Default | Notes |
|---|---|---|---|
key | string | — | Sub-key isolating the limit (per user/team/IP). Omit for a global limit. |
count | number | 1 | Units to consume. Must be a positive integer. |
reserve | boolean | false | Permit now and reserve future capacity (the stored value goes negative); retryAfter reports when the debt clears. A count above capacity is never permitted — see below. |
throws | boolean | false | Throw RateLimitError instead of returning a failing status. |
A count larger than the limit's capacity is caller misuse, not a rate rejection. It can never succeed no matter how long you wait, so it does not
return { ok: false } and does not honour throws: false — it throws an INTERNAL LunoraError (a 500), with or without reserve. rateLimit(...)
middleware re-throws it as-is rather than masking it behind the fail-open/fail-closed policy, which is reserved for genuine store outages. Clamp the
count, or raise the limit's capacity.
Procedure middleware
rateLimit(limiter, name, options) returns a Middleware you attach with
.use(...). The first argument is a LimiterResolver: either a fixed
RateLimiter or a (ctx) => RateLimiter that binds a context-derived limiter at
call time (handy for an ORM-backed store, see Stores).
import { RateLimiter, rateLimit, createDbStore } from "@lunora/ratelimit";
import { mutation } from "./_generated/server";
const config = { send: { kind: "token bucket", period: 1_000, rate: 10 } } as const;
export const send = mutation
.use(
rateLimit((ctx) => new RateLimiter({ config, store: createDbStore({ db: ctx.db }) }), "send", {
key: (ctx) => ctx.auth.userId ?? "anonymous",
}),
)
.mutation(async ({ ctx, args }) => {
// …
});For the common DB-backed case, dbRateLimit(config, name, options) is shorthand
for the resolver above; it builds the per-call RateLimiter + createDbStore
for you:
import type { RateLimitConfigMap } from "@lunora/ratelimit";
import { dbRateLimit } from "@lunora/ratelimit";
import { mutation } from "./_generated/server";
const config = { send: { kind: "token bucket", period: 1_000, rate: 10 } } satisfies RateLimitConfigMap;
export const send = mutation.use(dbRateLimit(config, "send", { key: (ctx) => ctx.auth.userId ?? "anonymous" })).mutation(async ({ ctx, args }) => {
// …
});Pass options.store to point at a non-default backing table/index/key column;
the rest of options matches rateLimit's.
RateLimitMiddlewareOptions:
| Option | Type | Default | Notes |
|---|---|---|---|
key | (ctx) => string | undefined | — | Sub-key derived from context. Omit for a global limit. A resolver that returns undefined throws INTERNAL rather than silently pooling every keyless caller into one bucket. |
count | number | 1 | Units to consume per call. |
message | string | — | Override the error message thrown on rejection. |
failOpen | boolean | false | Behavior when the limiter itself throws (store unavailable, etc). See below. |
Failure policy: the middleware fails closed by default: if resolving or invoking the limiter throws, it logs via console.error and rejects with
503. This is the safer default for security-sensitive limits (auth, account creation). Set failOpen: true only when degraded availability is preferable
to refusal, because a failing limiter then admits every request.
Deny list
A denyList passed to the constructor short-circuits before any token
accounting: a matching key is denied with reason: "deny" and
retryAfter: Infinity (the middleware maps this to 403 Forbidden).
const limiter = new RateLimiter({
config: { api: { kind: "token bucket", period: 1_000, rate: 10 } },
denyList: ["198.51.100.7", "abuser@example.com"],
});Each entry is stored both as given and in its normalized form
(packages/ratelimit/src/rate-limiter.ts:133). If you pass a normalize function
(applied to every incoming key for case-folding, trimming, or canonicalizing
IPs/emails), the limiter checks both the normalized and the raw form of each key.
Normalize your deny-list entries up front anyway, so that they match the form the
limiter stores.
Pluggable stores
Persistence is a RateLimitStore (get/set/delete, sync or async):
| Factory | Backing | Use when |
|---|---|---|
createMemoryStore() | An in-process Map. The default when no store is given. | Single-DO/process limits where state needn't survive eviction. |
createSqlStore({ sql }) | state.storage.sql (workerd SqlStorage, also node:sqlite). | Durable per-DO state that survives hibernation, and you have raw SQL. |
createDbStore({ db }) | A Lunora table via ctx.db (the ORM writer on a mutation/action). | Durable per-DO limits inside a procedure, where there is no raw SQL. Inside a mutation the consumed unit commits with the handler and a throw returns it. |
createReadOnlyDbStore({ db }) | The same table through a query context's reader ctx.db. | Showing remaining quota from a query — getValue/check only; limit/reset throw. |
createReadOnlyDbStore exists so a remaining-quota display does not have to cast
a query's ctx.db to the writer type. getValue and check project the stored
value forward to the current clock, which is a pure read; only limit/reset
write, and those reject with a message naming createDbStore as the fix.
createSqlStore creates its table (default _lunora_rate_limits) if missing.
createDbStore expects a table you declare in your schema with a key column,
indexed (defaults: table rateLimits, key column key). It works on a
shard-local table and on a .global() one:
import { defineTable, v } from "lunorash/server";
export const rateLimits = defineTable({
key: v.string(),
ts: v.number(),
value: v.number(),
prev: v.optional(v.number()),
})
.index("by_key", ["key"])
.index("by_ts", ["ts"]);After each write the limiter deletes up to 32 rows whose ts is past the limit's retention, through by_ts. A row
with a negative value (a reserved debt) is never deleted. Tables declared before this index was added need it
added before expiry runs; without it each sweep scans the whole table.
Every store admits exactly the configured rate under concurrent consumes. createMemoryStore and createSqlStore are synchronous, and the limiter reads,
decides and writes through them in one step. createDbStore writes through ctx.db.patchIf with the value it read as the condition, and creates a key's
row under an id derived from the key, so a consume that raced another one loses its write, re-reads, and decides again. That holds on a .global() table
too, where D1 calls do not hold the Durable Object's input gate.
Token budgets
A request limit is the wrong shape for a large language model (LLM): one call can cost a hundred
tokens or a hundred thousand, so "20 calls a minute" bounds nothing that
matters. tokenBudget binds one named limit whose unit is model tokens (or
cents) and spends it in arrears, which is how tokens actually work — the
cost is only known once the call returns.
import { tokenBudget } from "@lunora/ratelimit";
const budget = tokenBudget(limiter, "tokens");
const allowed = await budget.check(userId);
if (!allowed.ok) {
throw new LunoraError("RATE_LIMITED", `token budget exhausted; retry in ${String(allowed.retryAfter)}ms`);
}
const { text, usage } = await generateText({ model: ctx.ai.model(), prompt });
await budget.record(userId, usage?.totalTokens ?? 0);
return text;check runs before the call and consumes nothing: a tenant whose bucket is
already empty (or negative, from an expensive previous call) is turned away.
record runs after it — always, including when the call threw, since a
failed generation that consumed input tokens still has to be paid for. The
charge is a reservation, so the bucket may go negative: the tokens are already
spent, and the next call is refused until the debt refills away. A charge larger
than the limit's own ceiling is clamped to it rather than rejected, so the one
oversized call the budget exists to catch cannot escape it by being too big to
record.
Plugin form
ratelimitPlugin(limiter) packages the limiter as a Plugin that
exposes the resolved RateLimiter under ctx.api.ratelimit, so a handler can
call limit()/check()/reset() programmatically instead of (or alongside) the
enforcing middleware. Install its middleware with one .use(...):
import { RateLimiter, ratelimitPlugin } from "@lunora/ratelimit";
import { mutation } from "./_generated/server";
const limiter = new RateLimiter({
config: { send: { kind: "token bucket", period: 60_000, rate: 5, capacity: 5 } },
});
export const send = mutation.use(ratelimitPlugin(limiter).middleware!).mutation(async ({ ctx }) => {
const status = await ctx.api.ratelimit.limit("send", { key: ctx.auth.userId ?? "anonymous" });
if (!status.ok) {
throw new Error("slow down");
}
// …
});The plugin ships no schema extension (persistence is whatever store the limiter was built with), so it is middleware-only and skipped by the plugin schema fold.
API
Reference for the main exports of @lunora/ratelimit. The config and status types
(RateLimitConfig, RateLimitConfigMap, RateLimitKind, RateLimitStatus,
RateLimitStore, RateLimitArgs) are listed under Limit config,
Consuming a limit and Pluggable stores.
RateLimiter
Type: class, constructed with new RateLimiter({ config, store?, denyList?, normalize?, now? })
Holds the named limits and evaluates them. limit consumes, check peeks, and
reset clears accounting for one name and key.
RateLimiterOptions
Type: { config: RateLimitConfigMap; denyList?: Iterable<string>; normalize?: (key: string) => string; now?: () => number; store?: RateLimitStore }
Default: store is an in-memory store per instance. A warning is logged once when
you omit it.
The options for new RateLimiter. denyList denies matching keys with reason: "deny".
now is a clock for tests. After normalize runs, an IPv6 key is collapsed to its
/64 prefix (packages/ratelimit/src/rate-limiter.ts:75-77).
rateLimit
Type: (limiter: LimiterResolver, name: string, options?: RateLimitMiddlewareOptions) => Middleware
Returns procedure middleware that consumes the named limit before the handler
runs. limiter is a RateLimiter or a function that returns one from the context.
RateLimitMiddlewareOptions
Type: { key?: (ctx) => string | undefined; count?: number; message?: string; failOpen?: boolean }
Default: count is 1, and failOpen is false.
The options for rateLimit. failOpen: false returns 503 when the limiter throws.
dbRateLimit
Type: (config: RateLimitConfigMap, name: string, options?: RateLimitMiddlewareOptions & { store? }) => Middleware
options.store points the default table at a different table, index or key column.
Returns rateLimit middleware that builds a RateLimiter backed by createDbStore
for each call.
RateLimitError
Type: class extends LunoraError, constructed with (status: RateLimitStatus, message?: string)
Thrown when a limit rejects. Its wire code is TOO_MANY_REQUESTS (429), or
FORBIDDEN (403) for a deny-list hit.
createMemoryStore
Type: () => RateLimitStore
An in-process Map. It is the default when RateLimiter gets no store.
createSqlStore
Type: (options: SqlStoreOptions) => RateLimitStore
Stores the state in a raw SQL connection, such as state.storage.sql. It creates the
_lunora_rate_limits table when it is missing. table overrides the name.
createDbStore
Type: (options: DbStoreOptions) => RateLimitStore
Stores the state in a table declared in your schema, through ctx.db. table
defaults to rateLimits, and the key column defaults to key.
createReadOnlyDbStore
Type: (options: ReadOnlyDbStoreOptions) => RateLimitStore
Reads the same table through a query context. Only getValue and check work on it.
tokenBudget
Type: <Names extends string>(limiter: RateLimiter<Names>, name: Names) => TokenBudget
Binds one named limit to a token budget. check runs before a call and consumes
nothing, and record(key, tokens) runs after it.
ratelimitPlugin
Type: (limiter: RateLimiter) => Plugin
Exposes the limiter as ctx.api.ratelimit, and provides the enforcing middleware in
middleware.