WebSockets

Bun.serve() 支持服务器端 WebSockets，具备实时压缩、TLS 支持以及 Bun 原生的发布-订阅 API。

⚡️ 吞吐量提升 7 倍Bun 的 WebSockets 速度非常快。以 Linux x64 上的简单聊天室为例，Bun 每秒能处理的请求数是 Node.js + "ws" 的 7 倍。

每秒发送消息数	运行时	客户端数
~700,000	(`Bun.serve`) Bun v0.2.1 (x64)	16
~100,000	(`ws`) Node v18.10.0 (x64)	16

Bun 内部的 WebSocket 实现基于 uWebSockets。

启动 WebSocket 服务器

以下服务器使用 Bun.serve 构建，并在 fetch 处理程序中将每个传入请求升级为 WebSocket 连接。套接字处理程序在 websocket 参数中声明。

server.ts

Bun.serve({
  fetch(req, server) {
    // 将请求升级为 WebSocket
    if (server.upgrade(req)) {
      return; // 不返回 Response
    }
    return new Response("升级失败", { status: 500 });
  },
  websocket: {}, // 处理程序
});

Bun 支持以下 WebSocket 事件处理程序：

server.ts

Bun.serve({
  fetch(req, server) {}, // 升级逻辑
  websocket: {
    message(ws, message) {}, // 接收到消息
    open(ws) {}, // 连接打开
    close(ws, code, message) {}, // 连接关闭
    drain(ws) {}, // 套接字准备好接收更多数据
  },
});

为速度设计的 API

在 Bun 中，处理函数只需为服务器声明一次，而不是为每个套接字重复声明。你可以将单个 WebSocketHandler 对象传递给 Bun.serve()，其中包含用于处理 open、message、close、drain 和 error 的方法。这与客户端的 WebSocket 类不同，后者继承自 EventTarget（onmessage、onopen、onclose）。客户端通常只会打开少量套接字连接，因此基于事件的 API 在客户端很适用。但服务器端往往会打开大量连接，这意味着：

为每个连接添加/移除事件监听器所花费的时间会累积起来
为每个连接存储回调函数引用会占用额外内存
通常，人们会为每个连接创建新函数，这同样意味着更多的内存开销

在所有连接之间重复使用同一个处理程序对象，可以避免这两项开销。

每个处理程序的第一个参数都是负责处理该事件的 ServerWebSocket 实例。ServerWebSocket 类是一个快速的、原生 Bun 实现的 WebSocket，并提供了一些额外功能。

server.ts

Bun.serve({
  fetch(req, server) {}, // 升级逻辑
  websocket: {
    message(ws, message) {
      ws.send(message); // 将消息原样返回
    },
  },
});

发送消息

每个 ServerWebSocket 实例都有 .send() 方法用于向客户端发送消息，支持多种输入类型。

server.ts

Bun.serve({
  fetch(req, server) {}, // 升级逻辑
  websocket: {
    message(ws, message) {
      ws.send("Hello world"); // 字符串
      ws.send(response.arrayBuffer()); // ArrayBuffer
      ws.send(new Uint8Array([1, 2, 3])); // TypedArray | DataView
      ws.send(new Blob(["binary"])); // Blob
    },
  },
});

头信息

升级成功后，Bun 会根据规范发送 101 Switching Protocols 响应。要为此 Response 附加额外的 headers，请将它们传递给 server.upgrade()。

server.ts

Bun.serve({
  fetch(req, server) {
    const sessionId = await generateSessionId();
    server.upgrade(req, {
      headers: { 
        "Set-Cookie": `SessionId=${sessionId}`, 
      }, 
    });
  },
  websocket: {}, // 处理程序
});

上下文数据

在 .upgrade() 调用中为新的 WebSocket 附加上下文 data。它可在 WebSocket 处理程序中的 ws.data 属性上访问。要为 ws.data 进行强类型定义，可在 websocket 处理对象里添加 data 属性，从而为所有生命周期钩子中的 ws.data 指定类型。

server.ts

type WebSocketData = {
  createdAt: number;
  channelId: string;
  authToken: string;
};

