moxzi-web APIalpha
Every option and method of the Moxzi runtime object and the actor objects it returns.
All methods return promises unless marked otherwise.
Imports#
| Import | From | What it is |
|---|---|---|
Moxzi | moxzi-web | The runtime. Create one with Moxzi.start |
ActorError | moxzi-web | Thrown when an actor traps or rejects. Has .canister and .method |
ExecutionLimitError | moxzi-web | An ActorError thrown when a metered message exhausts its instruction budget |
idFromName(name) | moxzi-web | The 10-byte actor id install derives from a name |
fetchMopsClosure(base, entry, token?) | moxzi-web | Fetches an entry file's sources from moxzid --project, for compiling in the page |
| glue | moxzi-web/runtime | The runtime module. Pass it as glue in page mode |
indexedDbStore(name?, storeName?) | moxzi-web/storage | A store backed by IndexedDB |
memoryStore() | moxzi-web/storage | A store backed by a Map, for tests |
attachDevtools(moxzi, { open }) | moxzi-web/devtools | Adds an inspector panel to the page. Returns { detach, refresh, snapshot } |
Moxzi.start(options)#
| Option | Default | Meaning |
|---|---|---|
worker | false | Run actors in a Web Worker |
glue | The runtime module. Required in page mode; not used in worker mode | |
workerUrl | bundled | URL of moxzi-worker.js, if you serve it yourself |
deadlineMs | 0 (none) | Stop any message that runs longer than this. Worker mode only |
meter | false | Count instructions in every actor and trap a message that exceeds instructionLimit |
instructionLimit | 0 | Positive safe-integer instruction limit per message. Required when meter is true |
http | false | Allow HTTPS outcalls. Worker mode only, and the page must be cross-origin isolated |
httpTimeoutMs | 30000 | Finite host timeout for one outcall, including its streamed response body |
timerMs | 0 (off) | Run due timers every timerMs milliseconds. Without it, call tick() |
store | null | Where persist and autosave write |
autosave | false | Save an actor after each successful update |
manualTimeNs | null | Fix the actors' clock at this time (a bigint, in nanoseconds) instead of using Date.now(). Advance it with tick(ns) |
maxActors | 24 | Maximum installed actors. Creation is refused before another instance is published |
maxInstancePages | 320 | Maximum declared linear-memory pages per actor. The host safely lowers legacy unbounded modules before compiling them |
maxTotalPages | 4000 | Aggregate reserved linear-memory capacity plus live stable-memory pages |
maxImportBytes | 134217728 | Maximum byte length accepted by restore or loadAll before parsing or allocation |
Asking for deadlineMs or http without worker: true throws. Memory limits are host policy. Module or package metadata may describe a smaller compiled limit, but it cannot raise these ceilings. A quota refusal leaves installed actors and the previous committed state usable. Metering is also runtime policy. A per-install meter: false request cannot disable a metered runtime, and installed, spawned, upgraded and restored modules inherit the same limit.
Installing and upgrading#
| Method | Returns |
|---|---|
install({ name, wasm, arg, initTypes, idlFactory, meter }) | An actor object. wasm is bytes or a URL. arg and initTypes are the actor class arguments, if any. With a store, a saved actor is restored instead of initialised. meter may opt one actor into metering when the runtime is unmetered; it cannot opt out of runtime metering |
upgrade({ name, wasm, arg, initTypes, idlFactory }) | An actor object running the new code, with its state kept |
actor(name or id, idlFactory?) | An actor object for an actor that's already installed or loaded. Not async |
Use id (a Uint8Array) instead of name to address an actor by id.
Actor objects#
An actor object has one method per method in its idlFactory, plus:
| Member | Meaning |
|---|---|
id | The actor's id, a Uint8Array |
callRaw(method, argBytes?) | Send an update with Candid bytes. method is the export name, such as canister_update greet |
queryRaw(method, argBytes?) | The same for queries (canister_query greet) |
logs() | The actor's Debug.print output since the last read |
Methods marked query or composite_query in the idlFactory are sent as queries. See Candid in JavaScript for argument and result types.
Saving and restoring#
| Method | Meaning |
|---|---|
persist(name or id?) | Write one actor, or every installed actor, to the store |
forget(name or id) | Delete an actor's saved state, so the next install starts fresh |
save(name or id) | One actor's state as bytes |
restore(name or id, bytes) | Replace one actor's state |
saveAll() | The whole runtime as bytes, including actors created by other actors |
loadAll(bytes?) | Load a saveAll result (or the store's copy). Returns how many actors were loaded. Lifecycle hooks don't run |
Actors created by other actors exist only inside the runtime. Use saveAll and loadAll to keep them.
Timers#
| Method | Meaning |
|---|---|
tick(nowNs?) | Run due timers. Returns how many ran. With manualTimeNs, sets the clock first |
Deadlines and recovery#
| Member | Meaning |
|---|---|
canPreempt | true in worker mode. Not async |
withDeadline(ms, fn) | Run fn with a different deadline for the calls it makes |
recover() | Restart the worker and restore every installed actor from its last saved state. Called automatically when a deadline is hit |
stop() | Stop timers and the worker |
Instruction exhaustion fails with ExecutionLimitError and rolls back that message while the worker remains live. When the wall fallback fires, it fails with ActorError; the worker is restarted from the last committed whole-runtime checkpoint, including actors created by other actors and the saved timer policy.
Inspecting#
| Method | Returns |
|---|---|
logs(name or id) | Debug.print output since the last read |
history(name or id) | Recent messages: method, caller, size, outcome |
candidOf(name or id) | The Candid interface of the running module, or null |
canisterIds() | Every actor in the runtime, including ones created by other actors |