From 69b416a08c266f65e75fa5be70cd95788fbd968d Mon Sep 17 00:00:00 2001
From: "Mark D. Roth" <roth@google.com>
Date: Tue, 28 Aug 2018 08:53:31 -0700
Subject: Update naming documentation.

---
 doc/naming.md | 64 ++++++++++++++++++++++++++++++++++++-----------------------
 1 file changed, 39 insertions(+), 25 deletions(-)

(limited to 'doc')

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
-- 
cgit v1.2.3