@zerotal/arch 1.7.0

package/docs/rate-limiting.md

@@ -0,0 +1,253 @@
+---
+title: Rate Limiting
+description: Cap how many requests an actor can make in a time window and respond with 429 when they exceed it.
+---
+
+# Rate Limiting
+
+Rate limiting protects routes from abuse by counting requests per actor and
+rejecting anything over the threshold. Zerotal ships two complementary limiters in
+`@zerotal/core` — both built in, with nothing to install or register.
+
+- **`ThrottleMiddleware`** — a quick inline limiter you attach to a route or the
+  global pipeline.
+- **`RateLimiter`** — a **named**, reusable limiter you define once and apply by
+  name, with rich keying strategies and runtime inspection.
+
+Both use an in-memory sliding window and respond with **429 Too Many Requests**,
+setting `Retry-After` and `X-RateLimit-*` headers when the limit is exceeded.
+
+## Getting Started
+
+Rate limiting is built into `@zerotal/core` — nothing to install:
+
+```typescript
+import { ThrottleMiddleware } from "zerotal";
+```
+
+## Which should I use?
+
+- Reach for **`ThrottleMiddleware`** for a one-off limit on a single route or the
+  global pipeline — the options live right where you attach it.
+- Reach for **`RateLimiter`** when the same limit is reused across many routes, or
+  when you want to query and reset it at runtime (e.g. clearing failed-login
+  counters after a successful sign-in).
+
+## ThrottleMiddleware — inline
+
+Attach it directly with the static `.with(options)` factory, which returns a
+ready-to-use middleware class:
+
+```typescript
+// in routes/web.ts (or wherever you register routes)
+import { ThrottleMiddleware } from "zerotal";
+
+// Global: 120 requests / minute per IP
+app.use([ThrottleMiddleware.with({ maxAttempts: 120, windowSeconds: 60 })]);
+
+// Per-route: 5 login attempts / minute
+Router.post("/login", AuthController, "login", [
+  ThrottleMiddleware.with({ maxAttempts: 5, windowSeconds: 60 }),
+]);
+
+// Key by authenticated user instead of IP
+ThrottleMiddleware.with({
+  maxAttempts: 1000,
+  windowSeconds: 3600,
+  keyResolver: (ctx) => String(ctx.user?.id ?? ctx.ip()),
+});
+```
+
+| Option           | Required | Default     | Description                                                 |
+| ---------------- | -------- | ----------- | ----------------------------------------------------------- |
+| `maxAttempts`    | yes      | —           | Max requests within the window.                             |
+| `windowSeconds`  | no       | `60`        | Window length in seconds.                                   |
+| `keyResolver`    | no       | client IP   | Function returning the rate-limit key for a request.        |
+| `trustedProxies` | no       | `undefined` | Number of trusted upstream proxies (see the warning below). |
+
+> **Danger** — With `trustedProxies` left `undefined`, the limiter trusts the
+> leftmost `X-Forwarded-For` entry, which a client behind a real proxy can forge
+> to dodge the limit. Set `trustedProxies` to the exact number of proxies in
+> front of your server (`0` when there is none) so the real client IP is used.
+
+## RateLimiter — named limiters
+
+Define a limiter once (typically in a `ServiceProvider.onBooted()`), then apply it
+by name anywhere. Definitions are fluent, and `.register()` activates them:
+
+```typescript
+// in a ServiceProvider's onBooted()
+import { RateLimiter } from "zerotal";
+
+// 1000 req/hour per authenticated user (falls back to IP when unauthenticated)
+RateLimiter.for("api").limit(1000).every(3600).byUser().register();
+
+// 5 login attempts per minute, per IP
+RateLimiter.for("login").limit(5).every(60).byIp().register();
+
+// 500 req/min keyed by an API-key header (unknown key → per IP)
+RateLimiter.for("partner").limit(500).every(60).byApiKey("x-api-key").register();
+
+// Custom key
+RateLimiter.for("upload")
+  .limit(10)
+  .every(3600)
+  .by((ctx) => `user:${ctx.user?.id ?? "anon"}`)
+  .register();
+```
+
+> **Warning** — `.register()` is required. A definition that is never registered
+> cannot be resolved by `RateLimiter.middleware()`, which throws if the name is
+> unknown.
+
+### Keying strategies
+
+Each `.by*()` call sets how requests are bucketed. The default (no `.by*()` call)
+is the client IP.
+
+| Method               | Keys on                                     | Falls back to            |
+| -------------------- | ------------------------------------------- | ------------------------ |
+| `.byUser()`          | `ctx.user.id`                               | IP when unauthenticated  |
+| `.byApiKey(header?)` | `x-api-key` header (or a custom header)     | IP when header is absent |
+| `.byIp()`            | Socket IP → `X-Forwarded-For` → `X-Real-IP` | `'unknown'`              |
+| `.by(fn)`            | Return value of your function               | —                        |
+
+### Applying a named limiter
+
+`RateLimiter.middleware(name)` returns the middleware instance for a registered
+limiter, ready to drop into a route or group:
+
+```typescript
+// in routes/web.ts
+import { RateLimiter } from "zerotal";
+
+Router.post("/login", AuthController, "login", [RateLimiter.middleware("login")]);
+
+Router.group({ prefix: "/api", middleware: [RateLimiter.middleware("api")] }, () => {
+  Router.get("/users", UserController, "index");
+});
+```
+
+### Inspecting and resetting at runtime
+
+Check or clear a limiter imperatively — e.g. reset failed-login counts after a
+successful sign-in:
+
+```typescript
+// in a controller
+import { RateLimiter } from "zerotal";
+
+if (await RateLimiter.tooManyAttempts("login", ctx)) {
+  return ctx.json({ message: "Too Many Requests" }, 429);
+}
+
+RateLimiter.resetFor("login", ctx); // clear this actor's counter
+```
+
+> **Note** — `RateLimiter.tooManyAttempts()` records a hit and returns a promise,
+> so `await` it. Unlike the middleware, it never sends the 429 itself — you decide
+> how to respond.
+
+## Response on limit
+
+When the window is exceeded, both limiters return **429** with:
+
+- `Retry-After` — seconds until the window resets.
+- `X-RateLimit-Limit` / `X-RateLimit-Remaining` — the cap and what's left.
+- `X-RateLimit-Reset` — the unix timestamp (seconds) when the window resets.
+
+The 429 body is content-negotiated: an HTML page for web requests, a
+`{ message: "Too Many Requests" }` JSON object for API requests, and a plain-text
+line for CLI requests.
+
+> **Warning** — Counters are in-memory and live in the process. With multiple
+> instances behind a load balancer, each enforces the limit independently — fine
+> for coarse protection. For a hard global cap across instances, gate the action
+> with a shared store such as a [distributed lock](/docs/lock) or a cache-backed
+> counter.
+
+## Testing
+
+Set your suite up once as described in [Testing](/docs/testing). A rate limiter
+is only proven by the request that gets refused, so the test has to exhaust it.
+
+```typescript
+// tests/http/throttle.test.ts
+import { test, expect } from "bun:test";
+import { createApp } from "../helpers.ts";
+
+test("the sixth attempt in a minute is refused", async () => {
+  const app = await createApp();
+
+  for (let i = 0; i < 5; i++) {
+    (await app.post("/login", { email: "a@b.c", password: "wrong" })).assertStatus(422);
+  }
+
+  const blocked = await app.post("/login", { email: "a@b.c", password: "wrong" });
+
+  blocked.assertStatus(429);
+  blocked.assertHeader("Retry-After");
+  await app.close();
+});
+```
+
+**Assert the headers, not just the status.** `X-RateLimit-Limit`,
+`X-RateLimit-Remaining`, and `X-RateLimit-Reset` are what a well-behaved client
+reads to back off. A limiter that returns `429` without them still fails the
+clients it was meant to protect you from:
+
+```typescript
+// tests/http/throttle.test.ts
+blocked.assertHeader("X-RateLimit-Limit", "5");
+blocked.assertHeader("X-RateLimit-Remaining", "0");
+```
+
+**The counter is shared state**, so a limiter test contaminates whatever runs
+next in the same window. Give each test a distinct key — a different route, IP
+header, or user — rather than relying on ordering:
+
+```typescript
+// tests/http/throttle.test.ts
+await app.post("/login", { email: "a@b.c" }, { "X-Forwarded-For": "10.0.0.7" });
+```
+
+> **Warning** — A throttled response is `429` for JSON and an HTML page for a
+> browser request. `assertStatus(429)` holds for both; `assertJson()` does not.
+
+## References
+
+### `RateLimiter` (static)
+
+| Method            | Signature                                                           | Description                                                  |
+| ----------------- | ------------------------------------------------------------------- | ------------------------------------------------------------ |
+| `for`             | `for(name: string): LimiterDefinition`                              | Begin a fluent definition.                                   |
+| `middleware`      | `middleware(name: string): ThrottleMiddleware`                      | Get middleware for a registered limiter (throws if unknown). |
+| `tooManyAttempts` | `tooManyAttempts(name: string, ctx: HttpContext): Promise<boolean>` | Record a hit; `true` if the actor is over the limit.         |
+| `resetFor`        | `resetFor(name: string, ctx: HttpContext): void`                    | Reset the actor's counter for a limiter.                     |
+| `clear`           | `clear(): void`                                                     | Clear all registered limiters (useful in tests).             |
+
+### `LimiterDefinition` (fluent)
+
+| Method     | Signature                                    | Description                                                |
+| ---------- | -------------------------------------------- | ---------------------------------------------------------- |
+| `limit`    | `limit(max: number): this`                   | Maximum requests in the window (default `60`).             |
+| `every`    | `every(seconds: number): this`               | Window duration in seconds (default `60`).                 |
+| `byUser`   | `byUser(): this`                             | Key by `ctx.user.id`; IP when unauthenticated.             |
+| `byApiKey` | `byApiKey(header?: string): this`            | Key by header value (default `x-api-key`); IP when absent. |
+| `byIp`     | `byIp(): this`                               | Key by client IP (the explicit default).                   |
+| `by`       | `by(fn: (ctx: HttpContext) => string): this` | Key by your own resolver.                                  |
+| `register` | `register(): this`                           | Register the limiter with the global registry.             |
+
+### `ThrottleMiddleware`
+
+| Member     | Signature                                                                      | Description                              |
+| ---------- | ------------------------------------------------------------------------------ | ---------------------------------------- |
+| `with`     | `static with(options: Partial<ThrottleOptions>): new () => ThrottleMiddleware` | Build a middleware class from options.   |
+| `reset`    | `reset(): void`                                                                | Clear all counters (useful in tests).    |
+| `resetKey` | `resetKey(ctx: HttpContext): void`                                             | Clear the counter for one context's key. |
+
+## Next steps
+
+- [Middleware](/docs/middleware) — attaching middleware to routes and groups.
+- [Lock](/docs/lock) — coordinating limits across multiple instances.
+- [Authentication](/docs/authentication) — `ctx.user` used by `.byUser()`.

