|
|
|
|
@ -8,134 +8,30 @@ parameters to be automatically used by all clients of their service. |
|
|
|
|
|
|
|
|
|
# Format |
|
|
|
|
|
|
|
|
|
The service config is a JSON string of the following form: |
|
|
|
|
|
|
|
|
|
``` |
|
|
|
|
{ |
|
|
|
|
// [deprecated] Load balancing policy name (case insensitive). |
|
|
|
|
// 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 set, the load balancing policy should be |
|
|
|
|
// supported by the client, otherwise the service config is considered |
|
|
|
|
// invalid. |
|
|
|
|
// 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. |
|
|
|
|
'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, |
|
|
|
|
} |
|
|
|
|
], |
|
|
|
|
|
|
|
|
|
// Optional. 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, |
|
|
|
|
|
|
|
|
|
// Optional. 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, |
|
|
|
|
|
|
|
|
|
// Optional. 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, |
|
|
|
|
|
|
|
|
|
// Optional. 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. |
|
|
|
|
The format of the service config is defined by the |
|
|
|
|
[`grpc.service_config.ServiceConfig` protocol buffer |
|
|
|
|
message](https://github.com/grpc/grpc-proto/blob/master/grpc/service_config/service_config.proto). |
|
|
|
|
Note that new fields 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 |
|
|
|
|
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. |
|
|
|
|
The name resolver returns the service config to the gRPC client in JSON form. |
|
|
|
|
Individual resolver implementations determine where and in what format the |
|
|
|
|
service config is stored. If the resolver implemention obtains the |
|
|
|
|
service config in protobuf form, it must convert it to JSON using the |
|
|
|
|
normal [protobuf to JSON translation |
|
|
|
|
rules](https://developers.google.com/protocol-buffers/docs/proto3#json). |
|
|
|
|
Alternatively, a resolver implementation may obtain the service config |
|
|
|
|
already in JSON form, in which case it may return it directly. |
|
|
|
|
|
|
|
|
|
For details of how the DNS resolver plugin supports service configs, see |
|
|
|
|
[gRFC A2: Service Config via |
|
|
|
|
DNS](https://github.com/grpc/proposal/blob/master/A2-service-configs-in-dns.md). |
|
|
|
|
|
|
|
|
|
# APIs |
|
|
|
|
|
|
|
|
|
@ -147,4 +43,6 @@ The service config is used in the following APIs: |
|
|
|
|
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. |
|
|
|
|
explicitly. This can be used to set the config in unit tests. It can |
|
|
|
|
also be used to set the default config that will be used if the |
|
|
|
|
resolver plugin does not return a service config. |
|
|
|
|
|
Mark D. Roth
5 years ago