@alxia/rate-limit 0.4.0 → 0.4.2

package/README.md

@@ -46,8 +46,20 @@ routes declared after it, and also a request no route matches: it is counted,
 and past the limit answers the 429 before the 404. Put it in a `group` to
 count only some routes: a path-scoped `use('/api', …)` cannot give `rateLimit` to the context.
 
-Behind a proxy, give the app an `ip` option that reads the header it sets:
-`alxia({ ip: (request) => request.headers.get('x-real-ip') ?? undefined })`.
+Behind a proxy, the connection is the proxy: give the app an `ip` option that
+reads the client from the header the proxy appends to, with core's `forwardedIp`:
+
+```ts
+import { alxia, forwardedIp } from '@alxia/core';
+
+const app = alxia({ ip: forwardedIp({ trusted: 1 }) }) // one proxy in front
+	.use(rateLimit({ limit: 100, windowMs: 60_000 }));
+```
+
+Never key by the first entry of `X-Forwarded-For` (`split(',')[0]`): the client
+writes it, so a new value in each request is a new allowance. `forwardedIp`
+reads the entry your proxy appended
+([Serving](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/serving.md#the-clients-address-ip)).
 
 ## Across processes
 
@@ -63,12 +75,12 @@ app.use(rateLimit({ limit: 100, windowMs: 60_000, store: redisStore(redis, { nam
 
 A store that counts by a rate of its own declares it as `policy: { limit,
 windowMs }`, and `rateLimit({ store })` reads both from it, headers included:
-the numbers are written once. `redisStore(handle.limits.api, api)` does, from
-the definition `api`. A `limit` or `windowMs` given beside it that differs
+the numbers are written once. `redisStore(handle.limits.api)` does, from
+the bound limit's definition. A `limit` or `windowMs` given beside it that differs
 throws at declaration.
 
 ```ts
-app.use(rateLimit({ store: redisStore(handle.limits.api, api) }));
+app.use(rateLimit({ store: redisStore(handle.limits.api) }));
 ```
 
 A store of your own implements `RateLimitStore` (and, to count by a rate of

package/docs/guide.md

@@ -80,7 +80,7 @@ written once. Without one they are required, and a type error says so.
 import { redisStore } from '@alxia/redis';
 
 // `api` is the defineRateLimit definition the handle wired.
-app.use(rateLimit({ store: redisStore(handle.limits.api, api) })); // 100 per 60 s, from `api`
+app.use(rateLimit({ store: redisStore(handle.limits.api) })); // 100 per 60 s, from `api`
 ```
 
 A `limit` or a `windowMs` given beside a policy must equal it, or
@@ -96,15 +96,25 @@ above ten 365-day years (315,360,000,000), on the first request it counts rather
 
 By default a limit counts per client address, `ctx.ip`, which is what the
 app's [`ip` option](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/serving.md#the-clients-address-ip)
-reads. Behind a proxy, that is the proxy's address unless you set `ip`:
+reads. Behind a proxy, that is the proxy's address unless you set `ip`, and
+the header to read it from is the client's to write: the first entry of
+`X-Forwarded-For` is whatever the client sent, so a limit keyed by it is
+bypassed with a new value in each request. Use core's `forwardedIp`, which
+reads the entry your own proxies appended, from the right:
 
 ```ts
+import { alxia, forwardedIp } from '@alxia/core';
+
 const app = alxia({
-	ip: (request, server) =>
-		request.headers.get('x-real-ip') ?? server?.requestIP(request)?.address,
+	ip: forwardedIp({ trusted: 1 }), // or ['10.0.0.0/8'], the proxies' own ranges
 }).use(rateLimit({ limit: 100, windowMs: 60_000 }));
 ```
 
+`trusted` is the number of proxies in front of the app (`2` for a CDN and a
+load balancer), or their CIDR ranges, in which case a client that reaches the
+app directly is counted by its own address, whatever header it sends
+([Serving](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/serving.md#the-clients-address-ip)).
+
 Count by something else — an API key, a token — by returning it from `key`.
 It may be async. A request whose key is `undefined` is not counted: it passes,
 gets no rate-limit header, and its route reads `rateLimit` as `undefined`.

package/docs/roadmap.md

@@ -39,7 +39,7 @@ Nothing scheduled yet.
   reads `limit` and `windowMs` from it, both optional in the type, headers
   included; without a policy they stay required. A `limit` or `windowMs` that
   differs from the policy throws at declaration. `@alxia/redis`'s
-  `redisStore(handle.limits.api, api)` is such a store. Every existing form
+  `redisStore(handle.limits.api)` is such a store. Every existing form
   works as before.
 
 ### 0.1.0

package/docs/troubleshooting.md

@@ -22,6 +22,7 @@ nothing of its own; past the limit it answers a 429.
 **Counting**
 
 - [Every client is refused at once](#every-client-is-refused-at-once)
+- [One client is never refused, whatever it sends](#one-client-is-never-refused-whatever-it-sends)
 - [Nothing is limited, and no `RateLimit-*` header is sent](#nothing-is-limited-and-no-ratelimit--header-is-sent)
 - [A client makes more than `limit` requests](#a-client-makes-more-than-limit-requests)
 - [A client is refused before `limit` requests](#a-client-is-refused-before-limit-requests)
@@ -132,7 +133,7 @@ app.use(rateLimit({ limit: Number(Bun.env.RATE_LIMIT ?? 100), windowMs: 60_000 }
 ### `TypeError: rateLimit: limit … differs from the store's policy of …`
 
 **When:** `rateLimit()` is given a `store` that declares its own `policy`
-(`redisStore(handle.limits.api, api)`) and a `limit` or a `windowMs` that is
+(`redisStore(handle.limits.api)`) and a `limit` or a `windowMs` that is
 not the store's. It throws at declaration, so the app fails at startup:
 
 ```text
@@ -147,7 +148,7 @@ say what the store does not enforce. (`windowMs` reads the same way.)
 the rate, change the definition the store reads it from:
 
 ```ts
-app.use(rateLimit({ store: redisStore(handle.limits.api, api) }));
+app.use(rateLimit({ store: redisStore(handle.limits.api) }));
 ```
 
 ## Responses
@@ -181,16 +182,31 @@ busy client, or a handful of ordinary ones, and everyone gets the 429.
 **Why:** the default key is `ctx.ip`, the connection's address — the
 proxy's, the same for every request. All clients share one allowance.
 
-**Fix:** give the app an `ip` option that reads the header your proxy sets,
-and only from a proxy you trust:
+**Fix:** give the app an `ip` option that reads the client from the header
+your proxy appends to, with core's `forwardedIp`:
 
 ```ts
-const app = alxia({
-	ip: (request, server) =>
-		request.headers.get('x-real-ip') ?? server?.requestIP(request)?.address,
-}).use(rateLimit({ limit: 100, windowMs: 60_000 }));
+import { alxia, forwardedIp } from '@alxia/core';
+
+const app = alxia({ ip: forwardedIp({ trusted: 1 }) }).use(
+	rateLimit({ limit: 100, windowMs: 60_000 }),
+);
 ```
 
+### One client is never refused, whatever it sends
+
+**When:** behind a proxy, a client changes its `X-Forwarded-For` in each
+request and is never answered a 429, or one address is refused for a
+header another client wrote.
+
+**Why:** the `ip` option reads the header's first entry
+(`split(',')[0]`). That entry is what the client wrote, so each value is a
+new key. Each proxy appends the address it saw to the right.
+
+**Fix:** read from the right, as `forwardedIp` does: `trusted: 1` is the
+last entry, `2` the one before it behind two proxies, and a list of CIDR
+ranges the first entry from the right that is not a proxy of yours.
+
 ### Nothing is limited, and no `RateLimit-*` header is sent
 
 **When:** requests past `limit` still answer 200, without a rate-limit

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@alxia/rate-limit",
-	"version": "0.4.0",
+	"version": "0.4.2",
 	"description": "Rate limiting for alxia: a 429 with Retry-After past the limit, the remaining allowance typed in the context, pluggable stores",
 	"license": "MIT",
 	"type": "module",
@@ -41,12 +41,12 @@
 		]
 	},
 	"devDependencies": {
-		"@alxia/core": "^0.5.0",
+		"@alxia/core": "^0.6.0",
 		"@types/bun": "^1.4.2",
 		"zod": "^4.2.0"
 	},
 	"peerDependencies": {
-		"@alxia/core": "^0.5.0",
+		"@alxia/core": "^0.6.0",
 		"typescript": "^6.0.3 || ^7.0.0"
 	}
 }