diff --git a/docs/root/intro/arch_overview/http/http_connection_management.rst b/docs/root/intro/arch_overview/http/http_connection_management.rst index f25d721cc52ec..bc2731b9e0412 100644 --- a/docs/root/intro/arch_overview/http/http_connection_management.rst +++ b/docs/root/intro/arch_overview/http/http_connection_management.rst @@ -245,3 +245,16 @@ Timeouts Various configurable timeouts apply to an HTTP connection and its constituent streams. Please see :ref:`this FAQ entry ` for an overview of important timeout configuration. + +.. _arch_overview_http_header_map_settings: + +HTTP header map settings +------------------------ + +Envoy maintains the insertion order of headers (and pseudo headers that begin with ":") in the +HTTP header map using a linked list data-structure, which is very fast when the number of headers +is small. In addition it can use a map data-structure to ensure fast access to the various headers. +The map will be used once the number of headers in a HTTP request/response reaches the value of the +``envoy.http.headermap.lazy_map_min_size`` runtime feature. The default threshold value is set to +3, as previous experiments empirically showed that this value provides good performance for many +use-cases. diff --git a/docs/root/version_history/current.rst b/docs/root/version_history/current.rst index eff53425bf8dd..b4360a9bdc5e8 100644 --- a/docs/root/version_history/current.rst +++ b/docs/root/version_history/current.rst @@ -9,6 +9,11 @@ Minor Behavior Changes ---------------------- *Changes that may cause incompatibilities for some users, but should not for most* +* http: set the default :ref:`lazy headermap threshold ` to 3, + which defines the minimal number of headers in a request/response/trailers required for using a + dictionary in addition to the list. Setting the `envoy.http.headermap.lazy_map_min_size` runtime + feature to a non-negative number will override the default value. + Bug Fixes --------- *Changes expected to improve the state of the world and are unlikely to have negative effects* diff --git a/source/common/http/header_map_impl.h b/source/common/http/header_map_impl.h index 42a9bfde4a548..79dd2d54c6bb5 100644 --- a/source/common/http/header_map_impl.h +++ b/source/common/http/header_map_impl.h @@ -182,7 +182,7 @@ class HeaderMapImpl : NonCopyable { * List of HeaderEntryImpl that keeps the pseudo headers (key starting with ':') in the front * of the list (as required by nghttp2) and otherwise maintains insertion order. * When the list size is greater or equal to the envoy.http.headermap.lazy_map_min_size runtime - * feature value (or uint32_t max value if not set), all headers are added to a map, to allow + * feature value (defaults to 3, if not set), all headers are added to a map, to allow * fast access given a header key. Once the map is initialized, it will be used even if the number * of headers decreases below the threshold. * @@ -200,8 +200,8 @@ class HeaderMapImpl : NonCopyable { HeaderList() : pseudo_headers_end_(headers_.end()), - lazy_map_min_size_(static_cast(Runtime::getInteger( - "envoy.http.headermap.lazy_map_min_size", std::numeric_limits::max()))) {} + lazy_map_min_size_(static_cast( + Runtime::getInteger("envoy.http.headermap.lazy_map_min_size", 3))) {} template bool isPseudoHeader(const Key& key) { return !key.getStringView().empty() && key.getStringView()[0] == ':'; diff --git a/source/docs/header_map.md b/source/docs/header_map.md index de2a52fe27ea4..2a5eef11500e9 100644 --- a/source/docs/header_map.md +++ b/source/docs/header_map.md @@ -3,6 +3,8 @@ The Envoy header map implementation (`HeaderMapImpl`) has the following properties: * Headers are stored in a linked list (`HeaderList`) in the order they are added, with pseudo headers kept at the front of the list. +* Once the number of headers is at least the runtime configured feature `envoy.http.headermap.lazy_map_min_size`, + the header map will also use a map (`HeaderLazyMap`), in addition to the linked list, for faster access to the headers. * O(1) direct access is possible for common headers needed during data plane processing. This is provided by a table of pointers that reach directly into a linked list that is populated when headers are added or removed from the map. When O(1) headers are accessed by direct method @@ -12,8 +14,8 @@ The Envoy header map implementation (`HeaderMapImpl`) has the following properti request trailers, response headers, and response trailers) via core code and extensions (`CustomInlineHeaderRegistry`). Each registered header increases the size of the table by the size of a single pointer. * Operations that search, replace, etc. for a header by name that is not one of the O(1) headers - will incur an O(N) search through the linked list. This is an implementation deficiency for - certain usage patterns that will be improved in future changes. + will either incur an O(N) search through the linked list if the number of headers is below `envoy.http.headermap.lazy_map_min_size`, + and O(1) map access otherwise. ## Implementation details