@ayepi/rate 0.1.0 → 0.2.0

package/README.md

@@ -144,7 +144,7 @@ This package ships dense, machine-oriented reference docs written for **AI codin
 - [`ayepi-rate-stores-doer.md`](./ayepi-rate-stores-doer.md)
 - [`ayepi-rate.md`](./ayepi-rate.md)
 
-They live next to the source in the [repo](https://github.com/ClickerMonkey/ayepi/tree/main/packages/rate) and are **not** shipped in the npm tarball.
+They ship with this package and also live in the [repo](https://github.com/ClickerMonkey/ayepi/tree/main/packages/rate).
 
 ## License
 

package/ayepi-rate-stores-doer.md

@@ -0,0 +1,287 @@
+<!--
+ayepi-rate-stores-doer.md — reference for `@ayepi/rate` (stores, Redis, and the rate-limited doer), written for coding agents.
+
+Copy this file into any project that depends on `@ayepi/rate` (e.g. into your repo's
+`docs/` or `.claude/` directory) and reference it from your agents and slash commands.
+It documents the public API, the patterns the package expects, and how it works under the
+hood, with copy-pasteable examples. Keep it in sync with the installed package version.
+
+Companion to `ayepi-rate.md` (overview + the `rateLimit` middleware + standalone primitives).
+-->
+
+# `@ayepi/rate` — stores, Redis, and the rate-limited doer
+
+Companion to **`ayepi-rate.md`** (overview, the `rateLimit` middleware, and the standalone
+`limiter`/`rateLimitResponse` primitives). This file covers the pluggable store interface,
+the bundled `memoryStore`, the distributed `@ayepi/rate/redis` store, the `rateLimitedDoer`,
+and how everything works under the hood.
+
+---
+
+## Stores
+
+```ts
+interface RateLimitRule {
+  readonly limit: number;
+  readonly window: number;
+  readonly algorithm: Algorithm;
+  /** Count over-limit (rejected) requests against the limit. Default `false`. */
+  readonly countRejected?: boolean;
+}
+
+interface RateLimitStore {
+  /** Record a hit for `key` under `rule` at time `now` (ms) and return the decision. */
+  consume(key: string, rule: RateLimitRule, now: number): MaybePromise<RateLimitResult>;
+  /** Clear all state for `key` (optional). */
+  reset?(key: string): MaybePromise<void>;
+}
+```
+
+A custom store should honor `rule.countRejected`: when it is falsy (the default), a request
+the store **rejects** must not consume budget (don't persist its increment). The bundled
+`memoryStore` and `redisStore` both do this; `token-bucket` is naturally exempt (it never
+charges a request it can't admit).
+
+The **algorithm lives in the store**, not in the limiter — that is what keeps the limit
+correct across instances. Implement `RateLimitStore` for any backend (Postgres, DynamoDB,
+Memcached, …); only `consume` is required.
+
+### `memoryStore` (default, bundled)
+
+```ts
+function memoryStore(): RateLimitStore
+```
+
+An in-process store implementing all three algorithms, zero dependencies. It is the
+default when no `store` is passed. Expired counters and idle token buckets are swept
+lazily (amortized: a sweep runs once per ~1000 `consume` calls; idle buckets are dropped
+after ~10 minutes of inactivity since they refill to full anyway). **Single process only**
+— two server instances each get their own independent budget. Use the Redis store to share
+a limit across pods.
+
+### `redisStore` — `@ayepi/rate/redis`
+
+```ts
+import { redisStore } from '@ayepi/rate/redis'
+
+function redisStore(client: RedisEvalLike, opts?: RedisStoreOptions): RateLimitStore
+
+interface RedisStoreOptions {
+  /** Extra key namespace prepended to every key (default `''`). */
+  readonly prefix?: string;
+}
+
+interface RedisEvalLike {
+  eval(script: string, numKeys: number, ...args: (string | number)[]): Promise<unknown>;
+}
+```
+
+A distributed store backed by Redis (ioredis). Each algorithm runs as a single atomic Lua
+script, mirroring `memoryStore`'s semantics, so a limit is enforced **across all
+instances**. `ioredis` is an **optional peer dependency** — install it only if you use this
+store. An ioredis `Redis` instance satisfies `RedisEvalLike`.
+
+```ts
+// shared.ts
+import { rateLimit } from '@ayepi/rate'
+const limit = rateLimit({ requires: [auth] })
+
+// server.ts
+import Redis from 'ioredis'
+import { rateLimit } from '@ayepi/rate/server'
+import { redisStore } from '@ayepi/rate/redis'
+
+implement(api).middleware(rateLimit.server(limit, {
+  key: (io) => io.ctx.user.id,
+  limit: 100,
+  window: 60_000,
+  store: redisStore(new Redis(process.env.REDIS_URL!), { prefix: 'app:' }), // `store` is a .server option
+}))
+```
+
+Two stores sharing one Redis enforce a **shared** budget — that is the whole point of the
+distributed store (verified by the integration test). `reset(key)` issues a `DEL`.
+
+> Note `redisStore`'s `prefix` is a **second** namespace, applied in addition to the
+> limiter's own `prefix` (default `'rl:'`). The effective Redis key is
+> `redisPrefix + limiterPrefix + key` (e.g. `app:rl:user-1`).
+
+---
+
+## `rateLimitedDoer` — gating task start rate
+
+```ts
+function rateLimitedDoer(opts: RateLimitedDoerOptions): Doer
+
+interface RateLimitedDoerOptions extends LimiterOptions {
+  /** Limit key — a single shared bucket by default (`'doer'`), or derived per task. */
+  readonly key?: string | ((opts: DoerTaskOptions) => string);
+  /** Floor on the re-check delay for deferred tasks (ms, default 50). */
+  readonly retryFloor?: number;
+  /** Clock injection (default `Date.now`). */
+  readonly now?: () => number;
+  /** The doer that actually runs admitted tasks (default `unlimitedDoer`). Compose policies. */
+  readonly doer?: Doer;
+}
+```
+
+(`RateLimitedDoerOptions` extends `LimiterOptions` — see `ayepi-rate.md` for
+`limit`/`window`/`algorithm`/`store`/`prefix`.)
+
+A `Doer` (from `@ayepi/core/doer`) that caps the **start rate** of tasks using the same
+`limiter()` primitive (and the same pluggable store/algorithm) the middleware uses. It does
+**not** run tasks itself — when the limiter admits a task it hands it to an **inner doer**
+(default `unlimitedDoer()`), so you can compose a rate cap with a concurrency/ordering
+policy. Excess tasks wait, **oldest-first**; with a distributed store this rate-limits
+**across a fleet**.
+
+A `Doer` exposes `available()`, `do(task, opts?)`, and `done()` — see the doer section of
+the core docs. `rateLimitedDoer`'s `available()` is `min(limit − pending, inner.available())`.
+
+### Example — cap an `@ayepi/work` engine
+
+```ts
+import { rateLimitedDoer } from '@ayepi/rate'
+import { createWork } from '@ayepi/work'
+
+const doer = rateLimitedDoer({ limit: 100, window: 60_000, algorithm: 'token-bucket' })
+const w = createWork({ work: [sendEmail] as const, doer }) // ≤ 100 sends/min
+```
+
+### Example — compose a rate cap with a concurrency cap
+
+```ts
+import { rateLimitedDoer } from '@ayepi/rate'
+import { priorityDoer } from '@ayepi/core/doer'
+
+// ≤ 100 starts/min AND ≤ 4 running concurrently
+const doer = rateLimitedDoer({
+  limit: 100,
+  window: 60_000,
+  doer: priorityDoer({ max: 4 }),
+})
+```
+
+### Example — per-key buckets
+
+```ts
+// each `group` gets its own bucket of `limit`
+const doer = rateLimitedDoer({
+  limit: 10,
+  window: 60_000,
+  key: (o) => o.group ?? 'default', // o is the task's DoerTaskOptions ({} if none given)
+})
+```
+
+With a static `key` string (or the default `'doer'`) all tasks share one bucket.
+
+---
+
+## How it works under the hood
+
+### The three algorithms
+
+All three are implemented inside the store. `memoryStore` and `redisStore` produce the
+same decisions; Redis just runs each as one atomic Lua script.
+
+- **`fixed-window`** (default) — a counter per `[key, window]`. The first hit in a window
+  sets the reset time to `now + window`; a hit is `allowed` while `count < limit` and then
+  increments the counter. Cheap, but allows up to `2·limit` across a window boundary
+  (burst at the end of one window + start of the next).
+
+- **`sliding-window`** — keeps the current window's counter **and** reads the immediately
+  previous window's counter, then weights the previous count by how far into the current
+  window you are: `weighted = prevCount · (window − elapsed)/window + curCount`; a hit is
+  `allowed` while admitting it keeps `weighted <= limit`, and only then increments the
+  current counter. Smooths the boundary burst of fixed-window. (It stores sub-keys as
+  `key|windowStart`; `reset` deletes those sub-keys too.)
+
+- **`token-bucket`** — a bucket of capacity `limit` refilling at `limit/window` tokens per
+  ms. Each request costs 1 token; `allowed` if at least 1 token is available, otherwise
+  `retryAfter` is the time to refill the missing fraction. Permits bursts up to `limit`
+  while enforcing the long-run rate.
+
+By default a **rejected** request does not consume budget (the counter isn't incremented;
+token-bucket never had the token to spend). This keeps a client from extending its own
+block by hammering — most visible in `sliding-window`, where a counted rejection would
+weigh into the next window. Set `countRejected: true` on the rule/options for the stricter
+"every attempt counts" behavior.
+
+`reset`, `remaining`, and `retryAfter` are reported in **milliseconds** in
+`RateLimitInfo`; `rateLimitResponse` converts `reset`/`retryAfter` to **seconds** for the
+`ratelimit-reset` / `retry-after` headers (and emits `retry-after` only when the request
+was rejected).
+
+### Store consultation
+
+`limiter()` builds a `RateLimitRule` from `{ limit, window, algorithm }`, prepends
+`prefix` (default `'rl:'`) to the key, and calls `store.consume(prefixedKey, rule, now)`.
+The store records the hit and returns `{ allowed, limit, remaining, reset, retryAfter }`.
+The limiter is stateless beyond its rule + store reference — all per-key state lives in the
+store, which is why a distributed store gives a distributed limit.
+
+### Composition with the core middleware chain
+
+`rateLimit.server(def, opts)` binds a standard `@ayepi/core` middleware whose `run`:
+
+1. builds `kio = { req, ctx }`;
+2. if `skip(kio)` → calls `io.next({ ratelimit: <full budget> })` (admit, no store hit);
+3. otherwise `await limiter.check(key(kio))`;
+4. if **not** allowed → returns `rateLimitResponse(info, { status, headers, message })` —
+   a `Response`, which `@ayepi/core` treats as a **short-circuit**: the rest of the chain
+   and the handler are skipped (HTTP sends the `Response`; ws turns it into an error
+   frame);
+5. if allowed → `io.next({ ratelimit: info })`, merging `ratelimit` into the handler
+   context.
+
+Because `requires` is declared on the **def** and forwarded into the bound middleware, the
+limiter's dependency middleware run first and their context is available — see
+`ayepi-core-middleware.md` for how `requires` are auto-included and topologically ordered.
+
+### The doer abstraction
+
+`rateLimitedDoer` keeps a `pending` queue. On each `drain`:
+
+- if the inner doer has no capacity (`inner.available() <= 0`), it arms a short re-check
+  timer and stops;
+- otherwise it picks the **oldest** pending task (by `createdAt`, then submission `seq`),
+  calls `limiter.check(keyOf(task), now())`;
+- if denied, it arms a timer for `max(retryFloor, retryAfter)` and stops (drains again when
+  the limiter would allow);
+- if admitted, it removes the task and calls `inner.do(task.run, task.opts)`.
+
+`done()` resolves once `pending` is empty **and** the inner doer's `done()` resolves. The
+re-check timer is `unref`'d, so it won't keep a process alive on its own.
+
+---
+
+## Gotchas / constraints
+
+- **`memoryStore` is per-process.** Multiple instances each get an independent budget. For
+  a shared limit across pods, use `@ayepi/rate/redis` (or another distributed
+  `RateLimitStore`).
+- **`fixed-window` allows boundary bursts** (up to ~2·limit across a window edge). Use
+  `sliding-window` or `token-bucket` if that matters.
+- **Header time units differ from `RateLimitInfo`.** `RateLimitInfo.reset`/`retryAfter` are
+  **ms**; the `ratelimit-reset`/`retry-after` headers are **seconds** (`Math.ceil`'d).
+- **Custom `headers` replace, not merge.** A `headers` function returns the full header map;
+  the default `ratelimit-*` headers are not added alongside it.
+- **`message` arity differs** between `rateLimit` (`(info, io)`) and `rateLimitResponse`
+  (`(info)`).
+- **`skip` short-circuits the store** — skipped requests still get a `ctx.ratelimit` (full
+  budget, `reset`/`retryAfter` = 0) but record no hit.
+- **`redisStore` needs `ioredis`** (optional peer dep) and a working `eval` (Lua). Its
+  `prefix` stacks on top of the limiter's own `prefix`.
+- **`rateLimitedDoer` does not execute tasks** — it admits and hands off to an inner doer.
+  Without an inner concurrency cap (`unlimitedDoer` default), admitted tasks run with no
+  concurrency limit; the rate cap only governs *start rate*.
+- **Import paths:** `@ayepi/rate`, `@ayepi/rate/server`, and `@ayepi/rate/redis` exist.
+  `rateLimitedDoer`, `limiter`, `memoryStore`, and `rateLimitResponse` are exported from the
+  main `@ayepi/rate` entry; `rateLimit`'s `.server` binder is on `@ayepi/rate/server`.
+
+---
+
+See also: **`ayepi-rate.md`** (overview, the `rateLimit` middleware, standalone primitives),
+**`ayepi-core-middleware.md`** (middleware composition, `requires`, `StackCtx`,
+`.group()`/`.endpoint()`, short-circuit `Response` semantics), and `@ayepi/core/doer` (the
+`Doer` interface and bundled policies `unlimitedDoer`/`priorityDoer`/`ageDoer`/`balancedDoer`).

package/ayepi-rate.md

@@ -0,0 +1,452 @@
+<!--
+ayepi-rate.md — reference for `@ayepi/rate`, written for coding agents.
+
+Copy this file into any project that depends on `@ayepi/rate` (e.g. into your repo's
+`docs/` or `.claude/` directory) and reference it from your agents and slash commands.
+It documents the public API, the patterns the package expects, and how it works under the
+hood, with copy-pasteable examples. Keep it in sync with the installed package version.
+-->
+
+# `@ayepi/rate`
+
+Rate-limiting middleware for [`@ayepi/core`](https://www.npmjs.com/package/@ayepi/core).
+It derives a **key from the request context** (the authenticated user, an IP, an API
+token, …), checks it against a **store + algorithm**, and — when the limit is exceeded —
+**short-circuits the middleware chain with a 429 `Response`** (which `@ayepi/core` maps to
+a websocket error frame for ws transports). On allowed requests the handler receives
+`ctx.ratelimit` info. The same limiting primitive is reusable outside middleware (any
+handler, queue/cron worker, CLI) and powers a `rateLimitedDoer` that caps task **start
+rate** for `@ayepi/work`. Use it whenever you need per-user / per-key throttling on an
+ayepi API, with an in-memory default store and a distributed Redis store for limiting
+across instances.
+
+```sh
+pnpm add @ayepi/rate @ayepi/core
+# optional, only for the Redis store (peer dependency, optional):
+pnpm add ioredis
+```
+
+It ships as a **def / impl split**:
+
+- `@ayepi/rate` (frontend-safe) exports `rateLimit(opts?)`, a middleware **def factory**.
+  The def declares the contract that goes in the spec and **contributes `{ ratelimit }`** to
+  the handler context. A spec importing only this entry is safe to bundle for the frontend.
+  The standalone `limiter` / `memoryStore` / `rateLimitResponse` / `rateLimitedDoer`
+  primitives also live on this entry, unchanged.
+- `@ayepi/rate/server` augments `rateLimit` with **`.server(def, opts)`**, which binds the
+  policy. The policy options (`key`, `limit`, `window`, `algorithm`, `store`, `prefix`,
+  `countRejected`, `status`, `message`, `headers`, `alwaysHeaders`, `skip`) live here. Bind
+  the pair with `implement(api).middleware(...)`.
+
+Cross-reference: middleware composition (def vs impl, `requires`, `StackCtx`,
+`.group()`/`.endpoint()`), the `implement(api)` builder, and short-circuit semantics are
+documented in **`ayepi-core-middleware.md`** — read it alongside this file.
+
+---
+
+## At a glance
+
+```ts
+// shared.ts — frontend-safe
+import { rateLimit } from '@ayepi/rate'
+
+const limit = rateLimit({
+  requires: [auth],            // ctx.user is available + typed inside `key`/`skip`/`message` on the impl
+})
+
+const api = spec({ endpoints: { ...limit.group({ getThing: { /* … */ } }) } })
+```
+
+```ts
+// server.ts — binds the policy, with implement(api)
+import { rateLimit } from '@ayepi/rate/server'
+import { implement } from '@ayepi/core'
+
+const app = implement(api)
+  // 100 requests / minute per authenticated user, sliding window
+  .middleware(rateLimit.server(limit, {
+    key: (io) => io.ctx.user.id,
+    limit: 100,
+    window: 60_000,
+    algorithm: 'sliding-window',
+  }))
+  .server()
+```
+
+On allowed requests the handler reads `ctx.ratelimit` (`{ limit, remaining, reset,
+retryAfter }`); on exceeded requests the chain short-circuits with the 429 before the
+handler runs.
+
+> **Every middleware in a chain must be bound.** `implement(api)` is a chainable builder;
+> bind a def → impl pair with `.middleware(def, impl)` or `.middleware(boundPair)` (where
+> `rateLimit.server(def, opts)` returns the bound pair). If any middleware reachable from the
+> spec is left unbound, `.server()` throws.
+
+---
+
+## Public API surface
+
+Everything below is exported. `@internal` symbols are intentionally omitted.
+
+### Main entry `@ayepi/rate` (frontend-safe)
+
+| Export | Kind | Purpose |
+| --- | --- | --- |
+| `rateLimit` | function | **Def factory** — declares the middleware contract (`{ ratelimit }`). |
+| `limiter` | function | Standalone limiter primitive (`check`/`reset`/`rule`). |
+| `rateLimitResponse` | function | Build a 429 `Response` from limiter info. |
+| `rateLimitHeaders` | function | Compute the `RateLimit-*` header map from limiter info. |
+| `memoryStore` | function | The bundled in-process store (all three algorithms). |
+| `rateLimitedDoer` | function | A `Doer` that caps task **start rate**. |
+| `Algorithm` | type | `'fixed-window' \| 'sliding-window' \| 'token-bucket'`. |
+| `RateLimitInfo` | interface | Limiter state exposed to handlers + headers. |
+| `RateLimitResult` | interface | `RateLimitInfo` + `allowed`. |
+| `RateLimitRule` | interface | `{ limit, window, algorithm, countRejected? }` — what a store evaluates. |
+| `RateLimitStore` | interface | Pluggable backend (`consume` + optional `reset`). |
+| `RateKeyIO` | interface | `{ req, ctx }` passed to `key`/`skip`/`message`. |
+| `LimiterOptions` | interface | Base config (`limit`/`window`/`algorithm`/`store`/`prefix`). |
+| `RateLimitResponseOptions` | interface | `status`/`message`/`headers` for `rateLimitResponse`. |
+| `RateLimitDefOptions` | interface | Options for the `rateLimit` def (`name`/`requires`). |
+| `RateLimitedDoerOptions` | interface | Options for `rateLimitedDoer`. |
+| `Limiter` | interface | The object `limiter()` returns. |
+
+### Server subpath `@ayepi/rate/server`
+
+| Export | Kind | Purpose |
+| --- | --- | --- |
+| `rateLimit` | function | Same name, **augmented with `.server(def, opts)`** to bind the policy. |
+| `RateLimitServerOptions` | interface | The policy options for `.server` (extends `LimiterOptions`). |
+
+### Redis subpath `@ayepi/rate/redis`
+
+| Export | Kind | Purpose |
+| --- | --- | --- |
+| `redisStore` | function | A distributed `RateLimitStore` backed by ioredis. |
+| `RedisStoreOptions` | interface | `{ prefix? }`. |
+| `RedisEvalLike` | interface | Minimal ioredis surface (`eval`) the store needs. |
+
+> The package exposes exactly three import specifiers: `@ayepi/rate`, `@ayepi/rate/server`,
+> and `@ayepi/rate/redis` (per `package.json#exports`). `rateLimitedDoer` and the standalone
+> primitives live on the **main entry** — import them from `@ayepi/rate`, not a `/doer`
+> subpath. `rateLimit`'s `.server` binder is the **only** thing on `@ayepi/rate/server`.
+
+---
+
+## `rateLimit` — the def + the `.server` impl
+
+### The def (`@ayepi/rate`)
+
+```ts
+function rateLimit<const R extends readonly AnyMiddleware[] = readonly []>(
+  opts?: RateLimitDefOptions<R>,
+): RateLimitDef<{ ratelimit: RateLimitInfo }, R>
+
+interface RateLimitDefOptions<R extends readonly AnyMiddleware[]> {
+  /** Middleware this one depends on — their context is available (and typed) in `key`/`skip`/`message` on the impl. */
+  readonly requires?: R;
+  /** Middleware name for docs/debugging (default `'rateLimit'`). */
+  readonly name?: string;
+}
+```
+
+The def declares a `@ayepi/core` middleware that **provides `{ ratelimit: RateLimitInfo }`**
+to the handler context on allowed requests (and short-circuits with a 429 otherwise, once
+bound). It is frontend-safe and carries no policy. Compose the def exactly like any other
+ayepi middleware — attach it with `.endpoint()`, `.group()`, `use(...)` / `.with()`, or list
+it in another middleware's `requires` (see `ayepi-core-middleware.md`).
+
+### The impl (`@ayepi/rate/server`)
+
+```ts
+rateLimit.server: <const R extends readonly AnyMiddleware[]>(
+  def: RateLimitDef<{ ratelimit: RateLimitInfo }, R>,
+  opts: RateLimitServerOptions<StackCtx<R>, R>,
+) => BoundMiddleware  // pass to implement(api).middleware(...)
+```
+
+`.server` binds the policy and returns the bound pair. It composes with the chainable
+`implement(api)` builder: `implement(api).middleware(rateLimit.server(def, opts))`.
+
+### `RateLimitServerOptions`
+
+```ts
+interface RateLimitServerOptions<Ctx extends object, R extends readonly AnyMiddleware[]>
+  extends LimiterOptions {
+  /** Derive the rate-limit key from the request context (e.g. `io.ctx.user.id`). */
+  readonly key: (io: RateKeyIO<Ctx>) => string;
+  /** Over-limit status code (default `429`). */
+  readonly status?: number;
+  /** Over-limit body — string, JSON value, or a function of (info, io). */
+  readonly message?: string | Json | ((info: RateLimitInfo, io: RateKeyIO<Ctx>) => string | Json);
+  /** Response headers (see `RateLimitResponseOptions`). */
+  readonly headers?: boolean | ((info: RateLimitInfo) => Record<string, string>);
+  /** Also emit the `RateLimit-*` headers on allowed/skipped responses (default `false`). */
+  readonly alwaysHeaders?: boolean;
+  /** Bypass the limiter for some requests (e.g. an allow-list). */
+  readonly skip?: (io: RateKeyIO<Ctx>) => boolean;
+  /** Serve through (as allowed) when the **store** errors, instead of failing the request. Default `false` (fail-closed). */
+  readonly failOpen?: boolean;
+  /** Observe a store error (e.g. Redis down). Fires regardless of `failOpen`. Off by default; must not throw. */
+  readonly onError?: (err: unknown) => void;
+}
+```
+
+> **Store errors.** By default the limiter is **fail-closed**: if the store (e.g. a Redis
+> outage) throws, the error propagates and the request is rejected — a store outage doesn't
+> silently lift the limit. Set `failOpen: true` to serve such requests through instead, and/or
+> `onError` to observe the failure (it fires either way). `rateLimitedDoer` takes an `onError`
+> too: a store error there is reported and admission retried — it never strands pending tasks.
+
+…plus everything from `LimiterOptions`:
+
+```ts
+interface LimiterOptions {
+  /** Max requests (or token-bucket capacity) per window. */
+  readonly limit: number;
+  /** Window length in milliseconds (also the token refill period). */
+  readonly window: number;
+  /** Algorithm (default `'fixed-window'`). */
+  readonly algorithm?: Algorithm;
+  /** Backend store (default an in-process `memoryStore`). */
+  readonly store?: RateLimitStore;
+  /** Key prefix/namespace (default `'rl:'`). */
+  readonly prefix?: string;
+  /** Count requests that are themselves rejected (over-limit) against the limit (default `false`). */
+  readonly countRejected?: boolean;
+}
+```
+
+Notes grounded in the source:
+
+- **`key` is required** (a `.server` option). It runs per request; its return value is the
+  limiter key (the configured `prefix` is prepended internally — default `'rl:'`).
+- **`requires`** is declared on the **def** and flows context types into `key`/`skip`/`message`
+  on the impl. With `requires: [auth]`, `io.ctx.user` is typed. Without `requires`, `io.ctx`
+  is the empty context and you must read from `io.req` (e.g. `io.req.headers.get('x-user')`).
+- **`skip`** runs before the limiter. When it returns `true`, the request is admitted with
+  a synthetic `ctx.ratelimit` of `{ limit, remaining: limit, reset: 0, retryAfter: 0 }` —
+  no store hit.
+- **`countRejected`** (default `false`) — a request that is **itself rejected** (over the
+  limit) does **not** count against the limit, so a client can't extend its own block by
+  continuing to hammer the endpoint. This matters most for `sliding-window`, where a
+  counted rejection would carry into the next window. Set `true` for the stricter "every
+  attempt consumes budget" behavior. (No effect on `token-bucket`, which never charges a
+  request it can't admit.) Threads through to the Redis store as well.
+- **`alwaysHeaders`** (default `false`) — also emit the `RateLimit-*` headers on **allowed**
+  (and skipped) responses, not just the 429, so every response advertises the caller's
+  remaining budget. Uses the same `headers` formatting; `Retry-After` is omitted when the
+  request wasn't rate-limited.
+- **`message`** for the middleware takes `(info, io)`; `rateLimitResponse`'s standalone
+  `message` takes only `(info)`. `rateLimit.server` adapts between them.
+
+### `RateKeyIO` / `RateLimitInfo`
+
+```ts
+interface RateKeyIO<Ctx extends object> {
+  readonly req: Request;
+  readonly ctx: Ctx;
+}
+
+interface RateLimitInfo {
+  readonly limit: number;      // the configured request limit for the window
+  readonly remaining: number;  // requests/tokens left before the limit is hit
+  readonly reset: number;      // ms until the window/bucket resets
+  readonly retryAfter: number; // ms to wait before retrying (0 when allowed)
+}
+```
+
+### Example — apply to a group of endpoints
+
+```ts
+// shared.ts
+import { rateLimit } from '@ayepi/rate'
+import { spec } from '@ayepi/core'
+
+const limit = rateLimit({ requires: [auth] })
+
+const api = spec({
+  endpoints: {
+    ...limit.group({
+      listThings: { response: z.array(Thing) },
+      createThing: { body: NewThing, response: Thing },
+    }),
+  },
+})
+
+// server.ts
+import { rateLimit } from '@ayepi/rate/server'
+
+implement(api).middleware(rateLimit.server(limit, {
+  key: (io) => io.ctx.user.id,
+  limit: 100,
+  window: 60_000,
+  algorithm: 'sliding-window',
+}))
+```
+
+### Example — a single endpoint, reading `ctx.ratelimit`
+
+```ts
+// shared.ts
+const limit = rateLimit({ requires: [auth] })
+const api = spec({
+  endpoints: { hit: limit.endpoint({ response: z.object({ ok: z.boolean(), remaining: z.number() }) }) },
+})
+
+// server.ts
+import { rateLimit } from '@ayepi/rate/server'
+
+const app = implement(api)
+  .middleware(rateLimit.server(limit, { key: (io) => io.ctx.user.id, limit: 2, window: 60_000 }))
+  .handlers({
+    hit: ({ ratelimit }) => ({ ok: true, remaining: ratelimit.remaining }),
+  })
+  .server()
+```
+
+### Example — per-IP limiting without `requires`
+
+```ts
+// shared.ts
+const limit = rateLimit()
+// server.ts
+rateLimit.server(limit, {
+  key: (io) => io.req.headers.get('x-forwarded-for') ?? 'anon',
+  limit: 20,
+  window: 1_000,
+})
+```
+
+### Example — choosing an algorithm
+
+```ts
+rateLimit.server(limit, { key, limit: 100, window: 60_000, algorithm: 'fixed-window'   }) // default; simple counter per window
+rateLimit.server(limit, { key, limit: 100, window: 60_000, algorithm: 'sliding-window' }) // smoother; weights previous window
+rateLimit.server(limit, { key, limit: 100, window: 60_000, algorithm: 'token-bucket'   }) // steady rate, bursts up to `limit`
+```
+
+### Example — custom 429 (status, JSON body, headers, skip)
+
+```ts
+rateLimit.server(limit, {
+  key: (io) => clientIp(io.req),
+  limit: 20,
+  window: 1_000,
+  status: 503,                                                            // default 429
+  message: (info, io) => ({ error: 'slow down', retryAfter: info.retryAfter }), // string | JSON | fn(info, io)
+  headers: (info) => ({ 'x-ratelimit': String(info.limit) }),            // custom headers REPLACE the defaults
+  skip: (io) => io.req.headers.get('x-admin') === '1',                   // allow-list bypass
+})
+```
+
+- `headers: true` (default) emits draft `ratelimit-limit` / `ratelimit-remaining` /
+  `ratelimit-reset` — plus `retry-after` **only when the request was rejected** (`reset`
+  and `retry-after` in **seconds**, `Math.ceil`'d).
+- `headers: false` emits none of those.
+- A `headers` function returns your own map and **replaces** the defaults entirely.
+- `alwaysHeaders: true` applies the same formatting to allowed/skipped responses too (via
+  `io.setHeader`), so clients always see their remaining budget.
+- A string `message` is sent as `text/plain; charset=utf-8`; a JSON `message` is
+  `JSON.stringify`'d as `application/json`. Default body is `'Too many requests'`.
+
+---
+
+## Standalone primitives (no middleware)
+
+The middleware impl is a thin wrapper over `limiter()` + `rateLimitResponse()`. Both stay on
+the **main `@ayepi/rate` entry**, unchanged by the def/impl split — use them directly in a
+plain handler, a worker, a CLI, or another framework.
+
+### `limiter`
+
+```ts
+function limiter(opts: LimiterOptions): Limiter
+
+interface Limiter {
+  /** Record a hit for `key` (at `now`, default `Date.now()`) and return the decision. */
+  check(key: string, now?: number): MaybePromise<RateLimitResult>;
+  /** Clear all state for `key`. */
+  reset(key: string): MaybePromise<void>;
+  /** The rule this limiter enforces. */
+  readonly rule: RateLimitRule;
+}
+```
+
+`RateLimitResult` is `RateLimitInfo` plus `readonly allowed: boolean`.
+
+```ts
+import { limiter, reject } from '@ayepi/rate' // reject is from @ayepi/core
+
+const lim = limiter({ limit: 100, window: 60_000, algorithm: 'token-bucket' })
+
+const { allowed, remaining, retryAfter } = await lim.check(userId)
+if (!allowed) throw reject(429, 'RATE_LIMITED', `retry in ${retryAfter}ms`)
+
+await lim.reset(userId) // clear a key
+```
+
+`check` may return a value or a promise depending on the store (`memoryStore` is sync,
+`redisStore` is async) — `await` it to handle both.
+
+### `rateLimitResponse`
+
+```ts
+function rateLimitResponse(info: RateLimitInfo, opts?: RateLimitResponseOptions): Response
+
+interface RateLimitResponseOptions {
+  readonly status?: number;  // default 429
+  readonly message?: string | Json | ((info: RateLimitInfo) => string | Json);
+  readonly headers?: boolean | ((info: RateLimitInfo) => Record<string, string>);
+}
+```
+
+Builds the same 429 the middleware emits, but as a free-standing `Response` you can return
+from any handler that called `limiter()` directly:
+
+```ts
+const result = await lim.check(userId)
+if (!result.allowed) return rateLimitResponse(result, { message: { error: 'nope' } })
+```
+
+### `rateLimitHeaders`
+
+```ts
+function rateLimitHeaders(
+  info: RateLimitInfo,
+  headers?: boolean | ((info: RateLimitInfo) => Record<string, string>), // default true
+): Record<string, string>
+```
+
+The header map `rateLimitResponse` and the middleware's `alwaysHeaders` both use:
+`true` → draft `ratelimit-limit`/`-remaining`/`-reset` (plus `retry-after` only when
+`info.retryAfter > 0`); `false` → `{}`; a function → your own map. Handy if you call
+`limiter()` directly and want to set the same headers on your own `Response`:
+
+```ts
+const r = await lim.check(userId)
+for (const [k, v] of Object.entries(rateLimitHeaders(r))) res.headers.set(k, v)
+```
+
+---
+
+## Stores, the Redis store, and the rate-limited doer
+
+These topics — the pluggable `RateLimitStore` interface, the bundled `memoryStore`, the
+distributed `@ayepi/rate/redis` store, `rateLimitedDoer`, the algorithm internals, and the
+gotchas — live in the companion file to keep this one focused:
+
+- **[`ayepi-rate-stores-doer.md`](./ayepi-rate-stores-doer.md)**
+  - **Stores** — `RateLimitStore` interface, `memoryStore` (default, bundled),
+    `redisStore` (`@ayepi/rate/redis`) + `RedisStoreOptions` / `RedisEvalLike`.
+  - **`rateLimitedDoer`** — capping task start rate, composing with an inner doer,
+    per-key buckets.
+  - **How it works under the hood** — the three algorithms, store consultation, middleware
+    chain composition, the doer drain loop.
+  - **Gotchas / constraints.**
+
+---
+
+See also: **`ayepi-rate-stores-doer.md`** (stores, Redis, the doer, internals, gotchas),
+**`ayepi-core-middleware.md`** (middleware composition, `requires`, `StackCtx`,
+`.group()`/`.endpoint()`, short-circuit `Response` semantics) and `@ayepi/core/doer` (the
+`Doer` interface and bundled policies `unlimitedDoer`/`priorityDoer`/`ageDoer`/`balancedDoer`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ayepi/rate",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Rate-limiting middleware for @ayepi/core — pluggable stores, multiple algorithms, customizable 429 responses",
   "license": "MIT",
   "publishConfig": {
@@ -18,7 +18,8 @@
   "type": "module",
   "sideEffects": false,
   "files": [
-    "dist"
+    "dist",
+    "ayepi-*.md"
   ],
   "exports": {
     ".": {
@@ -58,7 +59,7 @@
   },
   "peerDependencies": {
     "ioredis": "^5",
-    "@ayepi/core": "^0.1.0"
+    "@ayepi/core": "^0.2.0"
   },
   "peerDependenciesMeta": {
     "ioredis": {
@@ -73,7 +74,7 @@
     "tsdown": "^0.12.0",
     "vitest": "^2.1.8",
     "zod": "^4.4.3",
-    "@ayepi/core": "0.1.0"
+    "@ayepi/core": "0.2.0"
   },
   "keywords": [
     "ayepi",