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