docs: Clarify xDS semantics for resources that do not exist. (envoypr…

…oxy#9322)

Clarify xDS protocol semantics for resources that do not exist.

Risk Level: Low
Testing: N/A
Docs Changes: Included in PR.

Signed-off-by: Mark D. Roth <[email protected]>

api/xds_protocol.rst

@@ -385,23 +385,35 @@ from the client's perspective.
 Knowing When a Requested Resource Does Not Exist
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-In the SotW protocol variants, responses for :ref:`Listener <envoy_api_msg_Listener>` and
-:ref:`Cluster <envoy_api_msg_Cluster>` resource types must include all resources requested by the
-client. Therefore, if a client requests a resource that does not exist, it can immediately
-tell this from the response.
-
-However, for other resource types, because each resource can be sent in its own response, there is
-no way to know from the next response whether the newly requested resource exists, because the next
+The SotW protocol variants do not provide any explicit mechanism to determine when a requested
+resource does not exist.
+
+Responses for :ref:`Listener <envoy_api_msg_Listener>` and :ref:`Cluster <envoy_api_msg_Cluster>`
+resource types must include all resources requested by the client. However, it may not be possible
+for the client to know that a resource does not exist based solely on its absence in a response,
+because the delivery of the updates is eventually consistent: if the client initially sends a
+request for resource A, then sends a request for resources A and B, and then sees a response
+containing only resource A, the client cannot conclude that resource B does not exist, because
+the response may have been sent on the basis of the first request, before the server saw the
+second request.
+
+For other resource types, because each resource can be sent in its own response, there is no way
+to know from the next response whether the newly requested resource exists, because the next
 response could be an unrelated update for another resource that had already been subscribed to
-previously. As a result, clients are expected to use a timeout (recommended duration is 15
-seconds) after sending a request for a new resource, after which they will consider the requested
-resource to not exist if they have not received the resource. In Envoy, this is done for
+previously.
+
+As a result, clients are expected to use a timeout (recommended duration is 15 seconds) after
+sending a request for a new resource, after which they will consider the requested resource to
+not exist if they have not received the resource. In Envoy, this is done for
 :ref:`RouteConfiguration <envoy_api_msg_RouteConfiguration>` and :ref:`ClusterLoadAssignment
 <envoy_api_msg_ClusterLoadAssignment>` resources during :ref:`resource warming
 <xds_protocol_resource_warming>`.
 
-Note that clients may want to use the same timeout even for :ref:`Listener
-<envoy_api_msg_Listener>` and :ref:`Cluster <envoy_api_msg_Cluster>` resources, to protect
+Note that this timeout is not strictly necessary when using wildcard mode for :ref:`Listener
+<envoy_api_msg_Listener>` and :ref:`Cluster <envoy_api_msg_Cluster>` resource types, because
+in that case every response will contain all existing resources that are relevant to the
+client, so the client can know that a resource does not exist by its absence in the next
+response it sees. However, using a timeout is still recommended in this case, since it protects
 against the case where the management server fails to send a response in a timely manner.
 
 Note that even if a requested resource does not exist at the moment when the client requests it,