Add support for Cloudflare's Websocket Hibernation API

[astanciu]

What is the feature you are proposing?

Currently, the hono/cloudflare-worker api uses the normal websocket api:
https://github.com/honojs/hono/blob/main/src/adapter/cloudflare-workers/websocket.ts#L47

Cloudflare recommends using the Hibernation Websocket API, as it allows long lived connections w/o incurring billing charges if the connection is dormant.
https://developers.cloudflare.com/durable-objects/examples/websocket-hibernation-server/

Would be great if the adapter was switched to this, or alternatively, had an option to pick or the other.

[rokasta12]

I've been researching this and wanted to share my analysis of the architectural challenges and a possible approach.

The Core Challenge

The Hibernation API is fundamentally different from the closure-based event model that Hono's WebSocket abstraction uses:

Aspect	Standard API (current)	Hibernation API
Accept	server.accept()	this.ctx.acceptWebSocket(server)
Events	server.addEventListener('message', fn)	Class methods: webSocketMessage(ws, msg)
State	Closures persist in memory	Closures destroyed on hibernation; must use serializeAttachment()
Runtime	Works in plain Workers	Only works inside Durable Objects
Lifecycle	Hono owns the middleware chain	The CF runtime calls methods on the user's DO class

Hono's current upgradeWebSocket uses defineWebSocketHelper, which creates a (c) => WSEvents closure and wires events via addEventListener. This cannot work with Hibernation because:

1. The DO can be evicted — closures don't survive
2. Event handlers must be class methods on the DO, not closures
3. ctx.acceptWebSocket() requires the DurableObjectState, which is outside Hono's middleware chain

Prior Art: The Bun Adapter

The Bun adapter (src/adapter/bun/websocket.ts) already solves a structurally similar problem. Bun's WebSocket handling uses runtime-managed handler methods (open, close, message) rather than addEventListener:

// Bun exports a `websocket` handler object
export const websocket: BunWebSocketHandler<BunWebSocketData> = {
  open(ws) { ... },
  close(ws, code, reason) { ... },
  message(ws, message) { ... },
}

It also has an internal createWSContext helper that wraps a raw Bun WebSocket into Hono's WSContext, giving users a consistent API across runtimes.

Proposed Approach

I think a full middleware-based abstraction would fight the architecture — the upgrade itself is just 3 lines (WebSocketPair + acceptWebSocket + return 101). The real value Hono can provide is:

1. createWSContext(ws: WebSocket): WSContext<WebSocket>

A public helper that wraps a raw Cloudflare WebSocket into Hono's WSContext, so users can use the consistent ws.send(), ws.close(), ws.readyState, ws.protocol, ws.url, ws.raw API inside their DO handler methods.

2. (Optional) Convenience upgrade helper

A lightweight function that encapsulates the WebSocketPair + acceptWebSocket + 101 response pattern, callable inside a Hono route handler.

Example DX

import { DurableObject } from 'cloudflare:workers'
import { Hono } from 'hono'
import { createWSContext } from 'hono/cloudflare-workers'

export class ChatRoom extends DurableObject {
  app = new Hono()

  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env)
    this.app.get('/ws', (c) => {
      const pair = new WebSocketPair()
      const [client, server] = Object.values(pair)
      this.ctx.acceptWebSocket(server)
      return new Response(null, { status: 101, webSocket: client })
    })
  }

  fetch(request: Request) {
    return this.app.fetch(request)
  }

  webSocketMessage(ws: WebSocket, message: string | ArrayBuffer) {
    const wsCtx = createWSContext(ws)
    wsCtx.send(`Echo: ${message}`)
  }

  webSocketClose(ws: WebSocket, code: number, reason: string, wasClean: boolean) {
    ws.close(code, reason)
  }
}

Open Questions

1. Should createWSContext be public API (unlike Bun's, which is @internal)?
2. Is there interest in a broader Durable Object adapter for Hono (a handle() function that properly threads state and env into c.env)?
3. Should the upgrade helper use defineWebSocketHelper or be a standalone function, given that hibernation doesn't fit the WSEvents closure model?

Happy to work on a PR if there's alignment on the approach. I recently added comprehensive test coverage for the CF Workers WebSocket adapter (#4748) so I'm fairly familiar with the internals.