@shaferllc/keel 0.59.0 → 0.68.0

package/docs/rate-limiting.md

@@ -0,0 +1,155 @@
+# Rate Limiting
+
+`rateLimiter()` is a middleware that caps how many requests a client can make in
+a window. It sets the standard `X-RateLimit-*` and `Retry-After` headers, and
+returns `429 Too Many Requests` when the limit is exceeded.
+
+It's a **fixed-window** limiter: each key gets a bucket that counts requests
+until a fixed reset time, then starts over. Simple, cheap, and edge-safe — the
+default store is a plain in-memory `Map`, so nothing is imported that can't run
+on a Worker.
+
+## Global or per-route
+
+```ts
+import { rateLimiter } from "@shaferllc/keel/core";
+
+// every request: 60 per minute per IP
+export class Kernel extends HttpKernel {
+  constructor(app: Application) {
+    super(app);
+    this.use(rateLimiter({ max: 60, window: 60 }));
+  }
+}
+
+// a stricter limit on a sensitive route
+router.post("/login", [AuthController, "login"]).use(rateLimiter({ max: 5, window: 60 }));
+```
+
+Each call to `rateLimiter()` owns its own bucket store, so a global limiter and a
+per-route limiter count independently — a request to `/login` ticks both, but in
+separate buckets. Stack as many as you like.
+
+## Options
+
+```ts
+rateLimiter({
+  max: 60,                     // requests per window (default 60)
+  window: 60,                  // window seconds (default 60)
+  key: (c) => c.req.header("x-api-key") ?? "anon", // bucket key (default: IP)
+  message: "Slow down!",       // 429 body message
+});
+```
+
+The `key` function decides what to limit by — per IP (default), per API key, per
+user id, etc. Different keys get independent buckets. Return the same string to
+share a bucket; return `"global"` (or any constant) to limit everyone together.
+
+### The default key
+
+With no `key`, the bucket is derived from the client IP, tried in this order:
+
+1. the first entry of `X-Forwarded-For` (trimmed),
+2. `X-Real-IP`,
+3. the literal `"global"` if neither header is present.
+
+That fallback means that behind a proxy that strips those headers, *every* client
+shares the `"global"` bucket — so set an explicit `key` if your platform doesn't
+surface the client IP.
+
+## Response headers
+
+Every response carries:
+
+| Header | Meaning |
+|--------|---------|
+| `X-RateLimit-Limit` | the ceiling for the window |
+| `X-RateLimit-Remaining` | requests left in the window |
+| `Retry-After` | (on 429) seconds until the window resets |
+
+On an allowed request the two `X-RateLimit-*` headers are written *after* the
+handler runs. On a rejected request all three are set on the `429` itself.
+
+## What happens at the limit
+
+The counter increments on every request. The request that pushes the count
+*past* `max` is the one that's rejected — so `max: 5` lets five requests through
+and blocks the sixth within the window. The `429` body is:
+
+```json
+{ "error": "Too Many Requests", "status": 429 }
+```
+
+`error` is your `message` if you passed one. `Retry-After` reports the whole
+seconds until the bucket resets. Once the window elapses the next request starts
+a fresh bucket at count 1.
+
+## Storage
+
+The default store is **in-memory** — per process, and per isolate on the edge.
+That's fine for a single instance, but limits aren't shared across instances.
+The store self-prunes: once it holds more than 10,000 keys it sweeps expired
+buckets on the next request, so a large key space (e.g. per-IP) won't grow
+unbounded.
+
+For distributed limiting, wrap your own middleware that counts in Redis/KV and
+returns `429` the same way.
+
+---
+
+## API reference
+
+### `rateLimiter(options?)`
+
+`rateLimiter(options?: RateLimiterOptions): MiddlewareHandler`
+
+Builds a fixed-window rate-limiting middleware. Each returned handler keeps its
+own private bucket store, counts requests per key within the window, sets the
+`X-RateLimit-*` headers, and short-circuits with `429` past the limit.
+
+```ts
+import { rateLimiter } from "@shaferllc/keel/core";
+
+const limit = rateLimiter({ max: 100, window: 60 });
+// register it: this.use(limit) globally, or .use(limit) on a route
+```
+
+**Notes:** all options are optional — `rateLimiter()` with no arguments is 60
+requests per 60 seconds, keyed by client IP. The returned handler is a Hono
+`MiddlewareHandler`, so it works anywhere middleware is accepted (`use`, per
+route, per group). Buckets live in a closure over the single call, so reusing the
+*same* handler shares state while a second `rateLimiter(...)` call does not.
+The `429` is returned before `next()`, so downstream handlers never run for a
+throttled request.
+
+### Interfaces & types
+
+#### `RateLimiterOptions`
+
+```ts
+interface RateLimiterOptions {
+  max?: number;                     // requests per window; default 60
+  window?: number;                  // window length in seconds; default 60
+  key?: (c: Context) => string;     // bucket key; default: client IP
+  message?: string;                 // 429 body message; default "Too Many Requests"
+}
+```
+
+The shape you pass to `rateLimiter()`. Every field is optional; `key` receives the
+Hono `Context` and returns the string that identifies the bucket.
+
+```ts
+import { rateLimiter, type RateLimiterOptions } from "@shaferllc/keel/core";
+
+const perUser: RateLimiterOptions = {
+  max: 30,
+  window: 60,
+  key: (c) => c.req.header("authorization") ?? "anon",
+  message: "Easy there — try again shortly.",
+};
+rateLimiter(perUser);
+```
+
+**Notes:** `window` is **seconds**, not milliseconds (it's multiplied by 1000
+internally). `key` is called on every request, so keep it cheap and pure. Returning
+a constant string collapses all clients into one shared bucket.