Bun.serve({
  fetch(req, server) {
    const cookies = new Bun.CookieMap(req.headers.get("cookie")!);

    server.upgrade(req, {
      // 此对象必须符合 WebSocketData 类型
      data: {
        createdAt: Date.now(),
        channelId: new URL(req.url).searchParams.get("channelId"),
        authToken: cookies.get("X-Token"),
      },
    });

    return undefined;
  },
  websocket: {
    // TypeScript：如此指定 ws.data 类型
    data: {} as WebSocketData,
    // 收到消息时调用的处理函数
    async message(ws, message) {
      // ws.data 现已正确类型为 WebSocketData
      const user = getUserFromToken(ws.data.authToken);

      await saveMessageToDatabase({
        channel: ws.data.channelId,
        message: String(message),
        userId: user.id,
      });
    },
  },
});

以前，你可以像 Bun.serve<MyData>({...}) 一样，通过 Bun.serve 的类型参数指定 ws.data 的类型。由于 TypeScript 的一个限制，这种模式已被移除，改用 data 属性。

要从浏览器连接到此服务器，可以创建一个新的 WebSocket。

browser.js

const socket = new WebSocket("ws://localhost:3000/chat");

socket.addEventListener("message", event => {
  console.log(event.data);
});

用户身份识别在页面上设置的 Cookie 会随 WebSocket 升级请求一起发送，并可在 fetch 处理程序的 req.headers 中访问。解析这些 Cookie 以识别连接的用户，并据此设置 data。

发布/订阅

Bun 的 ServerWebSocket 包含原生的基于主题的发布-订阅 API。各个套接字可以通过 .subscribe() 订阅主题（使用字符串标识符指定），并使用 .publish() 向该主题的所有其他订阅者发送消息（不包括自身）。这种基于主题的广播 API 类似于 MQTT 和 Redis Pub/Sub。

server.ts

const server = Bun.serve({
  fetch(req, server) {
    const url = new URL(req.url);
    if (url.pathname === "/chat") {
      console.log(`开始升级!`);
      const username = getUsernameFromReq(req);
      const success = server.upgrade(req, { data: { username } });
      return success ? undefined : new Response("WebSocket 升级错误", { status: 400 });
    }

    return new Response("Hello world");
  },
  websocket: {
    // TypeScript：如此指定 ws.data 类型
    data: {} as { username: string },
    open(ws) {
      const msg = `${ws.data.username} 加入了聊天室`;
      ws.subscribe("the-group-chat");
      server.publish("the-group-chat", msg);
    },
    message(ws, message) {
      // 群聊功能
      // 服务器将收到的消息转发给所有人
      server.publish("the-group-chat", `${ws.data.username}: ${message}`);

      // 查看当前订阅
      console.log(ws.subscriptions); // ["the-group-chat"]
    },
    close(ws) {
      const msg = `${ws.data.username} 离开了聊天室`;
      ws.unsubscribe("the-group-chat");
      server.publish("the-group-chat", msg);
    },
  },
});

console.log(`监听在 ${server.hostname}:${server.port}`);

调用 .publish(data) 会将消息发送给某个主题的所有订阅者，但不包括调用 .publish() 的套接字。要向某个主题的所有订阅者发送消息，请使用 Server 实例上的 .publish() 方法。

const server = Bun.serve({
  websocket: {
    // ...
  },
});

// 监听某个外部事件
server.publish("the-group-chat", "Hello world");

压缩

使用 perMessageDeflate 参数启用逐消息压缩。

server.ts

Bun.serve({
  websocket: {
    perMessageDeflate: true, 
  },
});

要压缩单条消息，请将一个 boolean 作为第二个参数传递给 .send()。

ws.send("Hello world", true);

要对压缩特性进行精细控制，请参考参考文档。

背压管理

ServerWebSocket 的 .send(message) 方法返回一个 number 表示操作结果。

-1 — 消息已入队，但存在背压（backpressure）
0 — 由于连接问题，消息已丢弃
1+ — 发送的字节数

超时和限制

默认情况下，Bun 会关闭处于空闲状态超过 120 秒的 WebSocket 连接。使用 idleTimeout 参数进行配置。

