:title
WS

:sig
WS(Request& context)

:see
>websocket
>1_COMPONENT
>1_INIT
>1_ONCE
>1_RENDER

:content
Defines the WebSocket message handler for the current `.uce` page.

Any `.uce` unit may expose both `RENDER(Request& context)` and `WS(Request& context)`. `RENDER(Request& context)` serves the initial HTTP response, while `WS(Request& context)` is called whenever a complete WebSocket message arrives for that page. Configure nginx/Apache to route WebSocket upgrade requests for `.uce` paths to the runtime's HTTP/WebSocket listener.

UCE reassembles fragmented messages before calling `WS(Request& context)`. Text and binary frames are both delivered. The current payload is available directly on `context.in`, message metadata is mirrored into `context.params["WS_..."]`, and connection-local state lives on `context.connection`.

## Connection State

`context.connection` is a broker-owned `DValue` for the current socket. It starts empty for a new client and persists across later `WS(Request& context)` calls on that same connection.

## Message Data

The current message payload is available as:

- `context.in`: current WebSocket payload
- `context.params["WS_MESSAGE"]`: same payload mirrored into the parameter map

The current message metadata is available as:

- `context.params["WS_CONNECTION_ID"]`: sender connection ID
- `context.params["WS_SCOPE"]`: current endpoint scope
- `context.params["WS_CONNECTION_COUNT"]`: number of currently connected clients in that scope
- `context.params["WS_OPCODE"]`: WebSocket opcode of the current message
- `context.params["WS_MESSAGE_TYPE"]`: `TEXT` or `BINARY`
- `context.params["WS_DOCUMENT_URI"]`: request URI of the current endpoint

Helper wrappers such as `ws_message()`, `ws_connection_id()`, `ws_scope()`, `ws_connection_count()`, `ws_opcode()`, and `ws_is_binary()` are still available when that reads better for the handler.

:example
print("WS is a unit directive; place it at top level in a .uce unit.\n");