capsule

package module
v0.0.7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 10, 2023 License: MIT Imports: 15 Imported by: 3

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
}

Documentation

Overview

Package capsule SDK for host applications

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CallHandleFunction added in v0.0.2 

func CallHandleFunction(ctx context.Context, mod api.Module, handleFunction api.Function, argFunction []byte) ([]byte, error)

CallHandleFunction calls the given handleFunction with the argument argFunction and returns the result. The function uses CopyDataToMemory to copy the argument to memory, and UnPackPosSize to unpack the result. Returns a byte slice and an error.

ctx: The context.Context mod: The api.Module handleFunction: The api.Function to be called argFunction: The argument to the function

Returns ([]byte, error).

func CallOnStart added in v0.0.4 

func CallOnStart(ctx context.Context, mod api.Module, wasmFile []byte)

CallOnStart calls the OnStart function (if it exists) from the given module.

func CallOnStop added in v0.0.4 

func CallOnStop(ctx context.Context, mod api.Module, wasmFile []byte)

CallOnStop calls the OnStop function (if it exists) from the given module.

func CopyDataToMemory 

func CopyDataToMemory(ctx context.Context, mod api.Module, data []byte) (uint64, uint64, error)

CopyDataToMemory copies data to memory.

ctx: The context for this function. mod: The module to copy the data to. data: The data to be copied to memory.

uint64, uint64, error: The position of the copied data, the size of the data, and an error if one occurs.

func DefineHostFuncCacheDel 

func DefineHostFuncCacheDel(builder wazero.HostModuleBuilder)

DefineHostFuncCacheDel defines a Go function that deletes a cache entry.

Parameters: - builder: a wazero.HostModuleBuilder object.

Returns: nothing.

func DefineHostFuncCacheGet 

func DefineHostFuncCacheGet(builder wazero.HostModuleBuilder)

DefineHostFuncCacheGet defines the Go function that calls the cacheGet function to get the value of a given key. The function takes in four parameters: the position of the key, the length of the key, the position of the returned value, and the length of the returned value. It returns an integer that represents the success or failure of the function call.

func DefineHostFuncCacheKeys 

func DefineHostFuncCacheKeys(builder wazero.HostModuleBuilder)

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.

func DefineHostFuncCacheSet 

func DefineHostFuncCacheSet(builder wazero.HostModuleBuilder)

DefineHostFuncCacheSet defines a new Go module function for setting values in the cache. It takes in 6 parameters:

  • key position (int32)
  • key length (int32)
  • value string position (int32)
  • value string length (int32)
  • returned position (int32)
  • returned length (int32)

It returns an int32 value.

func DefineHostFuncGetEnv 

func DefineHostFuncGetEnv(builder wazero.HostModuleBuilder)

DefineHostFuncGetEnv defines a new host function to get the environment variable value.

Parameters: - builder: the HostModuleBuilder to add the function to.

Returns: nothing.

func DefineHostFuncHTTP 

func DefineHostFuncHTTP(builder wazero.HostModuleBuilder)

DefineHostFuncHTTP defines the host module function for handling HTTP requests.

Parameter(s): builder: the wazero.HostModuleBuilder used to define the function.

Return(s): None.

func DefineHostFuncLog 

func DefineHostFuncLog(builder wazero.HostModuleBuilder)

DefineHostFuncLog defines and exports a host module function called hostLogString. This function takes two parameters:

  • string position (i32)
  • string length (i32)

It returns an i32 value.

func DefineHostFuncPrint 

func DefineHostFuncPrint(builder wazero.HostModuleBuilder)

DefineHostFuncPrint defines the hostPrintString function which takes in a string position and string length as parameters, and returns an integer.

builder: The HostModuleBuilder object.

Returns: None.

func DefineHostFuncReadFile 

func DefineHostFuncReadFile(builder wazero.HostModuleBuilder)

DefineHostFuncReadFile defines a function that reads a file from the host file system and returns its content as a string. The function takes in four parameters: - filePath: the pointer to the string representing the file path - filePathLen: the length of the file path string - returned: a pointer to the string where the file content will be stored - returnedLen: the length of the returned string

The function returns an integer representing whether the operation was successful.

func DefineHostFuncRedisDel added in v0.0.2 

func DefineHostFuncRedisDel(builder wazero.HostModuleBuilder)

DefineHostFuncRedisDel defines a Redis Del operation for the host module builder.

This function takes in a `builder` of type `wazero.HostModuleBuilder` and creates a new function builder for Redis Del operation. The function builder is then configured with parameters and exports the function with name "hostCacheDel".

func DefineHostFuncRedisGet added in v0.0.2 

func DefineHostFuncRedisGet(builder wazero.HostModuleBuilder)

DefineHostFuncRedisGet defines a function that gets a value from Redis cache.

func DefineHostFuncRedisKeys added in v0.0.2 

func DefineHostFuncRedisKeys(builder wazero.HostModuleBuilder)

