xref: /aosp_15_r20/external/sdk-platform-java/gapic-generator-java/src/main/proto/service_config.proto (revision 882aa7c72c3cd3b66e72a261bdd69b93f7de7670)

// Copyright 2016 The gRPC Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

// A ServiceConfig is supplied when a service is deployed. It mostly contains
// parameters for how clients that connect to the service should behave (for
// example, the load balancing policy to use to pick between service replicas).
//
// The configuration options provided here act as overrides to automatically
// chosen option values. Service owners should be conservative in specifying
// options as the system is likely to choose better values for these options in
// the vast majority of cases. In other words, please specify a configuration
// option only if you really have to, and avoid copy-paste inclusion of configs.
//
// Note that gRPC uses the service config in JSON form, not in protobuf
// form.  This proto definition is intended to help document the schema but
// will not actually be used directly by gRPC.

syntax = "proto3";

package grpc.service_config;

import "google/protobuf/duration.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/wrappers.proto";
import "google/rpc/code.proto";

option java_package = "io.grpc.serviceconfig";
option java_multiple_files = true;
option java_outer_classname = "ServiceConfigProto";

// Configuration for a method.
message MethodConfig {
  // The names of the methods to which this configuration applies.
  // - MethodConfig without names (empty list) will be skipped.
  // - Each name entry must be unique across the entire ServiceConfig.
  // - If the 'method' field is empty, this MethodConfig specifies the defaults
  //   for all methods for the specified service.
  // - If the 'service' field is empty, the 'method' field must be empty, and
  //   this MethodConfig specifies the default for all methods (it's the default
  //   config).
  //
  // When determining which MethodConfig to use for a given RPC, the most
  // specific match wins. For example, let's say that the service config
  // contains the following MethodConfig entries:
  //
  // method_config { name { } ... }
  // method_config { name { service: "MyService" } ... }
  // method_config { name { service: "MyService" method: "Foo" } ... }
  //
  // MyService/Foo will use the third entry, because it exactly matches the
  // service and method name. MyService/Bar will use the second entry, because
  // it provides the default for all methods of MyService. AnotherService/Baz
  // will use the first entry, because it doesn't match the other two.
  //
  // In JSON representation, value "", value `null`, and not present are the
  // same. The following are the same Name:
  // - { "service": "s" }
  // - { "service": "s", "method": null }
  // - { "service": "s", "method": "" }
  message Name {
    string service = 1;  // Required. Includes proto package name.
    string method = 2;
  }
  repeated Name name = 1;

  // 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.
  google.protobuf.BoolValue wait_for_ready = 2;

  // 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.
  google.protobuf.Duration timeout = 3;

  // 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 payload after per-message compression (but before stream
  // compression) 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 a ClientError.
  // Note that 0 is a valid value, meaning that the request message
  // must be empty.
  google.protobuf.UInt32Value max_request_message_bytes = 4;

  // 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 payload after per-message compression (but before stream
  // compression) 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 a ServerError will be sent to the client instead.
  // Note that 0 is a valid value, meaning that the response message
  // must be empty.
  google.protobuf.UInt32Value max_response_message_bytes = 5;

  // The retry policy for outgoing RPCs.
  message RetryPolicy {
    // The maximum number of RPC attempts, including the original attempt.
    //
    // This field is required and must be greater than 1.
    // Any value greater than 5 will be treated as if it were 5.
    uint32 max_attempts = 1;

    // Exponential backoff parameters. The initial retry attempt will occur at
    // random(0, initial_backoff). In general, the nth attempt will occur at
    // random(0,
    //   min(initial_backoff*backoff_multiplier**(n-1), max_backoff)).
    // Required. Must be greater than zero.
    google.protobuf.Duration initial_backoff = 2;
    // Required. Must be greater than zero.
    google.protobuf.Duration max_backoff = 3;
    float backoff_multiplier = 4;  // Required. Must be greater than zero.

    // The set of status codes which may be retried.
    //
    // This field is required and must be non-empty.
    repeated google.rpc.Code retryable_status_codes = 5;
  }

  // The hedging policy for outgoing RPCs. Hedged RPCs may execute more than
  // once on the server, so only idempotent methods should specify a hedging
  // policy.
  message HedgingPolicy {
    // The hedging policy will send up to max_requests RPCs.
    // This number represents the total number of all attempts, including
    // the original attempt.
    //
    // This field is required and must be greater than 1.
    // Any value greater than 5 will be treated as if it were 5.
    uint32 max_attempts = 1;

    // The first RPC will be sent immediately, but the max_requests-1 subsequent
    // hedged RPCs will be sent at intervals of every hedging_delay. Set this
    // to 0 to immediately send all max_requests RPCs.
    google.protobuf.Duration hedging_delay = 2;

    // The set of status codes which indicate other hedged RPCs may still
    // succeed. If a non-fatal status code is returned by the server, hedged
    // RPCs will continue. Otherwise, outstanding requests will be canceled and
    // the error returned to the client application layer.
    //
    // This field is optional.
    repeated google.rpc.Code non_fatal_status_codes = 3;
  }

  // Only one of retry_policy or hedging_policy may be set. If neither is set,
  // RPCs will not be retried or hedged.
  oneof retry_or_hedging_policy {
    RetryPolicy retry_policy = 6;
    HedgingPolicy hedging_policy = 7;
  }
}