package/docs/redis.md

@@ -0,0 +1,178 @@
+# Redis
+
+A Redis integration built on a small pluggable driver — like the database and
+mail layers, the core imports no client, so it runs on Node and on the edge.
+Point it at Upstash (HTTP/`fetch`), ioredis, node-redis, or the built-in
+`MemoryRedis` for tests and local dev.
+
+## Using it
+
+Register a driver once (in a service provider), then reach Redis anywhere with
+`redis()`:
+
+```ts
+import { redis, setRedis, MemoryRedis } from "@shaferllc/keel/core";
+
+setRedis(new MemoryRedis()); // swap for an Upstash / ioredis adapter in production
+
+await redis().set("views", "1");
+await redis().incr("views");            // 2
+await redis().get("views");             // "2"
+await redis().set("token", "abc", { ex: 60 }); // expire in 60s
+await redis().del("token");
+```
+
+The default client is a `MemoryRedis`, so `redis()` works out of the box in
+tests without any setup.
+
+## Commands
+
+```ts
+const r = redis();
+
+await r.get(key);                 // string | null
+await r.set(key, value, { ex });  // { ex: seconds } or { px: ms }
+await r.del(...keys);             // number removed
+await r.exists(...keys);          // number present
+await r.has(key);                 // boolean
+
+await r.incr(key);                // +1
+await r.decr(key);                // -1
+await r.incrBy(key, 5);
+
+await r.expire(key, 60);          // set a TTL (seconds)
+await r.ttl(key);                 // seconds left, -1 (no expiry), -2 (no key)
+await r.keys("user:*");           // glob match
+await r.flushAll();               // clear everything
+```
+
+### JSON & remember
+
+`getJson` / `setJson` handle serialization, and `remember` is the read-through
+cache pattern:
+
+```ts
+await redis().setJson("user:1", { id: 1, name: "Ada" });
+const user = await redis().getJson<{ id: number; name: string }>("user:1");
+
+// Compute once, cache for 300s, serve from cache after:
+const stats = await redis().remember("stats", 300, () => computeStats());
+```
+
+## As a cache store
+
+`redisStore()` adapts the Redis client into a [`CacheStore`](./cache.md), so the
+cache can be Redis-backed — shared across instances instead of per-process:
+
+```ts
+import { Cache, redisStore, redis } from "@shaferllc/keel/core";
+
+const cache = new Cache(redisStore(redis()));
+await cache.remember("home", 60, () => renderHome());
+```
+
+## Writing a driver
+
+A driver is the `RedisConnection` interface. Here's the shape for an Upstash
+REST client over `fetch` (edge-safe):
+
+```ts
+import type { RedisConnection } from "@shaferllc/keel/core";
+
+const upstash = (url: string, token: string): RedisConnection => {
+  const call = (...args: (string | number)[]) =>
+    fetch(url, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}` },
+      body: JSON.stringify(args),
+    }).then((r) => r.json());
+  return {
+    async get(key) { return (await call("GET", key)).result ?? null; },
+    async set(key, value, o) {
+      await (o?.ex ? call("SET", key, value, "EX", o.ex) : call("SET", key, value));
+    },
+    async del(...keys) { return (await call("DEL", ...keys)).result; },
+    async exists(...keys) { return (await call("EXISTS", ...keys)).result; },
+    async incrBy(key, n) { return (await call("INCRBY", key, n)).result; },
+    async expire(key, s) { return (await call("EXPIRE", key, s)).result === 1; },
+    async ttl(key) { return (await call("TTL", key)).result; },
+    async keys(pattern) { return (await call("KEYS", pattern)).result; },
+    async flushAll() { await call("FLUSHALL"); },
+  };
+};
+setRedis(upstash(env("UPSTASH_URL"), env("UPSTASH_TOKEN")));
+```
+
+## In tests
+
+`MemoryRedis` is a full in-memory implementation with TTL support — no server:
+
+```ts
+import { setRedis, MemoryRedis, redis } from "@shaferllc/keel/core";
+
+setRedis(new MemoryRedis());
+await redis().incr("signups");
+assert.equal(await redis().get("signups"), "1");
+```
+
+## API reference
+
+### `redis()`
+
+`redis(): Redis`
+
+The default client. Register a driver with `setRedis` first; defaults to a
+`MemoryRedis`.
+
+### `setRedis(conn)`
+
+`setRedis(conn: RedisConnection): Redis`
+
+Registers the driver behind `redis()` and returns the wrapping client. Last call
+wins.
+
+### `Redis`
+
+Wraps a `RedisConnection` with conveniences.
+
+| Method | Signature | Notes |
+|--------|-----------|-------|
+| `get` | `(key) => Promise<string \| null>` | raw string value |
+| `set` | `(key, value, options?) => Promise<void>` | `{ ex: seconds }` / `{ px: ms }` |
+| `del` / `exists` | `(...keys) => Promise<number>` | count removed / present |
+| `has` | `(key) => Promise<boolean>` | `exists(key) > 0` |
+| `incr` / `decr` | `(key) => Promise<number>` | ±1 |
+| `incrBy` | `(key, amount) => Promise<number>` | atomic add |
+| `expire` | `(key, seconds) => Promise<boolean>` | false if the key is gone |
+| `ttl` | `(key) => Promise<number>` | seconds, `-1` no expiry, `-2` no key |
+| `keys` | `(pattern?) => Promise<string[]>` | glob; default `"*"` |
+| `flushAll` | `() => Promise<void>` | clear all |
+| `getJson` / `setJson` | JSON convenience over `get`/`set` | |
+| `remember` | `(key, seconds, factory) => Promise<T>` | read-through cache |
+
+### `MemoryRedis`
+
+`class MemoryRedis implements RedisConnection`
+
+An in-memory driver with TTL support — the default and ideal for tests. Not
+shared across processes.
+
+### `redisStore(client?)`
+
+`redisStore(client?: Redis): CacheStore`
+
+Adapts a `Redis` client into a `CacheStore` for the cache layer. Defaults to the
+global `redis()`.
+
+### Interfaces & types
+
+#### `RedisConnection`
+
+The driver seam — implement it to back Redis with any client. Methods: `get`,
+`set`, `del`, `exists`, `incrBy`, `expire`, `ttl`, `keys`, `flushAll`.
+
+#### `SetOptions`
+
+`interface SetOptions { ex?: number; px?: number }`
+
+Expiry for `set` — `ex` in seconds, `px` in milliseconds.