Documentation and comments for runtime

[esnible]

The runtime lacks an explanation of parameters, return enumerations, and state managment.

For example, I see onRequestBody(body_buffer_length: usize, end_of_stream: bool): FilterDataStatusValues and see that FilterDataStatusValues are

  Continue = 0,
  StopIterationAndBuffer = 1,
  StopIterationAndWatermark = 2,
  StopIterationNoBuffer = 3

There is no explanation of these values in https://github.com/proxy-wasm/spec/tree/master/abi-versions/vNEXT either (for example, see proxy-wasm/spec#7 )

I suspect these values are defined at https://github.com/envoyproxy/envoy/blob/master/include/envoy/http/filter.h and that my use of the runtime must abide by the rules of https://www.envoyproxy.io/docs/envoy/latest/faq/extensions/contract.html?highlight#is-there-a-contract-my-http-filter-must-adhere-to

It would help a lot if this repository copied or linked to the adjacent Envoy filter documentation, if applicable. I have never written a native Envoy filter and lacking the context around the conventions of filter writing impedes my use of AssemblyScript.

[yuval-k]

Yes, the semantics are indeed very similar to a native envoy filter (i.e. no co-routine magic).

I will look into improving the docs and adding more examples

[esnible]

Feel free to cc me if you want a review of doc changes. I feel like this repo will become important to the Istio project.

I considered doing a PR myself but I was unsure if it was reasonable to copy text from https://github.com/envoyproxy/envoy/blob/master/include/envoy/http/filter.h or if it was required that all documentation comments be original to Solo.

[esnible]

The C++ example at https://github.com/envoyproxy/envoy-wasm/blob/master/examples/wasm/envoy_filter_http_wasm_example.cc#L62 includes the following code to log the HTTP body:

  auto body = getBufferBytes(WasmBufferType::HttpRequestBody, 0, body_buffer_length);
  LOG_ERROR(std::string("onRequestBody ") + std::string(body->view()));

I tried to simulate this using the runtime:

    // The definition of WasmBufferType::HttpRequestBody is in
    // https://github.com/proxy-wasm/proxy-wasm-cpp-sdk/blob/master/proxy_wasm_common.h
    let WasmBufferType_HttpRequestBody = 0
    var body = get_buffer_bytes(WasmBufferType_HttpRequestBody, 0, <u32>body_buffer_length)
    log(LogLevelValues.warn, "context id: " + this.context_id.toString() + "   : past get_buffer_bytes invocation")

The get_buffer_bytes seems to work; the past get_buffer_bytes invocation is logged, but immediately after it now logs critical envoy wasm wasm log: at: ~lib/rt/pure.ts(122:14)

What would be a correct Proxy-Runtime equivalent of the Envoy example?

[esnible]

See envoyproxy/envoy-wasm#634 for a discussion of difficulties with runtime state and http invocation. I am not having struggles with this runtime, but with Envoy Wasm itself. Envoy is segfaulting a lot. Any guidance?

Many AssemblyScript developers are coming from the browser world where script errors don't crash the browser.

[yuval-k]

like you mention, not much we can do to fix envoy crashes from the this code...

[esnible]

@yuval-k Can you give an example of how to get the httpCall() response body as a string in the callback?

I am getting a response with body_size 91. I want the body in a string. I tried and failed with

          var swd = get_status();
          var body = String.UTF8.decode(swd.data)

and

          let WasmBufferType_HttpCallResponseBody = 4
          var abbody = get_buffer_bytes(WasmBufferType_HttpCallResponseBody, 0, <u32>body_size)
          var body = String.UTF8.decode(abbody)