@bitbaum/limitkit 0.0.0-stage → 0.2.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +104 -2
- package/dist/http.d.ts +59 -0
- package/dist/http.js +77 -0
- package/dist/index.d.ts +23 -0
- package/dist/index.js +23 -0
- package/dist/limit.d.ts +78 -0
- package/dist/limit.js +112 -0
- package/dist/store.d.ts +54 -0
- package/dist/store.js +69 -0
- package/package.json +56 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Mao Nakamoto
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,105 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @bitbaum/limitkit
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Rate limiting as a **decision**, not a middleware.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
pnpm add @bitbaum/limitkit
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
## Why this exists
|
|
10
|
+
|
|
11
|
+
Twelve near-identical rate limiters were found across nine repos of one fleet —
|
|
12
|
+
orangecat alone carried four, and its ADR to unify them sat **"Proposed" for
|
|
13
|
+
seven months** while the count doubled. What actually varied between the twelve
|
|
14
|
+
was one thing: *where the counts live*. Everything else — the window
|
|
15
|
+
arithmetic, the refusal shape, the headers, the client-IP dance — was the same
|
|
16
|
+
idea written twelve slightly different ways, with independently re-invented
|
|
17
|
+
bugs (one kept an unbounded `Map` keyed by stranger IPs: a slow memory leak
|
|
18
|
+
fed by the public internet).
|
|
19
|
+
|
|
20
|
+
So the algorithm is fixed and the store is the seam.
|
|
21
|
+
|
|
22
|
+
## Use
|
|
23
|
+
|
|
24
|
+
```ts
|
|
25
|
+
import { slidingWindow, clientIp, toHeaders } from '@bitbaum/limitkit';
|
|
26
|
+
|
|
27
|
+
const loginLimiter = slidingWindow({ limit: 5, windowMs: 15 * 60_000 });
|
|
28
|
+
|
|
29
|
+
export async function POST(req: Request) {
|
|
30
|
+
const result = loginLimiter.check(`login:${clientIp(req.headers)}`);
|
|
31
|
+
if (!result.allowed) {
|
|
32
|
+
return Response.json(
|
|
33
|
+
{ error: 'Too many attempts' },
|
|
34
|
+
{ status: 429, headers: toHeaders(result) },
|
|
35
|
+
);
|
|
36
|
+
}
|
|
37
|
+
// ... the actual work, with toHeaders(result) on the success path too if you like
|
|
38
|
+
}
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
- **`slidingWindow(rule, store?)`** — N hits per *trailing* window. The default;
|
|
42
|
+
it is what most hand-rolled "fixed" windows actually meant.
|
|
43
|
+
- **`fixedWindow(rule, store?)`** — N hits per aligned bucket. Cheaper, burstier
|
|
44
|
+
at the boundary (up to 2N around a roll). Choose it by name, not by accident.
|
|
45
|
+
- **`check`** counts the hit when allowed and **counts nothing when refused** —
|
|
46
|
+
a hammered key recovers the moment the attacker stops, instead of locking the
|
|
47
|
+
legitimate user behind the same NAT out forever.
|
|
48
|
+
- The refusal's `retryAfterSeconds` is **derived from the actual oldest hit**,
|
|
49
|
+
never fabricated. "Try again shortly" on a window that opens in an hour is a
|
|
50
|
+
lie; this package refuses to tell it.
|
|
51
|
+
|
|
52
|
+
## The store seam
|
|
53
|
+
|
|
54
|
+
```ts
|
|
55
|
+
interface Store {
|
|
56
|
+
get(key: string): { hits: number[] } | undefined;
|
|
57
|
+
set(key: string, state: { hits: number[] }): void;
|
|
58
|
+
}
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
The default `MemoryStore` is **bounded** (LRU past `maxKeys`, default 5 000) —
|
|
62
|
+
the unbounded-Map leak is impossible by construction. It is per-process:
|
|
63
|
+
behind N workers the effective limit multiplies by N, which is fine for
|
|
64
|
+
blunting scripted abuse and wrong for billing enforcement. For shared state,
|
|
65
|
+
implement those two methods over Redis/Postgres — an adapter is a dozen lines,
|
|
66
|
+
because the store holds and the algorithm decides.
|
|
67
|
+
|
|
68
|
+
## HTTP edges
|
|
69
|
+
|
|
70
|
+
- **`toHeaders(result)`** — `X-RateLimit-Limit` / `-Remaining` / `-Reset`, plus
|
|
71
|
+
`Retry-After` on refusals only. A plain object you spread into your own
|
|
72
|
+
response; constructing a `Response` would mean choosing your framework for
|
|
73
|
+
you.
|
|
74
|
+
- **`clientIp(headers, { trustedProxies = 1 })`** — the forwarded hop your own
|
|
75
|
+
proxy wrote, then `x-real-ip`, then `"unknown"`. A proxy **appends** to
|
|
76
|
+
`X-Forwarded-For`, so the header reads `<what the client sent>, <what the
|
|
77
|
+
proxy saw>` and only the **last** entry is unforgeable. Reading the first
|
|
78
|
+
one — which this did before v0.2.0 — lets a caller vary the header per
|
|
79
|
+
request, mint a fresh bucket each time and never trip the limit at all.
|
|
80
|
+
Set `trustedProxies: 2` when a CDN sits in front of your proxy, or `0` when
|
|
81
|
+
the server is exposed directly and no forwarded header can be believed.
|
|
82
|
+
- **No HTTP client, no middleware, no framework types** — the package supplies
|
|
83
|
+
the decision; your app keeps its conventions.
|
|
84
|
+
- **No limit values** — how many attempts a login route allows is app
|
|
85
|
+
semantics. Centralize the rule; assert the numbers locally.
|
|
86
|
+
- **No distributed store** — that is *your* Redis and *your* ops posture. The
|
|
87
|
+
seam is two methods.
|
|
88
|
+
|
|
89
|
+
Everything takes `now` as an argument, so all of it is testable without
|
|
90
|
+
sleeping — which is why this package has tests and the twelve files it
|
|
91
|
+
replaces, collectively, had almost none.
|
|
92
|
+
|
|
93
|
+
## Development
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
pnpm run verify # lint + typecheck + build + test (tests import by package name)
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
MIT.
|
|
100
|
+
|
|
101
|
+
---
|
|
102
|
+
|
|
103
|
+
Part of **[bitbaum](https://bitbaum.orangecat.ch)** — AI-native products on open
|
|
104
|
+
infrastructure, built in Zürich. Every package here lists the apps that use it:
|
|
105
|
+
**[which apps use limitkit](https://bitbaum.orangecat.ch/packages/#limitkit)**.
|
package/dist/http.d.ts
ADDED
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The HTTP-facing edges — headers out, client identity in — shared because
|
|
3
|
+
* they were the two things every replaced implementation ALSO wrote, each
|
|
4
|
+
* slightly differently.
|
|
5
|
+
*
|
|
6
|
+
* No framework types. Both helpers speak the WHATWG `Headers` `get` shape,
|
|
7
|
+
* which Next/Remix/undici requests all satisfy, so the package needs no
|
|
8
|
+
* dependency and no per-framework adapter.
|
|
9
|
+
*/
|
|
10
|
+
import type { LimitResult } from "./limit.js";
|
|
11
|
+
/**
|
|
12
|
+
* The standard rate-limit response headers, as orangecat's ADR-0002 specified
|
|
13
|
+
* seven months before anything enforced it: X-RateLimit-Limit, -Remaining,
|
|
14
|
+
* -Reset (epoch seconds), plus Retry-After on refusals only.
|
|
15
|
+
*
|
|
16
|
+
* Returned as a plain object so the caller spreads it into whatever response
|
|
17
|
+
* type it owns — a package that constructed a `Response` would be choosing a
|
|
18
|
+
* framework, and choosing a framework is how a shared package stops being
|
|
19
|
+
* adoptable.
|
|
20
|
+
*/
|
|
21
|
+
export declare function toHeaders(result: LimitResult): Record<string, string>;
|
|
22
|
+
/** The `get` half of WHATWG Headers — what every framework request exposes. */
|
|
23
|
+
export type HeadersLike = {
|
|
24
|
+
get(name: string): string | null;
|
|
25
|
+
};
|
|
26
|
+
/**
|
|
27
|
+
* Best-effort client identity for keying a limiter.
|
|
28
|
+
*
|
|
29
|
+
* WHICH HOP, AND WHY IT IS NOT THE FIRST ONE
|
|
30
|
+
*
|
|
31
|
+
* `X-Forwarded-For` is a LIST, and a reverse proxy APPENDS to it. Caddy and
|
|
32
|
+
* nginx both do. So for a request that arrived through one proxy the header
|
|
33
|
+
* reads `<whatever the client sent>, <what the proxy actually saw>` — and the
|
|
34
|
+
* only entry the client could not forge is the LAST one.
|
|
35
|
+
*
|
|
36
|
+
* This function used to return the first, with a comment asserting that was
|
|
37
|
+
* "what the proxy saw", and a test pinning it. Both were wrong in the same
|
|
38
|
+
* direction. The effect was that every limiter keyed on this — across every
|
|
39
|
+
* adopter — could be bypassed completely by sending a random
|
|
40
|
+
* `X-Forwarded-For` with each request: a new header value is a new bucket, so
|
|
41
|
+
* no bucket ever fills. A limiter that cannot be tripped is not a limiter.
|
|
42
|
+
* Found in orangecat's payments audit (bitbaum/orangecat#563, finding 2).
|
|
43
|
+
*
|
|
44
|
+
* `trustedProxies` is how many proxies of your own sit in front. Default 1 —
|
|
45
|
+
* one reverse proxy is the overwhelmingly common shape and the only one where
|
|
46
|
+
* a default can be safe. Two proxies (a CDN in front of your own) means 2, and
|
|
47
|
+
* the answer moves one further left.
|
|
48
|
+
*
|
|
49
|
+
* `trustedProxies: 0` means the server is exposed directly, so EVERY forwarded
|
|
50
|
+
* header is written by the client and none can be believed: the result is
|
|
51
|
+
* "unknown" rather than a number that looks like evidence.
|
|
52
|
+
*
|
|
53
|
+
* Falls back to "unknown" rather than throwing: a limiter keyed on "unknown"
|
|
54
|
+
* throttles the anonymous bucket collectively, which is the right failure mode
|
|
55
|
+
* for the abuse this exists to blunt.
|
|
56
|
+
*/
|
|
57
|
+
export declare function clientIp(headers: HeadersLike, opts?: {
|
|
58
|
+
trustedProxies?: number;
|
|
59
|
+
}): string;
|
package/dist/http.js
ADDED
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The HTTP-facing edges — headers out, client identity in — shared because
|
|
3
|
+
* they were the two things every replaced implementation ALSO wrote, each
|
|
4
|
+
* slightly differently.
|
|
5
|
+
*
|
|
6
|
+
* No framework types. Both helpers speak the WHATWG `Headers` `get` shape,
|
|
7
|
+
* which Next/Remix/undici requests all satisfy, so the package needs no
|
|
8
|
+
* dependency and no per-framework adapter.
|
|
9
|
+
*/
|
|
10
|
+
/**
|
|
11
|
+
* The standard rate-limit response headers, as orangecat's ADR-0002 specified
|
|
12
|
+
* seven months before anything enforced it: X-RateLimit-Limit, -Remaining,
|
|
13
|
+
* -Reset (epoch seconds), plus Retry-After on refusals only.
|
|
14
|
+
*
|
|
15
|
+
* Returned as a plain object so the caller spreads it into whatever response
|
|
16
|
+
* type it owns — a package that constructed a `Response` would be choosing a
|
|
17
|
+
* framework, and choosing a framework is how a shared package stops being
|
|
18
|
+
* adoptable.
|
|
19
|
+
*/
|
|
20
|
+
export function toHeaders(result) {
|
|
21
|
+
const headers = {
|
|
22
|
+
"X-RateLimit-Limit": String(result.limit),
|
|
23
|
+
"X-RateLimit-Remaining": String(result.remaining),
|
|
24
|
+
"X-RateLimit-Reset": String(Math.ceil(result.resetAt / 1000)),
|
|
25
|
+
};
|
|
26
|
+
if (!result.allowed) {
|
|
27
|
+
headers["Retry-After"] = String(result.retryAfterSeconds);
|
|
28
|
+
}
|
|
29
|
+
return headers;
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* Best-effort client identity for keying a limiter.
|
|
33
|
+
*
|
|
34
|
+
* WHICH HOP, AND WHY IT IS NOT THE FIRST ONE
|
|
35
|
+
*
|
|
36
|
+
* `X-Forwarded-For` is a LIST, and a reverse proxy APPENDS to it. Caddy and
|
|
37
|
+
* nginx both do. So for a request that arrived through one proxy the header
|
|
38
|
+
* reads `<whatever the client sent>, <what the proxy actually saw>` — and the
|
|
39
|
+
* only entry the client could not forge is the LAST one.
|
|
40
|
+
*
|
|
41
|
+
* This function used to return the first, with a comment asserting that was
|
|
42
|
+
* "what the proxy saw", and a test pinning it. Both were wrong in the same
|
|
43
|
+
* direction. The effect was that every limiter keyed on this — across every
|
|
44
|
+
* adopter — could be bypassed completely by sending a random
|
|
45
|
+
* `X-Forwarded-For` with each request: a new header value is a new bucket, so
|
|
46
|
+
* no bucket ever fills. A limiter that cannot be tripped is not a limiter.
|
|
47
|
+
* Found in orangecat's payments audit (bitbaum/orangecat#563, finding 2).
|
|
48
|
+
*
|
|
49
|
+
* `trustedProxies` is how many proxies of your own sit in front. Default 1 —
|
|
50
|
+
* one reverse proxy is the overwhelmingly common shape and the only one where
|
|
51
|
+
* a default can be safe. Two proxies (a CDN in front of your own) means 2, and
|
|
52
|
+
* the answer moves one further left.
|
|
53
|
+
*
|
|
54
|
+
* `trustedProxies: 0` means the server is exposed directly, so EVERY forwarded
|
|
55
|
+
* header is written by the client and none can be believed: the result is
|
|
56
|
+
* "unknown" rather than a number that looks like evidence.
|
|
57
|
+
*
|
|
58
|
+
* Falls back to "unknown" rather than throwing: a limiter keyed on "unknown"
|
|
59
|
+
* throttles the anonymous bucket collectively, which is the right failure mode
|
|
60
|
+
* for the abuse this exists to blunt.
|
|
61
|
+
*/
|
|
62
|
+
export function clientIp(headers, opts = {}) {
|
|
63
|
+
const trusted = opts.trustedProxies ?? 1;
|
|
64
|
+
if (trusted > 0) {
|
|
65
|
+
const hops = (headers.get("x-forwarded-for") ?? "")
|
|
66
|
+
.split(",")
|
|
67
|
+
.map((hop) => hop.trim())
|
|
68
|
+
.filter(Boolean);
|
|
69
|
+
// Count from the RIGHT: the rightmost hop was written by the proxy nearest
|
|
70
|
+
// us. Clamped, because a shorter chain than configured means fewer proxies
|
|
71
|
+
// ran than expected — the leftmost is then the only candidate we have, and
|
|
72
|
+
// it is still the one our own proxy wrote.
|
|
73
|
+
if (hops.length > 0)
|
|
74
|
+
return hops[Math.max(0, hops.length - trusted)];
|
|
75
|
+
}
|
|
76
|
+
return headers.get("x-real-ip")?.trim() || "unknown";
|
|
77
|
+
}
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* limitkit — rate limiting as a DECISION, not a middleware.
|
|
3
|
+
*
|
|
4
|
+
* Extracted 2026-08-20 from twelve near-identical implementations across nine
|
|
5
|
+
* repos (orangecat alone carried four, and its ADR to unify them sat
|
|
6
|
+
* "Proposed" for seven months while the count doubled). What actually varied
|
|
7
|
+
* was one thing — where the counts live — so that is the one injectable seam:
|
|
8
|
+
*
|
|
9
|
+
* slidingWindow / fixedWindow — the algorithms, pure over store + clock
|
|
10
|
+
* Store / MemoryStore — the seam, with a BOUNDED default (one of
|
|
11
|
+
* the replaced implementations leaked memory
|
|
12
|
+
* via an unbounded Map keyed by stranger IPs)
|
|
13
|
+
* toHeaders / clientIp — the HTTP edges everyone also rewrote
|
|
14
|
+
*
|
|
15
|
+
* Deliberately NOT included, per the fleet's extraction rules: no HTTP client,
|
|
16
|
+
* no framework middleware, no Response construction. The package supplies the
|
|
17
|
+
* decision; the app keeps its own conventions. And no LIMITS — how many
|
|
18
|
+
* requests a login route allows is app semantics, asserted locally, exactly
|
|
19
|
+
* like which model id is a paid one (see ai-ration's modelCost).
|
|
20
|
+
*/
|
|
21
|
+
export { type LimitRule, type LimitResult, type Limiter, slidingWindow, fixedWindow, } from "./limit.js";
|
|
22
|
+
export { type Store, type WindowState, MemoryStore } from "./store.js";
|
|
23
|
+
export { type HeadersLike, toHeaders, clientIp } from "./http.js";
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* limitkit — rate limiting as a DECISION, not a middleware.
|
|
3
|
+
*
|
|
4
|
+
* Extracted 2026-08-20 from twelve near-identical implementations across nine
|
|
5
|
+
* repos (orangecat alone carried four, and its ADR to unify them sat
|
|
6
|
+
* "Proposed" for seven months while the count doubled). What actually varied
|
|
7
|
+
* was one thing — where the counts live — so that is the one injectable seam:
|
|
8
|
+
*
|
|
9
|
+
* slidingWindow / fixedWindow — the algorithms, pure over store + clock
|
|
10
|
+
* Store / MemoryStore — the seam, with a BOUNDED default (one of
|
|
11
|
+
* the replaced implementations leaked memory
|
|
12
|
+
* via an unbounded Map keyed by stranger IPs)
|
|
13
|
+
* toHeaders / clientIp — the HTTP edges everyone also rewrote
|
|
14
|
+
*
|
|
15
|
+
* Deliberately NOT included, per the fleet's extraction rules: no HTTP client,
|
|
16
|
+
* no framework middleware, no Response construction. The package supplies the
|
|
17
|
+
* decision; the app keeps its own conventions. And no LIMITS — how many
|
|
18
|
+
* requests a login route allows is app semantics, asserted locally, exactly
|
|
19
|
+
* like which model id is a paid one (see ai-ration's modelCost).
|
|
20
|
+
*/
|
|
21
|
+
export { slidingWindow, fixedWindow, } from "./limit.js";
|
|
22
|
+
export { MemoryStore } from "./store.js";
|
|
23
|
+
export { toHeaders, clientIp } from "./http.js";
|
package/dist/limit.d.ts
ADDED
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The decision: may this key take another hit right now?
|
|
3
|
+
*
|
|
4
|
+
* Pure over its inputs — the store and the clock are arguments — for the same
|
|
5
|
+
* reason ai-ration's fair-share is: the behaviour worth testing ("a full
|
|
6
|
+
* window refuses with an honest retry time") must be provable without a
|
|
7
|
+
* server, a database, or a real minute passing. Every replaced implementation
|
|
8
|
+
* baked `Date.now()` in, so none of them could test the one thing they were
|
|
9
|
+
* for without sleeping through it.
|
|
10
|
+
*
|
|
11
|
+
* Two window shapes, because the fleet genuinely used both and they refuse
|
|
12
|
+
* differently:
|
|
13
|
+
*
|
|
14
|
+
* FIXED — N hits per aligned window; the whole allowance reappears when
|
|
15
|
+
* the window rolls. Cheaper (one counter), burstier at the edge:
|
|
16
|
+
* 2N hits can land in moments around a boundary.
|
|
17
|
+
* SLIDING — N hits per trailing window, measured from each hit. Smoother,
|
|
18
|
+
* costs the timestamps. This is what most of the fleet meant even
|
|
19
|
+
* when it implemented fixed.
|
|
20
|
+
*
|
|
21
|
+
* The refusal carries `retryAfterSeconds` computed from the actual state —
|
|
22
|
+
* when the OLDEST counted hit ages out — not a guess. "Try again shortly" on
|
|
23
|
+
* a window that will not open for an hour is the same lie the 429 classifier
|
|
24
|
+
* in ai-ration exists to prevent, one layer down.
|
|
25
|
+
*/
|
|
26
|
+
import type { Store } from "./store.js";
|
|
27
|
+
export type LimitRule = {
|
|
28
|
+
/** Max hits inside the window. */
|
|
29
|
+
limit: number;
|
|
30
|
+
/** Window length in milliseconds. */
|
|
31
|
+
windowMs: number;
|
|
32
|
+
};
|
|
33
|
+
export type LimitResult = {
|
|
34
|
+
allowed: boolean;
|
|
35
|
+
/** The rule's ceiling, echoed for headers. */
|
|
36
|
+
limit: number;
|
|
37
|
+
/** Hits still available in this window (0 when refused). */
|
|
38
|
+
remaining: number;
|
|
39
|
+
/** Epoch ms when the window opens again (when the next hit would be allowed). */
|
|
40
|
+
resetAt: number;
|
|
41
|
+
/** Whole seconds until then; 0 when allowed. Never fabricated — derived
|
|
42
|
+
* from the oldest counted hit. */
|
|
43
|
+
retryAfterSeconds: number;
|
|
44
|
+
};
|
|
45
|
+
/**
|
|
46
|
+
* A limiter bound to one rule and one store.
|
|
47
|
+
*
|
|
48
|
+
* `check` counts the hit when allowed and counts NOTHING when refused: a
|
|
49
|
+
* refused request must not extend its own punishment, or a steady attacker
|
|
50
|
+
* locks a key shut forever and the legitimate user behind the same NAT never
|
|
51
|
+
* gets back in.
|
|
52
|
+
*/
|
|
53
|
+
export type Limiter = {
|
|
54
|
+
check(key: string, now?: number): LimitResult;
|
|
55
|
+
/** Read-only view: what would happen, counting nothing either way. */
|
|
56
|
+
peek(key: string, now?: number): LimitResult;
|
|
57
|
+
};
|
|
58
|
+
/**
|
|
59
|
+
* Sliding window: N hits per trailing `windowMs`, measured from each hit.
|
|
60
|
+
*
|
|
61
|
+
* The default, because it is what nearly every replaced implementation was
|
|
62
|
+
* reaching for: "no more than N in any M minutes", not "N per wall-clock
|
|
63
|
+
* bucket".
|
|
64
|
+
*/
|
|
65
|
+
export declare function slidingWindow(rule: LimitRule, store?: Store): Limiter;
|
|
66
|
+
/**
|
|
67
|
+
* Fixed window: N hits per aligned `windowMs` bucket.
|
|
68
|
+
*
|
|
69
|
+
* Kept because three of the replaced implementations chose it deliberately
|
|
70
|
+
* for cheapness, and because its edge-burst behaviour (up to 2N around a
|
|
71
|
+
* boundary) is sometimes fine and sometimes the whole objection — the choice
|
|
72
|
+
* should be named at the call site, not implied by whichever file got copied.
|
|
73
|
+
*
|
|
74
|
+
* Implemented on the same store contract: the bucket is represented as one
|
|
75
|
+
* synthetic hit timestamp (the bucket start) repeated per hit, so a remote
|
|
76
|
+
* Store needs no second schema.
|
|
77
|
+
*/
|
|
78
|
+
export declare function fixedWindow(rule: LimitRule, store?: Store): Limiter;
|
package/dist/limit.js
ADDED
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The decision: may this key take another hit right now?
|
|
3
|
+
*
|
|
4
|
+
* Pure over its inputs — the store and the clock are arguments — for the same
|
|
5
|
+
* reason ai-ration's fair-share is: the behaviour worth testing ("a full
|
|
6
|
+
* window refuses with an honest retry time") must be provable without a
|
|
7
|
+
* server, a database, or a real minute passing. Every replaced implementation
|
|
8
|
+
* baked `Date.now()` in, so none of them could test the one thing they were
|
|
9
|
+
* for without sleeping through it.
|
|
10
|
+
*
|
|
11
|
+
* Two window shapes, because the fleet genuinely used both and they refuse
|
|
12
|
+
* differently:
|
|
13
|
+
*
|
|
14
|
+
* FIXED — N hits per aligned window; the whole allowance reappears when
|
|
15
|
+
* the window rolls. Cheaper (one counter), burstier at the edge:
|
|
16
|
+
* 2N hits can land in moments around a boundary.
|
|
17
|
+
* SLIDING — N hits per trailing window, measured from each hit. Smoother,
|
|
18
|
+
* costs the timestamps. This is what most of the fleet meant even
|
|
19
|
+
* when it implemented fixed.
|
|
20
|
+
*
|
|
21
|
+
* The refusal carries `retryAfterSeconds` computed from the actual state —
|
|
22
|
+
* when the OLDEST counted hit ages out — not a guess. "Try again shortly" on
|
|
23
|
+
* a window that will not open for an hour is the same lie the 429 classifier
|
|
24
|
+
* in ai-ration exists to prevent, one layer down.
|
|
25
|
+
*/
|
|
26
|
+
import { MemoryStore } from "./store.js";
|
|
27
|
+
function decide(rule, hits, now) {
|
|
28
|
+
const live = hits.filter((t) => t > now - rule.windowMs);
|
|
29
|
+
const allowed = live.length < rule.limit;
|
|
30
|
+
const oldest = live[0];
|
|
31
|
+
const resetAt = live.length === 0 ? now : (oldest ?? now) + rule.windowMs;
|
|
32
|
+
return {
|
|
33
|
+
allowed,
|
|
34
|
+
result: {
|
|
35
|
+
allowed,
|
|
36
|
+
limit: rule.limit,
|
|
37
|
+
remaining: Math.max(0, rule.limit - live.length - (allowed ? 1 : 0)),
|
|
38
|
+
resetAt,
|
|
39
|
+
retryAfterSeconds: allowed ? 0 : Math.max(1, Math.ceil((resetAt - now) / 1000)),
|
|
40
|
+
},
|
|
41
|
+
};
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* Sliding window: N hits per trailing `windowMs`, measured from each hit.
|
|
45
|
+
*
|
|
46
|
+
* The default, because it is what nearly every replaced implementation was
|
|
47
|
+
* reaching for: "no more than N in any M minutes", not "N per wall-clock
|
|
48
|
+
* bucket".
|
|
49
|
+
*/
|
|
50
|
+
export function slidingWindow(rule, store = new MemoryStore()) {
|
|
51
|
+
return {
|
|
52
|
+
check(key, now = Date.now()) {
|
|
53
|
+
const state = store.get(key) ?? { hits: [] };
|
|
54
|
+
const live = state.hits.filter((t) => t > now - rule.windowMs);
|
|
55
|
+
const { allowed, result } = decide(rule, live, now);
|
|
56
|
+
// Counted only when allowed; a refusal writes back only the prune, so a
|
|
57
|
+
// hammered key still recovers the moment the attacker stops.
|
|
58
|
+
store.set(key, { hits: allowed ? [...live, now] : live });
|
|
59
|
+
return result;
|
|
60
|
+
},
|
|
61
|
+
peek(key, now = Date.now()) {
|
|
62
|
+
const state = store.get(key) ?? { hits: [] };
|
|
63
|
+
return decide(rule, state.hits, now).result;
|
|
64
|
+
},
|
|
65
|
+
};
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* Fixed window: N hits per aligned `windowMs` bucket.
|
|
69
|
+
*
|
|
70
|
+
* Kept because three of the replaced implementations chose it deliberately
|
|
71
|
+
* for cheapness, and because its edge-burst behaviour (up to 2N around a
|
|
72
|
+
* boundary) is sometimes fine and sometimes the whole objection — the choice
|
|
73
|
+
* should be named at the call site, not implied by whichever file got copied.
|
|
74
|
+
*
|
|
75
|
+
* Implemented on the same store contract: the bucket is represented as one
|
|
76
|
+
* synthetic hit timestamp (the bucket start) repeated per hit, so a remote
|
|
77
|
+
* Store needs no second schema.
|
|
78
|
+
*/
|
|
79
|
+
export function fixedWindow(rule, store = new MemoryStore()) {
|
|
80
|
+
const bucketStart = (now) => now - (now % rule.windowMs);
|
|
81
|
+
return {
|
|
82
|
+
check(key, now = Date.now()) {
|
|
83
|
+
const start = bucketStart(now);
|
|
84
|
+
const state = store.get(key) ?? { hits: [] };
|
|
85
|
+
const live = state.hits.filter((t) => t === start);
|
|
86
|
+
const allowed = live.length < rule.limit;
|
|
87
|
+
store.set(key, { hits: allowed ? [...live, start] : live });
|
|
88
|
+
const resetAt = start + rule.windowMs;
|
|
89
|
+
return {
|
|
90
|
+
allowed,
|
|
91
|
+
limit: rule.limit,
|
|
92
|
+
remaining: Math.max(0, rule.limit - live.length - (allowed ? 1 : 0)),
|
|
93
|
+
resetAt,
|
|
94
|
+
retryAfterSeconds: allowed ? 0 : Math.max(1, Math.ceil((resetAt - now) / 1000)),
|
|
95
|
+
};
|
|
96
|
+
},
|
|
97
|
+
peek(key, now = Date.now()) {
|
|
98
|
+
const start = bucketStart(now);
|
|
99
|
+
const state = store.get(key) ?? { hits: [] };
|
|
100
|
+
const live = state.hits.filter((t) => t === start);
|
|
101
|
+
const allowed = live.length < rule.limit;
|
|
102
|
+
const resetAt = start + rule.windowMs;
|
|
103
|
+
return {
|
|
104
|
+
allowed,
|
|
105
|
+
limit: rule.limit,
|
|
106
|
+
remaining: Math.max(0, rule.limit - live.length),
|
|
107
|
+
resetAt,
|
|
108
|
+
retryAfterSeconds: allowed ? 0 : Math.max(1, Math.ceil((resetAt - now) / 1000)),
|
|
109
|
+
};
|
|
110
|
+
},
|
|
111
|
+
};
|
|
112
|
+
}
|
package/dist/store.d.ts
ADDED
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Where the counts live — the ONE thing the fleet's implementations genuinely
|
|
3
|
+
* disagreed on, so it is the one thing left injectable.
|
|
4
|
+
*
|
|
5
|
+
* Of the twelve implementations this package replaces, eleven kept counts in
|
|
6
|
+
* process memory and one (orangecat) in Upstash Redis. Everything around the
|
|
7
|
+
* store — the window arithmetic, the refusal shape, the headers — was the same
|
|
8
|
+
* idea written twelve slightly different ways. So the algorithm is fixed and
|
|
9
|
+
* the store is a seam: an app that outgrows one process implements these two
|
|
10
|
+
* methods over Redis/Postgres and changes nothing else.
|
|
11
|
+
*
|
|
12
|
+
* The store speaks in WINDOWS, not in "check" calls, so a remote
|
|
13
|
+
* implementation is one round trip: read-modify-write of a single small value
|
|
14
|
+
* under a key. No store method ever decides anything — deciding is the
|
|
15
|
+
* algorithm's job, and keeping the store dumb is what makes an adapter a
|
|
16
|
+
* dozen lines instead of a re-implementation.
|
|
17
|
+
*/
|
|
18
|
+
/** One key's state: hit timestamps (ms) inside the current horizon. */
|
|
19
|
+
export type WindowState = {
|
|
20
|
+
/** Timestamps of counted hits, milliseconds. The algorithm prunes; the
|
|
21
|
+
* store just holds. */
|
|
22
|
+
hits: number[];
|
|
23
|
+
};
|
|
24
|
+
export interface Store {
|
|
25
|
+
/** The state for `key`, or undefined if none is held. */
|
|
26
|
+
get(key: string): WindowState | undefined;
|
|
27
|
+
/** Replace the state for `key`. An empty `hits` MAY be dropped entirely. */
|
|
28
|
+
set(key: string, state: WindowState): void;
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* The default store: in-process, and BOUNDED.
|
|
32
|
+
*
|
|
33
|
+
* Bounded is the point, not an optimisation. One of the twelve replaced
|
|
34
|
+
* implementations kept a bare `Map` that only ever grew — every distinct key
|
|
35
|
+
* (an IP, in practice) left an entry forever, which is a slow memory leak fed
|
|
36
|
+
* by strangers. Two others solved it independently (a prune pass, an LRU).
|
|
37
|
+
* This store evicts the oldest-touched key past `maxKeys`, so the failure mode
|
|
38
|
+
* is "a very old bucket forgets", never "the process grows without bound".
|
|
39
|
+
*
|
|
40
|
+
* Scope, stated plainly: per-process. Behind N workers each holds its own
|
|
41
|
+
* counts and the effective limit multiplies by N. That is acceptable for
|
|
42
|
+
* blunting scripted abuse (what every replaced implementation was actually
|
|
43
|
+
* for) and wrong for billing enforcement — for that, implement `Store` over
|
|
44
|
+
* something shared.
|
|
45
|
+
*/
|
|
46
|
+
export declare class MemoryStore implements Store {
|
|
47
|
+
private maxKeys;
|
|
48
|
+
private map;
|
|
49
|
+
constructor(maxKeys?: number);
|
|
50
|
+
get(key: string): WindowState | undefined;
|
|
51
|
+
set(key: string, state: WindowState): void;
|
|
52
|
+
/** How many keys are currently held. Exposed for tests and monitoring. */
|
|
53
|
+
get size(): number;
|
|
54
|
+
}
|
package/dist/store.js
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Where the counts live — the ONE thing the fleet's implementations genuinely
|
|
3
|
+
* disagreed on, so it is the one thing left injectable.
|
|
4
|
+
*
|
|
5
|
+
* Of the twelve implementations this package replaces, eleven kept counts in
|
|
6
|
+
* process memory and one (orangecat) in Upstash Redis. Everything around the
|
|
7
|
+
* store — the window arithmetic, the refusal shape, the headers — was the same
|
|
8
|
+
* idea written twelve slightly different ways. So the algorithm is fixed and
|
|
9
|
+
* the store is a seam: an app that outgrows one process implements these two
|
|
10
|
+
* methods over Redis/Postgres and changes nothing else.
|
|
11
|
+
*
|
|
12
|
+
* The store speaks in WINDOWS, not in "check" calls, so a remote
|
|
13
|
+
* implementation is one round trip: read-modify-write of a single small value
|
|
14
|
+
* under a key. No store method ever decides anything — deciding is the
|
|
15
|
+
* algorithm's job, and keeping the store dumb is what makes an adapter a
|
|
16
|
+
* dozen lines instead of a re-implementation.
|
|
17
|
+
*/
|
|
18
|
+
/**
|
|
19
|
+
* The default store: in-process, and BOUNDED.
|
|
20
|
+
*
|
|
21
|
+
* Bounded is the point, not an optimisation. One of the twelve replaced
|
|
22
|
+
* implementations kept a bare `Map` that only ever grew — every distinct key
|
|
23
|
+
* (an IP, in practice) left an entry forever, which is a slow memory leak fed
|
|
24
|
+
* by strangers. Two others solved it independently (a prune pass, an LRU).
|
|
25
|
+
* This store evicts the oldest-touched key past `maxKeys`, so the failure mode
|
|
26
|
+
* is "a very old bucket forgets", never "the process grows without bound".
|
|
27
|
+
*
|
|
28
|
+
* Scope, stated plainly: per-process. Behind N workers each holds its own
|
|
29
|
+
* counts and the effective limit multiplies by N. That is acceptable for
|
|
30
|
+
* blunting scripted abuse (what every replaced implementation was actually
|
|
31
|
+
* for) and wrong for billing enforcement — for that, implement `Store` over
|
|
32
|
+
* something shared.
|
|
33
|
+
*/
|
|
34
|
+
export class MemoryStore {
|
|
35
|
+
maxKeys;
|
|
36
|
+
map = new Map();
|
|
37
|
+
constructor(maxKeys = 5_000) {
|
|
38
|
+
this.maxKeys = maxKeys;
|
|
39
|
+
}
|
|
40
|
+
get(key) {
|
|
41
|
+
const state = this.map.get(key);
|
|
42
|
+
if (state) {
|
|
43
|
+
// Refresh recency so eviction tracks use, not insertion order.
|
|
44
|
+
this.map.delete(key);
|
|
45
|
+
this.map.set(key, state);
|
|
46
|
+
}
|
|
47
|
+
return state;
|
|
48
|
+
}
|
|
49
|
+
set(key, state) {
|
|
50
|
+
if (state.hits.length === 0) {
|
|
51
|
+
this.map.delete(key);
|
|
52
|
+
return;
|
|
53
|
+
}
|
|
54
|
+
this.map.delete(key);
|
|
55
|
+
this.map.set(key, state);
|
|
56
|
+
// Map iteration order is insertion order, so the first key is the
|
|
57
|
+
// least-recently-touched — evicting it is LRU without a dependency.
|
|
58
|
+
while (this.map.size > this.maxKeys) {
|
|
59
|
+
const oldest = this.map.keys().next().value;
|
|
60
|
+
if (oldest === undefined)
|
|
61
|
+
break;
|
|
62
|
+
this.map.delete(oldest);
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
/** How many keys are currently held. Exposed for tests and monitoring. */
|
|
66
|
+
get size() {
|
|
67
|
+
return this.map.size;
|
|
68
|
+
}
|
|
69
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,59 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@bitbaum/limitkit",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "0.2.2",
|
|
4
|
+
"description": "Rate limiting as a decision, not a middleware: fixed and sliding windows over an injectable store, a bounded in-memory store, standard RateLimit headers, and client-IP extraction. No HTTP client, no framework.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"author": "Mao Nakamoto",
|
|
7
|
+
"homepage": "https://github.com/bitbaum/limitkit#readme",
|
|
8
|
+
"repository": {
|
|
9
|
+
"type": "git",
|
|
10
|
+
"url": "git+https://github.com/bitbaum/limitkit.git"
|
|
11
|
+
},
|
|
12
|
+
"bugs": {
|
|
13
|
+
"url": "https://github.com/bitbaum/limitkit/issues"
|
|
14
|
+
},
|
|
15
|
+
"keywords": [
|
|
16
|
+
"rate-limit",
|
|
17
|
+
"rate-limiting",
|
|
18
|
+
"sliding-window",
|
|
19
|
+
"fixed-window",
|
|
20
|
+
"throttle",
|
|
21
|
+
"headless"
|
|
22
|
+
],
|
|
23
|
+
"type": "module",
|
|
24
|
+
"sideEffects": false,
|
|
25
|
+
"engines": {
|
|
26
|
+
"node": ">=20"
|
|
27
|
+
},
|
|
28
|
+
"publishConfig": {
|
|
29
|
+
"access": "public",
|
|
30
|
+
"provenance": true
|
|
31
|
+
},
|
|
32
|
+
"files": [
|
|
33
|
+
"dist"
|
|
34
|
+
],
|
|
35
|
+
"exports": {
|
|
36
|
+
".": {
|
|
37
|
+
"types": "./dist/index.d.ts",
|
|
38
|
+
"default": "./dist/index.js"
|
|
39
|
+
}
|
|
40
|
+
},
|
|
41
|
+
"devDependencies": {
|
|
42
|
+
"@eslint/js": "^10.0.1",
|
|
43
|
+
"@types/node": "^26.4.1",
|
|
44
|
+
"eslint": "^10.9.1",
|
|
45
|
+
"globals": "^17.12.0",
|
|
46
|
+
"prettier": "3.10.0",
|
|
47
|
+
"typescript": "^6.0.3",
|
|
48
|
+
"typescript-eslint": "^8.69.0"
|
|
49
|
+
},
|
|
50
|
+
"scripts": {
|
|
51
|
+
"build": "tsc -p tsconfig.json",
|
|
52
|
+
"lint": "eslint .",
|
|
53
|
+
"typecheck": "tsc -p tsconfig.json --noEmit",
|
|
54
|
+
"test": "node --test test/*.test.js",
|
|
55
|
+
"verify": "pnpm run format:check && pnpm run lint && pnpm run typecheck && pnpm run build && pnpm test",
|
|
56
|
+
"format": "prettier --write .",
|
|
57
|
+
"format:check": "prettier --check ."
|
|
58
|
+
}
|
|
6
59
|
}
|