async-grpc-xds 0.1.0 → 0.2.0

data/lib/envoy/extensions/load_balancing_policies/common/v3/common_pb.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: envoy/extensions/load_balancing_policies/common/v3/common.proto
+
+require "google/protobuf"
+
+require "envoy/config/core/v3/base_pb"
+require "envoy/config/route/v3/route_components_pb"
+require "envoy/type/v3/percent_pb"
+require "google/protobuf/duration_pb"
+require "google/protobuf/struct_pb"
+require "google/protobuf/wrappers_pb"
+require "envoy/annotations/deprecation_pb"
+require "udpa/annotations/status_pb"
+require "validate/validate_pb"
+
+
+descriptor_data = "\n?envoy/extensions/load_balancing_policies/common/v3/common.proto\x12\x32\x65nvoy.extensions.load_balancing_policies.common.v3\x1a\x1f\x65nvoy/config/core/v3/base.proto\x1a,envoy/config/route/v3/route_components.proto\x1a\x1b\x65nvoy/type/v3/percent.proto\x1a\x1egoogle/protobuf/duration.proto\x1a\x1cgoogle/protobuf/struct.proto\x1a\x1egoogle/protobuf/wrappers.proto\x1a#envoy/annotations/deprecation.proto\x1a\x1dudpa/annotations/status.proto\x1a\x17validate/validate.proto\"\xa4\x07\n\x10LocalityLbConfig\x12v\n\x14zone_aware_lb_config\x18\x01 \x01(\x0b\x32V.envoy.extensions.load_balancing_policies.common.v3.LocalityLbConfig.ZoneAwareLbConfigH\x00\x12\x84\x01\n\x1blocality_weighted_lb_config\x18\x02 \x01(\x0b\x32].envoy.extensions.load_balancing_policies.common.v3.LocalityLbConfig.LocalityWeightedLbConfigH\x00\x1a\xd2\x04\n\x11ZoneAwareLbConfig\x12/\n\x0frouting_enabled\x18\x01 \x01(\x0b\x32\x16.envoy.type.v3.Percent\x12\x36\n\x10min_cluster_size\x18\x02 \x01(\x0b\x32\x1c.google.protobuf.UInt64Value\x12\x1d\n\x15\x66\x61il_traffic_on_panic\x18\x03 \x01(\x08\x12\x32\n\x1d\x66orce_locality_direct_routing\x18\x04 \x01(\x08\x42\x0b\x18\x01\x92\xc7\x86\xd8\x04\x03\x33.0\x12\x7f\n\x10\x66orce_local_zone\x18\x05 \x01(\x0b\x32\x65.envoy.extensions.load_balancing_policies.common.v3.LocalityLbConfig.ZoneAwareLbConfig.ForceLocalZone\x12|\n\x0elocality_basis\x18\x06 \x01(\x0e\x32\x64.envoy.extensions.load_balancing_policies.common.v3.LocalityLbConfig.ZoneAwareLbConfig.LocalityBasis\x1a@\n\x0e\x46orceLocalZone\x12.\n\x08min_size\x18\x01 \x01(\x0b\x32\x1c.google.protobuf.UInt32Value\"@\n\rLocalityBasis\x12\x15\n\x11HEALTHY_HOSTS_NUM\x10\x00\x12\x18\n\x14HEALTHY_HOSTS_WEIGHT\x10\x01\x1a\x1a\n\x18LocalityWeightedLbConfigB \n\x19locality_config_specifier\x12\x03\xf8\x42\x01\"\xb4\x01\n\x0fSlowStartConfig\x12\x34\n\x11slow_start_window\x18\x01 \x01(\x0b\x32\x19.google.protobuf.Duration\x12\x37\n\naggression\x18\x02 \x01(\x0b\x32#.envoy.config.core.v3.RuntimeDouble\x12\x32\n\x12min_weight_percent\x18\x03 \x01(\x0b\x32\x16.envoy.type.v3.Percent\"\xc5\x01\n\x19\x43onsistentHashingLbConfig\x12 \n\x18use_hostname_for_hashing\x18\x01 \x01(\x08\x12\x42\n\x13hash_balance_factor\x18\x02 \x01(\x0b\x32\x1c.google.protobuf.UInt32ValueB\x07\xfa\x42\x04*\x02(d\x12\x42\n\x0bhash_policy\x18\x03 \x03(\x0b\x32-.envoy.config.route.v3.RouteAction.HashPolicy\"\x99\x01\n\x16OrcaOobReportingConfig\x12\x1d\n\nport_value\x18\x01 \x01(\rB\t\xfa\x42\x06*\x04\x18\xff\xff\x03\x12\x1e\n\tauthority\x18\x02 \x01(\tB\x0b\xfa\x42\x08r\x06\xc0\x01\x02\xc8\x01\x00\x12@\n\x1ftransport_socket_match_criteria\x18\x03 \x01(\x0b\x32\x17.google.protobuf.StructB\xbd\x01\n@io.envoyproxy.envoy.extensions.load_balancing_policies.common.v3B\x0b\x43ommonProtoP\x01Zbgithub.com/envoyproxy/go-control-plane/envoy/extensions/load_balancing_policies/common/v3;commonv3\xba\x80\xc8\xd1\x06\x02\x10\x02\x62\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Envoy
+	module Extensions
+		module LoadBalancingPolicies
+			module Common
+				module V3
+					LocalityLbConfig = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("envoy.extensions.load_balancing_policies.common.v3.LocalityLbConfig").msgclass
+					LocalityLbConfig::ZoneAwareLbConfig = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("envoy.extensions.load_balancing_policies.common.v3.LocalityLbConfig.ZoneAwareLbConfig").msgclass
+					LocalityLbConfig::ZoneAwareLbConfig::ForceLocalZone = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("envoy.extensions.load_balancing_policies.common.v3.LocalityLbConfig.ZoneAwareLbConfig.ForceLocalZone").msgclass
+					LocalityLbConfig::ZoneAwareLbConfig::LocalityBasis = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("envoy.extensions.load_balancing_policies.common.v3.LocalityLbConfig.ZoneAwareLbConfig.LocalityBasis").enummodule
+					LocalityLbConfig::LocalityWeightedLbConfig = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("envoy.extensions.load_balancing_policies.common.v3.LocalityLbConfig.LocalityWeightedLbConfig").msgclass
+					SlowStartConfig = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("envoy.extensions.load_balancing_policies.common.v3.SlowStartConfig").msgclass
+					ConsistentHashingLbConfig = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("envoy.extensions.load_balancing_policies.common.v3.ConsistentHashingLbConfig").msgclass
+					OrcaOobReportingConfig = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("envoy.extensions.load_balancing_policies.common.v3.OrcaOobReportingConfig").msgclass
+				end
+			end
+		end
+	end
+end

