syntax = "proto3";

package envoy.config.core.v3;

import "envoy/config/core/v3/extension.proto";
import "envoy/type/matcher/v3/string.proto";
import "envoy/type/v3/percent.proto";

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

import "xds/annotations/v3/status.proto";

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

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

// [#protodoc-title: Protocol options]

// [#not-implemented-hide:]
message TcpProtocolOptions {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.api.v2.core.TcpProtocolOptions";
}

// Config for keepalive probes in a QUIC connection.
//
// .. note::
//
//   QUIC keep-alive probing packets work differently from HTTP/2 keep-alive PINGs in a sense that the probing packet
//   itself doesn't timeout waiting for a probing response. QUIC has a shorter idle timeout than TCP, so it doesn't rely on such probing to discover dead connections. If the peer fails to respond, the connection will idle timeout eventually. Thus, they are configured differently from :ref:`connection_keepalive <envoy_v3_api_field_config.core.v3.Http2ProtocolOptions.connection_keepalive>`.
message QuicKeepAliveSettings {
  // The max interval for a connection to send keep-alive probing packets (with ``PING`` or ``PATH_RESPONSE``). The value should be smaller than :ref:`connection idle_timeout <envoy_v3_api_field_config.listener.v3.QuicProtocolOptions.idle_timeout>` to prevent idle timeout while not less than ``1s`` to avoid throttling the connection or flooding the peer with probes.
  //
  // If :ref:`initial_interval <envoy_v3_api_field_config.core.v3.QuicKeepAliveSettings.initial_interval>` is absent or zero, a client connection will use this value to start probing.
  //
  // If zero, disable keepalive probing.
  // If absent, use the QUICHE default interval to probe.
  google.protobuf.Duration max_interval = 1;

  // The interval to send the first few keep-alive probing packets to prevent connection from hitting the idle timeout. Subsequent probes will be sent, each one with an interval exponentially longer than previous one, till it reaches :ref:`max_interval <envoy_v3_api_field_config.core.v3.QuicKeepAliveSettings.max_interval>`. And the probes afterwards will always use :ref:`max_interval <envoy_v3_api_field_config.core.v3.QuicKeepAliveSettings.max_interval>`.
  //
  // The value should be smaller than :ref:`connection idle_timeout <envoy_v3_api_field_config.listener.v3.QuicProtocolOptions.idle_timeout>` to prevent idle timeout and smaller than max_interval to take effect.
  //
  // If absent, disable keepalive probing for a server connection. For a client connection, if :ref:`max_interval <envoy_v3_api_field_config.core.v3.QuicKeepAliveSettings.max_interval>` is zero, do not keepalive, otherwise use max_interval or QUICHE default to probe all the time.
  google.protobuf.Duration initial_interval = 2 [(validate.rules).duration = {
    lte {}
    gte {nanos: 1000000}
  }];
}

