dynamic_modules: add packed-address getter for cluster LB member updates (#45626)

**Commit Message:** dynamic_modules: add packed-address getter for
cluster LB member updates

**Additional Description:**

A dynamic module cluster LB that keeps its own address-to-host map fills
it during on_host_membership_update via get_member_update_host_address,
which returns each host's address as a formatted string. In clusters
with millions of hosts this dominates the update cost. Envoy formats the
sockaddr into a string, copies it across the ABI, and the module hashes
and byte-compares it on every insert and lookup; yet the string is
derived data, since Envoy already stores the address in parsed form.
This adds get_member_update_host_packed_address, which reads the IP
bytes and port straight from the sockaddr so a module can key its map by
an integer instead.
  
The getter is additive; existing getters and the
on_host_membership_update contract are unchanged.

Risk Level: Low
Testing: Unit and Integration Tests
Docs Changes:
Release Notes:
Platform Specific Features:

---------

Signed-off-by: Basundhara Chakrabarty <basundhara17061996@gmail.com>

Author: basundhara-c

source/extensions/clusters/dynamic_modules/abi_impl.cc

@@ -2,7 +2,10 @@
 
 // This file provides host-side implementations for the cluster dynamic module ABI callbacks.
 
+#include <cstring>
+
 #include "source/common/common/assert.h"
+#include "source/common/common/safe_memcpy.h"
 #include "source/common/common/thread.h"
 #include "source/common/http/message_impl.h"
 #include "source/common/router/string_accessor_impl.h"
@@ -1367,4 +1370,44 @@ envoy_dynamic_module_callback_cluster_lb_get_member_update_host(
   return const_cast<Envoy::Upstream::Host*>((*hosts)[index].get());
 }
 
+bool envoy_dynamic_module_callback_cluster_lb_get_member_update_host_packed_address(
+    envoy_dynamic_module_type_cluster_lb_envoy_ptr lb_envoy_ptr, size_t index, bool is_added,
+    envoy_dynamic_module_type_packed_address* result) {
+  if (lb_envoy_ptr == nullptr || result == nullptr) {
+    return false;
+  }
+  const auto* hosts =
+      is_added ? getLb(lb_envoy_ptr)->hostsAdded() : getLb(lb_envoy_ptr)->hostsRemoved();
+  if (hosts == nullptr || index >= hosts->size()) {
+    return false;
+  }
+  // Null for a pipe (non-IP) address; the packed representation only covers IP addresses.
+  const auto* ip = (*hosts)[index]->address()->ip();
+  if (ip == nullptr) {
+    return false;
+  }
+  std::memset(result->address_bytes, 0, sizeof(result->address_bytes));
+  // Both accessors return the address in network byte order, read straight from the sockaddr; see
+  // Ipv4/Ipv6Instance in source/common/network/address_impl.{h,cc}.
+  switch (ip->version()) {
+  case Envoy::Network::Address::IpVersion::v4: {
+    result->family = 4;
+    const uint32_t v4 = ip->ipv4()->address();
+    Envoy::safeMemcpyUnsafeDst(result->address_bytes, &v4);
+    break;
+  }
+  case Envoy::Network::Address::IpVersion::v6: {
+    result->family = 6;
+    const absl::uint128 v6 = ip->ipv6()->address();
+    Envoy::safeMemcpyUnsafeDst(result->address_bytes, &v6);
+    break;
+  }
+  default:
+    IS_ENVOY_BUG("unexpected IP version in cluster LB packed address getter");
+    return false;
+  }
+  result->port = static_cast<uint16_t>(ip->port());
+  return true;
+}
+
 } // extern "C"

source/extensions/dynamic_modules/abi/abi.h

@@ -10030,6 +10030,43 @@ envoy_dynamic_module_type_cluster_host_envoy_ptr
 envoy_dynamic_module_callback_cluster_lb_get_member_update_host(
     envoy_dynamic_module_type_cluster_lb_envoy_ptr lb_envoy_ptr, size_t index, bool is_added);
 
