@depup/h3 2.0.1-depup.0

package/dist/docs/0.guide/3.api/0.h3.md

@@ -0,0 +1,144 @@
+# H3
+
+> H3 class is the core of server.
+
+You can create a new H3 app instance using `new H3()`:
+
+```js
+import { H3 } from "h3";
+
+const app = new H3({/* optional config */});
+```
+
+## `H3` Methods
+
+### `H3.request`
+
+A [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)-compatible function allowing to fetch app routes.
+
+- Input can be a relative path, [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL), or [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request).
+- Returned value is a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) promise.
+
+```ts
+const response = await app.request("/");
+console.log(response, await response.text());
+```
+
+### `H3.fetch`
+Similar to `H3.request` but only accepts one `(req: Request)` argument for cross runtime compatibility.
+
+### `H3.on`
+
+Register route handler for specific HTTP method.
+
+```js
+const app = new H3().on("GET", "/", () => "OK");
+```
+
+<read-more></read-more>
+
+### `H3.[method]`
+
+Register route handler for specific HTTP method (shortcut for `app.on(method, ...)`).
+
+```js
+const app = new H3().get("/", () => "OK");
+```
+
+### `H3.all`
+
+Register route handler for all HTTP methods.
+
+```js
+const app = new H3().all("/", () => "OK");
+```
+
+### `H3.use`
+
+Register a global [middleware](/guide/basics/middleware).
+
+```js
+const app = new H3()
+  .use((event) => {
+    console.log(`request: ${event.req.url}`);
+  })
+  .all("/", () => "OK");
+```
+
+<read-more></read-more>
+
+### `H3.register`
+
+Register a H3 plugin to extend app.
+
+<read-more></read-more>
+
+### `H3.handler`
+
+An H3 [event handler](/guide/basics/handler) useful to compose multiple H3 app instances.
+
+**Example:** Nested apps.
+
+```js
+import { H3, serve, redirect, withBase } from "h3";
+
+const nestedApp = new H3().get("/test", () => "/test (sub app)");
+
+const app = new H3()
+  .get("/", (event) => redirect(event, "/api/test"))
+  .all("/api/**", withBase("/api", nestedApp.handler));
+
+serve(app);
+```
+
+### `H3.mount`
+
+Using `.mount` method, you can register a sub-app with prefix.
+
+<read-more></read-more>
+
+## `H3` Options
+
+You can pass global app configuration when initializing an app.
+
+Supported options:
+
+- `debug`: Displays debugging stack traces in HTTP responses (potentially dangerous for production!).
+- `silent`: When enabled, console errors for unhandled exceptions will not be displayed.
+- `allowMalformedURL`: When enabled, requests with a malformed percent-encoded URL path (e.g. `/foo%`, `/%ZZ`) are allowed through with the raw pathname instead of being rejected with a `400 Bad Request` (the default).
+- `plugins`: (see [plugins](/guide/advanced/plugins) for more information)
+
+> [!IMPORTANT]
+Enabling `debug` option, sends important stuff like stack traces in error responses. Only enable during development.
+
+### Global Hooks
+
+When initializing an H3 app, you can register global hooks:
+
+- `onError`
+- `onRequest`
+- `onResponse`
+These hooks are called for every request and can be used to add global logic to your app such as logging, error handling, etc.
+
+```js
+const app = new H3({
+  onRequest: (event) => {
+    console.log("Request:", event.req.url);
+  },
+  onResponse: (response, event) => {
+    console.log("Response:", event.url.pathname, response.status);
+  },
+  onError: (error, event) => {
+    console.error(error);
+  },
+});
+```
+
+> [!IMPORTANT]
+> Global hooks only run from main H3 app and **not** sub-apps. Use [middleware](/guide/basics/middleware) for more flexibility.
+
+## `H3` Properties
+
+### `H3.config`
+
+Global H3 instance config.

package/dist/docs/0.guide/3.api/1.h3event.md

