Comparison

A · AGENTS.md · grpc/grpc B · AGENTS.md · grpc/grpc

What each file covers, counted
Dimension	Only in A	Only in B	Overlap
Sections	7	4	0%
Commands	0	0	—
Section tags	1	3	0%

What each file covers

Sections

0 shared · 7 only in A · 4 only in B

− gRPC xDS
− Overarching Purpose
− Core Concepts
− `xds_client` Directory
− Files
− Major Classes
− Notes
+ gRPC C++ Agents Collaboration Guide
+ Preferred Tools & Libraries
+ Code Style & Conventions
+ About gRPC

Commands

neither file has any

Section tags

0 shared · 1 only in A · 3 only in B

− architecture
+ code-style
+ dependencies
+ do-not

Line diff

+29 added−40 removed5 unchanged11.1% identical

grpc/grpc · src/core/xds/AGENTS.md

@@ −1 @@

1# gRPC xDS

3This directory contains the implementation of gRPC's xDS support. xDS is a set of APIs that allow a gRPC client or server to discover and configure itself dynamically.

5See also: [gRPC Core overview](../AGENTS.md)

7## Overarching Purpose

9The code in this directory provides a gRPC implementation of the xDS APIs. This allows gRPC clients and servers to be configured by a central control plane. xDS is one way that service configurations can be delivered to a gRPC application; see [service config](../service_config/AGENTS.md) for more information.

11## Core Concepts

13* **`XdsClient`**: The `XdsClient` is the core of the xDS implementation. It is responsible for managing the connection to the xDS server, sending resource requests, and receiving and processing resource updates.

14* **Bootstrap File**: The `XdsClient` is configured via a bootstrap file. The bootstrap file is a JSON file that contains the information that the `XdsClient` needs to connect to the xDS server.

15* **xDS Resources**: xDS is a set of APIs for discovering and configuring different types of resources. The most important resource types for gRPC are:

16 * **LDS (Listener Discovery Service)**: Used to discover the listeners that are running on a gRPC server.

17 * **RDS (Route Discovery Service)**: Used to discover the routes that are available for a given listener.

18 * **CDS (Cluster Discovery Service)**: Used to discover the clusters that are available to the gRPC client.

19 * **EDS (Endpoint Discovery Service)**: Used to discover the endpoints (i.e., the backend servers) that are in a given cluster.

21## `xds_client` Directory

23The `xds_client` directory contains the core implementation of the xDS client.

25### Files

27* **`xds_client.h`, `xds_client.cc`**: These files define the `XdsClient` class.

28* **`xds_bootstrap.h`, `xds_bootstrap.cc`**: These files define the `XdsBootstrap` class, which is responsible for reading the xDS bootstrap file and creating the initial `XdsClient` configuration.

29* **`xds_api.h`, `xds_api.cc`**: These files define the `XdsApi` class, which provides a high-level API for interacting with the xDS server.

30* **`lrs_client.h`, `lrs_client.cc`**: These files define the `LrsClient` class, which is used to send load reports to the xDS server.

31* **`xds_resource_type.h`**: Defines the interface for a specific xDS resource type. Each resource type (e.g., LDS, RDS, CDS, EDS) has its own implementation of this interface.

33### Major Classes

35* **`grpc_core::XdsClient`**: The core of the xDS client implementation.

36* **`grpc_core::XdsBootstrap`**: Responsible for reading the xDS bootstrap file.

37* **`grpc_core::XdsApi`**: A high-level API for interacting with the xDS server.

38* **`grpc_core::LrsClient`**: A client for sending load reports to the xDS server.

40## Notes

42* xDS is a complex and powerful feature. A full understanding of xDS requires reading the official [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-docs/xds_protocol).

43* The gRPC xDS implementation is still under active development.

44* The xDS implementation is a good example of how gRPC can be extended with new features. It is implemented as a set of plugins that are loaded at runtime, and it uses the `CoreConfiguration` class to register its factories.

grpc/grpc · AGENTS.md

@@ +1 @@

1# gRPC C++ Agents Collaboration Guide

3This document outlines conventions and best practices for AI-assisted development in the gRPC C++ codebase.

5## Preferred Tools & Libraries

6* Prefer gRPC types before absl.

7* Prefer std types when available, use absl types when not

8* Prefer `std::optional` over `absl::optional`

9* gRPC uses C++17, so we can't use C++20 onwards types.

10* The Python implementation cannot depend on the protobuf library, so any shared libraries must expose a C-style API that does not rely on C++ protobuf types.