data/lib/envoy/type/tracing/v3/custom_tag_pb.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: envoy/type/tracing/v3/custom_tag.proto
+
+require "google/protobuf"
+
+require "envoy/type/metadata/v3/metadata_pb"
+require "udpa/annotations/status_pb"
+require "udpa/annotations/versioning_pb"
+require "validate/validate_pb"
+
+
+descriptor_data = "\n&envoy/type/tracing/v3/custom_tag.proto\x12\x15\x65nvoy.type.tracing.v3\x1a%envoy/type/metadata/v3/metadata.proto\x1a\x1dudpa/annotations/status.proto\x1a!udpa/annotations/versioning.proto\x1a\x17validate/validate.proto\"\xe0\x06\n\tCustomTag\x12\x14\n\x03tag\x18\x01 \x01(\tB\x07\xfa\x42\x04r\x02\x10\x01\x12;\n\x07literal\x18\x02 \x01(\x0b\x32(.envoy.type.tracing.v3.CustomTag.LiteralH\x00\x12\x43\n\x0b\x65nvironment\x18\x03 \x01(\x0b\x32,.envoy.type.tracing.v3.CustomTag.EnvironmentH\x00\x12\x41\n\x0erequest_header\x18\x04 \x01(\x0b\x32\'.envoy.type.tracing.v3.CustomTag.HeaderH\x00\x12=\n\x08metadata\x18\x05 \x01(\x0b\x32).envoy.type.tracing.v3.CustomTag.MetadataH\x00\x12\x0f\n\x05value\x18\x06 \x01(\tH\x00\x1aQ\n\x07Literal\x12\x16\n\x05value\x18\x01 \x01(\tB\x07\xfa\x42\x04r\x02\x10\x01:.\x9a\xc5\x88\x1e)\n\'envoy.type.tracing.v2.CustomTag.Literal\x1ao\n\x0b\x45nvironment\x12\x15\n\x04name\x18\x01 \x01(\tB\x07\xfa\x42\x04r\x02\x10\x01\x12\x15\n\rdefault_value\x18\x02 \x01(\t:2\x9a\xc5\x88\x1e-\n+envoy.type.tracing.v2.CustomTag.Environment\x1ak\n\x06Header\x12\x1b\n\x04name\x18\x01 \x01(\tB\r\xfa\x42\nr\x08\x10\x01\xc0\x01\x01\xc8\x01\x00\x12\x15\n\rdefault_value\x18\x02 \x01(\t:-\x9a\xc5\x88\x1e(\n&envoy.type.tracing.v2.CustomTag.Header\x1a\xc1\x01\n\x08Metadata\x12\x32\n\x04kind\x18\x01 \x01(\x0b\x32$.envoy.type.metadata.v3.MetadataKind\x12\x39\n\x0cmetadata_key\x18\x02 \x01(\x0b\x32#.envoy.type.metadata.v3.MetadataKey\x12\x15\n\rdefault_value\x18\x03 \x01(\t:/\x9a\xc5\x88\x1e*\n(envoy.type.tracing.v2.CustomTag.Metadata:&\x9a\xc5\x88\x1e!\n\x1f\x65nvoy.type.tracing.v2.CustomTagB\x0b\n\x04type\x12\x03\xf8\x42\x01\x42\x87\x01\n#io.envoyproxy.envoy.type.tracing.v3B\x0e\x43ustomTagProtoP\x01ZFgithub.com/envoyproxy/go-control-plane/envoy/type/tracing/v3;tracingv3\xba\x80\xc8\xd1\x06\x02\x10\x02\x62\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Envoy
+	module Type
+		module Tracing
+			module V3
+				CustomTag = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("envoy.type.tracing.v3.CustomTag").msgclass
+				CustomTag::Literal = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("envoy.type.tracing.v3.CustomTag.Literal").msgclass
+				CustomTag::Environment = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("envoy.type.tracing.v3.CustomTag.Environment").msgclass
+				CustomTag::Header = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("envoy.type.tracing.v3.CustomTag.Header").msgclass
+				CustomTag::Metadata = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("envoy.type.tracing.v3.CustomTag.Metadata").msgclass
+			end
+		end
+	end
+end

