1 // Copyright 2015 The gRPC Authors 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 // This file defines the GRPCLB LoadBalancing protocol. 16 // 17 // The canonical version of this proto can be found at 18 // https://github.com/grpc/grpc-proto/blob/master/grpc/lb/v1/load_balancer.proto 19 syntax = "proto3"; 20 21 package grpc.lb.v1; 22 23 import "google/protobuf/duration.proto"; 24 import "google/protobuf/timestamp.proto"; 25 26 option go_package = "google.golang.org/grpc/balancer/grpclb/grpc_lb_v1"; 27 option java_multiple_files = true; 28 option java_outer_classname = "LoadBalancerProto"; 29 option java_package = "io.grpc.grpclb"; 30 31 service LoadBalancer { 32 // Bidirectional rpc to get a list of servers. 33 rpc BalanceLoad(stream LoadBalanceRequest) returns (stream LoadBalanceResponse); 34 } 35 36 message LoadBalanceRequest { 37 oneof load_balance_request_type { 38 // This message should be sent on the first request to the load balancer. 39 InitialLoadBalanceRequest initial_request = 1; 40 41 // The client stats should be periodically reported to the load balancer 42 // based on the duration defined in the InitialLoadBalanceResponse. 43 ClientStats client_stats = 2; 44 } 45 } 46 47 message InitialLoadBalanceRequest { 48 // The name of the load balanced service (e.g., service.googleapis.com). Its 49 // length should be less than 256 bytes. 50 // The name might include a port number. How to handle the port number is up 51 // to the balancer. 52 string name = 1; 53 } 54 55 // Contains the number of calls finished for a particular load balance token. 56 message ClientStatsPerToken { 57 // See Server.load_balance_token. 58 string load_balance_token = 1; 59 60 // The total number of RPCs that finished associated with the token. 61 int64 num_calls = 2; 62 } 63 64 // Contains client level statistics that are useful to load balancing. Each 65 // count except the timestamp should be reset to zero after reporting the stats. 66 message ClientStats { 67 // The timestamp of generating the report. 68 google.protobuf.Timestamp timestamp = 1; 69 70 // The total number of RPCs that started. 71 int64 num_calls_started = 2; 72 73 // The total number of RPCs that finished. 74 int64 num_calls_finished = 3; 75 76 // The total number of RPCs that failed to reach a server except dropped RPCs. 77 int64 num_calls_finished_with_client_failed_to_send = 6; 78 79 // The total number of RPCs that finished and are known to have been received 80 // by a server. 81 int64 num_calls_finished_known_received = 7; 82 83 // The list of dropped calls. 84 repeated ClientStatsPerToken calls_finished_with_drop = 8; 85 86 reserved 4, 5; 87 } 88 89 message LoadBalanceResponse { 90 oneof load_balance_response_type { 91 // This message should be sent on the first response to the client. 92 InitialLoadBalanceResponse initial_response = 1; 93 94 // Contains the list of servers selected by the load balancer. The client 95 // should send requests to these servers in the specified order. 96 ServerList server_list = 2; 97 } 98 } 99 100 message InitialLoadBalanceResponse { 101 // This is an application layer redirect that indicates the client should use 102 // the specified server for load balancing. When this field is non-empty in 103 // the response, the client should open a separate connection to the 104 // load_balancer_delegate and call the BalanceLoad method. Its length should 105 // be less than 64 bytes. 106 string load_balancer_delegate = 1; 107 108 // This interval defines how often the client should send the client stats 109 // to the load balancer. Stats should only be reported when the duration is 110 // positive. 111 google.protobuf.Duration client_stats_report_interval = 2; 112 } 113 114 message ServerList { 115 // Contains a list of servers selected by the load balancer. The list will 116 // be updated when server resolutions change or as needed to balance load 117 // across more servers. The client should consume the server list in order 118 // unless instructed otherwise via the client_config. 119 repeated Server servers = 1; 120 121 // Was google.protobuf.Duration expiration_interval. 122 reserved 3; 123 } 124 125 // Contains server information. When the drop field is not true, use the other 126 // fields. 127 message Server { 128 // A resolved address for the server, serialized in network-byte-order. It may 129 // either be an IPv4 or IPv6 address. 130 bytes ip_address = 1; 131 132 // A resolved port number for the server. 133 int32 port = 2; 134 135 // An opaque but printable token for load reporting. The client must include 136 // the token of the picked server into the initial metadata when it starts a 137 // call to that server. The token is used by the server to verify the request 138 // and to allow the server to report load to the gRPC LB system. The token is 139 // also used in client stats for reporting dropped calls. 140 // 141 // Its length can be variable but must be less than 50 bytes. 142 string load_balance_token = 3; 143 144 // Indicates whether this particular request should be dropped by the client. 145 // If the request is dropped, there will be a corresponding entry in 146 // ClientStats.calls_finished_with_drop. 147 bool drop = 4; 148 149 reserved 5; 150 } 151
