wren/manual_src/pages/api/websocket.html

{# retoor <retoor@molodetz.nl> #}
{% extends 'page.html' %}

{% set page_title = "websocket" %}
{% set breadcrumb = [{"url": "api/index.html", "title": "API Reference"}, {"title": "websocket"}] %}
{% set prev_page = {"url": "api/http.html", "title": "http"} %}
{% set next_page = {"url": "api/yaml.html", "title": "yaml"} %}

{% block 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>
{% endblock %}