bun-types 1.3.2-canary.20251105T140650 → 1.3.2

package/docs/runtime/http/tls.mdx

@@ -0,0 +1,101 @@
+---
+title: TLS
+description: Enable TLS in Bun.serve
+---
+
+Bun supports TLS out of the box, powered by [BoringSSL](https://boringssl.googlesource.com/boringssl). Enable TLS by passing in a value for `key` and `cert`; both are required to enable TLS.
+
+```ts
+Bun.serve({
+  tls: {
+    key: Bun.file("./key.pem"), // [!code ++]
+    cert: Bun.file("./cert.pem"), // [!code ++]
+  },
+});
+```
+
+The `key` and `cert` fields expect the _contents_ of your TLS key and certificate, _not a path to it_. This can be a string, `BunFile`, `TypedArray`, or `Buffer`.
+
+```ts
+Bun.serve({
+  tls: {
+    key: Bun.file("./key.pem"), // BunFile
+    key: fs.readFileSync("./key.pem"), // Buffer
+    key: fs.readFileSync("./key.pem", "utf8"), // string
+    key: [Bun.file("./key1.pem"), Bun.file("./key2.pem")], // array of above
+  },
+});
+```
+
+### Passphrase
+
+If your private key is encrypted with a passphrase, provide a value for `passphrase` to decrypt it.
+
+```ts
+Bun.serve({
+  tls: {
+    key: Bun.file("./key.pem"),
+    cert: Bun.file("./cert.pem"),
+    passphrase: "my-secret-passphrase", // [!code ++]
+  },
+});
+```
+
+### CA Certificates
+
+Optionally, you can override the trusted CA certificates by passing a value for `ca`. By default, the server will trust the list of well-known CAs curated by Mozilla. When `ca` is specified, the Mozilla list is overwritten.
+
+```ts
+Bun.serve({
+  tls: {
+    key: Bun.file("./key.pem"), // path to TLS key
+    cert: Bun.file("./cert.pem"), // path to TLS cert
+    ca: Bun.file("./ca.pem"), // path to root CA certificate  // [!code ++]
+  },
+});
+```
+
+### Diffie-Hellman
+
+To override Diffie-Hellman parameters:
+
+```ts
+Bun.serve({
+  tls: {
+    dhParamsFile: "/path/to/dhparams.pem", // path to Diffie Hellman parameters // [!code ++]
+  },
+});
+```
+
+---
+
+## Server name indication (SNI)
+
+To configure the server name indication (SNI) for the server, set the `serverName` field in the `tls` object.
+
+```ts
+Bun.serve({
+  tls: {
+    serverName: "my-server.com", // SNI // [!code ++]
+  },
+});
+```
+
+To allow multiple server names, pass an array of objects to `tls`, each with a `serverName` field.
+
+```ts
+Bun.serve({
+  tls: [
+    {
+      key: Bun.file("./key1.pem"),
+      cert: Bun.file("./cert1.pem"),
+      serverName: "my-server1.com", // [!code ++]
+    },
+    {
+      key: Bun.file("./key2.pem"),
+      cert: Bun.file("./cert2.pem"),
+      serverName: "my-server2.com", // [!code ++]
+    },
+  ],
+});
+```

package/docs/{api/websockets.md → runtime/http/websockets.mdx}

@@ -1,22 +1,32 @@
+---
+title: WebSockets
+description: Server-side WebSockets in Bun
+---
+
 `Bun.serve()` supports server-side WebSockets, with on-the-fly compression, TLS support, and a Bun-native publish-subscribe API.
 
-{% callout %}
+<Info>
+
+**⚡️ 7x more throughput**
 
-**⚡️ 7x more throughput** — Bun's WebSockets are fast. For a [simple chatroom](https://github.com/oven-sh/bun/tree/main/bench/websocket-server/README.md) on Linux x64, Bun can handle 7x more requests per second than Node.js + [`"ws"`](https://github.com/websockets/ws).
+Bun's WebSockets are fast. For a [simple chatroom](https://github.com/oven-sh/bun/tree/main/bench/websocket-server/README.md) on Linux x64, Bun can handle 7x more requests per second than Node.js + [`"ws"`](https://github.com/websockets/ws).
 
-| Messages sent per second | Runtime                        | Clients |
-| ------------------------ | ------------------------------ | ------- |
-| ~700,000                 | (`Bun.serve`) Bun v0.2.1 (x64) | 16      |
-| ~100,000                 | (`ws`) Node v18.10.0 (x64)     | 16      |
+| **Messages sent per second** | **Runtime**                    | **Clients** |
+| ---------------------------- | ------------------------------ | ----------- |
+| ~700,000                     | (`Bun.serve`) Bun v0.2.1 (x64) | 16          |
+| ~100,000                     | (`ws`) Node v18.10.0 (x64)     | 16          |
 
 Internally Bun's WebSocket implementation is built on [uWebSockets](https://github.com/uNetworking/uWebSockets).
-{% /callout %}
+
+</Info>
+
+---
 
 ## Start a WebSocket server
 
 Below is a simple WebSocket server built with `Bun.serve`, in which all incoming requests are [upgraded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Protocol_upgrade_mechanism) to WebSocket connections in the `fetch` handler. The socket handlers are declared in the `websocket` parameter.
 
-```ts
+```ts server.ts icon="/icons/typescript.svg"
 Bun.serve({
   fetch(req, server) {
     // upgrade the request to a WebSocket
@@ -31,7 +41,7 @@ Bun.serve({
 
 The following WebSocket event handlers are supported:
 
-```ts
+```ts server.ts icon="/icons/typescript.svg"
 Bun.serve({
   fetch(req, server) {}, // upgrade logic
   websocket: {
@@ -43,7 +53,7 @@ Bun.serve({
 });
 ```
 
-{% details summary="An API designed for speed" %}
+<Accordion title="An API designed for speed">
 
 In Bun, handlers are declared once per server, instead of per socket.
 
@@ -60,11 +70,12 @@ But servers tend to have **many** socket connections open, which means:
 So, instead of using an event-based API, `ServerWebSocket` expects you to pass a single object with methods for each event in `Bun.serve()` and it is reused for each connection.
 
 This leads to less memory usage and less time spent adding/removing event listeners.
-{% /details %}
+
+</Accordion>
 
 The first argument to each handler is the instance of `ServerWebSocket` handling the event. The `ServerWebSocket` class is a fast, Bun-native implementation of [`WebSocket`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) with some additional features.
 
-```ts
+```ts server.ts icon="/icons/typescript.svg"
 Bun.serve({
   fetch(req, server) {}, // upgrade logic
   websocket: {
@@ -79,24 +90,32 @@ Bun.serve({
 
 Each `ServerWebSocket` instance has a `.send()` method for sending messages to the client. It supports a range of input types.
 
-```ts
-ws.send("Hello world"); // string
-ws.send(response.arrayBuffer()); // ArrayBuffer
-ws.send(new Uint8Array([1, 2, 3])); // TypedArray | DataView
+```ts server.ts icon="/icons/typescript.svg" focus={4-6}
+Bun.serve({
+  fetch(req, server) {}, // upgrade logic
+  websocket: {
+    message(ws, message) {
+      ws.send("Hello world"); // string
+      ws.send(response.arrayBuffer()); // ArrayBuffer
+      ws.send(new Uint8Array([1, 2, 3])); // TypedArray | DataView
+    },
+  },
+});
 ```
 
 ### Headers
 
 Once the upgrade succeeds, Bun will send a `101 Switching Protocols` response per the [spec](https://developer.mozilla.org/en-US/docs/Web/HTTP/Protocol_upgrade_mechanism). Additional `headers` can be attached to this `Response` in the call to `server.upgrade()`.
 
-```ts
+```ts server.ts icon="/icons/typescript.svg"
 Bun.serve({
   fetch(req, server) {
     const sessionId = await generateSessionId();
     server.upgrade(req, {
       headers: {
-        "Set-Cookie": `SessionId=${sessionId}`,
-      },
+        // [!code ++]
+        "Set-Cookie": `SessionId=${sessionId}`, // [!code ++]
+      }, // [!code ++]
     });
   },
   websocket: {}, // handlers
@@ -107,9 +126,7 @@ Bun.serve({
 
 Contextual `data` can be attached to a new WebSocket in the `.upgrade()` call. This data is made available on the `ws.data` property inside the WebSocket handlers.
 
-To strongly type `ws.data`, add a `data` property to the `websocket` handler object. This types `ws.data` across all lifecycle hooks.
-
-```ts
+```ts server.ts icon="/icons/typescript.svg"
 type WebSocketData = {
   createdAt: number;
   channelId: string;
@@ -134,7 +151,6 @@ Bun.serve({
   websocket: {
     // TypeScript: specify the type of ws.data like this
     data: {} as WebSocketData,
-
     // handler called when a message is received
     async message(ws, message) {
       // ws.data is now properly typed as WebSocketData
@@ -150,29 +166,28 @@ Bun.serve({
 });
 ```
 
-{% callout %}
-**Note:** Previously, you could specify the type of `ws.data` using a type parameter on `Bun.serve`, like `Bun.serve<MyData>({...})`. This pattern was removed due to [a limitation in TypeScript](https://github.com/microsoft/TypeScript/issues/26242) in favor of the `data` property shown above.
-{% /callout %}
-
 To connect to this server from the browser, create a new `WebSocket`.
 
-```ts#browser.js
+```ts browser.js icon="file-code"
 const socket = new WebSocket("ws://localhost:3000/chat");
 
 socket.addEventListener("message", event => {
   console.log(event.data);
-})
+});
 ```
 
-{% callout %}
-**Identifying users** — The cookies that are currently set on the page will be sent with the WebSocket upgrade request and available on `req.headers` in the `fetch` handler. Parse these cookies to determine the identity of the connecting user and set the value of `data` accordingly.
-{% /callout %}
+<Info>
+**Identifying users**
+
+The cookies that are currently set on the page will be sent with the WebSocket upgrade request and available on `req.headers` in the `fetch` handler. Parse these cookies to determine the identity of the connecting user and set the value of `data` accordingly.
+
+</Info>
 
 ### Pub/Sub
 
 Bun's `ServerWebSocket` implementation implements a native publish-subscribe API for topic-based broadcasting. Individual sockets can `.subscribe()` to a topic (specified with a string identifier) and `.publish()` messages to all other subscribers to that topic (excluding itself). This topic-based broadcast API is similar to [MQTT](https://en.wikipedia.org/wiki/MQTT) and [Redis Pub/Sub](https://redis.io/topics/pubsub).
 
-```ts
+```ts server.ts icon="/icons/typescript.svg"
 const server = Bun.serve({
   fetch(req, server) {
     const url = new URL(req.url);
@@ -180,9 +195,7 @@ const server = Bun.serve({
       console.log(`upgrade!`);
       const username = getUsernameFromReq(req);
       const success = server.upgrade(req, { data: { username } });
-      return success
-        ? undefined
-        : new Response("WebSocket upgrade error", { status: 400 });
+      return success ? undefined : new Response("WebSocket upgrade error", { status: 400 });
     }
 
     return new Response("Hello world");
@@ -190,7 +203,6 @@ const server = Bun.serve({
   websocket: {
     // TypeScript: specify the type of ws.data like this
     data: {} as { username: string },
-
     open(ws) {
       const msg = `${ws.data.username} has entered the chat`;
       ws.subscribe("the-group-chat");
@@ -229,12 +241,10 @@ server.publish("the-group-chat", "Hello world");
 
 Per-message [compression](https://websockets.readthedocs.io/en/stable/topics/compression.html) can be enabled with the `perMessageDeflate` parameter.
 
-```ts
+```ts server.ts icon="/icons/typescript.svg"
 Bun.serve({
-  fetch(req, server) {}, // upgrade logic
   websocket: {
-    // enable compression and decompression
-    perMessageDeflate: true,
+    perMessageDeflate: true, // [!code ++]
   },
 });
 ```
@@ -265,9 +275,7 @@ By default, Bun will close a WebSocket connection if it is idle for 120 seconds.
 Bun.serve({
   fetch(req, server) {}, // upgrade logic
   websocket: {
-    idleTimeout: 60, // 60 seconds
-
-    // ...
+    idleTimeout: 60, // 60 seconds  // [!code ++]
   },
 });
 ```
@@ -278,13 +286,13 @@ Bun will also close a WebSocket connection if it receives a message that is larg
 Bun.serve({
   fetch(req, server) {}, // upgrade logic
   websocket: {
-    maxPayloadLength: 1024 * 1024, // 1 MB
-
-    // ...
+    maxPayloadLength: 1024 * 1024, // 1 MB  // [!code ++]
   },
 });
 ```
 
+---
+
 ## Connect to a `Websocket` server
 
 Bun implements the `WebSocket` class. To create a WebSocket client that connects to a `ws://` or `wss://` server, create an instance of `WebSocket`, as you would in the browser.
@@ -303,19 +311,8 @@ For convenience, Bun lets you setting custom headers directly in the constructor
 ```ts
 const socket = new WebSocket("ws://localhost:3000", {
   headers: {
-    // custom headers
-  },
-});
-```
-
-### Client compression
-
-WebSocket clients support permessage-deflate compression. The `extensions` property shows negotiated compression:
-
-```ts
-const socket = new WebSocket("wss://echo.websocket.org");
-socket.addEventListener("open", () => {
-  console.log(socket.extensions); // => "permessage-deflate"
+    /* custom headers */
+  }, // [!code ++]
 });
 ```
 
@@ -335,17 +332,16 @@ socket.addEventListener("close", event => {});
 socket.addEventListener("error", event => {});
 ```
 
+---
+
 ## Reference
 
-```ts
+```ts See Typescript Definitions expandable
 namespace Bun {
   export function serve(params: {
     fetch: (req: Request, server: Server) => Response | Promise<Response>;
     websocket?: {
-      message: (
-        ws: ServerWebSocket,
-        message: string | ArrayBuffer | Uint8Array,
-      ) => void;
+      message: (ws: ServerWebSocket, message: string | ArrayBuffer | Uint8Array) => void;
       open?: (ws: ServerWebSocket) => void;
       close?: (ws: ServerWebSocket, code: number, reason: string) => void;
       error?: (ws: ServerWebSocket, error: Error) => void;
@@ -383,11 +379,7 @@ type Compressor =
 
 interface Server {
   pendingWebSockets: number;
-  publish(
-    topic: string,
-    data: string | ArrayBufferView | ArrayBuffer,
-    compress?: boolean,
-  ): number;
+  publish(topic: string, data: string | ArrayBufferView | ArrayBuffer, compress?: boolean): number;
   upgrade(
     req: Request,
     options?: {
@@ -410,164 +402,3 @@ interface ServerWebSocket {
   cork(cb: (ws: ServerWebSocket) => void): void;
 }
 ```
-
-<!--
-### `Bun.serve(params)`
-
-{% param name="params" %}
-Configuration object for WebSocket server
-{% /param %}
-
-{% param name=" fetch" %}
-`(req: Request, server: Server) => Response | Promise<Response>`
-
-Call `server.upgrade(req)` to upgrade the request to a WebSocket connection. This method returns `true` if the upgrade succeeds, or `false` if the upgrade fails.
-{% /param %}
-
-{% param name=" websocket" %}
-Configuration object for WebSocket server
-{% /param %}
-
-{% param name="  message" %}
-`(ws: ServerWebSocket, message: string | ArrayBuffer | Uint8Array) => void`
-
-This handler is called when a `WebSocket` receives a message.
-{% /param %}
-
-{% param name="  open" %}
-`(ws: ServerWebSocket) => void`
-
-This handler is called when a `WebSocket` is opened.
-{% /param %}
-
-{% param name="  close" %}
-`(ws: ServerWebSocket, code: number, message: string) => void`
-
-This handler is called when a `WebSocket` is closed.
-{% /param %}
-
-{% param name="  drain" %}
-`(ws: ServerWebSocket) => void`
-
-This handler is called when a `WebSocket` is ready to receive more data.
-{% /param %}
-
-{% param name="  perMessageDeflate" %}
-`boolean | {\n  compress?: boolean | Compressor;\n  decompress?: boolean | Compressor \n}`
-
-Enable per-message compression and decompression. This is a boolean value or an object with `compress` and `decompress` properties. Each property can be a boolean value or one of the following `Compressor` types:
-
-- `"disable"`
-- `"shared"`
-- `"dedicated"`
-- `"3KB"`
-- `"4KB"`
-- `"8KB"`
-- `"16KB"`
-- `"32KB"`
-- `"64KB"`
-- `"128KB"`
-- `"256KB"`
-
-{% /param %}
-
-### `ServerWebSocket`
-
-{% param name="readyState" %}
-`number`
-
-The current state of the `WebSocket` connection. This is one of the following values:
-
-- `0` `CONNECTING`
-- `1` `OPEN`
-- `2` `CLOSING`
-- `3` `CLOSED`
-
-{% /param %}
-
-{% param name="remoteAddress" %}
-
-`string`
-
-The remote address of the `WebSocket` connection
-{% /param %}
-
-{% param name="data" %}
-The data associated with the `WebSocket` connection. This is set in the `server.upgrade()` call.
-{% /param %}
-
-{% param name=".send()" %}
-`send(message: string | ArrayBuffer | Uint8Array, compress?: boolean): number`
-
-Send a message to the client. Returns a `number` indicating the result of the operation.
-
-- `-1`: the message was enqueued but there is backpressure
-- `0`: the message was dropped due to a connection issue
-- `1+`: the number of bytes sent
-
-The `compress` argument will enable compression for this message, even if the `perMessageDeflate` option is disabled.
-{% /param %}
-
-{% param name=".subscribe()" %}
-`subscribe(topic: string): void`
-
-Subscribe to a topic
-{% /param %}
-
-{% param name=".unsubscribe()" %}
-`unsubscribe(topic: string): void`
-
-Unsubscribe from a topic
-{% /param %}
-
-{% param name=".publish()" %}
-`publish(topic: string, data: string | ArrayBufferView | ArrayBuffer, compress?: boolean): number;`
-
-Send a message to all subscribers of a topic
-{% /param %}
-
-{% param name=".isSubscribed()" %}
-`isSubscribed(topic: string): boolean`
-
-Check if the `WebSocket` is subscribed to a topic
-{% /param %}
-{% param name=".cork()" %}
-`cork(cb: (ws: ServerWebSocket) => void): void;`
-
-Batch a set of operations on a `WebSocket` connection. The `message`, `open`, and `drain` callbacks are automatically corked, so
-you only need to call this if you are sending messages outside of those
-callbacks or in async functions.
-
-```ts
-ws.cork((ws) => {
-  ws.send("first");
-  ws.send("second");
-  ws.send("third");
-});
-```
-
-{% /param %}
-
-{% param name=".close()" %}
-`close(code?: number, message?: string): void`
-
-Close the `WebSocket` connection
-{% /param %}
-
-### `Server`
-
-{% param name="pendingWebsockets" %}
-Number of in-flight `WebSocket` messages
-{% /param %}
-
-{% param name=".publish()" %}
-`publish(topic: string, data: string | ArrayBufferView | ArrayBuffer, compress?: boolean): number;`
-
-Send a message to all subscribers of a topic
-{% /param %}
-
-{% param name=".upgrade()" %}
-`upgrade(req: Request): boolean`
-
-Upgrade a request to a `WebSocket` connection. Returns `true` if the upgrade succeeds, or `false` if the upgrade fails.
-{% /param %} -->