Extism Go PDK

This library can be used to writeExtism Plug-ins in Go.

Install

Include the library with Go get:

go get github.com/extism/go-pdk

Reference Documentation

You can find the reference documentation for this library onpkg.go.dev.

Getting Started

The goal of writing anExtism plug-in is to compile your Gocode to a Wasm module with exported functions that the host application caninvoke. The first thing you should understand is creating an export. Let's writea simple program that exports agreet function which will take a name as astring and return a greeting string. Paste this into yourmain.go:

package mainimport ("github.com/extism/go-pdk")//go:wasmexport greetfunc greet() int32 {input := pdk.Input()greeting := `Hello, ` + string(input) + `!`pdk.OutputString(greeting)return 0}

Some things to note about this code:

1. The//go:wasmexport greet comment is required. This marks the greet function as anexport with the namegreet that can be called by the host.
2. Exports in the Go PDK are coded to the raw ABI. You get parameters from thehost by callingpdk.Input* functions andyou send returns back with thepdk.Output* functions.
3. An Extism export expects an i32 return code.0 is success and1 is afailure.

Install thetinygo compiler:

Seehttps://tinygo.org/getting-started/install/ for instructions for yourplatform.

Note: while the core Go toolchain has support to target WebAssembly, we findtinygo to work well for plug-in code. Please open issues on this repositoryif you try building withgo build instead & have problems!

Compile this with the command:

tinygo build -o plugin.wasm -target wasip1 -buildmode=c-shared main.go

We can now testplugin.wasm using theExtism CLI'srun command:

extism call plugin.wasm greet --input "Benjamin" --wasi# => Hello, Benjamin!

Note: Currentlywasip1 must be provided for all Go plug-ins even if theydon't need system access, however this will eventually be optional.

Note: We also have a web-based, plug-in tester called theExtism Playground

More Exports: Error Handling

Suppose we want to re-write our greeting module to never greet Benjamins. We canusepdk.SetError orpdk.SetErrorString:

//go:wasmexport greetfunc greet() int32 {name := string(pdk.Input())if name == "Benjamin" {pdk.SetError(errors.New("Sorry, we don't greet Benjamins!"))return 1}greeting := `Hello, ` + name + `!`pdk.OutputString(greeting)return 0}

Now when we try again:

extism call plugin.wasm greet --input="Benjamin" --wasi# => Error: Sorry, we don't greet Benjamins!# => returned non-zero exit code: 1echo $? # print last status code# => 1extism call plugin.wasm greet --input="Zach" --wasi# => Hello, Zach!echo $?# => 0

Json

Extism export functions simply take bytes in and bytes out. Those can bewhatever you want them to be. A common and simple way to get more complex typesto and from the host is with json:

type Add struct {A int `json:"a"`B int `json:"b"`}type Sum struct {Sum int `json:"sum"`}//go:wasmexport addfunc add() int32 {params := Add{}// use json input helper, which automatically unmarshals the plugin input into your structerr := pdk.InputJSON(&params)if err != nil {pdk.SetError(err)return 1}sum := Sum{Sum: params.A + params.B}// use json output helper, which automatically marshals your struct to the plugin output_, err := pdk.OutputJSON(sum)if err != nil {pdk.SetError(err)return 1}return 0}

extism call plugin.wasm add --input='{"a": 20, "b": 21}' --wasi# => {"sum":41}

Configs

Configs are key-value pairs that can be passed in by the host when creating aplug-in. These can be useful to statically configure the plug-in with some datathat exists across every function call. Here is a trivial example usingpdk.GetConfig:

//go:wasmexport greetfunc greet() int32 {user, ok := pdk.GetConfig("user")if !ok {pdk.SetErrorString("This plug-in requires a 'user' key in the config")return 1}greeting := `Hello, ` + user + `!`pdk.OutputString(greeting)return 0}

To test it, theExtism CLI has a--configoption that lets you pass inkey=value pairs:

extism call plugin.wasm greet --config user=Benjamin# => Hello, Benjamin!

Variables

Variables are another key-value mechanism but it's a mutable data store thatwill persist across function calls. These variables will persist as long as thehost has loaded and not freed the plug-in.

//go:wasmexport countfunc count() int32 {count := pdk.GetVarInt("count")count = count + 1pdk.SetVarInt("count", count)pdk.OutputString(strconv.Itoa(count))return 0}

Note: Use the untyped variantspdk.SetVar(string, []byte)andpdk.GetVar(string) []byteto handle your own types.

Logging