package/docs/responses.md

@@ -0,0 +1,336 @@
+---
+title: Responses
+description: Send JSON, HTML views, redirects, and custom responses back to the client from controllers and middleware.
+---
+
+# Responses
+
+Controllers and middleware build the outgoing response by calling helper methods
+on the per-request `HttpContext`. After your action returns, the pipeline reads
+the context's `response` and sends it to the client.
+
+In a route handler you receive the request `HttpContext` directly — name it `ctx`
+— and call `ctx.json(...)`, `ctx.view(...)`, `ctx.redirect(...)`, and friends.
+Middleware receives the same context and uses the identical methods.
+
+> **Note** — Handlers and middleware receive the same `HttpContext` object. Every
+> helper below works on it; `ctx` is just the variable name used throughout.
+
+## Getting Started
+
+Responses are built into `@zerotal/core` — nothing to install. Every handler
+receives an `HttpContext` carrying the helpers below:
+
+```typescript
+import type { HttpContext } from "zerotal";
+```
+
+## JSON
+
+```typescript
+// in a controller
+ctx.json(data); // 200 OK  — Content-Type: application/json
+ctx.json(data, 201); // 201 Created
+ctx.json({ errors }, 422); // 422 Unprocessable Content
+```
+
+`json(data, status = 200)` serialises with `Response.json`, so anything
+JSON-serialisable is accepted: plain objects, arrays, ORM models, `null`.
+
+## HTML views
+
+### Full document
+
+`view()` accepts either pre-rendered markup, or a view component plus its props.
+It prepends `<!DOCTYPE html>` and sets `Content-Type: text/html`:
+
+```typescript
+// in a controller
+import { WelcomePage } from "../../resources/views/WelcomePage.tsx";
+
+ctx.view(WelcomePage(ctx, { title: "Hello" })); // pre-rendered markup
+ctx.view(WelcomePage, { title: "Hello" }); // component + props
+ctx.view(WelcomePage, { title: "Hello" }, 201); // component, props, status
+```
+
+When you pass a component, it receives the request `HttpContext` as its first
+argument and your props as its second. Route params and model bindings reach the
+component through `ctx.params`.
+
+JSX syntax needs `"jsxImportSource": "zerotal"` in your `tsconfig.json` — set
+once for the whole project, and already present in scaffolded apps. See the
+[View](/docs/view) guide.
+
+> **Tip** — Passing the component form (`ctx.view(WelcomePage, props)`) lets the
+> framework hand the component the `HttpContext` for you, so you can read route
+> params and model bindings from `ctx.params` without wiring them up by hand.
+
+### Raw HTML
+
+For htmx, Turbo Streams, or any partial render — no DOCTYPE prepended:
+
+```typescript
+// in a controller
+ctx.html('<p class="alert">Saved!</p>');
+ctx.html(renderPartial(data), 200);
+```
+
+### Markdown
+
+Render a Markdown string to a full HTML page using Bun's built-in
+`Bun.markdown.html()`. Tables, strikethrough, tasklists, autolinks, and heading
+IDs are enabled by default:
+
+```typescript
+// in a controller
+const content = await Bun.file("./docs/guide.md").text();
+ctx.markdown(content);
+ctx.markdown(content, { title: "Getting Started", headings: { ids: true } });
+```
+
+When no `title` option is given, the first heading in the document is used,
+falling back to `"Docs"`.
+
+## Redirects
+
+```typescript
+// in a controller
+ctx.redirect("/dashboard"); // 302 Found
+ctx.redirect("/dashboard", 303); // 303 See Other  ← use after POST/PUT
+ctx.redirect("/dashboard", 301); // 301 Permanent
+ctx.redirect("/dashboard", 307); // 307 Temporary (preserves method)
+ctx.redirect("/dashboard", 308); // 308 Permanent  (preserves method)
+
+ctx.back(); // 302 to Referer (safe — same origin only)
+ctx.back(303); // 303 to Referer
+```
+
+`back()` reads the `Referer` header and falls back to `/` when it is missing or
+points to a different origin.
+
+> **Tip** — POST-Redirect-GET: use `303` after mutating actions so browsers
+> always issue a `GET` on the redirect target and form re-submission is
+> prevented.
+
+> **Danger** — `back()` only follows a `Referer` on the same origin; a
+> cross-origin or forged value falls back to `/`. This prevents open-redirect
+> attacks — never bypass it by reading the header yourself.
+
+## File downloads
+
+Return a `Response` directly with the appropriate headers:
+
+```typescript
+// in a controller
+const file = Bun.file("./exports/report.csv");
+
+ctx.response = new Response(file as unknown as BodyInit, {
+  headers: {
+    "Content-Type": "text/csv",
+    "Content-Disposition": 'attachment; filename="report.csv"',
+  },
+});
+```
+
+## Custom responses
+
+Set `ctx.response` to any `Response` object — the pipeline sends it verbatim:
+
+```typescript
+// in a controller
+ctx.response = new Response("pong", { status: 200 });
+
+ctx.response = new Response(JSON.stringify({ ok: true }), {
+  status: 200,
+  headers: { "Content-Type": "application/json", "X-Custom": "value" },
+});
+
+// Stream a large body
+const stream = new ReadableStream({ ... });
+ctx.response = new Response(stream, {
+  headers: { "Content-Type": "text/event-stream" },
+});
+```
+
+## Appending headers to any response
+
+Every helper assigns a fresh `Response` to `ctx.response`. To add a header,
+rebuild it from the existing one:
+
+```typescript
+// in a controller, after setting ctx.response via any helper
+const existing = ctx.response!;
+const headers = new Headers(existing.headers);
+headers.set("X-Request-Id", ctx.requestId);
+
+ctx.response = new Response(existing.body, {
+  status: existing.status,
+  headers,
+});
+```
+
+## Flash + redirect
+
+Flash a message and redirect in one step — the flashed value is available via
+`ctx.flashed()` on the next request. Flashing requires an active session
+(see [Session](/docs/session)) and silently no-ops without one:
+
+```typescript
+// in a controller
+ctx.flash("success", "Post created!");
+ctx.redirect("/posts", 303);
+```
+
+In [Inertia](/docs/inertia) apps use the `inertia()` helper with `back()` or
+`redirect()` — no flash needed because Inertia preserves shared props across
+redirects.
+
+## Content negotiation
+
+Use `wantsJson()` (true when the client sends `Accept: application/json`) to
+respond differently based on what the client accepts:
+
+```typescript
+// in a controller
+async destroy(ctx: HttpContext): Promise<void> {
+  await post.delete();
+
+  if (ctx.wantsJson()) {
+    ctx.response = new Response(null, { status: 204 });
+  } else {
+    ctx.flash("success", "Post deleted.");
+    ctx.redirect("/posts", 303);
+  }
+}
+```
+
+## Router-level view shortcut
+
+For routes that only render a view with static or request-computed props, skip
+the controller entirely with `Router.view()`. A static props object is evaluated
+once at registration; a factory function receives the `HttpContext` per request
+and may be async:
+
+```typescript
+// routes/web.ts
+import { Router } from "zerotal";
+
+Router.view("/about", AboutPage, { title: "About Us" });
+
+Router.view("/dashboard", DashboardPage, async (ctx) => ({
+  user: ctx.user,
+  stats: await fetchStats(ctx.user!.id),
+}));
+```
+
+## Which helper should I use?
+
+- **`ctx.json()`** — API endpoints, fetch/XHR clients, Inertia validation
+  errors.
+- **`ctx.view()`** — full server-rendered HTML pages from a JSX component.
+- **`ctx.html()`** — HTML fragments for htmx or Turbo Streams (no DOCTYPE).
+- **`ctx.markdown()`** — serve a `.md` file as a styled documentation page.
+- **`ctx.redirect()` / `ctx.back()`** — after a mutation, or to send the user
+  elsewhere; pair with `flash()` for a one-request status message.
+- **`ctx.response = new Response(...)`** — downloads, streams, custom status
+  codes (e.g. `204 No Content`), or any header set the helpers don't cover.
+
+## Testing
+
+Set your suite up once as described in [Testing](/docs/testing). Every request
+through `TestApp` comes back as a `TestResponse`, whose assertions read as the
+sentence you would have written in a comment.
+
+**Assert the status by meaning, not by number**, so a failure says what went
+wrong rather than what integer it saw:
+
+```typescript
+// tests/http/posts.test.ts
+import { test } from "bun:test";
+import { createApp } from "../helpers.ts";
+
+test("creating a post", async () => {
+  const app = await createApp();
+
+  const res = await app.actingAs(user).post("/posts", { title: "Hello" });
+
+  res.assertCreated(); // clearer than assertStatus(201)
+  res.assertJsonPath("data.title", "Hello");
+  await app.close();
+});
+```
+
+`assertOk`, `assertCreated`, `assertNoContent`, `assertNotFound`,
+`assertUnauthorized`, `assertForbidden`, and `assertUnprocessable` all exist —
+reach for `assertStatus(n)` only when the code has no name.
+
+**Redirects and JSON need different assertions**, and picking the wrong one is
+how a broken route passes. `assertRedirect` checks the `Location` header;
+`assertJson` parses the body:
+
+```typescript
+// tests/http/posts.test.ts
+res.assertRedirect("/posts/hello"); // 3xx + Location
+res.assertJson({ id: 1, title: "Hello" }); // exact body match
+res.assertJsonPath("meta.total", 25); // one path, ignoring the rest
+res.assertJsonCount(3, "data"); // array length at a path
+```
+
+**Prefer `assertJsonPath` to `assertJson`** for anything with a timestamp or an
+id in it. An exact-match assertion on a whole body fails every time an unrelated
+field is added, which trains people to update tests without reading them.
+
+**Headers and cookies are part of the response contract** when a client depends
+on them:
+
+```typescript
+// tests/http/downloads.test.ts
+res.assertHeader("Content-Type", "text/csv");
+res.assertHeader("Content-Disposition");
+res.assertCookie("session");
+res.assertCookieMissing("remember_me");
+```
+
+> **Note** — `assertSee` and `assertDontSee` check the rendered body as text.
+> They are for HTML responses; on a JSON body they will happily match a substring
+> inside a field name and give you a passing test that proves nothing.
+
+## References
+
+Response helpers on `HttpContext`:
+
+| Method      | Signature                                                            | Description                                                           |
+| ----------- | -------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `json`      | `json(data: unknown, status = 200): void`                            | Serialise `data` as a JSON response.                                  |
+| `view`      | `view(markup, status?)` / `view(component, props?, status?)`         | Render a full HTML document (prepends `<!DOCTYPE html>`).             |
+| `html`      | `html(markup: string \| { toString(): string }, status = 200): void` | Send a raw HTML string with no DOCTYPE.                               |
+| `markdown`  | `markdown(content: string, options?, status = 200): void`            | Render Markdown to a full HTML page via `Bun.markdown.html()`.        |
+| `redirect`  | `redirect(url: string, status: 301\|302\|303\|307\|308 = 302): void` | Set a `Location` redirect response.                                   |
+| `back`      | `back(status: 301\|302\|303\|307\|308 = 302): void`                  | Redirect to the same-origin `Referer`, or `/`.                        |
+| `flash`     | `flash(key: string, value: unknown): void`                           | Stash a value for the next request (needs a session).                 |
+| `flashed`   | `flashed<T>(key: string): T \| undefined`                            | Read a value flashed in the previous request.                         |
+| `wantsJson` | `wantsJson(): boolean`                                               | True when `Accept` includes `application/json`.                       |
+| `response`  | `response: Response \| undefined`                                    | The outgoing response; assign a `Response` directly for full control. |
+
+Common status codes:
+
+| Helper                   | Status | Typical use                                      |
+| ------------------------ | ------ | ------------------------------------------------ |
+| `ctx.json(data)`         | 200    | GET, success                                     |
+| `ctx.json(data, 201)`    | 201    | POST, resource created                           |
+| `ctx.json(null, 204)`    | —      | DELETE, no content (set `ctx.response` directly) |
+| `ctx.json(errors, 422)`  | 422    | Validation failed                                |
+| `ctx.json(msg, 401)`     | 401    | Unauthenticated                                  |
+| `ctx.json(msg, 403)`     | 403    | Forbidden                                        |
+| `ctx.json(msg, 404)`     | 404    | Not found                                        |
+| `ctx.redirect(url)`      | 302    | General redirect                                 |
+| `ctx.redirect(url, 303)` | 303    | After POST/PUT/DELETE                            |
+| `ctx.redirect(url, 301)` | 301    | Permanent redirect                               |
+
+## Next steps
+
+- [Requests Context](/docs/context) — read input from the incoming request.
+- [View](/docs/view) — render JSX and Markdown pages.
+- [Inertia](/docs/inertia) — return Inertia responses for SPA frontends.
+- [Cookies](/docs/cookies) — attach cookies to outgoing responses.
+- [HttpContext](/docs/context) — the full per-request object these helpers live on.