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!

[PiotrSikora]

The current text works fine for me, thanks!

To be honest, I'm actually surprised that the trailing \0 works fine, since I recall having issues with it, hence the extra code to remove it in Rust & Go SDKs... But I was also under the impression that the serialization format came from CEL and wasn't our own invention, so my memory is clearly a little hazy around those details.

[kyessenov]

The binary format didn't come from CEL. The constraint was that "." wasn't good enough since segments can contain ".". But you should feel free to revise for vNext with a more standard list packing format.

[mpwarres]

The current text works fine for me, thanks!

Great!

To be honest, I'm actually surprised that the trailing \0 works fine, since I recall having issues with it, hence the extra code to remove it in Rust & Go SDKs... But I was also under the impression that the serialization format came from CEL and wasn't our own invention, so my memory is clearly a little hazy around those details.

Yeah, I'm not sure--maybe something changed over time? FWIW my reading of the current logic in Context::getProperty() is that (currently) the trailing '\0' would never even be seen by any of the CEL-evaluation functions.

I'll draft a PR for the C++ SDK to stop including it, for consistency with the other SDKs.

[mpwarres]

The binary format didn't come from CEL. The constraint was that "." wasn't good enough since segments can contain ".". But you should feel free to revise for vNext with a more standard list packing format.

Ah, TIL! I had wondered about that, interesting to know the history.

[PiotrSikora]

I think we should also add this to v0.2.0 and vNEXT (since any changes from v0.2.1 should be done via PRs and not by using a stale copy of the spec).

[mpwarres]

I think we should also add this to v0.2.0 and vNEXT (since any changes from v0.2.1 should be done via PRs and not by using a stale copy of the spec).

Right--done.

[mpwarres]

@PiotrSikora PTAL again--thanks!

[PiotrSikora]

LGTM, thanks!

Please capitalize the commit message summary & add trailing dot before merging.

[mpwarres]

Thanks! Done.