@@ -0,0 +1,160 @@
+# H3Event
+
+> H3Event, carries incoming request, prepared response and context.
+
+With each HTTP request, H3 internally creates an `H3Event` object and passes it though event handlers until sending the response.
+
+<read-more></read-more>
+
+An event is passed through all the lifecycle hooks and composable utils to use it as context.
+
+**Example:**
+
+```js
+app.get("/", async (event) => {
+  // Log HTTP request
+  console.log(`[${event.req.method}] ${event.req.url}`);
+
+  // Parsed URL and query params
+  const searchParams = event.url.searchParams;
+
+  // Try to read request JSON body
+  const jsonBody = await event.req.json().catch(() => {});
+
+  return "OK";
+});
+```
+
+## `H3Event` Methods
+
+### `H3Event.waitUntil`
+
+Tell the runtime about an ongoing operation that shouldn't close until the promise resolves.
+
+```js [app.mjs]
+import { logRequest } from "./tracing.mjs";
+
+app.get("/", (event) => {
+  request.waitUntil(logRequest(request));
+  return "OK";
+});
+```
+
+```js [tracing.mjs]
+export async function logRequest(request) {
+  await fetch("https://telemetry.example.com", {
+    method: "POST",
+    body: JSON.stringify({
+      method: request.method,
+      url: request.url,
+      ip: request.ip,
+    }),
+  });
+}
+```
+
+> [!TIP]
+> To release per-request resources (timers, upstream connections, file handles) once the event is fully over — on every runtime — use the [`onDispose(event, cb)`](/utils/response#ondisposeevent-cb) utility.
+
+## `H3Event` Properties
+
+### `H3Event.app?`
+
+Access to the H3 [application instance](/guide/api/h3).
+
+### `H3Event.context`
+
+The context is an object that contains arbitrary information about the request.
+
+You can store your custom properties inside `event.context` to share across utils.
+
+**Known context keys:**
+
+- `context.params`: Matched router parameters.
+- `middlewareParams`: Matched middleware parameters
+- `matchedRoute`: Matched router route object.
+- `sessions`: Cached session data.
+- `basicAuth`: Basic authentication data.
+
+### `H3Event.req`
+Incoming HTTP request info based on native [Web Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) with additional runtime addons (see [srvx docs](https://srvx.h3.dev/guide/handler#extended-request-context)).
+
+```ts
+app.get("/", async (event) => {
+  const url = event.req.url;
+  const method = event.req.method;
+  const headers = event.req.headers;
+
+  // (note: you can consume body only once with either of this)
+  const bodyStream = await event.req.body;
+  const textBody = await event.req.text();
+  const jsonBody = await event.req.json();
+  const formDataBody = await event.req.formData();
+
+  return "OK";
+});
+```
+
+### `H3Event.url`
+
+Access to the full parsed request [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL).
+
+```ts
+app.get("/", (event) => {
+  const { pathname, search, searchParams } = event.url;
+
+  return "OK";
+});
+```
+
+#### Pathname encoding
+
+`event.url.pathname` is the path in its wire encoding, with one exception: an escape that is <u>needlessly</u> there is dropped.
+
+An escape is needless when every decoding consumer — a proxy, a filesystem lookup, a handler calling `decodeURIComponent` — reads it as its literal, while H3's matchers compare the two as different strings. Left alone, that gap lets `/%61dmin` slip past an `/admin` guard and still reach the `/admin` route, or reach a catch-all handler that decodes it downstream. So H3 decodes exactly those escapes, once, before routing. Nothing else is touched:
+
+| Request | `event.url.pathname` | Why |
+| --- | --- | --- |
+| `/%61dmin` | `/admin` | Unreserved escape, needlessly encoded |
+| `/a%2eb` | `/a.b` | Unreserved escape, needlessly encoded |
+| `/a%21b` | `/a!b` | Decodes downstream, needlessly encoded |
+| `/%40handle` | `/@handle` | Decodes downstream, needlessly encoded |
+| `/a/%2e%2e/b` | `/b` | The URL parser resolved the dot segment first |
+| `/x%2fy` | `/x%2fy` | Separator, must stay encoded |
+| `/x%5cy` | `/x%5cy` | Separator, must stay encoded |
+| `/100%25` | `/100%25` | Decoding it would expose a nested escape |
+| `/a%20b` | `/a%20b` | The URL serializer re-encodes a space anyway |
+| `/caf%C3%A9` | `/caf%C3%A9` | The URL serializer re-encodes non-ASCII anyway |
+
+The decoded set is every escape whose character survives WHATWG path serialization unchanged, minus `%2f` and `%25`: the [RFC 3986 §2.3](https://www.rfc-editor.org/rfc/rfc3986#section-2.3) unreserved set (`ALPHA` / `DIGIT` / `-` / `.` / `_` / `~`), which is equivalent to its literal per [§6.2.2.2](https://www.rfc-editor.org/rfc/rfc3986#section-6.2.2.2), plus `!`, `$`, `&`, `'`, `(`, `)`, `*`, `+`, `,`, `:`, `;`, `=`, `@`, `[`, `]` and `|`. Anything else is left alone because decoding it cannot survive the round trip (`%20`, `%5E`, `%7B`, non-ASCII), would change how many segments the path has (`%2f`, `%5c`), would delete the character outright (`%09` and the other C0 controls), or would expose a nested escape (`%25`).
+
+That is wider than [`decodeURI`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURI), which preserves all of RFC 3986's reserved set (`; / ? : @ & = + $ ,`) — of which only `/` is structural in an already-parsed path. Routes like `/@handle` or `/resource:action` are ordinary, so a guard protecting one must not be walkable past by its escaped spelling (`/%40handle`).
+
+Route matching, `use()` matchers and your own `event.url.pathname` checks therefore all compare one and the same string. `event.req.url` always keeps the original wire encoding, so for a non-canonical path the two disagree: read the path from `event.url`, and never re-derive it from `event.req.url` — slicing one by an offset taken from the other is how mount prefixes and proxy targets desync.
+
+Canonicalization happens in the `H3Event` constructor, so it covers every event, including one built by `mockEvent()` or a standalone `handler.fetch()`.
+
+Every escape that survives is **opaque** — treat it that way:
+
+> [!WARNING]
+> Never decode `event.url.pathname` yourself. Decoding can reintroduce a `/` or `..` that routing and middleware never saw, which is a path traversal vector when the value reaches a filesystem or an upstream URL. To read a route param in decoded form, use [`getRouterParams(event, { decode: true })`](/utils/request#getrouterparamsevent-opts-decode), which decodes everything else but keeps encoded separators encoded. To canonicalize a path for a scope check, use [`resolveDotSegments`](/utils/security#resolvedotsegments).
+
+A route param therefore can never contain a path separator the router did not match on: `%2f` and `%5c` stay encoded, so `/a%2fb` and `/a%5cb` are one segment (matching the route `/:id`, not `/a/:id`).
+
+Requests with malformed percent-encoding (such as `/foo%` or `/%ZZ`) have no canonical form to decode to and are rejected with a `400 Bad Request` before any handler runs. Set the [`allowMalformedURL`](/guide/api/h3#h3-options) app option to receive the raw pathname instead.
+
+### `H3Event.res`
+
+Prepared HTTP response status and headers.
+
+```ts
+app.get("/", (event) => {
+  event.res.status = 200;
+  event.res.statusText = "OK";
+  event.res.headers.set("x-test", "works");
+
+  return "OK";
+});
+```
+
+<read-more></read-more>

package/dist/docs/0.guide/4.advanced/0.plugins.md

@@ -0,0 +1,50 @@
+# Plugins
+
+> H3 plugins allow you to extend an H3 app instance with reusable logic.
+
+## Register Plugins
+
+Plugins can be registered either when creating a new [H3 instance](/guide/api/h3) or by using [H3.register](/guide/api/h3#h3register).
+
+```js
+import { H3 } from "h3";
+import { logger } from "./logger.mjs";
+
+// Using instance config
+const app = new H3({
+  plugins: [logger()],
+});
+
+// Or register later
+app.register(logger());
+
+// ... rest of the code..
+app.get("/**", () => "Hello, World!");
+```
+
+> [!NOTE]
+> Plugins are always registered immediately. Therefore, the order in which they are used might be important depending on the plugin's functionality.
+
+## Creating Plugins
+
+H3 plugins are simply functions that accept an [H3 instance](/guide/api/h3) as the first argument and immediately apply logic to extend it.
+
+```js
+app.register((app) => {
+  app.use(...)
+})
+```
+
+For convenience, H3 provides a built-in `definePlugin` utility, which creates a typed factory function with optional plugin-specific options.
+
+```js
+import { definePlugin } from "h3";
+
+const logger = definePlugin((h3, _options) => {
+  if (h3.config.debug) {
+    h3.use((req) => {
+      console.log(`[${req.method}] ${req.url}`);
+    });
+  }
+});
+```

package/dist/docs/0.guide/4.advanced/1.websocket.md

@@ -0,0 +1,176 @@
+# WebSockets
+
+> H3 has built-in utilities for cross platform WebSocket and Server-Sent Events.
+
+You can add cross platform WebSocket support to H3 servers using [🔌 CrossWS](https://crossws.h3.dev/).
+
+## Usage
+
+WebSocket handlers can be defined using the `defineWebSocketHandler()` utility and registered to any route like event handlers.
+
+You need to register CrossWS as a server plugin in the `serve` function. The plugin resolves the correct hooks from your matched route automatically.
+
+```js
+import { H3, serve, defineWebSocketHandler } from "h3";
+
+import { plugin as ws } from "crossws/server";
+
+const app = new H3();
+
+app.get("/_ws", defineWebSocketHandler({ message: console.log }));
+
+serve(app, {
+  plugins: [ws()],
+});
+```
+
+> [!NOTE]
+> Passing a custom `resolve` to `ws()` is only needed to resolve hooks yourself (for example without invoking the app). By default, CrossWS calls the app's `fetch` handler and reads the hooks attached by `defineWebSocketHandler()`.
+
+`defineWebSocketHandler()` attaches the hooks to the **request** (CrossWS reads them back with `getWebSocketHooks(request)`, keyed by `Symbol.for("crossws.hooks")`), and answers the upgrade request with `426 Upgrade Required` for anything that is not a WebSocket client.
+
+They are attached to the request rather than to that response because a `Response` gets rebuilt on its way out of an app — merging a header staged by a [route rule](/guide/rules) or CORS middleware, or any middleware doing `new Response(res.body, res)` — and a rebuilt response carries none of the original's own properties. The response also exposes the hooks as `res.crossws` for convenience, but only when nothing rebuilt it; if you write a custom `resolve`, read the request instead:
+
+```js
+import { getWebSocketHooks } from "crossws";
+
+serve(app, {
+  plugins: [ws({ resolve: (req) => app.fetch(req).then(() => getWebSocketHooks(req)) })],
+});
+```
+
+**Full example:**
+
+```js [websocket.mjs]
+import { H3, serve, html, defineWebSocketHandler } from "h3";
+import { plugin as ws } from "crossws/server";
+
+export const app = new H3();
+
+// A minimal self-contained WebSocket playground served for plain HTTP requests.
+const playground = html`<!doctype html>
+  <title>H3 WebSocket Playground</title>
+  <h1>H3 WebSocket Playground</h1>
+  <form id="form">
+    <input id="input" placeholder="Type a message..." autocomplete="off" autofocus />
+    <button type="submit">Send</button>
+  </form>
+  <div id="log"></div>
+  <script type="module">
+    const log = (msg) => {
+      const line = document.createElement("div");
+      line.textContent = msg;
+      document.getElementById("log").append(line);
+    };
+    const url = location.href.replace(/^http/, "ws");
+    const ws = new WebSocket(url);
+    ws.addEventListener("open", () => log("[open] connected to " + url));
+    ws.addEventListener("message", (e) => log("[message] " + e.data));
+    ws.addEventListener("close", () => log("[close] disconnected"));
+    document.getElementById("form").addEventListener("submit", (e) => {
+      e.preventDefault();
+      const input = document.getElementById("input");
+      ws.send(input.value);
+      input.value = "";
+    });
+  </script>`;
+
+// A single route serves both the playground page (plain HTTP) and the
+// WebSocket endpoint (upgrade requests). The page connects back to itself.
+app.get(
+  "/",
+  defineWebSocketHandler(
+    {
+      open(peer) {
+        console.log("[open]", peer);
+
+        // Send welcome to the new client
+        peer.send("Welcome to the server!");
+
+        // Join new client to the "chat" channel
+        peer.subscribe("chat");
+
+        // Notify every other connected client
+        peer.publish("chat", `[system] ${peer} joined!`);
+      },
+
+      message(peer, message) {
+        console.log("[message]", peer);
+
+        if (message.text() === "ping") {
+          // Reply to the client with a ping response
+          peer.send("pong");
+          return;
+        }
+
+        // The server re-broadcasts incoming messages to everyone
+        peer.publish("chat", `[${peer}] ${message}`);
+
+        // Echo the message back to the sender
+        peer.send(message);
+      },
+
+      close(peer) {
+        console.log("[close]", peer);
+        peer.publish("chat", `[system] ${peer} has left the chat!`);
+        peer.unsubscribe("chat");
+      },
+    },
+    // Non-upgrade requests get the playground page.
+    () => playground,
+  ),
+);
+
+serve(app, {
+  plugins: [ws()],
+});
+```
+
+### Handling HTTP requests
+
+By default, a WebSocket route responds with `426 Upgrade Required` to any request that is not a WebSocket upgrade.
+
+You can pass an optional HTTP handler as the second argument to `defineWebSocketHandler()` to serve regular (non-upgrade) requests on the same route. WebSocket upgrade requests still go to the hooks.
+
+```js
+app.get(
+  "/_ws",
+  defineWebSocketHandler(
+    { message: (peer, message) => peer.send(message.text()) },
+    () => "Send a WebSocket upgrade request to connect.",
+  ),
+);
+```
+
+## Server-Sent Events (SSE)
+
+As an alternative to WebSockets, you can use [Server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events).
+
+H3 has a built-in `EventStream` class to create server-sent events. Construct it directly with `new EventStream(event)` and return it from a handler.
+
+### Example
+
+```js [server-sent-events.mjs]
+import { H3, serve, EventStream } from "h3";
+
+export const app = new H3();
+
+app.get("/", (event) => {
+  const eventStream = new EventStream(event);
+
+  // Send a message every second
+  const interval = setInterval(async () => {
+    await eventStream.push("Hello world");
+  }, 1000);
+
+  // cleanup the interval when the connection is terminated or the writer is closed
+  eventStream.onClosed(() => {
+    console.log("Connection closed");
+    clearInterval(interval);
+  });
+
+  return eventStream;
+});
+
+serve(app);
+```

package/dist/docs/0.guide/4.advanced/2.nightly.md

@@ -0,0 +1,13 @@
+# Nightly Builds
+
+You can opt-in to early test latest H3 changes using automated nightly release channel.
+
+If you are directly using `h3` as a dependency in your project:
+
+```json
+{
+  "dependencies": {
+    "h3": "npm:h3-nightly@latest"
+  }
+}
+```

package/dist/docs/1.utils/0.index/index.md

@@ -0,0 +1,46 @@
+# H3 Utils
+
+H3 is a composable framework. Instead of providing a big core, you start with a lightweight [H3](/guide/api/h3) instance and for every functionality, there is either a built-in utility or you can make yours.
+
+<card-group>
+
+<card>
+
+Utilities for incoming request.
+</card>
+
+<card>
+
+Utilities for preparing and sending response.
+</card>
+
+<card>
+
+Cookie utilities.
+</card>
+
+<card>
+
+Security utilities.
+</card>
+
+<card>
+
+Proxy utilities.
+</card>
+
+<card>
+
+MCP related utilities.
+</card>
+
+<card>
+
+More Utilities.
+</card>
+
+<card>
+
+Community made utilities.
+</card>
+</card-group>