web API

pub struct HttpResponse { status: integer, body: text, headers: vector<text> }

The result of an HTTP request.

pub fn ok(self: HttpResponse) -> boolean

Returns true when the status code is in the 200-299 range.

pub fn http_get(url: text) -> HttpResponse

Send a GET request.

pub fn http_post(url: text, body: text) -> HttpResponse

Send a POST request with a body.

pub fn http_put(url: text, body: text) -> HttpResponse

Send a PUT request with a body.

pub fn http_delete(url: text) -> HttpResponse

Send a DELETE request.

pub fn http_get_h(url: text, headers: vector<text>) -> HttpResponse

GET with custom headers.

pub fn http_post_h(url: text, body: text, headers: vector<text>) -> HttpResponse

POST with custom headers.

pub fn http_put_h(url: text, body: text, headers: vector<text>) -> HttpResponse

PUT with custom headers.

pub fn http_delete_h(url: text, headers: vector<text>) -> HttpResponse

DELETE with custom headers.

pub fn http_get_range(url: text, offset: integer, len: integer) -> HttpResponse

Read the byte range [offset, offset+len) of a remote file via a Range request. Returns status 206 (Partial Content) with the raw bytes in body when the server honours ranges; a server that ignores Range returns 200 with the full body. Read the bytes with byte_at(i, response.body).

pub fn http_get_range_h(url: text, offset: integer, len: integer, headers: vector<text>) -> HttpResponse

Byte-range read with extra custom headers (e.g. If-Range / If-None-Match).

pub fn http_size(url: text) -> integer

Resolve a URL's total byte size without downloading it. Tries a HEAD request (Content-Length); if the server omits the length on HEAD (some CDNs — e.g. github-raw — only report it on GET), falls back to a 1-byte range read and takes the total from the Content-Range header. Returns -1 if size is unavailable.

pub struct WsHandler { id: integer }

An open WebSocket session, from ws_handler. It is a slot number on the native side; the connection behind it reconnects on its own.

pub fn ws_handler(url: text) -> WsHandler?

Open a WebSocket session. Returns null only if the URL is malformed; transient connection failures (server not yet up, network blip) are absorbed by the auto-reconnect loop in the Rust layer, so this call always returns a usable handle for any well-formed ws://... or wss://... URL.

wss:// (TLS) works on BOTH targets: the browser uses the platform WebSocket, and the native client dials TLS through rustls with certificate validation ON by default (default port 443). For a self-signed dev endpoint, set LOFT_WS_INSECURE_SKIP_VERIFY=1 in the native process — an explicit opt-out, never a URL option, so it cannot be baked into a deployed config by accident.

⚠ The return is WsHandler? because null is the one distinction this call exists to make: test it with == null.

pub fn send(self: WsHandler, msg: text) -> boolean

Send a text message to the server. Returns true on success; false means the connection is currently in backoff / reconnecting and the caller may retry after the next pump().

pub fn send_binary(self: WsHandler, msg: text) -> boolean

Send msg as a binary WebSocket frame (opcode 2). Loft text is a byte buffer — build it with pack_reset / pack_u8 / … / pack_take, then ship it. Returns true on success; false means the connection is currently in backoff / reconnecting.

pub fn last_opcode(self: WsHandler) -> integer

Opcode of the last frame surfaced by try_recv / pump on this handler. Use after a successful read to decide whether to interpret the payload as utf-8 text or as a binary blob.

pub fn pump(self: WsHandler, on_message: fn(text)) -> integer

Drain any pending received messages, firing on_message for each. Returns the count of messages delivered this call. Call this from a main loop (and yield to the host between iterations on the browser target) to drive event delivery without async.

pub fn try_recv(self: WsHandler) -> text?

Non-blocking single-message receive. Returns the next pending message text if one is available, null otherwise. Equivalent to a single iteration of pump without the callback — useful when the receiver wants to drive its own loop and accumulate messages locally without capturing state inside a closure.

pub fn close(self: WsHandler)

Permanently close the session (no further reconnect attempts).

pub fn sleep_ms(ms: integer)

Block the calling thread for ms milliseconds. Convenience for tests and pacing loops; non-positive values are a no-op. In the browser it returns at once — the host event loop paces there, so call frame_yield instead.

pub fn pack_reset()

Empty the per-thread pack buffer. Call before each blob.

pub fn pack_u8(b: integer)

Append a single byte to the pack buffer: the low 8 bits of b.

pub fn pack_u16_le(v: integer)

Append the low 16 bits of v, little-endian.

pub fn pack_u32_le(v: integer)

Append the low 32 bits of v, little-endian — so -1 packs as FF FF FF FF, the same bytes as 0xFFFFFFFF.

pub fn pack_take() -> text

Take the contents of the pack buffer and return them as a text whose UTF-8 bytes are exactly the buffer bytes. Resets the buffer.

pub fn byte_at(idx: integer, t: text) -> integer

Read the byte at idx of the text payload. Out-of-range (negative or past the end) returns -1. Use to decode binary frames received via try_recv / pump. Argument order is (idx, t), unlike the (text, index) order elsewhere.

pub struct WsGroupEvent { handle: integer, message: text }

What one poll found: the handler slot that had a message and the message, or handle == -1 and "" when none had.

pub struct WsGroup { _dummy: integer }

A set of handlers to receive from in one scan; see above.

pub fn ws_group() -> WsGroup

Create a new (empty) group.

pub fn add(self: WsGroup, h: WsHandler)

Add a handler to the group.

pub fn poll(self: WsGroup) -> WsGroupEvent

Poll all handles round-robin. Returns a WsGroupEvent with handle >= 0 and the message if one is ready; handle == -1 means nothing is available right now.

pub fn frame_yield()

Yield one frame to the host event loop: a no-op natively, and in the browser the suspend point that lets the event loop run. Call once per WS poll iteration so the browser event loop can deliver WebSocket messages.