# README
Capsule Host SDK
š§ this is a work in progress
This SDK allows to create and manage a WebAssembly host application using WASI Capsule plugins.
The Capsule Host SDK use the Wazero runtime to run the host application.
Getting started: the host application
// Package main: host runtime
package main
import (
"context"
"fmt"
"log"
"os"
capsule "github.com/bots-garden/capsule-host-sdk"
)
func main() {
ctx := context.Background()
runtime := capsule.GetRuntime(ctx)
builder := capsule.GetBuilder(runtime)
// Instantiate builder with default host functions
builder.Instantiate(ctx)
defer runtime.Close(ctx)
// Load the WebAssembly module
wasmPath := "./main.wasm"
helloWasm, _ := os.ReadFile(wasmPath)
mod, _ := runtime.Instantiate(ctx, helloWasm)
// Get the reference to the WebAssembly handleFunction
handleFunction := capsule.GetHandle(mod)
pos, size, _ := capsule.CopyDataToMemory(ctx, mod, []byte("Bob Morane"))
// Call handleFunction with the position and the size of "Bob Morane"
res, _ := handleFunction.Call(ctx, pos, size)
resPos, resSize := capsule.UnPackPosSize(res[0])
bytesRes, err := capsule.ReadBytesFromMemory(mod, resPos, resSize)
if err != nil {
fmt.Println(err)
} else {
fmt.Println(string(bytesRes))
}
}
Getting started: the capsule plugin
package main
import (
capsule "github.com/bots-garden/capsule-module-sdk"
)
func main() {
capsule.SetHandle(Handle)
}
// Handle function
func Handle(param []byte) ([]byte, error) {
capsule.Log("š£ from the plugin: " + string(param))
capsule.Print("š from the plugin: " + string(param))
return []byte("Hello " + string(param)), nil
}
# Functions
CallHandleFunction calls the given handleFunction with the argument argFunction and returns the result.
CallOnStart calls the OnStart function (if it exists) from the given module.
CallOnStop calls the OnStop function (if it exists) from the given module.
CopyDataToMemory copies data to memory.
DefineHostFuncCacheDel defines a Go function that deletes a cache entry.
DefineHostFuncCacheGet defines the Go function that calls the cacheGet function to get the value of a given key.
DefineHostFuncCacheKeys defines the host function hostCacheKeys which takes in filter position, filter length, returned position, and returned length as parameters of type i32 and returns an i32.
DefineHostFuncCacheSet defines a new Go module function for setting values in the cache.
DefineHostFuncGetEnv defines a new host function to get the environment variable value.
DefineHostFuncHTTP defines the host module function for handling HTTP requests.
DefineHostFuncLog defines and exports a host module function called hostLogString.
DefineHostFuncPrint defines the hostPrintString function which takes in a string position and string length as parameters, and returns an integer.
DefineHostFuncReadFile defines a function that reads a file from the host file system and returns its content as a string.
DefineHostFuncRedisDel defines a Redis Del operation for the host module builder.
DefineHostFuncRedisGet defines a function that gets a value from Redis cache.
DefineHostFuncRedisKeys defines a function that exports a host module function that retrieves Redis cache keys.
DefineHostFuncRedisSet defines a Go function that sets a value in Redis.
DefineHostFuncTalk defines a host function.
DefineHostFuncWriteFile creates a new function called hostWriteFile in the HostModuleBuilder.
GetBuilder returns a new instance of the HostModuleBuilder configured with the default host functions.
GetHandle returns an exported function named "callHandle" from the given module.
GetHandleHTTP returns the exported 'callHandleHTTP' function from a given module.
GetHandleJSON returns the exported "callHandleJSON" function from the given module.
GetRuntime returns the WebAssembly runtime.
InitRedisClient initializes a Redis client instance if it is not already initialized.
ReadBytesFromMemory reads a sequence of bytes from the given module's memory starting from pos and with a length of size.
ReadBytesParameterFromMemory reads a slice of bytes from the given position in memory of the provided module.
ReadDataFromMemory reads data from a given position in the memory of a module.
Result returns the data without the first byte if the first byte is isSuccess.
ReturnBytesToMemory writes data from the host to a buffer in the module's memory and updates the buffer information in the module.
No description provided by the author
UnPackPosSize extracts the position and size of the returned value from a given pair.