duck.html.components.core.websocket

Lively Component System WebSocket implementation.

Module Contents

Classes

EventHandler	Event handler for incoming WebSocket messages.
LivelyWebSocketView	WebSocket view for handling communication between server-side HTML components and client-side via virtual DOM patching and JavaScript execution.

Functions

generate_uid

Generate a short unique ID for tracking JS execution results.

API

class duck.html.components.core.websocket.EventHandler(ws_view: duck.html.components.core.websocket.LivelyWebSocketView)

Event handler for incoming WebSocket messages.

Initialization

__slots__

(‘ws_view’, ‘event_map’, ‘session_save_lock’)

async dispatch(opcode: duck.html.components.core.opcodes.EventOpCode, data: List[Any])

Handle incoming WebSocket events.

async dispatch_component_event(data: List[Any])

Dispatch a component event e.g. Button click, then send patches to client on changes the button click event made on the component tree.

async ensure_session_saved(request)

Ensures session is saved on Lively event.

async handle_js_execution_result(data: List[Any])

Process a JavaScript execution result.

async handle_navigation(data: List[Any])

Handle a navigation request from the client.

class duck.html.components.core.websocket.LivelyWebSocketView(request, **kwargs)

Bases: duck.contrib.websockets.WebSocketView

WebSocket view for handling communication between server-side HTML components and client-side via virtual DOM patching and JavaScript execution.

Initialization

Initialize the WebSocketView with the initial HTTP upgrade request.

Parameters:

• upgrade_request – The HTTP request that initiated the WebSocket upgrade.

• **kwargs – Additional keyword arguments passed to subclasses.

Initializes internal state for compression, heartbeat, fragmentation, and communication queues.

RECEIVE_TIMEOUT

240

__slots__

(‘request’, ‘execution_futures’, ‘event_handler’)

async execute_js(code: str, timeout: Union[int, float] = None, wait_for_result: bool = False) → Optional[Any]

Sends JavaScript code to the client for execution over WebSocket, optionally awaiting the result.

Parameters:

• code – The JavaScript code to execute on the client.

• timeout – Maximum time (in seconds) to wait for a result.

• wait_for_result – Whether to wait for the feedback that the JS code has been executed.

Returns:

The result returned by the client if wait_for_result is True, otherwise None.

Return type:

Optional[Any]

Raises:

• JavascriptExecutionError – If the future is cancelled, usually due to WebSocket disconnection or the client raised an exception.

• JavascriptExecutionTimedOut – If the result was not received within the specified timeout.

• ValueError – If user specified a timeout yet wait_for_result is set to False.

async get_js_result(code: str, variable: str, timeout: Union[int, float, None] = None) → Any

Executes JavaScript on the client and retrieves the value of a specific variable.

This is useful when the server needs to fetch a value or result produced by JS code after execution.

Parameters:

• code – JavaScript code to execute.

• variable – The name of the variable whose value should be returned after execution.

• timeout – Maximum time (in seconds) to wait for the variable’s value.

Returns:

The value of the specified variable returned from the client.

Return type:

Any

Raises:

• JavascriptExecutionError – If the future is cancelled, typically due to WebSocket disconnection or the client raised an exception.

• JavascriptExecutionTimedOut – If the result is not received within the specified timeout.

async on_close(frame)

On close event.

async on_open()

On open event.

async on_receive(data: bytes, opcode: int)

Handles incoming WebSocket data.

Parameters:

• data – Message data.

• opcode – WebSocket frame opcode.

async send_data(data: Any)

Sends serialized data over the WebSocket.

async send_patches(patches: List)

Sends virtual DOM patch instructions to the client.

Parameters:

patches – A list of patch operations.

static serialize_data(data: Any) → bytes

Serializes data using MessagePack.

static unserialize_data(data: bytes) → Any

Deserializes MessagePack-encoded binary data.

async update_now(component, updates: List[str])

Sync current updates to the client immediately.

… admonition:: Notes

This uses ForceUpdate logic.

duck.html.components.core.websocket.generate_uid(length: int = 6) → str

Generate a short unique ID for tracking JS execution results.