Add bun support by aron-cf · Pull Request #159 · cloudflare/capnweb

aron-cf · 2026-03-26T14:23:39Z

Add Bun ServerWebSocket support to capnweb.

Bun's server-side WebSocket uses callback-based handlers registered on Bun.serve() rather than the standard addEventListener interface. Passing a Bun ServerWebSocket to newWebSocketRpcSession() silently fails because the event listeners never fire. (#61)

A new BunWebSocketTransport implements the RpcTransport interface using the same resolver pattern as the existing WebSocket and MessagePort transports. It exposes dispatchMessage, dispatchClose, and dispatchError methods that Bun's handler callbacks invoke to feed messages into the transport.

Two convenience functions sit on top of the transport. newBunWebSocketRpcHandler() returns a complete handler object you can pass straight to Bun.serve(), wiring everything up automatically via ws.data. newBunWebSocketRpcSession() returns the stub and transport for users who need custom handler logic.

The readme now documents both approaches and notes that Bun is a supported runtime.

Quick start with the handler helper

import { RpcTarget, newBunWebSocketRpcHandler } from "capnweb";

class MyApi extends RpcTarget {
  greet(name: string) { return `Hello, ${name}!`; }
}

let rpcHandler = newBunWebSocketRpcHandler(() => new MyApi());

Bun.serve({
  fetch(req, server) {
    if (server.upgrade(req)) return;
    return new Response("Not Found", { status: 404 });
  },
  websocket: rpcHandler,
});

Escape hatch with manual wiring

import { newBunWebSocketRpcSession, RpcTarget } from "capnweb";

class MyApi extends RpcTarget {
  greet(name: string) { return `Hello, ${name}!`; }
}

Bun.serve({
  fetch(req, server) {
    let userId = authenticate(req);
    server.upgrade(req, { data: { userId } });
  },
  websocket: {
    open(ws) {
      let { stub, transport } = newBunWebSocketRpcSession(ws, new MyApi());
      ws.data.transport = transport;
    },
    message(ws, msg) { ws.data.transport.dispatchMessage(msg); },
    close(ws, code, reason) { ws.data.transport.dispatchClose(code, reason); },
    error(ws, err) { ws.data.transport.dispatchError(err); },
  },
});

Testing locally

Run the test suite with npm test. The new tests in __tests__/bun.test.ts exercise the transport, both convenience functions, and full round-trip calls through a loopback pair without needing a real Bun server.

Unit tests cover message queuing, close and error propagation, abort semantics, buffer-to-string conversion, and end-to-end calls including bidirectional callbacks and error forwarding. All existing tests continue to pass.

Closes #61

github-actions · 2026-03-26T14:23:53Z

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

pkg-pr-new · 2026-03-26T14:24:17Z

Open in StackBlitz

npm i https://pkg.pr.new/cloudflare/capnweb@159

commit: afd751e

changeset-bot · 2026-03-26T14:24:24Z

⚠️ No Changeset found

Latest commit: afd751e

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

aron-cf · 2026-03-26T14:57:31Z

I have read the CLA Document and I hereby sign the CLA

aron-cf · 2026-03-26T14:57:47Z

recheck

kentonv · 2026-03-26T16:04:26Z

In package.json we currently have a special separate build for workerd that includes the workers-only stuff. Maybe we should have a separate build for bun, too? Avoid code bloat for other runtimes.

  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": {
        "workerd": "./dist/index-workers.js",
        "default": "./dist/index.js"
      },
      "require": {
        "workerd": "./dist/index-workers.cjs",
        "default": "./dist/index.cjs"
      }
    }
  },

vitest.config.ts

aron-cf · 2026-03-27T11:25:38Z

@kentonv thanks for the review.

In package.json we currently have a special separate build for workerd that includes the workers-only stuff. Maybe we should have a separate build for bun, too? Avoid code bloat for other runtimes.

Yeah that makes sense. I've done that.

I'm a bit confused how the bun test passes on node, unless it's not actually testing integration with Bun's builtin APIs. If it isn't testing integration then I don't think it's a useful test.

Yeh, that's fair. It was testing against the interface of the BunWebSocket server. I agree an integration test is more useful here. I've updated the tests to run against an actual Bun webserver.

