document how proxy_{get,set}_property expects paths to be serialized

[mpwarres]

Document the de-facto serialization format used by the various proxy-wasm SDKs (C++, Rust, Go) to serialize path_data arguments for the proxy_get_property and proxy_set_property hostcalls.

[PiotrSikora]

cc @kyessenov

[PiotrSikora]

That's not entirely correct. There is no NULL character at the end.

[mpwarres]

Hmm, while you're right about the Rust and Go SDKs not including a NULL char at the end, the C++ SDK does: code.

I can fix the C++ SDK to trim the last NULL char, but I think that host implementations would still need to tolerate a terminating NULL char in order to work with C++ plugins compiled prior to this fix. The Envoy implementation of getProperty does appear to tolerate this.

ISTM that in order to document the acceptable range of behaviors, the spec should say that path_data can (but is not required to) contain a terminating NULLchar. WDYT?

[mpwarres]

Updated to state that null char is a separator, but host implementations should also tolerate it as a terminator if present.

[kyessenov]

The segments could be empty, so the distinction is important actually. Although I don't recall if we ever tested it with empty segments, so it's under-specified.

[mpwarres]

My reading of this logic in Envoy::Extensions::Common::Wasm::getProperty() is that:

1. It handles each segment by finding the next null char (if any), and taking the substring up until that (which could be empty)
2. It bumps start to the previous end (which doesn't include null char) + 1 (skipping over the null char, if present)
3. Loop terminates when start >= path.size(). In the case of a path that does include a terminating null char, start will end up == path.size(), while in the case of a path that doesn't, start will end up equal to path.size() + 1. Either way, the loop terminates.

So I think it's still accurate to say that null char is a separator (which doesn't rule out empty segments), and that an optional terminating null char should be tolerated by host implementations.

If there's a different wording that either of you would prefer, I'm open to suggestions. Thanks!