PHP: Add refresh topology configuration (#70)

prateek-kumar-improving · web-flow · commit b0c3c1cb2c49 · 2025-11-05T16:45:18.000-08:00
* PHP: Add refresh topology

Signed-off-by: Prateek Kumar &lt;prateek.kumar@improving.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,7 @@
 
 #### Changes
 
+* PHP: Add refresh topology configuration
 * PHP: Add Multi-Database Support for Cluster Mode Valkey 9.0 - Added `database_id` parameter to `ValkeyGlideCluster` constructor and support for SELECT, COPY, and MOVE commands in cluster mode. The COPY command can now specify a `database_id` parameter for cross-database operations. This feature requires Valkey 9.0+ with `cluster-databases > 1` configuration.
 
 #### Documentation
diff --git a/common.h b/common.h
@@ -138,7 +138,8 @@ typedef struct {
     valkey_glide_base_client_configuration_t base;
     valkey_glide_periodic_checks_status_t    periodic_checks_status;
     valkey_glide_periodic_checks_manual_interval_t*
-        periodic_checks_manual; /* NULL if using status */
+         periodic_checks_manual;              /* NULL if using status */
+    bool refresh_topology_from_initial_nodes; /* false if not set */
 } valkey_glide_cluster_client_configuration_t;
 
 /* Configuration parsing functions */
diff --git a/src/client_constructor_mock.c b/src/client_constructor_mock.c
@@ -125,7 +125,7 @@ PHP_METHOD(ClientConstructorMock, simulate_standalone_constructor) {
     /* Build the connection request. */
     size_t   protobuf_message_len;
     uint8_t* request_bytes = create_connection_request(
-        "localhost", 6379, &protobuf_message_len, &client_config, 0, false);
+        "localhost", 6379, &protobuf_message_len, &client_config, 0, false, false);
 
     zval* php_request =
         build_php_connection_request(request_bytes, protobuf_message_len, &client_config);
@@ -175,14 +175,28 @@ PHP_METHOD(ClientConstructorMock, simulate_cluster_constructor) {
     /* Populate configuration parameters shared between client and cluster connections. */
     valkey_glide_build_client_config_base(&common_params, &client_config.base, true);
 
+    /* Parse cluster-specific advanced config options */
+    client_config.refresh_topology_from_initial_nodes = false; /* Default value */
+    if (common_params.advanced_config && Z_TYPE_P(common_params.advanced_config) == IS_ARRAY) {
+        HashTable* advanced_ht = Z_ARRVAL_P(common_params.advanced_config);
+        const char key_name[]  = "refresh_topology_from_initial_nodes";
+        zval*      refresh_topology_val =
+            zend_hash_str_find(advanced_ht, key_name, sizeof(key_name) - 1);
+        if (refresh_topology_val && Z_TYPE_P(refresh_topology_val) == IS_TRUE) {
+            client_config.refresh_topology_from_initial_nodes = true;
+        }
+    }
+
     /* Build the connection request. */
     size_t   protobuf_message_len;
-    uint8_t* request_bytes = create_connection_request("localhost",
-                                                       6379,
-                                                       &protobuf_message_len,
-                                                       &client_config.base,
-                                                       client_config.periodic_checks_status,
-                                                       true);
+    uint8_t* request_bytes =
+        create_connection_request("localhost",
+                                  6379,
+                                  &protobuf_message_len,
+                                  &client_config.base,
+                                  client_config.periodic_checks_status,
+                                  true,
+                                  client_config.refresh_topology_from_initial_nodes);
 
     zval* php_request =
         build_php_connection_request(request_bytes, protobuf_message_len, &client_config.base);
diff --git a/tests/ConnectionRequestTest.php b/tests/ConnectionRequestTest.php
@@ -460,4 +460,48 @@ public function testClusterPeriodicChecksDefault()
         $this->assertFalse($request->hasPeriodicChecksDisabled());
         $this->assertTrue($request->hasPeriodicChecksManualInterval());
     }
+
+    public function testClusterRefreshTopologyFromInitialNodesDefault()
+    {
+        // Test that refresh_topology_from_initial_nodes defaults to false when not specified
+        $request = ClientConstructorMock::simulate_cluster_constructor(
+            addresses: [['host' => 'localhost', 'port' => 8080]]
+        );
+        
+        $this->assertFalse($request->getRefreshTopologyFromInitialNodes());
+    }
+
+    public function testClusterRefreshTopologyFromInitialNodesEnabled()
+    {
+        // Test that refresh_topology_from_initial_nodes can be set to true
+        $request = ClientConstructorMock::simulate_cluster_constructor(
+            addresses: [['host' => 'localhost', 'port' => 8080]],
+            advanced_config: ['refresh_topology_from_initial_nodes' => true]
+        );
+        
+        $this->assertTrue($request->getRefreshTopologyFromInitialNodes());
+    }
+
+    public function testClusterRefreshTopologyFromInitialNodesDisabled()
+    {
+        // Test that refresh_topology_from_initial_nodes can be explicitly set to false
+        $request = ClientConstructorMock::simulate_cluster_constructor(
+            addresses: [['host' => 'localhost', 'port' => 8080]],
+            advanced_config: ['refresh_topology_from_initial_nodes' => false]
+        );
+        
+        $this->assertFalse($request->getRefreshTopologyFromInitialNodes());
+    }
+
+    public function testStandaloneRefreshTopologyFromInitialNodesIgnored()
+    {
+        // Test that refresh_topology_from_initial_nodes is ignored for standalone clients
+        $request = ClientConstructorMock::simulate_standalone_constructor(
+            addresses: [['host' => 'localhost', 'port' => 8080]],
+            advanced_config: ['refresh_topology_from_initial_nodes' => true]
+        );
+        
+        // Standalone clients should always have this as false (ignored)
+        $this->assertFalse($request->getRefreshTopologyFromInitialNodes());
+    }
 }
