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