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