AGENTS.md

1# gRPC Core Architecture
2 
3This document provides a high-level overview of the gRPC Core architecture. gRPC Core is a library written in C++ that provides a portable and performant implementation of the gRPC protocol.
4 
5## Core Concepts
6 
7The gRPC Core is built around a few key concepts:
8 
9*   **Channels and Calls**: A **channel** represents a connection to a gRPC service, while a **call** represents a single RPC. The [`call`](./call/AGENTS.md) directory contains the fundamental data structures for managing a call's lifecycle.
10*   **Transports**: A **transport** is responsible for sending and receiving data over the network. gRPC Core supports several transports, including CHTTP2, in-process, and an experimental "Chaotic Good" transport. See the [`transport`](./transport/AGENTS.md) and [`ext/transport`](./ext/transport/AGENTS.md) directories for more information.
11*   **Filters**: **Filters** are a mechanism for intercepting and modifying RPCs. They are used to implement a wide variety of features, including authentication, compression, and retry. See the [`filter`](./filter/AGENTS.md) and [`ext/filters`](./ext/filters/AGENTS.md) directories for more information.
12*   **Promises**: **Promises** are a framework for asynchronous programming. They are used extensively throughout the gRPC Core to implement non-blocking I/O and other asynchronous operations. See the [`lib/promise`](./lib/promise/AGENTS.md) directory for more information.
13*   **Event Engine**: The **Event Engine** is an abstraction layer that provides a consistent interface to the underlying operating system's I/O and threading primitives. See the [`lib/event_engine`](./lib/event_engine/AGENTS.md) directory for more information.
14 
15## Coding Style
16 
17*   **No Exceptions**: gRPC Core code does not use C++ exceptions. Functions should return an error code to indicate failure. Possible error types:
18    - bool - if the error is success or failure for a simple function, this is simple and efficient
19    - absl::Status, absl::StatusOr - a good fallback for cross layer code
20    - StatusFlag (in src/core/lib/promise) - a boolean that is recognizable as an error condition by the promise library; the same library provides ValueOrError that fills the role of StatusOr for this type
21    - It's ok and recommended to write a bespoke error type if your failures don't fit the above mold. It's strongly recommended to provide a mechanism to reduce custom errors to absl::Status for portability between layers.
22 
23## Directory Structure
24 
25The gRPC Core is organized into the following directories:
26 
27*   [`call`](./call/AGENTS.md): The heart of the gRPC C++ core, defining the fundamental data structures for an RPC.
28*   [`channelz`](./channelz/AGENTS.md): A system for inspecting the state of gRPC channels.
29*   [`client_channel`](./client_channel/AGENTS.md): The core implementation of the client-side channel, including name resolution, load balancing, and connectivity.
30*   [`config`](./config/AGENTS.md): Manages static and dynamic configuration of the gRPC Core.
31*   [`credentials`](./credentials/AGENTS.md): The core implementation of gRPC's credential system.
32*   [`ext`](./ext/AGENTS.md): Contains extensions to the gRPC Core, including filters and transports.
33*   [`filter`](./filter/AGENTS.md): The fundamental building blocks for the gRPC channel filter mechanism.
34*   [`handshaker`](./handshaker/AGENTS.md): A framework for establishing a secure connection between a client and a server.
35*   [`lib`](./lib/AGENTS.md): A collection of libraries that provide common functionality, such as data structures, memory management, and platform-specific code.
36*   [`load_balancing`](./load_balancing/AGENTS.md): A flexible and extensible framework for load balancing.
37*   [`plugin_registry`](./plugin_registry/AGENTS.md): The main entry point for configuring the gRPC Core library.
38*   [`resolver`](./resolver/AGENTS.md): A pluggable mechanism for resolving a logical name into a list of network addresses.
39*   [`server`](./server/AGENTS.md): The core implementation of the gRPC server.
40*   [`service_config`](./service_config/AGENTS.md): A mechanism for per-service and per-method configuration of a gRPC channel.
41*   [`telemetry`](./telemetry/AGENTS.md): A system for collecting and reporting metrics about the behavior of gRPC.
42*   [`transport`](./transport/AGENTS.md): The core transport abstraction for gRPC.
43*   [`tsi`](./tsi/AGENTS.md): An abstraction for different transport security mechanisms like TLS and ALTS.
44*   [`util`](./util/AGENTS.md): A collection of utility classes and functions.
45*   [`xds`](./xds/AGENTS.md): An implementation of the xDS APIs, which allow a gRPC client or server to discover and configure itself dynamically.
46