BEAST(3em)

💅 NAME ✨

okay so this is beast — the WebSocket bindings for Emilua, and you're reading the BEAST(3em) page, bestie. iconic 🦋

🌈 SYNOPSIS 💖

here's the vibe check, literally the whole flow:

local websocket = require 'beast'.websocket
local tls = require 'tls'

local host = 'example.com'

local ws = websocket.new(tls.dial(host .. ':https'))
ws:handshake(host, '/')

local text = nil
local buf = byte_span.new(ws:read_size_hint())
repeat
    print('reading...')
    local nread = ws:read_some(buf)
    text = byte_span.append(text, buf:slice(1, nread))
until ws.is_message_done
print(text)

🛠️ FUNCTIONS ✨

new(socket: ip.tcp.socket|tls.socket) → websocket

Constructor. periodt 💅

Heads up: the previous socket object is moved-from and becomes an invalid object — like, it's giving ex-socket energy, don't touch it after 💀.

get_option(self, opt: string) → value

Get an option from the socket. slay ✨

Currently available options are:

• "timeout: { handshake_timeout: number, idle_timeout: number, keep_alive_pings: boolean }" — stream option to control the behavior of websocket timeouts.
• "permessage_deflate: { client_enable: boolean, client_max_window_bits: integer, client_no_context_takeover: boolean, compLevel: integer, memLevel: integer, msg_size_threshold: integer, server_enable: boolean, server_max_window_bits: integer, server_no_context_takeover: boolean }" — permessage-deflate extension options.

set_option(self, opt: string, val)

Set an option on the socket. the way that works 🎀

Currently available options are:

• "timeout: "client"|"server"|{ handshake_timeout: "none"|number|nil, idle_timeout: "none"|number|nil, keep_alive_pings: boolean|nil }" — stream option to control the behavior of websocket timeouts.
• "permessage_deflate: { client_enable: boolean|nil, client_max_window_bits: integer|nil, client_no_context_takeover: boolean|nil, compLevel: integer|nil, memLevel: integer|nil, msg_size_threshold: integer|nil, server_enable: boolean|nil, server_max_window_bits: integer|nil, server_no_context_takeover: boolean|nil }" — permessage-deflate extension options.

accept(self)

Perform the WebSocket handshake in the server role. server main character energy 👑

close(self)

okay so there are four close flavors, bestie:

function close(self)                                              (1)
function close(self, reason_code: integer)                        (2)
function close(self, reason_string: string)                       (3)
function close(self, reason_code: integer, reason_string: string) (4)

Send a websocket close control frame. bye bye bye 🫶

handshake(self, host: string, target: string[, extra_headers: { [string]: string }])

Perform the WebSocket handshake in the client role. client-side slay ⭐

You can send extra headers in the opening handshake through the extra_headers parameter. Optional headers such as "origin" aren’t added by default. A list of common headers that might be of interest follows:

• "origin" — compare the "origin" to the "host" to block malicious scripts coming from web browsers.
• "cookie" — authentication token.
• "sec-websocket-protocol" — if present, this value indicates one or more comma-separated subprotocols the client wishes to speak, ordered by preference.

ping(self, payload: string)

Send a websocket ping control frame. ping bestie 🍓

pong(self, payload: string)

Send a websocket pong control frame. pong right back 🦋

read_size_hint(self[, initial_size: integer]) → integer

Returns a suggested maximum buffer size for the next call to read. helpful little hint 🌸

read_some(self, buffer: byte_span) → integer

Read some message data. reading era 😭

write_some(self, fin: boolean, buffer: byte_span) → integer

Write some message data. writing era ✨

write(self, buffer: byte_span) → integer

Write a complete message. whole message, no crumbs 💅

🦋 PROPERTIES 💅

auto_fragment: boolean

Automatic fragmentation. Read-write property. fragment it, bestie 🎀

binary: boolean

Binary message write option. Read-write property. binary vibes ⭐

compress: boolean

Compress message write option. Read-write property. squeeze it 🌈

got_binary: boolean

Whether the latest message data indicates binary. binary check 🔥

got_text: boolean

Whether the latest message data indicates text. text check 💖

is_message_done: boolean

Whether the last completed read finished the current message. done done done ✅

is_open: boolean

Whether the socket is open. open for business 👑

read_message_max: integer

The maximum incoming message size option. Read-write property. size limit tea 🍓

reason_code: integer

The close reason code received from the remote peer. remote peer said what now 🙈

reason_string: string

The close reason string received from the remote peer. receipts from the remote peer 😭

secure_prng: boolean

Whether the PRNG is cryptographically secure. Write-only property. write-only, no peeking 💀

text: boolean

Text message write option. Read-write property. text me 💌

write_buffer_bytes: integer

Write buffer size option. Read-write property. buffer size slay 🫶

---

okay that's the whole page, bestie 🫶 — footer tea: source/version Emilua 0.12.1, date 1980-01-01, manual BEAST(3em) ✨💖