data/lib/xds/data/orca/v3/orca_load_report_pb.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: xds/data/orca/v3/orca_load_report.proto
+
+require "google/protobuf"
+
+require "validate/validate_pb"
+
+
+descriptor_data = "\n\'xds/data/orca/v3/orca_load_report.proto\x12\x10xds.data.orca.v3\x1a\x17validate/validate.proto\"\x89\x05\n\x0eOrcaLoadReport\x12\'\n\x0f\x63pu_utilization\x18\x01 \x01(\x01\x42\x0e\xfa\x42\x0b\x12\t)\x00\x00\x00\x00\x00\x00\x00\x00\x12\x30\n\x0fmem_utilization\x18\x02 \x01(\x01\x42\x17\xfa\x42\x14\x12\x12\x19\x00\x00\x00\x00\x00\x00\xf0?)\x00\x00\x00\x00\x00\x00\x00\x00\x12\x0f\n\x03rps\x18\x03 \x01(\x04\x42\x02\x18\x01\x12G\n\x0crequest_cost\x18\x04 \x03(\x0b\x32\x31.xds.data.orca.v3.OrcaLoadReport.RequestCostEntry\x12\x64\n\x0butilization\x18\x05 \x03(\x0b\x32\x31.xds.data.orca.v3.OrcaLoadReport.UtilizationEntryB\x1c\xfa\x42\x19\x9a\x01\x16*\x14\x12\x12\x19\x00\x00\x00\x00\x00\x00\xf0?)\x00\x00\x00\x00\x00\x00\x00\x00\x12&\n\x0erps_fractional\x18\x06 \x01(\x01\x42\x0e\xfa\x42\x0b\x12\t)\x00\x00\x00\x00\x00\x00\x00\x00\x12\x1b\n\x03\x65ps\x18\x07 \x01(\x01\x42\x0e\xfa\x42\x0b\x12\t)\x00\x00\x00\x00\x00\x00\x00\x00\x12I\n\rnamed_metrics\x18\x08 \x03(\x0b\x32\x32.xds.data.orca.v3.OrcaLoadReport.NamedMetricsEntry\x12/\n\x17\x61pplication_utilization\x18\t \x01(\x01\x42\x0e\xfa\x42\x0b\x12\t)\x00\x00\x00\x00\x00\x00\x00\x00\x1a\x32\n\x10RequestCostEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\x01:\x02\x38\x01\x1a\x32\n\x10UtilizationEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\x01:\x02\x38\x01\x1a\x33\n\x11NamedMetricsEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\x01:\x02\x38\x01\x42]\n\x1b\x63om.github.xds.data.orca.v3B\x13OrcaLoadReportProtoP\x01Z\'github.com/cncf/xds/go/xds/data/orca/v3b\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Xds
+	module Data
+		module Orca
+			module V3
+				OrcaLoadReport = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("xds.data.orca.v3.OrcaLoadReport").msgclass
+			end
+		end
+	end
+end

