HTTP client builtins

10 builtins of Soma 3.2.4 in the category HTTP client, with their exact signatures, as soma describe --builtins --json prints them.

• http_get
• http_post
• http_put
• http_patch
• http_delete
• ws_connect
• ws_send
• link
• subscribe
• refusal

http_get

http_get(url: String, opts?: {timeout, max_bytes, headers}) -> Map|List|String

GET a URL. 2xx: the body (JSON parsed). Never raises on the network or a status: otherwise {error, kind, status, body}; an invalid or unknown option raises kind type — kind http_status (status + the upstream body), timeout, refused or network. timeout defaults to 30000 ms.

deterministic · replay: an effect: not in the log — replay calls it again

http_post

http_post(url: String, body, opts?: {timeout, max_bytes, headers}) -> Map|List|String

POST body (a Map/List is sent as JSON, a String as is). Same result shape and default timeout as http_get. Also http_put, http_patch, http_delete(url, opts?).

deterministic · replay: an effect: not in the log — replay calls it again

http_put

http_put(url: String, body, opts?) -> Map|List|String

PUT; same shape as http_post.

deterministic · replay: an effect: not in the log — replay calls it again

http_patch

http_patch(url: String, body, opts?) -> Map|List|String

PATCH; same shape as http_post.

deterministic · replay: an effect: not in the log — replay calls it again

http_delete

http_delete(url: String, opts?) -> Map|List|String

DELETE; same shape as http_get.

deterministic · replay: an effect: not in the log — replay calls it again

ws_connect

ws_connect(url: String) -> Map

Open a send-only WebSocket connection for ws_send() → {status, url}; replies are not read (receive with subscribe(url), which dispatches {"event", "data"} messages and reconnects after a drop).

deterministic · replay: pure

ws_send

ws_send(msg) -> ()

Send a message on the current WebSocket connection; errors if not connected.

deterministic · replay: pure

link

link(addr: "host:port") -> ()

Open a TCP signal-bus link to a peer node.

deterministic · replay: pure

subscribe

subscribe(url: String) -> ()

Subscribe to a remote event stream; an {"event", "data"} message runs on event(data) only for an event this program emits or soma.toml [bus] accept lists (else refused); other text runs on ws(msg).

deterministic · replay: pure

refusal

refusal(kind: String, detail?: String) -> Map

An HTTP response — status from the kind (conflict → 409, not_found → 404, unauthorized → 401, your own tag → 400) and body {error, kind, detail}, exactly what RAISING that error would answer. Return it when the handler must refuse AND keep what it wrote (an audit row): raising rolls the writes back, returning does not. It is a response envelope like response(): read the fields through _body (r._body.kind), and return it as the handler's value.

deterministic · replay: pure