1syntax = "proto3"; 2 3package envoy.api.v2.core; 4 5import "google/protobuf/duration.proto"; 6import "google/protobuf/wrappers.proto"; 7 8import "udpa/annotations/migrate.proto"; 9import "udpa/annotations/status.proto"; 10import "validate/validate.proto"; 11 12option java_package = "io.envoyproxy.envoy.api.v2.core"; 13option java_outer_classname = "ProtocolProto"; 14option java_multiple_files = true; 15option go_package = "github.com/envoyproxy/go-control-plane/envoy/api/v2/core"; 16option (udpa.annotations.file_migrate).move_to_package = "envoy.config.core.v3"; 17option (udpa.annotations.file_status).package_version_status = FROZEN; 18 19// [#protodoc-title: Protocol options] 20 21// [#not-implemented-hide:] 22message TcpProtocolOptions { 23} 24 25message UpstreamHttpProtocolOptions { 26 // Set transport socket `SNI <https://en.wikipedia.org/wiki/Server_Name_Indication>`_ for new 27 // upstream connections based on the downstream HTTP host/authority header, as seen by the 28 // :ref:`router filter <config_http_filters_router>`. 29 bool auto_sni = 1; 30 31 // Automatic validate upstream presented certificate for new upstream connections based on the 32 // downstream HTTP host/authority header, as seen by the 33 // :ref:`router filter <config_http_filters_router>`. 34 // This field is intended to set with `auto_sni` field. 35 bool auto_san_validation = 2; 36} 37 38// [#next-free-field: 6] 39message HttpProtocolOptions { 40 // Action to take when Envoy receives client request with header names containing underscore 41 // characters. 42 // Underscore character is allowed in header names by the RFC-7230 and this behavior is implemented 43 // as a security measure due to systems that treat '_' and '-' as interchangeable. Envoy by default allows client request headers with underscore 44 // characters. 45 enum HeadersWithUnderscoresAction { 46 // Allow headers with underscores. This is the default behavior. 47 ALLOW = 0; 48 49 // Reject client request. HTTP/1 requests are rejected with the 400 status. HTTP/2 requests 50 // end with the stream reset. The "httpN.requests_rejected_with_underscores_in_headers" counter 51 // is incremented for each rejected request. 52 REJECT_REQUEST = 1; 53 54 // Drop the header with name containing underscores. The header is dropped before the filter chain is 55 // invoked and as such filters will not see dropped headers. The 56 // "httpN.dropped_headers_with_underscores" is incremented for each dropped header. 57 DROP_HEADER = 2; 58 } 59 60 // The idle timeout for connections. The idle timeout is defined as the 61 // period in which there are no active requests. When the 62 // idle timeout is reached the connection will be closed. If the connection is an HTTP/2 63 // downstream connection a drain sequence will occur prior to closing the connection, see 64 // :ref:`drain_timeout 65 // <envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.drain_timeout>`. 66 // Note that request based timeouts mean that HTTP/2 PINGs will not keep the connection alive. 67 // If not specified, this defaults to 1 hour. To disable idle timeouts explicitly set this to 0. 68 // 69 // .. warning:: 70 // Disabling this timeout has a highly likelihood of yielding connection leaks due to lost TCP 71 // FIN packets, etc. 72 google.protobuf.Duration idle_timeout = 1; 73 74 // The maximum duration of a connection. The duration is defined as a period since a connection 75 // was established. If not set, there is no max duration. When max_connection_duration is reached 76 // the connection will be closed. Drain sequence will occur prior to closing the connection if 77 // if's applicable. See :ref:`drain_timeout 78 // <envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.drain_timeout>`. 79 // Note: not implemented for upstream connections. 80 google.protobuf.Duration max_connection_duration = 3; 81 82 // The maximum number of headers. If unconfigured, the default 83 // maximum number of request headers allowed is 100. Requests that exceed this limit will receive 84 // a 431 response for HTTP/1.x and cause a stream reset for HTTP/2. 85 google.protobuf.UInt32Value max_headers_count = 2 [(validate.rules).uint32 = {gte: 1}]; 86 87 // Total duration to keep alive an HTTP request/response stream. If the time limit is reached the stream will be 88 // reset independent of any other timeouts. If not specified, this value is not set. 89 google.protobuf.Duration max_stream_duration = 4; 90 91 // Action to take when a client request with a header name containing underscore characters is received. 92 // If this setting is not specified, the value defaults to ALLOW. 93 // Note: upstream responses are not affected by this setting. 94 HeadersWithUnderscoresAction headers_with_underscores_action = 5; 95} 96 97// [#next-free-field: 6] 98message Http1ProtocolOptions { 99 message HeaderKeyFormat { 100 message ProperCaseWords { 101 } 102 103 oneof header_format { 104 option (validate.required) = true; 105 106 // Formats the header by proper casing words: the first character and any character following 107 // a special character will be capitalized if it's an alpha character. For example, 108 // "content-type" becomes "Content-Type", and "foo$b#$are" becomes "Foo$B#$Are". 109 // Note that while this results in most headers following conventional casing, certain headers 110 // are not covered. For example, the "TE" header will be formatted as "Te". 111 ProperCaseWords proper_case_words = 1; 112 } 113 } 114 115 // Handle HTTP requests with absolute URLs in the requests. These requests 116 // are generally sent by clients to forward/explicit proxies. This allows clients to configure 117 // envoy as their HTTP proxy. In Unix, for example, this is typically done by setting the 118 // *http_proxy* environment variable. 119 google.protobuf.BoolValue allow_absolute_url = 1; 120 121 // Handle incoming HTTP/1.0 and HTTP 0.9 requests. 122 // This is off by default, and not fully standards compliant. There is support for pre-HTTP/1.1 123 // style connect logic, dechunking, and handling lack of client host iff 124 // *default_host_for_http_10* is configured. 125 bool accept_http_10 = 2; 126 127 // A default host for HTTP/1.0 requests. This is highly suggested if *accept_http_10* is true as 128 // Envoy does not otherwise support HTTP/1.0 without a Host header. 129 // This is a no-op if *accept_http_10* is not true. 130 string default_host_for_http_10 = 3; 131 132 // Describes how the keys for response headers should be formatted. By default, all header keys 133 // are lower cased. 134 HeaderKeyFormat header_key_format = 4; 135 136 // Enables trailers for HTTP/1. By default the HTTP/1 codec drops proxied trailers. 137 // 138 // .. attention:: 139 // 140 // Note that this only happens when Envoy is chunk encoding which occurs when: 141 // - The request is HTTP/1.1. 142 // - Is neither a HEAD only request nor a HTTP Upgrade. 143 // - Not a response to a HEAD request. 144 // - The content length header is not present. 145 bool enable_trailers = 5; 146} 147 148// [#next-free-field: 14] 149message Http2ProtocolOptions { 150 // Defines a parameter to be sent in the SETTINGS frame. 151 // See `RFC7540, sec. 6.5.1 <https://tools.ietf.org/html/rfc7540#section-6.5.1>`_ for details. 152 message SettingsParameter { 153 // The 16 bit parameter identifier. 154 google.protobuf.UInt32Value identifier = 1 [ 155 (validate.rules).uint32 = {lte: 65536 gte: 1}, 156 (validate.rules).message = {required: true} 157 ]; 158 159 // The 32 bit parameter value. 160 google.protobuf.UInt32Value value = 2 [(validate.rules).message = {required: true}]; 161 } 162 163 // `Maximum table size <https://httpwg.org/specs/rfc7541.html#rfc.section.4.2>`_ 164 // (in octets) that the encoder is permitted to use for the dynamic HPACK table. Valid values 165 // range from 0 to 4294967295 (2^32 - 1) and defaults to 4096. 0 effectively disables header 166 // compression. 167 google.protobuf.UInt32Value hpack_table_size = 1; 168 169 // `Maximum concurrent streams <https://httpwg.org/specs/rfc7540.html#rfc.section.5.1.2>`_ 170 // allowed for peer on one HTTP/2 connection. Valid values range from 1 to 2147483647 (2^31 - 1) 171 // and defaults to 2147483647. 172 // 173 // For upstream connections, this also limits how many streams Envoy will initiate concurrently 174 // on a single connection. If the limit is reached, Envoy may queue requests or establish 175 // additional connections (as allowed per circuit breaker limits). 176 google.protobuf.UInt32Value max_concurrent_streams = 2 177 [(validate.rules).uint32 = {lte: 2147483647 gte: 1}]; 178 179 // `Initial stream-level flow-control window 180 // <https://httpwg.org/specs/rfc7540.html#rfc.section.6.9.2>`_ size. Valid values range from 65535 181 // (2^16 - 1, HTTP/2 default) to 2147483647 (2^31 - 1, HTTP/2 maximum) and defaults to 268435456 182 // (256 * 1024 * 1024). 183 // 184 // NOTE: 65535 is the initial window size from HTTP/2 spec. We only support increasing the default 185 // window size now, so it's also the minimum. 186 // 187 // This field also acts as a soft limit on the number of bytes Envoy will buffer per-stream in the 188 // HTTP/2 codec buffers. Once the buffer reaches this pointer, watermark callbacks will fire to 189 // stop the flow of data to the codec buffers. 190 google.protobuf.UInt32Value initial_stream_window_size = 3 191 [(validate.rules).uint32 = {lte: 2147483647 gte: 65535}]; 192 193 // Similar to *initial_stream_window_size*, but for connection-level flow-control 194 // window. Currently, this has the same minimum/maximum/default as *initial_stream_window_size*. 195 google.protobuf.UInt32Value initial_connection_window_size = 4 196 [(validate.rules).uint32 = {lte: 2147483647 gte: 65535}]; 197 198 // Allows proxying Websocket and other upgrades over H2 connect. 199 bool allow_connect = 5; 200 201 // [#not-implemented-hide:] Hiding until envoy has full metadata support. 202 // Still under implementation. DO NOT USE. 203 // 204 // Allows metadata. See [metadata 205 // docs](https://github.com/envoyproxy/envoy/blob/main/source/docs/h2_metadata.md) for more 206 // information. 207 bool allow_metadata = 6; 208 209 // Limit the number of pending outbound downstream frames of all types (frames that are waiting to 210 // be written into the socket). Exceeding this limit triggers flood mitigation and connection is 211 // terminated. The ``http2.outbound_flood`` stat tracks the number of terminated connections due 212 // to flood mitigation. The default limit is 10000. 213 // [#comment:TODO: implement same limits for upstream outbound frames as well.] 214 google.protobuf.UInt32Value max_outbound_frames = 7 [(validate.rules).uint32 = {gte: 1}]; 215 216 // Limit the number of pending outbound downstream frames of types PING, SETTINGS and RST_STREAM, 217 // preventing high memory utilization when receiving continuous stream of these frames. Exceeding 218 // this limit triggers flood mitigation and connection is terminated. The 219 // ``http2.outbound_control_flood`` stat tracks the number of terminated connections due to flood 220 // mitigation. The default limit is 1000. 221 // [#comment:TODO: implement same limits for upstream outbound frames as well.] 222 google.protobuf.UInt32Value max_outbound_control_frames = 8 [(validate.rules).uint32 = {gte: 1}]; 223 224 // Limit the number of consecutive inbound frames of types HEADERS, CONTINUATION and DATA with an 225 // empty payload and no end stream flag. Those frames have no legitimate use and are abusive, but 226 // might be a result of a broken HTTP/2 implementation. The `http2.inbound_empty_frames_flood`` 227 // stat tracks the number of connections terminated due to flood mitigation. 228 // Setting this to 0 will terminate connection upon receiving first frame with an empty payload 229 // and no end stream flag. The default limit is 1. 230 // [#comment:TODO: implement same limits for upstream inbound frames as well.] 231 google.protobuf.UInt32Value max_consecutive_inbound_frames_with_empty_payload = 9; 232 233 // Limit the number of inbound PRIORITY frames allowed per each opened stream. If the number 234 // of PRIORITY frames received over the lifetime of connection exceeds the value calculated 235 // using this formula:: 236 // 237 // max_inbound_priority_frames_per_stream * (1 + inbound_streams) 238 // 239 // the connection is terminated. The ``http2.inbound_priority_frames_flood`` stat tracks 240 // the number of connections terminated due to flood mitigation. The default limit is 100. 241 // [#comment:TODO: implement same limits for upstream inbound frames as well.] 242 google.protobuf.UInt32Value max_inbound_priority_frames_per_stream = 10; 243 244 // Limit the number of inbound WINDOW_UPDATE frames allowed per DATA frame sent. If the number 245 // of WINDOW_UPDATE frames received over the lifetime of connection exceeds the value calculated 246 // using this formula:: 247 // 248 // 1 + 2 * (inbound_streams + 249 // max_inbound_window_update_frames_per_data_frame_sent * outbound_data_frames) 250 // 251 // the connection is terminated. The ``http2.inbound_priority_frames_flood`` stat tracks 252 // the number of connections terminated due to flood mitigation. The default limit is 10. 253 // Setting this to 1 should be enough to support HTTP/2 implementations with basic flow control, 254 // but more complex implementations that try to estimate available bandwidth require at least 2. 255 // [#comment:TODO: implement same limits for upstream inbound frames as well.] 256 google.protobuf.UInt32Value max_inbound_window_update_frames_per_data_frame_sent = 11 257 [(validate.rules).uint32 = {gte: 1}]; 258 259 // Allows invalid HTTP messaging and headers. When this option is disabled (default), then 260 // the whole HTTP/2 connection is terminated upon receiving invalid HEADERS frame. However, 261 // when this option is enabled, only the offending stream is terminated. 262 // 263 // See `RFC7540, sec. 8.1 <https://tools.ietf.org/html/rfc7540#section-8.1>`_ for details. 264 bool stream_error_on_invalid_http_messaging = 12; 265 266 // [#not-implemented-hide:] 267 // Specifies SETTINGS frame parameters to be sent to the peer, with two exceptions: 268 // 269 // 1. SETTINGS_ENABLE_PUSH (0x2) is not configurable as HTTP/2 server push is not supported by 270 // Envoy. 271 // 272 // 2. SETTINGS_ENABLE_CONNECT_PROTOCOL (0x8) is only configurable through the named field 273 // 'allow_connect'. 274 // 275 // Note that custom parameters specified through this field can not also be set in the 276 // corresponding named parameters: 277 // 278 // .. code-block:: text 279 // 280 // ID Field Name 281 // ---------------- 282 // 0x1 hpack_table_size 283 // 0x3 max_concurrent_streams 284 // 0x4 initial_stream_window_size 285 // 286 // Collisions will trigger config validation failure on load/update. Likewise, inconsistencies 287 // between custom parameters with the same identifier will trigger a failure. 288 // 289 // See `IANA HTTP/2 Settings 290 // <https://www.iana.org/assignments/http2-parameters/http2-parameters.xhtml#settings>`_ for 291 // standardized identifiers. 292 repeated SettingsParameter custom_settings_parameters = 13; 293} 294 295// [#not-implemented-hide:] 296message GrpcProtocolOptions { 297 Http2ProtocolOptions http2_protocol_options = 1; 298} 299