// Copyright 2025 Envoy Project 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.

syntax = "proto3";

package envoy.extensions.router.cluster_specifiers.matcher.v3;

import "xds/type/matcher/v3/matcher.proto";

import "udpa/annotations/status.proto";
import "validate/validate.proto";

option java_package = "io.envoyproxy.envoy.extensions.router.cluster_specifiers.matcher.v3";
option java_outer_classname = "MatcherProto";
option java_multiple_files = true;
option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/router/cluster_specifiers/matcher/v3;matcherv3";
option (udpa.annotations.file_status).package_version_status = ACTIVE;

// [#protodoc-title: Matcher Based Cluster Specifier]
// [#extension: envoy.router.cluster_specifier_plugin.matcher]

message ClusterAction {
  // Indicates the upstream cluster to which the request should be routed
  // to.
  string cluster = 1 [(validate.rules).string = {min_len: 1}];
}

message MatcherClusterSpecifier {
  // The matcher for cluster selection after the route has been selected. This is used when the
  // route has multiple clusters (like multiple clusters for different users) and the matcher
  // is used to select the cluster to use for the request.
  //
  // The match tree to use for grouping incoming requests into buckets.
  //
  // Example:
  //
  // .. validated-code-block:: yaml
  //   :type-name: xds.type.matcher.v3.Matcher
  //
  //   matcher_list:
  //     matchers:
  //     - predicate:
  //         single_predicate:
  //           input:
  //             typed_config:
  //               '@type': type.googleapis.com/envoy.type.matcher.v3.HttpRequestHeaderMatchInput
  //               header_name: env
  //           value_match:
  //             exact: staging
  //       on_match:
  //         action:
  //           typed_config:
  //             '@type': type.googleapis.com/envoy.extensions.router.cluster_specifiers.matcher.v3.ClusterAction
  //             cluster: "staging-cluster"
  //
  //     - predicate:
  //         single_predicate:
  //           input:
  //             typed_config:
  //               '@type': type.googleapis.com/envoy.type.matcher.v3.HttpRequestHeaderMatchInput
  //               header_name: env
  //           value_match:
  //             exact: prod
  //       on_match:
  //         action:
  //           typed_config:
  //             '@type': type.googleapis.com/envoy.extensions.router.cluster_specifiers.matcher.v3.ClusterAction
  //             cluster: "prod-cluster"
  //
  //   # Catch-all with a default cluster.
  //   on_no_match:
  //     action:
  //       typed_config:
  //         '@type': type.googleapis.com/envoy.extensions.router.cluster_specifiers.matcher.v3.ClusterAction
  //         cluster: "default-cluster"
  //
  xds.type.matcher.v3.Matcher cluster_matcher = 1 [(validate.rules).message = {required: true}];
}
