Host calls

Outbound HTTP and plugin ports

Fetching from the web, sending to an owner-granted URL, and listening on an owner-granted port.

Generated by tools/gen_api_docs.py; do not edit by hand. See host calls for how a call is made and how values are encoded. Each example shows the shape of a Wasm request with its required fields; the values in it are illustrative.

http_fetch

fn http_fetch(plugin: &str, url: &str) -> Result<u64, String>

Starts fetching url (https only, a GET), answering at once with a number to ask http_result about. Every redirect has to be https too, and every address a host resolves to public: never this machine or its network. The body is at most 16 MiB and the fetch at most 30 s. At most 8 per plugin running or finished and not read to the end. An answer left unread goes after five minutes, or sooner if too much text is held. The body is text: bytes that are not UTF-8 become U+FFFD.

Wasm request

Router notes: plugin is never sent by a Wasm guest: the server fills it in from the manifest name.

Reply: {"ok": ...} holding the Rust return value Result<u64, String>, encoded as in conventions. An Err arrives as {"error": "..."}.

{"call": "http_fetch", "url": "https://example.com/"}

http_result

fn http_result(plugin: &str, fetch: u64, offset: usize, length: usize) -> Option<Result<HttpPiece, String>>

A finished fetch: its status and up to length bytes (at most 1 MiB) of the body from byte offset on, or why it failed. None while it runs, and for a number this plugin was not given. The fetch is forgotten once the piece reaching the end of the body is taken.

Wasm request

Shape and limits, as the router words its errors: "fetch is out of range"; "offset is out of range"; "length is out of range".

Router notes: plugin is never sent by a Wasm guest: the server fills it in from the manifest name.

Reply: {"ok": ...} holding the Rust return value Option<Result<HttpPiece, String>>, encoded as in conventions; objects in it carry status, body, total, next, error. An Err arrives as {"error": "..."}.

{"call": "http_result", "fetch": 1}

http_send

fn http_send(plugin: &str, grant: &str, request: &HttpSend) -> Result<u64, String>

Sends request to one of this plugin's outbound grants: the plugin-outbound.<plugin>.<grant> section of rustmc.yml, whose URL the path is appended to. The URL is the owner's, never the plugin's. GET or POST; no redirect is followed, so a 3xx is the answer. Answers at once with a number to ask http_result about, sharing the per-plugin cap with http_fetch. A grant reaches this machine's network only when it says private.

Needs: a plugin-outbound.<plugin>.<grant> section in rustmc.yml .

Wasm request

Router notes: The URL is the owner's, from the grant: a guest names the grant and nothing more. plugin is never sent by a Wasm guest: the server fills it in from the manifest name.

Reply: {"ok": ...} holding the Rust return value Result<u64, String>, encoded as in conventions. An Err arrives as {"error": "..."}.

{"call": "http_send", "method": "POST", "path": "/hook", "grant": "api"}

net_listen

fn net_listen(plugin: &str, grant: &str) -> Result<NetListening, String>

Opens one of this plugin's grants: the plugin-ports.<plugin>.<grant> section of rustmc.yml. Nothing else can open a port. The address, the port, the mode and every limit are the owner's, so a plugin names the grant and nothing more. Asking again for one already open answers the same. Everything a plugin opened closes when it unloads.

Needs: a plugin-ports.<plugin>.<grant> section in rustmc.yml .

Wasm request

Router notes: The plugin is the caller, from the manifest: a guest that could name one could take another's port, or read what its clients sent. plugin is never sent by a Wasm guest: the server fills it in from the manifest name.

Reply: {"ok": ...} holding the Rust return value Result<NetListening, String>, encoded as in conventions; objects in it carry port, mode. An Err arrives as {"error": "..."}.

{"call": "net_listen", "grant": "api"}

net_unlisten

fn net_unlisten(plugin: &str, grant: &str) -> bool

Closes a grant and every connection on it. Whether it was open.

Needs: a plugin-ports grant (see net_listen).

Wasm request

Router notes: plugin is never sent by a Wasm guest: the server fills it in from the manifest name.

Reply: {"ok": ...} holding the Rust return value bool, encoded as in conventions.

{"call": "net_unlisten", "grant": "api"}

net_poll

fn net_poll(plugin: &str, max_bytes: usize) -> Vec<NetEvent>

What happened on this plugin's ports, oldest first. Nothing runs a plugin when bytes arrive: a plugin asks, normally each tick, so traffic cannot spend its fuel or the server's, and one that stops asking delays only its own clients until its limits turn them away. Stops before max_bytes (at most 1 MiB), with every event counted as at least 256 bytes so that a budget limits empty ones too, though one event always comes if any waits.

Needs: a plugin-ports grant (see net_listen).

Wasm request

Shape and limits, as the router words its errors: "max_bytes is out of range".

Router notes: plugin is never sent by a Wasm guest: the server fills it in from the manifest name.

Reply: {"ok": ...} holding the Rust return value Vec<NetEvent>, encoded as in conventions.

{"call": "net_poll"}

net_send

fn net_send(plugin: &str, connection: u64, bytes: &[u8]) -> Result<bool, String>

Sends bytes on a connection, after an http one's net_respond said more. False if it has gone. An error if the grant's max-queued-kib would be passed, so a plugin sending a lot sends a piece at a time.

Needs: a plugin-ports grant (see net_listen).

Wasm request

Router notes: plugin is never sent by a Wasm guest: the server fills it in from the manifest name.

Reply: {"ok": ...} holding the Rust return value Result<bool, String>, encoded as in conventions. An Err arrives as {"error": "..."}.

{"call": "net_send", "connection": 1}

net_respond

fn net_respond(plugin: &str, connection: u64, status: u16, headers: &[(String, String)], body: &[u8], more: bool) -> Result<bool, String>

Answers an http request, once. The server writes Content-Length and Connection: close, and closes when the body is out. With more it writes neither length nor end: send the rest with net_send, and finish with net_close. False if the client has gone. Headers that could split the response are an error.

Needs: a plugin-ports grant (see net_listen).

Wasm request

Shape and limits, as the router words its errors: "status is out of range".

Router notes: plugin is never sent by a Wasm guest: the server fills it in from the manifest name.

Reply: {"ok": ...} holding the Rust return value Result<bool, String>, encoded as in conventions. An Err arrives as {"error": "..."}.

{"call": "net_respond", "connection": 1, "status": 200}

net_close

fn net_close(plugin: &str, connection: u64) -> bool

Closes a connection once what is waiting to go has gone. Whether it was open.

Needs: a plugin-ports grant (see net_listen).

Wasm request

Router notes: plugin is never sent by a Wasm guest: the server fills it in from the manifest name.

Reply: {"ok": ...} holding the Rust return value bool, encoded as in conventions.

{"call": "net_close", "connection": 1}

From docs/api/reference/host-calls/network.md in the RustMC repository at bbd81209ad.