Because Wasm modules by default do not have access to the system, printing tostdout won't work (unless you use WASI). Extism provides a simplelogging function that allowsyou to use the host application to log without having to give the plug-inpermission to make syscalls.

//go:wasmexport log_stufffunc logStuff() int32 {pdk.Log(pdk.LogInfo, "An info log!")pdk.Log(pdk.LogDebug, "A debug log!")pdk.Log(pdk.LogWarn, "A warn log!")pdk.Log(pdk.LogError, "An error log!")return 0}

FromExtism CLI:

extism call plugin.wasm log_stuff --wasi --log-level=debug2023/10/12 12:11:23 Calling function : log_stuff2023/10/12 12:11:23 An info log!2023/10/12 12:11:23 A debug log!2023/10/12 12:11:23 A warn log!2023/10/12 12:11:23 An error log!

Note: From the CLI you need to pass a level with--log-level. If you arerunning the plug-in in your own host using one of our SDKs, you need to makesure that you callset_log_file to"stdout" or some file location.

HTTP

Sometimes it is useful to let a plug-inmake HTTP calls.See this example

//go:wasmexport http_getfunc httpGet() int32 {// create an HTTP Request (withuot relying on WASI), set headers as neededreq := pdk.NewHTTPRequest(pdk.MethodGet, "https://jsonplaceholder.typicode.com/todos/1")req.SetHeader("some-name", "some-value")req.SetHeader("another", "again")// send the request, get response back (can check status on response via res.Status())res := req.Send()pdk.OutputMemory(res.Memory())return 0}

By default, Extism modules cannot make HTTP requests unless you specify whichhosts it can connect to. You can use--alow-host in the Extism CLI to setthis:

extism call plugin.wasm http_get --wasi --allow-host='*.typicode.com'# => { "userId": 1, "id": 1, "title": "delectus aut autem", "completed": false }

Imports (Host Functions)

Like any other code module, Wasm not only let's you export functions to theoutside world, you can import them too. Host Functions allow a plug-in to importfunctions defined in the host. For example, if you host application is writtenin Python, it can pass a Python function down to your Go plug-in where you caninvoke it.

This topic can get fairly complicated and we have not yet fully abstracted theWasm knowledge you need to do this correctly. So we recommend reading ourconcept doc on Host Functionsbefore you get started.

A Simple Example

Host functions have a similar interface as exports. You just need to declarethem as extern on the top of your main.go. You only declare the interface as itis the host's responsibility to provide the implementation:

//go:wasmimport extism:host/user a_python_funcfunc aPythonFunc(uint64) uint64

We should be able to call this function as a normal Go function. Note that weneed to manually handle the pointer casting:

//go:wasmexport hello_from_pythonfunc helloFromPython() int32 {    msg := "An argument to send to Python"    mem := pdk.AllocateString(msg)    defer mem.Free()    ptr := aPythonFunc(mem.Offset())    rmem := pdk.FindMemory(ptr)    response := string(rmem.ReadBytes())    pdk.OutputString(response)    return 0}

Testing it out

We can't really test this from the Extism CLI as something must provide theimplementation. So let's write out the Python side here. Check out thedocs for Host SDKs to implement ahost function in a language of your choice.

from extism import host_fn, Plugin@host_fn()def a_python_func(input: str) -> str:    # just printing this out to prove we're in Python land    print("Hello from Python!")    # 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 input + "!"

Now when we load the plug-in we pass the host function:

manifest = {"wasm": [{"path": "/path/to/plugin.wasm"}]}plugin = Plugin(manifest, functions=[a_python_func], wasi=True)result = plugin.call('hello_from_python', b'').decode('utf-8')print(result)

python3 app.py# => Hello from Python!# => An argument to send to Python!

Reactor modules

Since TinyGo version 0.34.0, the compiler has native support forReactor modules.

Make sure you invoke the compiler with the-buildmode=c-shared flagso that libc and the Go runtime are properly initialized:

cd example/reactortinygo build -target wasip1 -buildmode=c-shared -o reactor.wasm ./tiny_main.goextism call ./reactor.wasm read_file --input "./test.txt" --allow-path . --wasi --log-level info# => Hello World!

Note on TinyGo 0.33.0 and earlier

TinyGo versions below 0.34.0 do not supportReactor modules.If you want to use WASI inside your Reactor module functions (exported functions otherthanmain). You can however import thewasi-reactor module to ensure that libcand go runtime are initialized as expected:

Moreover, older versions may not provide the special//go:wasmexportdirective, and instead use//export.