+/**
+ * envoy_dynamic_module_type_packed_address holds a host's IP address and port as packed integers,
+ * read directly from the host's parsed sockaddr without any string formatting. This is the output
+ * of envoy_dynamic_module_callback_cluster_lb_get_member_update_host_packed_address.
+ *
+ * @param address_bytes is the IP address in network byte order. An IPv4 address occupies the first
+ * four bytes; an IPv6 address occupies all sixteen. Bytes beyond the address are zeroed.
+ * @param port is the port in host byte order.
+ * @param family is 4 for an IPv4 address and 6 for an IPv6 address.
+ */
+typedef struct envoy_dynamic_module_type_packed_address {
+  uint8_t address_bytes[16];
+  uint16_t port;
+  uint8_t family;
+} envoy_dynamic_module_type_packed_address;
+
+/**
+ * envoy_dynamic_module_callback_cluster_lb_get_member_update_host_packed_address returns the
+ * address of an added or removed host during the on_cluster_lb_on_host_membership_update event hook
+ * as packed integers, read directly from the host's sockaddr with no string formatting or
+ * allocation. This is the packed-integer sibling of
+ * envoy_dynamic_module_callback_cluster_lb_get_member_update_host_address, intended for modules
+ * that key their own host maps by an integer rather than a string. It is only valid during
+ * envoy_dynamic_module_on_cluster_lb_on_host_membership_update.
+ *
+ * @param lb_envoy_ptr is the pointer to the Envoy cluster load balancer.
+ * @param index is the index of the host in the added or removed list.
+ * @param is_added is true to get an added host address, false to get a removed host address.
+ * @param result is the output buffer that receives the packed address. Its contents are unspecified
+ * when the callback returns false; callers must gate on the return value.
+ * @return true if the host was found and has an IP address, false on a null pointer, an
+ * out-of-bounds index, the callback not being active, or a non-IP (pipe) address.
+ */
+bool envoy_dynamic_module_callback_cluster_lb_get_member_update_host_packed_address(
+    envoy_dynamic_module_type_cluster_lb_envoy_ptr lb_envoy_ptr, size_t index, bool is_added,
+    envoy_dynamic_module_type_packed_address* result);
+
 // =============================================================================
 // =============================== Load Balancer ===============================
 // =============================================================================

source/extensions/dynamic_modules/abi_impl.cc

@@ -509,6 +509,15 @@ envoy_dynamic_module_callback_cluster_lb_get_member_update_host(
   return nullptr;
 }
 
+__attribute__((weak)) bool
+envoy_dynamic_module_callback_cluster_lb_get_member_update_host_packed_address(
+    envoy_dynamic_module_type_cluster_lb_envoy_ptr, size_t, bool,
+    envoy_dynamic_module_type_packed_address*) {
+  IS_ENVOY_BUG("envoy_dynamic_module_callback_cluster_lb_get_member_update_host_packed_address: "
+               "not implemented in this context");
+  return false;
+}
+
 __attribute__((weak)) void envoy_dynamic_module_callback_cluster_pre_init_complete(
     envoy_dynamic_module_type_cluster_envoy_ptr) {
   IS_ENVOY_BUG("envoy_dynamic_module_callback_cluster_pre_init_complete: "

source/extensions/dynamic_modules/sdk/rust/src/cluster.rs

@@ -124,6 +124,20 @@ pub enum HostSelectionResult {
   AsyncPending(Box<dyn AsyncHostSelectionHandle>),
 }
 
+/// A host's IP address and port as packed integers.
+///
+/// This is the decoded form of the packed address returned by
+/// [`EnvoyClusterLoadBalancer::get_member_update_host_packed_address`]. The address bytes are in
+/// network byte order and the port is in host byte order, letting a module key its own host map by
+/// an integer rather than a formatted string.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum PackedAddress {
+  /// An IPv4 address (4 bytes, network byte order) and port (host byte order).
+  V4([u8; 4], u16),
+  /// An IPv6 address (16 bytes, network byte order) and port (host byte order).
+  V6([u8; 16], u16),
+}
+
 /// A handle for canceling an in-progress asynchronous host selection.
 ///
 /// When the stream is destroyed before async host selection completes (e.g., due to a timeout),
@@ -660,6 +674,23 @@ pub trait EnvoyClusterLoadBalancer: Send {
     index: usize,
     is_added: bool,
   ) -> Option<abi::envoy_dynamic_module_type_cluster_host_envoy_ptr>;
+
+  /// Returns the address of an added or removed host during the
+  /// [`ClusterLb::on_host_membership_update`] callback as packed integers.
+  ///
+  /// Unlike [`EnvoyClusterLoadBalancer::get_member_update_host_address`], this reads the IP address
+  /// and port directly from the host's sockaddr without formatting a string, so a module can key
+  /// its own host map by an integer. It is only valid during the `on_host_membership_update`
+  /// callback.
+  ///
+  /// Set `is_added` to `true` to get an added host address, `false` for a removed host address.
+  /// Returns `None` when the index is out of bounds, the callback is not active, or the host has a
+  /// non-IP (pipe) address.
+  fn get_member_update_host_packed_address(
+    &self,
+    index: usize,
+    is_added: bool,
+  ) -> Option<PackedAddress>;
 }
 
 /// Envoy-side scheduler that dispatches events to the main thread.
