Repository: envoyproxy/envoy
File: api/envoy/extensions/filters/http/ext_authz/v3/ext_authz.proto (Protocol Buffers)

Code before:
  //
  // .. note::
  //   Client request headers with the same key will be overridden.
  repeated config.core.v3.HeaderValue headers_to_add = 2;
}

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

  // When this :ref:`list <envoy_v3_api_msg_type.matcher.v3.ListStringMatcher>` is set, authorization
  // response headers that have a correspondent match will be added to the original client request.
  //
  // .. note::
  //   Existing headers will be overridden.
  type.matcher.v3.ListStringMatcher allowed_upstream_headers = 1;

  // When this :ref:`list <envoy_v3_api_msg_type.matcher.v3.ListStringMatcher>` is set, authorization
  // response headers that have a correspondent match will be added to the original client request.
  //
  // .. note::
  //   Existing headers will be appended.
  type.matcher.v3.ListStringMatcher allowed_upstream_headers_to_append = 3;

  // When this :ref:`list <envoy_v3_api_msg_type.matcher.v3.ListStringMatcher>` is set, authorization
  // response headers that have a correspondent match will be added to the client's response.
  //
  // .. note::
  //   When this list is *not* set, all the authorization response headers, except
  //   ``Authority (Host)``, will be in the response to the client.
  //
  // When a header is included in this list, ``Path``, ``Status``, ``Content-Length``, ``WWW-Authenticate`` and
  // ``Location`` are automatically added.
  type.matcher.v3.ListStringMatcher allowed_client_headers = 2;

  // When this :ref:`list <envoy_v3_api_msg_type.matcher.v3.ListStringMatcher>` is set, authorization
  // response headers that have a correspondent match will be added to the client's response when
  // the authorization response itself is successful, i.e. not failed or denied. When this list is
  // *not* set, no additional headers will be added to the client's response on success.
  type.matcher.v3.ListStringMatcher allowed_client_headers_on_success = 4;

  // When this :ref:`list <envoy_v3_api_msg_type.matcher.v3.ListStringMatcher>` is set, authorization
  // response headers that have a correspondent match will be emitted as dynamic metadata to be consumed
  // by the next filter. This metadata lives in a namespace specified by the canonical name of extension filter
  // that requires it:
  //
  // - :ref:`envoy.filters.http.ext_authz <config_http_filters_ext_authz_dynamic_metadata>` for HTTP filter.
  // - :ref:`envoy.filters.network.ext_authz <config_network_filters_ext_authz_dynamic_metadata>` for network filter.
  type.matcher.v3.ListStringMatcher dynamic_metadata_from_headers = 5;
}

Review comment (suggestion):
Just realized that this reference a type, and not the field's name (which IMHO may also not really needed, as the type will have the link).
Not sure if you want to address it as part of this PR (seems like a recurrent pattern in different fields of this file), or just keep as is.

Code after:
  //
  // .. note::
  //   Client request headers with the same key will be overridden.
  repeated config.core.v3.HeaderValue headers_to_add = 2;
}

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

  // When this :ref:`list <envoy_v3_api_msg_type.matcher.v3.ListStringMatcher>` is set, authorization
  // response headers that have a correspondent match will be added to the original client request.
  //
  // .. note::
  //   Existing headers will be overridden.
  type.matcher.v3.ListStringMatcher allowed_upstream_headers = 1;

  // When this :ref:`list <envoy_v3_api_msg_type.matcher.v3.ListStringMatcher>` is set, authorization
  // response headers that have a correspondent match will be added to the original client request.
  //
  // .. note::
  //   Existing headers will be appended.
  type.matcher.v3.ListStringMatcher allowed_upstream_headers_to_append = 3;

  // When this :ref:`list <envoy_v3_api_msg_type.matcher.v3.ListStringMatcher>` is set, authorization
  // response headers that have a correspondent match will be added to the client's response.
  // When a header is included in this list, ``Path``, ``Status``, ``Content-Length``, ``WWW-Authenticate`` and
  // ``Location`` are automatically added.
  //
  // .. note::
  //   When this list is *not* set, all the authorization response headers, except
  //   ``Authority (Host)``, will be in the response to the client.
  type.matcher.v3.ListStringMatcher allowed_client_headers = 2;

  // When this :ref:`list <envoy_v3_api_msg_type.matcher.v3.ListStringMatcher>` is set, authorization
  // response headers that have a correspondent match will be added to the client's response when
  // the authorization response itself is successful, i.e. not failed or denied. When this list is
  // *not* set, no additional headers will be added to the client's response on success.
  type.matcher.v3.ListStringMatcher allowed_client_headers_on_success = 4;

  // When this :ref:`list <envoy_v3_api_msg_type.matcher.v3.ListStringMatcher>` is set, authorization
  // response headers that have a correspondent match will be emitted as dynamic metadata to be consumed
  // by the next filter. This metadata lives in a namespace specified by the canonical name of extension filter
  // that requires it:
  //
  // - :ref:`envoy.filters.http.ext_authz <config_http_filters_ext_authz_dynamic_metadata>` for HTTP filter.
  // - :ref:`envoy.filters.network.ext_authz <config_network_filters_ext_authz_dynamic_metadata>` for network filter.
  type.matcher.v3.ListStringMatcher dynamic_metadata_from_headers = 5;
}