Extism Rust PDK
This library can be used to write Extism Plug-ins in Rust.
Install
Generate a lib
project with Cargo:
Add the library from crates.io.
Change your Cargo.toml
to set the crate-type to cdylib
(this instructs the compiler to produce a dynamic library, which for our target will be a Wasm binary):
[]
= ["cdylib"]
Getting Started
The goal of writing an Extism plug-in is to compile your Rust code to a Wasm module with exported functions that the host application can invoke. The first thing you should understand is creating an export. Let's write a simple program that exports a greet
function which will take a name as a string and return a greeting string. For this, we use the #[plugin_fn]
macro on our exported function:
use *;
Since we don't need any system access for this, we can compile this to the lightweight wasm32-unknown-unknown
target instead of using the wasm32-wasi
target:
Note: You can also put a default target in
.cargo/config.toml
:
[]
= "wasm32-unknown-unknown"
This will put your compiled wasm in target/wasm32-unknown-unknown/debug
.
We can now test it using the Extism CLI's run
command:
# => Hello, Benjamin!
Note: We also have a web-based, plug-in tester called the Extism Playground
More About Exports
Adding the plugin_fn macro to your function does a couple things. It exposes your function as an export and it handles some of the lower level ABI details that allow you to declare your Wasm function as if it were a normal Rust function. Here are a few examples of exports you can define.
Primitive Types
A common thing you may want to do is pass some primitive Rust data back and forth. The plugin_fn macro can map these types for you:
Note: The plugin_fn macro uses the convert crate to automatically convert and pass types across the guest / host boundary.
// f32 and f64
// i32, i64, u32, u64
// u8 vec
// Strings
Json
We provide a Json type that allows you to pass structs that implement serde::Deserialize as parameters and serde::Serialize as returns:
The same thing can be accomplished using the extism-convert
derive macros:
Raw Export Interface
plugin_fn is a nice macro abstraction but there may be times where you want more control. You can code directly to the raw ABI interface of export functions.
pub unsafe extern "C"
Configs
Configs are key-value pairs that can be passed in by the host when creating a plug-in. These can be useful to statically configure the plug-in with some data that exists across every function call. Here is a trivial example:
To test it, the Extism CLI has a --config
option that lets you pass in key=value
pairs:
# => Hello, Benjamin!
Variables
Variables are another key-value mechanism but it's a mutable data store that will persist across function calls. These variables will persist as long as the host has loaded and not freed the plug-in. You can use var::get and var::set to manipulate them.
Logging
Because Wasm modules by default do not have access to the system, printing to stdout won't work (unless you use WASI). Extism provides some simple logging macros that allow you to use the host application to log without having to give the plug-in permission to make syscalls. The primary one is log! but we also have some convenience macros named by log level:
From Extism CLI:
Note: From the CLI you need to pass a level with
--log-level
. If you are running the plug-in in your own host using one of our SDKs, you need to make sure that you callset_log_file
to"stdout"
or some file location.
HTTP
Sometimes it is useful to let a plug-in make HTTP calls.
Note: See HttpRequest docs for more info on the request and response types:
Imports (Host Functions)
Like any other code module, Wasm not only let's you export functions to the outside world, you can import them too. Host Functions allow a plug-in to import functions defined in the host. For example, if you host application is written in Python, it can pass a Python function down to your Rust plug-in where you can invoke it.
This topic can get fairly complicated and we have not yet fully abstracted the Wasm knowledge you need to do this correctly. So we recommend reading out concept doc on Host Functions before you get started.
A Simple Example
Host functions have a similar interface as exports. You just need to declare them as extern
on the top of your lib.rs
. You only declare the interface as it is the host's responsibility to provide the implementation:
extern "ExtismHost"
To declare a host function in a specific namespace, pass the module name to the host_fn
macro:
Note: The types we accept here are the same as the exports as the interface also uses the convert crate.
To call this function, we must use the unsafe
keyword. Also note that it automatically wraps the
function return with a Result in case the call fails.
Testing it out
We can't really test this from the Extism CLI as something must provide the implementation. So let's write out the Python side here. Check out the docs for Host SDKs to implement a host function in a language of your choice.
# just printing this out to prove we're in Python land
# let's just add "!" to the input string
# but you could imagine here we could add some
# applicaiton code like query or manipulate the database
# or our application APIs
return +
Now when we load the plug-in we pass the host function:
=
=
=
# => Hello from Python!
# => An argument to send to Python!
Reach Out!
Have a question or just want to drop in and say hi? Hop on the Discord!