@depup/h3 2.0.1-depup.0

package/dist/docs/1.utils/1.request.md

@@ -0,0 +1,447 @@
+# Request
+
+> H3 request utilities.
+
+## Body
+
+### `assertBodySize(event, limit)`
+
+Asserts that the request body size is within the specified limit.
+
+The limit is enforced **as the body is read**, not by pre-buffering: the request is wrapped by srvx's `limitRequestBody`, which counts bytes as they flow and aborts with a `413` {@link HTTPError} the moment the running total exceeds `limit` (the error is injected via `createError`). This preserves the byte-accurate guarantee (a lying-small `Content-Length` is still caught mid-stream) without holding the body in memory or blocking streaming handlers.
+
+An honest `Content-Length` that already exceeds the limit is rejected up-front with a `413`, and a request carrying both `Content-Length` and `Transfer-Encoding` is rejected with a `400` (request smuggling, RFC 7230).
+
+Because enforcement is tied to consumption, an overflow on a chunked / unknown-length body surfaces when the handler reads the body rather than as a pre-handler `413`, and a body the handler never reads is never counted.
+
+**Example:**
+
+```ts
+app.post("/", async (event) => {
+  assertBodySize(event, 10 * 1024 * 1024); // 10MB
+  const data = await event.req.formData();
+});
+```
+
+### `readBody(event, options?)`
+
+Reads request body and tries to parse using JSON.parse or URLSearchParams.
+
+By default the body is parsed as JSON (falling back to URL-encoded parsing when the `Content-Type` is `application/x-www-form-urlencoded`). Other body types, such as `multipart/form-data`, must be opted into explicitly via `options.type` and are never auto-detected from the request headers.
+
+**Example:**
+
+```ts
+app.post("/", async (event) => {
+  const body = await readBody(event);
+});
+```
+
+**Example:**
+
+```ts
+app.post("/upload", async (event) => {
+  const body = await readBody(event, { type: "formData" });
+});
+```
+
+### `readValidatedBody(event, validate)`
+
+Tries to read the request body via `readBody`, then uses the provided validation schema or function and either throws a validation error or returns the result.
+
+You can use a simple function to validate the body or use a Standard-Schema compatible library like `zod` to define a schema.
+
+**Example:**
+
+```ts
+function validateBody(body: any) {
+  return typeof body === "object" && body !== null;
+}
+app.post("/", async (event) => {
+  const body = await readValidatedBody(event, validateBody);
+});
+```
+
+**Example:**
+
+```ts
+import { z } from "zod";
+const objectSchema = z.object({
+  name: z.string().min(3).max(20),
+  age: z.number({ coerce: true }).positive().int(),
+});
+app.post("/", async (event) => {
+  const body = await readValidatedBody(event, objectSchema);
+});
+```
+
+**Example:**
+
+```ts
+import * as v from "valibot";
+app.post("/", async (event) => {
+  const body = await readValidatedBody(
+    event,
+    v.object({
+      name: v.pipe(v.string(), v.minLength(3), v.maxLength(20)),
+      age: v.pipe(v.number(), v.integer(), v.minValue(1)),
+    }),
+    {
+      onError: ({ issues }) => ({
+        statusText: "Custom validation error",
+        message: v.summarize(issues),
+      }),
+    },
+  );
+});
+```
+
+## Query (HTTP `QUERY` method)
+
+Utilities for the [HTTP `QUERY` method (RFC 10008)](https://www.rfc-editor.org/rfc/rfc10008): advertise the query formats a resource accepts and validate the request `Content-Type`.
+
+### `appendAcceptQuery(event, mediaTypes)`
+
+Advertise the query formats a resource accepts by setting the `Accept-Query` response header (RFC 10008, HTTP `QUERY` method).
+
+The media types are serialized as a [Structured Fields](https://www.rfc-editor.org/rfc/rfc8941) List: the base media type becomes a token and any `;name=value` parameters are emitted with their values as quoted strings.
+
+**Example:**
+
+```ts
+app.query("/search", (event) => {
+  appendAcceptQuery(event, ["application/sql;charset=UTF-8", "application/jsonpath"]);
+  // Accept-Query: application/sql;charset="UTF-8", application/jsonpath
+  return handleSearch(event);
+});
+```
+
+### `requireContentType(event, acceptedTypes)`
+
+Assert that the request `Content-Type` is present and one of the accepted media types, following the requirements of RFC 10008 for the HTTP `QUERY` method.
+
+Throws:
+
+- `400 Bad Request` if the `Content-Type` header is missing.
+
+- `422 Unprocessable Content` if the `Content-Type` header is malformed.
+
+- `415 Unsupported Media Type` if the media type is not accepted.
+
+
+Accepted types may use wildcards: `*` / `*/*` match anything and `type/*` matches any subtype of `type`.
+
+**Example:**
+
+```ts
+app.query("/search", async (event) => {
+  requireContentType(event, ["application/sql", "application/jsonpath"]);
+  const body = await readBody(event, { type: "text" });
+  // ...
+});
+```
+
+## Cache
+
+### `handleCacheHeaders(event, opts)`
+
+Check request caching headers (`If-None-Match`, `If-Modified-Since`) and add caching headers (Last-Modified, ETag, Cache-Control).
+
+Note: `public` is added by default, but never alongside a caller-supplied `private`/`no-store` directive, so passing `cacheControls: ["private"]` no longer produces a contradictory `public, private`.
+
+## More Request Utils
+
+### `assertMethod(event, expected, allowHead?)`
+
+Asserts that the incoming request method is of the expected type using `isMethod`.
+
+If the method is not allowed, it will throw a 405 error and include an `Allow` response header listing the permitted methods, as required by RFC 9110.
+
+If `allowHead` is `true`, it will allow `HEAD` requests to pass if the expected method is `GET`.
+
+**Example:**
+
+```ts
+app.get("/", (event) => {
+  assertMethod(event, "GET");
+  // Handle GET request, otherwise throw 405 error
+});
+```
+
+### `getQuery(event)`
+
+Get parsed query string object from the request URL.
+
+To access the raw (unparsed) query string, for example to parse nested queries with a custom parser such as `qs`, use `event.url.search` directly.
+
+**Example:**
+
+```ts
+app.get("/", (event) => {
+  const query = getQuery(event); // { key: "value", key2: ["value1", "value2"] }
+  const rawQuery = event.url.search; // "?key=value&key2=value1&key2=value2"
+});
+```
+
+### `getRequestHost(event, opts: { xForwardedHost? })`
+
+Get the request hostname.
+
+If `xForwardedHost` is `true`, it will use the `x-forwarded-host` header if it exists.
+
+If no host header is found, it will return an empty string.
+
+**Security:** The returned host reflects the client-supplied `Host` (or `X-Forwarded-Host`) header and can be spoofed. Do not trust it for security decisions (CSRF/origin checks, cache keys, generating absolute links sent to other users) unless the `Host` value is pinned or validated upstream (e.g. an allow-list of expected hosts, or a reverse proxy that overwrites it).
+
+**Example:**
+
+```ts
+app.get("/", (event) => {
+  const host = getRequestHost(event); // "example.com"
+});
+```
+
+### `getRequestIP(event)`
+
+Try to get the client IP address from the incoming request.
+
+By default the address comes from `event.req.ip`: the connection peer, or the client resolved from the forwarded chain when the server is configured to trust an upstream proxy (e.g. srvx's `trustProxy`).
+
+If `xForwardedFor` is `true`, the **first** entry of the `x-forwarded-for` header is returned instead, when the header exists.
+
+If IP cannot be determined, it will default to `undefined`.
+
+**Security:** `xForwardedFor` is opt-in because that first entry is client input. Proxies conventionally <u>append</u> to the chain (nginx `$proxy_add_x_forwarded_for`, most CDNs, and h3's own {@link proxy} util), so a value sent by the client stays at the left of the chain and is exactly what this returns — letting any caller choose their own address and defeat IP allow-lists, rate limiting, geo checks, and audit logs. Enabling it also <u>overrides</u> `event.req.ip`, discarding an address the server already resolved correctly. Prefer configuring the server to trust your proxy (srvx `trustProxy` walks the chain from the right, past trusted hops) and leave this option off; only enable it when an upstream you control always overwrites `x-forwarded-for` on every request.
+
+**Example:**
+
+```ts
+app.get("/", (event) => {
+  const ip = getRequestIP(event); // "192.0.2.0"
+});
+```
+
+### `getRequestProtocol(event, opts: { xForwardedProto? })`
+
+Get the request protocol.
+
+If `xForwardedProto` is `true`, it will use the `x-forwarded-proto` header if it exists. When the header contains a comma-separated list of protocols, the first entry is used.
+
+Note: This header is opt-in (default `false`) since it can be spoofed by clients. Only enable it when your application runs behind a trusted reverse proxy or CDN that sets this header. This default was changed to match `getRequestHost` (`xForwardedHost`) and `getRequestIP` (`xForwardedFor`).
+
+If protocol cannot be determined, it will default to "http".
+
+**Example:**
+
+```ts
+app.get("/", (event) => {
+  const protocol = getRequestProtocol(event); // "https"
+});
+```
+
+### `getRequestURL(event, opts: { xForwardedHost?, xForwardedProto? })`
+
+Generated the full incoming request URL.
+
+If `xForwardedHost` is `true`, it will use the `x-forwarded-host` header if it exists.
+
+If `xForwardedProto` is `true`, it will use the `x-forwarded-proto` header if it exists.
+
+**Security:** The `.origin` and `.host` of the returned URL are derived from the client-supplied `Host` (or `X-Forwarded-Host`) header and can be spoofed. Do not trust them for security decisions (CSRF/origin checks, cache keys, generating absolute links sent to other users) unless the `Host` value is pinned or validated upstream (e.g. an allow-list of expected hosts, or a reverse proxy that overwrites it). The `.pathname` and `.search` are not derived from the spoofable host, but remain untrusted client input — validate or encode them for their eventual sink (e.g. filesystem lookups, HTML output, downstream queries).
+
+**Example:**
+
+```ts
+app.get("/", (event) => {
+  const url = getRequestURL(event); // "https://example.com/path"
+});
+```
+
+### `getRouterParam(event, name, opts: { decode? })`
+
+Get a matched route param by name.
+
+If `decode` option is `true`, it will decode the matched route param (like `decodeURIComponent`), except encoded path separators (`%2f`, `%5c`) are kept encoded so decoding can never reintroduce a `/` or `\` the router never matched.
+
+**Example:**
+
+```ts
+app.get("/", (event) => {
+  const param = getRouterParam(event, "key");
+});
+```
+
+### `getRouterParams(event, opts: { decode? })`
+
+Get matched route params.
+
+By default params are returned exactly as they appeared in the URL path, still percent-encoded.
+
+With `decode: true` each param is decoded **once** (like `decodeURIComponent`), except encoded path separators (`%2f`, `%5c`, at any `%25`-nesting depth) which are left in their encoded form so decoding can never reintroduce a `/` or `\` the router never matched.
+
+A single decode is not the same as "fully decoded": `%25XX` decodes to the literal text `%XX`, so the result can still contain percent-escapes — including dot segments (`%252e%252e` -> `%2e%2e`) and control characters (`%2500` -> `%00`). **Do not decode the result again**: a second pass turns those back into traversal (`../`) and separators the routing and middleware layers never saw. Treat the returned string as final and validate it as-is.
+
+**Example:**
+
+```ts
+app.get("/", (event) => {
+  const params = getRouterParams(event); // { key: "value" }
+});
+```
+
+**Example:**
+
+```ts
+// GET /files/%252e%252e/x
+app.get("/files/**:rest", (event) => {
+  getRouterParams(event); // { rest: "%252e%252e/x" }
+  getRouterParams(event, { decode: true }); // { rest: "%2e%2e/x" } — still encoded, do not decode again
+});
+```
+
+### `getValidatedQuery(event, validate)`
+
+Get the query param from the request URL validated with validate function.
+
+You can use a simple function to validate the query object or use a Standard-Schema compatible library like `zod` to define a schema.
+
+**Example:**
+
+```ts
+app.get("/", async (event) => {
+  const query = await getValidatedQuery(event, (data) => {
+    return "key" in data && typeof data.key === "string";
+  });
+});
+```
+
+**Example:**
+
+```ts
+import { z } from "zod";
+app.get("/", async (event) => {
+  const query = await getValidatedQuery(
+    event,
+    z.object({
+      key: z.string(),
+    }),
+  );
+});
+```
+
+**Example:**
+
+```ts
+import * as v from "valibot";
+app.get("/", async (event) => {
+  const params = await getValidatedQuery(
+    event,
+    v.object({
+      key: v.string(),
+    }),
+    {
+      onError: ({ issues }) => ({
+        statusText: "Custom validation error",
+        message: v.summarize(issues),
+      }),
+    },
+  );
+});
+```
+
+### `getValidatedRouterParams(event, validate)`
+
+Get matched route params and validate with validate function.
+
+If `decode` option is `true`, params are decoded **once** exactly as described in {@link getRouterParams} — path separators stay encoded, other escapes decode a single level, and the validated value can still contain `%XX`. Validate it as-is; do not decode it again.
+
+You can use a simple function to validate the params object or use a Standard-Schema compatible library like `zod` to define a schema.
+
+**Example:**
+
+```ts
+app.get("/:key", async (event) => {
+  const params = await getValidatedRouterParams(event, (data) => {
+    return "key" in data && typeof data.key === "string";
+  });
+});
+```
+
+**Example:**
+
+```ts
+import { z } from "zod";
+app.get("/:key", async (event) => {
+  const params = await getValidatedRouterParams(
+    event,
+    z.object({
+      key: z.string(),
+    }),
+  );
+});
+```
+
+**Example:**
+
+```ts
+import * as v from "valibot";
+app.get("/:key", async (event) => {
+  const params = await getValidatedRouterParams(
+    event,
+    v.object({
+      key: v.pipe(v.string(), v.picklist(["route-1", "route-2", "route-3"])),
+    }),
+    {
+      decode: true,
+      onError: ({ issues }) => ({
+        statusText: "Custom validation error",
+        message: v.summarize(issues),
+      }),
+    },
+  );
+});
+```
+
+### `isMethod(event, expected, allowHead?)`
+
+Checks if the incoming request method is of the expected type.
+
+If `allowHead` is `true`, it will allow `HEAD` requests to pass if the expected method is `GET`.
+
+**Example:**
+
+```ts
+app.get("/", (event) => {
+  if (isMethod(event, "GET")) {
+    // Handle GET request
+  } else if (isMethod(event, ["POST", "PUT"])) {
+    // Handle POST or PUT request
+  }
+});
+```
+
+### `requestWithBaseURL(req, base, options: { url?: URL })`
+
+Create a lightweight request proxy with the base path stripped from the URL pathname.
+
+`options.url` is the parsed request URL to strip `base` from, in place of parsing `req.url`. Pass `event.url` whenever there is an event: for a non-canonical path it holds the canonicalized form the parent matched `base` against, while `req.url` still holds the wire form, and slicing one by an offset derived from the other is how mount prefixes desync.
+
+### `requestWithURL(req, url)`
+
+Create a lightweight request proxy that overrides only the URL.
+
+Avoids cloning the original request (no `new Request()` allocation).
+
+### `toRequest(input, options?)`
+
+Convert input into a web [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request).
+
+If input is a relative URL, it will be normalized into a full path based on the `host` header.
+
+If input is already a Request and no options are provided, it will be returned as-is.
+
+**Security:** The `host` header is client input. It is only used as the authority of the synthesized URL (falling back to `localhost` when absent or malformed) and can never widen into the path, and `x-forwarded-proto` is ignored, so the scheme is always `http`. Pass an absolute URL to control the origin.
+
+### `getRequestFingerprint(event, opts)`
+
+Get a unique fingerprint for the incoming request.

package/dist/docs/1.utils/2.response.md

@@ -0,0 +1,172 @@
+# Response
+
+> H3 response utilities.
+
+## Event Stream
+
+### `EventStream()`
+
+### `isEventStream(input)`
+
+## Sanitize
+
+### `sanitizeStatusCode(statusCode?, defaultStatusCode)`
+
+Make sure the status code is a valid HTTP status code.
+
+### `sanitizeStatusMessage(statusMessage)`
+
+Make sure the status message is safe to use in a response.
+
+Allowed characters: horizontal tabs, spaces or visible ascii characters: [https://www.rfc-editor.org/rfc/rfc7230#section-3.1.2](https://www.rfc-editor.org/rfc/rfc7230#section-3.1.2)
+
+## Serve Static
+
+### `serveStatic(event, options)`
+
+Dynamically serve static assets based on the request path.
+
+**Security — path traversal:** `serveStatic` resolves `.`/`..` segments but deliberately keeps encoded separators (`%2f`, `%5c`) percent-encoded in the `id` it passes to `getMeta`/`getContents`, exactly as `event.url.pathname` does. The `id` therefore has the same segment structure the router and pathname-scoped `use()` guards matched on: `/private%5cx` stays one opaque segment and cannot be served as `/private/x` past a `use("/private/**")` guard. Resolve the `id` against your asset root as an opaque string — a backend that decodes it re-introduces separators and re-opens the hole.
+
+A **non-canonical pathname is not served** (404, or falls through when `fallthrough` is set): more than one leading separator (`//private/x`, `/\\private/x`) or a dot segment that survived URL canonicalization, which means one spelled with `%25`-nested escapes (`/pub/%252e%252e/private/x`). Both dispatch to a catch-all route while missing a narrower `use("/private/**")` guard, and the only `id` `serveStatic` could build from them resolves back into the guarded path. Assets are reachable under their canonical spelling — the one routing and `use()` guards match on — only.
+
+Everything else is decoded once for the on-disk lookup, so a file's real name reaches the backend: `/50%25.png` → `/50%.png`, `/a%20b` → `/a b`, and one `%25` level is peeled off a nested separator (`/a%252fb` → `/a%2fb`, still a literal `%2f`, never a boundary). RFC 3986's reserved set stays encoded, so an `id` can never grow a `?` or `#` that would truncate it in a URL.
+
+Two things `serveStatic` cannot enforce for filesystem-backed assets: **case-insensitive filesystems** (macOS, Windows) need both sides of any allow/deny check case-folded (otherwise `/SECRET.env` slips past a check for `/secret.env`), and **symlinks** need the resolved path re-asserted against the asset root after following links (e.g. `realpath(target)`).
+
+## More Response Utils
+
+### `html(first)`
+
+### `iterable(iterable)`
+
+Iterate a source of chunks and send back each chunk in order. Supports mixing async work together with emitting chunks.
+
+Each chunk must be a string or a buffer.
+
+For generator (yielding) functions, the returned value is treated the same as yielded values.
+
+The first chunk is awaited before the response is created, so status and headers staged while producing it (`event.res.status`, `event.res.headers`) are still applied. Everything set after the first chunk is ignored — headers are already on the wire by then. (Returning a raw `ReadableStream` gives no such window: its response is created before the stream is read.)
+
+**Example:**
+
+```ts
+return iterable(async function* work() {
+  // Open document body
+  yield "<!DOCTYPE html>\n<html><body><h1>Executing...</h1><ol>\n";
+  // Do work ...
+  for (let i = 0; i < 1000; i++) {
+    await delay(1000);
+    // Report progress
+    yield `<li>Completed job #`;
+    yield i;
+    yield `</li>\n`;
+  }
+  // Close out the report
+  return `</ol></body></html>`;
+});
+async function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+```
+
+### `noContent(status)`
+
+Respond with an empty payload.
+
+**Example:**
+
+```ts
+app.get("/", () => noContent());
+```
+
+### `onDispose(event, cb)`
+
+Register a callback that runs once the event is fully over: the response body finished streaming, the client disconnected, or the body errored — on every runtime, not just Node.js.
+
+The callback receives `undefined` on normal completion, or the cancel/abort reason otherwise. Callbacks run in registration order after the global `onResponse` hook; sync throws and async rejections are absorbed (reported via `console.error` unless the app is configured with `silent`), and pending async callbacks are passed to `waitUntil`.
+
+Registering after disposal invokes the callback immediately. Registration is only guaranteed to observe the end of the event when made during request handling (handler, middleware, or `onResponse`).
+
+Note: this signals <u>"h3 is done with this event"</u>, not <u>"the client received the response"</u> — for non-streaming bodies on non-Node.js runtimes it fires when the response is handed to the runtime. To react to a client disconnect <u>while still producing</u> the response (for example to abort an upstream fetch), use `event.req.signal` instead.
+
+**Example:**
+
+```ts
+app.get("/sse", (event) => {
+  const interval = setInterval(() => {}, 1000);
+  onDispose(event, () => clearInterval(interval));
+  // ... return a streaming response
+});
+```
+
+### `raw(value)`
+
+Mark a string as trusted, pre-escaped HTML so it is used by the {@link html} util **without** being escaped.
+
+Only use this for markup you fully control — passing user input to `raw` re-introduces XSS risk.
+
+**Example:**
+
+```ts
+// `heading` is trusted markup; `userName` is escaped automatically.
+app.get("/", () => html`<div>${raw(heading)}<span>${userName}</span></div>`);
+```
+
+**Example:**
+
+```ts
+// Send a trusted markup string as-is:
+app.get("/", () => html(raw("<h1>Hello, World!</h1>")));
+```
+
+### `redirect(location, status, statusText?)`
+
+Send a redirect response to the client.
+
+It adds the `location` header to the response and sets the status code to 302 by default.
+
+In the body, it sends a simple HTML page with a meta refresh tag to redirect the client in case the headers are ignored.
+
+**Security:** If `location` derives from user input (query params, form fields, headers, etc.), validate it against an allow-list of permitted destinations before redirecting. Passing user-controlled values through unchecked creates an open redirect vulnerability. Prefer `redirectBack` for "return to previous page" flows, which only honors same-origin referers.
+
+**Example:**
+
+```ts
+app.get("/", () => {
+  return redirect("https://example.com");
+});
+```
+
+**Example:**
+
+```ts
+app.get("/", () => {
+  return redirect("https://example.com", 301); // Permanent redirect
+});
+```
+
+### `redirectBack(event)`
+
+Redirect the client back to the previous page using the `referer` header.
+
+If the `referer` header is missing or is a different origin, it falls back to the provided URL (default `"/"`).
+
+By default, only the **pathname** of the referer is used (query string and hash are stripped) to prevent spoofed referers from carrying unintended parameters. Set `allowQuery: true` to preserve the query string.
+
+**Security:** The `fallback` value MUST be a trusted, hardcoded path — never use user input. Passing user-controlled values (e.g., query params) as `fallback` creates an open redirect vulnerability.
+
+**Example:**
+
+```ts
+app.post("/submit", (event) => {
+  // process form...
+  return redirectBack(event, { fallback: "/form" });
+});
+```
+
+### `writeEarlyHints(event, hints)`
+
+Write `HTTP/1.1 103 Early Hints` to the client.
+
+In runtimes that don't support early hints natively, this function falls back to setting response headers which can be used by CDN.

package/dist/docs/1.utils/3.cookie.md

@@ -0,0 +1,33 @@
+# Cookie
+
+> H3 cookie utilities.
+
+### `deleteChunkedCookie(event, name, serializeOptions?)`
+
+Remove a set of chunked cookies by name.
+
+### `deleteCookie(event, name, serializeOptions?)`
+
+Remove a cookie by name.
+
+### `getChunkedCookie(event, name)`
+
+Get a chunked cookie value by name. Will join chunks together.
+
+### `getCookie(event, name)`
+
+Get a cookie value by name.
+
+### `getValidatedCookies(event, validate, options?: { onError?: OnValidateError })`
+
+### `parseCookies(event)`
+
+Parse the request to get HTTP Cookie header string and returning an object of all cookie name-value pairs.
+
+### `setChunkedCookie(event, name, value, options?)`
+
+Set a cookie value by name. Chunked cookies will be created as needed.
+
+### `setCookie(event, name, value, options?)`
+
+Set a cookie value by name.