websocket

Talk to WebSocket servers: websocket.connect("wss://host/path") gives a connection with send(text), receive(timeout?), each(fn), close() and .open. Text and JSON (maps/lists) messages, TLS for wss://, pings answered automatically, messages up to 16 MB. For the server side see the server library's app.ws().

This library keeps a network connection open, so it needs the TB app on your computer. The examples here show the code; run them with tb file.tb.

import websocket

Example

Needs the TB app on your computer, so there is no Run button here.

import websocket

let ws = websocket.connect("wss://echo.example.com/socket")
ws.send({"hello": "Tanisha"})
say(ws.receive(5))
ws.close()

Functions

connect(url, options?)

returns ws

Open a WebSocket to ws://host:port/path, or to wss://... (TLS).

Options

  • headers a map of {name: value} to send, for tokens.
  • timeout seconds to connect and complete the handshake (default: 10).
  • ca_file a PEM file of certificates to trust.
  • insecure true to skip certificate checks (testing only).

Example

let ws = websocket.connect("wss://example.com/chat")
ws.send("hello")
say(ws.receive(5))
ws.close()
Visualizehow websocket.connect works

websocket.connect("wss://chat.example.com/live", {"timeout": 10}) gives <ws>

websocket.connect: your computer talking to another oneyour computerhostchat.example.com443wsssends: upgrade: websocketgets back: messages both waysoptions?timeout10result · ws<ws>

Illustration: example values, drawn from what the function does.

is_url(x)

returns bool

True if x is text starting with ws:// or wss:// and naming a host.

Visualizehow websocket.is_url works

websocket.is_url("wss://chat.example.com/live") gives true

websocket.is_url: inputs flowing into the function and the resultx"wss://chat.example.com/live"websocket.is_urlresult · booltruex"ws://localhost:8080"websocket.is_urlresult · booltruex"https://example.com"websocket.is_urlresult · boolfalse

Real result: worked out by running this example with TB while the site was built.

Values

NameValueWhat it is
websocket.max_message16777216

The biggest message send() or receive() handles (16 MB).

Visualizehow websocket.max_message works

websocket.max_message gives 16777216

The value websocket.max_messagewebsocket.max_message16777216what it isThe biggest message send() or receive()handles (16 MB).

No inputs: call it as it is.

Real value, read from TB while the site was built.

websocket.close_reasons{1000: "normal", 1001: "going away", 1002: "protocol error", 1003: "unsupport...

What the standard close codes mean.

Visualizehow websocket.close_reasons works

websocket.close_reasons gives {1000: "normal", 1001: "going away", 1002: "protocol error", 1003: "unsupported…

The value websocket.close_reasonswebsocket.close_reasons1000"normal"1001"going away"1002"protocol error"1003"unsupported data"1006"connection lost"1007"bad data"1008"policy violation"… 2 more keyswhat it isWhat the standard close codes mean.

No inputs: call it as it is.

Real value, read from TB while the site was built.