// QUIC protocol options which apply to both downstream and upstream connections.
// [#next-free-field: 14]
message QuicProtocolOptions {
  // Config for QUIC connection migration across network interfaces, i.e. cellular to WIFI, upon
  // network change events from the platform, i.e. the current network gets
  // disconnected, or upon the QUIC detecting a bad connection. After migration, the
  // connection may be on a different network other than the default network
  // picked by the platform. Both iOS and Android will use a default network to interact with the internet, usually prefer unmetered network (WIFI)
  // over metered ones (cellular). And users can specify which network to be used as the default. A connection on non-default network is only allowed to
  // serve new requests for a certain period of time before being drained, and
  // meanwhile, QUIC will try to migrate to the default network if possible.
  message ConnectionMigrationSettings {
    // Config for options to migrate idle connections which aren't serving any requests.
    message MigrateIdleConnectionSettings {
      // If idle connections are allowed to be migrated, only migrate the connection
      // if it hasn't been idle for longer than this idle period. Otherwise, the
      // connection will be closed instead.
      // Default to 30s.
      google.protobuf.Duration max_idle_time_before_migration = 1
          [(validate.rules).duration = {gte {seconds: 1}}];
    }

    // Config whether and how to migrate idle connections.
    // If absent, idle connections will not be migrated but be closed upon
    // migration signals.
    MigrateIdleConnectionSettings migrate_idle_connections = 1;

    // After migrating to a non-default network interface, the connection will
    // only be allowed to stay on that network for up to this period of time before
    // being drained unless it migrates to the default network or that network
    // gets picked as the default by the device by then.
    // Default to 128s.
    google.protobuf.Duration max_time_on_non_default_network = 2
        [(validate.rules).duration = {gte {seconds: 1}}];
  }

  // Maximum number of streams that the client can negotiate per connection. ``100``
  // if not specified.
  google.protobuf.UInt32Value max_concurrent_streams = 1 [(validate.rules).uint32 = {gte: 1}];

  // `Initial stream-level flow-control receive window
  // <https://tools.ietf.org/html/draft-ietf-quic-transport-34#section-4.1>`_ size. Valid values range from
  // ``1`` to ``16777216`` (``2^24``, maximum supported by QUICHE) and defaults to ``16777216`` (``16 * 1024 * 1024``).
  //
  // .. note::
  //
  //   ``16384`` (``2^14``) is the minimum window size supported in Google QUIC. If configured smaller than it, we will use
  //   ``16384`` instead. QUICHE IETF QUIC implementation supports ``1`` byte window. We only support increasing the default
  //   window size now, so it's also the minimum.
  //
  // This field also acts as a soft limit on the number of bytes Envoy will buffer per-stream in the
  // QUIC stream send and receive buffers. Once the buffer reaches this pointer, watermark callbacks will fire to
  // stop the flow of data to the stream buffers.
  google.protobuf.UInt32Value initial_stream_window_size = 2
      [(validate.rules).uint32 = {lte: 16777216 gte: 1}];

  // Similar to ``initial_stream_window_size``, but for connection-level
  // flow-control. Valid values range from ``1`` to ``25165824`` (``24MB``, maximum supported by QUICHE) and defaults
  // to ``25165824`` (``24 * 1024 * 1024``).
  //
  // .. note::
  //
  //   ``16384`` (``2^14``) is the minimum window size supported in Google QUIC. We only support increasing the default
  //   window size now, so it's also the minimum.
  //
  google.protobuf.UInt32Value initial_connection_window_size = 3
      [(validate.rules).uint32 = {lte: 25165824 gte: 1}];

  // The number of timeouts that can occur before port migration is triggered for QUIC clients.
  // This defaults to ``4``. If set to ``0``, port migration will not occur on path degrading.
  // Timeout here refers to QUIC internal path degrading timeout mechanism, such as ``PTO``.
  // This has no effect on server sessions.
  google.protobuf.UInt32Value num_timeouts_to_trigger_port_migration = 4
      [(validate.rules).uint32 = {lte: 5 gte: 0}];

  // Probes the peer at the configured interval to solicit traffic, i.e. ``ACK`` or ``PATH_RESPONSE``, from the peer to push back connection idle timeout.
  // If absent, use the default keepalive behavior of which a client connection sends ``PING``s every ``15s``, and a server connection doesn't do anything.
  QuicKeepAliveSettings connection_keepalive = 5;

  // A comma-separated list of strings representing QUIC connection options defined in
  // `QUICHE <https://github.com/google/quiche/blob/main/quiche/quic/core/crypto/crypto_protocol.h>`_ and to be sent by upstream connections.
  string connection_options = 6;

  // A comma-separated list of strings representing QUIC client connection options defined in
  // `QUICHE <https://github.com/google/quiche/blob/main/quiche/quic/core/crypto/crypto_protocol.h>`_ and to be sent by upstream connections.
  string client_connection_options = 7;

  // The duration that a QUIC connection stays idle before it closes itself. If this field is not present, QUICHE
  // default ``600s`` will be applied.
  // For internal corporate network, a long timeout is often fine.
  // But for client facing network, ``30s`` is usually a good choice.
  // Do not add an upper bound here. A long idle timeout is useful for maintaining warm connections at non-front-line proxy for low QPS services.
  google.protobuf.Duration idle_network_timeout = 8
      [(validate.rules).duration = {gte {seconds: 1}}];

  // Maximum packet length for QUIC connections. It refers to the largest size of a QUIC packet that can be transmitted over the connection.
  // If not specified, one of the `default values in QUICHE <https://github.com/google/quiche/blob/main/quiche/quic/core/quic_constants.h>`_ is used.
  google.protobuf.UInt64Value max_packet_length = 9;

  // A customized UDP socket and a QUIC packet writer using the socket for
  // client connections. i.e. Mobile uses its own implementation to interact
  // with platform socket APIs.
  // If not present, the default platform-independent socket and writer will be used.
  // [#extension-category: envoy.quic.client_packet_writer]
  TypedExtensionConfig client_packet_writer = 10;

  // Enable QUIC `connection migration
  // <https://datatracker.ietf.org/doc/html/rfc9000#name-connection-migration>`
  // to a different network interface when the current network is degrading or
  // has become bad.
  // In order to use a different network interface other than the platform's default one,
  // a customized :ref:`client_packet_writer <envoy_v3_api_field_config.core.v3.QuicProtocolOptions.client_packet_writer>` needs to be configured to
  // create UDP sockets on non-default networks.
  // Only takes effect when runtime key ``envoy.reloadable_features.use_migration_in_quiche`` is true.
  // If absent, the feature will be disabled.
  // [#not-implemented-hide:]
  ConnectionMigrationSettings connection_migration = 11;

  // Timeout for a QUIC connection to schedule memory reduction callback when the network has been idle for a while.
  // This value should be smaller than the idle timeout to take effect.
  // If not specified, memory reduction is set to infinite by QUIC connection (disabled).
  google.protobuf.Duration memory_reduction_timeout = 12
      [(validate.rules).duration = {gte {seconds: 1}}];

  // If true, the QUIC connection will signal support for `SCONE <https://datatracker.ietf.org/doc/draft-ietf-scone-protocol/>`_ (Standard
  // Communication with Network Elements) and process SCONE packets.
  // If not present, the QUICHE default behavior will be used.
  google.protobuf.BoolValue enable_scone = 13;
}

message UpstreamHttpProtocolOptions {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.api.v2.core.UpstreamHttpProtocolOptions";

  // Set transport socket `SNI <https://en.wikipedia.org/wiki/Server_Name_Indication>`_ for new
  // upstream connections based on the downstream HTTP host/authority header or any other arbitrary
  // header when :ref:`override_auto_sni_header <envoy_v3_api_field_config.core.v3.UpstreamHttpProtocolOptions.override_auto_sni_header>`
  // is set, as seen by the :ref:`router filter <config_http_filters_router>`.
  // Does nothing if a filter before the http router filter sets the corresponding metadata.
  //
  // See :ref:`SNI configuration <start_quick_start_securing_sni_client>` for details on how this
  // interacts with other validation options.
  bool auto_sni = 1;

  // Automatic validate upstream presented certificate for new upstream connections based on the
  // downstream HTTP host/authority header or any other arbitrary header when :ref:`override_auto_sni_header <envoy_v3_api_field_config.core.v3.UpstreamHttpProtocolOptions.override_auto_sni_header>`
  // is set, as seen by the :ref:`router filter <config_http_filters_router>`.
  // This field is intended to be set with ``auto_sni`` field.
  // Does nothing if a filter before the http router filter sets the corresponding metadata.
  //
  // See :ref:`validation configuration <start_quick_start_securing_validation>` for how this interacts with
  // other validation options.
  bool auto_san_validation = 2;

  // An optional alternative to the host/authority header to be used for setting the SNI value.
  // It should be a valid downstream HTTP header, as seen by the
  // :ref:`router filter <config_http_filters_router>`.
  // If unset, host/authority header will be used for populating the SNI. If the specified header
  // is not found or the value is empty, host/authority header will be used instead.
  // This field is intended to be set with ``auto_sni`` and/or ``auto_san_validation`` fields.
  // If none of these fields are set then setting this would be a no-op.
  // Does nothing if a filter before the http router filter sets the corresponding metadata.
  string override_auto_sni_header = 3
      [(validate.rules).string = {well_known_regex: HTTP_HEADER_NAME ignore_empty: true}];
}