@@ -1496,6 +1527,38 @@ impl EnvoyClusterLoadBalancer for EnvoyClusterLoadBalancerImpl {
       Some(host)
     }
   }
+
+  fn get_member_update_host_packed_address(
+    &self,
+    index: usize,
+    is_added: bool,
+  ) -> Option<PackedAddress> {
+    let mut result = abi::envoy_dynamic_module_type_packed_address {
+      address_bytes: [0; 16],
+      port: 0,
+      family: 0,
+    };
+    let found = unsafe {
+      abi::envoy_dynamic_module_callback_cluster_lb_get_member_update_host_packed_address(
+        self.raw,
+        index,
+        is_added,
+        &mut result,
+      )
+    };
+    if !found {
+      return None;
+    }
+    match result.family {
+      4 => {
+        let mut v4 = [0u8; 4];
+        v4.copy_from_slice(&result.address_bytes[..4]);
+        Some(PackedAddress::V4(v4, result.port))
+      },
+      6 => Some(PackedAddress::V6(result.address_bytes, result.port)),
+      _ => None,
+    }
+  }
 }
 
 /// Implementation of [`EnvoyClusterMetrics`] that calls into the Envoy ABI.

source/extensions/dynamic_modules/sdk/rust/src/lib_test.rs

@@ -4259,6 +4259,16 @@ pub extern "C" fn envoy_dynamic_module_callback_cluster_lb_get_member_update_hos
   std::ptr::null_mut()
 }
 
