data-plane-api/envoy/extensions/upstreams/http/v3/http_protocol_options.proto

syntax = "proto3";

package envoy.extensions.upstreams.http.v3;

import "envoy/config/core/v3/protocol.proto";

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

option java_package = "io.envoyproxy.envoy.extensions.upstreams.http.v3";
option java_outer_classname = "HttpProtocolOptionsProto";
option java_multiple_files = true;
option (udpa.annotations.file_status).package_version_status = ACTIVE;

// [#protodoc-title: HTTP Protocol Options]
// [#extension: envoy.upstreams.http.http_protocol_options]

// HttpProtocolOptions specifies Http upstream protocol options. This object
// is used in
// :ref:`typed_extension_protocol_options<envoy_v3_api_field_config.cluster.v3.Cluster.typed_extension_protocol_options>`,
// keyed by the name `envoy.extensions.upstreams.http.v3.HttpProtocolOptions`.
//
// This controls what protocol(s) should be used for upstream and how said protocol(s) are configured.
//
// This replaces the prior pattern of explicit protocol configuration directly
// in the cluster. So a configuration like this, explicitly configuring the use of HTTP/2 upstream:
//
// .. code::
//
//   clusters:
//     - name: some_service
//       connect_timeout: 5s
//       upstream_http_protocol_options:
//         auto_sni: true
//       common_http_protocol_options:
//         idle_timeout: 1s
//       http2_protocol_options:
//         max_concurrent_streams: 100
//        .... [further cluster config]
//
// Would now look like this:
//
// .. code::
//
//   clusters:
//     - name: some_service
//       connect_timeout: 5s
//       typed_extension_protocol_options:
//         envoy.extensions.upstreams.http.v3.HttpProtocolOptions:
//           "@type": type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions
//           upstream_http_protocol_options:
//             auto_sni: true
//           common_http_protocol_options:
//             idle_timeout: 1s
//           explicit_http_config:
//             http2_protocol_options:
//               max_concurrent_streams: 100
//        .... [further cluster config]
// [#next-free-field: 6]
message HttpProtocolOptions {
  // If this is used, the cluster will only operate on one of the possible upstream protocols.
  // Note that HTTP/2 or above should generally be used for upstream gRPC clusters.
  message ExplicitHttpConfig {
    oneof protocol_config {
      option (validate.required) = true;

      config.core.v3.Http1ProtocolOptions http_protocol_options = 1;

      config.core.v3.Http2ProtocolOptions http2_protocol_options = 2;

      // .. warning::
      //   QUIC support is currently alpha and should be used with caution. Please
      //   see :ref:`here <arch_overview_http3>` for details.
      config.core.v3.Http3ProtocolOptions http3_protocol_options = 3;
    }
  }

  // If this is used, the cluster can use either of the configured protocols, and
  // will use whichever protocol was used by the downstream connection.
  //
  // If HTTP/3 is configured for downstream and not configured for upstream,
  // HTTP/3 requests will fail over to HTTP/2.
  message UseDownstreamHttpConfig {
    config.core.v3.Http1ProtocolOptions http_protocol_options = 1;

    config.core.v3.Http2ProtocolOptions http2_protocol_options = 2;

    // .. warning::
    //   QUIC support is currently alpha and should be used with caution. Please
    //   see :ref:`here <arch_overview_http3>` for details.
    config.core.v3.Http3ProtocolOptions http3_protocol_options = 3;
  }

  // If this is used, the cluster can use either HTTP/1 or HTTP/2, and will use whichever
  // protocol is negotiated by ALPN with the upstream.
  // Clusters configured with *AutoHttpConfig* will use the highest available
  // protocol; HTTP/2 if supported, otherwise HTTP/1.
  // If the upstream does not support ALPN, *AutoHttpConfig* will fail over to HTTP/1.
  // This can only be used with transport sockets which support ALPN. Using a
  // transport socket which does not support ALPN will result in configuration
  // failure. The transport layer may be configured with custom ALPN, but the default ALPN
  // for the cluster (or if custom ALPN fails) will be "h2,http/1.1".
  message AutoHttpConfig {
    config.core.v3.Http1ProtocolOptions http_protocol_options = 1;

    config.core.v3.Http2ProtocolOptions http2_protocol_options = 2;

    // Unlike HTTP/1 and HTTP/2, HTTP/3 will not be configured unless it is
    // present, and (soon) only if there is an indication of server side
    // support.
    // See :ref:`here <arch_overview_http3_upstream>` for more information on
    // when HTTP/3 will be used, and when Envoy will fail over to TCP.
    //
    // .. warning::
    //   QUIC support is currently alpha and should be used with caution. Please
    //   see :ref:`here <arch_overview_http3>` for details.
    //   AutoHttpConfig config is undergoing especially rapid change and as it
    //   is alpha is not guaranteed to be API-stable.
    config.core.v3.Http3ProtocolOptions http3_protocol_options = 3;

    // The presence of alternate protocols cache options causes the use of the
    // alternate protocols cache, which is responsible for parsing and caching
    // HTTP Alt-Svc headers. This enables the use of HTTP/3 for origins that
    // advertise supporting it.
    //
    // .. note::
    //   This is required when HTTP/3 is enabled.
    config.core.v3.AlternateProtocolsCacheOptions alternate_protocols_cache_options = 4;
  }

  // This contains options common across HTTP/1 and HTTP/2
  config.core.v3.HttpProtocolOptions common_http_protocol_options = 1;

  // This contains common protocol options which are only applied upstream.
  config.core.v3.UpstreamHttpProtocolOptions upstream_http_protocol_options = 2;

  // This controls the actual protocol to be used upstream.
  oneof upstream_protocol_options {
    option (validate.required) = true;

    // To explicitly configure either HTTP/1 or HTTP/2 (but not both!) use *explicit_http_config*.
    // If the *explicit_http_config* is empty, HTTP/1.1 is used.
    ExplicitHttpConfig explicit_http_config = 3;

    // This allows switching on protocol based on what protocol the downstream
    // connection used.
    UseDownstreamHttpConfig use_downstream_protocol_config = 4;

    // This allows switching on protocol based on ALPN
    AutoHttpConfig auto_config = 5;
  }
}