AGENTS.md

1# gRPC Service Config
2 
3This directory contains the implementation of gRPC's service config feature, which allows for per-service and per-method configuration of a gRPC channel.
4 
5See also: [gRPC Core overview](../AGENTS.md)
6 
7## Overarching Purpose
8 
9The code in this directory provides a mechanism for parsing and applying service configs. Service configs can be used to configure a variety of features, such as load balancing, retries, and message size limits.
10 
11## Core Concepts
12 
13*   **`ServiceConfig`**: The `ServiceConfig` class is an abstract base class for service configs. It provides methods for retrieving the raw JSON string of the service config, as well as for retrieving parsed config values for a given method.
14*   **`ServiceConfigParser`**: The `ServiceConfigParser` class is a registry of `Parser` instances. Each `Parser` is responsible for parsing a specific part of the service config. This makes the service config framework highly extensible.
15 
16## How to Add a New Service Config Parser
17 
181.  Create a new class that derives from `ServiceConfigParser::Parser`.
192.  Implement the `ParseGlobalParams` and/or `ParsePerMethodParams` methods. These methods will be called by the `ServiceConfig` framework to parse the global and per-method parts of the service config, respectively.
203.  Register your parser with the `CoreConfiguration` builder at startup.
21 
22## Files
23 
24*   **`service_config.h`**: Defines the `ServiceConfig` class.
25*   **`service_config_parser.h`, `service_config_parser.cc`**: These files define the `ServiceConfigParser` class.
26*   **`service_config_impl.h`, `service_config_impl.cc`**: These files define the `ServiceConfigImpl` class, which is the concrete implementation of the `ServiceConfig` interface.
27*   **`service_config_call_data.h`**: Defines the `ServiceConfigCallData` class, which is used to store the per-call service config data.
28 
29## Notes
30 
31*   Service configs are typically provided by the name resolver (see [`../resolver/AGENTS.md`](../resolver/AGENTS.md)).
32*   Service configs can also be delivered via xDS (see [`../xds/AGENTS.md`](../xds/AGENTS.md)).
33*   The service config is a powerful feature that allows for a great deal of flexibility in configuring gRPC channels.
34*   The service config is used to configure load balancing (see [`../load_balancing/AGENTS.md`](../load_balancing/AGENTS.md)).
35