12## Code Style & Conventions

13* `#include <grpc/support/port_platform.h>` is not required unless its macros are needed for compilation.

14* Only include headers that are actively used.

15* Abseil headers are sorted before gRPC headers.

16* For public api headers (in `include/grpc`) we use `<grpc/...>`.

17 * Example: `#include <grpc/grpc.h>`

18* Prefer explicit types over `std::pair` or `std::tuple` for return types.

19* Use `LOG(ERROR)` from `absl/log/log.h` for logging errors, never use `std::cerr` or `gpr_log`.

20* The `fuzztest.h` header is located at `fuzztest/fuzztest.h`.

22## About gRPC

23* gRPC uses its own macros for Bazel libraries, tests, etc. Each directory should have a `grpc_package` declaration. For libraries use `grpc_cc_library`, for tests `grpc_cc_test`.

24* Dependencies on non-gRPC libraries (like gtest or absl) are listed in the `external_deps` attribute.

25* The `:grpc` BUILD target is not allowed to depend on the C++ protobuf library, either directly or transitively.

26* Build files for implementation code are typically located in `src/core/BUILD` and `BUILD`. Do not add new `BUILD` files under the `src/` tree without explicit instruction.

27* Tests are located in `test/core` and `test/cpp` (corresponding to the `src` directories). These test directories contain their own `BUILD` files.

28* Fuzz tests use `fuzztest_main` instead of `gtest_main`.

29* When depending on a `grpc_proto_library`, the name of the `cc_library` target is the same as the `name` of the `grpc_proto_library` rule itself, not `[name]_cc_proto` as one might expect from standard Bazel `cc_proto_library` rules. The build system error messages can be misleading in this case.

30* The 'gtest' external_dep also includes 'gmock'.

31* All `upb` related build rules (`grpc_upb_proto_library`, `grpc_upb_proto_reflection_library`) for protos defined anywhere in the repository must be defined in the root `BUILD` file. They should not be placed in the `BUILD` file of the subdirectory where the proto is located.

32* Core end-to-end tests are defined in `test/core/end2end/BUILD` using the `grpc_core_end2end_test_suite` macro. This macro generates multiple `grpc_cc_test` targets by combining a configuration file (like `end2end_http2_config.cc`) with individual test implementation files located in `test/core/end2end/tests/`. The final test target name is created by appending `_test` to the `name` attribute of the macro. For example, `grpc_core_end2end_test_suite(name = "end2end_http2", ...)` generates the test target `//test/core/end2end:end2end_http2_test`.

33* Unused named parameters is a compilation failure.

@@ −1 +1 @@

1−# gRPC xDS

1+# gRPC C++ Agents Collaboration Guide

3−This directory contains the implementation of gRPC's xDS support. xDS is a set of APIs that allow a gRPC client or server to discover and configure itself dynamically.

3+This document outlines conventions and best practices for AI-assisted development in the gRPC C++ codebase.

5−See also: [gRPC Core overview](../AGENTS.md)

5+## Preferred Tools & Libraries

6+* Prefer gRPC types before absl.

7+* Prefer std types when available, use absl types when not

8+* Prefer `std::optional` over `absl::optional`

9+* gRPC uses C++17, so we can't use C++20 onwards types.

10+* The Python implementation cannot depend on the protobuf library, so any shared libraries must expose a C-style API that does not rely on C++ protobuf types.

611

7−## Overarching Purpose

12+## Code Style & Conventions

13+* `#include <grpc/support/port_platform.h>` is not required unless its macros are needed for compilation.

14+* Only include headers that are actively used.

15+* Abseil headers are sorted before gRPC headers.

16+* For public api headers (in `include/grpc`) we use `<grpc/...>`.

17+ * Example: `#include <grpc/grpc.h>`

18+* Prefer explicit types over `std::pair` or `std::tuple` for return types.

19+* Use `LOG(ERROR)` from `absl/log/log.h` for logging errors, never use `std::cerr` or `gpr_log`.

20+* The `fuzztest.h` header is located at `fuzztest/fuzztest.h`.

821

9−The code in this directory provides a gRPC implementation of the xDS APIs. This allows gRPC clients and servers to be configured by a central control plane. xDS is one way that service configurations can be delivered to a gRPC application; see [service config](../service_config/AGENTS.md) for more information.

10−

11−## Core Concepts

12−

13−* **`XdsClient`**: The `XdsClient` is the core of the xDS implementation. It is responsible for managing the connection to the xDS server, sending resource requests, and receiving and processing resource updates.

