Incremental XDS proposal.

api/XDS_PROTOCOL.md

@@ -285,6 +285,50 @@ admin:
 
 ```
 
+### Incremental xDS
+
+Incremental xDS is separate xDS endpoint available for ADS that allows:
+
+  * Incremental updates of the list of tracked resources by the xDS client.
+    This supports Envoy on-demand / lazily requesting additional resources. For
+    example, this may occur when a request corresponding to an unknown cluster
+    arrives.
+  * The xDS server can incremetally update the resources on the client.
+    This support the goal of scalability of xDS resources. Rather than deliver
+    all 100k clusters when a single cluster is modified, the management server
+    only needs to deliver the single cluster that changed.
+
+An xDS Incremental session is always in the context of a gRPC bidirectional
+stream. This allows the xDS server to keep track of the state of xDS clients
+connected to it. There is no REST version of Incremental xDS.
+
+In Incremental xDS the nonce field is required and used to pair
+IncrementalDiscoveryResponse to a IncrementalDiscoveryRequest ACK or NACK.
+Optionaly, a response message level system_version_info is present for
+debugging purposes only.
+
+IncrementalDiscoveryRequest can be sent in 3 situations:
+  1. Initial message in a xDS bidirectional gRPC stream.
+  2. As a ACK or NACK response to a previous IncrementalDiscoveryResponse.
+     In this case the response_nonce is set to the nonce value in the Response.
+     ACK or NACK is determined by the absence or presence of error_detail.
+  3. Spontaneous IncrementalDiscoveryRequest from the client.
+     This can be done to dynamically add or remove elements from the tracked
+     resource_names set. In this case response_nonce must be omitted.
+
+In this first example the client connects as receive a first update that it ACKs.
+The second update fails and the client NACKs the update. Later the xDS client
+spontaneously requests the "wc" resource.
+
+![Incremental session example](diagrams/incremental.svg)
+
+On reconnect the xDS Incremental client may tell the server of its known resources
+to avoid resending them over the network.
+
+![Incremental reconnect example](diagrams/incremental-reconnect.svg)
+
+The Incremental xDS method may be added to CDS and RDS in the future.
+
 ## REST-JSON polling subscriptions
 
 Synchronous (long) polling via REST endpoints is also available for the xDS