1Service Config in gRPC 2====================== 3 4# Objective 5 6The service config is a mechanism that allows service owners to publish 7parameters to be automatically used by all clients of their service. 8 9# Format 10 11The fields of the service config are defined by the 12[`grpc.service_config.ServiceConfig` protocol buffer 13message](https://github.com/grpc/grpc-proto/blob/master/grpc/service_config/service_config.proto). 14Note that new fields may be added in the future as new functionality is 15introduced. 16 17Internally, gRPC uses the service config in JSON form. The JSON 18representation is the result of converting the protobuf form into JSON 19using the normal [protobuf to JSON translation 20rules](https://developers.google.com/protocol-buffers/docs/proto3#json). 21In particular, this means: 22- Field names are converted from `snake_case` to `camelCase`. 23- Field values are converted as per the documented translation rules: 24 - Strings, 32-bit integers, and bools are converted into the 25 corresponding JSON types. 26 - 64-bit integers are converted into strings (e.g., `"251"`). 27 - The value of a repeated field will be represented as a JSON array. 28 - The value of a `google.protobuf.Duration` will be represented as a 29 string containing a decimal number of seconds (e.g., `"1.000340012s"`). 30 31For more details, see the protobuf docs linked above. 32 33Note that the JSON representation has one advantage over the protobuf 34representation, which is that it is possible to encode configurations 35for [LB policies](load-balancing.md) that are not known to gRPC. In 36protobuf form, the `loadBalancingConfig` field contains a `oneof` 37supporting only the built-in LB policies. However, in JSON form, the 38field inside the `oneof` is encoded as a string that indicates the LB 39policy name. In JSON form, that string can be any arbitrary value, not 40just one of the supported policies inside of the `oneof`, so third-party 41policies can be selected. 42 43# Architecture 44 45A service config is associated with a server name. The [name 46resolver](naming.md) plugin, when asked to resolve a particular server 47name, will return both the resolved addresses and the service config. 48 49The name resolver returns the service config to the gRPC client in JSON form. 50Individual resolver implementations determine where and in what format the 51service config is stored. If the resolver implemention obtains the 52service config in protobuf form, it must convert it to JSON. 53Alternatively, a resolver implementation may obtain the service config 54already in JSON form, in which case it may return it directly. Or it 55may construct the JSON dynamically from some other source data. 56 57For details of how the DNS resolver plugin supports service configs, see 58[gRFC A2: Service Config via 59DNS](https://github.com/grpc/proposal/blob/master/A2-service-configs-in-dns.md). 60 61# Example 62 63Here is an example service config in protobuf form: 64 65``` 66{ 67 // Use round_robin LB policy. 68 load_balancing_config: { round_robin: {} } 69 // This method config applies to method "foo/bar" and to all methods 70 // of service "baz". 71 method_config: { 72 name: { 73 service: "foo" 74 method: "bar" 75 } 76 name: { 77 service: "baz" 78 } 79 // Default timeout for matching methods. 80 timeout: { 81 seconds: 1 82 nanos: 1 83 } 84 } 85} 86``` 87 88Here is the same example service config in JSON form: 89 90``` 91{ 92 "loadBalancingConfig": [ { "round_robin": {} } ], 93 "methodConfig": [ 94 { 95 "name": [ 96 { "service": "foo", "method": "bar" }, 97 { "service": "baz" } 98 ], 99 "timeout": "1.000000001s" 100 } 101 ] 102} 103``` 104 105# APIs 106 107The service config is used in the following APIs: 108 109- In the resolver API, used by resolver plugins to return the service 110 config to the gRPC client. 111- In the gRPC client API, where users can query the channel to obtain 112 the service config associated with the channel (for debugging 113 purposes). 114- In the gRPC client API, where users can set the service config 115 explicitly. This can be used to set the config in unit tests. It can 116 also be used to set the default config that will be used if the 117 resolver plugin does not return a service config. 118