WebSocketRouteHandle

class WebSocketRouteHandle<D extends InjectMap = {}, T extends WebSocketDescriptor = {}>

The build-time handle host.ws.route(path, opts) returns: attach the connection’s lifecycle behaviors with individual registrar calls, the same way host.http.get/post register behaviors (never an object literal). Runs once at registration; the handlers are static and receive the live connection per event. Generic over the route’s inject map D and descriptor T, so scope/socket are fully typed.

Two-lifetime split mirrors the Durable Object: the route handle is to the live connection what DurableHandle is to the request context - build-time config vs the runtime object. Constructed by the arc only (exported type-only from the package index, like HttpGroup it is dev-held, never dev-constructed); it collects behaviors into the registration’s shared WsHandlerFns, and the pre-handshake upgrade hook into the registration’s upgrade slot.

How you get one

Handed to you by the framework; see Inline handlers.

Methods

close()

close(handler: WebSocketCloseHandler<D, T>): this

Registers the terminal-close behavior.

handler WebSocketCloseHandler<D, T>

returns this

error()

error(handler: WebSocketErrorHandler<D, T>): this

Registers the transport/protocol-error behavior.

handler WebSocketErrorHandler<D, T>

returns this

message()

message(handler: WebSocketMessageHandler<D, T>): this

Registers the per-message behavior.

handler WebSocketMessageHandler<D, T>

returns this

open()

open(handler: WebSocketOpenHandler<D, T>): this

Registers the OPEN behavior.

handler WebSocketOpenHandler<D, T>

returns this

upgrade()

2 overloads

upgrade(handler: WebSocketUpgradeHandler<D, T>): this

Registers the pre-handshake upgrade hook.

The one moment with request context, before the handshake completes. The bare form shares the route’s inject map (the hook’s deps resolve from the same per-connection container the handlers use); the options form declares the hook’s OWN inject plus the state tokens it provides via scope.state.

handler WebSocketUpgradeHandler<D, T>

returns this

upgrade<I extends InjectMap>(opts: WebSocketUpgradeOptions<I>, handler: WebSocketUpgradeHandler<I, T>): this

Registers the pre-handshake upgrade hook.

The one moment with request context, before the handshake completes. The bare form shares the route’s inject map (the hook’s deps resolve from the same per-connection container the handlers use); the options form declares the hook’s OWN inject plus the state tokens it provides via scope.state.

opts WebSocketUpgradeOptions<I>

handler WebSocketUpgradeHandler<I, T>

returns this

Learn: Inline handlers