grpc.io
grpc.io copied to clipboard
grpc
Is metadata _really_ "opaque to gRPC"?
@ejona86 - #994 and #996 got me thinking: I question the truth of the statement that "Metadata is opaque to gRPC itself" since #996 highlights that there are restrictions on the values that keys can take on -- and hence the metadata isn't opaque.
Maybe we can just drop the mention of opaqueness from that section of the docs?
https://github.com/grpc/grpc.io/blob/2c8783c1737fdbd324a3e2d65fc0c69f91758ba9/content/en/docs/what-is-grpc/core-concepts.md?plain=1#L200
I wouldn't have chosen the word opaque myself, but I don't see it as all that wrong depending on what the word means to you. I'd say that metadata has no semantic meaning to grpc itself (although wording that can still be troublesome as there are grpc features like tracing that will use specific metadata keys...). So really I'd probably reorganize things to describe it from a different perspective and focus on "hey, application author, you can use this for your own stuff on top of grpc." Describe it by saying how you use it instead of forming a definition for it.
https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md points out there's quite a few restrictions, but these are mostly the same restrictions that are in HTTP (but more restrictive because we don't allow obsolete parts of HTTP like Latin-1-but-you-don't-actually-know-the-encoding in headers). You can see the two paragraphs starting with "Custom-Metadata header order is not guaranteed to be preserved...".
But those don't really make it non-opaque to me. It is still pretty opaque but we've defined certain specific and limited transforms that might be made to it such that the application must treat those as equivalent values, but that's true in HTTP as well. The main point is that gRPC is unable to decode the values into something meaningful in the general case; the meaning of each individual metadata key is defined elsewhere (commonly in your app, but maybe HTTP itself for caching, etc).
Ping on this @chalin. "[User-defined] Metadata is not used by gRPC"?
If @ejona86 is ok with that phrase (including the "User-defined" qualification", then it's ok with me.