14−* **Bootstrap File**: The `XdsClient` is configured via a bootstrap file. The bootstrap file is a JSON file that contains the information that the `XdsClient` needs to connect to the xDS server.

15−* **xDS Resources**: xDS is a set of APIs for discovering and configuring different types of resources. The most important resource types for gRPC are:

16− * **LDS (Listener Discovery Service)**: Used to discover the listeners that are running on a gRPC server.

17− * **RDS (Route Discovery Service)**: Used to discover the routes that are available for a given listener.

18− * **CDS (Cluster Discovery Service)**: Used to discover the clusters that are available to the gRPC client.

19− * **EDS (Endpoint Discovery Service)**: Used to discover the endpoints (i.e., the backend servers) that are in a given cluster.

20−

21−## `xds_client` Directory

22−

23−The `xds_client` directory contains the core implementation of the xDS client.

24−

25−### Files

26−

27−* **`xds_client.h`, `xds_client.cc`**: These files define the `XdsClient` class.

28−* **`xds_bootstrap.h`, `xds_bootstrap.cc`**: These files define the `XdsBootstrap` class, which is responsible for reading the xDS bootstrap file and creating the initial `XdsClient` configuration.

29−* **`xds_api.h`, `xds_api.cc`**: These files define the `XdsApi` class, which provides a high-level API for interacting with the xDS server.

30−* **`lrs_client.h`, `lrs_client.cc`**: These files define the `LrsClient` class, which is used to send load reports to the xDS server.

31−* **`xds_resource_type.h`**: Defines the interface for a specific xDS resource type. Each resource type (e.g., LDS, RDS, CDS, EDS) has its own implementation of this interface.

32−

33−### Major Classes

34−

35−* **`grpc_core::XdsClient`**: The core of the xDS client implementation.

36−* **`grpc_core::XdsBootstrap`**: Responsible for reading the xDS bootstrap file.

37−* **`grpc_core::XdsApi`**: A high-level API for interacting with the xDS server.

38−* **`grpc_core::LrsClient`**: A client for sending load reports to the xDS server.

39−

40−## Notes

41−

42−* xDS is a complex and powerful feature. A full understanding of xDS requires reading the official [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-docs/xds_protocol).

43−* The gRPC xDS implementation is still under active development.

44−* The xDS implementation is a good example of how gRPC can be extended with new features. It is implemented as a set of plugins that are loaded at runtime, and it uses the `CoreConfiguration` class to register its factories.

22+## About gRPC

23+* gRPC uses its own macros for Bazel libraries, tests, etc. Each directory should have a `grpc_package` declaration. For libraries use `grpc_cc_library`, for tests `grpc_cc_test`.

24+* Dependencies on non-gRPC libraries (like gtest or absl) are listed in the `external_deps` attribute.

25+* The `:grpc` BUILD target is not allowed to depend on the C++ protobuf library, either directly or transitively.

26+* Build files for implementation code are typically located in `src/core/BUILD` and `BUILD`. Do not add new `BUILD` files under the `src/` tree without explicit instruction.

27+* Tests are located in `test/core` and `test/cpp` (corresponding to the `src` directories). These test directories contain their own `BUILD` files.

28+* Fuzz tests use `fuzztest_main` instead of `gtest_main`.

29+* When depending on a `grpc_proto_library`, the name of the `cc_library` target is the same as the `name` of the `grpc_proto_library` rule itself, not `[name]_cc_proto` as one might expect from standard Bazel `cc_proto_library` rules. The build system error messages can be misleading in this case.

30+* The 'gtest' external_dep also includes 'gmock'.

31+* All `upb` related build rules (`grpc_upb_proto_library`, `grpc_upb_proto_reflection_library`) for protos defined anywhere in the repository must be defined in the root `BUILD` file. They should not be placed in the `BUILD` file of the subdirectory where the proto is located.

32+* Core end-to-end tests are defined in `test/core/end2end/BUILD` using the `grpc_core_end2end_test_suite` macro. This macro generates multiple `grpc_cc_test` targets by combining a configuration file (like `end2end_http2_config.cc`) with individual test implementation files located in `test/core/end2end/tests/`. The final test target name is created by appending `_test` to the `name` attribute of the macro. For example, `grpc_core_end2end_test_suite(name = "end2end_http2", ...)` generates the test target `//test/core/end2end:end2end_http2_test`.

33+* Unused named parameters is a compilation failure.

4534