|
| 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 like 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 | +
|
1 | 12 | # WebAssembly for Proxies (Go SDK) [](https://github.com/tetratelabs/proxy-wasm-go-sdk/actions) [](LICENSE) |
2 | 13 |
|
3 | 14 | The Go SDK for |
4 | 15 | [Proxy-Wasm](https://github.com/proxy-wasm/spec), enabling developers to write Proxy-Wasm plugins in Go. |
5 | 16 | This SDK is powered by [TinyGo](https://tinygo.org/) and does not support the official Go compiler. |
6 | | - |
7 | | -## Getting Started |
8 | | - |
9 | | -- [examples](examples) directory contains the example codes on top of this SDK. |
10 | | -- [OVERVIEW.md](doc/OVERVIEW.md) the overview of Proxy-Wasm, the API of this SDK, and the things you should know when writing plugins. |
11 | | - |
12 | | -## Requirements |
13 | | - |
14 | | -- [TinyGo](https://tinygo.org/): v0.32+ - This SDK depends on TinyGo and leverages its [WASI](https://github.com/WebAssembly/WASI) (WebAssembly System Interface) target. Please follow the official instruction [here](https://tinygo.org/getting-started/) for installing TinyGo. |
15 | | -- [Envoy](https://www.envoyproxy.io) - To run compiled examples, you need to have Envoy binary. We recommend using [func-e](https://func-e.io) as the easiest way to get started with Envoy. Alternatively, you can follow [the official instruction](https://www.envoyproxy.io/docs/envoy/latest/start/install). |
16 | | - |
17 | | - |
18 | | -## Installation |
19 | | - |
20 | | -``` |
21 | | -go get github.com/tetratelabs/proxy-wasm-go-sdk |
22 | | -``` |
23 | | - |
24 | | -## Build and run Examples |
25 | | - |
26 | | -```bash |
27 | | -# Build all examples. |
28 | | -make build.examples |
29 | | - |
30 | | -# Build a specific example. |
31 | | -make build.example name=helloworld |
32 | | - |
33 | | -# Run a specific example. |
34 | | -make run name=helloworld |
35 | | -``` |
36 | | - |
37 | | -## Compatible Envoy builds |
38 | | - |
39 | | -Envoy is the first host side implementation of Proxy-Wasm ABI, |
40 | | -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. |
41 | | - |
42 | | -Please refer to [workflow.yaml](.github/workflows/workflow.yaml) for which version is used for End-to-End tests. |
43 | | - |
44 | | -## Build tags |
45 | | - |
46 | | -The following build tags can be used to customize the behavior of the built plugin: |
47 | | - |
48 | | -- `proxywasm_timing`: Enables logging of time spent in invocation of the plugin's exported functions. This can be useful for debugging performance issues. |
49 | | - |
50 | | -## Contributing |
51 | | - |
52 | | -We welcome contributions from the community! See [CONTRIBUTING.md](doc/CONTRIBUTING.md) for how to contribute to this repository. |
53 | | - |
54 | | -## External links |
55 | | - |
56 | | -- [WebAssembly for Proxies (ABI specification)](https://github.com/proxy-wasm/spec) |
57 | | -- [WebAssembly for Proxies (AssemblyScript SDK)](https://github.com/solo-io/proxy-runtime) |
58 | | -- [WebAssembly for Proxies (C++ SDK)](https://github.com/proxy-wasm/proxy-wasm-cpp-sdk) |
59 | | -- [WebAssembly for Proxies (Rust SDK)](https://github.com/proxy-wasm/proxy-wasm-rust-sdk) |
60 | | -- [TinyGo - Go compiler for small places](https://tinygo.org/) |
0 commit comments