sdk

package module
v0.0.0-...-634d4eb Latest Latest
Warning

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

 Go to latest Published: Sep 12, 2023 License: MIT Imports: 16 Imported by: 1

README

Module SDK for Go

This module provides glue code to implement a buildr WASI module easily and quickly. To implement a new buildr WASI module:

  1. Create a new Go module
  2. Reference this SDK (go get -u code.icb4dc0.de/buildr/wasi-module-sdk-go)
  3. create a main.go with an empty main() function
  4. implement the sdk.Module interface for your module
  5. implement an init() function that registers your module and the SDK's type registry
  6. compile the module e.g. with tinygo

See also the examples directory to get started.

Dependencies

easyjson

Right now the SDK depends on easyjson to unmarshal the modules state as defined in the HCL configuration. The main reason for this is that the reflection support in TinyGo is limited and for instance encoding/json heavily depends on reflection. The SDK itself uses protobuf (vtprotobuf) to exchange data with the host without reflection but this is not generic enough to support every possibility of module configuration (e.g. map<string, string> would require extra encoding/decoding steps, same for map<string, bytes). Therefore, the SDK requires you to generate easyjson compatible unmarshal functions.

slog

buildr is using slog for logging (as soon as Go 1.21 is released it will move to the final version) and also the SDK is using it to allow modules log messages. When using the SDK there's nothing to be done except using the logger the is provided by the ExecutionContext. Alternatively it'd be possible to log to STDOUT/STDERR but keep in mind that logs written to these streams directly will be 'mixed' with the output of other processes.

Documentation

Index

Constants

View Source 
const (
	CategoryTool    = commonv1.Category_CategoryTool
	CategoryTask    = commonv1.Category_CategoryTask
	CategoryBuild   = commonv1.Category_CategoryBuild
	CategoryPackage = commonv1.Category_CategoryPackage
	CategoryRelease = commonv1.Category_CategoryRelease
)

Variables

This section is empty.

Functions

func BinaryNameFor 

func BinaryNameFor(ptr, size uint32) uint64

func BinaryNameForModule 

func BinaryNameForModule(req *wasiv1.BinaryNameRequest) (*wasiv1.BinaryNameResponse, error)

func GetInventory 

func GetInventory(*wasiv1.PluginInventoryRequest) (*wasiv1.PluginInventoryResponse, error)

func GetState 

func GetState(req *remotev1.GetStateRequest) (*remotev1.GetStateResponse, error)

func HelpFor 

func HelpFor(ptr, size uint32) uint64

func HelpForModule 

func HelpForModule(helpRequest *wasiv1.HelpRequest) (*wasiv1.HelpResponse, error)

func Inventory 

func Inventory(ptr, size uint32) uint64

func LogMsg 

func LogMsg(taskLog *remotev1.TaskLog) (*remotev1.Result, error)

func Register 

func Register(cat Category, moduleName string, factory Factory)

func Run 

func Run(ptr, size uint32) uint64

func SetState 

func SetState(req *remotev1.SetState) (*remotev1.Result, error)

func StartTask 

func StartTask(req *remotev1.StartTaskRequest) (*wasiv1.StartTaskResponse, error)

Types

type BinaryNamer 

type BinaryNamer interface {
	BinaryName() string
}

type Category 

type Category = commonv1.Category

type Encoder 

type Encoder[T any] interface {
	Get(ctx context.Context, key string) (val T, ok bool, meta StateMetadata, err error)
	Set(ctx context.Context, key string, val T) error
}

type Example 

type Example struct {
	Spec        TaskSpec[Module]
	Name        string
	Description string
}

type ExecutionContext 

type ExecutionContext interface {
	context.Context
	WorkingDir() string
	OutDir() string
	BinariesDir() string
	StdOut() io.Writer
	StdErr() io.Writer
	Logger() *slog.Logger
	GetState(ctx context.Context, key string) ([]byte, StateMetadata, error)
	SetState(ctx context.Context, key string, value []byte) error
}