// Configures the alternate protocols cache which tracks alternate protocols that can be used to
// make an HTTP connection to an origin server. See https://tools.ietf.org/html/rfc7838 for
// HTTP Alternative Services and https://datatracker.ietf.org/doc/html/draft-ietf-dnsop-svcb-https-04
// for the "HTTPS" DNS resource record.
// [#next-free-field: 6]
message AlternateProtocolsCacheOptions {
  // Allows pre-populating the cache with HTTP/3 alternate protocols entries with a 7 day lifetime.
  // This will cause Envoy to attempt HTTP/3 to those upstreams, even if the upstreams have not
  // advertised HTTP/3 support. These entries will be overwritten by alt-svc
  // response headers or cached values.
  // As with regular cached entries, if the origin response would result in clearing an existing
  // alternate protocol cache entry, pre-populated entries will also be cleared.
  // Adding a cache entry with hostname=foo.com port=123 is the equivalent of getting
  // response headers
  // alt-svc: h3=:"123"; ma=86400" in a response to a request to foo.com:123
  message AlternateProtocolsCacheEntry {
    // The host name for the alternate protocol entry.
    string hostname = 1
        [(validate.rules).string = {well_known_regex: HTTP_HEADER_NAME ignore_empty: true}];

    // The port for the alternate protocol entry.
    uint32 port = 2 [(validate.rules).uint32 = {lt: 65535 gt: 0}];
  }

  // The name of the cache. Multiple named caches allow independent alternate protocols cache
  // configurations to operate within a single Envoy process using different configurations. All
  // alternate protocols cache options with the same name *must* be equal in all fields when
  // referenced from different configuration components. Configuration will fail to load if this is
  // not the case.
  string name = 1 [(validate.rules).string = {min_len: 1}];

  // The maximum number of entries that the cache will hold. If not specified defaults to ``1024``.
  //
  // .. note::
  //
  //   The implementation is approximate and enforced independently on each worker thread, thus
  //   it is possible for the maximum entries in the cache to go slightly above the configured
  //   value depending on timing. This is similar to how other circuit breakers work.
  google.protobuf.UInt32Value max_entries = 2 [(validate.rules).uint32 = {gt: 0}];

  // Allows configuring a persistent
  // :ref:`key value store <envoy_v3_api_msg_config.common.key_value.v3.KeyValueStoreConfig>` to flush
  // alternate protocols entries to disk.
  // This function is currently only supported if concurrency is 1
  // Cached entries will take precedence over pre-populated entries below.
  TypedExtensionConfig key_value_store_config = 3;

  // Allows pre-populating the cache with entries, as described above.
  repeated AlternateProtocolsCacheEntry prepopulated_entries = 4;

  // Optional list of hostnames suffixes for which Alt-Svc entries can be shared. For example, if
  // this list contained the value ``.c.example.com``, then an Alt-Svc entry for ``foo.c.example.com``
  // could be shared with ``bar.c.example.com`` but would not be shared with ``baz.example.com``. On
  // the other hand, if the list contained the value ``.example.com`` then all three hosts could share
  // Alt-Svc entries. Each entry must start with ``.``. If a hostname matches multiple suffixes, the
  // first listed suffix will be used.
  //
  // Since lookup in this list is O(n), it is recommended that the number of suffixes be limited.
  // [#not-implemented-hide:]
  repeated string canonical_suffixes = 5;
}

