FlareWebSocketContext

class FlareWebSocketContext<TOut = string | Uint8Array>

The connection a WebSocket handler holds: a lean, runtime-agnostic noun over the live socket.

The framework constructs one per connection: on a resident backing (Node, or the CF Worker isolate) once at open, held for the connection’s life; on a Durable Object hibernation backing, freshly per event over the re-fetched socket, its state and channel membership restored from the socket attachment. Every field is reconstructable from the platform socket plus state, which is exactly what makes that re-materialization possible. It wraps a IFlareWebSocket - the normalized send/close/readyState the runtime provides (the Node codec, the resident workerd socket, or the hibernating native socket) - and adds the framework’s identity, durable state, and outbound serialization. This is the WebSocket analog of FlareHttpContext: the thing handlers act on. Route input and DI live on scope, never here, so the connection stays just the connection.

Generic over the outbound message type TOut; send serializes through the route’s outgoing schema when one is declared (supplied as serialize), otherwise passes raw wire types through.

How you get one

Handed to you by the framework; see Overview.

Properties

id

id: string

Stable connection id, minted at open (v4 UUID) and carried across a Durable Object hibernation wake via the socket attachment.

Accessors

bufferedAmount

get bufferedAmount(): number

Accepted-but-unflushed bytes, for backpressure-aware producers.

returns number

protocol

get protocol(): string

Negotiated subprotocol, or "" when none was selected.

returns string

readyState

get readyState(): 0 | 1 | 2 | 3

Connection state (WHATWG readyState: 0 CONNECTING, 1 OPEN, 2 CLOSING, 3 CLOSED).

returns 0 | 1 | 2 | 3

state

get state(): WebSocketState

Durable per-connection state (survives a hibernation wake on a Durable Object).

returns WebSocketState

Methods

close()

close(code?: number, reason?: string): void

Initiates the closing handshake. code defaults to 1000; reason is UTF-8, truncated to 123 bytes.

code? number

reason? string

publish()

2 overloads

publish(message: TOut): void

Publishes a message to subscribers, serialized once (through this route’s outgoing schema) and sent to each subscriber’s socket directly.

• publish(message) - to every channel THIS connection is subscribed to, excluding itself (the common “broadcast to my room” case).
• publish(channel, message, opts?) - to a named channel, excluding this connection unless self is set.

A channel’s payload shape is a domain-wide convention you own: channels are a flat per-domain namespace (like Socket.IO rooms / Phoenix topics), so the framework does not scope or re-validate by route/contract.

message TOut

publish(channel: string, message: TOut, opts?: { self?: boolean }): void

Publishes a message to subscribers, serialized once (through this route’s outgoing schema) and sent to each subscriber’s socket directly.

• publish(message) - to every channel THIS connection is subscribed to, excluding itself (the common “broadcast to my room” case).
• publish(channel, message, opts?) - to a named channel, excluding this connection unless self is set.

A channel’s payload shape is a domain-wide convention you own: channels are a flat per-domain namespace (like Socket.IO rooms / Phoenix topics), so the framework does not scope or re-validate by route/contract.

channel string

message TOut

opts? { self?: boolean }

send()

send(message: TOut): void

Sends one message; serialized through the route’s outgoing schema when one is declared.

message TOut

subscribe()

subscribe(channel: string): void

Joins channel so this connection receives messages published to it. Membership is dropped automatically on close. No-op when the context cannot broadcast (a plain Worker across isolates - use a Durable Object for fan-out).

channel string

unsubscribe()

unsubscribe(channel: string): void

Leaves channel.

channel string

Learn: Overview