type Executor 

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

func NewExecutor 

func NewExecutor(repoRoot, outDir, binDir string) Executor

func (Executor) Run 

func (e Executor) Run(ctx context.Context, m Module) error

type Factory 

type Factory interface {
	Create() Module
}

type FuncExportWrapper 

type FuncExportWrapper[TRequest bapi.ProtoMessage, TResponse bapi.ProtoMessage] func(req TRequest) (TResponse, error)

func (FuncExportWrapper[TRequest, TResponse]) Call 

func (w FuncExportWrapper[TRequest, TResponse]) Call(reqPtr, reqSize uint32) uint64

type Help 

type Help struct {
	Name        string
	Description string
	Examples    []Example
}

type Helper 

type Helper interface {
	Help() Help
}

type JSONStateEncoder 

type JSONStateEncoder[T any] struct {
	Context ExecutionContext
}

func NewJSONStateEncoder 

func NewJSONStateEncoder[T any](ctx ExecutionContext) *JSONStateEncoder[T]

func (JSONStateEncoder[T]) Get 

func (j JSONStateEncoder[T]) Get(ctx context.Context, key string) (val T, ok bool, meta StateMetadata, err error)

func (JSONStateEncoder[T]) Set 

func (j JSONStateEncoder[T]) Set(ctx context.Context, key string, val T) error

type Module 

type Module interface {
	Execute(ctx ExecutionContext) error
	Category() Category
	Type() string
}

type ModuleFactoryFunc 

type ModuleFactoryFunc func() Module

func (ModuleFactoryFunc) Create 

func (f ModuleFactoryFunc) Create() Module

type Reference 

type Reference struct {
	Category Category
	Type     string
}

type Registration 

type Registration interface {
	RegisterAt(registry *TypeRegistry)
}

type RegistrationFunc 

type RegistrationFunc func(registry *TypeRegistry)

func (RegistrationFunc) RegisterAt 

func (f RegistrationFunc) RegisterAt(registry *TypeRegistry)

type StateMetadata 

type StateMetadata struct {
	ModifiedAt time.Time
	TTL        *time.Time
}

type StateProxy 

type StateProxy struct{}

func (StateProxy) Get 

func (s StateProxy) Get(key []byte) (state []byte, meta StateMetadata, err error)

func (StateProxy) Set 

func (s StateProxy) Set(key, state []byte) error

type TaskSpec 

type TaskSpec[T Module] struct {
	Module     T
	ModuleName string
	Container  *commonv1.ContainerSpec
	OutputDir  string
}

type ToolModule 

type ToolModule interface {
	Module
	BinaryNamer
}

type TypeRegistry 

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

func NewTypeRegistry 

func NewTypeRegistry() *TypeRegistry

func (*TypeRegistry) Add 

func (r *TypeRegistry) Add(cat Category, moduleName string, factory Factory)

func (*TypeRegistry) Get 

func (r *TypeRegistry) Get(cat Category, moduleName string) Module

func (*TypeRegistry) List 

func (r *TypeRegistry) List() (refs []Reference)

type WASIHandler 

type WASIHandler struct {
	Level slog.Level
	// contains filtered or unexported fields
}

func NewWASIHandler 

func NewWASIHandler() WASIHandler

func (WASIHandler) Enabled 

func (h WASIHandler) Enabled(_ context.Context, level slog.Level) bool

func (WASIHandler) Handle 

func (h WASIHandler) Handle(_ context.Context, record slog.Record) error

func (WASIHandler) WithAttrs 

func (h WASIHandler) WithAttrs(attrs []slog.Attr) slog.Handler

func (WASIHandler) WithGroup 

func (h WASIHandler) WithGroup(name string) slog.Handler

Source Files

View all Source files

Directories

Path Synopsis
integration module

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.