From aa5bb8e422854f3dcb49191cb8e390efd498022a Mon Sep 17 00:00:00 2001 From: "Mark D. Roth" Date: Tue, 3 Mar 2020 09:37:33 -0800 Subject: [PATCH] service config doc update --- doc/service_config.md | 146 +++++++----------------------------------- 1 file changed, 22 insertions(+), 124 deletions(-) diff --git a/doc/service_config.md b/doc/service_config.md index 4cef4567d19..d6ff597d78c 100644 --- a/doc/service_config.md +++ b/doc/service_config.md @@ -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.