// 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.config.common.mutation_rules.v3;

import "envoy/config/core/v3/base.proto";
import "envoy/type/matcher/v3/regex.proto";

import "google/protobuf/wrappers.proto";

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

option java_package = "io.envoyproxy.envoy.config.common.mutation_rules.v3";
option java_outer_classname = "MutationRulesProto";
option java_multiple_files = true;
option go_package = "github.com/envoyproxy/go-control-plane/envoy/config/common/mutation_rules/v3;mutation_rulesv3";
option (udpa.annotations.file_status).package_version_status = ACTIVE;

// [#protodoc-title: Header mutation rules]

// The HeaderMutationRules structure specifies what headers may be
// manipulated by a processing filter. This set of rules makes it
// possible to control which modifications a filter may make.
//
// By default, an external processing server may add, modify, or remove
// any header except for an "Envoy internal" header (which is typically
// denoted by an x-envoy prefix) or specific headers that may affect
// further filter processing:
//
// * ``host``
// * ``:authority``
// * ``:scheme``
// * ``:method``
//
// Every attempt to add, change, append, or remove a header will be
// tested against the rules here. Disallowed header mutations will be
// ignored unless ``disallow_is_error`` is set to true.
//
// Attempts to remove headers are further constrained -- regardless of the
// settings, system-defined headers (that start with ``:``) and the ``host``
// header may never be removed.
//
// In addition, a counter will be incremented whenever a mutation is
// rejected. In the ext_proc filter, that counter is named
// ``rejected_header_mutations``.
// [#next-free-field: 8]
message HeaderMutationRules {
  // By default, certain headers that could affect processing of subsequent
  // filters or request routing cannot be modified. These headers are
  // ``host``, ``:authority``, ``:scheme``, and ``:method``. Setting this parameter
  // to true allows these headers to be modified as well.
  google.protobuf.BoolValue allow_all_routing = 1;

  // If true, allow modification of envoy internal headers. By default, these
  // start with ``x-envoy`` but this may be overridden in the ``Bootstrap``
  // configuration using the
  // :ref:`header_prefix <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.header_prefix>`
  // field. Default is false.
  google.protobuf.BoolValue allow_envoy = 2;

  // If true, prevent modification of any system header, defined as a header
  // that starts with a ``:`` character, regardless of any other settings.
  // A processing server may still override the ``:status`` of an HTTP response
  // using an ``ImmediateResponse`` message. Default is false.
  google.protobuf.BoolValue disallow_system = 3;

  // If true, prevent modifications of all header values, regardless of any
  // other settings. A processing server may still override the ``:status``
  // of an HTTP response using an ``ImmediateResponse`` message. Default is false.
  google.protobuf.BoolValue disallow_all = 4;

  // If set, specifically allow any header that matches this regular
  // expression. This overrides all other settings except for
  // ``disallow_expression``.
  type.matcher.v3.RegexMatcher allow_expression = 5;

  // If set, specifically disallow any header that matches this regular
  // expression regardless of any other settings.
  type.matcher.v3.RegexMatcher disallow_expression = 6;

  // If true, and if the rules in this list cause a header mutation to be
  // disallowed, then the filter using this configuration will terminate the
  // request with a 500 error. In addition, regardless of the setting of this
  // parameter, any attempt to set, add, or modify a disallowed header will
  // cause the ``rejected_header_mutations`` counter to be incremented.
  // Default is false.
  google.protobuf.BoolValue disallow_is_error = 7;
}

// The HeaderMutation structure specifies an action that may be taken on HTTP
// headers.
message HeaderMutation {
  oneof action {
    option (validate.required) = true;

    // Remove the specified header if it exists.
    string remove = 1
        [(validate.rules).string = {well_known_regex: HTTP_HEADER_VALUE strict: false}];

    // Append new header by the specified HeaderValueOption.
    core.v3.HeaderValueOption append = 2;
  }
}
