Refactor towards End-use doc. (tetratelabs#190)

Signed-off-by: Takeshi Yoneda <[email protected]>

Author: mathetake

README.md

@@ -3,58 +3,19 @@ __This project is in its early stage, and the API is likely to change and not st
 # WebAssembly for Proxies (Go SDK) [![Build](https://github.com/tetratelabs/proxy-wasm-go-sdk/workflows/test/badge.svg)](https://github.com/tetratelabs/proxy-wasm-go-sdk/actions) [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 
 The Go SDK for
- [Proxy-Wasm](https://github.com/proxy-wasm/spec), enabling developers to write Proxy-Wasm extensions in Go.
-
+ [Proxy-Wasm](https://github.com/proxy-wasm/spec), enabling developers to write Proxy-Wasm plugins in Go. 
 This SDK is powered by [TinyGo](https://tinygo.org/) and does not support the official Go compiler.
 
-```golang
-import (
-	"github.com/tetratelabs/proxy-wasm-go-sdk/proxywasm"
-	"github.com/tetratelabs/proxy-wasm-go-sdk/proxywasm/types"
-)
-
-type vmContext struct{}
-
-// Implement types.VMContext.
-func (*vmContext) NewPluginContext(contextID uint32) types.PluginContext {
-	return &pluginContext{}
-}
-
-type pluginContext struct {
-	counter proxywasm.MetricCounter
-}
-
-// Implement types.PluginContext.
-func (*pluginContext) NewHttpContext(contextID uint32) types.HttpContext {
-	return &httpContext{counter: proxywasm.DefineCounterMetric("proxy_wasm_go.request_counter")}
-}
-
-type httpContext struct {
-	counter proxywasm.MetricCounter
-}
-
-// Implement types.HttpContext.
-func (ctx *httpContext) OnHttpRequestHeaders(int, bool) types.Action {
-	// Increment the request counter when we receive request headers.
-	ctx.counter.Increment(1)
-	return types.ActionContinue
-}
-```
-
-## Requirements
-
-This SDK depends on TinyGo and leverages its [WASI](https://github.com/WebAssembly/WASI) (WebAssembly System Interface) target.
+## Getting Started
 
-Please follow the official instruction [here](https://tinygo.org/getting-started/) for installing TinyGo.
+- [examples](examples) directory contains the example codes on top of this SDK.
 
-### Compatible ABI / Envoy builds (tested on CI)
+## Requirements
 
-| proxy-wasm-go-sdk| proxy-wasm ABI version |istio/proxyv2| Envoy upstream|
-|:-------------:|:-------------:|:-------------:|:-------------:|
-| main | 0.2.0| 1.9, 1.10 | 1.18 |
-| v0.3.0 | 0.2.0| 1.9, 1.10 | 1.18 |
+- [TinyGo](https://tinygo.org/) - 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.
+- [Envoy](https://www.envoyproxy.io) - To run compiled examples, you need to have Envoy binary. Please follow [the official instruction](https://www.envoyproxy.io/docs/envoy/latest/start/install).
 
-## Development
+## Build and run Examples
 
 ```bash
 # Build all examples.
@@ -64,48 +25,28 @@ make build.examples
 make build.example name=helloworld
 
 # Run a specific example.
-# This requires you to have Envoy binary locally.
 make run name=helloworld
+```
 
-# Run local tests without running envoy processes.
-make test
+## Compatible Envoy builds (tested on CI)
 
-# Run all e2e tests.
-# This requires you to have Envoy binary locally.
-make test.e2e
+Envoy is the first host side implementation of Proxy-Wasm ABI, 
+and we run end-to-end tests with multiple Envoy versions in order to verify Proxy-Wasm Go SDK works as expected.
 
-# Run e2e tests for a specific example.
-# This requires you to have Envoy binary locally.
-make test.e2e.single name=helloworld
-```
+| proxy-wasm-go-sdk| istio/proxyv2| Envoy upstream|
+|:-------------:|:-------------:|:-------------:|
+| main | 1.9, 1.10 | 1.18 |
+| v0.3.0 | 1.9, 1.10 | 1.18 |
+
+## Contributing
+
+We welcome contributions from the community! See [CONTRIBUTING.md](doc/CONTRIBUTING.md) for how to contribute to this repository.
 
-## Limitations and Considerations
-
-- Some of existing libraries are not available (importable but runtime panic / non-importable)
-    - There are several reasons for this:
-        1. TinyGo's WASI target does not support some of syscall: For example, we cannot import `crypto/rand` package.
-        2. TinyGo does not implement all of reflect package([examples](https://github.com/tinygo-org/tinygo/blob/v0.14.1/src/reflect/value.go#L299-L305)).
-        3. [proxy-wasm-cpp-host](https://github.com/proxy-wasm/proxy-wasm-cpp-host) has not supported some of WASI APIs yet 
-    - These issues will be mitigated as TinyGo and proxy-wasm-cpp-host evolve.
-- There's performance overhead of using Go/TinyGo due to GC
-    - `runtime.GC` is called whenever the heap runs out (see [1](https://tinygo.org/lang-support/#garbage-collection),
-    [2](https://github.com/tinygo-org/tinygo/blob/v0.14.1/src/runtime/gc_conservative.go#L218-L239)).
-    - TinyGo allows us to disable GC, but we cannot do that since we need to use maps (implicitly causes allocation)
-     for saving the plugin's [state](https://github.com/tetratelabs/proxy-wasm-go-sdk/blob/cf6ad74ed58b284d3d8ceeb8c5dba2280d5b1007/proxywasm/vmstate.go#L41-L46).
-    - Theoretically, we can implement our own GC algorithms tailored for proxy-wasm through `alloc(uintptr)` [interface](https://github.com/tinygo-org/tinygo/blob/v0.14.1/src/runtime/gc_none.go#L13) 
-    with `-gc=none` option. This is the future TODO.
-- `recover` is [not implemented](https://github.com/tinygo-org/tinygo/issues/891) in TinyGo, and there's no way to prevent the Wasm virtual machine from aborting.
-- Goroutine support
-    - In TinyGo, Goroutine is implmeneted through LLVM's coroutine (see [this blog post](https://aykevl.nl/2019/02/tinygo-goroutines)).
-    - In Envoy, Wasm modules are run in the event driven manner, and therefore the "scheduler" is not executed once the main function exits.
-        That means you cannot have the expected behavior of Goroutine as in ordinary host environments.
-        - The question "How to deal with Goroutine in a thread local Wasm VM executed in the event drive manner" has yet to be answered.
-    - We strongly recommend that you implement the `OnTick` function for any asynchronous task instead of using Goroutine.
-    - The scheduler can be disabled with `-scheduler=none` option of TinyGo.
-
-## References
+## External links
 
 - [WebAssembly for Proxies (ABI specification)](https://github.com/proxy-wasm/spec)
+- [WebAssembly for Proxies (AssemblyScript SDK)](https://github.com/solo-io/proxy-runtime)
 - [WebAssembly for Proxies (C++ SDK)](https://github.com/proxy-wasm/proxy-wasm-cpp-sdk)
 - [WebAssembly for Proxies (Rust SDK)](https://github.com/proxy-wasm/proxy-wasm-rust-sdk)
+- [WebAssembly for Proxies (Zig SDK)](https://github.com/mathetake/proxy-wasm-zig-sdk)
 - [TinyGo - Go compiler for small places](https://tinygo.org/)

doc/CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# Contributing
+
+We welcome contributions from the community. Please read the following guidelines carefully to maximize the chances of your PR being merged.
+
+## Coding Style
+
+The code is linted using a stringent golang-ci. To run this linter (and a few others) use run `make check`. To format your files, you can run `make format`.
+
+## Running tests
+
+```
+# Run local tests without running envoy processes.
+make test
+
+# Run all e2e tests.
+# This requires you to have Envoy binary locally.
+make test.e2e
+
+# Run e2e tests for a specific example.
+# This requires you to have Envoy binary locally.
+make test.e2e.single name=helloworld
+```
+
+## Code Reviews
+
+* Indicate the priority of each comment, following this
+[feedback ladder](https://www.netlify.com/blog/2020/03/05/feedback-ladders-how-we-encode-code-reviews-at-netlify/).
+If none was indicated it will be treated as `[dust]`.
+* A single approval is sufficient to merge, except when the change cuts
+across several components; then it should be approved by at least one owner
+of each component. If a reviewer asks for changes in a PR they should be
+addressed before the PR is merged, even if another reviewer has already
+approved the PR.
+* During the review, address the comments and commit the changes _without_ squashing the commits.
+This facilitates incremental reviews since the reviewer does not go through all the code again to
+find out what has changed since the last review.

e2e/e2e_test.go

@@ -220,7 +220,7 @@ func Test_network(t *testing.T) {
 func Test_shared_data(t *testing.T) {
 	stdErr, kill := startEnvoy(t, 8001)
 	defer kill()
-	var count int
+	var count int = 10000000
 	require.Eventually(t, func() bool {
 		res, err := http.Get("http://localhost:18000")
 		if err != nil {
@@ -231,7 +231,7 @@ func Test_shared_data(t *testing.T) {
 			return false
 		}
 		count++
-		return count == 10
+		return count == 10000010
 	}, 5*time.Second, time.Millisecond, "Endpoint not healthy.")
 	require.Eventually(t, func() bool {
 		return checkMessage(stdErr.String(), []string{fmt.Sprintf("shared value: %d", count)}, nil)

examples/dispatch_call_on_tick/main_test.go

@@ -1,3 +1,10 @@
+// These tests are supposed to run with `proxytest` build tag, and this way we can leverage the testing framework in "proxytest" package.
+// The framework emulates the expected behavior of Envoyproxy, and you can test your extensions without running Envoy and with
+// the standard Go CLI. To run tests, simply run
+// go test -tags=proxytest ./...
+
+//+build proxytest
+
 package main
 
 import (

examples/foreign_call_on_tick/main_test.go

@@ -1,3 +1,10 @@
+// These tests are supposed to run with `proxytest` build tag, and this way we can leverage the testing framework in "proxytest" package.
+// The framework emulates the expected behavior of Envoyproxy, and you can test your extensions without running Envoy and with
+// the standard Go CLI. To run tests, simply run
+// go test -tags=proxytest ./...
+
+//+build proxytest
+
 package main
 
 import (

examples/helloworld/main_test.go

@@ -1,3 +1,10 @@
+// These tests are supposed to run with `proxytest` build tag, and this way we can leverage the testing framework in "proxytest" package.
+// The framework emulates the expected behavior of Envoyproxy, and you can test your extensions without running Envoy and with
+// the standard Go CLI. To run tests, simply run
+// go test -tags=proxytest ./...
+
+//+build proxytest
+
 package main
 
 import (

examples/http_auth_random/main_test.go

@@ -1,3 +1,10 @@
+// These tests are supposed to run with `proxytest` build tag, and this way we can leverage the testing framework in "proxytest" package.
+// The framework emulates the expected behavior of Envoyproxy, and you can test your extensions without running Envoy and with
+// the standard Go CLI. To run tests, simply run
+// go test -tags=proxytest ./...
+
+//+build proxytest
+
 package main
 
 import (

examples/http_body/main_test.go

@@ -1,3 +1,10 @@
+// These tests are supposed to run with `proxytest` build tag, and this way we can leverage the testing framework in "proxytest" package.
+// The framework emulates the expected behavior of Envoyproxy, and you can test your extensions without running Envoy and with
+// the standard Go CLI. To run tests, simply run
+// go test -tags=proxytest ./...
+
+//+build proxytest
+
 package main
 
 import (

examples/http_headers/main_test.go

@@ -1,3 +1,10 @@
+// These tests are supposed to run with `proxytest` build tag, and this way we can leverage the testing framework in "proxytest" package.
+// The framework emulates the expected behavior of Envoyproxy, and you can test your extensions without running Envoy and with
+// the standard Go CLI. To run tests, simply run
+// go test -tags=proxytest ./...
+
+//+build proxytest
+
 package main
 
 import (

examples/http_routing/main_test.go

@@ -1,3 +1,10 @@
+// These tests are supposed to run with `proxytest` build tag, and this way we can leverage the testing framework in "proxytest" package.
+// The framework emulates the expected behavior of Envoyproxy, and you can test your extensions without running Envoy and with
+// the standard Go CLI. To run tests, simply run
+// go test -tags=proxytest ./...
+
+//+build proxytest
+
 package main
 
 import (