// [#next-free-field: 9]
message HttpProtocolOptions {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.api.v2.core.HttpProtocolOptions";

  // Action to take when Envoy receives client request with header names containing underscore
  // characters.
  // Underscore character is allowed in header names by the RFC-7230 and this behavior is implemented
  // as a security measure due to systems that treat '_' and '-' as interchangeable. Envoy by default allows client request headers with underscore
  // characters.
  enum HeadersWithUnderscoresAction {
    // Allow headers with underscores. This is the default behavior.
    ALLOW = 0;

    // Reject client request. HTTP/1 requests are rejected with ``HTTP 400`` status. HTTP/2 requests
    // end with the stream reset. The ``httpN.requests_rejected_with_underscores_in_headers`` counter
    // is incremented for each rejected request.
    REJECT_REQUEST = 1;

    // Drop the client header with name containing underscores. The header is dropped before the filter chain is
    // invoked and as such filters will not see dropped headers. The
    // ``httpN.dropped_headers_with_underscores`` is incremented for each dropped header.
    DROP_HEADER = 2;
  }

  // The idle timeout for connections. The idle timeout is defined as the
  // period in which there are no active requests. When the
  // idle timeout is reached the connection will be closed. If the connection is an HTTP/2
  // downstream connection a drain sequence will occur prior to closing the connection, see
  // :ref:`drain_timeout
  // <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.drain_timeout>`.
  //
  // .. note::
  //
  //   Request based timeouts mean that HTTP/2 PINGs will not keep the connection alive.
  //
  // If not specified, this defaults to ``1 hour``. To disable idle timeouts explicitly set this to ``0``.
  //
  // .. warning::
  //   Disabling this timeout has a highly likelihood of yielding connection leaks due to lost TCP
  //   FIN packets, etc.
  //
  // If the :ref:`overload action <config_overload_manager_overload_actions>` "envoy.overload_actions.reduce_timeouts"
  // is configured, this timeout is scaled for downstream connections according to the value for
  // :ref:`HTTP_DOWNSTREAM_CONNECTION_IDLE <envoy_v3_api_enum_value_config.overload.v3.ScaleTimersOverloadActionConfig.TimerType.HTTP_DOWNSTREAM_CONNECTION_IDLE>`.
  google.protobuf.Duration idle_timeout = 1;

  // The maximum duration of a connection. The duration is defined as a period since a connection
  // was established. If not set, there is no max duration. When max_connection_duration is reached,
  // the drain sequence will kick-in. The connection will be closed after the drain timeout period
  // if there are no active streams. See :ref:`drain_timeout
  // <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.drain_timeout>`.
  google.protobuf.Duration max_connection_duration = 3;

  // Percentage-based jitter for ``max_connection_duration``. If set, the actual connection duration
  // limit is extended by a random duration up to ``max_connection_duration * jitter / 100``.
  // This staggers connection teardowns across time and prevents a thundering-herd of reconnects
  // when many connections are established at roughly the same time.
  // This field is ignored if ``max_connection_duration`` is not set. If not set, no jitter is added.
  //
  // .. note::
  //   This field is currently only honored for downstream connections by the HTTP connection
  //   manager. It is not yet supported for upstream cluster connections.
  //
  // This is analogous to
  // :ref:`max_downstream_connection_duration_jitter_percentage
  // <envoy_v3_api_field_extensions.filters.network.tcp_proxy.v3.TcpProxy.max_downstream_connection_duration_jitter_percentage>`
  // in the TCP proxy filter.
  type.v3.Percent max_connection_duration_jitter = 8;

  // The maximum number of headers (request headers if configured on HttpConnectionManager,
  // response headers when configured on a cluster).
  // If unconfigured, the default maximum number of headers allowed is ``100``.
  // The default value for requests can be overridden by setting runtime key ``envoy.reloadable_features.max_request_headers_count``.
  // The default value for responses can be overridden by setting runtime key ``envoy.reloadable_features.max_response_headers_count``.
  // Downstream requests that exceed this limit will receive a ``HTTP 431`` response for HTTP/1.x and cause a stream
  // reset for HTTP/2.
  // Upstream responses that exceed this limit will result in a ``HTTP 502`` response.
  google.protobuf.UInt32Value max_headers_count = 2 [(validate.rules).uint32 = {gte: 1}];

  // The maximum size of response headers.
  // If unconfigured, the default is ``60 KiB``, except for HTTP/1 response headers which have a default
  // of ``80 KiB``.
  // The default value can be overridden by setting runtime key ``envoy.reloadable_features.max_response_headers_size_kb``.
  // Responses that exceed this limit will result in a ``HTTP 503`` response.
  // In Envoy, this setting is only valid when configured on an upstream cluster, not on the
  // :ref:`HTTP Connection Manager
  // <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.common_http_protocol_options>`.
  //
  // .. note::
  //
  //   Currently some protocol codecs impose limits on the maximum size of a single header.
  //
  //   * HTTP/2 (when using nghttp2) limits a single header to around 100 KB by default. This can be
  //     adjusted via :ref:`max_header_field_size_kb
  //     <envoy_v3_api_field_config.core.v3.Http2ProtocolOptions.max_header_field_size_kb>`.
  //   * HTTP/3 limits a single header to around 1024 KB.
  //
  google.protobuf.UInt32Value max_response_headers_kb = 7
      [(validate.rules).uint32 = {lte: 8192 gt: 0}];

  // Total duration to keep alive an HTTP request/response stream. If the time limit is reached the stream will be
  // reset independent of any other timeouts. If not specified, this value is not set.
  google.protobuf.Duration max_stream_duration = 4;

  // Action to take when a client request with a header name containing underscore characters is received.
  // If this setting is not specified, the value defaults to ``ALLOW``.
  //
  // .. note::
  //
  //   Upstream responses are not affected by this setting.
  //
  // .. note::
  //
  //   This only affects client headers. It does not affect headers added by Envoy filters and does not have any
  //   impact if added to cluster config.
  HeadersWithUnderscoresAction headers_with_underscores_action = 5;

  // Optional maximum requests for both upstream and downstream connections.
  // If not specified, there is no limit.
  // Setting this parameter to ``1`` will effectively disable keep alive.
  // For HTTP/2 and HTTP/3, due to concurrent stream processing, the limit is approximate.
  google.protobuf.UInt32Value max_requests_per_connection = 6;
}