Bun.serve({
  fetch(req, server) {}, // 升级逻辑
  websocket: {
    idleTimeout: 60, // 60 秒
  },
});

如果收到的消息大于 16 MB，Bun 也会关闭 WebSocket 连接。使用 maxPayloadLength 参数进行配置。

Bun.serve({
  fetch(req, server) {}, // 升级逻辑
  websocket: {
    maxPayloadLength: 1024 * 1024, // 1 MB
  },
});

连接到 WebSocket 服务器

Bun 实现了 WebSocket 类。创建连接至 ws:// 或 wss:// 服务器的 WebSocket 客户端实例类似于浏览器中的用法。

const socket = new WebSocket("ws://localhost:3000");

// 支持子协议协商
const socket2 = new WebSocket("ws://localhost:3000", ["soap", "wamp"]);

在浏览器中，页面上设置的 Cookie 会随 WebSocket 升级请求一起发送。这是 WebSocket API 的标准功能。在 Bun 中，你还可以直接在构造函数中设置自定义请求头。这是 Bun 对 WebSocket 标准的特有扩展。在浏览器中无法使用。

const socket = new WebSocket("ws://localhost:3000", {
  headers: {
    /* 自定义头部 */
  }, 
});

给套接字添加事件监听器的方法：

// 收到消息
socket.addEventListener("message", event => {});

// 连接打开
socket.addEventListener("open", event => {});

// 连接关闭
socket.addEventListener("close", event => {});

// 错误处理
socket.addEventListener("error", event => {});

参考

See Typescript Definitions

namespace Bun {
  export function serve(params: {
    fetch: (req: Request, server: Server) => Response | Promise<Response>;
    websocket?: {
      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;
      drain?: (ws: ServerWebSocket) => void;

      maxPayloadLength?: number; // 默认值：16 * 1024 * 1024 = 16 MB
      idleTimeout?: number; // 默认值：120（秒）
      backpressureLimit?: number; // 默认值：16 * 1024 * 1024 = 16 MB
      closeOnBackpressureLimit?: boolean; // 默认值：false
      sendPings?: boolean; // 默认值：true
      publishToSelf?: boolean; // 默认值：false

      perMessageDeflate?:
        | boolean
        | {
            compress?: boolean | Compressor;
            decompress?: boolean | Compressor;
          };
    };
  }): Server;
}

type Compressor =
  | `"disable"`
  | `"shared"`
  | `"dedicated"`
  | `"3KB"`
  | `"4KB"`
  | `"8KB"`
  | `"16KB"`
  | `"32KB"`
  | `"64KB"`
  | `"128KB"`
  | `"256KB"`;

interface Server {
  pendingWebSockets: number;
  publish(topic: string, data: string | ArrayBufferView | ArrayBuffer | Blob, compress?: boolean): number;
  upgrade(
    req: Request,
    options?: {
      headers?: HeadersInit;
      data?: any;
    },
  ): boolean;
}

interface ServerWebSocket {
  readonly data: any;
  readonly readyState: number;
  readonly remoteAddress: string;
  readonly subscriptions: string[];
  send(message: string | ArrayBuffer | Uint8Array | Blob, compress?: boolean): number;
  close(code?: number, reason?: string): void;
  subscribe(topic: string): boolean;
  unsubscribe(topic: string): boolean;
  publish(topic: string, message: string | ArrayBuffer | Uint8Array | Blob): void;
  isSubscribed(topic: string): boolean;
  cork(cb: (ws: ServerWebSocket) => void): void;
}

开始使用

核心运行时

文件与模块系统

HTTP 服务器

网络通信

数据与存储

并发

进程与系统

交互与工具链

实用工具

标准与兼容性

贡献

启动 WebSocket 服务器

发送消息

头信息

上下文数据

发布/订阅

压缩

背压管理

超时和限制

连接到 WebSocket 服务器

参考

​启动 WebSocket 服务器

​发送消息

​头信息

​上下文数据

​发布/订阅

​压缩

​背压管理

​超时和限制

​连接到 WebSocket 服务器

​参考

启动 WebSocket 服务器

发送消息

头信息

上下文数据

发布/订阅

压缩

背压管理

超时和限制

连接到 WebSocket 服务器

参考