http: setting default lazy headermap threshold to 3

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 <faq_configuration_timeouts>` 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.

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 <arch_overview_http_header_map_settings>` 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*

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<uint32_t>(Runtime::getInteger(
-              "envoy.http.headermap.lazy_map_min_size", std::numeric_limits<uint32_t>::max()))) {}
+          lazy_map_min_size_(static_cast<uint32_t>(
+              Runtime::getInteger("envoy.http.headermap.lazy_map_min_size", 3))) {}
 
     template <class Key> bool isPseudoHeader(const Key& key) {
       return !key.getStringView().empty() && key.getStringView()[0] == ':';

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