45 lines
1.9 KiB
Plaintext
45 lines
1.9 KiB
Plaintext
: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");
|