Runtime Architecture
Thepalyra-plugins-runtime is built on top of Wasmtime and Cranelift. It is responsible for instantiating WASM modules, enforcing resource quotas (fuel and memory), and providing the “bridge” between the guest WASM module and the Palyra host services.
Key Components
WasmRuntime: The primary entry point for the host. It manages thewasmtime::Engineand appliesRuntimeLimitsto every execution crates/palyra-plugins/runtime/src/lib.rs#105-108.RuntimeStoreState: Holds the state for a specific WASM instance, including itsStoreLimitsand theCapabilityHandlesit is authorized to use crates/palyra-plugins/runtime/src/lib.rs#201-204.- Fuel & Epoch Interruption: The runtime uses Wasmtime’s fuel mechanism to prevent infinite loops and epoch-based interruption for wall-clock timeouts crates/palyra-plugins/runtime/src/lib.rs#117-118.
WasmRuntime Execution Flow
The following diagram illustrates the lifecycle of a plugin execution from the daemon’s perspective. Plugin Execution Sequence Sources: crates/palyra-plugins/runtime/src/lib.rs#152-186, crates/palyra-daemon/src/wasm_plugin_runner.rs#114-126Resource Limits & Fuel Budgets
To prevent Resource Exhaustion attacks, the runtime enforces strict limits defined inRuntimeLimits crates/palyra-plugins/runtime/src/lib.rs#24-29.
| Limit | Description | Default Value |
|---|---|---|
fuel_budget | Maximum instructions allowed (Wasmtime fuel) | 10,000,000 |
max_memory_bytes | Linear memory allocation limit | 64 MiB |
max_table_elements | Maximum elements in WASM tables | 100,000 |
max_instances | Maximum concurrent module instances | 256 |
WasmPluginRunnerPolicy in the daemon further refines these limits and adds higher-level constraints such as max_module_size_bytes crates/palyra-daemon/src/wasm_plugin_runner.rs#18-30.
Sources: crates/palyra-plugins/runtime/src/lib.rs#31-40, crates/palyra-daemon/src/wasm_plugin_runner.rs#18-30
Host Capabilities & SDK Interface
Plugins do not have direct access to the network, filesystem, or secrets. Instead, they must request capabilities in their manifest, which are then mapped to integer handles at runtime.Capability Import Interface
The host exports several functions to the guest under thepalyra:host/capabilities module (defined by HOST_CAPABILITIES_IMPORT_MODULE crates/palyra-plugins/runtime/src/lib.rs#3-9).
- Count Functions: Returns the number of granted items for a category (e.g.,
host_capability_http_count). - Handle Functions: Returns a handle for a specific index (e.g.,
host_capability_http_handle).
Handle Range Mapping
To prevent handle confusion, handles are partitioned into specific ranges:- HTTP: 10,000+
- Secrets: 20,000+
- Storage: 30,000+
- Channels: 40,000+
Implementation Details
Module Resolution
TheWasmPluginRunner in the daemon handles the resolution of WASM bytes from multiple sources crates/palyra-daemon/src/wasm_plugin_runner.rs#179-182:
- Inline Payloads:
module_wat(WebAssembly Text) ormodule_base64crates/palyra-daemon/src/wasm_plugin_runner.rs#202-213. - Installed Skills: Resolving a
skill_idandtool_idto a specific.wasmfile within the skill’s directory crates/palyra-daemon/src/wasm_plugin_runner.rs#85-94.
Error Handling
The runtime distinguishes between different failure modes using theRuntimeError enum crates/palyra-plugins/runtime/src/lib.rs#90-103:
Compile: Validation or compilation failure.ExecutionLimitExceeded: Guest ran out of fuel or memory.ExecutionTimedOut: Wall-clock timeout triggered by epoch interruption.
WasmPluginRunErrorKind for the Gateway response crates/palyra-daemon/src/wasm_plugin_runner.rs#44-51.
Sources: crates/palyra-daemon/src/wasm_plugin_runner.rs#96-126, crates/palyra-plugins/runtime/src/lib.rs#90-103