data/lib/xds/service/orca/v3/open_rca_service.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "protocol/grpc/interface"
+require "xds/service/orca/v3/orca_pb"
+
+module Xds
+	module Service
+		module Orca
+			module V3
+				# Interface definition for the out-of-band ORCA load reporting service.
+				class OpenRcaService < Protocol::GRPC::Interface
+					rpc :StreamCoreMetrics,
+						request_class: OrcaLoadReportRequest,
+						response_class: Xds::Data::Orca::V3::OrcaLoadReport,
+						streaming: :server_streaming
+				end
+			end
+		end
+	end
+end

data/lib/xds/service/orca/v3/orca_pb.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: xds/service/orca/v3/orca.proto
+
+require "google/protobuf"
+
+require "xds/data/orca/v3/orca_load_report_pb"
+require "google/protobuf/duration_pb"
+
+
+descriptor_data = "\n\x1exds/service/orca/v3/orca.proto\x12\x13xds.service.orca.v3\x1a\'xds/data/orca/v3/orca_load_report.proto\x1a\x1egoogle/protobuf/duration.proto\"g\n\x15OrcaLoadReportRequest\x12\x32\n\x0freport_interval\x18\x01 \x01(\x0b\x32\x19.google.protobuf.Duration\x12\x1a\n\x12request_cost_names\x18\x02 \x03(\t2u\n\x0eOpenRcaService\x12\x63\n\x11StreamCoreMetrics\x12*.xds.service.orca.v3.OrcaLoadReportRequest\x1a .xds.data.orca.v3.OrcaLoadReport0\x01\x42Y\n\x1e\x63om.github.xds.service.orca.v3B\tOrcaProtoP\x01Z*github.com/cncf/xds/go/xds/service/orca/v3b\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Xds
+	module Service
+		module Orca
+			module V3
+				OrcaLoadReportRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("xds.service.orca.v3.OrcaLoadReportRequest").msgclass
+			end
+		end
+	end
+end

data/proto/envoy/config/common/mutation_rules/v3/mutation_rules.proto