Can we add Bun to the test matrix, and write a test that actually tests against Bun's built-in APIs?

I've not created a test matrix to keep things simple, but happy to do so if you'd prefer. Now we now have a npm run test:bun script to run the integration tests against the Bun web server and a new npm run test:ci to run both vitest and bun on CI. I've added a note to the README to cover this.

Bun uses callback-based WebSocket handlers registered on `Bun.serve()` rather than the standard `addEventListener` interface. Passing a Bun ServerWebSocket to `newWebSocketRpcSession()` errors because the `addEventListener` method does not exist (cloudflare#61). A new BunWebSocketTransport implements the RpcTransport interface using the same resolver pattern as the existing WebSocket and MessagePort transports. It exposes dispatchMessage, dispatchClose, and dispatchError methods that Bun handler callbacks invoke to feed messages into the transport. Two convenience functions sit on top of the transport. `newBunWebSocketRpcHandler()` returns a complete handler object you can pass straight to `Bun.serve()`, wiring everything up automatically via `ws.data`. `newBunWebSocketRpcSession()` returns the stub and transport for users who need custom handler logic. The Bun-specific code ships in a separate entry point (index-bun.ts) mapped via a "bun" conditional export in package.json, following the same pattern as the existing workerd build. Other runtimes never load this code. The test suite in __tests__/bun.test.ts runs under Bun native test runner against real `Bun.serve()` instances with actual WebSocket connections. Run with `npm run test:bun` or `npm run test:ci`. Closes cloudflare#61

Adds the oven-sh/setup-bun action so the Bun runtime is available in the Playwright container. The test step now runs `test:ci` which chains Vitest and Bun tests in sequence.

Adds an "HTTP server on Bun" section to the readme showing both the handler helper and the manual wiring escape hatch. Notes that the Bun helpers ship via a conditional export and are never loaded by other runtimes. Adds a development section documenting the test scripts: npm test for vitest only, npm run test:bun for the Bun suite, and npm run test:ci for both together.

Previously, "bun" and "workerd" were nested inside "import"/"require", which meant TypeScript always fell through to the single top-level "types" entry and picked up index.d.ts regardless of the active condition. Each platform block is now a top-level condition with its own "types", "import", and "require" keys: - "bun" resolves to index-bun.d.ts, which exposes BunWebSocketTransport, BunServerWebSocket, and the Bun-specific session helpers - "workerd" shares the same declarations as the default but keeps a distinct runtime (index-workers.js) that imports cloudflare:workers and registers it for native RPC interop - The bare "types"/"import"/"require" fallback covers Node.js and every other environment

kentonv · 2026-04-05T23:08:15Z

README.md

+
+Bun's server-side WebSocket API uses [callback-based handlers](https://bun.sh/docs/runtime/http/websockets) instead of the standard `addEventListener` interface. Cap'n Web provides `newBunWebSocketRpcHandler()` which returns a handler object you can pass directly to `Bun.serve()`.
+
+> **Note:** The Bun-specific helpers (`newBunWebSocketRpcHandler`, `newBunWebSocketRpcSession`, and `BunWebSocketTransport`) are shipped in a separate build entry point that Bun resolves automatically via the `"bun"` [conditional export](https://nodejs.org/api/packages.html#conditional-exports) in `package.json`. Other runtimes never load this code, keeping bundle size minimal.


I think we can leave out this line, it probably isn't worth the cognitive overhead for people to be aware of this.

kentonv · 2026-04-05T23:14:33Z

README.md

+});
+```
+
+If you need to attach custom data to connections or add your own logic to the WebSocket handlers, use `newBunWebSocketRpcSession()` instead, which gives you direct access to the transport:


Let's leave this out (here to the end of the section). It can be documented in doc comments in the code, but I don't think we want to spend prime README space on it.

kentonv · 2026-04-05T23:14:54Z

src/bun.ts

@@ -0,0 +1,140 @@
+// Copyright (c) 2025 Cloudflare, Inc.


It's 2026. :)

kentonv · 2026-04-05T23:17:27Z

src/index-bun.ts

+         BunWebSocketTransport } from "./bun.js";
+
+export { newBunWebSocketRpcHandler, BunWebSocketTransport };
+export type { BunServerWebSocket } from "./bun.js";


I don't think we should export this type -- people should use the official types from @types/bun, ours is just a minimal subset.

Is it possible for us to use @types/bun here without forcing non-bun dependents to depend on it? Some way to declare dependencies that only apply to one platform?

kentonv · 2026-04-05T23:23:42Z

README.md

    : Disposable;
 ```

