AGENTS.md

1# gRPC Client Channel
2 
3This directory contains the core implementation of the client-side channel in gRPC. It's responsible for managing the entire lifecycle of a connection from a client to a server, including name resolution, load balancing, and connectivity.
4 
5## Overarching Purpose
6 
7The code in this directory provides the building blocks for creating and managing client-side channels. It orchestrates the process of turning a target URI into a set of connections to backend servers, and then distributing RPCs across those connections.
8 
9## Core Concepts
10 
11The client channel is built around a few key abstractions:
12 
13*   **`ClientChannel`**: The top-level object that represents a connection to a service. It owns the other components and is responsible for orchestrating the overall process of name resolution, load balancing, and connection management.
14*   **`Subchannel`**: A `Subchannel` represents a connection to a single backend address. A `ClientChannel` typically manages multiple `Subchannel`s, one for each address returned by the resolver.
15*   **`Resolver`**: The `Resolver` is responsible for taking a target URI (e.g., "dns:///my-service.example.com") and resolving it to a list of backend addresses. See the [resolver documentation](../resolver/AGENTS.md) for more details.
16*   **`LoadBalancingPolicy`**: The `LoadBalancingPolicy` is responsible for taking the list of subchannels from the `ClientChannel` and deciding which one to use for each RPC. See the [load balancing documentation](../load_balancing/AGENTS.md) for more details.
17 
18## Legacy Architecture
19 
20The original architecture of the client channel relied heavily on callback-based filters. This approach is still present in some parts of the code, but is being actively migrated to a more modern, promise-based model.
21 
22*   **`retry_filter.h`, `retry_filter.cc`**: Implements a channel filter that provides automatic retries for failed RPCs, based on the service config. This is an example of a "dynamic filter", which can be configured on a per-service or per-method basis.
23*   **`dynamic_filters.h`, `dynamic_filters.cc`**: These files provide the framework for creating and managing dynamic filters.
24 
25## Modern Architecture
26 
27The newer architecture of the client channel is based on promise-based interceptors. This approach is more flexible and easier to reason about, and is the preferred way to implement new features.
28 
29*   **`retry_interceptor.h`, `retry_interceptor.cc`**: Implements an interceptor that provides automatic retries for failed RPCs, based on the service config. This is the modern, promise-based replacement for `retry_filter`.
30 
31## Files
32 
33*   **`client_channel.h`, `client_channel.cc`**: These files contain the main `ClientChannel` class, which is the primary implementation of the `grpc::Channel` interface for clients. It manages the entire lifecycle of a client-side channel.
34*   **`subchannel.h`, `subchannel.cc`**: These files define the `Subchannel` class, which represents a connection to a single backend address.
35*   **`client_channel_factory.h`, `client_channel_factory.cc`**: These files define the `ClientChannelFactory`, which is responsible for creating `ClientChannel` and `Subchannel` instances.
36*   **`connector.h`**: Defines the `Connector` interface, which is responsible for establishing a transport-level connection to a given address.
37*   **`load_balanced_call_destination.h`, `load_balanced_call_destination.cc`**: Defines the `LoadBalancedCallDestination`, which is a call destination that uses a `LoadBalancingPolicy` to select a subchannel for each call.
38*   **`retry_filter.h`, `retry_filter.cc`**: Implements a channel filter that provides automatic retries for failed RPCs, based on the service config. This is an example of a "dynamic filter", which can be configured on a per-service or per-method basis.
39*   **`retry_interceptor.h`, `retry_interceptor.cc`**: Implements an interceptor that provides automatic retries for failed RPCs, based on the service config.
40*   **`config_selector.h`**: Defines the `ConfigSelector` class, which is used to select the appropriate service config for a given RPC.
41*   **`subchannel_pool_interface.h`, `subchannel_pool_interface.cc`**: Defines the interface for a subchannel pool, which is used to cache and reuse subchannels.
42*   **`global_subchannel_pool.h`, `global_subchannel_pool.cc`**: Implements a global subchannel pool that can be shared across multiple channels.
43 
44## Major Classes
45 
46*   **`grpc_core::ClientChannel`**: The main client-side channel implementation. It integrates the [resolver](../resolver/AGENTS.md), [load balancing policy](../load_balancing/AGENTS.md), and subchannels to provide a unified view of a connection to a service.
47*   **`grpc_core::Subchannel`**: Represents a single connection to a backend. It manages the connectivity state of that connection and provides a mechanism for creating transports.
48*   **`grpc_core::ClientChannelFactory`**: A factory class for creating client channels and subchannels.
49*   **`grpc_core::Connector`**: An interface for creating a transport-level connection.
50 
51## Notes
52 
53*   The client channel is a complex piece of machinery that coordinates several different components. Understanding the roles of the [resolver](../resolver/AGENTS.md), [load balancing policy](../load_balancing/AGENTS.md), and subchannels is key to understanding how it works.
54*   Much of the client channel is being migrated to a new, promise-based architecture. As a result, you will see a mix of legacy callback-based code and newer promise-based code. The `retry_filter.h` and `retry_interceptor.h` files are a good example of this transition, where the former is the legacy implementation and the latter is the new promise-based one.
55*   The `dynamic_filters` are a legacy mechanism for adding filters to the channel. They are being replaced by the more flexible interceptor model.
56*   The `ClientChannel` uses a `WorkSerializer` to ensure that all of its internal state is accessed in a thread-safe manner.
57*   The `ConfigSelector` allows for different service configs to be used for different RPCs on the same channel. This is used to support features like per-method retry policies.
58