@rtorcato/cf-common
Interfaces
AcceptWebSocketOptions
Defined in: index.ts:13
Options for acceptWebSocket.
Type Parameters
A
A
Properties
tags?
optionaltags?:string[]
Defined in: index.ts:15
Tags for ctx.getWebSockets(tag) (at most 10, each at most 256 characters).
attachment?
optionalattachment?:A
Defined in: index.ts:17
Per-socket state that survives hibernation. Read it back with getAttachment.
BroadcastOptions
Defined in: index.ts:101
Options for broadcast.
Properties
tag?
optionaltag?:string
Defined in: index.ts:103
Only send to sockets accepted with this tag.
except?
optionalexcept?:WebSocket
Defined in: index.ts:105
Skip this socket, typically the sender.
Functions
acceptWebSocket()
acceptWebSocket<
A>(request,ctx,options?):Response
Defined in: index.ts:31
Accept a WebSocket upgrade on a Durable Object with the hibernation API and
return the 101 response for its fetch handler. A request without an
Upgrade: websocket header throws an exposed 426 with code
WS_UPGRADE_REQUIRED.
Example
async fetch(request: Request) {
return acceptWebSocket(request, this.ctx, { tags: ['lobby'], attachment: { name: 'ada' } })
}
Type Parameters
A
A = unknown
Parameters
request
Request
ctx
DurableObjectState
options?
AcceptWebSocketOptions<A> = {}
Returns
Response
getAttachment()
getAttachment<
A>(ws):A|null
Defined in: index.ts:52
Read a socket's attachment, typed as A, or null if none was set. The type
is asserted, not validated.
Type Parameters
A
A
Parameters
ws
WebSocket
Returns
A | null
setAttachment()
setAttachment<
A>(ws,attachment):void
Defined in: index.ts:60
Replace a socket's attachment. It is stored with structured clone, and the runtime caps its serialized size (it throws past that), so keep it small.
Type Parameters
A
A
Parameters
ws
WebSocket
attachment
A
Returns
void
parseMessage()
parseMessage<
T>(message,schema):T
Defined in: index.ts:76
Parse a webSocketMessage payload as JSON and validate it with schema (any
object with parse(input): T, such as a Zod schema). Binary messages are
decoded as UTF-8 first. Malformed JSON or a failed parse throws an exposed
400 with code WS_INVALID_MESSAGE; the handler isn't wrapped by
defineFetch, so catch it and reply or close the socket yourself.
Example
async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer) {
const msg = parseMessage(message, ChatMessage)
}
Type Parameters
T
T
Parameters
message
string | ArrayBuffer
schema
SchemaLike<T>
Returns
T
sendMessage()
sendMessage<
T>(ws,data):void
Defined in: index.ts:96
Send data to one socket as a JSON text message.
Type Parameters
T
T
Parameters
ws
WebSocket
data
T
Returns
void
broadcast()
broadcast<
T>(ctx,data,options?):number
Defined in: index.ts:116
Send data as JSON to every socket the Durable Object has accepted (or only
those with tag). The payload is serialized once. A socket that throws on
send (already closing) is skipped. Returns how many sockets it was sent to.
Example
broadcast(this.ctx, { type: 'joined', name }, { tag: 'lobby', except: ws })
Type Parameters
T
T
Parameters
ctx
DurableObjectState
data
T
options?
BroadcastOptions = {}
Returns
number