+Note: Bun's `ServerWebSocket` does not implement the standard `WebSocket` `addEventListener` interface. If you are using Bun, use the dedicated `newBunWebSocketRpcHandler()` or `newBunWebSocketRpcSession()` described above.


Remove this line, it's redundant.

kentonv · 2026-04-05T23:24:16Z

README.md

 // Now we can call methods on the stub.
 ```

+Cap'n Web's built-in transports (WebSocket, MessagePort, HTTP batch, and Bun ServerWebSocket) are all implemented on top of this interface.


Remove. Don't add unrelated stuff to the readme.

kentonv · 2026-04-05T23:24:35Z

README.md

+
 Note that sessions are entirely symmetric: neither side is defined as the "client" nor the "server". Each side can optionally expose a "main interface" to the other. In typical scenarios with a logical client and server, the server exposes a main interface but the client does not.
+
+## Development


Remove new section.

aron-cf force-pushed the bun-support branch from e89120e to f848d29 Compare March 26, 2026 14:34

github-actions bot added a commit that referenced this pull request Mar 26, 2026

@aron-cf has signed the CLA in #159

bb18391

kentonv reviewed Mar 26, 2026

View reviewed changes

vitest.config.ts Outdated Show resolved Hide resolved

aron-cf force-pushed the bun-support branch from 60f740e to 4f4984d Compare March 27, 2026 11:22

aron-cf force-pushed the bun-support branch from 4f4984d to 3ebc2e6 Compare March 27, 2026 11:32

aron-cf requested a review from kentonv March 30, 2026 10:11

aron-cf added 4 commits March 30, 2026 12:12

Add Bun to the CI test workflow

1775bd3

Adds the oven-sh/setup-bun action so the Bun runtime is available in the Playwright container. The test step now runs `test:ci` which chains Vitest and Bun tests in sequence.

aron-cf force-pushed the bun-support branch from 3ebc2e6 to afd751e Compare March 30, 2026 11:13

kentonv reviewed Apr 5, 2026

View reviewed changes


		Bun's server-side WebSocket API uses [callback-based handlers](https://bun.sh/docs/runtime/http/websockets) instead of the standard `addEventListener` interface. Cap'n Web provides `newBunWebSocketRpcHandler()` which returns a handler object you can pass directly to `Bun.serve()`.

		> Note: The Bun-specific helpers (`newBunWebSocketRpcHandler`, `newBunWebSocketRpcSession`, and `BunWebSocketTransport`) are shipped in a separate build entry point that Bun resolves automatically via the `"bun"` [conditional export](https://nodejs.org/api/packages.html#conditional-exports) in `package.json`. Other runtimes never load this code, keeping bundle size minimal.


		Note that sessions are entirely symmetric: neither side is defined as the "client" nor the "server". Each side can optionally expose a "main interface" to the other. In typical scenarios with a logical client and server, the server exposes a main interface but the client does not.

		## Development

Conversation

aron-cf commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Quick start with the handler helper

Escape hatch with manual wiring

Testing locally

Uh oh!

github-actions bot commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new bot commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

aron-cf commented Mar 26, 2026

Uh oh!

aron-cf commented Mar 26, 2026

Uh oh!

kentonv commented Mar 26, 2026

Uh oh!

Uh oh!

aron-cf commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

aron-cf commented Mar 26, 2026 •

edited

Loading

github-actions bot commented Mar 26, 2026 •

edited

Loading

pkg-pr-new bot commented Mar 26, 2026 •

edited

Loading

changeset-bot bot commented Mar 26, 2026 •

edited

Loading

aron-cf commented Mar 27, 2026 •

edited

Loading