# BunWebSocketData

**Kind:** Interface

**Source:** [`src/adapter/bun/websocket.ts`](https://github.com/honojs/hono/blob/main/src/adapter/bun/websocket.ts#L24)

**Part of:** [Adapter](subsystem-src-adapter)

`BunWebSocketData` stores per-connection metadata for the Bun WebSocket adapter. It keeps the WebSocket event handlers, the requested URL, and the negotiated protocol together so Bun callbacks can access connection context.

## Properties

| Property | Type |
|---|---|
| `events` | `WSEvents` |
| `url` | `URL` |
| `protocol` | `string` |

## Diagram

```mermaid
graph LR
  WS[Bun WebSocket connection] --> Data[BunWebSocketData]
  Data --> Events[events: WSEvents]
  Data --> URL[url: URL]
  Data --> Protocol[protocol: string]
  Events --> Handlers[WebSocket event handlers]
```

## Usage

```ts
import type { BunWebSocketData } from "./adapter/bun/websocket";

const connectionData: BunWebSocketData = {
  events: {
    open(ws) {
      ws.send("Connected");
    },
    message(ws, message) {
      ws.send(`Received: ${message}`);
    },
  },
  url: new URL("wss://example.com/chat"),
  protocol: "chat",
};

// Pass connectionData as WebSocket adapter context where required.
```

## AI Coding Instructions

- Keep `events` bound to the `WSEvents` handlers expected by the WebSocket adapter.
- Store the full `URL` object in `url`; do not replace it with a string.
- Set `protocol` to the protocol selected for the connection, including an empty string when no protocol is negotiated.
- Preserve this data object when forwarding Bun WebSocket callbacks so handlers receive the correct connection context.

## How it works

`BunWebSocketData` is a TypeScript interface for the data attached to a Bun server WebSocket by this adapter. It has three fields: `events: WSEvents`, `url: URL`, and `protocol: string`. [src/adapter/bun/websocket.ts:24-28]

- `events` holds optional `onOpen`, `onMessage`, `onClose`, and `onError` callbacks. The callback WebSocket context is typed as `WSContext<unknown>` because `BunWebSocketData` uses `WSEvents` without a type argument. [src/helper/websocket/index.ts:14-19]
- `url` is the parsed request URL. During an upgrade, the adapter sets it with `new URL(c.req.url)`. [src/adapter/bun/websocket.ts:61-68]
- `protocol` is set to the first value from the `sec-websocket-protocol` request header after splitting on commas and trimming whitespace; it is an empty string when that header is absent. [src/adapter/bun/websocket.ts:65-68]

The adapter passes a `BunWebSocketData` object as the `data` option to `server.upgrade`. [src/adapter/bun/websocket.ts:49-55] [src/adapter/bun/websocket.ts:61-69] If no Bun server is available from the context, the upgrade path throws `TypeError('env has to include the 2nd argument of fetch.')`. [src/adapter/bun/websocket.ts:49-59]

When creating a `WSContext` for a connected socket, the adapter reads `ws.data.url` and `ws.data.protocol` into the context, and exposes the Bun socket itself as `raw`. [src/adapter/bun/websocket.ts:33-45] The `WSContext` constructor copies a non-null URL into a new `URL` object and maps a missing protocol to `null`; this adapter supplies both fields from `BunWebSocketData`. [src/helper/websocket/index.ts:70-77]

The Bun WebSocket handler reads `ws.data.events` on `open`, `close`, and `message`, then calls the corresponding callback only when it is present. [src/adapter/bun/websocket.ts:76-103] `onOpen` receives an `Event('open')`; `onClose` receives a `CloseEvent` containing Bun’s `code` and `reason`; and `onMessage` receives a `MessageEvent` whose data is either the incoming string or `message.buffer`. [src/adapter/bun/websocket.ts:77-102] Although `WSEvents` declares `onError`, this handler has no error method and does not invoke `onError`. [src/helper/websocket/index.ts:14-19] [src/adapter/bun/websocket.ts:76-104]