diff --git a/tests/ValkeyGlideClusterTest.php b/tests/ValkeyGlideClusterTest.php
@@ -1062,4 +1062,79 @@ public function testCopyMultiDatabase()
         $this->valkey_glide->select(0);
         $this->valkey_glide->del($srcKey);
     }
+
+    public function testRefreshTopologyFromInitialNodesDefault()
+    {
+        // Test that refresh_topology_from_initial_nodes defaults to false when not specified
+        $client = new ValkeyGlideCluster(
+            addresses: [['host' => 'localhost', 'port' => 7001]],
+            use_tls: false,
+            credentials: null,
+            read_from: ValkeyGlide::READ_FROM_PREFER_REPLICA,
+            request_timeout: null,
+            reconnect_strategy: null,
+            client_name: null,
+            periodic_checks: ValkeyGlideCluster::PERIODIC_CHECK_ENABLED_DEFAULT_CONFIGS,
+            client_az: null,
+            advanced_config: ['connection_timeout' => 5000]
+        );
+        
+        // Perform basic operation to verify client works
+        $result = $client->ping(['type' => 'primarySlotKey', 'key' => 'test']);
+        $this->assertTrue($result);
+        
+        $client->close();
+    }
+
+    public function testRefreshTopologyFromInitialNodesEnabled()
+    {
+        // Test that refresh_topology_from_initial_nodes can be set to true
+        $client = new ValkeyGlideCluster(
+            addresses: [['host' => 'localhost', 'port' => 7001]],
+            use_tls: false,
+            credentials: null,
+            read_from: ValkeyGlide::READ_FROM_PREFER_REPLICA,
+            request_timeout: null,
+            reconnect_strategy: null,
+            client_name: null,
+            periodic_checks: ValkeyGlideCluster::PERIODIC_CHECK_ENABLED_DEFAULT_CONFIGS,
+            client_az: null,
+            advanced_config: [
+                'connection_timeout' => 5000,
+                'refresh_topology_from_initial_nodes' => true
+            ]
+        );
+        
+        // Perform basic operation to verify client works
+        $result = $client->ping(['type' => 'primarySlotKey', 'key' => 'test']);
+        $this->assertTrue($result);
+        
+        $client->close();
+    }
+
+    public function testRefreshTopologyFromInitialNodesDisabled()
+    {
+        // Test that refresh_topology_from_initial_nodes can be explicitly set to false
+        $client = new ValkeyGlideCluster(
+            addresses: [['host' => 'localhost', 'port' => 7001]],
+            use_tls: false,
+            credentials: null,
+            read_from: ValkeyGlide::READ_FROM_PREFER_REPLICA,
+            request_timeout: null,
+            reconnect_strategy: null,
+            client_name: null,
+            periodic_checks: ValkeyGlideCluster::PERIODIC_CHECK_ENABLED_DEFAULT_CONFIGS,
+            client_az: null,
+            advanced_config: [
+                'connection_timeout' => 5000,
+                'refresh_topology_from_initial_nodes' => false
+            ]
+        );
+        
+        // Perform basic operation to verify client works
+        $result = $client->ping(['type' => 'primarySlotKey', 'key' => 'test']);
+        $this->assertTrue($result);
+        
+        $client->close();
+    }
 }
