2026-01-24 22:40:22 +00:00
<!DOCTYPE html>
<!-- retoor <retoor@molodetz.nl> -->
< html lang = "en" >
< head >
< meta charset = "UTF-8" >
< meta name = "viewport" content = "width=device-width, initial-scale=1.0" >
< title > websocket - Wren-CLI Manual</ title >
< link rel = "stylesheet" href = "../css/style.css" >
</ head >
< body >
< button class = "mobile-menu-toggle" > Menu</ button >
< div class = "container" >
< aside class = "sidebar" >
< div class = "sidebar-header" >
< h1 >< a href = "../index.html" > Wren-CLI</ a ></ h1 >
< div class = "version" > v0.4.0</ div >
</ div >
< nav class = "sidebar-nav" >
< div class = "section" >
< span class = "section-title" > Getting Started</ span >
< ul >
< li >< a href = "../getting-started/index.html" > Overview</ a ></ li >
< li >< a href = "../getting-started/installation.html" > Installation</ a ></ li >
< li >< a href = "../getting-started/first-script.html" > First Script</ a ></ li >
< li >< a href = "../getting-started/repl.html" > Using the REPL</ a ></ li >
</ ul >
</ div >
< div class = "section" >
< span class = "section-title" > Language</ span >
< ul >
< li >< a href = "../language/index.html" > Syntax Overview</ a ></ li >
< li >< a href = "../language/classes.html" > Classes</ a ></ li >
< li >< a href = "../language/methods.html" > Methods</ a ></ li >
< li >< a href = "../language/control-flow.html" > Control Flow</ a ></ li >
< li >< a href = "../language/fibers.html" > Fibers</ a ></ li >
< li >< a href = "../language/modules.html" > Modules</ a ></ li >
</ ul >
</ div >
< div class = "section" >
< span class = "section-title" > API Reference</ span >
< ul >
< li >< a href = "index.html" > Overview</ a ></ li >
2026-01-25 03:58:39 +00:00
< li >< a href = "string.html" > String</ a ></ li >
< li >< a href = "number.html" > Num</ a ></ li >
2026-01-24 22:40:22 +00:00
< li >< a href = "http.html" > http</ a ></ li >
< li >< a href = "websocket.html" class = "active" > websocket</ a ></ li >
< li >< a href = "tls.html" > tls</ a ></ li >
< li >< a href = "net.html" > net</ a ></ li >
< li >< a href = "dns.html" > dns</ a ></ li >
< li >< a href = "json.html" > json</ a ></ li >
< li >< a href = "base64.html" > base64</ a ></ li >
< li >< a href = "regex.html" > regex</ a ></ li >
< li >< a href = "jinja.html" > jinja</ a ></ li >
< li >< a href = "crypto.html" > crypto</ a ></ li >
< li >< a href = "os.html" > os</ a ></ li >
< li >< a href = "env.html" > env</ a ></ li >
< li >< a href = "signal.html" > signal</ a ></ li >
< li >< a href = "subprocess.html" > subprocess</ a ></ li >
< li >< a href = "sqlite.html" > sqlite</ a ></ li >
< li >< a href = "datetime.html" > datetime</ a ></ li >
< li >< a href = "timer.html" > timer</ a ></ li >
< li >< a href = "io.html" > io</ a ></ li >
2026-01-25 03:58:39 +00:00
< li >< a href = "pathlib.html" > pathlib</ a ></ li >
2026-01-24 22:40:22 +00:00
< li >< a href = "scheduler.html" > scheduler</ a ></ li >
< li >< a href = "math.html" > math</ a ></ li >
</ ul >
</ div >
< div class = "section" >
< span class = "section-title" > Tutorials</ span >
< ul >
< li >< a href = "../tutorials/index.html" > Tutorial List</ a ></ li >
< li >< a href = "../tutorials/http-client.html" > HTTP Client</ a ></ li >
< li >< a href = "../tutorials/websocket-chat.html" > WebSocket Chat</ a ></ li >
< li >< a href = "../tutorials/database-app.html" > Database App</ a ></ li >
< li >< a href = "../tutorials/template-rendering.html" > Templates</ a ></ li >
< li >< a href = "../tutorials/cli-tool.html" > CLI Tool</ a ></ li >
</ ul >
</ div >
< div class = "section" >
< span class = "section-title" > How-To Guides</ span >
< ul >
< li >< a href = "../howto/index.html" > How-To List</ a ></ li >
< li >< a href = "../howto/http-requests.html" > HTTP Requests</ a ></ li >
< li >< a href = "../howto/json-parsing.html" > JSON Parsing</ a ></ li >
< li >< a href = "../howto/regex-patterns.html" > Regex Patterns</ a ></ li >
< li >< a href = "../howto/file-operations.html" > File Operations</ a ></ li >
< li >< a href = "../howto/async-operations.html" > Async Operations</ a ></ li >
< li >< a href = "../howto/error-handling.html" > Error Handling</ a ></ li >
</ ul >
</ div >
</ nav >
</ aside >
< main class = "content" >
< nav class = "breadcrumb" >
< a href = "../index.html" > Home</ a >
< span class = "separator" > /</ span >
< a href = "index.html" > API Reference</ a >
< span class = "separator" > /</ span >
< span > websocket</ span >
</ nav >
< article >
< h1 > websocket</ h1 >
< p > The < code > websocket</ code > module provides WebSocket client and server functionality implementing the RFC 6455 protocol. It supports both < code > ws://</ code > and < code > wss://</ code > (secure) connections.</ p >
< pre >< code > import "websocket" for WebSocket, WebSocketServer, WebSocketMessage</ code ></ pre >
< div class = "toc" >
< h4 > On This Page</ h4 >
< ul >
< li >< a href = "#websocket-class" > WebSocket Class</ a ></ li >
< li >< a href = "#websocketserver-class" > WebSocketServer Class</ a ></ li >
< li >< a href = "#websocketmessage-class" > WebSocketMessage Class</ a ></ li >
< li >< a href = "#opcodes" > Frame Opcodes</ a ></ li >
< li >< a href = "#examples" > Examples</ a ></ li >
</ ul >
</ div >
< h2 id = "websocket-class" > WebSocket Class</ h2 >
< p > WebSocket client for connecting to WebSocket servers.</ p >
< div class = "class-header" >
< h3 > WebSocket</ h3 >
< p > WebSocket client connection</ p >
</ div >
< h3 > Static Methods</ h3 >
< div class = "method-signature" >
< span class = "method-name" > WebSocket.connect</ span > (< span class = "param" > url</ span > ) → < span class = "type" > WebSocket</ span >
</ div >
< p > Connects to a WebSocket server.</ p >
< ul class = "param-list" >
< li >< span class = "param-name" > url</ span > < span class = "param-type" > (String)</ span > - WebSocket URL (ws:// or wss://)</ li >
< li >< span class = "returns" > Returns:</ span > Connected WebSocket instance</ li >
</ ul >
< pre >< code > var ws = WebSocket.connect("ws://echo.websocket.org")</ code ></ pre >
< div class = "method-signature" >
< span class = "method-name" > WebSocket.connect</ span > (< span class = "param" > url</ span > , < span class = "param" > headers</ span > ) → < span class = "type" > WebSocket</ span >
</ div >
< p > Connects with custom headers (useful for authentication).</ p >
< ul class = "param-list" >
< li >< span class = "param-name" > url</ span > < span class = "param-type" > (String)</ span > - WebSocket URL</ li >
< li >< span class = "param-name" > headers</ span > < span class = "param-type" > (Map)</ span > - Custom HTTP headers for handshake</ li >
</ ul >
< pre >< code > var headers = {"Authorization": "Bearer token123"}
var ws = WebSocket.connect("wss://api.example.com/ws", headers)</ code ></ pre >
< h3 > Properties</ h3 >
< div class = "method-signature" >
< span class = "method-name" > url</ span > → < span class = "type" > String</ span >
</ div >
< p > The URL this WebSocket is connected to.</ p >
< div class = "method-signature" >
< span class = "method-name" > isOpen</ span > → < span class = "type" > Bool</ span >
</ div >
< p > True if the connection is still open.</ p >
< h3 > Methods</ h3 >
< div class = "method-signature" >
< span class = "method-name" > send</ span > (< span class = "param" > text</ span > )
</ div >
< p > Sends a text message to the server.</ p >
< ul class = "param-list" >
< li >< span class = "param-name" > text</ span > < span class = "param-type" > (String)</ span > - Text message to send</ li >
</ ul >
< pre >< code > ws.send("Hello, server!")</ code ></ pre >
< div class = "method-signature" >
< span class = "method-name" > sendBinary</ span > (< span class = "param" > bytes</ span > )
</ div >
< p > Sends a binary message to the server.</ p >
< ul class = "param-list" >
< li >< span class = "param-name" > bytes</ span > < span class = "param-type" > (List)</ span > - List of bytes to send</ li >
</ ul >
< pre >< code > ws.sendBinary([0x01, 0x02, 0x03, 0x04])</ code ></ pre >
< div class = "method-signature" >
< span class = "method-name" > receive</ span > () → < span class = "type" > WebSocketMessage|null</ span >
</ div >
< p > Receives the next message from the server. Blocks until a message arrives. Returns null if the connection is closed.</ p >
< pre >< code > var msg = ws.receive()
if (msg != null && msg.isText) {
System.print("Got: %(msg.text)")
}</ code ></ pre >
< div class = "method-signature" >
< span class = "method-name" > ping</ span > ()
</ div >
< p > Sends a ping frame to the server.</ p >
< div class = "method-signature" >
< span class = "method-name" > ping</ span > (< span class = "param" > data</ span > )
</ div >
< p > Sends a ping frame with payload data (max 125 bytes).</ p >
< div class = "method-signature" >
< span class = "method-name" > pong</ span > (< span class = "param" > data</ span > )
</ div >
< p > Sends a pong frame (usually automatic in response to ping).</ p >
< div class = "method-signature" >
< span class = "method-name" > close</ span > ()
</ div >
< p > Closes the connection with status code 1000 (normal closure).</ p >
< div class = "method-signature" >
< span class = "method-name" > close</ span > (< span class = "param" > code</ span > , < span class = "param" > reason</ span > )
</ div >
< p > Closes the connection with a custom status code and reason.</ p >
< ul class = "param-list" >
< li >< span class = "param-name" > code</ span > < span class = "param-type" > (Num)</ span > - Close status code (1000-4999)</ li >
< li >< span class = "param-name" > reason</ span > < span class = "param-type" > (String)</ span > - Human-readable close reason</ li >
</ ul >
< pre >< code > ws.close(1000, "Goodbye")</ code ></ pre >
< h2 id = "websocketserver-class" > WebSocketServer Class</ h2 >
< p > WebSocket server for accepting client connections.</ p >
< div class = "class-header" >
< h3 > WebSocketServer</ h3 >
< p > WebSocket server</ p >
</ div >
< h3 > Static Methods</ h3 >
< div class = "method-signature" >
< span class = "method-name" > WebSocketServer.bind</ span > (< span class = "param" > host</ span > , < span class = "param" > port</ span > ) → < span class = "type" > WebSocketServer</ span >
</ div >
< p > Creates a WebSocket server listening on the specified host and port.</ p >
< ul class = "param-list" >
< li >< span class = "param-name" > host</ span > < span class = "param-type" > (String)</ span > - Host to bind to (e.g., "0.0.0.0", "127.0.0.1")</ li >
< li >< span class = "param-name" > port</ span > < span class = "param-type" > (Num)</ span > - Port number</ li >
</ ul >
< pre >< code > var server = WebSocketServer.bind("0.0.0.0", 8080)</ code ></ pre >
< h3 > Methods</ h3 >
< div class = "method-signature" >
< span class = "method-name" > accept</ span > () → < span class = "type" > WebSocket|null</ span >
</ div >
< p > Accepts and upgrades an incoming connection. Blocks until a client connects. Returns a WebSocket instance for the connected client.</ p >
< pre >< code > var client = server.accept()
if (client != null) {
System.print("Client connected!")
}</ code ></ pre >
< div class = "method-signature" >
< span class = "method-name" > close</ span > ()
</ div >
< p > Stops the server and closes the listening socket.</ p >
< h2 id = "websocketmessage-class" > WebSocketMessage Class</ h2 >
< p > Represents a WebSocket frame received from a connection.</ p >
< div class = "class-header" >
< h3 > WebSocketMessage</ h3 >
< p > WebSocket message/frame</ p >
</ div >
< h3 > Properties</ h3 >
< table >
< tr >
< th > Property</ th >
< th > Type</ th >
< th > Description</ th >
</ tr >
< tr >
< td >< code > opcode</ code ></ td >
< td > Num</ td >
< td > Frame opcode (1=text, 2=binary, 8=close, 9=ping, 10=pong)</ td >
</ tr >
< tr >
< td >< code > payload</ code ></ td >
< td > List</ td >
< td > Raw payload bytes</ td >
</ tr >
< tr >
< td >< code > fin</ code ></ td >
< td > Bool</ td >
< td > True if this is the final fragment</ td >
</ tr >
< tr >
< td >< code > isText</ code ></ td >
< td > Bool</ td >
< td > True if this is a text frame</ td >
</ tr >
< tr >
< td >< code > isBinary</ code ></ td >
< td > Bool</ td >
< td > True if this is a binary frame</ td >
</ tr >
< tr >
< td >< code > isClose</ code ></ td >
< td > Bool</ td >
< td > True if this is a close frame</ td >
</ tr >
< tr >
< td >< code > isPing</ code ></ td >
< td > Bool</ td >
< td > True if this is a ping frame</ td >
</ tr >
< tr >
< td >< code > isPong</ code ></ td >
< td > Bool</ td >
< td > True if this is a pong frame</ td >
</ tr >
< tr >
< td >< code > text</ code ></ td >
< td > String</ td >
< td > Payload as string (only for text frames)</ td >
</ tr >
< tr >
< td >< code > bytes</ code ></ td >
< td > List</ td >
< td > Payload as byte list</ td >
</ tr >
< tr >
< td >< code > closeCode</ code ></ td >
< td > Num</ td >
< td > Close status code (only for close frames)</ td >
</ tr >
< tr >
< td >< code > closeReason</ code ></ td >
< td > String</ td >
< td > Close reason text (only for close frames)</ td >
</ tr >
</ table >
< h2 id = "opcodes" > Frame Opcodes</ h2 >
< table >
< tr >
< th > Opcode</ th >
< th > Type</ th >
< th > Description</ th >
</ tr >
< tr >
< td > 0</ td >
< td > Continuation</ td >
< td > Continuation of fragmented message</ td >
</ tr >
< tr >
< td > 1</ td >
< td > Text</ td >
< td > UTF-8 text data</ td >
</ tr >
< tr >
< td > 2</ td >
< td > Binary</ td >
< td > Binary data</ td >
</ tr >
< tr >
< td > 8</ td >
< td > Close</ td >
< td > Connection close</ td >
</ tr >
< tr >
< td > 9</ td >
< td > Ping</ td >
< td > Ping (keepalive)</ td >
</ tr >
< tr >
< td > 10</ td >
< td > Pong</ td >
< td > Pong response</ td >
</ tr >
</ table >
< h3 > Common Close Codes</ h3 >
< table >
< tr >
< th > Code</ th >
< th > Meaning</ th >
</ tr >
< tr >
< td > 1000</ td >
< td > Normal closure</ td >
</ tr >
< tr >
< td > 1001</ td >
< td > Going away (server shutdown)</ td >
</ tr >
< tr >
< td > 1002</ td >
< td > Protocol error</ td >
</ tr >
< tr >
< td > 1003</ td >
< td > Unsupported data type</ td >
</ tr >
< tr >
< td > 1005</ td >
< td > No status received</ td >
</ tr >
< tr >
< td > 1006</ td >
< td > Abnormal closure</ td >
</ tr >
< tr >
< td > 1011</ td >
< td > Server error</ td >
</ tr >
</ table >
< h2 id = "examples" > Examples</ h2 >
< h3 > Echo Client</ h3 >
< pre >< code > import "websocket" for WebSocket
var ws = WebSocket.connect("ws://echo.websocket.org")
ws.send("Hello, WebSocket!")
var msg = ws.receive()
if (msg != null && msg.isText) {
System.print("Echo: %(msg.text)")
}
ws.close()</ code ></ pre >
< h3 > Chat Client</ h3 >
< pre >< code > import "websocket" for WebSocket
import "json" for Json
var ws = WebSocket.connect("wss://chat.example.com/socket")
ws.send(Json.stringify({
"type": "join",
"room": "general",
"username": "alice"
}))
while (ws.isOpen) {
var msg = ws.receive()
if (msg == null) break
if (msg.isClose) {
System.print("Server closed: %(msg.closeCode) %(msg.closeReason)")
break
}
if (msg.isText) {
var data = Json.parse(msg.text)
if (data["type"] == "message") {
System.print("%(data["from"]): %(data["text"])")
}
}
}
ws.close()</ code ></ pre >
< h3 > WebSocket Server</ h3 >
< pre >< code > import "websocket" for WebSocketServer
var server = WebSocketServer.bind("0.0.0.0", 8080)
System.print("WebSocket server listening on port 8080")
while (true) {
var client = server.accept()
if (client == null) continue
System.print("Client connected")
while (client.isOpen) {
var msg = client.receive()
if (msg == null) break
if (msg.isClose) {
System.print("Client disconnected")
break
}
if (msg.isText) {
System.print("Received: %(msg.text)")
client.send("Echo: %(msg.text)")
}
}
}</ code ></ pre >
< h3 > Secure WebSocket (WSS)</ h3 >
< pre >< code > import "websocket" for WebSocket
var ws = WebSocket.connect("wss://secure.example.com/socket")
ws.send("Secure message")
var response = ws.receive()
System.print(response.text)
ws.close()</ code ></ pre >
< div class = "admonition note" >
< div class = "admonition-title" > Note</ div >
< p > Ping frames are automatically responded to with pong frames. You typically do not need to handle ping/pong manually unless implementing custom keepalive logic.</ p >
</ div >
</ article >
< footer class = "page-footer" >
< a href = "http.html" class = "prev" > http</ a >
< a href = "tls.html" class = "next" > tls</ a >
</ footer >
</ main >
</ div >
< script src = "../js/main.js" ></ script >
</ body >
</ html >