@@ -0,0 +1,113 @@
+syntax = "proto3";
+
+package envoy.config.common.mutation_rules.v3;
+
+import "envoy/config/core/v3/base.proto";
+import "envoy/type/matcher/v3/regex.proto";
+import "envoy/type/matcher/v3/string.proto";
+
+import "google/protobuf/wrappers.proto";
+
+import "udpa/annotations/status.proto";
+import "validate/validate.proto";
+
+option java_package = "io.envoyproxy.envoy.config.common.mutation_rules.v3";
+option java_outer_classname = "MutationRulesProto";
+option java_multiple_files = true;
+option go_package = "github.com/envoyproxy/go-control-plane/envoy/config/common/mutation_rules/v3;mutation_rulesv3";
+option (udpa.annotations.file_status).package_version_status = ACTIVE;
+
+// [#protodoc-title: Header mutation rules]
+
+// The HeaderMutationRules structure specifies what headers may be
+// manipulated by a processing filter. This set of rules makes it
+// possible to control which modifications a filter may make.
+//
+// By default, an external processing server may add, modify, or remove
+// any header except for an "Envoy internal" header (which is typically
+// denoted by an x-envoy prefix) or specific headers that may affect
+// further filter processing:
+//
+// * ``host``
+// * ``:authority``
+// * ``:scheme``
+// * ``:method``
+//
+// Every attempt to add, change, append, or remove a header will be
+// tested against the rules here. Disallowed header mutations will be
+// ignored unless ``disallow_is_error`` is set to true.
+//
+// Attempts to remove headers are further constrained -- regardless of the
+// settings, system-defined headers (that start with ``:``) and the ``host``
+// header may never be removed.
+//
+// In addition, a counter will be incremented whenever a mutation is
+// rejected. In the ext_proc filter, that counter is named
+// ``rejected_header_mutations``.
+// [#next-free-field: 8]
+message HeaderMutationRules {
+  // By default, certain headers that could affect processing of subsequent
+  // filters or request routing cannot be modified. These headers are
+  // ``host``, ``:authority``, ``:scheme``, and ``:method``. Setting this parameter
+  // to true allows these headers to be modified as well.
+  google.protobuf.BoolValue allow_all_routing = 1;
+
+  // If true, allow modification of envoy internal headers. By default, these
+  // start with ``x-envoy`` but this may be overridden in the ``Bootstrap``
+  // configuration using the
+  // :ref:`header_prefix <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.header_prefix>`
+  // field. Default is false.
+  google.protobuf.BoolValue allow_envoy = 2;
+
+  // If true, prevent modification of any system header, defined as a header
+  // that starts with a ``:`` character, regardless of any other settings.
+  // A processing server may still override the ``:status`` of an HTTP response
+  // using an ``ImmediateResponse`` message. Default is false.
+  google.protobuf.BoolValue disallow_system = 3;
+
+  // If true, prevent modifications of all header values, regardless of any
+  // other settings. A processing server may still override the ``:status``
+  // of an HTTP response using an ``ImmediateResponse`` message. Default is false.
+  google.protobuf.BoolValue disallow_all = 4;
+
+  // If set, specifically allow any header that matches this regular
+  // expression. This overrides all other settings except for
+  // ``disallow_expression``.
+  type.matcher.v3.RegexMatcher allow_expression = 5;
+
+  // If set, specifically disallow any header that matches this regular
+  // expression regardless of any other settings.
+  type.matcher.v3.RegexMatcher disallow_expression = 6;
+
+  // If true, and if the rules in this list cause a header mutation to be
+  // disallowed, then the filter using this configuration will terminate the
+  // request with a 500 error. In addition, regardless of the setting of this
+  // parameter, any attempt to set, add, or modify a disallowed header will
+  // cause the ``rejected_header_mutations`` counter to be incremented.
+  // Default is false.
+  google.protobuf.BoolValue disallow_is_error = 7;
+}
+
+// The HeaderMutation structure specifies an action that may be taken on HTTP
+// headers.
+message HeaderMutation {
+  message RemoveOnMatch {
+    // A string matcher that will be applied to the header key. If the header key
+    // matches, the header will be removed.
+    type.matcher.v3.StringMatcher key_matcher = 1 [(validate.rules).message = {required: true}];
+  }
+
+  oneof action {
+    option (validate.required) = true;
+
+    // Remove the specified header if it exists.
+    string remove = 1
+        [(validate.rules).string = {well_known_regex: HTTP_HEADER_VALUE strict: false}];
+
+    // Append new header by the specified HeaderValueOption.
+    core.v3.HeaderValueOption append = 2;
+
+    // Remove the header if the key matches the specified string matcher.
+    RemoveOnMatch remove_on_match = 3;
+  }
+}

data/proto/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto

