add limitation docs

.github/CODEOWNERS

@@ -0,0 +1 @@
+*   @mathetake

README.md

@@ -16,7 +16,7 @@ To download compatible envoyproxy, run
 getenvoy fetch wasm:1.15
 ```
 
-The targe Envoy version is `release/v1.15`
+The target Envoy version is `release/v1.15`
  branch on [envoyproxy/envoy-wasm](https://github.com/envoyproxy/envoy-wasm/tree/release/v1.15).
 
 ## run examples
@@ -41,9 +41,31 @@ To run tests:
 go test -tags=proxytest -v -race ./...
 ```
 
-## limitations / considerations
+## language and compiler limitations/considerations
+
+- You can only use really limited set of existing libraries. 
+    - There are two reasons for this:
+        1. TinyGo [uses](https://github.com/tinygo-org/tinygo/blob/release/loader/loader.go#L79-L83) the official parser, lexer, etc., 
+    which forces your program to implicitly import `syscall/js` package if you import packages using system calls. 
+    The package expects the host environment to have the `syscall/js` specific ABI as in 
+    [wasm_exec.js](https://github.com/tinygo-org/tinygo/blob/154d4a781f6121bd6f584cca4a88909e0b091f63/targets/wasm_exec.js) 
+    which is not available outside of that javascript.
+        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)).
+    - The syscall problem maybe solvable by emulating `syscall/js` function
+    through WASI interface (which is implemented by V8 engine running on Envoy), but we haven't tried.
+- Note that there's performance overhead in using Go/TinyGo due to GC
+    - runtime.GC() is called whenever heap allocation happens (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/master/proxywasm/vmstate.go#L17-L22).
+    - 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 not way to prevent the WASM virtual machine from aborting.
+- Be careful about using Goroutine
+    - In Tinygo, Goroutine is implmeneted through LLVM's coroutine (see [this blog post](https://aykevl.nl/2019/02/tinygo-goroutines)).
+    - Make every goroutine exit as soon as possible, otherwise it will block the proxy's worker thread. That is too bad for processing realtime network requests.
+    - We strongly recommend that you implement the `OnTick` function for any asynchronous task instead of using Goroutine so we do not block requests.
 
-TODO
 
 ## references
 

examples/helloworld/main.go

@@ -36,6 +36,9 @@ func newHelloWorld(contextID uint32) proxywasm.RootContext {
 
 // override
 func (ctx *helloWorld) OnVMStart(int) bool {
+	go func() {
+		proxywasm.LogInfo("sleeped")
+	}()
 	proxywasm.LogInfo("proxy_on_vm_start from Go!")
 	if err := proxywasm.HostCallSetTickPeriodMilliSeconds(1000); err != nil {
 		proxywasm.LogCritical("failed to set tick period: ", err.Error())

proxywasm/abi_configuration_test.go

@@ -12,12 +12,12 @@ type configurationContext struct {
 	onVMStartCalled, onConfigureCalled bool
 }
 
-func (c *configurationContext) OnVMStart(vmConfigurationSize int) bool {
+func (c *configurationContext) OnVMStart(_ int) bool {
 	c.onVMStartCalled = true
 	return true
 }
 
-func (c *configurationContext) OnConfigure(pluginConfigurationSize int) bool {
+func (c *configurationContext) OnConfigure(_ int) bool {
 	c.onConfigureCalled = true
 	return true
 }

proxywasm/hostcall_utils_go.go

@@ -16,6 +16,7 @@
 
 // since the difference of the types in SliceHeader.{Len, Cap} between tinygo and go,
 // we have to have separated functions for converting bytes
+// https://github.com/tinygo-org/tinygo/issues/1284
 
 package proxywasm
 

proxywasm/hostcall_utils_tinygo.go

@@ -16,6 +16,7 @@
 
 // since the difference of the types in SliceHeader.{Len, Cap} between tinygo and go,
 // we have to have separated functions for converting bytes
+// https://github.com/tinygo-org/tinygo/issues/1284
 
 package proxywasm