Suggestion: Clarify that, in practice, user-configurable values for gRPC endpoint URLs do not support a path component, and why

[ghannington-Rocket]

Problem

Googling for:

grpc url path

reveals some confusion about whether gRPC supports endpoint URLs with a path component.

One has to delve to find the answer, in "gRPC over HTTP2":

Path → ":path" "/" Service-Name "/" {method name} ; But see note below. ... Some gRPC implementations may allow the Path format shown above to be overridden, but this functionality is strongly discouraged. gRPC does not go out of its way to break users that are using this kind of override, but we do not actively support it, and some functionality (e.g., service config support) will not work when the path is not of the form shown above.

Suggestion

Somewhere in an introductory, language-implementation-independent topic in the gRPC documentation, highlight the fact that, in practice, user-configurable values for gRPC endpoint URLs do not support a path component, and why.

And/or elaborate on and/or reword that note about the path in "gRPC over HTTP2", for clarity. While I understand that the existing wording deliberately allows for the possibility of implementations that "allow the Path format shown above to be overridden", I think a concise statement to the effect that, in practice, user-configurable values for endpoint URLs are limited to, say, host:port, would help to avoid confusion.

Reference

• opentelemetry-collector GitHub issue #5319, "[Otlpexporter] Support path in endpoint".

[ghannington-Rocket]

I acknowledge that, to the designers and developers of gRPC—who might also be the writers of the gRPC docs that I've cited, or might have provided draft content to the writers—this point will be obvious: the path format is intrinsic to the design of gRPC over HTTP/2; so, of course specifying a non-root path is going to be problematic, and hence, strongly discouraged; not supported by implementations in practice.

However, new users of gRPC might bring expectations based on experience with API endpoint URLs that involve, or allow, path components. Hence, to those users, this point might not be so obvious; worth clarifying.