// Configuration for pick_first LB policy.
message PickFirstConfig {}

// Configuration for round_robin LB policy.
message RoundRobinConfig {}

// Configuration for grpclb LB policy.
message GrpcLbConfig {
  // Optional.  What LB policy to use for routing between the backend
  // addresses.  If unset, defaults to round_robin.
  // Currently, the only supported values are round_robin and pick_first.
  // Note that this will be used both in balancer mode and in fallback mode.
  // Multiple LB policies can be specified; clients will iterate through
  // the list in order and stop at the first policy that they support.
  repeated LoadBalancingConfig child_policy = 1;
  // Optional.  If specified, overrides the name of the service to be sent to
  // the balancer.
  string service_name = 2;
}

// Configuration for priority LB policy.
message PriorityLoadBalancingPolicyConfig {
  // A map of name to child policy configuration.
  // The names are used to allow the priority policy to update
  // existing child policies instead of creating new ones every
  // time it receives a config update.
  message Child {
    repeated LoadBalancingConfig config = 1;

    // If true, will ignore reresolution requests from this child.
    bool ignore_reresolution_requests = 2;
  }
  map<string, Child> children = 1;

  // A list of child names in decreasing priority order
  // (i.e., first element is the highest priority).
  repeated string priorities = 2;
}

// Configuration for weighted_target LB policy.
message WeightedTargetLoadBalancingPolicyConfig {
  message Target {
    uint32 weight = 1;
    repeated LoadBalancingConfig child_policy = 2;
  }
  map<string, Target> targets = 1;
}

// Configuration for xds_cluster_manager_experimental LB policy.
message XdsClusterManagerLoadBalancingPolicyConfig {
  message Child {
    repeated LoadBalancingConfig child_policy = 1;
  }
  map<string, Child> children = 1;
}

// Configuration for the cds LB policy.
message CdsConfig {
  string cluster = 1;  // Required.
}

// Represents an xDS server.
message XdsServer {
  string server_uri = 1 [json_name = "server_uri"];  // Required.

  message ChannelCredentials {
    string type = 1;  // Required.
    google.protobuf.Struct config = 2;  // Optional JSON config.
  }
  // A list of channel creds to use.  The first supported type will be used.
  repeated ChannelCredentials channel_creds = 2 [json_name = "channel_creds"];

  // A repeated list of server features.
  repeated google.protobuf.Value server_features = 3
      [json_name = "server_features"];
}