// [#next-free-field: 12]
message Http1ProtocolOptions {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.api.v2.core.Http1ProtocolOptions";

  // [#next-free-field: 9]
  message HeaderKeyFormat {
    option (udpa.annotations.versioning).previous_message_type =
        "envoy.api.v2.core.Http1ProtocolOptions.HeaderKeyFormat";

    message ProperCaseWords {
      option (udpa.annotations.versioning).previous_message_type =
          "envoy.api.v2.core.Http1ProtocolOptions.HeaderKeyFormat.ProperCaseWords";
    }

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

      // Formats the header by proper casing words: the first character and any character following
      // a special character will be capitalized if it's an alpha character. For example,
      // ``"content-type"`` becomes ``"Content-Type"``, and ``"foo$b#$are"`` becomes ``"Foo$B#$Are"``.
      //
      // .. note::
      //
      //   While this results in most headers following conventional casing, certain headers
      //   are not covered. For example, the ``"TE"`` header will be formatted as ``"Te"``.
      ProperCaseWords proper_case_words = 1;

      // Configuration for stateful formatter extensions that allow using received headers to
      // affect the output of encoding headers. E.g., preserving case during proxying.
      // [#extension-category: envoy.http.stateful_header_formatters]
      TypedExtensionConfig stateful_formatter = 8;
    }
  }

  // Handle HTTP requests with absolute URLs in the requests. These requests
  // are generally sent by clients to forward/explicit proxies. This allows clients to configure
  // envoy as their HTTP proxy. In Unix, for example, this is typically done by setting the
  // ``http_proxy`` environment variable.
  google.protobuf.BoolValue allow_absolute_url = 1;

  // Handle incoming HTTP/1.0 and HTTP/0.9 requests.
  // This is off by default, and not fully standards compliant. There is support for pre-HTTP/1.1
  // style connect logic, dechunking, and handling lack of client host iff
  // ``default_host_for_http_10`` is configured.
  bool accept_http_10 = 2;

  // A default host for HTTP/1.0 requests. This is highly suggested if ``accept_http_10`` is true as
  // Envoy does not otherwise support HTTP/1.0 without a Host header.
  // This is a no-op if ``accept_http_10`` is not true.
  string default_host_for_http_10 = 3;

  // Describes how the keys for headers encoded by the HTTP/1 codec should be formatted. By
  // default, all header keys are lower cased.
  HeaderKeyFormat header_key_format = 4;

  // Enables trailers for HTTP/1. By default the HTTP/1 codec drops proxied trailers.
  //
  // .. attention::
  //
  //   This only happens when Envoy is chunk encoding which occurs when:
  //   - The request is HTTP/1.1.
  //   - Is neither a ``HEAD`` only request nor a HTTP Upgrade.
  //   - Not a response to a ``HEAD`` request.
  //   - The ``Content-Length`` header is not present.
  bool enable_trailers = 5;

  // Allows Envoy to process requests/responses with both ``Content-Length`` and ``Transfer-Encoding``
  // headers set. By default such messages are rejected, but if option is enabled - Envoy will
  // remove ``Content-Length`` header and process message.
  // See `RFC7230, sec. 3.3.3 <https://tools.ietf.org/html/rfc7230#section-3.3.3>`_ for details.
  //
  // .. attention::
  //
  //   Enabling this option might lead to request smuggling vulnerability, especially if traffic
  //   is proxied via multiple layers of proxies.
  // [#comment:TODO: This field is ignored when the
  // :ref:`header validation configuration <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.typed_header_validation_config>`
  // is present.]
  bool allow_chunked_length = 6;

  // Allows invalid HTTP messaging. When this option is false, then Envoy will terminate
  // HTTP/1.1 connections upon receiving an invalid HTTP message. However,
  // when this option is true, then Envoy will leave the HTTP/1.1 connection
  // open where possible.
  // If set, this overrides any HCM :ref:`stream_error_on_invalid_http_messaging
  // <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.stream_error_on_invalid_http_message>`.
  google.protobuf.BoolValue override_stream_error_on_invalid_http_message = 7;

  // Allows sending fully qualified URLs when proxying the first line of the
  // response. By default, Envoy will only send the path components in the first line.
  // If this is true, Envoy will create a fully qualified URI composing scheme
  // (inferred if not present), host (from the host/:authority header) and path
  // (from first line or :path header).
  bool send_fully_qualified_url = 8;

  // [#not-implemented-hide:] Hiding so that field can be removed after BalsaParser is rolled out.
  // If set, force HTTP/1 parser: BalsaParser if true, http-parser if false.
  // If unset, HTTP/1 parser is selected based on
  // envoy.reloadable_features.http1_use_balsa_parser.
  // See issue #21245.
  google.protobuf.BoolValue use_balsa_parser = 9
      [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];

  // [#not-implemented-hide:] Hiding so that field can be removed.
  // If true, and BalsaParser is used (either `use_balsa_parser` above is true,
  // or `envoy.reloadable_features.http1_use_balsa_parser` is true and
  // `use_balsa_parser` is unset), then every non-empty method with only valid
  // characters is accepted. Otherwise, methods not on the hard-coded list are
  // rejected.
  // Once UHV is enabled, this field should be removed, and BalsaParser should
  // allow any method. UHV validates the method, rejecting empty string or
  // invalid characters, and provides :ref:`restrict_http_methods
  // <envoy_v3_api_field_extensions.http.header_validators.envoy_default.v3.HeaderValidatorConfig.restrict_http_methods>`
  // to reject custom methods.
  bool allow_custom_methods = 10 [(xds.annotations.v3.field_status).work_in_progress = true];

  // Ignore HTTP/1.1 upgrade values matching any of the supplied matchers.
  //
  // .. note::
  //
  //   ``h2c`` upgrades are always removed for backwards compatibility, regardless of the
  //   value in this setting.
  repeated type.matcher.v3.StringMatcher ignore_http_11_upgrade = 11;
}

message KeepaliveSettings {
  // Send HTTP/2 PING frames at this period, in order to test that the connection is still alive.
  // If this is zero, interval PINGs will not be sent.
  google.protobuf.Duration interval = 1 [(validate.rules).duration = {gte {nanos: 1000000}}];

  // How long to wait for a response to a keepalive PING. If a response is not received within this
  // time period, the connection will be aborted.
  //
  // .. note::
  //
  //   In order to prevent the influence of Head-of-line (HOL) blocking the timeout period is extended when *any* frame is received on
  //   the connection, under the assumption that if a frame is received the connection is healthy.
  google.protobuf.Duration timeout = 2 [(validate.rules).duration = {
    required: true
    gte {nanos: 1000000}
  }];

  // A random jitter amount as a percentage of interval that will be added to each interval.
  // A value of zero means there will be no jitter.
  // The default value is ``15%``.
  type.v3.Percent interval_jitter = 3;

  // If the connection has been idle for this duration, send a HTTP/2 ping ahead
  // of new stream creation, to quickly detect dead connections.
  // If this is zero, this type of PING will not be sent.
  // If an interval ping is outstanding, a second ping will not be sent as the
  // interval ping will determine if the connection is dead.
  //
  // The same feature for HTTP/3 is given by inheritance from QUICHE which uses :ref:`connection idle_timeout <envoy_v3_api_field_config.listener.v3.QuicProtocolOptions.idle_timeout>` and the current PTO of the connection to decide whether to probe before sending a new request.
  google.protobuf.Duration connection_idle_interval = 4
      [(validate.rules).duration = {gte {nanos: 1000000}}];
}