package mainimport ("os""github.com/extism/go-pdk"_ "github.com/extism/go-pdk/wasi-reactor")//export read_filefunc read_file() {name := pdk.InputString()content, err := os.ReadFile(name)if err != nil {pdk.Log(pdk.LogError, err.Error())return}pdk.Output(content)}func main() {}

tinygo build -target wasip1 -o reactor.wasm ./tiny_main.goextism call ./reactor.wasm read_file --input "./test.txt" --allow-path . --wasi --log-level info# => Hello World!

Note: this is not required if you only have themain function.

Generating Bindings

It's often very useful to define a schema to describe the function signaturesand types you want to use between Extism SDK and PDK languages.

XTP Bindgen is an open sourceframework to generate PDK bindings for Extism plug-ins. It's used by theXTP Platform, but can be used outside of the platformto define any Extism compatible plug-in system.

1. Install thextp CLI.

See installation instructionshere.

2. Create a schema using our OpenAPI-inspired IDL:

version: v1-draftexports:   CountVowels:      input:           type: string          contentType: text/plain; charset=utf-8      output:          $ref: "#/components/schemas/VowelReport"          contentType: application/json# components.schemas defined in example-schema.yaml...

See an example inexample-schema.yaml, or a full"kitchen sink" example onthe docs page.

3. Generate bindings to use from your plugins:

xtp plugin init --schema-file ./example-schema.yaml    1. TypeScript                        > 2. Go                                  3. Rust                                4. Python                              5. C#                                  6. Zig                                 7. C++                                 8. GitHub Template                     9. Local Template

This will create an entire boilerplate plugin project for you to get startedwith:

package main// returns VowelReport (The result of counting vowels on the Vowels input.)func CountVowels(input string) (VowelReport, error) {// TODO: fill out your implementation herepanic("Function not implemented.")}

Implement the empty function(s), and runxtp plugin build to compile yourplugin.

For more information about XTP Bindgen, see thedylibso/xtp-bindgen repository andthe officialXTP Schema documentation.

Reach Out!

Have a question or just want to drop in and say hi?Hop on the Discord!

Constants¶

Variables¶

Functions¶

func GetConfig(keystring) (string,bool)

func GetVar(keystring) []byte

func GetVarInt(keystring)int

func Input() []byte

func InputJSON(vany)error

func InputString()string

func JSONFrom(offsetuint64, vany)error

func Log(levelLogLevel, sstring)

func LogMemory(levelLogLevel, mMemory)

func Output(data []byte)

func OutputJSON(vany)error

func OutputMemory(memMemory)

func OutputString(sstring)

func ParamBytes(offsetuint64) []byte

func ParamString(offsetuint64)string

func ParamU32(offsetuint64)uint32

func ParamU64(offsetuint64)uint64

func RemoveVar(keystring)

func ResultBytes(d []byte)uint64

func ResultString(sstring)uint64

func ResultU32(duint32)uint64

func ResultU64(duint64)uint64

func SetError(errerror)

func SetErrorString(errstring)

func SetVar(keystring, value []byte)

func SetVarInt(keystring, valueint)

Types¶

type HTTPMethodint32

const (MethodGetHTTPMethod =iotaMethodHeadMethodPostMethodPutMethodPatch//RFC 5789MethodDeleteMethodConnectMethodOptionsMethodTrace)

func (mHTTPMethod) String()string

type HTTPRequest struct {// contains filtered or unexported fields}

func NewHTTPRequest(methodHTTPMethod, urlstring) *HTTPRequest

func (r *HTTPRequest) Send()HTTPResponse

func (r *HTTPRequest) SetBody(body []byte) *HTTPRequest

func (r *HTTPRequest) SetHeader(keystring, valuestring) *HTTPRequest

type HTTPRequestMeta struct {URLstring            `json:"url"`Methodstring            `json:"method"`Headers map[string]string `json:"headers"`}

type HTTPResponse struct {// contains filtered or unexported fields}

func (rHTTPResponse) Body() []byte

func (r *HTTPResponse) Headers() map[string]string

func (rHTTPResponse) Memory()Memory

func (rHTTPResponse) Status()uint16

type LogLevelint

const (LogTraceLogLevel =iotaLogDebugLogInfoLogWarnLogError)

type Memory =memory.Memory

func Allocate(lengthint)Memory

func AllocateBytes(data []byte)Memory

func AllocateJSON(vany) (Memory,error)

func AllocateString(datastring)Memory

func FindMemory(offsetuint64)Memory

func NewMemory(offsetuint64, lengthuint64)Memory