// Configuration for xds_cluster_resolver LB policy.
message XdsClusterResolverLoadBalancingPolicyConfig {
  // Describes a discovery mechanism instance.
  // For EDS or LOGICAL_DNS clusters, there will be exactly one
  // DiscoveryMechanism, which will describe the cluster of the parent
  // CDS policy.
  // For aggregate clusters, there will be one DiscoveryMechanism for each
  // underlying cluster.
  message DiscoveryMechanism {
    // Cluster name.
    string cluster = 1;

    // LRS server to send load reports to.
    // If not present, load reporting will be disabled.
    // If set to the empty string, load reporting will be sent to the same
    // server that we obtained CDS data from.
    // DEPRECATED: Use new lrs_load_reporting_server field instead.
    google.protobuf.StringValue lrs_load_reporting_server_name = 2
        [deprecated=true];

    // LRS server to send load reports to.
    // If not present, load reporting will be disabled.
    // Supercedes lrs_load_reporting_server_name field.
    XdsServer lrs_load_reporting_server = 7;

    // Maximum number of outstanding requests can be made to the upstream
    // cluster.  Default is 1024.
    google.protobuf.UInt32Value max_concurrent_requests = 3;

    enum Type {
      UNKNOWN = 0;
      EDS = 1;
      LOGICAL_DNS = 2;
    };
    Type type = 4;

    // For type EDS only.
    // EDS service name, as returned in CDS.
    // May be unset if not specified in CDS.
    string eds_service_name = 5;

    // For type LOGICAL_DNS only.
    // DNS name to resolve in "host:port" form.
    string dns_hostname = 6;
  }

  // Ordered list of discovery mechanisms.
  // Must have at least one element.
  // Results from each discovery mechanism are concatenated together in
  // successive priorities.
  repeated DiscoveryMechanism discovery_mechanisms = 1;

  // xDS LB policy.
  // This represents the xDS LB policy, which does not necessarily map
  // one-to-one to a gRPC LB policy.  Currently, the following policies
  // are supported:
  // - "ROUND_ROBIN" (config is empty)
  // - "RING_HASH" (config is a RingHashLoadBalancingConfig)
  repeated LoadBalancingConfig xds_lb_policy = 2;
}

// Configuration for xds_cluster_impl LB policy.
message XdsClusterImplLoadBalancingPolicyConfig {
  // Cluster name.  Required.
  string cluster = 1;

  // EDS service name.
  // Not set if cluster is not an EDS cluster or if it does not
  // specify an EDS service name.
  string eds_service_name = 2;

  // Server to send load reports to.
  // If unset, no load reporting is done.
  // If set to empty string, load reporting will be sent to the same
  // server as we are getting xds data from.
  // DEPRECATED: Use new lrs_load_reporting_server field instead.
  google.protobuf.StringValue lrs_load_reporting_server_name = 3
      [deprecated=true];

  // LRS server to send load reports to.
  // If not present, load reporting will be disabled.
  // Supercedes lrs_load_reporting_server_name field.
  XdsServer lrs_load_reporting_server = 7;

  // Maximum number of outstanding requests can be made to the upstream cluster.
  // Default is 1024.
  google.protobuf.UInt32Value max_concurrent_requests = 4;

  // Drop configuration.
  message DropCategory {
    string category = 1;
    uint32 requests_per_million = 2;
  }
  repeated DropCategory drop_categories = 5;

  // Child policy.
  repeated LoadBalancingConfig child_policy = 6;
}

// Configuration for eds LB policy.
message EdsLoadBalancingPolicyConfig {
  // Cluster name.  Required.
  string cluster = 1;

  // EDS service name, as returned in CDS.
  // May be unset if not specified in CDS.
  string eds_service_name = 2;

  // Server to send load reports to.
  // If unset, no load reporting is done.
  // If set to empty string, load reporting will be sent to the same
  // server as we are getting xds data from.
  google.protobuf.StringValue lrs_load_reporting_server_name = 3;

  // Locality-picking policy.
  // This policy's config is expected to be in the format used
  // by the weighted_target policy.  Note that the config should include
  // an empty value for the "targets" field; that empty value will be
  // replaced by one that is dynamically generated based on the EDS data.
  // Optional; defaults to "weighted_target".
  repeated LoadBalancingConfig locality_picking_policy = 4;

  // Endpoint-picking policy.
  // This will be configured as the policy for each child in the
  // locality-policy's config.
  // Optional; defaults to "round_robin".
  repeated LoadBalancingConfig endpoint_picking_policy = 5;
}

