From 2ef3c2850e15bce57310844ac27188e0899a7cdf Mon Sep 17 00:00:00 2001 From: Benjamin Cane Date: Mon, 1 Jan 2024 15:36:35 -0700 Subject: [PATCH] Updating README --- README.md | 87 +++++++++++++++++++++++++++++++++++++++++++++ callbacks/router.go | 5 ++- engine/module.go | 2 +- engine/wasm.go | 4 +-- 4 files changed, 92 insertions(+), 6 deletions(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..89fa6eb --- /dev/null +++ b/README.md @@ -0,0 +1,87 @@ +# wapc-toolkit + +[![PkgGoDev](https://pkg.go.dev/badge/github.com/tarmac-project/wapc-toolkit)](https://pkg.go.dev/github.com/tarmac-project/wapc-toolkit) +[![Build Status](https://github.com/tarmac-project/wapc-toolkit/actions/workflows/build.yml/badge.svg)](https://github.com/tarmac-project/wapc-toolkit/actions/workflows/build.yml) +[![Go Report Card](https://goreportcard.com/badge/github.com/tarmac-project/wapc-toolkit)](https://goreportcard.com/report/github.com/tarmac-project/wapc-toolkit) +[![codecov](https://codecov.io/gh/tarmac-project/wapc-toolkit/graph/badge.svg?token=mysp7aUTWp)](https://codecov.io/gh/tarmac-project/wapc-toolkit) + +The wapc-toolkit is a collection of packages for Go applications using WebAssembly Procedure Calls (waPC). + +The waPC protocol standardizes communications and error handling between both the Host and Guest. It defines how WebAssembly Hosts invoke functions within the Guest and how Hosts extend host-level functionality to the Guest modules. + +### What is in the toolkit? + +This toolkit aims to solve common problems for Go applications using waPC. The toolkit is still growing but already has some valuable tools. + +| Package | Description | Go Docs | +| --- | --- | --- | +| Callbacks | A waPC HostCall callback router, extending multiple callbacks to waPC guests. | [![PkgGoDev](https://pkg.go.dev/badge/github.com/tarmac-project/wapc-toolkit/callbacks)](https://pkg.go.dev/github.com/tarmac-project/wapc-toolkit/callbacks) | +| Engine | A simplified interface for hosts loading and executing waPC guest modules. | [![PkgGoDev](https://pkg.go.dev/badge/github.com/tarmac-project/wapc-toolkit/engine)](https://pkg.go.dev/github.com/tarmac-project/wapc-toolkit/engine) | + +#### waPC Go Implementations + +- Host: [wapc-go](https://github.com/wapc/wapc-go) +- Guest: [wapc-guest-tinygo](https://github.com/wapc/wapc-guest-tinygo) + +### Use Cases + +WebAssembly (WASM) is not just for the browser; with the creation of the WebAssembly System Interface (WASI), WebAssembly can be used as a language-agnostic way to enable many use cases. The waPC protocol and this toolkit make it approachable for everyone. + +What could we use this toolkit for? Here are some thoughts. + +- Stored Procedures: WASM provides a modern & testable approach to extending custom processing on databases, message brokers, or any other platform. +- Serverless runtimes: WASM solves much of the cold-start problem, and waPC enables runtimes to extend functionality to Guest modules. +- Dynamic Plugins: do you need to make your application more modular but also want to separate your core from your modules? WASM is an excellent answer to this problem. +- And many more. + +## Getting Started + +The toolkit is a collection of packages that you can import and use independently. + +The following shows an example of leveraging the engine to load and execute a waPC guest module. + +```go +package main + +import ( + "github.com/tarmac-project/wapc-toolkit/engine" +) + +func main() { + // Create a new engine server. + server, err := engine.New(ServerConfig{...}) + if err != nil { + // do something + } + + // Load the guest module. + err = server.LoadModule(engine.ModuleConfig{ + Name: "my-guest-module", + Filepath: "./my-guest-module.wasm", + }) + if err != nil { + // do something + } + + // Lookup the guest module. + m, err := server.Lookup("my-guest-module") + if err != nil { + // do something + } + + // Call the Hello function within the guest module. + rsp, err := m.Run("Hello", []byte("world")) + if err != nil { + // do something + } +} +``` + +## Contributing + +If you would like to contribute, please fork the repo and send in a pull request. All contributions are welcome and +appreciated. + +## License + +The Apache 2 License. Please see [LICENSE](LICENSE) for more information. diff --git a/callbacks/router.go b/callbacks/router.go index ffced9b..46f689b 100644 --- a/callbacks/router.go +++ b/callbacks/router.go @@ -1,13 +1,12 @@ /* -Package callbacks provides a callback router as part of the wapc-toolkit; users can use the callbacks -package with other packages in the toolkit or directly with the github.com/wapc/wapc-go package. +Package callbacks is part of the wapc-toolkit and provides a router for waPC HostCall callbacks. The wapc-toolkit is a collection of packages focused on providing tools for Go applications using the WebAssembly Procedure Calls (waPC) standard. The waPC standard is used by host and module applications to communicate. The Go implementation github.com/wapc/wapc-go offers multiple host runtimes supporting the WebAssembly System Interface (WASI) and an SDK for guest modules. -The Go waPC package allows modules to perform callbacks to hosts via a hostcall function. +The Go waPC package allows modules to perform callbacks to hosts via a HostCall function. When a host initiates the waPC engine, it can register a single function to handle these host calls. The callbacks package provides a router that can be registered with the waPC engine. It enables diff --git a/engine/module.go b/engine/module.go index 44c46a2..f9cd4b6 100644 --- a/engine/module.go +++ b/engine/module.go @@ -92,7 +92,7 @@ func (m *Module) Run(function string, payload []byte) ([]byte, error) { // Invoke the module with the user-provided function and payload r, err = i.Invoke(m.ctx, function, payload) if err != nil { - return r, fmt.Errorf("invocation of WASM module failed - %w", err) + return r, err } return r, nil diff --git a/engine/wasm.go b/engine/wasm.go index 1d328d2..32f98d9 100644 --- a/engine/wasm.go +++ b/engine/wasm.go @@ -2,9 +2,9 @@ Package engine is part of the wapc-toolkit and provides a simplified interface for loading and executing waPC guest modules. -The wapc-toolkit is a collection of packages focused on providing tools for Go applications using the Web Assembly +The wapc-toolkit is a collection of packages focused on providing tools for Go applications using the WebAssembly Procedure Calls (waPC) standard. The waPC standard is used by host and module applications to communicate. The -Go implementation github.com/wapc/wapc-go offers multiple host runtimes supporting the Web Assembly System +Go implementation github.com/wapc/wapc-go offers multiple host runtimes supporting the WebAssembly System Interface (WASI) and an SDK for guest modules. This package aims to provide a simplified WebAssembly Engine Server that implements the waPC protocol. Under