@@ -0,0 +1,96 @@
+syntax = "proto3";
+
+package envoy.extensions.load_balancing_policies.client_side_weighted_round_robin.v3;
+
+import "envoy/extensions/load_balancing_policies/common/v3/common.proto";
+
+import "google/protobuf/duration.proto";
+import "google/protobuf/wrappers.proto";
+
+import "udpa/annotations/status.proto";
+import "validate/validate.proto";
+
+option java_package = "io.envoyproxy.envoy.extensions.load_balancing_policies.client_side_weighted_round_robin.v3";
+option java_outer_classname = "ClientSideWeightedRoundRobinProto";
+option java_multiple_files = true;
+option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3;client_side_weighted_round_robinv3";
+option (udpa.annotations.file_status).package_version_status = ACTIVE;
+
+// [#protodoc-title: Client-Side Weighted Round Robin Load Balancing Policy]
+// [#extension: envoy.load_balancing_policies.client_side_weighted_round_robin]
+
+// Configuration for the client_side_weighted_round_robin LB policy.
+//
+// This policy differs from the built-in ROUND_ROBIN policy in terms of
+// how the endpoint weights are determined. In the ROUND_ROBIN policy,
+// the endpoint weights are sent by the control plane via EDS. However,
+// in this policy, the endpoint weights are instead determined via qps (queries
+// per second), eps (errors per second), and utilization metrics sent by the
+// endpoint using the Open Request Cost Aggregation (ORCA) protocol. Utilization
+// is determined by using the ORCA application_utilization field, if set, or
+// else falling back to the cpu_utilization field. All queries count toward qps,
+// regardless of result. Only failed queries count toward eps. A config
+// parameter error_utilization_penalty controls the penalty to adjust endpoint
+// weights using eps and qps. The weight of a given endpoint is computed as:
+// ``qps / (utilization + eps/qps * error_utilization_penalty)``.
+//
+// Note that Envoy will forward the ORCA response headers/trailers from the upstream
+// cluster to the downstream client. This means that if the downstream client is also
+// configured to use ``client_side_weighted_round_robin`` it will load balance against
+// Envoy based on upstream weights. This can happen when Envoy is used as a reverse proxy.
+// To avoid this issue you can configure the :ref:`header_mutation filter  <envoy_v3_api_msg_extensions.filters.http.header_mutation.v3.HeaderMutation>` to remove
+// the ORCA payload from the response headers/trailers.
+//
+// See the :ref:`load balancing architecture
+// overview<arch_overview_load_balancing_types>` for more information.
+//
+// [#next-free-field: 10]
+message ClientSideWeightedRoundRobin {
+  // Whether to enable out-of-band utilization reporting collection from
+  // the endpoints. By default, per-request utilization reporting is used.
+  google.protobuf.BoolValue enable_oob_load_report = 1;
+
+  // Load reporting interval to request from the server. Note that the
+  // server may not provide reports as frequently as the client requests.
+  // Used only when enable_oob_load_report is true. Default is 10 seconds.
+  google.protobuf.Duration oob_reporting_period = 2;
+
+  // A given endpoint must report load metrics continuously for at least
+  // this long before the endpoint weight will be used. This avoids
+  // churn when the set of endpoint addresses changes. Takes effect
+  // both immediately after we establish a connection to an endpoint and
+  // after weight_expiration_period has caused us to stop using the most
+  // recent load metrics. Default is 10 seconds.
+  google.protobuf.Duration blackout_period = 3;
+
+  // If a given endpoint has not reported load metrics in this long,
+  // then we stop using the reported weight. This ensures that we do
+  // not continue to use very stale weights. Once we stop using a stale
+  // value, if we later start seeing fresh reports again, the
+  // blackout_period applies. Defaults to 3 minutes.
+  google.protobuf.Duration weight_expiration_period = 4;
+
+  // How often endpoint weights are recalculated. Values less than 100ms are
+  // capped at 100ms. Default is 1 second.
+  google.protobuf.Duration weight_update_period = 5;
+
+  // The multiplier used to adjust endpoint weights with the error rate
+  // calculated as eps/qps. Configuration is rejected if this value is negative.
+  // Default is 1.0.
+  google.protobuf.FloatValue error_utilization_penalty = 6 [(validate.rules).float = {gte: 0.0}];
+
+  // By default, endpoint weight is computed based on the :ref:`application_utilization <envoy_v3_api_field_.xds.data.orca.v3.OrcaLoadReport.application_utilization>` field reported by the endpoint.
+  // If that field is not set, then utilization will instead be computed by taking the max of the values of the metrics specified here.
+  // For map fields in the ORCA proto, the string will be of the form ``<map_field_name>.<map_key>``. For example, the string ``named_metrics.foo`` will mean to look for the key ``foo`` in the ORCA :ref:`named_metrics <envoy_v3_api_field_.xds.data.orca.v3.OrcaLoadReport.named_metrics>` field.
+  // If none of the specified metrics are present in the load report, then :ref:`cpu_utilization <envoy_v3_api_field_.xds.data.orca.v3.OrcaLoadReport.cpu_utilization>` is used instead.
+  repeated string metric_names_for_computing_utilization = 7;
+
+  // Configuration for slow start mode.
+  // If this configuration is not set, slow start will not be not enabled.
+  common.v3.SlowStartConfig slow_start_config = 8;
+
+  // Optional overrides for the OOB reporting connection (alternative port,
+  // ``:authority``, transport socket selection). Honored only when
+  // ``enable_oob_load_report`` is true.
+  common.v3.OrcaOobReportingConfig oob_reporting_config = 9;
+}

data/proto/envoy/extensions/load_balancing_policies/common/v3/common.proto