// [#next-free-field: 23]
message Http2ProtocolOptions {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.api.v2.core.Http2ProtocolOptions";

  // Defines a parameter to be sent in the SETTINGS frame.
  // See `RFC7540, sec. 6.5.1 <https://tools.ietf.org/html/rfc7540#section-6.5.1>`_ for details.
  message SettingsParameter {
    option (udpa.annotations.versioning).previous_message_type =
        "envoy.api.v2.core.Http2ProtocolOptions.SettingsParameter";

    // The 16 bit parameter identifier.
    google.protobuf.UInt32Value identifier = 1 [
      (validate.rules).uint32 = {lte: 65535 gte: 0},
      (validate.rules).message = {required: true}
    ];

    // The 32 bit parameter value.
    google.protobuf.UInt32Value value = 2 [(validate.rules).message = {required: true}];
  }

  // `Maximum table size <https://httpwg.org/specs/rfc7541.html#rfc.section.4.2>`_
  // (in octets) that the encoder is permitted to use for the dynamic HPACK table. Valid values
  // range from ``0`` to ``4294967295`` (``2^32 - 1``) and defaults to ``4096``. ``0`` effectively disables header
  // compression.
  google.protobuf.UInt32Value hpack_table_size = 1;

  // `Maximum concurrent streams <https://httpwg.org/specs/rfc7540.html#rfc.section.5.1.2>`_
  // allowed for peer on one HTTP/2 connection. Valid values range from ``1`` to ``2147483647`` (``2^31 - 1``)
  // and defaults to ``1024`` for safety and should be sufficient for most use cases.
  //
  // For upstream connections, this also limits how many streams Envoy will initiate concurrently
  // on a single connection. If the limit is reached, Envoy may queue requests or establish
  // additional connections (as allowed per circuit breaker limits).
  //
  // This acts as an upper bound: Envoy will lower the max concurrent streams allowed on a given
  // connection based on upstream settings. Config dumps will reflect the configured upper bound,
  // not the per-connection negotiated limits.
  google.protobuf.UInt32Value max_concurrent_streams = 2
      [(validate.rules).uint32 = {lte: 2147483647 gte: 1}];

  // `Initial stream-level flow-control window
  // <https://httpwg.org/specs/rfc7540.html#rfc.section.6.9.2>`_ size. Valid values range from ``65535``
  // (``2^16 - 1``, HTTP/2 default) to ``2147483647`` (``2^31 - 1``, HTTP/2 maximum) and defaults to
  // ``16MiB`` (``16 * 1024 * 1024``).
  //
  // .. note::
  //
  //   ``65535`` is the initial window size from HTTP/2 spec. We only support increasing the default window size now,
  //   so it's also the minimum.
  //
  // This field also acts as a soft limit on the number of bytes Envoy will buffer per-stream in the
  // HTTP/2 codec buffers. Once the buffer reaches this pointer, watermark callbacks will fire to
  // stop the flow of data to the codec buffers.
  google.protobuf.UInt32Value initial_stream_window_size = 3
      [(validate.rules).uint32 = {lte: 2147483647 gte: 65535}];

  // Similar to ``initial_stream_window_size``, but for connection-level flow-control
  // window. The default is ``24MiB`` (``24 * 1024 * 1024``).
  google.protobuf.UInt32Value initial_connection_window_size = 4
      [(validate.rules).uint32 = {lte: 2147483647 gte: 65535}];

  // Allows proxying Websocket and other upgrades over H2 connect.
  bool allow_connect = 5;

  // [#not-implemented-hide:] Hiding until Envoy has full metadata support.
  // Still under implementation. DO NOT USE.
  //
  // Allows sending and receiving HTTP/2 METADATA frames. See [metadata
  // docs](https://github.com/envoyproxy/envoy/blob/main/source/docs/h2_metadata.md) for more
  // information.
  bool allow_metadata = 6;

  // Limit the number of pending outbound downstream frames of all types (frames that are waiting to
  // be written into the socket). Exceeding this limit triggers flood mitigation and connection is
  // terminated. The ``http2.outbound_flood`` stat tracks the number of terminated connections due
  // to flood mitigation. The default limit is ``10000``.
  google.protobuf.UInt32Value max_outbound_frames = 7 [(validate.rules).uint32 = {gte: 1}];

  // Limit the number of pending outbound downstream frames of types ``PING``, ``SETTINGS`` and ``RST_STREAM``,
  // preventing high memory utilization when receiving continuous stream of these frames. Exceeding
  // this limit triggers flood mitigation and connection is terminated. The
  // ``http2.outbound_control_flood`` stat tracks the number of terminated connections due to flood
  // mitigation. The default limit is ``1000``.
  google.protobuf.UInt32Value max_outbound_control_frames = 8 [(validate.rules).uint32 = {gte: 1}];

  // Limit the number of consecutive inbound frames of types ``HEADERS``, ``CONTINUATION`` and ``DATA`` with an
  // empty payload and no end stream flag. Those frames have no legitimate use and are abusive, but
  // might be a result of a broken HTTP/2 implementation. The ``http2.inbound_empty_frames_flood``
  // stat tracks the number of connections terminated due to flood mitigation.
  // Setting this to ``0`` will terminate connection upon receiving first frame with an empty payload
  // and no end stream flag. The default limit is ``1``.
  google.protobuf.UInt32Value max_consecutive_inbound_frames_with_empty_payload = 9;

  // Limit the number of inbound ``PRIORITY`` frames allowed per each opened stream. If the number
  // of ``PRIORITY`` frames received over the lifetime of connection exceeds the value calculated
  // using this formula::
  //
  //   ``max_inbound_priority_frames_per_stream`` * (1 + ``opened_streams``)
  //
  // the connection is terminated. For downstream connections the ``opened_streams`` is incremented when
  // Envoy receives complete response headers from the upstream server. For upstream connection the
  // ``opened_streams`` is incremented when Envoy sends the ``HEADERS`` frame for a new stream. The
  // ``http2.inbound_priority_frames_flood`` stat tracks
  // the number of connections terminated due to flood mitigation. The default limit is ``100``.
  google.protobuf.UInt32Value max_inbound_priority_frames_per_stream = 10;

  // Limit the number of inbound ``WINDOW_UPDATE`` frames allowed per ``DATA`` frame sent. If the number
  // of ``WINDOW_UPDATE`` frames received over the lifetime of connection exceeds the value calculated
  // using this formula::
  //
  //   ``5 + 2 * (opened_streams +
  //            max_inbound_window_update_frames_per_data_frame_sent * outbound_data_frames)``
  //
  // the connection is terminated. For downstream connections the ``opened_streams`` is incremented when
  // Envoy receives complete response headers from the upstream server. For upstream connections the
  // ``opened_streams`` is incremented when Envoy sends the ``HEADERS`` frame for a new stream. The
  // ``http2.inbound_window_update_frames_flood`` stat tracks the number of connections terminated due to
  // flood mitigation. The default ``max_inbound_window_update_frames_per_data_frame_sent`` value is ``10``.
  // Setting this to ``1`` should be enough to support HTTP/2 implementations with basic flow control,
  // but more complex implementations that try to estimate available bandwidth require at least ``2``.
  google.protobuf.UInt32Value max_inbound_window_update_frames_per_data_frame_sent = 11
      [(validate.rules).uint32 = {gte: 1}];

  // Allows invalid HTTP messaging and headers. When this option is disabled (default), then
  // the whole HTTP/2 connection is terminated upon receiving invalid HEADERS frame. However,
  // when this option is enabled, only the offending stream is terminated.
  //
  // This is overridden by HCM :ref:`stream_error_on_invalid_http_messaging
  // <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.stream_error_on_invalid_http_message>`
  // iff present.
  //
  // This is deprecated in favor of :ref:`override_stream_error_on_invalid_http_message
  // <envoy_v3_api_field_config.core.v3.Http2ProtocolOptions.override_stream_error_on_invalid_http_message>`
  //
  // See `RFC7540, sec. 8.1 <https://tools.ietf.org/html/rfc7540#section-8.1>`_ for details.
  bool stream_error_on_invalid_http_messaging = 12
      [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];

  // Allows invalid HTTP messaging and headers. When this option is disabled (default), then
  // the whole HTTP/2 connection is terminated upon receiving invalid HEADERS frame. However,
  // when this option is enabled, only the offending stream is terminated.
  //
  // This overrides any HCM :ref:`stream_error_on_invalid_http_messaging
  // <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.stream_error_on_invalid_http_message>`
  //
  // See `RFC7540, sec. 8.1 <https://tools.ietf.org/html/rfc7540#section-8.1>`_ for details.
  google.protobuf.BoolValue override_stream_error_on_invalid_http_message = 14;

  // [#not-implemented-hide:]
  // Specifies SETTINGS frame parameters to be sent to the peer, with two exceptions:
  //
  // 1. SETTINGS_ENABLE_PUSH (0x2) is not configurable as HTTP/2 server push is not supported by
  // Envoy.
  //
  // 2. SETTINGS_ENABLE_CONNECT_PROTOCOL (0x8) is only configurable through the named field
  // 'allow_connect'.
  //
  // .. note::
  //
  //   Custom parameters specified through this field can not also be set in the
  //   corresponding named parameters:
  //
  // .. code-block:: text
  //
  //   ID    Field Name
  //   ----------------
  //   0x1   hpack_table_size
  //   0x3   max_concurrent_streams
  //   0x4   initial_stream_window_size
  //
  // Collisions will trigger config validation failure on load/update. Likewise, inconsistencies
  // between custom parameters with the same identifier will trigger a failure.
  //
  // See `IANA HTTP/2 Settings
  // <https://www.iana.org/assignments/http2-parameters/http2-parameters.xhtml#settings>`_ for
  // standardized identifiers.
  repeated SettingsParameter custom_settings_parameters = 13;

  // Send HTTP/2 PING frames to verify that the connection is still healthy. If the remote peer
  // does not respond within the configured timeout, the connection will be aborted.
  KeepaliveSettings connection_keepalive = 15;

  // [#not-implemented-hide:] Hiding so that the field can be removed after oghttp2 is rolled out.
  // If set, force use of a particular HTTP/2 codec: oghttp2 if true, nghttp2 if false.
  // If unset, HTTP/2 codec is selected based on envoy.reloadable_features.http2_use_oghttp2.
  google.protobuf.BoolValue use_oghttp2_codec = 16
      [(xds.annotations.v3.field_status).work_in_progress = true];

  // Configure the maximum amount of metadata than can be handled per stream. Defaults to ``1 MB``.
  google.protobuf.UInt64Value max_metadata_size = 17;

  // Controls whether to encode headers using huffman encoding.
  // This can be useful in cases where the cpu spent encoding the headers isn't
  // worth the network bandwidth saved e.g. for localhost.
  // If unset, uses the data plane's default value.
  google.protobuf.BoolValue enable_huffman_encoding = 18;

  // Configures the maximum wire-encoded size in KB of an individual header field (name or value)
  // that the ``nghttp2`` HPACK inflater will accept. This limit applies to the HPACK-compressed
  // length on the wire, not the decoded length. If not specified, defaults to ``64`` KB
  // which is the ``nghttp2`` default.
  //
  // This limit applies to headers received by the codec. When configured on the downstream
  // HTTP Connection Manager, it limits individual request header fields. When configured on an
  // upstream cluster, it limits individual response header fields.
  //
  // Due to Huffman encoding, the decoded header size that passes a given wire limit depends
  // on the compression ratio of the content. For example, at the default ``64`` KB wire
  // limit, highly compressible header values can be approximately ``100`` KB when decoded.
  // Increasing this limit allows accepting larger individual headers at the cost of increased
  // memory usage during HPACK decompression.
  //
  // This option only applies when using ``nghttp2``. It is a no-op for ``oghttp2``. The configured
  // value of this field sets the per-header field size limit, which must not exceed the
  // applicable aggregate total header size limit. Since a single header field cannot be larger
  // than the total size allowed for all headers combined, this value is validated against
  // :ref:`max_request_headers_kb <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.max_request_headers_kb>`
  // when configured on the downstream HTTP Connection Manager, and against
  // :ref:`max_response_headers_kb <envoy_v3_api_field_config.core.v3.HttpProtocolOptions.max_response_headers_kb>`
  // when configured on an upstream cluster.
  //
  // Since ``Http2ProtocolOptions`` is configured independently for downstream and upstream,
  // different per-header field limits can be set for each direction without requiring separate
  // request and response fields.
  //
  // .. note::
  //
  //   When increasing this limit, ensure that upstream services and other proxies in the request
  //   path can also handle the larger individual header sizes. Mismatched limits may result in
  //   request failures.
  google.protobuf.UInt32Value max_header_field_size_kb = 19
      [(validate.rules).uint32 = {lte: 256 gte: 64}];

  // Whether to disallow obsolete text for oghttp2 in header field values.
  // If not set, it defaults to false.
  // From RFC 9110, https://www.rfc-editor.org/rfc/rfc9110.html#section-5.5:
  // obs-text = %x80-FF
  google.protobuf.BoolValue disallow_obs_text = 20;

  // Configures the initial token count for the RST_STREAM rate limiter used by the ``nghttp2``
  // server-side connection. This uses a token-bucket algorithm where each received RST_STREAM
  // frame consumes one token, and tokens are replenished at :ref:`stream_reset_rate
  // <envoy_v3_api_field_config.core.v3.Http2ProtocolOptions.stream_reset_rate>` per second.
  // When no tokens remain, ``nghttp2`` sends GOAWAY with ``INTERNAL_ERROR`` to close the
  // connection, protecting against CVE-2023-44487 (HTTP/2 Rapid Reset). Defaults to ``1000``.
  //
  // This option only applies when using ``nghttp2`` as a server. It has no effect on ``oghttp2``
  // or on client-side connections.
  google.protobuf.UInt64Value stream_reset_burst = 21;

  // Configures the token replenishment rate (tokens per second) for the RST_STREAM rate limiter
  // used by the ``nghttp2`` server-side connection. See :ref:`stream_reset_burst
  // <envoy_v3_api_field_config.core.v3.Http2ProtocolOptions.stream_reset_burst>` for details.
  // Defaults to ``33``.
  //
  // This option only applies when using ``nghttp2`` as a server. It has no effect on ``oghttp2``
  // or on client-side connections.
  google.protobuf.UInt64Value stream_reset_rate = 22;
}