DefineHostFuncRedisKeys defines a function that exports a host module function that retrieves Redis cache keys. It takes in four parameters: filter position, filter length, returned position and returned length. It returns an integer.

func DefineHostFuncRedisSet added in v0.0.2 

func DefineHostFuncRedisSet(builder wazero.HostModuleBuilder)

DefineHostFuncRedisSet defines a Go function that sets a value in Redis.

It takes in the key and value string positions and lengths as well as the positions and lengths of the returned value. It returns an integer value.

func DefineHostFuncTalk 

func DefineHostFuncTalk(builder wazero.HostModuleBuilder)

DefineHostFuncTalk defines a host function

func DefineHostFuncWriteFile 

func DefineHostFuncWriteFile(builder wazero.HostModuleBuilder)

DefineHostFuncWriteFile creates a new function called hostWriteFile in the HostModuleBuilder. It accepts the following parameters: - filePath (int32): position - filePath (int32): length - content (int32): position - content (int32): length - returned (int32): position - returned (int32): length The function returns an int32.

func GetBuilder 

func GetBuilder(runtime wazero.Runtime) wazero.HostModuleBuilder

GetBuilder returns a new instance of the HostModuleBuilder configured with the default host functions

func GetHandle 

func GetHandle(mod api.Module) api.Function

GetHandle returns an exported function named "callHandle" from the given module.

mod: The module to retrieve the function from.

Returns: An exported function with the name "callHandle".

func GetHandleHTTP 

func GetHandleHTTP(mod api.Module) api.Function

GetHandleHTTP returns the exported 'callHandleHTTP' function from a given module.

mod: The module containing the exported function.

returns:

  • api.Function: the exported 'callHandleHTTP' function.

func GetHandleJSON 

func GetHandleJSON(mod api.Module) api.Function

GetHandleJSON returns the exported "callHandleJSON" function from the given module.

mod: the module to retrieve the function from.

returns: the exported "callHandleJSON" function.

func GetRuntime 

func GetRuntime(ctx context.Context) wazero.Runtime

GetRuntime returns the WebAssembly runtime. It takes a context and returns a wazero.Runtime object.

func InitRedisClient added in v0.0.2 

func InitRedisClient()

InitRedisClient initializes a Redis client instance if it is not already initialized.

func ReadBytesFromMemory 

func ReadBytesFromMemory(mod api.Module, pos uint32, size uint32) ([]byte, error)

ReadBytesFromMemory reads a sequence of bytes from the given module's memory starting from pos and with a length of size. It returns the bytes read and any error encountered.

func ReadBytesParameterFromMemory 

func ReadBytesParameterFromMemory(mod api.Module, pos uint32, size uint32) ([]byte, error)

ReadBytesParameterFromMemory reads a slice of bytes from the given position in memory of the provided module. Returns the slice of bytes and an error if the read operation failed due to the specified position being out of range.

mod: The module from which to read memory. pos: The starting position to read from. size: The number of bytes to read.

Returns: A slice of bytes read from memory and an error if the read operation failed.

func ReadDataFromMemory 

func ReadDataFromMemory(mod api.Module, pos uint32, size uint32) ([]byte, error)

ReadDataFromMemory reads data from a given position in the memory of a module.

Parameters: - mod: the module to read data from. - pos: the position in the memory to read from. - size: the size of the data to read.

Returns: - a byte slice containing the read data. - an error if the position or size are out of range of the memory size.

func Result 

func Result(data []byte) ([]byte, error)

Result returns the data without the first byte if the first byte is isSuccess. Otherwise, it returns nil and an error with the data starting from the second byte.

data: A byte slice containing the data to check. []byte: The data without the first byte if the first byte is isSuccess. error: If the first byte is not isSuccess, it returns an error with the data starting from the second byte.

func ReturnBytesToMemory 

func ReturnBytesToMemory(ctx context.Context, mod api.Module, positionReturnBuffer uint32, lengthReturnBuffer uint32, dataFromHost []byte) (bool, error)

ReturnBytesToMemory writes data from the host to a buffer in the module's memory and updates the buffer information in the module. It returns a boolean value indicating whether the write was successful and an error if any.

ctx: context required for the operation. mod: the module where the buffer is. positionReturnBuffer: the position in memory where the buffer's position will be written. lengthReturnBuffer: the position in memory where the buffer's length will be written. dataFromHost: the data to be written to the buffer.

Returns: - a boolean indicating whether the write was successful. - an error if any.

func TestMe added in v0.0.7 

func TestMe() string

func UnPackPosSize 

func UnPackPosSize(pair uint64) (uint32, uint32)

UnPackPosSize extracts the position and size of the returned value from a given pair.

pair: 64-bit unsigned integer. Returns a pair of 32-bit unsigned integers.

Types

This section is empty.

Source Files

View all Source files

Directories

Path Synopsis
Package models ...
 Package models ...

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.