dynamic_modules: per-cluster persistent cross-priority host map via cluster ABI

The cross-priority host map rebuilds itself with a full O(N) make_shared<HostMap>
copy on every membership delta. MainPrioritySetImpl can now back it with an immer
persistent map so a delta is applied in O(delta), selected per cluster via
setUsePersistentCrossPriorityHostMap(). crossPriorityHostMap() returns an abstract
HostLookupTable backed by either the legacy flat map (the default, preserving the
exact prior behavior) or the immer map, and updateDynamicHostList takes a
host-lookup functor so it stays backing-agnostic.

Dynamic-modules clusters opt in through the new
envoy_dynamic_module_callback_cluster_use_persistent_host_map ABI callback (the
DynamicModuleCluster::setUsePersistentHostMap forwarder) and the Rust SDK
EnvoyCluster::set_use_persistent_host_map method. Membership behavior is identical
under either backing.

Signed-off-by: Rohit Agrawal <rohit.agrawal@databricks.com>

Author: agrawroh

bazel/deps.yaml

@@ -939,6 +939,17 @@ fp16:
   extensions:
   - envoy.wasm.runtime.v8
 
+immer:
+  project_name: "immer"
+  project_desc: "Header-only library of persistent and immutable data structures for C++"
+  project_url: "https://github.com/arximboldi/immer"
+  release_date: "2026-01-13"
+  use_category:
+  - dataplane_core
+  cpe: "N/A"
+  license: "BSL-1.0"
+  license_url: "https://github.com/arximboldi/immer/blob/v{version}/LICENSE"
+
 googleurl:
   project_name: "Chrome URL parsing library"
   project_desc: "Chrome URL parsing library"

bazel/external/immer.BUILD

@@ -0,0 +1,11 @@
+load("@rules_cc//cc:defs.bzl", "cc_library")
+
+licenses(["notice"])  # BSL-1.0
+
+package(default_visibility = ["//visibility:public"])
+
+cc_library(
+    name = "immer",
+    hdrs = glob(["immer/**/*.hpp"]),
+    includes = ["."],
+)

bazel/repositories.bzl

@@ -211,6 +211,7 @@ def envoy_dependencies(skip_targets = []):
     _highway()
     _dragonbox()
     _fp16()
+    _immer()
     _simdutf()
     _quiche()
     _googleurl()
@@ -806,6 +807,12 @@ def _fp16():
         build_file = "@envoy//bazel/external:fp16.BUILD",
     )
 
