...

Text file src/github.com/datawire/ambassador/v2/api/envoy/config/route/v4alpha/route_components.proto

Documentation: github.com/datawire/ambassador/v2/api/envoy/config/route/v4alpha

     1syntax = "proto3";
     2
     3package envoy.config.route.v4alpha;
     4
     5import "envoy/config/core/v4alpha/base.proto";
     6import "envoy/config/core/v4alpha/extension.proto";
     7import "envoy/config/core/v4alpha/proxy_protocol.proto";
     8import "envoy/type/matcher/v4alpha/regex.proto";
     9import "envoy/type/matcher/v4alpha/string.proto";
    10import "envoy/type/metadata/v3/metadata.proto";
    11import "envoy/type/tracing/v3/custom_tag.proto";
    12import "envoy/type/v3/percent.proto";
    13import "envoy/type/v3/range.proto";
    14
    15import "google/protobuf/any.proto";
    16import "google/protobuf/duration.proto";
    17import "google/protobuf/struct.proto";
    18import "google/protobuf/wrappers.proto";
    19
    20import "envoy/annotations/deprecation.proto";
    21import "udpa/annotations/status.proto";
    22import "udpa/annotations/versioning.proto";
    23import "validate/validate.proto";
    24
    25option java_package = "io.envoyproxy.envoy.config.route.v4alpha";
    26option java_outer_classname = "RouteComponentsProto";
    27option java_multiple_files = true;
    28option (udpa.annotations.file_status).package_version_status = NEXT_MAJOR_VERSION_CANDIDATE;
    29
    30// [#protodoc-title: HTTP route components]
    31// * Routing :ref:`architecture overview <arch_overview_http_routing>`
    32// * HTTP :ref:`router filter <config_http_filters_router>`
    33
    34// The top level element in the routing configuration is a virtual host. Each virtual host has
    35// a logical name as well as a set of domains that get routed to it based on the incoming request's
    36// host header. This allows a single listener to service multiple top level domain path trees. Once
    37// a virtual host is selected based on the domain, the routes are processed in order to see which
    38// upstream cluster to route to or whether to perform a redirect.
    39// [#next-free-field: 21]
    40message VirtualHost {
    41  option (udpa.annotations.versioning).previous_message_type = "envoy.config.route.v3.VirtualHost";
    42
    43  enum TlsRequirementType {
    44    // No TLS requirement for the virtual host.
    45    NONE = 0;
    46
    47    // External requests must use TLS. If a request is external and it is not
    48    // using TLS, a 301 redirect will be sent telling the client to use HTTPS.
    49    EXTERNAL_ONLY = 1;
    50
    51    // All requests must use TLS. If a request is not using TLS, a 301 redirect
    52    // will be sent telling the client to use HTTPS.
    53    ALL = 2;
    54  }
    55
    56  reserved 9, 12;
    57
    58  reserved "per_filter_config";
    59
    60  // The logical name of the virtual host. This is used when emitting certain
    61  // statistics but is not relevant for routing.
    62  string name = 1 [(validate.rules).string = {min_len: 1}];
    63
    64  // A list of domains (host/authority header) that will be matched to this
    65  // virtual host. Wildcard hosts are supported in the suffix or prefix form.
    66  //
    67  // Domain search order:
    68  //  1. Exact domain names: ``www.foo.com``.
    69  //  2. Suffix domain wildcards: ``*.foo.com`` or ``*-bar.foo.com``.
    70  //  3. Prefix domain wildcards: ``foo.*`` or ``foo-*``.
    71  //  4. Special wildcard ``*`` matching any domain.
    72  //
    73  // .. note::
    74  //
    75  //   The wildcard will not match the empty string.
    76  //   e.g. ``*-bar.foo.com`` will match ``baz-bar.foo.com`` but not ``-bar.foo.com``.
    77  //   The longest wildcards match first.
    78  //   Only a single virtual host in the entire route configuration can match on ``*``. A domain
    79  //   must be unique across all virtual hosts or the config will fail to load.
    80  //
    81  // Domains cannot contain control characters. This is validated by the well_known_regex HTTP_HEADER_VALUE.
    82  repeated string domains = 2 [(validate.rules).repeated = {
    83    min_items: 1
    84    items {string {well_known_regex: HTTP_HEADER_VALUE strict: false}}
    85  }];
    86
    87  // The list of routes that will be matched, in order, for incoming requests.
    88  // The first route that matches will be used.
    89  repeated Route routes = 3;
    90
    91  // Specifies the type of TLS enforcement the virtual host expects. If this option is not
    92  // specified, there is no TLS requirement for the virtual host.
    93  TlsRequirementType require_tls = 4 [(validate.rules).enum = {defined_only: true}];
    94
    95  // A list of virtual clusters defined for this virtual host. Virtual clusters
    96  // are used for additional statistics gathering.
    97  repeated VirtualCluster virtual_clusters = 5;
    98
    99  // Specifies a set of rate limit configurations that will be applied to the
   100  // virtual host.
   101  repeated RateLimit rate_limits = 6;
   102
   103  // Specifies a list of HTTP headers that should be added to each request
   104  // handled by this virtual host. Headers specified at this level are applied
   105  // after headers from enclosed :ref:`envoy_api_msg_config.route.v4alpha.Route` and before headers from the
   106  // enclosing :ref:`envoy_api_msg_config.route.v4alpha.RouteConfiguration`. For more information, including
   107  // details on header value syntax, see the documentation on :ref:`custom request headers
   108  // <config_http_conn_man_headers_custom_request_headers>`.
   109  repeated core.v4alpha.HeaderValueOption request_headers_to_add = 7
   110      [(validate.rules).repeated = {max_items: 1000}];
   111
   112  // Specifies a list of HTTP headers that should be removed from each request
   113  // handled by this virtual host.
   114  repeated string request_headers_to_remove = 13 [(validate.rules).repeated = {
   115    items {string {min_len: 1 well_known_regex: HTTP_HEADER_NAME strict: false}}
   116  }];
   117
   118  // Specifies a list of HTTP headers that should be added to each response
   119  // handled by this virtual host. Headers specified at this level are applied
   120  // after headers from enclosed :ref:`envoy_api_msg_config.route.v4alpha.Route` and before headers from the
   121  // enclosing :ref:`envoy_api_msg_config.route.v4alpha.RouteConfiguration`. For more information, including
   122  // details on header value syntax, see the documentation on :ref:`custom request headers
   123  // <config_http_conn_man_headers_custom_request_headers>`.
   124  repeated core.v4alpha.HeaderValueOption response_headers_to_add = 10
   125      [(validate.rules).repeated = {max_items: 1000}];
   126
   127  // Specifies a list of HTTP headers that should be removed from each response
   128  // handled by this virtual host.
   129  repeated string response_headers_to_remove = 11 [(validate.rules).repeated = {
   130    items {string {min_len: 1 well_known_regex: HTTP_HEADER_NAME strict: false}}
   131  }];
   132
   133  // Indicates that the virtual host has a CORS policy.
   134  CorsPolicy cors = 8;
   135
   136  // The per_filter_config field can be used to provide virtual host-specific
   137  // configurations for filters. The key should match the filter name, such as
   138  // *envoy.filters.http.buffer* for the HTTP buffer filter. Use of this field is filter
   139  // specific; see the :ref:`HTTP filter documentation <config_http_filters>`
   140  // for if and how it is utilized.
   141  map<string, google.protobuf.Any> typed_per_filter_config = 15;
   142
   143  // Decides whether the :ref:`x-envoy-attempt-count
   144  // <config_http_filters_router_x-envoy-attempt-count>` header should be included
   145  // in the upstream request. Setting this option will cause it to override any existing header
   146  // value, so in the case of two Envoys on the request path with this option enabled, the upstream
   147  // will see the attempt count as perceived by the second Envoy. Defaults to false.
   148  // This header is unaffected by the
   149  // :ref:`suppress_envoy_headers
   150  // <envoy_api_field_extensions.filters.http.router.v4alpha.Router.suppress_envoy_headers>` flag.
   151  //
   152  // [#next-major-version: rename to include_attempt_count_in_request.]
   153  bool include_request_attempt_count = 14;
   154
   155  // Decides whether the :ref:`x-envoy-attempt-count
   156  // <config_http_filters_router_x-envoy-attempt-count>` header should be included
   157  // in the downstream response. Setting this option will cause the router to override any existing header
   158  // value, so in the case of two Envoys on the request path with this option enabled, the downstream
   159  // will see the attempt count as perceived by the Envoy closest upstream from itself. Defaults to false.
   160  // This header is unaffected by the
   161  // :ref:`suppress_envoy_headers
   162  // <envoy_api_field_extensions.filters.http.router.v4alpha.Router.suppress_envoy_headers>` flag.
   163  bool include_attempt_count_in_response = 19;
   164
   165  // Indicates the retry policy for all routes in this virtual host. Note that setting a
   166  // route level entry will take precedence over this config and it'll be treated
   167  // independently (e.g.: values are not inherited).
   168  RetryPolicy retry_policy = 16;
   169
   170  // [#not-implemented-hide:]
   171  // Specifies the configuration for retry policy extension. Note that setting a route level entry
   172  // will take precedence over this config and it'll be treated independently (e.g.: values are not
   173  // inherited). :ref:`Retry policy <envoy_api_field_config.route.v4alpha.VirtualHost.retry_policy>` should not be
   174  // set if this field is used.
   175  google.protobuf.Any retry_policy_typed_config = 20;
   176
   177  // Indicates the hedge policy for all routes in this virtual host. Note that setting a
   178  // route level entry will take precedence over this config and it'll be treated
   179  // independently (e.g.: values are not inherited).
   180  HedgePolicy hedge_policy = 17;
   181
   182  // The maximum bytes which will be buffered for retries and shadowing.
   183  // If set and a route-specific limit is not set, the bytes actually buffered will be the minimum
   184  // value of this and the listener per_connection_buffer_limit_bytes.
   185  google.protobuf.UInt32Value per_request_buffer_limit_bytes = 18;
   186}
   187
   188// A filter-defined action type.
   189message FilterAction {
   190  option (udpa.annotations.versioning).previous_message_type = "envoy.config.route.v3.FilterAction";
   191
   192  google.protobuf.Any action = 1;
   193}
   194
   195// A route is both a specification of how to match a request as well as an indication of what to do
   196// next (e.g., redirect, forward, rewrite, etc.).
   197//
   198// .. attention::
   199//
   200//   Envoy supports routing on HTTP method via :ref:`header matching
   201//   <envoy_api_msg_config.route.v4alpha.HeaderMatcher>`.
   202// [#next-free-field: 18]
   203message Route {
   204  option (udpa.annotations.versioning).previous_message_type = "envoy.config.route.v3.Route";
   205
   206  reserved 6, 8;
   207
   208  reserved "per_filter_config";
   209
   210  // Name for the route.
   211  string name = 14;
   212
   213  // Route matching parameters.
   214  RouteMatch match = 1 [(validate.rules).message = {required: true}];
   215
   216  oneof action {
   217    option (validate.required) = true;
   218
   219    // Route request to some upstream cluster.
   220    RouteAction route = 2;
   221
   222    // Return a redirect.
   223    RedirectAction redirect = 3;
   224
   225    // Return an arbitrary HTTP response directly, without proxying.
   226    DirectResponseAction direct_response = 7;
   227
   228    // [#not-implemented-hide:]
   229    // If true, a filter will define the action (e.g., it could dynamically generate the
   230    // RouteAction).
   231    // [#comment: TODO(samflattery): Remove cleanup in route_fuzz_test.cc when
   232    // implemented]
   233    FilterAction filter_action = 17;
   234  }
   235
   236  // The Metadata field can be used to provide additional information
   237  // about the route. It can be used for configuration, stats, and logging.
   238  // The metadata should go under the filter namespace that will need it.
   239  // For instance, if the metadata is intended for the Router filter,
   240  // the filter name should be specified as *envoy.filters.http.router*.
   241  core.v4alpha.Metadata metadata = 4;
   242
   243  // Decorator for the matched route.
   244  Decorator decorator = 5;
   245
   246  // The typed_per_filter_config field can be used to provide route-specific
   247  // configurations for filters. The key should match the filter name, such as
   248  // *envoy.filters.http.buffer* for the HTTP buffer filter. Use of this field is filter
   249  // specific; see the :ref:`HTTP filter documentation <config_http_filters>` for
   250  // if and how it is utilized.
   251  map<string, google.protobuf.Any> typed_per_filter_config = 13;
   252
   253  // Specifies a set of headers that will be added to requests matching this
   254  // route. Headers specified at this level are applied before headers from the
   255  // enclosing :ref:`envoy_api_msg_config.route.v4alpha.VirtualHost` and
   256  // :ref:`envoy_api_msg_config.route.v4alpha.RouteConfiguration`. For more information, including details on
   257  // header value syntax, see the documentation on :ref:`custom request headers
   258  // <config_http_conn_man_headers_custom_request_headers>`.
   259  repeated core.v4alpha.HeaderValueOption request_headers_to_add = 9
   260      [(validate.rules).repeated = {max_items: 1000}];
   261
   262  // Specifies a list of HTTP headers that should be removed from each request
   263  // matching this route.
   264  repeated string request_headers_to_remove = 12 [(validate.rules).repeated = {
   265    items {string {min_len: 1 well_known_regex: HTTP_HEADER_NAME strict: false}}
   266  }];
   267
   268  // Specifies a set of headers that will be added to responses to requests
   269  // matching this route. Headers specified at this level are applied before
   270  // headers from the enclosing :ref:`envoy_api_msg_config.route.v4alpha.VirtualHost` and
   271  // :ref:`envoy_api_msg_config.route.v4alpha.RouteConfiguration`. For more information, including
   272  // details on header value syntax, see the documentation on
   273  // :ref:`custom request headers <config_http_conn_man_headers_custom_request_headers>`.
   274  repeated core.v4alpha.HeaderValueOption response_headers_to_add = 10
   275      [(validate.rules).repeated = {max_items: 1000}];
   276
   277  // Specifies a list of HTTP headers that should be removed from each response
   278  // to requests matching this route.
   279  repeated string response_headers_to_remove = 11 [(validate.rules).repeated = {
   280    items {string {min_len: 1 well_known_regex: HTTP_HEADER_NAME strict: false}}
   281  }];
   282
   283  // Presence of the object defines whether the connection manager's tracing configuration
   284  // is overridden by this route specific instance.
   285  Tracing tracing = 15;
   286
   287  // The maximum bytes which will be buffered for retries and shadowing.
   288  // If set, the bytes actually buffered will be the minimum value of this and the
   289  // listener per_connection_buffer_limit_bytes.
   290  google.protobuf.UInt32Value per_request_buffer_limit_bytes = 16;
   291}
   292
   293// Compared to the :ref:`cluster <envoy_api_field_config.route.v4alpha.RouteAction.cluster>` field that specifies a
   294// single upstream cluster as the target of a request, the :ref:`weighted_clusters
   295// <envoy_api_field_config.route.v4alpha.RouteAction.weighted_clusters>` option allows for specification of
   296// multiple upstream clusters along with weights that indicate the percentage of
   297// traffic to be forwarded to each cluster. The router selects an upstream cluster based on the
   298// weights.
   299message WeightedCluster {
   300  option (udpa.annotations.versioning).previous_message_type =
   301      "envoy.config.route.v3.WeightedCluster";
   302
   303  // [#next-free-field: 11]
   304  message ClusterWeight {
   305    option (udpa.annotations.versioning).previous_message_type =
   306        "envoy.config.route.v3.WeightedCluster.ClusterWeight";
   307
   308    reserved 7, 8;
   309
   310    reserved "per_filter_config";
   311
   312    // Name of the upstream cluster. The cluster must exist in the
   313    // :ref:`cluster manager configuration <config_cluster_manager>`.
   314    string name = 1 [(validate.rules).string = {min_len: 1}];
   315
   316    // An integer between 0 and :ref:`total_weight
   317    // <envoy_api_field_config.route.v4alpha.WeightedCluster.total_weight>`. When a request matches the route,
   318    // the choice of an upstream cluster is determined by its weight. The sum of weights across all
   319    // entries in the clusters array must add up to the total_weight, which defaults to 100.
   320    google.protobuf.UInt32Value weight = 2;
   321
   322    // Optional endpoint metadata match criteria used by the subset load balancer. Only endpoints in
   323    // the upstream cluster with metadata matching what is set in this field will be considered for
   324    // load balancing. Note that this will be merged with what's provided in
   325    // :ref:`RouteAction.metadata_match <envoy_api_field_config.route.v4alpha.RouteAction.metadata_match>`, with
   326    // values here taking precedence. The filter name should be specified as *envoy.lb*.
   327    core.v4alpha.Metadata metadata_match = 3;
   328
   329    // Specifies a list of headers to be added to requests when this cluster is selected
   330    // through the enclosing :ref:`envoy_api_msg_config.route.v4alpha.RouteAction`.
   331    // Headers specified at this level are applied before headers from the enclosing
   332    // :ref:`envoy_api_msg_config.route.v4alpha.Route`, :ref:`envoy_api_msg_config.route.v4alpha.VirtualHost`, and
   333    // :ref:`envoy_api_msg_config.route.v4alpha.RouteConfiguration`. For more information, including details on
   334    // header value syntax, see the documentation on :ref:`custom request headers
   335    // <config_http_conn_man_headers_custom_request_headers>`.
   336    repeated core.v4alpha.HeaderValueOption request_headers_to_add = 4
   337        [(validate.rules).repeated = {max_items: 1000}];
   338
   339    // Specifies a list of HTTP headers that should be removed from each request when
   340    // this cluster is selected through the enclosing :ref:`envoy_api_msg_config.route.v4alpha.RouteAction`.
   341    repeated string request_headers_to_remove = 9 [(validate.rules).repeated = {
   342      items {string {well_known_regex: HTTP_HEADER_NAME strict: false}}
   343    }];
   344
   345    // Specifies a list of headers to be added to responses when this cluster is selected
   346    // through the enclosing :ref:`envoy_api_msg_config.route.v4alpha.RouteAction`.
   347    // Headers specified at this level are applied before headers from the enclosing
   348    // :ref:`envoy_api_msg_config.route.v4alpha.Route`, :ref:`envoy_api_msg_config.route.v4alpha.VirtualHost`, and
   349    // :ref:`envoy_api_msg_config.route.v4alpha.RouteConfiguration`. For more information, including details on
   350    // header value syntax, see the documentation on :ref:`custom request headers
   351    // <config_http_conn_man_headers_custom_request_headers>`.
   352    repeated core.v4alpha.HeaderValueOption response_headers_to_add = 5
   353        [(validate.rules).repeated = {max_items: 1000}];
   354
   355    // Specifies a list of headers to be removed from responses when this cluster is selected
   356    // through the enclosing :ref:`envoy_api_msg_config.route.v4alpha.RouteAction`.
   357    repeated string response_headers_to_remove = 6 [(validate.rules).repeated = {
   358      items {string {well_known_regex: HTTP_HEADER_NAME strict: false}}
   359    }];
   360
   361    // The per_filter_config field can be used to provide weighted cluster-specific
   362    // configurations for filters. The key should match the filter name, such as
   363    // *envoy.filters.http.buffer* for the HTTP buffer filter. Use of this field is filter
   364    // specific; see the :ref:`HTTP filter documentation <config_http_filters>`
   365    // for if and how it is utilized.
   366    map<string, google.protobuf.Any> typed_per_filter_config = 10;
   367  }
   368
   369  // Specifies one or more upstream clusters associated with the route.
   370  repeated ClusterWeight clusters = 1 [(validate.rules).repeated = {min_items: 1}];
   371
   372  // Specifies the total weight across all clusters. The sum of all cluster weights must equal this
   373  // value, which must be greater than 0. Defaults to 100.
   374  google.protobuf.UInt32Value total_weight = 3 [(validate.rules).uint32 = {gte: 1}];
   375
   376  // Specifies the runtime key prefix that should be used to construct the
   377  // runtime keys associated with each cluster. When the *runtime_key_prefix* is
   378  // specified, the router will look for weights associated with each upstream
   379  // cluster under the key *runtime_key_prefix* + "." + *cluster[i].name* where
   380  // *cluster[i]* denotes an entry in the clusters array field. If the runtime
   381  // key for the cluster does not exist, the value specified in the
   382  // configuration file will be used as the default weight. See the :ref:`runtime documentation
   383  // <operations_runtime>` for how key names map to the underlying implementation.
   384  string runtime_key_prefix = 2;
   385}
   386
   387// [#next-free-field: 13]
   388message RouteMatch {
   389  option (udpa.annotations.versioning).previous_message_type = "envoy.config.route.v3.RouteMatch";
   390
   391  message GrpcRouteMatchOptions {
   392    option (udpa.annotations.versioning).previous_message_type =
   393        "envoy.config.route.v3.RouteMatch.GrpcRouteMatchOptions";
   394  }
   395
   396  message TlsContextMatchOptions {
   397    option (udpa.annotations.versioning).previous_message_type =
   398        "envoy.config.route.v3.RouteMatch.TlsContextMatchOptions";
   399
   400    // If specified, the route will match against whether or not a certificate is presented.
   401    // If not specified, certificate presentation status (true or false) will not be considered when route matching.
   402    google.protobuf.BoolValue presented = 1;
   403
   404    // If specified, the route will match against whether or not a certificate is validated.
   405    // If not specified, certificate validation status (true or false) will not be considered when route matching.
   406    google.protobuf.BoolValue validated = 2;
   407  }
   408
   409  // An extensible message for matching CONNECT requests.
   410  message ConnectMatcher {
   411    option (udpa.annotations.versioning).previous_message_type =
   412        "envoy.config.route.v3.RouteMatch.ConnectMatcher";
   413  }
   414
   415  reserved 5, 3;
   416
   417  reserved "regex";
   418
   419  oneof path_specifier {
   420    option (validate.required) = true;
   421
   422    // If specified, the route is a prefix rule meaning that the prefix must
   423    // match the beginning of the *:path* header.
   424    string prefix = 1;
   425
   426    // If specified, the route is an exact path rule meaning that the path must
   427    // exactly match the *:path* header once the query string is removed.
   428    string path = 2;
   429
   430    // If specified, the route is a regular expression rule meaning that the
   431    // regex must match the *:path* header once the query string is removed. The entire path
   432    // (without the query string) must match the regex. The rule will not match if only a
   433    // subsequence of the *:path* header matches the regex.
   434    //
   435    // [#next-major-version: In the v3 API we should redo how path specification works such
   436    // that we utilize StringMatcher, and additionally have consistent options around whether we
   437    // strip query strings, do a case sensitive match, etc. In the interim it will be too disruptive
   438    // to deprecate the existing options. We should even consider whether we want to do away with
   439    // path_specifier entirely and just rely on a set of header matchers which can already match
   440    // on :path, etc. The issue with that is it is unclear how to generically deal with query string
   441    // stripping. This needs more thought.]
   442    type.matcher.v4alpha.RegexMatcher safe_regex = 10 [(validate.rules).message = {required: true}];
   443
   444    // If this is used as the matcher, the matcher will only match CONNECT requests.
   445    // Note that this will not match HTTP/2 upgrade-style CONNECT requests
   446    // (WebSocket and the like) as they are normalized in Envoy as HTTP/1.1 style
   447    // upgrades.
   448    // This is the only way to match CONNECT requests for HTTP/1.1. For HTTP/2,
   449    // where Extended CONNECT requests may have a path, the path matchers will work if
   450    // there is a path present.
   451    // Note that CONNECT support is currently considered alpha in Envoy.
   452    // [#comment:TODO(htuch): Replace the above comment with an alpha tag.
   453    ConnectMatcher connect_matcher = 12;
   454  }
   455
   456  // Indicates that prefix/path matching should be case sensitive. The default
   457  // is true.
   458  google.protobuf.BoolValue case_sensitive = 4;
   459
   460  // Indicates that the route should additionally match on a runtime key. Every time the route
   461  // is considered for a match, it must also fall under the percentage of matches indicated by
   462  // this field. For some fraction N/D, a random number in the range [0,D) is selected. If the
   463  // number is <= the value of the numerator N, or if the key is not present, the default
   464  // value, the router continues to evaluate the remaining match criteria. A runtime_fraction
   465  // route configuration can be used to roll out route changes in a gradual manner without full
   466  // code/config deploys. Refer to the :ref:`traffic shifting
   467  // <config_http_conn_man_route_table_traffic_splitting_shift>` docs for additional documentation.
   468  //
   469  // .. note::
   470  //
   471  //    Parsing this field is implemented such that the runtime key's data may be represented
   472  //    as a FractionalPercent proto represented as JSON/YAML and may also be represented as an
   473  //    integer with the assumption that the value is an integral percentage out of 100. For
   474  //    instance, a runtime key lookup returning the value "42" would parse as a FractionalPercent
   475  //    whose numerator is 42 and denominator is HUNDRED. This preserves legacy semantics.
   476  core.v4alpha.RuntimeFractionalPercent runtime_fraction = 9;
   477
   478  // Specifies a set of headers that the route should match on. The router will
   479  // check the request’s headers against all the specified headers in the route
   480  // config. A match will happen if all the headers in the route are present in
   481  // the request with the same values (or based on presence if the value field
   482  // is not in the config).
   483  repeated HeaderMatcher headers = 6;
   484
   485  // Specifies a set of URL query parameters on which the route should
   486  // match. The router will check the query string from the *path* header
   487  // against all the specified query parameters. If the number of specified
   488  // query parameters is nonzero, they all must match the *path* header's
   489  // query string for a match to occur.
   490  repeated QueryParameterMatcher query_parameters = 7;
   491
   492  // If specified, only gRPC requests will be matched. The router will check
   493  // that the content-type header has a application/grpc or one of the various
   494  // application/grpc+ values.
   495  GrpcRouteMatchOptions grpc = 8;
   496
   497  // If specified, the client tls context will be matched against the defined
   498  // match options.
   499  //
   500  // [#next-major-version: unify with RBAC]
   501  TlsContextMatchOptions tls_context = 11;
   502}
   503
   504// [#next-free-field: 12]
   505message CorsPolicy {
   506  option (udpa.annotations.versioning).previous_message_type = "envoy.config.route.v3.CorsPolicy";
   507
   508  reserved 1, 8, 7;
   509
   510  reserved "allow_origin", "allow_origin_regex", "enabled";
   511
   512  // Specifies string patterns that match allowed origins. An origin is allowed if any of the
   513  // string matchers match.
   514  repeated type.matcher.v4alpha.StringMatcher allow_origin_string_match = 11;
   515
   516  // Specifies the content for the *access-control-allow-methods* header.
   517  string allow_methods = 2;
   518
   519  // Specifies the content for the *access-control-allow-headers* header.
   520  string allow_headers = 3;
   521
   522  // Specifies the content for the *access-control-expose-headers* header.
   523  string expose_headers = 4;
   524
   525  // Specifies the content for the *access-control-max-age* header.
   526  string max_age = 5;
   527
   528  // Specifies whether the resource allows credentials.
   529  google.protobuf.BoolValue allow_credentials = 6;
   530
   531  oneof enabled_specifier {
   532    // Specifies the % of requests for which the CORS filter is enabled.
   533    //
   534    // If neither ``enabled``, ``filter_enabled``, nor ``shadow_enabled`` are specified, the CORS
   535    // filter will be enabled for 100% of the requests.
   536    //
   537    // If :ref:`runtime_key <envoy_api_field_config.core.v4alpha.RuntimeFractionalPercent.runtime_key>` is
   538    // specified, Envoy will lookup the runtime key to get the percentage of requests to filter.
   539    core.v4alpha.RuntimeFractionalPercent filter_enabled = 9;
   540  }
   541
   542  // Specifies the % of requests for which the CORS policies will be evaluated and tracked, but not
   543  // enforced.
   544  //
   545  // This field is intended to be used when ``filter_enabled`` and ``enabled`` are off. One of those
   546  // fields have to explicitly disable the filter in order for this setting to take effect.
   547  //
   548  // If :ref:`runtime_key <envoy_api_field_config.core.v4alpha.RuntimeFractionalPercent.runtime_key>` is specified,
   549  // Envoy will lookup the runtime key to get the percentage of requests for which it will evaluate
   550  // and track the request's *Origin* to determine if it's valid but will not enforce any policies.
   551  core.v4alpha.RuntimeFractionalPercent shadow_enabled = 10;
   552}
   553
   554// [#next-free-field: 37]
   555message RouteAction {
   556  option (udpa.annotations.versioning).previous_message_type = "envoy.config.route.v3.RouteAction";
   557
   558  enum ClusterNotFoundResponseCode {
   559    // HTTP status code - 503 Service Unavailable.
   560    SERVICE_UNAVAILABLE = 0;
   561
   562    // HTTP status code - 404 Not Found.
   563    NOT_FOUND = 1;
   564  }
   565
   566  // The router is capable of shadowing traffic from one cluster to another. The current
   567  // implementation is "fire and forget," meaning Envoy will not wait for the shadow cluster to
   568  // respond before returning the response from the primary cluster. All normal statistics are
   569  // collected for the shadow cluster making this feature useful for testing.
   570  //
   571  // During shadowing, the host/authority header is altered such that *-shadow* is appended. This is
   572  // useful for logging. For example, *cluster1* becomes *cluster1-shadow*.
   573  //
   574  // .. note::
   575  //
   576  //   Shadowing will not be triggered if the primary cluster does not exist.
   577  message RequestMirrorPolicy {
   578    option (udpa.annotations.versioning).previous_message_type =
   579        "envoy.config.route.v3.RouteAction.RequestMirrorPolicy";
   580
   581    reserved 2;
   582
   583    reserved "runtime_key";
   584
   585    // Specifies the cluster that requests will be mirrored to. The cluster must
   586    // exist in the cluster manager configuration.
   587    string cluster = 1 [(validate.rules).string = {min_len: 1}];
   588
   589    // If not specified, all requests to the target cluster will be mirrored.
   590    //
   591    // If specified, this field takes precedence over the `runtime_key` field and requests must also
   592    // fall under the percentage of matches indicated by this field.
   593    //
   594    // For some fraction N/D, a random number in the range [0,D) is selected. If the
   595    // number is <= the value of the numerator N, or if the key is not present, the default
   596    // value, the request will be mirrored.
   597    core.v4alpha.RuntimeFractionalPercent runtime_fraction = 3;
   598
   599    // Determines if the trace span should be sampled. Defaults to true.
   600    google.protobuf.BoolValue trace_sampled = 4;
   601  }
   602
   603  // Specifies the route's hashing policy if the upstream cluster uses a hashing :ref:`load balancer
   604  // <arch_overview_load_balancing_types>`.
   605  // [#next-free-field: 7]
   606  message HashPolicy {
   607    option (udpa.annotations.versioning).previous_message_type =
   608        "envoy.config.route.v3.RouteAction.HashPolicy";
   609
   610    message Header {
   611      option (udpa.annotations.versioning).previous_message_type =
   612          "envoy.config.route.v3.RouteAction.HashPolicy.Header";
   613
   614      // The name of the request header that will be used to obtain the hash
   615      // key. If the request header is not present, no hash will be produced.
   616      string header_name = 1
   617          [(validate.rules).string = {min_len: 1 well_known_regex: HTTP_HEADER_NAME strict: false}];
   618
   619      // If specified, the request header value will be rewritten and used
   620      // to produce the hash key.
   621      type.matcher.v4alpha.RegexMatchAndSubstitute regex_rewrite = 2;
   622    }
   623
   624    // Envoy supports two types of cookie affinity:
   625    //
   626    // 1. Passive. Envoy takes a cookie that's present in the cookies header and
   627    //    hashes on its value.
   628    //
   629    // 2. Generated. Envoy generates and sets a cookie with an expiration (TTL)
   630    //    on the first request from the client in its response to the client,
   631    //    based on the endpoint the request gets sent to. The client then
   632    //    presents this on the next and all subsequent requests. The hash of
   633    //    this is sufficient to ensure these requests get sent to the same
   634    //    endpoint. The cookie is generated by hashing the source and
   635    //    destination ports and addresses so that multiple independent HTTP2
   636    //    streams on the same connection will independently receive the same
   637    //    cookie, even if they arrive at the Envoy simultaneously.
   638    message Cookie {
   639      option (udpa.annotations.versioning).previous_message_type =
   640          "envoy.config.route.v3.RouteAction.HashPolicy.Cookie";
   641
   642      // The name of the cookie that will be used to obtain the hash key. If the
   643      // cookie is not present and ttl below is not set, no hash will be
   644      // produced.
   645      string name = 1 [(validate.rules).string = {min_len: 1}];
   646
   647      // If specified, a cookie with the TTL will be generated if the cookie is
   648      // not present. If the TTL is present and zero, the generated cookie will
   649      // be a session cookie.
   650      google.protobuf.Duration ttl = 2;
   651
   652      // The name of the path for the cookie. If no path is specified here, no path
   653      // will be set for the cookie.
   654      string path = 3;
   655    }
   656
   657    message ConnectionProperties {
   658      option (udpa.annotations.versioning).previous_message_type =
   659          "envoy.config.route.v3.RouteAction.HashPolicy.ConnectionProperties";
   660
   661      // Hash on source IP address.
   662      bool source_ip = 1;
   663    }
   664
   665    message QueryParameter {
   666      option (udpa.annotations.versioning).previous_message_type =
   667          "envoy.config.route.v3.RouteAction.HashPolicy.QueryParameter";
   668
   669      // The name of the URL query parameter that will be used to obtain the hash
   670      // key. If the parameter is not present, no hash will be produced. Query
   671      // parameter names are case-sensitive.
   672      string name = 1 [(validate.rules).string = {min_len: 1}];
   673    }
   674
   675    message FilterState {
   676      option (udpa.annotations.versioning).previous_message_type =
   677          "envoy.config.route.v3.RouteAction.HashPolicy.FilterState";
   678
   679      // The name of the Object in the per-request filterState, which is an
   680      // Envoy::Http::Hashable object. If there is no data associated with the key,
   681      // or the stored object is not Envoy::Http::Hashable, no hash will be produced.
   682      string key = 1 [(validate.rules).string = {min_len: 1}];
   683    }
   684
   685    oneof policy_specifier {
   686      option (validate.required) = true;
   687
   688      // Header hash policy.
   689      Header header = 1;
   690
   691      // Cookie hash policy.
   692      Cookie cookie = 2;
   693
   694      // Connection properties hash policy.
   695      ConnectionProperties connection_properties = 3;
   696
   697      // Query parameter hash policy.
   698      QueryParameter query_parameter = 5;
   699
   700      // Filter state hash policy.
   701      FilterState filter_state = 6;
   702    }
   703
   704    // The flag that short-circuits the hash computing. This field provides a
   705    // 'fallback' style of configuration: "if a terminal policy doesn't work,
   706    // fallback to rest of the policy list", it saves time when the terminal
   707    // policy works.
   708    //
   709    // If true, and there is already a hash computed, ignore rest of the
   710    // list of hash polices.
   711    // For example, if the following hash methods are configured:
   712    //
   713    //  ========= ========
   714    //  specifier terminal
   715    //  ========= ========
   716    //  Header A  true
   717    //  Header B  false
   718    //  Header C  false
   719    //  ========= ========
   720    //
   721    // The generateHash process ends if policy "header A" generates a hash, as
   722    // it's a terminal policy.
   723    bool terminal = 4;
   724  }
   725
   726  // Allows enabling and disabling upgrades on a per-route basis.
   727  // This overrides any enabled/disabled upgrade filter chain specified in the
   728  // HttpConnectionManager
   729  // :ref:`upgrade_configs
   730  // <envoy_api_field_extensions.filters.network.http_connection_manager.v4alpha.HttpConnectionManager.upgrade_configs>`
   731  // but does not affect any custom filter chain specified there.
   732  message UpgradeConfig {
   733    option (udpa.annotations.versioning).previous_message_type =
   734        "envoy.config.route.v3.RouteAction.UpgradeConfig";
   735
   736    // Configuration for sending data upstream as a raw data payload. This is used for
   737    // CONNECT requests, when forwarding CONNECT payload as raw TCP.
   738    message ConnectConfig {
   739      option (udpa.annotations.versioning).previous_message_type =
   740          "envoy.config.route.v3.RouteAction.UpgradeConfig.ConnectConfig";
   741
   742      // If present, the proxy protocol header will be prepended to the CONNECT payload sent upstream.
   743      core.v4alpha.ProxyProtocolConfig proxy_protocol_config = 1;
   744    }
   745
   746    // The case-insensitive name of this upgrade, e.g. "websocket".
   747    // For each upgrade type present in upgrade_configs, requests with
   748    // Upgrade: [upgrade_type] will be proxied upstream.
   749    string upgrade_type = 1
   750        [(validate.rules).string = {min_len: 1 well_known_regex: HTTP_HEADER_VALUE strict: false}];
   751
   752    // Determines if upgrades are available on this route. Defaults to true.
   753    google.protobuf.BoolValue enabled = 2;
   754
   755    // Configuration for sending data upstream as a raw data payload. This is used for
   756    // CONNECT requests, when forwarding CONNECT payload as raw TCP.
   757    // Note that CONNECT support is currently considered alpha in Envoy.
   758    // [#comment:TODO(htuch): Replace the above comment with an alpha tag.
   759    ConnectConfig connect_config = 3;
   760  }
   761
   762  message MaxStreamDuration {
   763    option (udpa.annotations.versioning).previous_message_type =
   764        "envoy.config.route.v3.RouteAction.MaxStreamDuration";
   765
   766    // Specifies the maximum duration allowed for streams on the route. If not specified, the value
   767    // from the :ref:`max_stream_duration
   768    // <envoy_api_field_config.core.v4alpha.HttpProtocolOptions.max_stream_duration>` field in
   769    // :ref:`HttpConnectionManager.common_http_protocol_options
   770    // <envoy_api_field_extensions.filters.network.http_connection_manager.v4alpha.HttpConnectionManager.common_http_protocol_options>`
   771    // is used. If this field is set explicitly to zero, any
   772    // HttpConnectionManager max_stream_duration timeout will be disabled for
   773    // this route.
   774    google.protobuf.Duration max_stream_duration = 1;
   775
   776    // If present, and the request contains a `grpc-timeout header
   777    // <https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md>`_, use that value as the
   778    // *max_stream_duration*, but limit the applied timeout to the maximum value specified here.
   779    // If set to 0, the `grpc-timeout` header is used without modification.
   780    google.protobuf.Duration grpc_timeout_header_max = 2;
   781
   782    // If present, Envoy will adjust the timeout provided by the `grpc-timeout` header by
   783    // subtracting the provided duration from the header. This is useful for allowing Envoy to set
   784    // its global timeout to be less than that of the deadline imposed by the calling client, which
   785    // makes it more likely that Envoy will handle the timeout instead of having the call canceled
   786    // by the client. If, after applying the offset, the resulting timeout is zero or negative,
   787    // the stream will timeout immediately.
   788    google.protobuf.Duration grpc_timeout_header_offset = 3;
   789  }
   790
   791  reserved 12, 18, 19, 16, 22, 21, 10, 14, 23, 28, 26, 31;
   792
   793  reserved "request_mirror_policy", "include_vh_rate_limits", "max_grpc_timeout",
   794      "grpc_timeout_offset", "internal_redirect_action", "max_internal_redirects";
   795
   796  oneof cluster_specifier {
   797    option (validate.required) = true;
   798
   799    // Indicates the upstream cluster to which the request should be routed
   800    // to.
   801    string cluster = 1 [(validate.rules).string = {min_len: 1}];
   802
   803    // Envoy will determine the cluster to route to by reading the value of the
   804    // HTTP header named by cluster_header from the request headers. If the
   805    // header is not found or the referenced cluster does not exist, Envoy will
   806    // return a 404 response.
   807    //
   808    // .. attention::
   809    //
   810    //   Internally, Envoy always uses the HTTP/2 *:authority* header to represent the HTTP/1
   811    //   *Host* header. Thus, if attempting to match on *Host*, match on *:authority* instead.
   812    //
   813    // .. note::
   814    //
   815    //   If the header appears multiple times only the first value is used.
   816    string cluster_header = 2
   817        [(validate.rules).string = {min_len: 1 well_known_regex: HTTP_HEADER_NAME strict: false}];
   818
   819    // Multiple upstream clusters can be specified for a given route. The
   820    // request is routed to one of the upstream clusters based on weights
   821    // assigned to each cluster. See
   822    // :ref:`traffic splitting <config_http_conn_man_route_table_traffic_splitting_split>`
   823    // for additional documentation.
   824    WeightedCluster weighted_clusters = 3;
   825  }
   826
   827  // The HTTP status code to use when configured cluster is not found.
   828  // The default response code is 503 Service Unavailable.
   829  ClusterNotFoundResponseCode cluster_not_found_response_code = 20
   830      [(validate.rules).enum = {defined_only: true}];
   831
   832  // Optional endpoint metadata match criteria used by the subset load balancer. Only endpoints
   833  // in the upstream cluster with metadata matching what's set in this field will be considered
   834  // for load balancing. If using :ref:`weighted_clusters
   835  // <envoy_api_field_config.route.v4alpha.RouteAction.weighted_clusters>`, metadata will be merged, with values
   836  // provided there taking precedence. The filter name should be specified as *envoy.lb*.
   837  core.v4alpha.Metadata metadata_match = 4;
   838
   839  // Indicates that during forwarding, the matched prefix (or path) should be
   840  // swapped with this value. This option allows application URLs to be rooted
   841  // at a different path from those exposed at the reverse proxy layer. The router filter will
   842  // place the original path before rewrite into the :ref:`x-envoy-original-path
   843  // <config_http_filters_router_x-envoy-original-path>` header.
   844  //
   845  // Only one of *prefix_rewrite* or
   846  // :ref:`regex_rewrite <envoy_api_field_config.route.v4alpha.RouteAction.regex_rewrite>`
   847  // may be specified.
   848  //
   849  // .. attention::
   850  //
   851  //   Pay careful attention to the use of trailing slashes in the
   852  //   :ref:`route's match <envoy_api_field_config.route.v4alpha.Route.match>` prefix value.
   853  //   Stripping a prefix from a path requires multiple Routes to handle all cases. For example,
   854  //   rewriting */prefix* to */* and */prefix/etc* to */etc* cannot be done in a single
   855  //   :ref:`Route <envoy_api_msg_config.route.v4alpha.Route>`, as shown by the below config entries:
   856  //
   857  //   .. code-block:: yaml
   858  //
   859  //     - match:
   860  //         prefix: "/prefix/"
   861  //       route:
   862  //         prefix_rewrite: "/"
   863  //     - match:
   864  //         prefix: "/prefix"
   865  //       route:
   866  //         prefix_rewrite: "/"
   867  //
   868  //   Having above entries in the config, requests to */prefix* will be stripped to */*, while
   869  //   requests to */prefix/etc* will be stripped to */etc*.
   870  string prefix_rewrite = 5
   871      [(validate.rules).string = {well_known_regex: HTTP_HEADER_VALUE strict: false}];
   872
   873  // Indicates that during forwarding, portions of the path that match the
   874  // pattern should be rewritten, even allowing the substitution of capture
   875  // groups from the pattern into the new path as specified by the rewrite
   876  // substitution string. This is useful to allow application paths to be
   877  // rewritten in a way that is aware of segments with variable content like
   878  // identifiers. The router filter will place the original path as it was
   879  // before the rewrite into the :ref:`x-envoy-original-path
   880  // <config_http_filters_router_x-envoy-original-path>` header.
   881  //
   882  // Only one of :ref:`prefix_rewrite <envoy_api_field_config.route.v4alpha.RouteAction.prefix_rewrite>`
   883  // or *regex_rewrite* may be specified.
   884  //
   885  // Examples using Google's `RE2 <https://github.com/google/re2>`_ engine:
   886  //
   887  // * The path pattern ``^/service/([^/]+)(/.*)$`` paired with a substitution
   888  //   string of ``\2/instance/\1`` would transform ``/service/foo/v1/api``
   889  //   into ``/v1/api/instance/foo``.
   890  //
   891  // * The pattern ``one`` paired with a substitution string of ``two`` would
   892  //   transform ``/xxx/one/yyy/one/zzz`` into ``/xxx/two/yyy/two/zzz``.
   893  //
   894  // * The pattern ``^(.*?)one(.*)$`` paired with a substitution string of
   895  //   ``\1two\2`` would replace only the first occurrence of ``one``,
   896  //   transforming path ``/xxx/one/yyy/one/zzz`` into ``/xxx/two/yyy/one/zzz``.
   897  //
   898  // * The pattern ``(?i)/xxx/`` paired with a substitution string of ``/yyy/``
   899  //   would do a case-insensitive match and transform path ``/aaa/XxX/bbb`` to
   900  //   ``/aaa/yyy/bbb``.
   901  type.matcher.v4alpha.RegexMatchAndSubstitute regex_rewrite = 32;
   902
   903  oneof host_rewrite_specifier {
   904    // Indicates that during forwarding, the host header will be swapped with
   905    // this value.
   906    string host_rewrite_literal = 6
   907        [(validate.rules).string = {well_known_regex: HTTP_HEADER_VALUE strict: false}];
   908
   909    // Indicates that during forwarding, the host header will be swapped with
   910    // the hostname of the upstream host chosen by the cluster manager. This
   911    // option is applicable only when the destination cluster for a route is of
   912    // type *strict_dns* or *logical_dns*. Setting this to true with other cluster
   913    // types has no effect.
   914    google.protobuf.BoolValue auto_host_rewrite = 7;
   915
   916    // Indicates that during forwarding, the host header will be swapped with the content of given
   917    // downstream or :ref:`custom <config_http_conn_man_headers_custom_request_headers>` header.
   918    // If header value is empty, host header is left intact.
   919    //
   920    // .. attention::
   921    //
   922    //   Pay attention to the potential security implications of using this option. Provided header
   923    //   must come from trusted source.
   924    //
   925    // .. note::
   926    //
   927    //   If the header appears multiple times only the first value is used.
   928    string host_rewrite_header = 29
   929        [(validate.rules).string = {well_known_regex: HTTP_HEADER_NAME strict: false}];
   930
   931    // Indicates that during forwarding, the host header will be swapped with
   932    // the result of the regex substitution executed on path value with query and fragment removed.
   933    // This is useful for transitioning variable content between path segment and subdomain.
   934    //
   935    // For example with the following config:
   936    //
   937    //   .. code-block:: yaml
   938    //
   939    //     host_rewrite_path_regex:
   940    //       pattern:
   941    //         google_re2: {}
   942    //         regex: "^/(.+)/.+$"
   943    //       substitution: \1
   944    //
   945    // Would rewrite the host header to `envoyproxy.io` given the path `/envoyproxy.io/some/path`.
   946    type.matcher.v4alpha.RegexMatchAndSubstitute host_rewrite_path_regex = 35;
   947  }
   948
   949  // Specifies the upstream timeout for the route. If not specified, the default is 15s. This
   950  // spans between the point at which the entire downstream request (i.e. end-of-stream) has been
   951  // processed and when the upstream response has been completely processed. A value of 0 will
   952  // disable the route's timeout.
   953  //
   954  // .. note::
   955  //
   956  //   This timeout includes all retries. See also
   957  //   :ref:`config_http_filters_router_x-envoy-upstream-rq-timeout-ms`,
   958  //   :ref:`config_http_filters_router_x-envoy-upstream-rq-per-try-timeout-ms`, and the
   959  //   :ref:`retry overview <arch_overview_http_routing_retry>`.
   960  google.protobuf.Duration timeout = 8;
   961
   962  // Specifies the idle timeout for the route. If not specified, there is no per-route idle timeout,
   963  // although the connection manager wide :ref:`stream_idle_timeout
   964  // <envoy_api_field_extensions.filters.network.http_connection_manager.v4alpha.HttpConnectionManager.stream_idle_timeout>`
   965  // will still apply. A value of 0 will completely disable the route's idle timeout, even if a
   966  // connection manager stream idle timeout is configured.
   967  //
   968  // The idle timeout is distinct to :ref:`timeout
   969  // <envoy_api_field_config.route.v4alpha.RouteAction.timeout>`, which provides an upper bound
   970  // on the upstream response time; :ref:`idle_timeout
   971  // <envoy_api_field_config.route.v4alpha.RouteAction.idle_timeout>` instead bounds the amount
   972  // of time the request's stream may be idle.
   973  //
   974  // After header decoding, the idle timeout will apply on downstream and
   975  // upstream request events. Each time an encode/decode event for headers or
   976  // data is processed for the stream, the timer will be reset. If the timeout
   977  // fires, the stream is terminated with a 408 Request Timeout error code if no
   978  // upstream response header has been received, otherwise a stream reset
   979  // occurs.
   980  //
   981  // If the :ref:`overload action <config_overload_manager_overload_actions>` "envoy.overload_actions.reduce_timeouts"
   982  // is configured, this timeout is scaled according to the value for
   983  // :ref:`HTTP_DOWNSTREAM_STREAM_IDLE <envoy_api_enum_value_config.overload.v3.ScaleTimersOverloadActionConfig.TimerType.HTTP_DOWNSTREAM_STREAM_IDLE>`.
   984  google.protobuf.Duration idle_timeout = 24;
   985
   986  // Indicates that the route has a retry policy. Note that if this is set,
   987  // it'll take precedence over the virtual host level retry policy entirely
   988  // (e.g.: policies are not merged, most internal one becomes the enforced policy).
   989  RetryPolicy retry_policy = 9;
   990
   991  // [#not-implemented-hide:]
   992  // Specifies the configuration for retry policy extension. Note that if this is set, it'll take
   993  // precedence over the virtual host level retry policy entirely (e.g.: policies are not merged,
   994  // most internal one becomes the enforced policy). :ref:`Retry policy <envoy_api_field_config.route.v4alpha.VirtualHost.retry_policy>`
   995  // should not be set if this field is used.
   996  google.protobuf.Any retry_policy_typed_config = 33;
   997
   998  // Indicates that the route has request mirroring policies.
   999  repeated RequestMirrorPolicy request_mirror_policies = 30;
  1000
  1001  // Optionally specifies the :ref:`routing priority <arch_overview_http_routing_priority>`.
  1002  core.v4alpha.RoutingPriority priority = 11 [(validate.rules).enum = {defined_only: true}];
  1003
  1004  // Specifies a set of rate limit configurations that could be applied to the
  1005  // route.
  1006  repeated RateLimit rate_limits = 13;
  1007
  1008  // Specifies a list of hash policies to use for ring hash load balancing. Each
  1009  // hash policy is evaluated individually and the combined result is used to
  1010  // route the request. The method of combination is deterministic such that
  1011  // identical lists of hash policies will produce the same hash. Since a hash
  1012  // policy examines specific parts of a request, it can fail to produce a hash
  1013  // (i.e. if the hashed header is not present). If (and only if) all configured
  1014  // hash policies fail to generate a hash, no hash will be produced for
  1015  // the route. In this case, the behavior is the same as if no hash policies
  1016  // were specified (i.e. the ring hash load balancer will choose a random
  1017  // backend). If a hash policy has the "terminal" attribute set to true, and
  1018  // there is already a hash generated, the hash is returned immediately,
  1019  // ignoring the rest of the hash policy list.
  1020  repeated HashPolicy hash_policy = 15;
  1021
  1022  // Indicates that the route has a CORS policy.
  1023  CorsPolicy cors = 17;
  1024
  1025  repeated UpgradeConfig upgrade_configs = 25;
  1026
  1027  // If present, Envoy will try to follow an upstream redirect response instead of proxying the
  1028  // response back to the downstream. An upstream redirect response is defined
  1029  // by :ref:`redirect_response_codes
  1030  // <envoy_api_field_config.route.v4alpha.InternalRedirectPolicy.redirect_response_codes>`.
  1031  InternalRedirectPolicy internal_redirect_policy = 34;
  1032
  1033  // Indicates that the route has a hedge policy. Note that if this is set,
  1034  // it'll take precedence over the virtual host level hedge policy entirely
  1035  // (e.g.: policies are not merged, most internal one becomes the enforced policy).
  1036  HedgePolicy hedge_policy = 27;
  1037
  1038  // Specifies the maximum stream duration for this route.
  1039  MaxStreamDuration max_stream_duration = 36;
  1040}
  1041
  1042// HTTP retry :ref:`architecture overview <arch_overview_http_routing_retry>`.
  1043// [#next-free-field: 12]
  1044message RetryPolicy {
  1045  option (udpa.annotations.versioning).previous_message_type = "envoy.config.route.v3.RetryPolicy";
  1046
  1047  enum ResetHeaderFormat {
  1048    SECONDS = 0;
  1049    UNIX_TIMESTAMP = 1;
  1050  }
  1051
  1052  message RetryPriority {
  1053    option (udpa.annotations.versioning).previous_message_type =
  1054        "envoy.config.route.v3.RetryPolicy.RetryPriority";
  1055
  1056    reserved 2;
  1057
  1058    reserved "config";
  1059
  1060    string name = 1 [(validate.rules).string = {min_len: 1}];
  1061
  1062    oneof config_type {
  1063      google.protobuf.Any typed_config = 3;
  1064    }
  1065  }
  1066
  1067  message RetryHostPredicate {
  1068    option (udpa.annotations.versioning).previous_message_type =
  1069        "envoy.config.route.v3.RetryPolicy.RetryHostPredicate";
  1070
  1071    reserved 2;
  1072
  1073    reserved "config";
  1074
  1075    string name = 1 [(validate.rules).string = {min_len: 1}];
  1076
  1077    oneof config_type {
  1078      google.protobuf.Any typed_config = 3;
  1079    }
  1080  }
  1081
  1082  message RetryBackOff {
  1083    option (udpa.annotations.versioning).previous_message_type =
  1084        "envoy.config.route.v3.RetryPolicy.RetryBackOff";
  1085
  1086    // Specifies the base interval between retries. This parameter is required and must be greater
  1087    // than zero. Values less than 1 ms are rounded up to 1 ms.
  1088    // See :ref:`config_http_filters_router_x-envoy-max-retries` for a discussion of Envoy's
  1089    // back-off algorithm.
  1090    google.protobuf.Duration base_interval = 1 [(validate.rules).duration = {
  1091      required: true
  1092      gt {}
  1093    }];
  1094
  1095    // Specifies the maximum interval between retries. This parameter is optional, but must be
  1096    // greater than or equal to the `base_interval` if set. The default is 10 times the
  1097    // `base_interval`. See :ref:`config_http_filters_router_x-envoy-max-retries` for a discussion
  1098    // of Envoy's back-off algorithm.
  1099    google.protobuf.Duration max_interval = 2 [(validate.rules).duration = {gt {}}];
  1100  }
  1101
  1102  message ResetHeader {
  1103    option (udpa.annotations.versioning).previous_message_type =
  1104        "envoy.config.route.v3.RetryPolicy.ResetHeader";
  1105
  1106    // The name of the reset header.
  1107    //
  1108    // .. note::
  1109    //
  1110    //   If the header appears multiple times only the first value is used.
  1111    string name = 1
  1112        [(validate.rules).string = {min_len: 1 well_known_regex: HTTP_HEADER_NAME strict: false}];
  1113
  1114    // The format of the reset header.
  1115    ResetHeaderFormat format = 2 [(validate.rules).enum = {defined_only: true}];
  1116  }
  1117
  1118  // A retry back-off strategy that applies when the upstream server rate limits
  1119  // the request.
  1120  //
  1121  // Given this configuration:
  1122  //
  1123  // .. code-block:: yaml
  1124  //
  1125  //   rate_limited_retry_back_off:
  1126  //     reset_headers:
  1127  //     - name: Retry-After
  1128  //       format: SECONDS
  1129  //     - name: X-RateLimit-Reset
  1130  //       format: UNIX_TIMESTAMP
  1131  //     max_interval: "300s"
  1132  //
  1133  // The following algorithm will apply:
  1134  //
  1135  //  1. If the response contains the header ``Retry-After`` its value must be on
  1136  //     the form ``120`` (an integer that represents the number of seconds to
  1137  //     wait before retrying). If so, this value is used as the back-off interval.
  1138  //  2. Otherwise, if the response contains the header ``X-RateLimit-Reset`` its
  1139  //     value must be on the form ``1595320702`` (an integer that represents the
  1140  //     point in time at which to retry, as a Unix timestamp in seconds). If so,
  1141  //     the current time is subtracted from this value and the result is used as
  1142  //     the back-off interval.
  1143  //  3. Otherwise, Envoy will use the default
  1144  //     :ref:`exponential back-off <envoy_v3_api_field_config.route.v3.RetryPolicy.retry_back_off>`
  1145  //     strategy.
  1146  //
  1147  // No matter which format is used, if the resulting back-off interval exceeds
  1148  // ``max_interval`` it is discarded and the next header in ``reset_headers``
  1149  // is tried. If a request timeout is configured for the route it will further
  1150  // limit how long the request will be allowed to run.
  1151  //
  1152  // To prevent many clients retrying at the same point in time jitter is added
  1153  // to the back-off interval, so the resulting interval is decided by taking:
  1154  // ``random(interval, interval * 1.5)``.
  1155  //
  1156  // .. attention::
  1157  //
  1158  //   Configuring ``rate_limited_retry_back_off`` will not by itself cause a request
  1159  //   to be retried. You will still need to configure the right retry policy to match
  1160  //   the responses from the upstream server.
  1161  message RateLimitedRetryBackOff {
  1162    option (udpa.annotations.versioning).previous_message_type =
  1163        "envoy.config.route.v3.RetryPolicy.RateLimitedRetryBackOff";
  1164
  1165    // Specifies the reset headers (like ``Retry-After`` or ``X-RateLimit-Reset``)
  1166    // to match against the response. Headers are tried in order, and matched case
  1167    // insensitive. The first header to be parsed successfully is used. If no headers
  1168    // match the default exponential back-off is used instead.
  1169    repeated ResetHeader reset_headers = 1 [(validate.rules).repeated = {min_items: 1}];
  1170
  1171    // Specifies the maximum back off interval that Envoy will allow. If a reset
  1172    // header contains an interval longer than this then it will be discarded and
  1173    // the next header will be tried. Defaults to 300 seconds.
  1174    google.protobuf.Duration max_interval = 2 [(validate.rules).duration = {gt {}}];
  1175  }
  1176
  1177  // Specifies the conditions under which retry takes place. These are the same
  1178  // conditions documented for :ref:`config_http_filters_router_x-envoy-retry-on` and
  1179  // :ref:`config_http_filters_router_x-envoy-retry-grpc-on`.
  1180  string retry_on = 1;
  1181
  1182  // Specifies the allowed number of retries. This parameter is optional and
  1183  // defaults to 1. These are the same conditions documented for
  1184  // :ref:`config_http_filters_router_x-envoy-max-retries`.
  1185  google.protobuf.UInt32Value max_retries = 2;
  1186
  1187  // Specifies a non-zero upstream timeout per retry attempt. This parameter is optional. The
  1188  // same conditions documented for
  1189  // :ref:`config_http_filters_router_x-envoy-upstream-rq-per-try-timeout-ms` apply.
  1190  //
  1191  // .. note::
  1192  //
  1193  //   If left unspecified, Envoy will use the global
  1194  //   :ref:`route timeout <envoy_api_field_config.route.v4alpha.RouteAction.timeout>` for the request.
  1195  //   Consequently, when using a :ref:`5xx <config_http_filters_router_x-envoy-retry-on>` based
  1196  //   retry policy, a request that times out will not be retried as the total timeout budget
  1197  //   would have been exhausted.
  1198  google.protobuf.Duration per_try_timeout = 3;
  1199
  1200  // Specifies an implementation of a RetryPriority which is used to determine the
  1201  // distribution of load across priorities used for retries. Refer to
  1202  // :ref:`retry plugin configuration <arch_overview_http_retry_plugins>` for more details.
  1203  RetryPriority retry_priority = 4;
  1204
  1205  // Specifies a collection of RetryHostPredicates that will be consulted when selecting a host
  1206  // for retries. If any of the predicates reject the host, host selection will be reattempted.
  1207  // Refer to :ref:`retry plugin configuration <arch_overview_http_retry_plugins>` for more
  1208  // details.
  1209  repeated RetryHostPredicate retry_host_predicate = 5;
  1210
  1211  // The maximum number of times host selection will be reattempted before giving up, at which
  1212  // point the host that was last selected will be routed to. If unspecified, this will default to
  1213  // retrying once.
  1214  int64 host_selection_retry_max_attempts = 6;
  1215
  1216  // HTTP status codes that should trigger a retry in addition to those specified by retry_on.
  1217  repeated uint32 retriable_status_codes = 7;
  1218
  1219  // Specifies parameters that control exponential retry back off. This parameter is optional, in which case the
  1220  // default base interval is 25 milliseconds or, if set, the current value of the
  1221  // `upstream.base_retry_backoff_ms` runtime parameter. The default maximum interval is 10 times
  1222  // the base interval. The documentation for :ref:`config_http_filters_router_x-envoy-max-retries`
  1223  // describes Envoy's back-off algorithm.
  1224  RetryBackOff retry_back_off = 8;
  1225
  1226  // Specifies parameters that control a retry back-off strategy that is used
  1227  // when the request is rate limited by the upstream server. The server may
  1228  // return a response header like ``Retry-After`` or ``X-RateLimit-Reset`` to
  1229  // provide feedback to the client on how long to wait before retrying. If
  1230  // configured, this back-off strategy will be used instead of the
  1231  // default exponential back off strategy (configured using `retry_back_off`)
  1232  // whenever a response includes the matching headers.
  1233  RateLimitedRetryBackOff rate_limited_retry_back_off = 11;
  1234
  1235  // HTTP response headers that trigger a retry if present in the response. A retry will be
  1236  // triggered if any of the header matches match the upstream response headers.
  1237  // The field is only consulted if 'retriable-headers' retry policy is active.
  1238  repeated HeaderMatcher retriable_headers = 9;
  1239
  1240  // HTTP headers which must be present in the request for retries to be attempted.
  1241  repeated HeaderMatcher retriable_request_headers = 10;
  1242}
  1243
  1244// HTTP request hedging :ref:`architecture overview <arch_overview_http_routing_hedging>`.
  1245message HedgePolicy {
  1246  option (udpa.annotations.versioning).previous_message_type = "envoy.config.route.v3.HedgePolicy";
  1247
  1248  // Specifies the number of initial requests that should be sent upstream.
  1249  // Must be at least 1.
  1250  // Defaults to 1.
  1251  // [#not-implemented-hide:]
  1252  google.protobuf.UInt32Value initial_requests = 1 [(validate.rules).uint32 = {gte: 1}];
  1253
  1254  // Specifies a probability that an additional upstream request should be sent
  1255  // on top of what is specified by initial_requests.
  1256  // Defaults to 0.
  1257  // [#not-implemented-hide:]
  1258  type.v3.FractionalPercent additional_request_chance = 2;
  1259
  1260  // Indicates that a hedged request should be sent when the per-try timeout is hit.
  1261  // This means that a retry will be issued without resetting the original request, leaving multiple upstream requests in flight.
  1262  // The first request to complete successfully will be the one returned to the caller.
  1263  //
  1264  // * At any time, a successful response (i.e. not triggering any of the retry-on conditions) would be returned to the client.
  1265  // * Before per-try timeout, an error response (per retry-on conditions) would be retried immediately or returned ot the client
  1266  //   if there are no more retries left.
  1267  // * After per-try timeout, an error response would be discarded, as a retry in the form of a hedged request is already in progress.
  1268  //
  1269  // Note: For this to have effect, you must have a :ref:`RetryPolicy <envoy_api_msg_config.route.v4alpha.RetryPolicy>` that retries at least
  1270  // one error code and specifies a maximum number of retries.
  1271  //
  1272  // Defaults to false.
  1273  bool hedge_on_per_try_timeout = 3;
  1274}
  1275
  1276// [#next-free-field: 10]
  1277message RedirectAction {
  1278  option (udpa.annotations.versioning).previous_message_type =
  1279      "envoy.config.route.v3.RedirectAction";
  1280
  1281  enum RedirectResponseCode {
  1282    // Moved Permanently HTTP Status Code - 301.
  1283    MOVED_PERMANENTLY = 0;
  1284
  1285    // Found HTTP Status Code - 302.
  1286    FOUND = 1;
  1287
  1288    // See Other HTTP Status Code - 303.
  1289    SEE_OTHER = 2;
  1290
  1291    // Temporary Redirect HTTP Status Code - 307.
  1292    TEMPORARY_REDIRECT = 3;
  1293
  1294    // Permanent Redirect HTTP Status Code - 308.
  1295    PERMANENT_REDIRECT = 4;
  1296  }
  1297
  1298  // When the scheme redirection take place, the following rules apply:
  1299  //  1. If the source URI scheme is `http` and the port is explicitly
  1300  //     set to `:80`, the port will be removed after the redirection
  1301  //  2. If the source URI scheme is `https` and the port is explicitly
  1302  //     set to `:443`, the port will be removed after the redirection
  1303  oneof scheme_rewrite_specifier {
  1304    // The scheme portion of the URL will be swapped with "https".
  1305    bool https_redirect = 4;
  1306
  1307    // The scheme portion of the URL will be swapped with this value.
  1308    string scheme_redirect = 7;
  1309  }
  1310
  1311  // The host portion of the URL will be swapped with this value.
  1312  string host_redirect = 1
  1313      [(validate.rules).string = {well_known_regex: HTTP_HEADER_VALUE strict: false}];
  1314
  1315  // The port value of the URL will be swapped with this value.
  1316  uint32 port_redirect = 8;
  1317
  1318  oneof path_rewrite_specifier {
  1319    // The path portion of the URL will be swapped with this value.
  1320    // Please note that query string in path_redirect will override the
  1321    // request's query string and will not be stripped.
  1322    //
  1323    // For example, let's say we have the following routes:
  1324    //
  1325    // - match: { path: "/old-path-1" }
  1326    //   redirect: { path_redirect: "/new-path-1" }
  1327    // - match: { path: "/old-path-2" }
  1328    //   redirect: { path_redirect: "/new-path-2", strip-query: "true" }
  1329    // - match: { path: "/old-path-3" }
  1330    //   redirect: { path_redirect: "/new-path-3?foo=1", strip_query: "true" }
  1331    //
  1332    // 1. if request uri is "/old-path-1?bar=1", users will be redirected to "/new-path-1?bar=1"
  1333    // 2. if request uri is "/old-path-2?bar=1", users will be redirected to "/new-path-2"
  1334    // 3. if request uri is "/old-path-3?bar=1", users will be redirected to "/new-path-3?foo=1"
  1335    string path_redirect = 2
  1336        [(validate.rules).string = {well_known_regex: HTTP_HEADER_VALUE strict: false}];
  1337
  1338    // Indicates that during redirection, the matched prefix (or path)
  1339    // should be swapped with this value. This option allows redirect URLs be dynamically created
  1340    // based on the request.
  1341    //
  1342    // .. attention::
  1343    //
  1344    //   Pay attention to the use of trailing slashes as mentioned in
  1345    //   :ref:`RouteAction's prefix_rewrite <envoy_api_field_config.route.v4alpha.RouteAction.prefix_rewrite>`.
  1346    string prefix_rewrite = 5
  1347        [(validate.rules).string = {well_known_regex: HTTP_HEADER_VALUE strict: false}];
  1348
  1349    // Indicates that during redirect, portions of the path that match the
  1350    // pattern should be rewritten, even allowing the substitution of capture
  1351    // groups from the pattern into the new path as specified by the rewrite
  1352    // substitution string. This is useful to allow application paths to be
  1353    // rewritten in a way that is aware of segments with variable content like
  1354    // identifiers.
  1355    //
  1356    // Examples using Google's `RE2 <https://github.com/google/re2>`_ engine:
  1357    //
  1358    // * The path pattern ``^/service/([^/]+)(/.*)$`` paired with a substitution
  1359    //   string of ``\2/instance/\1`` would transform ``/service/foo/v1/api``
  1360    //   into ``/v1/api/instance/foo``.
  1361    //
  1362    // * The pattern ``one`` paired with a substitution string of ``two`` would
  1363    //   transform ``/xxx/one/yyy/one/zzz`` into ``/xxx/two/yyy/two/zzz``.
  1364    //
  1365    // * The pattern ``^(.*?)one(.*)$`` paired with a substitution string of
  1366    //   ``\1two\2`` would replace only the first occurrence of ``one``,
  1367    //   transforming path ``/xxx/one/yyy/one/zzz`` into ``/xxx/two/yyy/one/zzz``.
  1368    //
  1369    // * The pattern ``(?i)/xxx/`` paired with a substitution string of ``/yyy/``
  1370    //   would do a case-insensitive match and transform path ``/aaa/XxX/bbb`` to
  1371    //   ``/aaa/yyy/bbb``.
  1372    type.matcher.v4alpha.RegexMatchAndSubstitute regex_rewrite = 9;
  1373  }
  1374
  1375  // The HTTP status code to use in the redirect response. The default response
  1376  // code is MOVED_PERMANENTLY (301).
  1377  RedirectResponseCode response_code = 3 [(validate.rules).enum = {defined_only: true}];
  1378
  1379  // Indicates that during redirection, the query portion of the URL will
  1380  // be removed. Default value is false.
  1381  bool strip_query = 6;
  1382}
  1383
  1384message DirectResponseAction {
  1385  option (udpa.annotations.versioning).previous_message_type =
  1386      "envoy.config.route.v3.DirectResponseAction";
  1387
  1388  // Specifies the HTTP response status to be returned.
  1389  uint32 status = 1 [(validate.rules).uint32 = {lt: 600 gte: 100}];
  1390
  1391  // Specifies the content of the response body. If this setting is omitted,
  1392  // no body is included in the generated response.
  1393  //
  1394  // .. note::
  1395  //
  1396  //   Headers can be specified using *response_headers_to_add* in the enclosing
  1397  //   :ref:`envoy_api_msg_config.route.v4alpha.Route`, :ref:`envoy_api_msg_config.route.v4alpha.RouteConfiguration` or
  1398  //   :ref:`envoy_api_msg_config.route.v4alpha.VirtualHost`.
  1399  core.v4alpha.DataSource body = 2;
  1400}
  1401
  1402message Decorator {
  1403  option (udpa.annotations.versioning).previous_message_type = "envoy.config.route.v3.Decorator";
  1404
  1405  // The operation name associated with the request matched to this route. If tracing is
  1406  // enabled, this information will be used as the span name reported for this request.
  1407  //
  1408  // .. note::
  1409  //
  1410  //   For ingress (inbound) requests, or egress (outbound) responses, this value may be overridden
  1411  //   by the :ref:`x-envoy-decorator-operation
  1412  //   <config_http_filters_router_x-envoy-decorator-operation>` header.
  1413  string operation = 1 [(validate.rules).string = {min_len: 1}];
  1414
  1415  // Whether the decorated details should be propagated to the other party. The default is true.
  1416  google.protobuf.BoolValue propagate = 2;
  1417}
  1418
  1419message Tracing {
  1420  option (udpa.annotations.versioning).previous_message_type = "envoy.config.route.v3.Tracing";
  1421
  1422  // Target percentage of requests managed by this HTTP connection manager that will be force
  1423  // traced if the :ref:`x-client-trace-id <config_http_conn_man_headers_x-client-trace-id>`
  1424  // header is set. This field is a direct analog for the runtime variable
  1425  // 'tracing.client_sampling' in the :ref:`HTTP Connection Manager
  1426  // <config_http_conn_man_runtime>`.
  1427  // Default: 100%
  1428  type.v3.FractionalPercent client_sampling = 1;
  1429
  1430  // Target percentage of requests managed by this HTTP connection manager that will be randomly
  1431  // selected for trace generation, if not requested by the client or not forced. This field is
  1432  // a direct analog for the runtime variable 'tracing.random_sampling' in the
  1433  // :ref:`HTTP Connection Manager <config_http_conn_man_runtime>`.
  1434  // Default: 100%
  1435  type.v3.FractionalPercent random_sampling = 2;
  1436
  1437  // Target percentage of requests managed by this HTTP connection manager that will be traced
  1438  // after all other sampling checks have been applied (client-directed, force tracing, random
  1439  // sampling). This field functions as an upper limit on the total configured sampling rate. For
  1440  // instance, setting client_sampling to 100% but overall_sampling to 1% will result in only 1%
  1441  // of client requests with the appropriate headers to be force traced. This field is a direct
  1442  // analog for the runtime variable 'tracing.global_enabled' in the
  1443  // :ref:`HTTP Connection Manager <config_http_conn_man_runtime>`.
  1444  // Default: 100%
  1445  type.v3.FractionalPercent overall_sampling = 3;
  1446
  1447  // A list of custom tags with unique tag name to create tags for the active span.
  1448  // It will take effect after merging with the :ref:`corresponding configuration
  1449  // <envoy_api_field_extensions.filters.network.http_connection_manager.v4alpha.HttpConnectionManager.Tracing.custom_tags>`
  1450  // configured in the HTTP connection manager. If two tags with the same name are configured
  1451  // each in the HTTP connection manager and the route level, the one configured here takes
  1452  // priority.
  1453  repeated type.tracing.v3.CustomTag custom_tags = 4;
  1454}
  1455
  1456// A virtual cluster is a way of specifying a regex matching rule against
  1457// certain important endpoints such that statistics are generated explicitly for
  1458// the matched requests. The reason this is useful is that when doing
  1459// prefix/path matching Envoy does not always know what the application
  1460// considers to be an endpoint. Thus, it’s impossible for Envoy to generically
  1461// emit per endpoint statistics. However, often systems have highly critical
  1462// endpoints that they wish to get “perfect” statistics on. Virtual cluster
  1463// statistics are perfect in the sense that they are emitted on the downstream
  1464// side such that they include network level failures.
  1465//
  1466// Documentation for :ref:`virtual cluster statistics <config_http_filters_router_vcluster_stats>`.
  1467//
  1468// .. note::
  1469//
  1470//    Virtual clusters are a useful tool, but we do not recommend setting up a virtual cluster for
  1471//    every application endpoint. This is both not easily maintainable and as well the matching and
  1472//    statistics output are not free.
  1473message VirtualCluster {
  1474  option (udpa.annotations.versioning).previous_message_type =
  1475      "envoy.config.route.v3.VirtualCluster";
  1476
  1477  reserved 1, 3;
  1478
  1479  reserved "pattern", "method";
  1480
  1481  // Specifies a list of header matchers to use for matching requests. Each specified header must
  1482  // match. The pseudo-headers `:path` and `:method` can be used to match the request path and
  1483  // method, respectively.
  1484  repeated HeaderMatcher headers = 4;
  1485
  1486  // Specifies the name of the virtual cluster. The virtual cluster name as well
  1487  // as the virtual host name are used when emitting statistics. The statistics are emitted by the
  1488  // router filter and are documented :ref:`here <config_http_filters_router_stats>`.
  1489  string name = 2 [(validate.rules).string = {min_len: 1}];
  1490}
  1491
  1492// Global rate limiting :ref:`architecture overview <arch_overview_global_rate_limit>`.
  1493message RateLimit {
  1494  option (udpa.annotations.versioning).previous_message_type = "envoy.config.route.v3.RateLimit";
  1495
  1496  // [#next-free-field: 10]
  1497  message Action {
  1498    option (udpa.annotations.versioning).previous_message_type =
  1499        "envoy.config.route.v3.RateLimit.Action";
  1500
  1501    // The following descriptor entry is appended to the descriptor:
  1502    //
  1503    // .. code-block:: cpp
  1504    //
  1505    //   ("source_cluster", "<local service cluster>")
  1506    //
  1507    // <local service cluster> is derived from the :option:`--service-cluster` option.
  1508    message SourceCluster {
  1509      option (udpa.annotations.versioning).previous_message_type =
  1510          "envoy.config.route.v3.RateLimit.Action.SourceCluster";
  1511    }
  1512
  1513    // The following descriptor entry is appended to the descriptor:
  1514    //
  1515    // .. code-block:: cpp
  1516    //
  1517    //   ("destination_cluster", "<routed target cluster>")
  1518    //
  1519    // Once a request matches against a route table rule, a routed cluster is determined by one of
  1520    // the following :ref:`route table configuration <envoy_api_msg_config.route.v4alpha.RouteConfiguration>`
  1521    // settings:
  1522    //
  1523    // * :ref:`cluster <envoy_api_field_config.route.v4alpha.RouteAction.cluster>` indicates the upstream cluster
  1524    //   to route to.
  1525    // * :ref:`weighted_clusters <envoy_api_field_config.route.v4alpha.RouteAction.weighted_clusters>`
  1526    //   chooses a cluster randomly from a set of clusters with attributed weight.
  1527    // * :ref:`cluster_header <envoy_api_field_config.route.v4alpha.RouteAction.cluster_header>` indicates which
  1528    //   header in the request contains the target cluster.
  1529    message DestinationCluster {
  1530      option (udpa.annotations.versioning).previous_message_type =
  1531          "envoy.config.route.v3.RateLimit.Action.DestinationCluster";
  1532    }
  1533
  1534    // The following descriptor entry is appended when a header contains a key that matches the
  1535    // *header_name*:
  1536    //
  1537    // .. code-block:: cpp
  1538    //
  1539    //   ("<descriptor_key>", "<header_value_queried_from_header>")
  1540    message RequestHeaders {
  1541      option (udpa.annotations.versioning).previous_message_type =
  1542          "envoy.config.route.v3.RateLimit.Action.RequestHeaders";
  1543
  1544      // The header name to be queried from the request headers. The header’s
  1545      // value is used to populate the value of the descriptor entry for the
  1546      // descriptor_key.
  1547      string header_name = 1
  1548          [(validate.rules).string = {min_len: 1 well_known_regex: HTTP_HEADER_NAME strict: false}];
  1549
  1550      // The key to use in the descriptor entry.
  1551      string descriptor_key = 2 [(validate.rules).string = {min_len: 1}];
  1552
  1553      // If set to true, Envoy skips the descriptor while calling rate limiting service
  1554      // when header is not present in the request. By default it skips calling the
  1555      // rate limiting service if this header is not present in the request.
  1556      bool skip_if_absent = 3;
  1557    }
  1558
  1559    // The following descriptor entry is appended to the descriptor and is populated using the
  1560    // trusted address from :ref:`x-forwarded-for <config_http_conn_man_headers_x-forwarded-for>`:
  1561    //
  1562    // .. code-block:: cpp
  1563    //
  1564    //   ("remote_address", "<trusted address from x-forwarded-for>")
  1565    message RemoteAddress {
  1566      option (udpa.annotations.versioning).previous_message_type =
  1567          "envoy.config.route.v3.RateLimit.Action.RemoteAddress";
  1568    }
  1569
  1570    // The following descriptor entry is appended to the descriptor:
  1571    //
  1572    // .. code-block:: cpp
  1573    //
  1574    //   ("generic_key", "<descriptor_value>")
  1575    message GenericKey {
  1576      option (udpa.annotations.versioning).previous_message_type =
  1577          "envoy.config.route.v3.RateLimit.Action.GenericKey";
  1578
  1579      // The value to use in the descriptor entry.
  1580      string descriptor_value = 1 [(validate.rules).string = {min_len: 1}];
  1581
  1582      // An optional key to use in the descriptor entry. If not set it defaults
  1583      // to 'generic_key' as the descriptor key.
  1584      string descriptor_key = 2;
  1585    }
  1586
  1587    // The following descriptor entry is appended to the descriptor:
  1588    //
  1589    // .. code-block:: cpp
  1590    //
  1591    //   ("header_match", "<descriptor_value>")
  1592    message HeaderValueMatch {
  1593      option (udpa.annotations.versioning).previous_message_type =
  1594          "envoy.config.route.v3.RateLimit.Action.HeaderValueMatch";
  1595
  1596      // The value to use in the descriptor entry.
  1597      string descriptor_value = 1 [(validate.rules).string = {min_len: 1}];
  1598
  1599      // If set to true, the action will append a descriptor entry when the
  1600      // request matches the headers. If set to false, the action will append a
  1601      // descriptor entry when the request does not match the headers. The
  1602      // default value is true.
  1603      google.protobuf.BoolValue expect_match = 2;
  1604
  1605      // Specifies a set of headers that the rate limit action should match
  1606      // on. The action will check the request’s headers against all the
  1607      // specified headers in the config. A match will happen if all the
  1608      // headers in the config are present in the request with the same values
  1609      // (or based on presence if the value field is not in the config).
  1610      repeated HeaderMatcher headers = 3 [(validate.rules).repeated = {min_items: 1}];
  1611    }
  1612
  1613    // The following descriptor entry is appended when the
  1614    // :ref:`dynamic metadata <well_known_dynamic_metadata>` contains a key value:
  1615    //
  1616    // .. code-block:: cpp
  1617    //
  1618    //   ("<descriptor_key>", "<value_queried_from_dynamic_metadata>")
  1619    //
  1620    // .. attention::
  1621    //   This action has been deprecated in favor of the :ref:`metadata <envoy_api_msg_config.route.v4alpha.RateLimit.Action.MetaData>` action
  1622    message DynamicMetaData {
  1623      option (udpa.annotations.versioning).previous_message_type =
  1624          "envoy.config.route.v3.RateLimit.Action.DynamicMetaData";
  1625
  1626      // The key to use in the descriptor entry.
  1627      string descriptor_key = 1 [(validate.rules).string = {min_len: 1}];
  1628
  1629      // Metadata struct that defines the key and path to retrieve the string value. A match will
  1630      // only happen if the value in the dynamic metadata is of type string.
  1631      type.metadata.v3.MetadataKey metadata_key = 2 [(validate.rules).message = {required: true}];
  1632
  1633      // An optional value to use if *metadata_key* is empty. If not set and
  1634      // no value is present under the metadata_key then no descriptor is generated.
  1635      string default_value = 3;
  1636    }
  1637
  1638    // The following descriptor entry is appended when the metadata contains a key value:
  1639    //
  1640    // .. code-block:: cpp
  1641    //
  1642    //   ("<descriptor_key>", "<value_queried_from_metadata>")
  1643    message MetaData {
  1644      option (udpa.annotations.versioning).previous_message_type =
  1645          "envoy.config.route.v3.RateLimit.Action.MetaData";
  1646
  1647      enum Source {
  1648        // Query :ref:`dynamic metadata <well_known_dynamic_metadata>`
  1649        DYNAMIC = 0;
  1650
  1651        // Query :ref:`route entry metadata <envoy_api_field_config.route.v4alpha.Route.metadata>`
  1652        ROUTE_ENTRY = 1;
  1653      }
  1654
  1655      // The key to use in the descriptor entry.
  1656      string descriptor_key = 1 [(validate.rules).string = {min_len: 1}];
  1657
  1658      // Metadata struct that defines the key and path to retrieve the string value. A match will
  1659      // only happen if the value in the metadata is of type string.
  1660      type.metadata.v3.MetadataKey metadata_key = 2 [(validate.rules).message = {required: true}];
  1661
  1662      // An optional value to use if *metadata_key* is empty. If not set and
  1663      // no value is present under the metadata_key then no descriptor is generated.
  1664      string default_value = 3;
  1665
  1666      // Source of metadata
  1667      Source source = 4 [(validate.rules).enum = {defined_only: true}];
  1668    }
  1669
  1670    reserved 7;
  1671
  1672    reserved "dynamic_metadata";
  1673
  1674    oneof action_specifier {
  1675      option (validate.required) = true;
  1676
  1677      // Rate limit on source cluster.
  1678      SourceCluster source_cluster = 1;
  1679
  1680      // Rate limit on destination cluster.
  1681      DestinationCluster destination_cluster = 2;
  1682
  1683      // Rate limit on request headers.
  1684      RequestHeaders request_headers = 3;
  1685
  1686      // Rate limit on remote address.
  1687      RemoteAddress remote_address = 4;
  1688
  1689      // Rate limit on a generic key.
  1690      GenericKey generic_key = 5;
  1691
  1692      // Rate limit on the existence of request headers.
  1693      HeaderValueMatch header_value_match = 6;
  1694
  1695      // Rate limit on metadata.
  1696      MetaData metadata = 8;
  1697
  1698      // Rate limit descriptor extension. See the rate limit descriptor extensions documentation.
  1699      core.v4alpha.TypedExtensionConfig extension = 9;
  1700    }
  1701  }
  1702
  1703  message Override {
  1704    option (udpa.annotations.versioning).previous_message_type =
  1705        "envoy.config.route.v3.RateLimit.Override";
  1706
  1707    // Fetches the override from the dynamic metadata.
  1708    message DynamicMetadata {
  1709      option (udpa.annotations.versioning).previous_message_type =
  1710          "envoy.config.route.v3.RateLimit.Override.DynamicMetadata";
  1711
  1712      // Metadata struct that defines the key and path to retrieve the struct value.
  1713      // The value must be a struct containing an integer "requests_per_unit" property
  1714      // and a "unit" property with a value parseable to :ref:`RateLimitUnit
  1715      // enum <envoy_api_enum_type.v3.RateLimitUnit>`
  1716      type.metadata.v3.MetadataKey metadata_key = 1 [(validate.rules).message = {required: true}];
  1717    }
  1718
  1719    oneof override_specifier {
  1720      option (validate.required) = true;
  1721
  1722      // Limit override from dynamic metadata.
  1723      DynamicMetadata dynamic_metadata = 1;
  1724    }
  1725  }
  1726
  1727  // Refers to the stage set in the filter. The rate limit configuration only
  1728  // applies to filters with the same stage number. The default stage number is
  1729  // 0.
  1730  //
  1731  // .. note::
  1732  //
  1733  //   The filter supports a range of 0 - 10 inclusively for stage numbers.
  1734  google.protobuf.UInt32Value stage = 1 [(validate.rules).uint32 = {lte: 10}];
  1735
  1736  // The key to be set in runtime to disable this rate limit configuration.
  1737  string disable_key = 2;
  1738
  1739  // A list of actions that are to be applied for this rate limit configuration.
  1740  // Order matters as the actions are processed sequentially and the descriptor
  1741  // is composed by appending descriptor entries in that sequence. If an action
  1742  // cannot append a descriptor entry, no descriptor is generated for the
  1743  // configuration. See :ref:`composing actions
  1744  // <config_http_filters_rate_limit_composing_actions>` for additional documentation.
  1745  repeated Action actions = 3 [(validate.rules).repeated = {min_items: 1}];
  1746
  1747  // An optional limit override to be appended to the descriptor produced by this
  1748  // rate limit configuration. If the override value is invalid or cannot be resolved
  1749  // from metadata, no override is provided. See :ref:`rate limit override
  1750  // <config_http_filters_rate_limit_rate_limit_override>` for more information.
  1751  Override limit = 4;
  1752}
  1753
  1754// .. attention::
  1755//
  1756//   Internally, Envoy always uses the HTTP/2 *:authority* header to represent the HTTP/1 *Host*
  1757//   header. Thus, if attempting to match on *Host*, match on *:authority* instead.
  1758//
  1759// .. attention::
  1760//
  1761//   To route on HTTP method, use the special HTTP/2 *:method* header. This works for both
  1762//   HTTP/1 and HTTP/2 as Envoy normalizes headers. E.g.,
  1763//
  1764//   .. code-block:: json
  1765//
  1766//     {
  1767//       "name": ":method",
  1768//       "exact_match": "POST"
  1769//     }
  1770//
  1771// .. attention::
  1772//   In the absence of any header match specifier, match will default to :ref:`present_match
  1773//   <envoy_api_field_config.route.v4alpha.HeaderMatcher.present_match>`. i.e, a request that has the :ref:`name
  1774//   <envoy_api_field_config.route.v4alpha.HeaderMatcher.name>` header will match, regardless of the header's
  1775//   value.
  1776//
  1777//  [#next-major-version: HeaderMatcher should be refactored to use StringMatcher.]
  1778// [#next-free-field: 13]
  1779message HeaderMatcher {
  1780  option (udpa.annotations.versioning).previous_message_type =
  1781      "envoy.config.route.v3.HeaderMatcher";
  1782
  1783  reserved 2, 3, 5;
  1784
  1785  reserved "regex_match";
  1786
  1787  // Specifies the name of the header in the request.
  1788  string name = 1
  1789      [(validate.rules).string = {min_len: 1 well_known_regex: HTTP_HEADER_NAME strict: false}];
  1790
  1791  // Specifies how the header match will be performed to route the request.
  1792  oneof header_match_specifier {
  1793    // If specified, header match will be performed based on the value of the header.
  1794    string exact_match = 4;
  1795
  1796    // If specified, this regex string is a regular expression rule which implies the entire request
  1797    // header value must match the regex. The rule will not match if only a subsequence of the
  1798    // request header value matches the regex.
  1799    type.matcher.v4alpha.RegexMatcher safe_regex_match = 11;
  1800
  1801    // If specified, header match will be performed based on range.
  1802    // The rule will match if the request header value is within this range.
  1803    // The entire request header value must represent an integer in base 10 notation: consisting of
  1804    // an optional plus or minus sign followed by a sequence of digits. The rule will not match if
  1805    // the header value does not represent an integer. Match will fail for empty values, floating
  1806    // point numbers or if only a subsequence of the header value is an integer.
  1807    //
  1808    // Examples:
  1809    //
  1810    // * For range [-10,0), route will match for header value -1, but not for 0, "somestring", 10.9,
  1811    //   "-1somestring"
  1812    type.v3.Int64Range range_match = 6;
  1813
  1814    // If specified, header match will be performed based on whether the header is in the
  1815    // request.
  1816    bool present_match = 7;
  1817
  1818    // If specified, header match will be performed based on the prefix of the header value.
  1819    // Note: empty prefix is not allowed, please use present_match instead.
  1820    //
  1821    // Examples:
  1822    //
  1823    // * The prefix *abcd* matches the value *abcdxyz*, but not for *abcxyz*.
  1824    string prefix_match = 9 [(validate.rules).string = {min_len: 1}];
  1825
  1826    // If specified, header match will be performed based on the suffix of the header value.
  1827    // Note: empty suffix is not allowed, please use present_match instead.
  1828    //
  1829    // Examples:
  1830    //
  1831    // * The suffix *abcd* matches the value *xyzabcd*, but not for *xyzbcd*.
  1832    string suffix_match = 10 [(validate.rules).string = {min_len: 1}];
  1833
  1834    // If specified, header match will be performed based on whether the header value contains
  1835    // the given value or not.
  1836    // Note: empty contains match is not allowed, please use present_match instead.
  1837    //
  1838    // Examples:
  1839    //
  1840    // * The value *abcd* matches the value *xyzabcdpqr*, but not for *xyzbcdpqr*.
  1841    string contains_match = 12 [(validate.rules).string = {min_len: 1}];
  1842  }
  1843
  1844  // If specified, the match result will be inverted before checking. Defaults to false.
  1845  //
  1846  // Examples:
  1847  //
  1848  // * The regex ``\d{3}`` does not match the value *1234*, so it will match when inverted.
  1849  // * The range [-10,0) will match the value -1, so it will not match when inverted.
  1850  bool invert_match = 8;
  1851}
  1852
  1853// Query parameter matching treats the query string of a request's :path header
  1854// as an ampersand-separated list of keys and/or key=value elements.
  1855// [#next-free-field: 7]
  1856message QueryParameterMatcher {
  1857  option (udpa.annotations.versioning).previous_message_type =
  1858      "envoy.config.route.v3.QueryParameterMatcher";
  1859
  1860  reserved 3, 4;
  1861
  1862  reserved "value", "regex";
  1863
  1864  // Specifies the name of a key that must be present in the requested
  1865  // *path*'s query string.
  1866  string name = 1 [(validate.rules).string = {min_len: 1 max_bytes: 1024}];
  1867
  1868  oneof query_parameter_match_specifier {
  1869    // Specifies whether a query parameter value should match against a string.
  1870    type.matcher.v4alpha.StringMatcher string_match = 5
  1871        [(validate.rules).message = {required: true}];
  1872
  1873    // Specifies whether a query parameter should be present.
  1874    bool present_match = 6;
  1875  }
  1876}
  1877
  1878// HTTP Internal Redirect :ref:`architecture overview <arch_overview_internal_redirects>`.
  1879message InternalRedirectPolicy {
  1880  option (udpa.annotations.versioning).previous_message_type =
  1881      "envoy.config.route.v3.InternalRedirectPolicy";
  1882
  1883  // An internal redirect is not handled, unless the number of previous internal redirects that a
  1884  // downstream request has encountered is lower than this value.
  1885  // In the case where a downstream request is bounced among multiple routes by internal redirect,
  1886  // the first route that hits this threshold, or does not set :ref:`internal_redirect_policy
  1887  // <envoy_api_field_config.route.v4alpha.RouteAction.internal_redirect_policy>`
  1888  // will pass the redirect back to downstream.
  1889  //
  1890  // If not specified, at most one redirect will be followed.
  1891  google.protobuf.UInt32Value max_internal_redirects = 1;
  1892
  1893  // Defines what upstream response codes are allowed to trigger internal redirect. If unspecified,
  1894  // only 302 will be treated as internal redirect.
  1895  // Only 301, 302, 303, 307 and 308 are valid values. Any other codes will be ignored.
  1896  repeated uint32 redirect_response_codes = 2 [(validate.rules).repeated = {max_items: 5}];
  1897
  1898  // Specifies a list of predicates that are queried when an upstream response is deemed
  1899  // to trigger an internal redirect by all other criteria. Any predicate in the list can reject
  1900  // the redirect, causing the response to be proxied to downstream.
  1901  repeated core.v4alpha.TypedExtensionConfig predicates = 3;
  1902
  1903  // Allow internal redirect to follow a target URI with a different scheme than the value of
  1904  // x-forwarded-proto. The default is false.
  1905  bool allow_cross_scheme_redirect = 4;
  1906}

View as plain text