@@ -0,0 +1,188 @@
+syntax = "proto3";
+
+package envoy.extensions.load_balancing_policies.common.v3;
+
+import "envoy/config/core/v3/base.proto";
+import "envoy/config/route/v3/route_components.proto";
+import "envoy/type/v3/percent.proto";
+
+import "google/protobuf/duration.proto";
+import "google/protobuf/struct.proto";
+import "google/protobuf/wrappers.proto";
+
+import "envoy/annotations/deprecation.proto";
+import "udpa/annotations/status.proto";
+import "validate/validate.proto";
+
+option java_package = "io.envoyproxy.envoy.extensions.load_balancing_policies.common.v3";
+option java_outer_classname = "CommonProto";
+option java_multiple_files = true;
+option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/load_balancing_policies/common/v3;commonv3";
+option (udpa.annotations.file_status).package_version_status = ACTIVE;
+
+// [#protodoc-title: Common configuration for two or more load balancing policy extensions]
+
+message LocalityLbConfig {
+  // Configuration for :ref:`zone aware routing
+  // <arch_overview_load_balancing_zone_aware_routing>`.
+  // [#next-free-field: 7]
+  message ZoneAwareLbConfig {
+    // Basis for computing per-locality percentages in zone-aware routing.
+    enum LocalityBasis {
+      // Use the number of healthy hosts in each locality.
+      HEALTHY_HOSTS_NUM = 0;
+
+      // Use the weights of healthy hosts in each locality.
+      HEALTHY_HOSTS_WEIGHT = 1;
+    }
+
+    // Configures Envoy to always route requests to the local zone regardless of the
+    // upstream zone structure. In Envoy's default configuration, traffic is distributed proportionally
+    // across all upstream hosts while trying to maximize local routing when possible. The approach
+    // with force_local_zone aims to be more predictable and if there are upstream hosts in the local
+    // zone, they will receive all traffic.
+    // * :ref:`runtime values <config_cluster_manager_cluster_runtime_zone_routing>`.
+    // * :ref:`Zone aware routing support <arch_overview_load_balancing_zone_aware_routing>`.
+    message ForceLocalZone {
+      // Configures the minimum number of upstream hosts in the local zone required when force_local_zone
+      // is enabled. If the number of upstream hosts in the local zone is less than the specified value,
+      // Envoy will fall back to the default proportional-based distribution across localities.
+      // If not specified, the default is 1.
+      // * :ref:`runtime values <config_cluster_manager_cluster_runtime_zone_routing>`.
+      // * :ref:`Zone aware routing support <arch_overview_load_balancing_zone_aware_routing>`.
+      google.protobuf.UInt32Value min_size = 1;
+    }
+
+    // Configures percentage of requests that will be considered for zone aware routing
+    // if zone aware routing is configured. If not specified, the default is 100%.
+    // * :ref:`runtime values <config_cluster_manager_cluster_runtime_zone_routing>`.
+    // * :ref:`Zone aware routing support <arch_overview_load_balancing_zone_aware_routing>`.
+    type.v3.Percent routing_enabled = 1;
+
+    // Configures minimum upstream cluster size required for zone aware routing
+    // If upstream cluster size is less than specified, zone aware routing is not performed
+    // even if zone aware routing is configured. If not specified, the default is 6.
+    // * :ref:`runtime values <config_cluster_manager_cluster_runtime_zone_routing>`.
+    // * :ref:`Zone aware routing support <arch_overview_load_balancing_zone_aware_routing>`.
+    google.protobuf.UInt64Value min_cluster_size = 2;
+
+    // If set to true, Envoy will not consider any hosts when the cluster is in :ref:`panic
+    // mode<arch_overview_load_balancing_panic_threshold>`. Instead, the cluster will fail all
+    // requests as if all hosts are unhealthy. This can help avoid potentially overwhelming a
+    // failing service.
+    bool fail_traffic_on_panic = 3;
+
+    // If set to true, Envoy will force LocalityDirect routing if a local locality exists.
+    bool force_locality_direct_routing = 4
+        [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
+
+    ForceLocalZone force_local_zone = 5;
+
+    // Determines how locality percentages are computed:
+    // - HEALTHY_HOSTS_NUM: proportional to the count of healthy hosts.
+    // - HEALTHY_HOSTS_WEIGHT: proportional to the weights of healthy hosts.
+    // Default value is HEALTHY_HOSTS_NUM if unset.
+    LocalityBasis locality_basis = 6;
+  }
+
+  // Configuration for :ref:`locality weighted load balancing
+  // <arch_overview_load_balancing_locality_weighted_lb>`
+  message LocalityWeightedLbConfig {
+  }
+
+  oneof locality_config_specifier {
+    option (validate.required) = true;
+
+    // Configuration for local zone aware load balancing.
+    ZoneAwareLbConfig zone_aware_lb_config = 1;
+
+    // Enable locality weighted load balancing.
+    LocalityWeightedLbConfig locality_weighted_lb_config = 2;
+  }
+}
+
+// Configuration for :ref:`slow start mode <arch_overview_load_balancing_slow_start>`.
+message SlowStartConfig {
+  // Represents the size of slow start window.
+  // If set, the newly created host remains in slow start mode starting from its creation time
+  // for the duration of slow start window.
+  google.protobuf.Duration slow_start_window = 1;
+
+  // This parameter controls the speed of traffic increase over the slow start window. Defaults to 1.0,
+  // so that endpoint would get linearly increasing amount of traffic.
+  // When increasing the value for this parameter, the speed of traffic ramp-up increases non-linearly.
+  // The value of aggression parameter should be greater than 0.0.
+  // By tuning the parameter, is possible to achieve polynomial or exponential shape of ramp-up curve.
+  //
+  // During slow start window, effective weight of an endpoint would be scaled with time factor and aggression:
+  // ``new_weight = weight * max(min_weight_percent, time_factor ^ (1 / aggression))``,
+  // where ``time_factor=(time_since_start_seconds / slow_start_time_seconds)``.
+  //
+  // As time progresses, more and more traffic would be sent to endpoint, which is in slow start window.
+  // Once host exits slow start, time_factor and aggression no longer affect its weight.
+  config.core.v3.RuntimeDouble aggression = 2;
+
+  // Configures the minimum percentage of origin weight that avoids too small new weight,
+  // which may cause endpoints in slow start mode receive no traffic in slow start window.
+  // If not specified, the default is 10%.
+  type.v3.Percent min_weight_percent = 3;
+}
+
+// Common Configuration for all consistent hashing load balancers (MaglevLb, RingHashLb, etc.)
+message ConsistentHashingLbConfig {
+  // If set to ``true``, the cluster will use hostname instead of the resolved
+  // address as the key to consistently hash to an upstream host. Only valid for StrictDNS clusters with hostnames which resolve to a single IP address.
+  bool use_hostname_for_hashing = 1;
+
+  // Configures percentage of average cluster load to bound per upstream host. For example, with a value of 150
+  // no upstream host will get a load more than 1.5 times the average load of all the hosts in the cluster.
+  // If not specified, the load is not bounded for any upstream host. Typical value for this parameter is between 120 and 200.
+  // Minimum is 100.
+  //
+  // Applies to both Ring Hash and Maglev load balancers.
+  //
+  // This is implemented based on the method described in the paper https://arxiv.org/abs/1608.01350. For the specified
+  // ``hash_balance_factor``, requests to any upstream host are capped at ``hash_balance_factor/100`` times the average number of requests
+  // across the cluster. When a request arrives for an upstream host that is currently serving at its max capacity, linear probing
+  // is used to identify an eligible host. Further, the linear probe is implemented using a random jump in hosts ring/table to identify
+  // the eligible host (this technique is as described in the paper https://arxiv.org/abs/1908.08762 - the random jump avoids the
+  // cascading overflow effect when choosing the next host in the ring/table).
+  //
+  // If weights are specified on the hosts, they are respected.
+  //
+  // This is an O(N) algorithm, unlike other load balancers. Using a lower ``hash_balance_factor`` results in more hosts
+  // being probed, so use a higher value if you require better performance.
+  google.protobuf.UInt32Value hash_balance_factor = 2 [(validate.rules).uint32 = {gte: 100}];
+
+  //  Specifies a list of hash policies to use for ring hash load balancing. If ``hash_policy`` is
+  // set, then
+  // :ref:`route level hash policy <envoy_v3_api_field_config.route.v3.RouteAction.hash_policy>`
+  // will be ignored.
+  repeated config.route.v3.RouteAction.HashPolicy hash_policy = 3;
+}
+
+// Connection overrides for the ORCA out-of-band (OOB) reporting stream, used by
+// load balancing policies that consume ORCA load reports (e.g.
+// :ref:`client_side_weighted_round_robin
+// <envoy_v3_api_msg_extensions.load_balancing_policies.client_side_weighted_round_robin.v3.ClientSideWeightedRoundRobin>`).
+// Whether and when OOB reporting runs is controlled by the embedding policy.
+message OrcaOobReportingConfig {
+  // Optional alternative port for the OOB reporting connection, for example an
+  // ORCA reporting sidecar listening on a dedicated port. If 0 or unset, the
+  // port of the host's ORCA reporting address is used. Ignored for non-IP
+  // (pipe/UDS) host addresses.
+  uint32 port_value = 1 [(validate.rules).uint32 = {lte: 65535}];
+
+  // Value of the ``:authority`` header on the OOB gRPC stream. If empty, the
+  // endpoint hostname is used, then the dialed address, then the cluster name.
+  string authority = 2
+      [(validate.rules).string = {well_known_regex: HTTP_HEADER_VALUE strict: false}];
+
+  // Optional key/value pairs used to select a transport socket from the
+  // cluster's :ref:`transport_socket_matches
+  // <envoy_v3_api_field_config.cluster.v3.Cluster.transport_socket_matches>`
+  // for the OOB connection. If unset, or if no match is found, the cluster's
+  // default transport socket is used. ALPN ``h2`` is always forced on the OOB
+  // connection regardless of this setting.
+  google.protobuf.Struct transport_socket_match_criteria = 3;
+}