BEAST(3em)

💅 BEAST 💅

ok so this is a page from the beast section of the Emilua manual pages (that's the (3em) bit, bestie — we're in the library-call girlies section) ✨

🌸 NAME 🌸

beast — the WebSocket bindings for Emilua, no cap 🦋

✨ DESCRIPTION ✨

local beast = require 'beast'

So here's the tea: this module exposes bindings for the class websocket::stream that lives in the Boost.Beast library (<https://www.boost.org/doc/libs/1_86_0/libs/beast/doc/html/index.html>) 💖. If you wanna actually know how to use these bindings, go read Boost.Beast's own documentation for an overview — that's the assignment, bestie, iykyk 📚

Okay now the important part 👑 — the whole concept of a dynamic buffer from Boost.Beast? Ignored here. Completely. Not invited to the party 🚫. Dynamic buffers as Boost.Beast (and Boost.Asio) expose them are, like, way more prone to error than usual when you hand them to programmers who are too used to GC interfaces 😭. So here we only use Emilua's byte_span type (which was inspired by Golang's slices — iconic lineage honestly) 🌈

Also ignored: beast::websocket::stream::read() 🙈 — it only works over dynamic buffers, so it just can't sit with us. But lowkey it's so easy to reimplement in pure Lua that nothing is really lost, periodt 💅

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)

🫶 that's the whole vibe: make your buffer, read some, append some, repeat until ws.is_message_done says we're done. chef's kiss 🔥

✨ and that's the page! brought to you by Emilua 0.12.1, dated the one and only 1980-01-01 (yes she's timeless 💀🎀). mwah, go read the Boost.Beast docs now, ily 🧚‍♀️💜