// Configuration for ring_hash LB policy.
message RingHashLoadBalancingConfig {
  uint64 min_ring_size = 1;
  uint64 max_ring_size = 2;
}

// Configuration for lrs LB policy.
message LrsLoadBalancingPolicyConfig {
  // Cluster name.  Required.
  string cluster_name = 1;

  // EDS service name, as returned in CDS.
  // May be unset if not specified in CDS.
  string eds_service_name = 2;

  // Server to send load reports to.  Required.
  // If set to empty string, load reporting will be sent to the same
  // server as we are getting xds data from.
  string lrs_load_reporting_server_name = 3;

  // The locality for which this policy will report load.  Required.
  message Locality {
    string region = 1;
    string zone = 2;
    string subzone = 3;
  }
  Locality locality = 4;

  // Endpoint-picking policy.
  repeated LoadBalancingConfig child_policy = 5;
}

// Configuration for xds LB policy.
message XdsConfig {
  // Name of balancer to connect to.
  string balancer_name = 1 [deprecated = true];
  // Optional.  What LB policy to use for intra-locality routing.
  // If unset, will use whatever algorithm is specified by the balancer.
  // Multiple LB policies can be specified; clients will iterate through
  // the list in order and stop at the first policy that they support.
  repeated LoadBalancingConfig child_policy = 2;
  // Optional.  What LB policy to use in fallback mode.  If not
  // specified, defaults to round_robin.
  // Multiple LB policies can be specified; clients will iterate through
  // the list in order and stop at the first policy that they support.
  repeated LoadBalancingConfig fallback_policy = 3;
  // Optional.  Name to use in EDS query.  If not present, defaults to
  // the server name from the target URI.
  string eds_service_name = 4;
  // LRS server to send load reports to.
  // If not present, load reporting will be disabled.
  // If set to the empty string, load reporting will be sent to the same
  // server that we obtained CDS data from.
  google.protobuf.StringValue lrs_load_reporting_server_name = 5;
}

