data-plane-api/envoy/config/core/v4alpha/protocol.proto

syntax = "proto3";

package envoy.config.core.v4alpha;

import "envoy/type/v3/percent.proto";

import "google/protobuf/duration.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.config.core.v4alpha";
option java_outer_classname = "ProtocolProto";
option java_multiple_files = true;
option (udpa.annotations.file_status).package_version_status = NEXT_MAJOR_VERSION_CANDIDATE;

// [#protodoc-title: Protocol options]

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

message UpstreamHttpProtocolOptions {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.config.core.v3.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, as seen by the
  // :ref:`router filter <config_http_filters_router>`.
  bool auto_sni = 1;

  // Automatic validate upstream presented certificate for new upstream connections based on the
  // downstream HTTP host/authority header, as seen by the
  // :ref:`router filter <config_http_filters_router>`.
  // This field is intended to set with `auto_sni` field.
  bool auto_san_validation = 2;
}

// [#next-free-field: 6]
message HttpProtocolOptions {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.config.core.v3.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 the 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 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_api_field_extensions.filters.network.http_connection_manager.v4alpha.HttpConnectionManager.drain_timeout>`.
  // Note that 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_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 connection will be closed. Drain sequence will occur prior to closing the connection if
  // if's applicable. See :ref:`drain_timeout
  // <envoy_api_field_extensions.filters.network.http_connection_manager.v4alpha.HttpConnectionManager.drain_timeout>`.
  // Note: not implemented for upstream connections.
  google.protobuf.Duration max_connection_duration = 3;

  // The maximum number of headers. If unconfigured, the default
  // maximum number of request headers allowed is 100. Requests that exceed this limit will receive
  // a 431 response for HTTP/1.x and cause a stream reset for HTTP/2.
  google.protobuf.UInt32Value max_headers_count = 2 [(validate.rules).uint32 = {gte: 1}];

  // 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.
  HeadersWithUnderscoresAction headers_with_underscores_action = 5;
}

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

  message HeaderKeyFormat {
    option (udpa.annotations.versioning).previous_message_type =
        "envoy.config.core.v3.Http1ProtocolOptions.HeaderKeyFormat";

    message ProperCaseWords {
      option (udpa.annotations.versioning).previous_message_type =
          "envoy.config.core.v3.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 that 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;
    }
  }

  // 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 response headers 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::
  //
  //   Note that 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.
  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;
}

message KeepaliveSettings {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.config.core.v3.KeepaliveSettings";

  // Send HTTP/2 PING frames at this period, in order to test that the connection is still alive.
  google.protobuf.Duration interval = 1 [(validate.rules).duration = {
    required: true
    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.
  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;
}

// [#next-free-field: 16]
message Http2ProtocolOptions {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.config.core.v3.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.config.core.v3.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}];
  }

  reserved 12;

  reserved "stream_error_on_invalid_http_messaging";

  // `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 2147483647.
  //
  // 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).
  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 268435456
  // (256 * 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. Currently, this has the same minimum/maximum/default as *initial_stream_window_size*.
  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 metadata. 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.
  // NOTE: flood and abuse mitigation for upstream connections is presently enabled by the
  // `envoy.reloadable_features.upstream_http2_flood_checks` flag.
  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.
  // NOTE: flood and abuse mitigation for upstream connections is presently enabled by the
  // `envoy.reloadable_features.upstream_http2_flood_checks` flag.
  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.
  // NOTE: flood and abuse mitigation for upstream connections is presently enabled by the
  // `envoy.reloadable_features.upstream_http2_flood_checks` flag.
  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 send 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.
  // NOTE: flood and abuse mitigation for upstream connections is presently enabled by the
  // `envoy.reloadable_features.upstream_http2_flood_checks` flag.
  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_priority_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.
  // NOTE: flood and abuse mitigation for upstream connections is presently enabled by the
  // `envoy.reloadable_features.upstream_http2_flood_checks` flag.
  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 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 that 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:]
message GrpcProtocolOptions {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.config.core.v3.GrpcProtocolOptions";

  Http2ProtocolOptions http2_protocol_options = 1;
}

// [#not-implemented-hide:]
//
// A message which allows using HTTP/3 as an upstream protocol.
//
// Eventually this will include configuration for tuning HTTP/3.
message Http3ProtocolOptions {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.config.core.v3.Http3ProtocolOptions";
}