WebSocket counter example

This example demonstrates the routed app server plus SocketBox-style websocket listeners.

It serves an HTML page at /, opens a websocket connection to /ws, increments a shared counter when the button is clicked, and broadcasts the new count to every connected browser tab.

Project Structure

• app.bxs: Main routed app plus websocket listener registration.
• views/home.bxm: HTML page with the client-side websocket code.

Key Concepts

1. Listener Class Registration

WebSockets are enabled with a listener instance:

import boxlang.web;

listener = new ClickCounterSocket();
listener.configure();

app.enableWebSockets( "/ws", listener );

MatchBox snapshots the listener instance state when you register it, then restores that state inside the websocket runtime. This keeps preconfigured listener objects usable instead of forcing a zero-argument constructor.

2. Listener Lifecycle

The listener class uses the familiar SocketBox-style methods:

• onConnect( channel )
• onMessage( message, channel )
• onClose( channel )

3. Channel Helpers

The channel object currently supports:

• sendMessage() / sendText()
• sendJson()
• sendBytes()
• broadcastMessage() / broadcastText()
• broadcastJson()
• broadcastBytes()
• close()
• getId(), getPath(), getURL() and getHTTPHeader( name, [default] ), which describe the connection and its upgrade request

The Web server guide describes each method. This example uses sendJson() to initialize new connections and broadcastJson() to fan out counter changes.

Running the Example

The --app flag belongs to the matchbox_server binary, which you build from the MatchBox source tree. From the project root:

cargo run -p matchbox_server -- --app docs/examples/websocket_counter/app.bxs

Then open:

• http://localhost:8099/

Open the page in two tabs and click the button in either tab. Both tabs update to the same counter value. The count lives in the listener inside the WebSocket runtime, so it survives page reloads and resets when the server restarts.

To attach a listener without a routed app, use the websocket block of boxlang.json in a webroot; see the guide.