Skip to main content

HTTP Network Library (Http)

Http lets a document make network requests. Like file and environment access, it's off by default: a document can't reach the network unless the app running it says so. That matters when the document came from a model or a user, so the app decides exactly where it can connect.

Turning It On​

The host turns on Http, either for any host or, better for documents you didn't write, for a list of hosts. A request to any other host throws, and so does a response that redirects to one.

doc.allowHttp(['api.example.com']); // or doc.allowHttp() for any host (Http.fetch uses the platform's fetch)

An entry is a host name (any port) or a host and port, like localhost:8080.

Any host means any public host. Your machine and private networks (localhost, 10.x, 192.168.x, 169.254.x where cloud providers serve instance credentials, *.internal, ...) stay off limits, on every redirect too, unless you list them or allow them with doc.allowPrivateNetwork() (allow_private_network() in Python and Rust). Rust and Python also check every address a name resolves to; JavaScript can't, so list the hosts when that matters. See Security and the Sandbox.

To give one part of a document fewer hosts than the rest (a plugin, say), seal it with hosts: doc.seal('plugins.weather', { hosts: ['api.weather.example'] }). Its requests (and redirects) must be to one of those hosts, and on your list too. doc.disallowHttp([...]) removes hosts from your list. See Confining Code From Somewhere Else.

The stof CLI turns on Http for any host, since it runs your own files.

The examples on this page aren't runnable on this site, because the docs don't give documents network access.

How Requests Run​

Http.fetch is async: it starts the request in its own process, so the rest of the document keeps running, and you await the response when you need it. Start several requests before awaiting any of them and they run in parallel. See Async for how processes work.

Making Requests​

async Http::fetch(url: str, method: str = "get", body: str | blob = null, headers: map = null, timeout: seconds = null, query: map = null, bearer: str = null, max: bytes = null) -> Promise<map>​

Makes a request and returns the response as a map: status, ok, headers, content_type, and bytes (the body). Every other function on this page reads that map. timeout is in seconds (or any time, like 500ms), query adds URL query parameters, and bearer sets an Authorization: Bearer header. max is the largest response it reads (like 10MB), by default the call's memory limit: a larger response isn't read, and the map has an error instead of a status, so a server can't make your app hold more than the document may.

const resp = await Http::fetch("https://restcountries.com/v3.1/region/europe");

Reading the Response​

Http::success(response: map) -> bool​

Status in [200, 299].

const resp = await Http::fetch("https://restcountries.com/v3.1/region/europe");
assert(Http::success(resp));

Http::client_error(response: map) -> bool​

Status in [400, 499].

assert_not(Http::client_error(resp));

Http::server_error(response: map) -> bool​

Status in [500, 599].

assert_not(Http::server_error(resp));

Http::text(response: map) -> str​

The response body as UTF-8 text, the same as Http::blob(response) as str.

const body = Http::text(resp);

Http::blob(response: map) -> blob​

The response body as raw bytes.

const body = Http::blob(resp);

Http::size(response: map) -> bytes​

The response body's size, as a memory unit, so it converts to any other memory unit:

const mib_body_size = Http::size(resp) as MiB;

Http::parse(response: map, context: obj = self) -> obj​

Parses the response body into an object (and returns it), using the response's Content-Type header to pick the format, so a JSON response is parsed as JSON. Without that header it's parsed as Stof. Throws if the format isn't one this document has, or if there's no body:

const body = new {};
try { Http::parse(resp, body); }
catch { /* didn't work out */ }