Host calls

The server: time, logging, health, restarts and cryptography

The server clock, the log, health and profiling, restarts and world resets, and random numbers and RSA.

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.

tick_health

fn tick_health() -> Option<TickHealth>

How long ticks are taking. None before the loop has measured one.

Wasm request

No fields besides call.

Reply: {"ok": ...} holding the Rust return value Option<TickHealth>, encoded as in conventions; objects in it carry mspt, target_mspt.

{"call": "tick_health"}

tick

fn tick() -> u64

How many ticks since the server started.

Wasm request

No fields besides call.

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

{"call": "tick"}

server_health

fn server_health() -> String

How the server is doing, as JSON: TPS, MSPT (average and longest) and CPU over 5 s, 10 s, 1 min, 5 min and 15 min, memory, and the players, creatures and worlds. For a plugin that reports server health (the spark equivalent).

Wasm request

No fields besides call.

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

{"call": "server_health"}

profiler

fn profiler(op: &str, interval_ms: u32) -> Result<String, String>

The server's sampling profiler: op is start (sampling every interval_ms), stop (answers the report: each system's share of the samples and its time, as JSON) or status. One profile runs at a time, server-wide; it stops by itself after ten minutes.

Wasm request

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

{"call": "profiler", "op": "start"}

request_restart

fn request_restart(plugin: &str, reason: &str) -> Result<bool, String>

Stops the server as /stop does -- every plugin told server_stopping and stopped, the world and everybody in it saved -- and then ends the process with RESTART_EXIT_CODE rather than nought, so the script or service that started it starts it again (see docs/restarting.md). Everybody online is disconnected with reason, each saved as they leave, and it is logged. The stop begins once the calling plugin's call has returned. Ok(false) when a restart was already asked for.

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": "request_restart"}

schedule_world_reset

fn schedule_world_reset(plugin: &str, reset: &WorldReset) -> Result<(), String>

Asks for the world to be reset the next time the server starts: before it opens, the world directory is renamed aside with the time in its name (nothing is deleted) and a fresh one is made, with reset.seed or a random seed and the generator the server is configured with, its sidecars written anew. Refused unless the server owner allowed it (world-reset.allow-plugins in rustmc.yml), because it is the most destructive thing a plugin can do. Pair it with request_restart for a wipe; asked again, the newer request replaces the older.

Wasm request

Shape: seed is a whole number, or a string holding one (a seed past 2^53 loses its low bits as a JSON number); null or missing for a random seed. reason is optional.

Shape and limits, as the router words its errors: "seed … is not a whole number that fits in 64 bits"; "seed should be a whole number, not …".

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<(), String>, encoded as in conventions. An Err arrives as {"error": "..."}.

{"call": "schedule_world_reset"}

cancel_world_reset

fn cancel_world_reset(plugin: &str) -> Result<bool, String>

Takes back a reset asked for and not yet done. Whether there was one.

Wasm request

No fields besides call.

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": "cancel_world_reset"}

secure_random

fn secure_random(length: usize) -> Result<Vec<u8>, String>

length bytes from the operating system's cryptographic source, at most 4096: for keys, tokens and challenges. An error if this server has none. Nothing else a plugin can reach is fit for that: random_get says so.

Wasm request

Shape and limits, as the router words its errors: "length is out of range"; "length is more than …".

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

{"call": "secure_random", "length": 32}

rsa_generate

fn rsa_generate(plugin: &str) -> Result<RsaKeyPair, String>

A new RSA-2048 key pair. Slow, about a second, so it is for a plugin's first start, and each plugin may ask once in 30 seconds. Here and not in a guest because one key costs thousands of calls' fuel.

Wasm request

No fields besides call.

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<RsaKeyPair, String>, encoded as in conventions; objects in it carry private, public. An Err arrives as {"error": "..."}.

{"call": "rsa_generate"}

rsa_decrypt

fn rsa_decrypt(plugin: &str, private_key: &[u8], sealed: &[u8]) -> Option<Vec<u8>>

Takes the PKCS#1 v1.5 padding off an RSA block, with a PKCS#8 DER key. None for every failure, and no reason, because a caller that could tell bad padding from a bad key could pass that on to whoever sent the block. It costs milliseconds of the tick that a guest's fuel does not count, so each plugin has about 25 a second; past that it is None too.

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 Option<Vec<u8>>, encoded as in conventions.

{"call": "rsa_decrypt"}

now

fn now() -> u64

The wall clock: milliseconds since 1970 (UTC). Ticks stop when the server does and slow when it lags; this is for what is measured in real time -- an expiry, an audit entry.

Wasm request

No fields besides call.

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

{"call": "now"}

log

fn log(plugin: &str, text: &str) -> ()

Writes a line to the server's own log, tagged with the plugin's name.

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 (), encoded as in conventions.

{"call": "log", "text": "Hello"}

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