doc: add fake control plane xds test comments (#9735)

xds/src/test/java/io/grpc/xds/FakeControlPlaneXdsIntegrationTest.java

@@ -51,6 +51,22 @@
 /**
  * Xds integration tests using a local control plane, implemented in {@link
  * XdsTestControlPlaneService}. Test cases can inject xds configs to the control plane for testing.
+ *
+ * <p>Test components:
+ * 1) A Control Plane {@link XdsTestControlPlaneService} accepts xds requests from multiple clients
+ * from the Data Plane, see {@link ControlPlaneRule}.
+ * 2) A test xDS server {@link XdsServerWrapper}, see {@link DataPlaneRule}.
+ * 3) A test xDS client that uses a testing scheme {@link XdsNameResolverProvider#createForTest},
+ * see {@link DataPlaneRule}.
+ *
+ * <p>The configuration dependency and ephemeral port allocation requires the components to
+ * be initialized in a certain order:
+ * 1) Start the Control Plane server {@link XdsTestControlPlaneService}. After start the bootstrap
+ * information (w/ Control Plane's address) can be constructed for the Data Plane to initialize.
+ * 2) Set LDS and RDS config at the Control Plane. Get the bootstrap file from the Control
+ * Plane from 1). And then start the test xDS server (requires LDS/RDS and bootstrap file to start).
+ * 3) Construct EDS config w/ test server address from 2). Set CDS and EDS Config at the Control
+ * Plane. Then start the test xDS client (requires EDS to do xDS name resolution).
  */
 @RunWith(JUnit4.class)
 public class FakeControlPlaneXdsIntegrationTest {

xds/src/test/java/io/grpc/xds/XdsTestControlPlaneService.java

@@ -33,6 +33,26 @@
 import java.util.logging.Level;
 import java.util.logging.Logger;
 
+/**
+* A bidi-stream service that acts as a local xDS Control Plane.
+ * It accepts xDS config injection through a method call {@link #setXdsConfig}. Handling AdsStream
+ * response or updating xds config are run in syncContext.
+ *
+ * <p>The service maintains lookup tables:
+ * Subscriber table: map from each resource type, to a map from each client to subscribed resource
+ * names set.
+ * Resources table: store the resources in raw proto message.
+ *
+ * <p>xDS protocol requires version/nonce to avoid various race conditions. In this impl:
+ * Version stores the latest version number per each resource type. It is simply bumped up on each
+ * xds config set.
+ * Nonce stores the nonce number for each resource type and for each client. Incoming xDS requests
+ * share the same proto message type but may at different resources update phases:
+ * 1) Original: an initial xDS request.
+ * 2) NACK an xDS response.
+ * 3) ACK an xDS response.
+ * The service is capable of distinguish these cases when handling the request.
+ */
 final class XdsTestControlPlaneService extends
  AggregatedDiscoveryServiceGrpc.AggregatedDiscoveryServiceImplBase {
  private static final Logger logger = Logger.getLogger(XdsTestControlPlaneService.class.getName());