+#[no_mangle]
+pub extern "C" fn envoy_dynamic_module_callback_cluster_lb_get_member_update_host_packed_address(
+  _lb_envoy_ptr: abi::envoy_dynamic_module_type_cluster_lb_envoy_ptr,
+  _index: usize,
+  _is_added: bool,
+  _result: *mut abi::envoy_dynamic_module_type_packed_address,
+) -> bool {
+  false
+}
+
 #[no_mangle]
 pub extern "C" fn envoy_dynamic_module_callback_cluster_lb_async_host_selection_complete(
   _lb_envoy_ptr: abi::envoy_dynamic_module_type_cluster_lb_envoy_ptr,
@@ -5291,6 +5301,45 @@ fn test_cluster_lb_get_member_update_host_none() {
   assert!(mock_lb.get_member_update_host(0, false).is_none());
 }
 
+#[test]
+fn test_cluster_lb_get_member_update_host_packed_address() {
+  let mut mock_lb = cluster::MockEnvoyClusterLoadBalancer::new();
+  mock_lb
+    .expect_get_member_update_host_packed_address()
+    .withf(|index, is_added| *index == 0 && *is_added)
+    .returning(|_, _| Some(cluster::PackedAddress::V4([127, 0, 0, 1], 10001)));
+  mock_lb
+    .expect_get_member_update_host_packed_address()
+    .withf(|_, is_added| !*is_added)
+    .returning(|_, _| Some(cluster::PackedAddress::V6([1; 16], 10002)));
+
+  match mock_lb.get_member_update_host_packed_address(0, true) {
+    Some(cluster::PackedAddress::V4(addr, port)) => {
+      assert_eq!(addr, [127, 0, 0, 1]);
+      assert_eq!(port, 10001);
+    },
+    other => panic!("expected V4, got {other:?}"),
+  }
+  match mock_lb.get_member_update_host_packed_address(0, false) {
+    Some(cluster::PackedAddress::V6(addr, port)) => {
+      assert_eq!(addr, [1; 16]);
+      assert_eq!(port, 10002);
+    },
+    other => panic!("expected V6, got {other:?}"),
+  }
+}
+
+#[test]
+fn test_cluster_lb_get_member_update_host_packed_address_none() {
+  let mut mock_lb = cluster::MockEnvoyClusterLoadBalancer::new();
+  mock_lb
+    .expect_get_member_update_host_packed_address()
+    .returning(|_, _| None);
+  assert!(mock_lb
+    .get_member_update_host_packed_address(0, false)
+    .is_none());
+}
+
 #[test]
 fn test_cluster_lb_get_host_locality() {
   let mut mock_lb = cluster::MockEnvoyClusterLoadBalancer::new();

test/extensions/clusters/dynamic_modules/cluster_test.cc

@@ -3408,6 +3408,76 @@ TEST_F(DynamicModuleClusterTest, LbMemberUpdateHostPointer) {
             envoy_dynamic_module_callback_cluster_lb_get_member_update_host(lb_ptr, 0, true));
 }
 
+// Test get_member_update_host_packed_address returns the packed IP/port during a membership update.
+TEST_F(DynamicModuleClusterTest, LbMemberUpdateHostPackedAddress) {
+  auto result = createCluster(makeYamlConfig("cluster_no_op"));
+  ASSERT_TRUE(result.ok()) << result.status().message();
+
+  auto cluster = std::dynamic_pointer_cast<DynamicModuleCluster>(result->first);
+  auto handle = std::make_shared<DynamicModuleClusterHandle>(cluster);
+  auto lb_instance = std::make_unique<DynamicModuleLoadBalancer>(handle, cluster->prioritySet());
+  auto* lb_ptr = static_cast<void*>(lb_instance.get());
+
+  // Distinctive octets so every byte position is pinned, and the upper twelve bytes must stay
+  // zeroed (no leftover from a previous v6 read), exercising the memset.
+  auto v4_host = Upstream::makeTestHost(cluster->info(), "tcp://1.2.3.4:10001");
+  // Distinctive bytes at both ends and the interior so a reversed/byte-swapped copy is caught.
+  auto v6_host = Upstream::makeTestHost(cluster->info(), "tcp://[2001:db8:1122:3344::1]:10002");
+  auto pipe_host = Upstream::makeTestHost(cluster->info(), "unix:///tmp/dynamic_modules_test");
+
+  envoy_dynamic_module_type_packed_address addr{};
+
+  // Outside a membership update callback the borrowed vectors are null, so the getter fails.
+  EXPECT_FALSE(envoy_dynamic_module_callback_cluster_lb_get_member_update_host_packed_address(
+      lb_ptr, 0, true, &addr));
+
+  Upstream::HostVector added{v4_host, v6_host};
+  Upstream::HostVector removed{pipe_host};
+  DynamicModuleClusterTestPeer::setMemberUpdateHosts(*lb_instance, &added, &removed);
+
+  // IPv6 host first: all sixteen bytes hold the address in network byte order. Reading it before
+  // the IPv4 host leaves non-zero bytes in the buffer, so the IPv4 read below must zero them.
+  ASSERT_TRUE(envoy_dynamic_module_callback_cluster_lb_get_member_update_host_packed_address(
+      lb_ptr, 1, true, &addr));
+  EXPECT_EQ(6, addr.family);
+  EXPECT_EQ(10002, addr.port);
+  const uint8_t expected_v6[16] = {0x20, 0x01, 0x0d, 0xb8, 0x11, 0x22, 0x33, 0x44,
+                                   0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01};
+  for (size_t i = 0; i < 16; ++i) {
+    EXPECT_EQ(expected_v6[i], addr.address_bytes[i]) << "v6 byte " << i;
+  }
+
+  // IPv4 host: address in the first four bytes (network byte order), the upper twelve zeroed by the
+  // memset (which must clear the leftover IPv6 bytes above), port in host byte order.
+  ASSERT_TRUE(envoy_dynamic_module_callback_cluster_lb_get_member_update_host_packed_address(
+      lb_ptr, 0, true, &addr));
+  EXPECT_EQ(4, addr.family);
+  EXPECT_EQ(10001, addr.port);
+  const uint8_t expected_v4[16] = {1, 2, 3, 4, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0};
+  for (size_t i = 0; i < 16; ++i) {
+    EXPECT_EQ(expected_v4[i], addr.address_bytes[i]) << "v4 byte " << i;
+  }
+
+  // A pipe (non-IP) address returns false.
+  EXPECT_FALSE(envoy_dynamic_module_callback_cluster_lb_get_member_update_host_packed_address(
+      lb_ptr, 0, false, &addr));
+
+  // Out-of-bounds index returns false.
+  EXPECT_FALSE(envoy_dynamic_module_callback_cluster_lb_get_member_update_host_packed_address(
+      lb_ptr, 2, true, &addr));
+
+  // Null load balancer and null result return false.
+  EXPECT_FALSE(envoy_dynamic_module_callback_cluster_lb_get_member_update_host_packed_address(
+      nullptr, 0, true, &addr));
+  EXPECT_FALSE(envoy_dynamic_module_callback_cluster_lb_get_member_update_host_packed_address(
+      lb_ptr, 0, true, nullptr));
+
+  // Once the callback ends the borrowed vectors are cleared and the getter fails again.
+  DynamicModuleClusterTestPeer::setMemberUpdateHosts(*lb_instance, nullptr, nullptr);
+  EXPECT_FALSE(envoy_dynamic_module_callback_cluster_lb_get_member_update_host_packed_address(
+      lb_ptr, 0, true, &addr));
+}
+
 // Test hosts-per-locality is correctly maintained with locality-aware hosts.
 TEST_F(DynamicModuleClusterTest, HostsPerLocalityWithLocality) {
   auto result = createCluster(makeYamlConfig("cluster_no_op"));

test/extensions/clusters/dynamic_modules/integration_test.cc

@@ -179,6 +179,26 @@ TEST_P(DynamicModuleClusterIntegrationTest, WorkerLocalPrioritySetRebuild) {
   EXPECT_EQ("200", response->headers().getStatusValue());
 }
 
+// Drives the packed member-update address getter end to end. Each worker load balancer reads the
+// added host's address both as a string and as packed integers and confirms they agree before
+// incrementing the counter, so this runs the real packing under both IPv4 and IPv6 params.
+TEST_P(DynamicModuleClusterIntegrationTest, MemberUpdatePackedAddress) {
+  concurrency_ = 2;
+  initializeWithDecCluster("member_update_packed_address");
+
+  // Each worker increments the counter once its packed address matches the formatted address.
+  test_server_->waitForCounter("dynamicmodulescustom.packed_address_verified_total",
+                               testing::Ge(2));
+
+  codec_client_ = makeHttpConnection(makeClientConnection(lookupPort("http")));
+  auto response =
+      sendRequestAndWaitForResponse(default_request_headers_, 0, default_response_headers_, 0);
+
+  EXPECT_TRUE(upstream_request_->complete());
+  EXPECT_TRUE(response->complete());
+  EXPECT_EQ("200", response->headers().getStatusValue());
+}
+
 // Verifies that the cluster lifecycle callbacks fire correctly during cluster
 // initialization.
 TEST_P(DynamicModuleClusterIntegrationTest, LifecycleCallbacks) {