webSocket(Default connection surface: once opted in, every socket handed to the agent speaks the agent socket protocol with zero subclass code. The surface is opt-in: it activates only when the subclass overrides a connection seam (ws,req):void|Promise<void>
authorize or
onAttach) or webSocket itself. Overriding
onConnect alone does NOT activate it — that
hook predates the surface, so a subclass already using it stays
socketless. An agent that never opted in never asked to hold sockets —
this method then throws AgentSocketsNotEnabledError before
touching the socket, and the runtime rejects the connection exactly as
it does for an actor with no webSocket handler: nothing is sent,
nothing is held.
Once opted in, the default implementation admits the socket: clients
receive a state snapshot on connect (plus message history, and event
replay when subscribed), then live pushes of every committed
setState / this.messages append /
this.events emit — and, once granted the "rpc" claim by an
authorize override, can invoke
@rpc()-decorated methods remotely. Connections pass
through authorize and
onAttach on the way in.
Override it to take ownership of raw sockets: a socket you handle
WITHOUT calling super.webSocket(ws, req) never touches the protocol
layer — no frames are sent to it and it is not counted in
attachments. Route the sockets you do want
on the protocol through super.webSocket(ws, req).
The returned promise settles once the socket is wired, not once the
connection is admitted: with the host delivering frames only after this
method returns, the negotiation runs on the client’s first frame (or on
the attachGraceMs timer for a silent client). Observe admission through
onAttach, not by reading
attachments right after the await.
Parameters
Returns
void | Promise<void>
Overrides
StatefulActor.webSocket
AgentSocketsNotEnabledError
Thrown by the defaultAgent.webSocket when the
agent has not enabled its connection surface — neither
authorize nor onAttach
is overridden, and webSocket itself is not overridden either. Overriding
onConnect alone does not enable the surface, so
an agent whose only connection code is an onConnect override still throws
this. The runtime treats an agent in that state exactly like an actor with
no webSocket handler: the socket is rejected and nothing is held.
Extends
Error