// Selects LB policy and provides corresponding configuration.
//
// In general, all instances of this field should be repeated. Clients will
// iterate through the list in order and stop at the first policy that they
// support.  This allows the service config to specify custom policies that may
// not be known to all clients.
//
// - If the config for the first supported policy is invalid, the whole service
//   config is invalid.
// - If the list doesn't contain any supported policy, the whole service config
//   is invalid.
message LoadBalancingConfig {
  // Exactly one LB policy may be configured.
  oneof policy {
    // For each new LB policy supported by gRPC, a new field must be added
    // here.  The field's name must be the LB policy name and its type is a
    // message that provides whatever configuration parameters are needed
    // by the LB policy.  The configuration message will be passed to the
    // LB policy when it is instantiated on the client.
    //
    // If the LB policy does not require any configuration parameters, the
    // message for that LB policy may be empty.
    //
    // Note that if an LB policy contains another nested LB policy
    // (e.g., a gslb policy picks the cluster and then delegates to
    // a round_robin policy to pick the backend within that cluster), its
    // configuration message may include a nested instance of the
    // LoadBalancingConfig message to configure the nested LB policy.

    PickFirstConfig pick_first = 4 [json_name = "pick_first"];

    RoundRobinConfig round_robin = 1 [json_name = "round_robin"];

    // gRPC lookaside load balancing.
    // This will eventually be deprecated by the new xDS-based local
    // balancing policy.
    GrpcLbConfig grpclb = 3;

    // REMAINING POLICIES ARE EXPERIMENTAL -- DO NOT USE

    PriorityLoadBalancingPolicyConfig priority_experimental = 9
        [json_name = "priority_experimental"];
    WeightedTargetLoadBalancingPolicyConfig weighted_target_experimental = 10
        [json_name = "weighted_target_experimental"];

    // xDS-based load balancing.
    XdsClusterManagerLoadBalancingPolicyConfig xds_cluster_manager_experimental
        = 14 [json_name = "xds_cluster_manager_experimental"];
    CdsConfig cds_experimental = 6 [json_name = "cds_experimental"];
    XdsClusterResolverLoadBalancingPolicyConfig
        xds_cluster_resolver_experimental = 11
        [json_name = "xds_cluster_resolver_experimental"];
    XdsClusterImplLoadBalancingPolicyConfig xds_cluster_impl_experimental = 12
        [json_name = "xds_cluster_impl_experimental"];
    RingHashLoadBalancingConfig ring_hash_experimental = 13
        [json_name = "ring_hash_experimental"];

    // Deprecated xDS-related policies.
    LrsLoadBalancingPolicyConfig lrs_experimental = 8
        [json_name = "lrs_experimental", deprecated = true];
    EdsLoadBalancingPolicyConfig eds_experimental = 7
        [json_name = "eds_experimental", deprecated = true];
    XdsConfig xds = 2 [deprecated = true];
    XdsConfig xds_experimental = 5 [json_name = "xds_experimental",
                                    deprecated = true];

    // Next available ID: 14
  }
}

// A ServiceConfig represents information about a service but is not specific to
// any name resolver.
message ServiceConfig {
  // Load balancing policy.
  //
  // Note that load_balancing_policy is deprecated in favor of
  // load_balancing_config; the former will be used only if the latter
  // is unset.
  //
  // If no LB policy is configured here, then the default is pick_first.
  // If the policy name is set via the client API, that value overrides
  // the value specified here.
  //
  // If the deprecated load_balancing_policy field is used, 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 policy is configured here.  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.
  enum LoadBalancingPolicy {
    UNSPECIFIED = 0;
    ROUND_ROBIN = 1;
  }
  LoadBalancingPolicy load_balancing_policy = 1 [deprecated = true];
  // Multiple LB policies can be specified; clients will iterate through
  // the list in order and stop at the first policy that they support. If none
  // are supported, the service config is considered invalid.
  repeated LoadBalancingConfig load_balancing_config = 4;

  // Per-method configuration.
  repeated MethodConfig method_config = 2;

  // If a RetryThrottlingPolicy is provided, gRPC will automatically throttle
  // retry attempts and hedged RPCs when the client's ratio of failures to
  // successes exceeds a threshold.
  //
  // For each server name, the gRPC client will maintain a token_count which is
  // initially set to max_tokens. Every outgoing RPC (regardless of service or
  // method invoked) will change token_count as follows:
  //
  //   - Every failed RPC will decrement the token_count by 1.
  //   - Every successful RPC will increment the token_count by token_ratio.
  //
  // If token_count is less than or equal to max_tokens / 2, then RPCs will not
  // be retried and hedged RPCs will not be sent.
  message RetryThrottlingPolicy {
    // The number of tokens starts at max_tokens. The token_count will always be
    // between 0 and max_tokens.
    //
    // This field is required and must be greater than zero.
    uint32 max_tokens = 1;

    // The amount of tokens to add on each successful RPC. Typically this will
    // be some number between 0 and 1, e.g., 0.1.
    //
    // This field is required and must be greater than zero. Up to 3 decimal
    // places are supported.
    float token_ratio = 2;
  }
  RetryThrottlingPolicy retry_throttling = 3;

  message HealthCheckConfig {
    // Service name to use in the health-checking request.
    google.protobuf.StringValue service_name = 1;
  }
  HealthCheckConfig health_check_config = 5;

  // next available tag: 6
}