|
1 | | -> [!WARNING] |
2 | | -> We are no longer recommending this SDK or Wasm in general for anyone due to the fundamental memory issue of TinyGo (See [the detailed explanation](https://github.com/tetratelabs/proxy-wasm-go-sdk/issues/450#issuecomment-2253729297) by a long-time community member) |
3 | | -> as well as [the project state of Proxy-Wasm in general](https://github.com/envoyproxy/envoy/issues/35420). |
4 | | -> If you are not in a position where you have to run untrusted binaries (like for example, you run Envoy proxies while your client gives you the binaries to run), we recommend using other extension mechanism |
5 | | -> such as Lua or External Processing which should be comparable or better or worse depending on the use case. |
6 | | -> |
7 | | -> If you are already using this SDK, but still want to continue using Wasm for some reason instead of Lua or External Processing, |
8 | | -> we strongly recommend migrating to the Rust or C++ SDK due to the memory issue of TinyGo described in the link above. |
9 | | -> |
10 | | -> We keep this repository open and not archived for the existing users, but we cannot provide any support or guarantee for the future development of this SDK. |
11 | | -> However, at any time, we may decide to archive this repository if we see no reason to keep it open. |
| 1 | +# WebAssembly for Proxies (Go SDK) [](https://github.com/proxy-wasm/proxy-wasm-go-sdk/actions) [](LICENSE) |
| 2 | + |
| 3 | +The Go SDK for |
| 4 | + [Proxy-Wasm](https://github.com/proxy-wasm/spec), enabling developers to write Proxy-Wasm plugins in Go. |
| 5 | + |
| 6 | +Note: This SDK targets the upstream Go compiler, version 1.24 or later. This is different than the forked github.com/tetratelabs/proxy-wasm-go-sdk, which targets the TinyGo compiler. |
| 7 | + |
| 8 | +## Project Status |
| 9 | + |
| 10 | +This SDK is based off of github.com/tetratelabs/proxy-wasm-go-sdk; however, it is effectively a new SDK targeting a completely different toolchain. It relies on the not-yet-released Go 1.24 and hasn't seen extensive prod testing by end-users. This SDK is an alpha product. |
| 11 | + |
| 12 | +## Getting Started |
| 13 | + |
| 14 | +- [examples](examples) directory contains the example codes on top of this SDK. |
| 15 | +- [OVERVIEW.md](doc/OVERVIEW.md) the overview of Proxy-Wasm, the API of this SDK, and the things you should know when writing plugins. |
| 16 | + |
| 17 | +## Requirements |
| 18 | + |
| 19 | +- \[Required] [Go](https://go.dev/): v1.24+ - This SDK leverages Go 1.24's support for [WASI](https://github.com/WebAssembly/WASI) (WebAssembly System Interface) reactors. You can grab a release candidate from the [Go unstable releases page](https://go.dev/dl/#unstable). A stable release of Go 1.24 is [expected in February 2025](https://tip.golang.org/doc/go1.24). |
| 20 | +- \[Required] A host environment supporting this toolchain - This SDK leverages additional host imports added to the proxy-wasm-cpp-host in [PR#427](https://github.com/proxy-wasm/proxy-wasm-cpp-host/pull/427). This has yet to be merged, let alone make its way downstream to Envoy, ATS, nginx, or managed environments. |
| 21 | +- \[Optional] [Envoy](https://www.envoyproxy.io) - To run end-to-end tests, you need to have an Envoy binary. You can use [func-e](https://func-e.io) as an easy way to get started with Envoy or follow [the official instruction](https://www.envoyproxy.io/docs/envoy/latest/start/install). |
| 22 | + |
| 23 | +## Installation |
| 24 | + |
| 25 | +``` |
| 26 | +go get github.com/proxy-wasm/proxy-wasm-go-sdk |
| 27 | +``` |
| 28 | + |
| 29 | +## Minimal Example Plugin |
| 30 | + |
| 31 | +A minimal plugin: |
| 32 | + |
| 33 | +```go |
| 34 | +package main |
| 35 | + |
| 36 | +import ( |
| 37 | + "github.com/proxy-wasm/proxy-wasm-go-sdk/proxywasm" |
| 38 | + "github.com/proxy-wasm/proxy-wasm-go-sdk/proxywasm/types" |
| 39 | +) |
| 40 | + |
| 41 | +func init() { |
| 42 | + proxywasm.SetVMContext(&vmContext{}) |
| 43 | +} |
| 44 | +type vmContext struct { |
| 45 | + types.DefaultVMContext |
| 46 | +} |
| 47 | +type pluginContext struct { |
| 48 | + types.DefaultPluginContext |
| 49 | +} |
| 50 | +func (*context) NewPluginContext(contextID uint32) types.PluginContext { |
| 51 | + return &context{} |
| 52 | +} |
| 53 | +func main() {} |
| 54 | +``` |
| 55 | + |
| 56 | +It can be compiled with `env GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared -o my-plugin.wasm main.go`. |
| 57 | + |
| 58 | +## Build and run Examples |
| 59 | + |
| 60 | +```bash |
| 61 | +# Build all examples. |
| 62 | +make build.examples |
| 63 | + |
| 64 | +# Build a specific example using the `go` tool. |
| 65 | +cd examples/helloworld |
| 66 | +env GOOS=wasp1 GOARCH=wasm go build -buildmode=c-shared -o main.wasm main.go |
| 67 | + |
| 68 | +# Test the built wasm module using `go test`. |
| 69 | +go test |
| 70 | + |
| 71 | +# Build and test a specific example from the repo root using `make`. |
| 72 | +make build.example name=helloworld |
| 73 | +make run name=helloworld |
| 74 | +``` |
| 75 | + |
| 76 | +## Compatible Envoy builds |
| 77 | + |
| 78 | +Envoy is the first host side implementation of Proxy-Wasm ABI, |
| 79 | +and we run end-to-end tests with multiple versions of Envoy and Envoy-based [istio/proxy](https://github.com/istio/proxy) in order to verify Proxy-Wasm Go SDK works as expected. |
| 80 | + |
| 81 | +Please refer to [workflow.yaml](.github/workflows/workflow.yaml) for which version is used for End-to-End tests. |
| 82 | + |
| 83 | +## Build tags |
| 84 | + |
| 85 | +The following build tags can be used to customize the behavior of the built plugin. Build tags [can be specified in the `go build` command via the `-tags` flag](https://pkg.go.dev/cmd/go#:~:text=tags): |
| 86 | + |
| 87 | +- `proxywasm_timing`: Enables logging of time spent in invocation of the plugin's exported functions. This can be useful for debugging performance issues. |
| 88 | + |
| 89 | +## Contributing |
| 90 | + |
| 91 | +We welcome contributions from the community! See [CONTRIBUTING.md](doc/CONTRIBUTING.md) for how to contribute to this repository. |
| 92 | + |
| 93 | +## External links |
| 94 | + |
| 95 | +- [WebAssembly for Proxies (ABI specification)](https://github.com/proxy-wasm/spec) |
| 96 | +- [WebAssembly for Proxies (C++ SDK)](https://github.com/proxy-wasm/proxy-wasm-cpp-sdk) |
| 97 | +- [WebAssembly for Proxies (Rust SDK)](https://github.com/proxy-wasm/proxy-wasm-rust-sdk) |
| 98 | +- [WebAssembly for Proxies (AssemblyScript SDK)](https://github.com/solo-io/proxy-runtime) |
0 commit comments