-
Notifications
You must be signed in to change notification settings - Fork 4.8k
/
protocol.proto
432 lines (373 loc) · 21.8 KB
/
protocol.proto
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
syntax = "proto3";
package envoy.config.core.v3;
import "envoy/config/core/v3/extension.proto";
import "envoy/type/v3/percent.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/wrappers.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 (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";
}
// QUIC protocol options which apply to both downstream and upstream connections.
message QuicProtocolOptions {
// Maximum number of streams that the client can negotiate per connection. 100
// if not specified.
google.protobuf.UInt32Value max_concurrent_streams = 1;
}
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, 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.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 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.v3.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.v3.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.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 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;
// 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 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 {
// 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.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 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).
//
// 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 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 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 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.api.v2.core.GrpcProtocolOptions";
Http2ProtocolOptions http2_protocol_options = 1;
}
// [#not-implemented-hide:]
//
// A message which allows using HTTP/3.
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;
}