oRPC Hibernation Plugin
Plugin to fully leverage Hibernation APIs in oRPC server (Cloudflare Websocket Hibernation, etc).
SKILL.mdskills/orpc-hibernation/SKILL.md
GitHubHibernation Plugin
Helps you fully leverage Hibernation APIs, especially useful for Cloudflare Websocket Hibernation.
Setup
import { HibernationPlugin } from '@orpc/server/hibernation'
const handler = new RPCHandler(router, {
plugins: [new HibernationPlugin()],
})
Event Iterator
HibernationEventIterator and encodeHibernationRPCEvent help return event iterators that utilize Hibernation APIs.
- Return
HibernationEventIteratorfrom your handler:
import { HibernationEventIterator } from '@orpc/server/hibernation'
export const onMessage = os.handler(async ({ context }) => {
return new HibernationEventIterator<{ message: string }>((id) => {
context.ws.serializeAttachment({ id })
})
})
- Send events with
encodeHibernationRPCEvent:
import { encodeHibernationRPCEvent } from '@orpc/server/hibernation'
export const sendMessage = os.handler(async ({ input, context }) => {
const websockets = context.getWebSockets()
for (const ws of websockets) {
const { id } = ws.deserializeAttachment()
// yield an event
ws.send(encodeHibernationRPCEvent(id, { message: input.message }, {
customJsonSerializers: []
}))
// return and stop event iterator
ws.send(encodeHibernationRPCEvent(id, { message: input.message }, { event: 'done' }))
// throw and stop event iterator
ws.send(encodeHibernationRPCEvent(id, new ORPCError('INTERNAL_SERVER_ERROR'), { event: 'error' }))
}
})
Cloudflare Durable Object Chat Room Example
import { RPCHandler } from '@orpc/server/websocket'
import { encodeHibernationRPCEvent, HibernationEventIterator, HibernationPlugin } from '@orpc/server/hibernation'
import { DurableObject } from 'cloudflare:workers'
const base = os.$context<{
handler: RPCHandler<any>
ws: WebSocket
getWebsockets: () => WebSocket[]
}>()
export const router = {
send: base.input(z.object({ message: z.string() })).handler(async ({ input, context }) => {
const websockets = context.getWebsockets()
for (const ws of websockets) {
const data = ws.deserializeAttachment()
if (typeof data !== 'object' || data === null) continue
ws.send(encodeHibernationRPCEvent(data.id, input.message))
}
}),
onMessage: base.handler(async ({ context }) => {
return new HibernationEventIterator<string>((id) => {
context.ws.serializeAttachment({ id })
})
}),
}
const handler = new RPCHandler(router, {
plugins: [new HibernationPlugin()],
})
export class ChatRoom extends DurableObject {
async fetch(): Promise<Response> {
const { '0': client, '1': server } = new WebSocketPair()
this.ctx.acceptWebSocket(server)
return new Response(null, { status: 101, webSocket: client })
}
async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer) {
await handler.message(ws, message, {
context: { handler, ws, getWebsockets: () => this.ctx.getWebSockets() },
})
}
async webSocketClose(ws: WebSocket) {
handler.close(ws)
}
}