+def _immer():
+    external_http_archive(
+        name = "immer",
+        build_file = "@envoy//bazel/external:immer.BUILD",
+    )
+
 def _simdutf():
     external_http_archive(
         name = "simdutf",

bazel/repository_locations.bzl

@@ -546,6 +546,12 @@ REPOSITORY_LOCATIONS_SPEC = dict(
         sha256 = "e2da4f41bae8869f8dee56f4c104e699e7de3a483b5e451fda8e76fbcc66c59a",
         urls = ["https://github.com/Maratyszcza/FP16/archive/{version}.zip"],
     ),
+    immer = dict(
+        version = "0.9.1",
+        strip_prefix = "immer-{version}",
+        sha256 = "b18b92ba60ec3186dc36ef671d3c2ae542cbb63eb6dc0e258476c6111a67c971",
+        urls = ["https://github.com/arximboldi/immer/archive/v{version}.tar.gz"],
+    ),
     simdutf = dict(
         # NOTE: Update together with v8 and proxy_wasm_cpp_host.
         version = "8.1.0",

changelogs/current/new_features/dynamic_modules__added-cluster-use-persistent-host-map.rst

@@ -0,0 +1,5 @@
+Added the ``envoy_dynamic_module_callback_cluster_use_persistent_host_map`` ABI callback so that a
+dynamic-modules cluster can opt into a persistent cross-priority host map in place of the
+default flat copy-on-write map, making each membership delta O(delta) instead of an O(N) flat copy.
+Membership behavior is identical under either backing, and the flat map remains the default. The
+Rust SDK exposes this as ``EnvoyCluster::set_use_persistent_host_map``.

envoy/upstream/BUILD

@@ -170,6 +170,7 @@ envoy_cc_library(
         "//envoy/ssl:context_interface",
         "//envoy/ssl:context_manager_interface",
         "//envoy/upstream:types_interface",
+        "@abseil-cpp//absl/functional:function_ref",
         "@envoy_api//envoy/config/cluster/v3:pkg_cc_proto",
         "@envoy_api//envoy/config/core/v3:pkg_cc_proto",
     ],

envoy/upstream/upstream.h

@@ -29,6 +29,7 @@
 #include "envoy/upstream/resource_manager.h"
 #include "envoy/upstream/types.h"
 
+#include "absl/functional/function_ref.h"
 #include "absl/strings/string_view.h"
 #include "fmt/format.h"
 
@@ -362,6 +363,53 @@ using ExcludedHostVector = Phantom<HostVector, Excluded>;
 using HostMap = absl::flat_hash_map<std::string, Upstream::HostSharedPtr>;
 using HostMapSharedPtr = std::shared_ptr<HostMap>;
 using HostMapConstSharedPtr = std::shared_ptr<const HostMap>;
+
+/**
+ * Read-only host-by-address lookup published to workers. Backed by either the flat HostMap (the
+ * default) or a persistent map, selected per cluster via
+ * `MainPrioritySetImpl::setUsePersistentCrossPriorityHostMap`, so the backing is swappable without
+ * changing consumers.
+ */
+class HostLookupTable {
+public:
+  virtual ~HostLookupTable() = default;
+
+  /**
+   * @param address the host address to look up.
+   * @return HostSharedPtr the host for the address, or nullptr if absent.
+   */
+  virtual HostSharedPtr findHost(absl::string_view address) const PURE;
+
+  /**
+   * @return size_t the number of hosts in the table.
+   */
+  virtual size_t size() const PURE;
+
+  /**
+   * @return bool true if the table holds no hosts.
+   */
+  virtual bool empty() const PURE;
+
+  /**
+   * Invokes a callback for each (address, host) entry. Iteration order is unspecified.
+   *
+   * @param cb the callback to invoke for each entry.
+   */
+  virtual void
+  forEach(absl::FunctionRef<void(const std::string&, const HostSharedPtr&)> cb) const PURE;
+};
+using HostLookupTableConstSharedPtr = std::shared_ptr<const HostLookupTable>;
+
+/**
+ * Wraps a flat HostMap in the HostLookupTable interface. Defined in upstream_impl.cc so the
+ * concrete type stays private. Available to tests and consumers that hold a HostMap but need to
+ * publish a HostLookupTable.
+ *
+ * @param map the flat host map to wrap.
+ * @return HostLookupTableConstSharedPtr a lookup table backed by the given map.
+ */
+HostLookupTableConstSharedPtr makeFlatHostLookupTable(HostMapConstSharedPtr map);
+
 using HostVectorSharedPtr = std::shared_ptr<HostVector>;
 using HostVectorConstSharedPtr = std::shared_ptr<const HostVector>;
 
@@ -590,10 +638,10 @@ class PrioritySet {
   virtual const std::vector<HostSetPtr>& hostSetsPerPriority() const PURE;
 
   /**
-   * @return HostMapConstSharedPtr read only cross priority host map that indexed by host address
-   * string.
+   * @return HostLookupTableConstSharedPtr read only cross priority host lookup table indexed by
+   * host address string.
    */
-  virtual HostMapConstSharedPtr crossPriorityHostMap() const PURE;
+  virtual HostLookupTableConstSharedPtr crossPriorityHostMap() const PURE;
 
   /**
    * Parameter class for updateHosts.
@@ -627,7 +675,7 @@ class PrioritySet {
                            const HostVector& hosts_added, const HostVector& hosts_removed,
                            std::optional<bool> weighted_priority_health,
                            std::optional<uint32_t> overprovisioning_factor,
-                           HostMapConstSharedPtr cross_priority_host_map = nullptr) PURE;
+                           HostLookupTableConstSharedPtr cross_priority_host_map = nullptr) PURE;
 
   /**
    * Callback provided during batch updates that can be used to update hosts.

source/common/upstream/BUILD

@@ -385,6 +385,24 @@ envoy_cc_library(
     ],
 )
 
+envoy_cc_library(
+    name = "persistent_host_map_lib",
+    srcs = ["persistent_host_map.cc"],
+    hdrs = ["persistent_host_map.h"],
+    # `immer`'s variable-length CHAMP nodes use a flexible array member, so the shared empty-node
+    # singleton is constructed in a buffer smaller than `sizeof(node)`. The vptr sanitizer reads
+    # that as a constructor call on insufficient space and reports a false positive, so `immer` is
+    # confined to this library with vptr disabled here only. The check stays enabled elsewhere.
+    copts = ["-fno-sanitize=vptr"],
+    rbe_pool = "6gig",
+    deps = [
+        "//envoy/upstream:upstream_interface",
+        "@abseil-cpp//absl/functional:function_ref",
+        "@abseil-cpp//absl/strings:string_view",
+        "@immer",
+    ],
+)
+
 envoy_cc_library(
     name = "upstream_lib",
     srcs = ["upstream_impl.cc"],
@@ -393,6 +411,7 @@ envoy_cc_library(
         ":cluster_factory_lib",
         ":default_local_address_selector_factory",
         ":health_checker_lib",
+        ":persistent_host_map_lib",
         # TODO(mattklein123): Move the clusters to extensions so they can be compiled out.
         ":upstream_includes",
         ":transport_socket_match_lib",
@@ -504,6 +523,7 @@ envoy_cc_library(
         "//source/extensions/upstreams/http:config",
         "//source/extensions/upstreams/tcp:config",
         "//source/server:transport_socket_config_lib",
+        "@abseil-cpp//absl/functional:function_ref",
         "@abseil-cpp//absl/synchronization",
         "@envoy_api//envoy/config/cluster/v3:pkg_cc_proto",
         "@envoy_api//envoy/config/core/v3:pkg_cc_proto",

source/common/upstream/cluster_manager_impl.cc

@@ -1194,7 +1194,8 @@ void ClusterManagerImpl::postThreadLocalClusterUpdate(ClusterManagerCluster& cm_
     per_priority.overprovisioning_factor_ = host_set->overprovisioningFactor();
   }
 
-  HostMapConstSharedPtr host_map = cm_cluster.cluster().prioritySet().crossPriorityHostMap();
+  HostLookupTableConstSharedPtr host_map =
+      cm_cluster.cluster().prioritySet().crossPriorityHostMap();
 
   pending_cluster_creations_.erase(cm_cluster.cluster().info()->name());
 
@@ -1304,7 +1305,7 @@ void ClusterManagerImpl::postThreadLocalClusterUpdate(ClusterManagerCluster& cm_
 ClusterManagerImpl::ClusterInitializationObjectConstSharedPtr
 ClusterManagerImpl::addOrUpdateClusterInitializationObjectIfSupported(
     const ThreadLocalClusterUpdateParams& params, ClusterInfoConstSharedPtr cluster_info,
-    LoadBalancerFactorySharedPtr load_balancer_factory, HostMapConstSharedPtr map,
+    LoadBalancerFactorySharedPtr load_balancer_factory, HostLookupTableConstSharedPtr map,
     UnitFloat drop_overload, absl::string_view drop_category) {
   if (!deferralIsSupportedForCluster(cluster_info)) {
     return nullptr;
@@ -1386,7 +1387,7 @@ ClusterManagerImpl::ThreadLocalClusterManagerImpl::initializeClusterInlineIfExis
 
 ClusterManagerImpl::ClusterInitializationObject::ClusterInitializationObject(
     const ThreadLocalClusterUpdateParams& params, ClusterInfoConstSharedPtr cluster_info,
-    LoadBalancerFactorySharedPtr load_balancer_factory, HostMapConstSharedPtr map,
+    LoadBalancerFactorySharedPtr load_balancer_factory, HostLookupTableConstSharedPtr map,
     UnitFloat drop_overload, absl::string_view drop_category)
     : cluster_info_(std::move(cluster_info)), load_balancer_factory_(load_balancer_factory),
       cross_priority_host_map_(map), drop_overload_(drop_overload), drop_category_(drop_category) {
@@ -1399,7 +1400,7 @@ ClusterManagerImpl::ClusterInitializationObject::ClusterInitializationObject(
 ClusterManagerImpl::ClusterInitializationObject::ClusterInitializationObject(
     const absl::flat_hash_map<int, ThreadLocalClusterUpdateParams::PerPriority>& per_priority_state,
     const ThreadLocalClusterUpdateParams& update_params, ClusterInfoConstSharedPtr cluster_info,
-    LoadBalancerFactorySharedPtr load_balancer_factory, HostMapConstSharedPtr map,
+    LoadBalancerFactorySharedPtr load_balancer_factory, HostLookupTableConstSharedPtr map,
     UnitFloat drop_overload, absl::string_view drop_category)
     : per_priority_state_(per_priority_state), cluster_info_(std::move(cluster_info)),
       load_balancer_factory_(load_balancer_factory), cross_priority_host_map_(map),
@@ -1513,7 +1514,7 @@ void ClusterManagerImpl::ThreadLocalClusterManagerImpl::ClusterEntry::updateHost
     LocalityWeightsConstSharedPtr locality_weights, const HostVector& hosts_added,
     const HostVector& hosts_removed, std::optional<bool> weighted_priority_health,
     std::optional<uint32_t> overprovisioning_factor,
-    HostMapConstSharedPtr cross_priority_host_map) {
+    HostLookupTableConstSharedPtr cross_priority_host_map) {
   ENVOY_LOG(debug, "membership update for TLS cluster {} added {} removed {}", name,
             hosts_added.size(), hosts_removed.size());
   priority_set_.updateHosts(priority, std::move(update_hosts_params), std::move(locality_weights),
@@ -1841,7 +1842,7 @@ void ClusterManagerImpl::ThreadLocalClusterManagerImpl::updateClusterMembership(
     const std::string& name, uint32_t priority, PrioritySet::UpdateHostsParams update_hosts_params,
     LocalityWeightsConstSharedPtr locality_weights, const HostVector& hosts_added,
     const HostVector& hosts_removed, bool weighted_priority_health,
-    uint64_t overprovisioning_factor, HostMapConstSharedPtr cross_priority_host_map) {
+    uint64_t overprovisioning_factor, HostLookupTableConstSharedPtr cross_priority_host_map) {
   ASSERT(thread_local_clusters_.find(name) != thread_local_clusters_.end());
   const auto& cluster_entry = thread_local_clusters_[name];
   cluster_entry->updateHosts(name, priority, std::move(update_hosts_params),

source/common/upstream/cluster_manager_impl.h

@@ -454,20 +454,20 @@ class ClusterManagerImpl : public ClusterManager,
     ClusterInitializationObject(const ThreadLocalClusterUpdateParams& params,
                                 ClusterInfoConstSharedPtr cluster_info,
                                 LoadBalancerFactorySharedPtr load_balancer_factory,
-                                HostMapConstSharedPtr map, UnitFloat drop_overload,
+                                HostLookupTableConstSharedPtr map, UnitFloat drop_overload,
                                 absl::string_view drop_category);
 
     ClusterInitializationObject(
         const absl::flat_hash_map<int, ThreadLocalClusterUpdateParams::PerPriority>&
             per_priority_state,
         const ThreadLocalClusterUpdateParams& update_params, ClusterInfoConstSharedPtr cluster_info,
-        LoadBalancerFactorySharedPtr load_balancer_factory, HostMapConstSharedPtr map,
+        LoadBalancerFactorySharedPtr load_balancer_factory, HostLookupTableConstSharedPtr map,
         UnitFloat drop_overload, absl::string_view drop_category);
 
     absl::flat_hash_map<int, ThreadLocalClusterUpdateParams::PerPriority> per_priority_state_;
     const ClusterInfoConstSharedPtr cluster_info_;
     const LoadBalancerFactorySharedPtr load_balancer_factory_;
-    const HostMapConstSharedPtr cross_priority_host_map_;
+    const HostLookupTableConstSharedPtr cross_priority_host_map_;
     UnitFloat drop_overload_{0};
     const std::string drop_category_;
   };
@@ -628,7 +628,7 @@ class ClusterManagerImpl : public ClusterManager,
                        const HostVector& hosts_added, const HostVector& hosts_removed,
                        std::optional<bool> weighted_priority_health,
                        std::optional<uint32_t> overprovisioning_factor,
-                       HostMapConstSharedPtr cross_priority_host_map);
+                       HostLookupTableConstSharedPtr cross_priority_host_map);
 
       // Drains any connection pools associated with the removed hosts. All connections will be
       // closed gracefully and no new connections will be created.
@@ -720,7 +720,7 @@ class ClusterManagerImpl : public ClusterManager,
                                  LocalityWeightsConstSharedPtr locality_weights,
                                  const HostVector& hosts_added, const HostVector& hosts_removed,
                                  bool weighted_priority_health, uint64_t overprovisioning_factor,
-                                 HostMapConstSharedPtr cross_priority_host_map);
+                                 HostLookupTableConstSharedPtr cross_priority_host_map);
     void onHostHealthFailure(const HostSharedPtr& host);
 
     ConnPoolsContainer* getHttpConnPoolsContainer(const HostConstSharedPtr& host,
@@ -931,7 +931,7 @@ class ClusterManagerImpl : public ClusterManager,
    */
   ClusterInitializationObjectConstSharedPtr addOrUpdateClusterInitializationObjectIfSupported(
       const ThreadLocalClusterUpdateParams& params, ClusterInfoConstSharedPtr cluster_info,
-      LoadBalancerFactorySharedPtr load_balancer_factory, HostMapConstSharedPtr map,
+      LoadBalancerFactorySharedPtr load_balancer_factory, HostLookupTableConstSharedPtr map,
       UnitFloat drop_overload, absl::string_view drop_category);
 
   bool deferralIsSupportedForCluster(const ClusterInfoConstSharedPtr& info) const;