diff --git a/tests/ValkeyGlideTest.php b/tests/ValkeyGlideTest.php
@@ -7829,4 +7829,30 @@ public function testGetCommandWithConsoleLogging()
             echo "=======================================================\n";
         }
     }
+
+    public function testRefreshTopologyFromInitialNodesIgnoredInStandalone()
+    {
+        // Test that refresh_topology_from_initial_nodes is ignored for standalone clients
+        $client = new ValkeyGlide(
+            addresses: [['host' => 'localhost', 'port' => 6379]],
+            use_tls: false,
+            credentials: null,
+            read_from: ValkeyGlide::READ_FROM_PRIMARY,
+            request_timeout: null,
+            reconnect_strategy: null,
+            database_id: null,
+            client_name: null,
+            client_az: null,
+            advanced_config: [
+                'connection_timeout' => 5000,
+                'refresh_topology_from_initial_nodes' => true  // Should be completely ignored
+            ]
+        );
+        
+        // Perform basic operation to verify client works
+        $result = $client->ping();
+        $this->assertTrue($result);
+        
+        $client->close();
+    }
 }
diff --git a/valkey_glide_cluster.c b/valkey_glide_cluster.c
@@ -78,6 +78,18 @@ PHP_METHOD(ValkeyGlideCluster, __construct) {
     /* Populate configuration parameters shared between client and cluster connections. */
     valkey_glide_build_client_config_base(&common_params, &client_config.base, true);
 
+    /* Parse cluster-specific advanced config options */
+    client_config.refresh_topology_from_initial_nodes = false; /* Default value */
+    if (common_params.advanced_config && Z_TYPE_P(common_params.advanced_config) == IS_ARRAY) {
+        HashTable* advanced_ht = Z_ARRVAL_P(common_params.advanced_config);
+        const char key_name[]  = "refresh_topology_from_initial_nodes";
+        zval*      refresh_topology_val =
+            zend_hash_str_find(advanced_ht, key_name, sizeof(key_name) - 1);
+        if (refresh_topology_val && Z_TYPE_P(refresh_topology_val) == IS_TRUE) {
+            client_config.refresh_topology_from_initial_nodes = true;
+        }
+    }
+
     /* Issue the connection request. */
     const ConnectionResponse* conn_resp = create_glide_cluster_client(&client_config);
 
diff --git a/valkey_glide_cluster.stub.php b/valkey_glide_cluster.stub.php
@@ -153,6 +153,12 @@ class ValkeyGlideCluster
      */
     public const IAM_CONFIG_REFRESH_INTERVAL = 'refreshIntervalSeconds';
 
+    /**
+     * @var string
+     * Advanced config key for refresh topology from initial nodes option
+     */
+    public const ADVANCED_CONFIG_REFRESH_TOPOLOGY_FROM_INITIAL_NODES = 'refresh_topology_from_initial_nodes';
+
                     /**
                    *  @var int
          * Enables the periodic checks with the default configurations.
@@ -186,9 +192,11 @@ class ValkeyGlideCluster
      * @param string|null $client_name          Client name identifier.
      * @param int|null $periodic_checks         Periodic checks configuration.
      * @param string|null $client_az            Client availability zone.
-     * @param array|null $advanced_config       Advanced configuration ['connection_timeout' => 5000,
-     *                                          'tls_config' => ['use_insecure_tls' => false]].
-     *                                           connection_timeout is in milliseconds.
+     * @param array|null $advanced_config       Advanced configuration options:
+     *                                          - 'connection_timeout' => 5000 (milliseconds)
+     *                                          - 'tls_config' => ['use_insecure_tls' => false]
+     *                                          - 'refresh_topology_from_initial_nodes' => false (default: false)
+     *                                            When true, topology updates use only initial nodes instead of internal cluster view.
      * @param bool|null $lazy_connect           Whether to use lazy connection.
      * @param int|null $database_id             Index of the logical database to connect to. Must be non-negative 
      *                                          and within the range supported by the server configuration. 
diff --git a/valkey_glide_commands_common.h b/valkey_glide_commands_common.h
@@ -70,7 +70,8 @@ uint8_t* create_connection_request(const char*                               hos
                                    size_t*                                   len,
                                    valkey_glide_base_client_configuration_t* config,
                                    valkey_glide_periodic_checks_status_t     periodic_checks,
-                                   bool                                      is_cluster);
+                                   bool                                      is_cluster,
+                                   bool refresh_topology_from_initial_nodes);
 
 /* Bit operations - UNIFIED SIGNATURES */
 int execute_bitcount_command(zval* object, int argc, zval* return_value, zend_class_entry* ce);
diff --git a/valkey_glide_core_commands.c b/valkey_glide_core_commands.c
@@ -46,7 +46,8 @@ uint8_t* create_connection_request(const char*                               hos
                                    size_t*                                   len,
                                    valkey_glide_base_client_configuration_t* config,
                                    valkey_glide_periodic_checks_status_t     periodic_checks,
-                                   bool                                      is_cluster) {
+                                   bool                                      is_cluster,
+                                   bool refresh_topology_from_initial_nodes) {
     /* Create a connection request */
     ConnectionRequest__ConnectionRequest conn_req = CONNECTION_REQUEST__CONNECTION_REQUEST__INIT;
 
@@ -133,6 +134,13 @@ uint8_t* create_connection_request(const char*                               hos
         conn_req.connection_timeout = config->advanced_config->connection_timeout;
     }
 
+    /* Set refresh topology from initial nodes for cluster mode */
+    if (is_cluster) {
+        conn_req.refresh_topology_from_initial_nodes = refresh_topology_from_initial_nodes;
+    } else {
+        conn_req.refresh_topology_from_initial_nodes = false;
+    }
+
     conn_req.lazy_connect = config->lazy_connect;
     /* Map read_from configuration */
     if (config->read_from == VALKEY_GLIDE_READ_FROM_PREFER_REPLICA) {
@@ -208,14 +216,20 @@ uint8_t* create_connection_request(const char*                               hos
 static const ConnectionResponse* create_base_glide_client(
     valkey_glide_base_client_configuration_t* config,
     valkey_glide_periodic_checks_status_t     periodic_checks,
-    bool                                      is_cluster) {
+    bool                                      is_cluster,
+    bool                                      refresh_topology_from_initial_nodes) {
     /* Create a connection request using first address or default */
     size_t      len;
     const char* default_host = "localhost";
     int         default_port = 6379;
 
-    uint8_t* request_bytes = create_connection_request(
-        default_host, default_port, &len, config, periodic_checks, is_cluster);
+    uint8_t* request_bytes = create_connection_request(default_host,
+                                                       default_port,
+                                                       &len,
+                                                       config,
+                                                       periodic_checks,
+                                                       is_cluster,
+                                                       refresh_topology_from_initial_nodes);
 
     if (!request_bytes) {
         return NULL;
@@ -243,12 +257,15 @@ static const ConnectionResponse* create_base_glide_client(
 
 /* Create a Valkey Glide client */
 const ConnectionResponse* create_glide_client(valkey_glide_base_client_configuration_t* config) {
-    return create_base_glide_client(config, VALKEY_GLIDE_PERIODIC_CHECKS_DISABLED, false);
+    return create_base_glide_client(config, VALKEY_GLIDE_PERIODIC_CHECKS_DISABLED, false, false);
 }
 
 const ConnectionResponse* create_glide_cluster_client(
     valkey_glide_cluster_client_configuration_t* config) {
-    return create_base_glide_client(&config->base, config->periodic_checks_status, true);
+    return create_base_glide_client(&config->base,
+                                    config->periodic_checks_status,
+                                    true,
+                                    config->refresh_topology_from_initial_nodes);
 }
 
 /* Custom result processor for SET commands with GET option support */
