Bun.serveで、WebSocketのサーバーを立てる方法
Bun の Bun.serve には WebSocket のサーバー機能が組み込まれていて、ws などのパッケージを入れなくても、TypeScript の1ファイルで WebSocket のサーバーを立てられます。部屋ごとの一斉配信(Pub/Sub)も、メソッドを呼ぶだけで使えます。
チャットや通知、画面の自動更新のように、サーバーからブラウザーへ即座にデータを送るリアルタイム通信を作りたいときに使えます。ここでは、エコーサーバーと小さなチャットを動かして、書き方と実際に返ってきた結果を確かめました。
検証環境は Ubuntu 24.04(x86_64)、Bun 1.4.4 です。クライアントには Bun に組み込みの WebSocket と curl 8.5.0 を使い、ブラウザーでの確認には Playwright の Chromium を使いました。TLS(wss://)、圧縮(perMessageDeflate)、送信の詰まり(バックプレッシャー)、多数の接続での性能は試していません。公式ドキュメントは、検証に使った版(タグ bun-v1.4.4)の元ファイルを GitHub で確認し、リンクもそこに張っています。
fetch で切り替えて、websocket にハンドラーを書く
WebSocket の接続は、ふつうの HTTP のリクエストとして届きます。fetch の中で server.upgrade(req) を呼ぶと、その接続が WebSocket に切り替わります。切り替えたあとの処理は、websocket に書いたハンドラーが受け持ちます(公式ドキュメントの、WebSocket のサーバーを立てる節)。
次の echo.ts は、届いたメッセージに echo: を付けて送り返すサーバーです。
const server = Bun.serve({
fetch(req, server) {
if (new URL(req.url).pathname === "/ws") {
// WebSocket への切り替えに成功したら、Response は返さない
if (server.upgrade(req)) return;
return new Response("WebSocket の接続ではありません\n", { status: 400 });
}
return new Response("ふつうの HTTP の応答です\n");
},
websocket: {
open(ws) {
console.log("open");
},
message(ws, message) {
const kind = typeof message === "string" ? "string" : message.constructor.name;
console.log(`message: ${kind} ${message}`);
const result = ws.send(`echo: ${message}`);
console.log(`send() の戻り値: ${result}`);
},
close(ws, code, reason) {
console.log(`close: code=${code} reason=${reason}`);
},
},
});
console.log(`listening on ${server.url}`);
ハンドラーは接続ごとではなく、サーバーに1組だけ書きます。どの接続のできごとかは、第1引数の ws で区別します。ブラウザーの WebSocket のように、接続ごとに onmessage を登録する形ではありません。
接続を試すクライアントは、Bun に組み込みの WebSocket で書きました。ブラウザーと同じ WebSocket クラスで、new WebSocket("ws://...") で接続します(公式ドキュメントの、クライアントとして接続する節)。
const ws = new WebSocket("ws://localhost:3000/ws");
ws.addEventListener("open", () => {
console.log("client: open");
ws.send("こんにちは");
ws.send(new Uint8Array([104, 105]));
});
let count = 0;
ws.addEventListener("message", (event) => {
console.log(`client: ${event.data}`);
if (++count === 2) ws.close(1000, "bye");
});
ws.addEventListener("close", (event) => {
console.log(`client: close code=${event.code} reason=${event.reason}`);
});
bun echo.ts でサーバーを起動しておき、別のターミナルで bun echo-client.ts を実行した結果です。
$ bun echo-client.ts
client: open
client: echo: こんにちは
client: echo: hi
client: close code=1000 reason=bye
サーバー側には次のように出ました。
listening on http://localhost:3000/
open
message: string こんにちは
send() の戻り値: 21
message: Buffer hi
send() の戻り値: 8
close: code=1000 reason=bye
文字列で送ったメッセージは string、バイト列で送ったメッセージは Buffer で届きました。ws.send() は、送ったバイト数を返します。「echo: こんにちは」は、echo: の6バイトと、UTF-8 で1文字3バイトのひらがな5文字(15バイト)で21バイトです。接続が閉じているなどでメッセージが捨てられたときは 0、送信待ちには入ったものの詰まっているときは -1 が返ります(公式ドキュメントの、send の戻り値の説明)。
クライアントが close(1000, "bye") で閉じると、サーバーの close ハンドラーにも同じ 1000 と bye が届いています。
curl で、切り替えの応答を見る
同じ /ws に、curl でふつうの GET を送ると、server.upgrade() が false を返し、コードで決めた 400 になりました。
$ curl -s -i http://localhost:3000/ws
HTTP/1.1 400 Bad Request
content-type: text/plain;charset=utf-8
Date: Sun, 15 Nov 2026 08:33:00 GMT
Content-Length: 41
WebSocket の接続ではありません
WebSocket の接続を始めるときのヘッダーを付けて送ると、101 Switching Protocols が返りました。curl はその後の WebSocket のやり取りをしないので、2秒で打ち切っています(終了コード 28 は、curl のマニュアルの、終了コードの一覧にあるとおりタイムアウトです)。
$ curl -s -i --max-time 2 -H "Connection: Upgrade" -H "Upgrade: websocket" -H "Sec-WebSocket-Version: 13" -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" http://localhost:3000/ws
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
Date: Sun, 15 Nov 2026 08:33:00 GMT
Sec-WebSocket-Key には、MDN の WebSocket サーバーの作り方の解説に出てくる例の値を使いました。返ってきた Sec-WebSocket-Accept は、そこに書かれている答えと同じ値です。
Pub/Sub で、部屋の全員にメッセージを配る
チャットのように、1人が送ったメッセージを全員に配るときは、Bun の Pub/Sub を使います。接続ごとに ws.subscribe("部屋の名前") で購読しておき、publish() でその部屋の購読者に一斉に送ります(公式ドキュメントの Pub/Sub の節)。
次の chat.ts は、名前と部屋を URL で受け取り、同じ部屋の人にメッセージを配るサーバーです。
type ChatData = { name: string; room: string };
const ALLOWED_ORIGINS = new Set(["http://localhost:3000"]);
const server = Bun.serve({
routes: {
// ブラウザーで試すためのページ(chat.html)を返す
"/": new Response(Bun.file("chat.html")),
},
fetch(req, server) {
const url = new URL(req.url);
if (url.pathname !== "/chat") return new Response("Not Found\n", { status: 404 });
// ほかのサイトのページからの接続を断る(Origin がないのはブラウザー以外のクライアント)
const origin = req.headers.get("origin");
if (origin && !ALLOWED_ORIGINS.has(origin)) {
return new Response("Forbidden\n", { status: 403 });
}
const name = url.searchParams.get("name");
if (!name) return new Response("name を指定してください\n", { status: 400 });
const ok = server.upgrade(req, {
data: { name, room: url.searchParams.get("room") ?? "lobby" },
});
return ok ? undefined : new Response("WebSocket の接続ではありません\n", { status: 400 });
},
websocket: {
data: {} as ChatData,
open(ws) {
ws.subscribe(ws.data.room);
// ws.publish は、自分以外の購読者に送る
ws.publish(ws.data.room, `${ws.data.name} さんが入室しました`);
console.log(`open: ${ws.data.name} 購読者=${server.subscriberCount(ws.data.room)}`);
},
message(ws, message) {
// server.publish は、送った本人も含めた全員に送る
const sent = server.publish(ws.data.room, `${ws.data.name}: ${message}`);
console.log(`publish: ${ws.data.name} 戻り値=${sent} 購読=${JSON.stringify(ws.subscriptions)}`);
},
close(ws, code) {
// 閉じた接続の購読は、Bun が自動で外す
server.publish(ws.data.room, `${ws.data.name} さんが退室しました`);
console.log(`close: ${ws.data.name} code=${code} 購読者=${server.subscriberCount(ws.data.room)}`);
},
},
});
console.log(`listening on ${server.url}`);
接続ごとの情報(ここでは名前と部屋)は、server.upgrade() の data に入れます。ハンドラーの中では ws.data で読めます。websocket に data: {} as ChatData と書いておくと、ws.data に型が付きます(公式ドキュメントの、接続ごとのデータの節)。
自分を含めるかどうかで、publish を使い分ける
alice、bob、carol の3人を順に接続し、alice がメッセージを送ってから bob が抜ける、という流れを試しました。クライアントは Bun の WebSocket で3つの接続を順に開き、操作の間を100ミリ秒ずつあけています。字下げした行は、その時点で誰が何を受け取ったかを示しています。
$ bun chat-client.ts
alice が接続
bob が接続
alice が受信: bob さんが入室しました
carol が接続
alice が受信: carol さんが入室しました
bob が受信: carol さんが入室しました
alice が送信
alice が受信: alice: こんにちは
bob が受信: alice: こんにちは
carol が受信: alice: こんにちは
bob が切断
alice が受信: bob さんが退室しました
carol が受信: bob さんが退室しました
入室の知らせは ws.publish() で送っています。こちらは、入った本人には届いていません。ws.publish() は、呼んだ接続を除いた購読者に送るためです。一方、server.publish() で配ったチャットの本文は、送った alice 本人にも届きました。
ws.publish() で本人にも送りたいときは、websocket に publishToSelf: true を指定します(型定義にある publishToSelf の説明)。
サーバー側の出力は次のとおりです。
listening on http://localhost:3000/
open: alice 購読者=1
open: bob 購読者=2
open: carol 購読者=3
publish: alice 戻り値=22 購読=["lobby"]
close: bob code=1005 購読者=2
close: alice code=1005 購読者=1
close: carol code=1005 購読者=0
bob の close ハンドラーの中で数えた購読者は、すでに2人に減っていました。閉じた接続の購読は Bun が外すので、unsubscribe() を自分で呼ばなくても、抜けた人には配られません。クライアントが close() を引数なしで呼んだときは、サーバーには 1005(コードなし)が届きました。
server.publish() の戻り値 22 は、送ったメッセージ「alice: こんにちは」のバイト数です。購読者の人数ではありません。人数を知りたいときは server.subscriberCount() を使います(型定義にある publish と subscriberCount の説明)。
ブラウザーからつなぐ
chat.ts は、/ で次の chat.html を返します(先頭の <meta> や <title> などと、見た目を整える <style> は省いています)。ブラウザー側の処理は、標準の WebSocket で書けます。
<h1 id="title"></h1>
<ul id="log"></ul>
<form id="form"><input id="text" autocomplete="off"><button>送信</button></form>
<script>
const name = new URLSearchParams(location.search).get("name");
document.getElementById("title").textContent = `${name} さんの画面`;
const ws = new WebSocket(`ws://${location.host}/chat?name=${encodeURIComponent(name)}`);
const log = document.getElementById("log");
ws.addEventListener("message", (e) => {
const li = document.createElement("li");
li.textContent = e.data;
log.append(li);
});
document.getElementById("form").addEventListener("submit", (e) => {
e.preventDefault();
const input = document.getElementById("text");
ws.send(input.value);
input.value = "";
});
</script>
Chromium で ?name=alice と ?name=bob のページを開き、それぞれから1回ずつ送った画面です。先に入った alice の画面にだけ、bob の入室の知らせが出ています。

Origin を確かめてから upgrade する
WebSocket の接続には、ブラウザーの同一オリジンポリシーがかかりません。そのため、Cookie の SameSite 属性によっては、ほかのサイトのページから、利用者の Cookie 付きで接続されることがあります。公式ドキュメントでは、server.upgrade() の前に Origin ヘッダーを許可リストと照らし合わせるよう勧めています(公式ドキュメントの、Cookie で利用者を見分けるときの注意)。
chat.ts に、許可していない Origin を付けて接続しようとすると、403 で断られました。
$ curl -s -i -H "Origin: https://other.example.com" -H "Connection: Upgrade" -H "Upgrade: websocket" -H "Sec-WebSocket-Version: 13" -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" "http://localhost:3000/chat?name=mallory"
HTTP/1.1 403 Forbidden
content-type: text/plain;charset=utf-8
Date: Sun, 15 Nov 2026 08:33:03 GMT
Content-Length: 10
Forbidden
Origin: http://localhost:3000 を付けたときと、上の画面の Chromium からの接続は、どちらも切り替えに成功しました。
大きすぎるメッセージと、何も届かない接続
websocket には、受け取るメッセージの大きさの上限(maxPayloadLength、既定は 16MB)と、何も届かない接続を閉じるまでの秒数(idleTimeout、既定は120秒)を指定できます(公式ドキュメントの、タイムアウトと上限の節)。次の limits.ts で、上限を 1KB、タイムアウトを8秒にして試しました。
const server = Bun.serve({
port: 3001,
fetch(req, server) {
return server.upgrade(req) ? undefined : new Response("NG\n", { status: 400 });
},
websocket: {
maxPayloadLength: 1024, // 受け取るメッセージは 1KB まで
idleTimeout: 8, // 8 秒何も届かなければ閉じる
sendPings: process.env.SEND_PINGS !== "false", // 閉じる前に ping を送るか(既定は true)
message(ws, message) {
ws.send(`受信 ${message.length} バイト`);
},
close(ws, code, reason) {
console.log(`server close: code=${code} reason=${reason}`);
},
},
});
console.log(`listening on ${server.url} sendPings=${process.env.SEND_PINGS !== "false"}`);
クライアントは、1つ目の接続で 1,000 バイトと 2,000 バイトのメッセージを送り、2つ目の接続では何も送らずに20秒待ちます。結果をまとめると、次のようになりました。
| 試したこと | クライアントが受け取った結果 |
|---|---|
| 1,000 バイトを送る | 「受信 1000 バイト」が返る |
| 2,000 バイトを送る | すぐに閉じられた(コード 1009、Received too big message) |
何も送らずに待つ(sendPings は既定の true) |
20秒後も開いたまま |
何も送らずに待つ(sendPings: false) |
8.0秒後に閉じられた(コード 1006) |
上限を超えたメッセージを受け取ると、Bun はコード 1009 で接続を閉じます。このとき、サーバーの close ハンドラーに届いたコードは 1009 ではなく 1006 で、理由に Received too big message が入っていました。公式ドキュメントにある、プロトコル違反のときの説明と同じ動きです(公式ドキュメントの、接続を閉じるときの節)。
既定の sendPings: true では、タイムアウトの少し前にサーバーが ping を送り、クライアントが pong を返すことで接続が続きます。Bun のクライアントで待ったところ、8秒のタイムアウトを過ぎても閉じられませんでした。sendPings: false にすると、8.0秒後に閉じられました。
/idle: close code=1006 reason= (8.0 秒後)
タイムアウトで閉じられたクライアントが受け取ったコードは 1006 でした。1006 は、Close フレームなしで接続が切れたことを示すコードです。サーバーの close ハンドラーには、1006 と WebSocket timed out from inactivity が届きました。
error ハンドラーがないと、例外でサーバーのプロセスが終わる
message ハンドラーの中で例外が起きたときの動きを、次の errors.ts で確かめました。boom という文字列を受け取ると例外を投げます。環境変数で error ハンドラーのある・なしを切り替えています。
const withHandler = process.env.WITH_ERROR_HANDLER === "true";
const server = Bun.serve({
port: 3002,
fetch(req, server) {
return server.upgrade(req) ? undefined : new Response("NG\n", { status: 400 });
},
websocket: {
message(ws, message) {
if (message === "boom") throw new Error("メッセージの処理で失敗しました");
ws.send(`ok: ${message}`);
},
close(ws, code, reason) {
console.log(`server close: code=${code} reason=${reason}`);
},
...(withHandler && {
error(error, ws) {
console.log(`error handler: ${error.message}`);
ws.close(1011, "サーバーの中でエラーが起きました");
},
}),
},
});
console.log(`listening on ${server.url} error ハンドラー=${withHandler}`);
クライアントから「1回目」「boom」「2回目」を順に送りました。error ハンドラーがないときは、boom を受け取った時点で、サーバーのプロセスが終了コード 1 で終わりました(パスは /path/to/app に置き換え、エラーの前に出るソースコードの抜粋は省いています)。
error: メッセージの処理で失敗しました
at message (/path/to/app/errors.ts:10:41)
Bun v1.4.4 (Linux x64)
クライアントには、Close フレームなしで切れたことを示す 1006 が届いています。
公開するサーバーでは、websocket に error ハンドラーを書くか、ハンドラーの中の処理を try...catch で囲んでください。公式ドキュメントによると、async のハンドラーが reject したときは error ハンドラーは呼ばれません(公式ドキュメントのエラーの節)。
error ハンドラーを書いたときは、サーバーは動き続け、その接続だけがコード 1011 で閉じられました。
$ bun errors-client.ts
client: ok: 1回目
client: close code=1011 reason=サーバーの中でエラーが起きました
error ハンドラーは、ほかのハンドラーと違って、第1引数がエラー、第2引数が ws です。
サーバーを止めても、WebSocket の接続は残る
server.stop() で止めたとき、開いている WebSocket の接続がどうなるかも確かめました。接続から1秒後にサーバーを止め、クライアントは3秒後に接続の状態(readyState)を表示します。
| 止め方 | クライアントの結果 |
|---|---|
server.stop() |
3秒後も readyState=1(開いたまま) |
server.stop(true) |
コード 1001、Server closed で閉じられた |
引数なしの server.stop() では、開いている WebSocket は閉じられませんでした。公式ドキュメントにも、server.stop() は開いている WebSocket を閉じず、server.stop(true) はそれぞれを 1001 で閉じる、と書かれています(公式ドキュメントの、接続を閉じるときの節)。
サーバーを止めるときに、つないでいるクライアントにも閉じたことを伝えたいなら、server.stop(true) を呼びます。1001 は Going Away と呼ばれるコードで、サーバーの障害やブラウザーのページ移動などで、接続の相手が去ることを示します(MDN の、CloseEvent.code の一覧)。





