Core Runtime APIs
fetch
Standard fetch implementation.
const res = await fetch("https://api.example.com/data");
const data = await res.json(); // JSON
const text = await res.text(); // text
const blob = await res.blob(); // Blob
const buf = await res.arrayBuffer(); // ArrayBuffer
Companion objects Request, Response, Headers, AbortController, AbortSignal, FormData, Blob, and File are all available.
// Timeout control
const ac = new AbortController();
setTimeout(() => ac.abort(), 10000);
const res = await fetch(url, { signal: ac.signal });
// Or
const res = await fetch(url, { signal: AbortSignal.timeout(10000) });
Binary Response Optimization
For binary responses (e.g. image downloads), strongly recommend this request header:
x-rquickjs-host-offload-binary-v1: 1
Effect: explicitly declare “this response must be returned as raw binary” so the host passes the byte stream through to the plugin. Without this header, the host may preprocess binary responses (stringify, re-encode, or wrap), causing corrupted data, wrong length, or image decode failures.
const res = await fetch(url, {
headers: { "x-rquickjs-host-offload-binary-v1": "1" },
});
const buf = await res.arrayBuffer();
⚠️
arrayBuffer()may carry abyteOffset; barenew DataView(buf)/new Uint8Array(buf)reads from the wrong position. When parsing binary (index files, image headers, etc.), always construct with the offset:const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);const bytes = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
Recommendation: always include this header in
fetchImageBytes. Missing it is one of the most common reasons images fail to display.
Response measurement hostMeta
Every fetch response carries a non-standard extension field, hostMeta, with host-side measurements:
const res = await fetch(url);
const { ip, host, peerIp, bytes, ttfbMs, bodyMs } = res.hostMeta;
ip/host: which fronted IP / domain this request used; bothnullwhen host fronting is not in playpeerIp: actual TCP peer IP (the proxy address when a proxy is used)bytes: response body sizettfbMs: request sent → response headers (includes connect + TLS handshake + first byte)bodyMs: headers → body fully read;bytes / bodyMsis this request's throughput
The host only measures and never ranks; plugins can use this for passive measurement or attribution. Full host-fronting (IP direct) docs: Host Fronting & Network Measurement.
bridge
The sole bridge between the plugin and the Rust host.
Methods
bridge.call(name, ...args)— async host route callbridge.callSync(name, ...args)— sync call (blocks; use carefully)bridge.gzipCompress(input)— gzip compressbridge.gzipDecompress(input)— gzip decompress
Built-in Routes
These routes work out of the box:
Compression
compression.gzip_compresscompression.gzip_decompress
Native
native.putnative.takenative.exec
Math
math.add
Crypto routes (
crypto.*) are covered under crypto below and are not repeated here.
native
Byte buffer pool for binary data. Most cases only need fetch and bridge; direct use is not recommended.
Main methods:
native.put(input)— put data into the pool, returns idnative.take(id)— take data from the poolnative.free(id)— free buffer
console
console.log("...");
console.info("...");
console.warn("...");
console.error("...");
console.debug("...");
Output goes to host logs. Other console methods fall back to console.log-level behavior.