Compute program interface
Keep this page open while you write a program for Compute. It says what a WebAssembly module may import and must export, when the platform calls it, and what happens when a call fails. For the steps to build and run one, see Write your first program, Run a program as a process and Wake a process on a timer or a schedule. The fields of Program and Process are on Resources.
What the module must look like
A program is a WebAssembly core module that uses the canonical ABI (the output of wit-bindgen for the interface below, without a component step). It is checked when you register it, and again by the node before it runs.
| Rule | Value |
|---|---|
| Size | At most 256 KiB. |
| Declared memory | A maximum is required, at most 4096 pages (256 MiB). |
| Exports | memory, cabi_realloc and the five handlers below. |
| Imports | Only functions listed on this page, from etorm:compute/host@0.1.0 and etorm:compute/objects@0.1.0. An unknown import is refused with its name. There is no WASI: no files, sockets, environment or wall clock. |
| Start function | Not allowed. |
| Interface version | 0.1.0. A program that imports a function the platform lacks is refused at registration. |
Functions a program can call
These are imported from etorm:compute/host@0.1.0. You can call them only while a handler runs.
| Function | Behaviour |
|---|---|
interfaces() -> list<interface-info> | One entry per interface of the process: index, name, mac (6 bytes), mtu, link-local (16 bytes) and prefix (the first 8 bytes of the VPC's IPv6 /64, if any). |
send(interface, frame) -> result | Queues one Ethernet frame without FCS or VLAN tag. Frames leave when the activation ends, in order. Errors: no-such-interface, too-large(limit) (also for a frame shorter than 14 bytes), bad-source-mac, queue-full. |
now() -> u64 | Monotonic nanoseconds. Only differences mean anything. It never goes back, also across a restore. |
unix-seconds() -> u64 | Wall clock in seconds since the Unix epoch. |
set-timer(id, at) | Wakes the process with timer(id) at a value of now. Setting an id again replaces it. At most 16 timers. |
cancel-timer(id) | Removes a timer. |
random(len) -> list<u8> | Secure random bytes, at most 4096 per call. |
config(key) -> option<string> | A value of the process's spec.config. |
log(level, message) | Level 0 debug, 1 info, 2 warn, 3 error. The last 50 lines are in status.logs. |
state-get() -> list<u8> | The durable state, empty before the first state-set. |
state-set(state) -> result | Replaces the state. Error too-large(limit) above spec.resources.stateMaxBytes. Takes effect only if the activation finishes. |
report(key, value) -> result | Shows a value in status.reported. The last write of a key wins and an empty value removes it. Keys are 1 to 64 bytes of A-Z a-z 0-9 _ . - (otherwise bad-key); keys and values together at most 4096 bytes (otherwise too-large). Takes effect only if the activation finishes. |
Handlers the platform calls
Export each one as etorm:compute/handler@0.1.0#<name>. All five must be exported, even if your program has nothing to do in some of them. A handler that does nothing can be empty.
| Handler | Called with | When |
|---|---|---|
start(reason) | 0 created, 1 resumed, 2 restarted, 3 restored | Once at the beginning of each life (below), before any other handler. |
scheduled(tick) | name, due (Unix seconds), missed | A schedule of the process ticked. Ticks missed while the process could not run arrive as one tick with missed above 0. |
timer(id) | The id given to set-timer | The timer is due. It never fires early, fires once, and fires late if the process could not run in time. |
frames(batch) | Up to 64 frames, oldest first, each with its interface index and bytes | Frames are waiting. |
stop() | Nothing | Before the process is suspended, stopped or replaced. It has a small allowance of fuel (20 000) to save state. |
What happens when a process wakes
An activation is one wake-up. The handlers that apply are called in this order: start (first activation of a life only), scheduled for each due tick, timer for each due timer, frames for each batch. A process is woken by a frame, one of its timers, one of its schedules, or its own lifecycle, and at most 100 times a second.
- An ephemeral process (the default) gets a new instance for every activation. Linear memory does not survive, so anything you want to keep goes through
state-set. - A resident process (
spec.residency: Resident) keeps its instance and memory between activations. A failed activation discards the instance and the next one is a new life. - A life begins at creation, at resume from
Suspended, after a failure or a restart, and after a restore from a snapshot. An ordinary wake-up is not a new life. - An activation commits as a whole. If it returns, its
state-set,report, queued frames and timer changes take effect together. If it traps, runs out of memory or exceeds a limit, none of them take effect. The frames it was given are lost, and the failure is counted. - Long calls run in slices. Execution is metered in fuel, one unit per WebAssembly instruction. A slice is 2 000 000 units (about a millisecond). A long call is paused between slices so that other processes get to run. An activation that needs more than 1000 slices fails with
ActivationTooLong. - Object writes (below) happen when called and are not part of the commit.
Limits
| What | Limit |
|---|---|
| Program module | 256 KiB (platform programs: 32 MiB) |
| Declared memory maximum | 4096 pages (256 MiB) |
| Process memory | 64 KiB times 2 to the power memoryPower (0 to 12, default 4 = 1 MiB; 12 = 256 MiB). A program that needs more at start-up is refused; growing past it fails the activation. |
| Processor | cpuMillicores 1 to 1000 (default 100; a core is 2 000 000 000 fuel a second). A process with no allowance left waits; status.usage.throttled counts the waits. cpuShare (1 to 100, default 10) is the weight when processes compete. |
| State | stateMaxBytes up to 1 MiB (default 64 KiB) |
| Config | 64 entries, 16 KiB in all |
| Interfaces per process | 8 |
| Timers per process | 16 |
| Schedules per process | 8 |
| Buckets per process | 4 |
| Frames per handler call | 64 |
| Queue per interface | 256 frames in each direction; a full ingress queue drops the newest frames (status.usage.framesDropped) |
| Frame size | 14 bytes to MTU + 14 (at most 1514) |
| Send rate per interface | 2000 frames a second sustained (burst 4000), 16 Mbit/s; the rest is dropped and counted |
| Wake-ups | 100 a second per process |
random | 4096 bytes per call |
report | 4096 bytes in all, keys up to 64 bytes |
Frames a process sends and receives
- Frames are Ethernet II: 6 bytes destination, 6 source, 2 EtherType, payload. No preamble, FCS or 802.1Q tag.
- A process receives unicast frames for its interface MAC, broadcast, and all multicast of the VPC. It does its own filtering.
sendaccepts only frames whose source is the MAC of the interface it sends on, with the multicast bit clear. A frame never returns to the interface that sent it.- MACs start with
02:e8:and are stable for as long as the interface exists. IPv6 is primary: the interface has a link-local address and the SLAAC address of its MAC in the VPC prefix (reported instatus.interfaces). IPv4 is never assigned. - Delivery is best effort. Queues overflow, a failed activation loses the frames it was given, and a restart loses what was queued. Protocols on top must handle loss, as they would on any Ethernet.
When a process fails, restarts or stops
| Event | Result |
|---|---|
| One activation fails (trap, out-of-bounds access, memory or fuel limit, malformed return) | Nothing it did is committed. The process stays Ready with condition LastActivationFailed; the error is in status.usage.lastError. |
| Five failures in a row | Phase Failed. |
restartPolicy: Always (default) or OnFailure | A Failed process starts again after 10 seconds, then 20, doubling up to 10 minutes. The new life calls start(restarted) and keeps the saved state. |
restartPolicy: Never | It stays Failed. |
desiredState: Suspended | stop runs, then nothing is delivered; state and interfaces are kept. Resuming calls start(resumed); due timers fire once. |
desiredState: Stopped | stop runs and the state is deleted. |
Whatever goes wrong, a process cannot affect another process, the node or the network beyond its own interfaces. Its only effects are frames, state, timers, reports and log lines.
Read and write objects in a bucket
A program that imports etorm:compute/objects@0.1.0 can use the buckets named in the process's spec.buckets (up to four, in the same project). Any other bucket returns not-bound. Calls are synchronous.
| Function | Behaviour |
|---|---|
get(bucket, key) | The object, or none. |
put(bucket, key, value, create-only) | Writes the object. With create-only it writes only if the key does not exist and returns false if it did; otherwise it returns true. |
delete(bucket, key) | Deletes the object. |
Keys are 1 to 1024 bytes of UTF-8, and values are up to 32 MiB. The errors are not-bound, unavailable, too-large and bad-key. Writes are not rolled back when an activation fails, so a write can outlive an activation that did not commit.
Hibernate a resident process
A resident process with spec.hibernation.bucketRef can be set to desiredState: Hibernated. Its memory, globals, state, timers and schedule positions are written as a snapshot to the bucket and the machine lets go of it. Setting Running continues it on the machine that serves its VPCs, with the same MAC and addresses, and calls start(restored). Frames that were queued are dropped, and now continues from where it was plus the time that passed. The latest snapshot is in status.snapshot. See Hibernate and resume a process.
Write the program in Rust
If you write in Rust, you do not have to use the raw interface. The etorm-guest crate wraps it for programs built for wasm32-unknown-unknown. Your program implements the Program trait (start, frames, timer, scheduled, stop, with empty defaults for the ones you leave out) and declares it with program!. Every handler gets a Cx with now, unix_seconds, send, set_timer, cancel_timer, interfaces, config, log, state, set_state, random and objects (get, put, put_new, delete). A resident process keeps the Program value between calls, and an ephemeral one gets a new value each time. The crate also builds natively with an in-memory host, so programs can be tested without a node.
The crate includes a TCP and IPv6 stack (etorm_guest::net, neighbor discovery, ICMPv6, listeners, outbound connections) driven by frames and a timer in the reserved id range 0xFFFF0000 to 0xFFFF00FF. TLS is not included. A program built with the SDK needs a declared memory maximum and a stack size that fits its memory allowance.
What the interface leaves out
Check these before you design a program around the interface.
- Frames are untagged Ethernet II up to 1514 bytes. The platform does no multicast filtering for the program, a program cannot set its MAC, and a program cannot read per-interface counters.
configis visible to everyone who can read the process, so keep secrets out of it.- A program reaches the network only through its own VPC interfaces. The platform provides no sockets and no TLS. The SDK's stack provides TCP over IPv6.
- Programs are core WebAssembly modules, without components or WASI. The SDK is for Rust.