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

syntax = "proto3";

package envoy.extensions.filters.http.fault.v3;

import "envoy/config/route/v3/route_components.proto";
import "envoy/extensions/filters/common/fault/v3/fault.proto";
import "envoy/type/v3/percent.proto";

import "google/protobuf/struct.proto";
import "google/protobuf/wrappers.proto";

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

option java_package = "io.envoyproxy.envoy.extensions.filters.http.fault.v3";
option java_outer_classname = "FaultProto";
option java_multiple_files = true;
option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/http/fault/v3;faultv3";
option (udpa.annotations.file_status).package_version_status = ACTIVE;

// [#protodoc-title: Fault Injection]
// Fault Injection :ref:`configuration overview <config_http_filters_fault_injection>`.
// [#extension: envoy.filters.http.fault]

// [#next-free-field: 6]
message FaultAbort {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.config.filter.http.fault.v2.FaultAbort";

  // Fault aborts are controlled via an HTTP header (if applicable). See the
  // :ref:`HTTP fault filter <config_http_filters_fault_injection_http_header>` documentation for
  // more information.
  message HeaderAbort {
    option (udpa.annotations.versioning).previous_message_type =
        "envoy.config.filter.http.fault.v2.FaultAbort.HeaderAbort";
  }

  reserved 1;

  oneof error_type {
    option (validate.required) = true;

    // HTTP status code to use to abort the HTTP request.
    uint32 http_status = 2 [(validate.rules).uint32 = {lt: 600 gte: 200}];

    // gRPC status code to use to abort the gRPC request.
    uint32 grpc_status = 5;

    // Fault aborts are controlled via an HTTP header (if applicable).
    HeaderAbort header_abort = 4;
  }

  // The percentage of requests/operations/connections that will be aborted with the error code
  // provided.
  type.v3.FractionalPercent percentage = 3;
}

// [#next-free-field: 17]
message HTTPFault {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.config.filter.http.fault.v2.HTTPFault";

  // If specified, the filter will inject delays based on the values in the
  // object.
  common.fault.v3.FaultDelay delay = 1;

  // If specified, the filter will abort requests based on the values in
  // the object. At least ``abort`` or ``delay`` must be specified.
  FaultAbort abort = 2;

  // Specifies the name of the (destination) upstream cluster that the
  // filter should match on. Fault injection will be restricted to requests
  // bound to the specific upstream cluster.
  string upstream_cluster = 3;

  // Specifies a set of headers that the filter should match on. The fault
  // injection filter can be applied selectively to requests that match a set of
  // headers specified in the fault filter config. The chances of actual fault
  // injection further depend on the value of the :ref:`percentage
  // <envoy_v3_api_field_extensions.filters.http.fault.v3.FaultAbort.percentage>` field.
  // The filter will check the request's headers against all the specified
  // headers in the filter config. A match will happen if all the headers in the
  // config are present in the request with the same values (or based on
  // presence if the ``value`` field is not in the config).
  repeated config.route.v3.HeaderMatcher headers = 4;

  // Faults are injected for the specified list of downstream hosts. If this
  // setting is not set, faults are injected for all downstream nodes.
  // Downstream node name is taken from :ref:`the HTTP
  // x-envoy-downstream-service-node
  // <config_http_conn_man_headers_downstream-service-node>` header and compared
  // against downstream_nodes list.
  repeated string downstream_nodes = 5;

  // The maximum number of faults that can be active at a single time via the configured fault
  // filter. Note that because this setting can be overridden at the route level, it's possible
  // for the number of active faults to be greater than this value (if injected via a different
  // route). If not specified, defaults to unlimited. This setting can be overridden via
  // ``runtime <config_http_filters_fault_injection_runtime>`` and any faults that are not injected
  // due to overflow will be indicated via the ``faults_overflow
  // <config_http_filters_fault_injection_stats>`` stat.
  //
  // .. attention::
  //   Like other :ref:`circuit breakers <arch_overview_circuit_break>` in Envoy, this is a fuzzy
  //   limit. It's possible for the number of active faults to rise slightly above the configured
  //   amount due to the implementation details.
  google.protobuf.UInt32Value max_active_faults = 6;

  // The response rate limit to be applied to the response body of the stream. When configured,
  // the percentage can be overridden by the :ref:`fault.http.rate_limit.response_percent
  // <config_http_filters_fault_injection_runtime>` runtime key.
  //
  // .. attention::
  //  This is a per-stream limit versus a connection level limit. This means that concurrent streams
  //  will each get an independent limit.
  common.fault.v3.FaultRateLimit response_rate_limit = 7;

  // The runtime key to override the :ref:`default <config_http_filters_fault_injection_runtime>`
  // runtime. The default is: fault.http.delay.fixed_delay_percent
  string delay_percent_runtime = 8;

  // The runtime key to override the :ref:`default <config_http_filters_fault_injection_runtime>`
  // runtime. The default is: fault.http.abort.abort_percent
  string abort_percent_runtime = 9;

  // The runtime key to override the :ref:`default <config_http_filters_fault_injection_runtime>`
  // runtime. The default is: fault.http.delay.fixed_duration_ms
  string delay_duration_runtime = 10;

  // The runtime key to override the :ref:`default <config_http_filters_fault_injection_runtime>`
  // runtime. The default is: fault.http.abort.http_status
  string abort_http_status_runtime = 11;

  // The runtime key to override the :ref:`default <config_http_filters_fault_injection_runtime>`
  // runtime. The default is: fault.http.max_active_faults
  string max_active_faults_runtime = 12;

  // The runtime key to override the :ref:`default <config_http_filters_fault_injection_runtime>`
  // runtime. The default is: fault.http.rate_limit.response_percent
  string response_rate_limit_percent_runtime = 13;

  // The runtime key to override the :ref:`default <config_http_filters_fault_injection_runtime>`
  // runtime. The default is: fault.http.abort.grpc_status
  string abort_grpc_status_runtime = 14;

  // To control whether stats storage is allocated dynamically for each downstream server.
  // If set to true, "x-envoy-downstream-service-cluster" field of header will be ignored by this filter.
  // If set to false, dynamic stats storage will be allocated for the downstream cluster name.
  // Default value is false.
  bool disable_downstream_cluster_stats = 15;

  // When an abort or delay fault is executed, the metadata struct provided here will be added to the
  // request's dynamic metadata under the namespace corresponding to the name of the fault filter.
  // This data can be logged as part of Access Logs using the :ref:`command operator
  // <config_access_log_command_operators>` %DYNAMIC_METADATA(NAMESPACE)%, where NAMESPACE is the name of
  // the fault filter.
  google.protobuf.Struct filter_metadata = 16;
}
