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.
- TypeScript
- Python
- Rust
doc.allowHttp(['api.example.com']); // or doc.allowHttp() for any host (Http.fetch uses the platform's fetch)
doc.allow_http_hosts(['api.example.com']) # or doc.allow_http() for any host
graph.allow_http_hosts(["api.example.com"]); // or graph.allow_http() for any host (the "http" feature)
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 */ }