From 69b416a08c266f65e75fa5be70cd95788fbd968d Mon Sep 17 00:00:00 2001 From: "Mark D. Roth" Date: Tue, 28 Aug 2018 08:53:31 -0700 Subject: Update naming documentation. --- doc/naming.md | 64 ++++++++++++++++----------- src/core/ext/filters/client_channel/README.md | 18 +------- 2 files changed, 40 insertions(+), 42 deletions(-) diff --git a/doc/naming.md b/doc/naming.md index 676aa9f298..581c550567 100644 --- a/doc/naming.md +++ b/doc/naming.md @@ -14,34 +14,48 @@ be plugged in. ### Name Syntax A fully qualified, self contained name used for gRPC channel construction -uses the syntax: - -``` -scheme://authority/endpoint_name -``` - -Here, `scheme` indicates the name-system to be used. Currently, we -support the following schemes: - -- `dns` - -- `ipv4` (IPv4 address) - -- `ipv6` (IPv6 address) - -- `unix` (path to unix domain socket -- unix systems only) +uses URI syntax as defined in [RFC 3986](https://tools.ietf.org/html/rfc3986). + +The URI scheme indicates what resolver plugin to use. If no scheme +prefix is specified or the scheme is unknown, the `dns` scheme is used +by default. + +The URI path indicates the name to be resolved. + +Most gRPC implementations support the following URI schemes: + +- `dns:[//authority/]host[:port]` -- DNS (default) + - `host` is the host to resolve via DNS. + - `port` is the port to return for each address. If not specified, + 443 is used (but some implementations default to 80 for insecure + channels). + - `authority` indicates the DNS server to use, although this is only + supported by some implementations. (In C-core, the default DNS + resolver does not support this, but the c-ares based resolver + supports specifying this in the form "IP:port".) + +- `unix:path` or `unix://absolute_path` -- Unix domain sockets (Unix systems only) + - `path` indicates the location of the desired socket. + - In the first form, the path may be relative or absolute; in the + second form, the path must be absolute (i.e., there will actually be + three slashes, two prior to the path and another to begin the + absolute path). + +The following schemes are supported by the gRPC C-core implementation, +but may not be supported in other languages: + +- `ipv4:address[:port][,address[:port],...]` -- IPv4 addresses + - Can specify multiple comma-delimited addresses of the form `address[:port]`: + - `address` is the IPv4 address to use. + - `port` is the port to use. If not specified, 443 is used. + +- `ipv6:address[:port][,address[:port],...]` -- IPv6 addresses + - Can specify multiple comma-delimited addresses of the form `address[:port]`: + - `address` is the IPv6 address to use. + - `port` is the port to use. If not specified, 443 is used. In the future, additional schemes such as `etcd` could be added. -The `authority` indicates some scheme-specific bootstrap information, e.g., -for DNS, the authority may include the IP[:port] of the DNS server to -use. Often, a DNS name may be used as the authority, since the ability to -resolve DNS names is already built into all gRPC client libraries. - -Finally, the `endpoint_name` indicates a concrete name to be looked up -in a given name-system identified by the scheme and the authority. The -syntax of the endpoint name is dictated by the scheme in use. - ### Resolver Plugins The gRPC client library will use the specified scheme to pick the right diff --git a/src/core/ext/filters/client_channel/README.md b/src/core/ext/filters/client_channel/README.md index 7c209db12e..9676a4535b 100644 --- a/src/core/ext/filters/client_channel/README.md +++ b/src/core/ext/filters/client_channel/README.md @@ -46,20 +46,4 @@ construction arguments for concrete grpc_subchannel instances. Naming for GRPC =============== -Names in GRPC are represented by a URI (as defined in -[RFC 3986](https://tools.ietf.org/html/rfc3986)). - -The following schemes are currently supported: - -dns:///host:port - dns schemes are currently supported so long as authority is - empty (authority based dns resolution is expected in a future - release) - -unix:path - the unix scheme is used to create and connect to unix domain - sockets - the authority must be empty, and the path - represents the absolute or relative path to the desired - socket - -ipv4:host:port - a pre-resolved ipv4 dotted decimal address/port combination - -ipv6:[host]:port - a pre-resolved ipv6 address/port combination +See [/doc/naming.md](gRPC name resolution). -- cgit v1.2.3