FileSystemBufferFilterConfig (proto)
This extension has the qualified name envoy.filters.http.file_system_buffer
Note
This extension is work-in-progress. Functionality is incomplete and it is not intended for production use.
This extension has an unknown security posture and should only be used in deployments where both the downstream and upstream are trusted.
Tip
This extension extends and can be used with the following extension category:
This extension must be configured with one of the following type URLs:
Warning
This API feature is currently work-in-progress. API features marked as work-in-progress are not considered stable, are not covered by the threat model, are not supported by the security team, and are subject to breaking changes. Do not use this feature without understanding each of the previous points.
extensions.filters.http.file_system_buffer.v3.BufferBehavior
[extensions.filters.http.file_system_buffer.v3.BufferBehavior proto]
The behavior of the filter for a stream.
{
"stream_when_possible": {...},
"bypass": {...},
"inject_content_length_if_necessary": {...},
"fully_buffer_and_always_inject_content_length": {...},
"fully_buffer": {...}
}
- stream_when_possible
(extensions.filters.http.file_system_buffer.v3.BufferBehavior.StreamWhenPossible) Don’t inject
content-length
header. Output immediately, buffer only if output is slower than input.Precisely one of stream_when_possible, bypass, inject_content_length_if_necessary, fully_buffer_and_always_inject_content_length, fully_buffer must be set.
- bypass
(extensions.filters.http.file_system_buffer.v3.BufferBehavior.Bypass) Never buffer, do nothing.
Precisely one of stream_when_possible, bypass, inject_content_length_if_necessary, fully_buffer_and_always_inject_content_length, fully_buffer must be set.
- inject_content_length_if_necessary
(extensions.filters.http.file_system_buffer.v3.BufferBehavior.InjectContentLengthIfNecessary) If
content-length
is not present, buffer the entire input, injectcontent-length
header, then output. Ifcontent-length
is already present, act likestream_when_possible
.Precisely one of stream_when_possible, bypass, inject_content_length_if_necessary, fully_buffer_and_always_inject_content_length, fully_buffer must be set.
- fully_buffer_and_always_inject_content_length
(extensions.filters.http.file_system_buffer.v3.BufferBehavior.FullyBufferAndAlwaysInjectContentLength) Always buffer the entire input, and inject
content-length
, overwriting any provided content-length header.Precisely one of stream_when_possible, bypass, inject_content_length_if_necessary, fully_buffer_and_always_inject_content_length, fully_buffer must be set.
- fully_buffer
(extensions.filters.http.file_system_buffer.v3.BufferBehavior.FullyBuffer) Always buffer the entire input, do not modify
content-length
.Precisely one of stream_when_possible, bypass, inject_content_length_if_necessary, fully_buffer_and_always_inject_content_length, fully_buffer must be set.
extensions.filters.http.file_system_buffer.v3.BufferBehavior.StreamWhenPossible
[extensions.filters.http.file_system_buffer.v3.BufferBehavior.StreamWhenPossible proto]
extensions.filters.http.file_system_buffer.v3.BufferBehavior.Bypass
[extensions.filters.http.file_system_buffer.v3.BufferBehavior.Bypass proto]
extensions.filters.http.file_system_buffer.v3.BufferBehavior.InjectContentLengthIfNecessary
[extensions.filters.http.file_system_buffer.v3.BufferBehavior.InjectContentLengthIfNecessary proto]
extensions.filters.http.file_system_buffer.v3.BufferBehavior.FullyBufferAndAlwaysInjectContentLength
extensions.filters.http.file_system_buffer.v3.BufferBehavior.FullyBuffer
[extensions.filters.http.file_system_buffer.v3.BufferBehavior.FullyBuffer proto]
extensions.filters.http.file_system_buffer.v3.StreamConfig
[extensions.filters.http.file_system_buffer.v3.StreamConfig proto]
The configuration for one direction of the filter behavior.
{
"behavior": {...},
"memory_buffer_bytes_limit": {...},
"storage_buffer_bytes_limit": {...},
"storage_buffer_queue_high_watermark_bytes": {...}
}
- behavior
(extensions.filters.http.file_system_buffer.v3.BufferBehavior) Whether to bypass / stream / fully buffer / etc. If unset in route, vhost and listener config, the default is
stream_when_possible
.
- memory_buffer_bytes_limit
(UInt64Value) The amount stored in the memory buffer before buffering to disk. If unset in route, vhost and listener config, defaults to a hardcoded value of 1MiB
- storage_buffer_bytes_limit
(UInt64Value) The maximum storage (excluding memory) to be buffered in this filter. If unset in route, vhost and listener config, defaults to a hardcoded value of 32MiB
- storage_buffer_queue_high_watermark_bytes
(UInt64Value) The maximum amount that can be queued for writing to storage, above which the source is requested to pause. If unset, defaults to the same value as
memory_buffer_bytes_limit
.For example, assuming the recipient is not consuming data at all, if
memory_buffer_bytes_limit
was 32MiB, andstorage_buffer_queue_high_watermark_bytes
was 64MiB, and the filesystem is backed up so writes are not occurring promptly, then:Any request less than 32MiB will eventually pass through without ever attempting to write to disk.
Any request with over 32MiB buffered will start trying to write to disk. If it reaches (32+64)MiB buffered in memory (write to disk isn’t keeping up), a high watermark signal is sent to the source.
Any stream whose total size exceeds
memory_buffer_bytes_limit + storage_buffer_bytes_limit
will provoke an error. (Note, if the recipient is consuming data then it is possible for such an oversized request to pass through the buffer filter, provided the recipient isn’t consuming data too slowly.)
The low watermark signal is sent when the memory buffer is at size
memory_buffer_bytes_limit + (storage_buffer_queue_high_watermark_bytes / 2)
.
extensions.filters.http.file_system_buffer.v3.FileSystemBufferFilterConfig
[extensions.filters.http.file_system_buffer.v3.FileSystemBufferFilterConfig proto]
A file system buffer filter configuration.
Route-specific configs override only the fields they explicitly include; unset fields inherit from the vhost or listener-level config, or, if never set, and not required, use a default value.
{
"manager_config": {...},
"storage_buffer_path": {...},
"request": {...},
"response": {...}
}
- manager_config
(extensions.common.async_files.v3.AsyncFileManagerConfig) A configuration for an AsyncFileManager.
If unset in route, vhost and listener, and the behavior is not
bypass
in both directions, an Internal Server Error response will be sent.
- storage_buffer_path
(StringValue) An optional path to which the unlinked files should be written - this may determine which physical storage device will be used.
If unset in route, vhost and listener, will use the environment variable
TMPDIR
, or, if that’s also unset, will use/tmp
.
- request
(extensions.filters.http.file_system_buffer.v3.StreamConfig) Optional configuration for how to buffer (or not) requests. If unset in route, vhost and listener,
StreamConfig
default values will be used (with behaviorstream_when_possible
)
- response
(extensions.filters.http.file_system_buffer.v3.StreamConfig) Optional configuration for how to buffer (or not) responses. If unset in route, vhost and listener,
StreamConfig
default values will be used (with behaviorstream_when_possible
)