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 service config is a JSON string of the following form:
12
13```
14{
15  // [deprecated] Load balancing policy name (case insensitive).
16  // Currently, the only selectable client-side policy provided with gRPC
17  // is 'round_robin', but third parties may add their own policies.
18  // This field is optional; if unset, the default behavior is to pick
19  // the first available backend. If set, the load balancing policy should be
20  // supported by the client, otherwise the service config is considered
21  // invalid.
22  // If the policy name is set via the client API, that value overrides
23  // the value specified here.
24  //
25  // Note that if the resolver returns at least one balancer address (as
26  // opposed to backend addresses), gRPC will use grpclb (see
27  // https://github.com/grpc/grpc/blob/master/doc/load-balancing.md),
28  // regardless of what LB policy is requested either here or via the
29  // client API.
30  'loadBalancingPolicy': string,
31
32  // Per-method configuration.  Optional.
33  'methodConfig': [
34    {
35      // The names of the methods to which this method config applies. There
36      // must be at least one name. Each name entry must be unique across the
37      // entire service config. If the 'method' field is empty, then this
38      // method config specifies the defaults for all methods for the specified
39      // service.
40      //
41      // For example, let's say that the service config contains the following
42      // method config entries:
43      //
44      // 'methodConfig': [
45      //   { 'name': [ { 'service': 'MyService' } ] ... },
46      //   { 'name': [ { 'service': 'MyService', 'method': 'Foo' } ] ... }
47      // ]
48      //
49      // For a request for MyService/Foo, we will use the second entry, because
50      // it exactly matches the service and method name.
51      // For a request for MyService/Bar, we will use the first entry, because
52      // it provides the default for all methods of MyService.
53      'name': [
54        {
55          // RPC service name.  Required.
56          // If using gRPC with protobuf as the IDL, then this will be of
57          // the form "pkg.service_name", where "pkg" is the package name
58          // defined in the proto file.
59          'service': string,
60
61          // RPC method name.  Optional (see above).
62          'method': string,
63        }
64      ],
65
66      // Optional. Whether RPCs sent to this method should wait until the
67      // connection is ready by default. If false, the RPC will abort
68      // immediately if there is a transient failure connecting to the server.
69      // Otherwise, gRPC will attempt to connect until the deadline is
70      // exceeded.
71      //
72      // The value specified via the gRPC client API will override the value
73      // set here. However, note that setting the value in the client API will
74      // also affect transient errors encountered during name resolution,
75      // which cannot be caught by the value here, since the service config
76      // is obtained by the gRPC client via name resolution.
77      'waitForReady': bool,
78
79      // Optional. The default timeout in seconds for RPCs sent to this method.
80      // This can be overridden in code. If no reply is received in the
81      // specified amount of time, the request is aborted and a
82      // deadline-exceeded error status is returned to the caller.
83      //
84      // The actual deadline used will be the minimum of the value specified
85      // here and the value set by the application via the gRPC client API.
86      // If either one is not set, then the other will be used.
87      // If neither is set, then the request has no deadline.
88      //
89      // The format of the value is that of the 'Duration' type defined here:
90      // https://developers.google.com/protocol-buffers/docs/proto3#json
91      'timeout': string,
92
93      // Optional. The maximum allowed payload size for an individual request
94      // or object in a stream (client->server) in bytes. The size which is
95      // measured is the serialized, uncompressed payload in bytes. This
96      // applies both to streaming and non-streaming requests.
97      //
98      // The actual value used is the minimum of the value specified here and
99      // the value set by the application via the gRPC client API.
100      // If either one is not set, then the other will be used.
101      // If neither is set, then the built-in default is used.
102      //
103      // If a client attempts to send an object larger than this value, it
104      // will not be sent and the client will see an error.
105      // Note that 0 is a valid value, meaning that the request message must
106      // be empty.
107      'maxRequestMessageBytes': number,
108
109      // Optional. The maximum allowed payload size for an individual response
110      // or object in a stream (server->client) in bytes. The size which is
111      // measured is the serialized, uncompressed payload in bytes. This
112      // applies both to streaming and non-streaming requests.
113      //
114      // The actual value used is the minimum of the value specified here and
115      // the value set by the application via the gRPC client API.
116      // If either one is not set, then the other will be used.
117      // If neither is set, then the built-in default is used.
118      //
119      // If a server attempts to send an object larger than this value, it
120      // will not be sent, and the client will see an error.
121      // Note that 0 is a valid value, meaning that the response message must
122      // be empty.
123      'maxResponseMessageBytes': number
124    }
125  ]
126}
127```
128
129Note that new per-method parameters may be added in the future as new
130functionality is introduced.
131
132# Architecture
133
134A service config is associated with a server name.  The [name resolver](naming.md)
135plugin, when asked to resolve a particular server
136name, will return both the resolved addresses and the service config.
137
138TODO(roth): Design how the service config will be encoded in DNS.
139
140# APIs
141
142The service config is used in the following APIs:
143
144- In the resolver API, used by resolver plugins to return the service
145  config to the gRPC client.
146- In the gRPC client API, where users can query the channel to obtain
147  the service config associated with the channel (for debugging
148  purposes).
149- In the gRPC client API, where users can set the service config
150  explicitly.  This is intended for use in unit tests.
151