// [#not-implemented-hide:]
message GrpcProtocolOptions {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.api.v2.core.GrpcProtocolOptions";

  Http2ProtocolOptions http2_protocol_options = 1;
}

// A message which allows using HTTP/3.
// [#next-free-field: 10]
message Http3ProtocolOptions {
  QuicProtocolOptions quic_protocol_options = 1;

  // Allows invalid HTTP messaging and headers. When this option is disabled (default), then
  // the whole HTTP/3 connection is terminated upon receiving invalid HEADERS frame. However,
  // when this option is enabled, only the offending stream is terminated.
  //
  // If set, this overrides any HCM :ref:`stream_error_on_invalid_http_messaging
  // <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.stream_error_on_invalid_http_message>`.
  google.protobuf.BoolValue override_stream_error_on_invalid_http_message = 2;

  // Allows proxying Websocket and other upgrades over HTTP/3 CONNECT using
  // the header mechanisms from the `HTTP/2 extended connect RFC
  // <https://datatracker.ietf.org/doc/html/rfc8441>`_
  // and settings `proposed for HTTP/3
  // <https://datatracker.ietf.org/doc/draft-ietf-httpbis-h3-websockets/>`_
  //
  // .. note::
  //
  //   HTTP/3 CONNECT is not yet an RFC.
  bool allow_extended_connect = 5 [(xds.annotations.v3.field_status).work_in_progress = true];

  // [#not-implemented-hide:] Hiding until Envoy has full metadata support.
  // Still under implementation. DO NOT USE.
  //
  // Allows sending and receiving HTTP/3 METADATA frames. See [metadata
  // docs](https://github.com/envoyproxy/envoy/blob/main/source/docs/h2_metadata.md) for more
  // information.
  bool allow_metadata = 6;

  // [#not-implemented-hide:] Hiding until Envoy has full HTTP/3 upstream support.
  // Still under implementation. DO NOT USE.
  //
  // Disables QPACK compression related features for HTTP/3 including:
  // No huffman encoding, zero dynamic table capacity and no cookie crumbling.
  // This can be useful for trading off CPU vs bandwidth when an upstream HTTP/3 connection multiplexes multiple downstream connections.
  bool disable_qpack = 7;

  // Disables connection level flow control for HTTP/3 streams. This is useful in situations where the streams share the same connection
  // but originate from different end-clients, so that each stream can make progress independently at non-front-line proxies.
  bool disable_connection_flow_control_for_streams = 8;

  // Whether to disallow obsolete text in header field values.
  // If not set, it defaults to true for alignment with current behavior.
  // As defined in RFC 9110, https://www.rfc-editor.org/rfc/rfc9110.html#section-5.5:
  // an obs-text character is a character in the range %x80-FF
  google.protobuf.BoolValue disallow_obs_text = 9;
}

// A message to control transformations to the :scheme header
message SchemeHeaderTransformation {
  oneof transformation {
    // Overwrite any Scheme header with the contents of this string.
    // If set, takes precedence over ``match_upstream``.
    string scheme_to_overwrite = 1 [(validate.rules).string = {in: "http" in: "https"}];
  }

  // Set the Scheme header to match the upstream transport protocol. For example, should a
  // request be sent to the upstream over TLS, the scheme header will be set to ``"https"``. Should the
  // request be sent over plaintext, the scheme header will be set to ``"http"``.
  // If ``scheme_to_overwrite`` is set, this field is not used.
  bool match_upstream = 2;
}
