[server] Support generating rack aware bucket assignment when creating table (#786)

Author: swuferhong

fluss-client/src/main/java/com/alibaba/fluss/client/utils/MetadataUtils.java

@@ -297,7 +297,8 @@ private static Map<Integer, ServerNode> getAliveTabletServers(MetadataResponse r
                                             nodeId,
                                             serverNode.getHost(),
                                             serverNode.getPort(),
-                                            ServerType.TABLET_SERVER));
+                                            ServerType.TABLET_SERVER,
+                                            serverNode.getRack()));
                         });
         return aliveTabletServers;
     }

fluss-client/src/test/java/com/alibaba/fluss/client/metadata/TestingMetadataUpdater.java

@@ -44,11 +44,11 @@ public class TestingMetadataUpdater extends MetadataUpdater {
     private static final ServerNode COORDINATOR =
             new ServerNode(0, "localhost", 90, ServerType.COORDINATOR);
     private static final ServerNode NODE1 =
-            new ServerNode(1, "localhost", 90, ServerType.TABLET_SERVER);
+            new ServerNode(1, "localhost", 90, ServerType.TABLET_SERVER, "rack1");
     private static final ServerNode NODE2 =
-            new ServerNode(2, "localhost", 91, ServerType.TABLET_SERVER);
+            new ServerNode(2, "localhost", 91, ServerType.TABLET_SERVER, "rack2");
     private static final ServerNode NODE3 =
-            new ServerNode(3, "localhost", 92, ServerType.TABLET_SERVER);
+            new ServerNode(3, "localhost", 92, ServerType.TABLET_SERVER, "rack3");
 
     private final TestCoordinatorGateway coordinatorGateway;
     private final Map<Integer, TestTabletServerGateway> tabletServerGatewayMap;

fluss-client/src/test/java/com/alibaba/fluss/client/write/RecordAccumulatorTest.java

@@ -95,9 +95,9 @@ class RecordAccumulatorTest {
                     System.currentTimeMillis(),
                     System.currentTimeMillis());
 
-    ServerNode node1 = new ServerNode(1, "localhost", 90, ServerType.TABLET_SERVER);
-    ServerNode node2 = new ServerNode(2, "localhost", 91, ServerType.TABLET_SERVER);
-    ServerNode node3 = new ServerNode(3, "localhost", 92, ServerType.TABLET_SERVER);
+    ServerNode node1 = new ServerNode(1, "localhost", 90, ServerType.TABLET_SERVER, "rack1");
+    ServerNode node2 = new ServerNode(2, "localhost", 91, ServerType.TABLET_SERVER, "rack2");
+    ServerNode node3 = new ServerNode(3, "localhost", 92, ServerType.TABLET_SERVER, "rack3");
     private final ServerNode[] serverNodes = new ServerNode[] {node1, node2, node3};
     private final TableBucket tb1 = new TableBucket(DATA1_TABLE_ID, 0);
     private final TableBucket tb2 = new TableBucket(DATA1_TABLE_ID, 1);

fluss-client/src/test/java/com/alibaba/fluss/client/write/StickyStaticBucketAssignerTest.java

@@ -46,9 +46,9 @@
 
 /** Test for {@link StickyBucketAssigner}. */
 class StickyStaticBucketAssignerTest {
-    ServerNode node1 = new ServerNode(1, "localhost", 90, ServerType.TABLET_SERVER);
-    ServerNode node2 = new ServerNode(2, "localhost", 91, ServerType.TABLET_SERVER);
-    ServerNode node3 = new ServerNode(3, "localhost", 92, ServerType.TABLET_SERVER);
+    ServerNode node1 = new ServerNode(1, "localhost", 90, ServerType.TABLET_SERVER, "rack1");
+    ServerNode node2 = new ServerNode(2, "localhost", 91, ServerType.TABLET_SERVER, "rack2");
+    ServerNode node3 = new ServerNode(3, "localhost", 92, ServerType.TABLET_SERVER, "rack3");
     private final ServerNode[] serverNodes = new ServerNode[] {node1, node2, node3};
     private final BucketLocation bucket1 =
             new BucketLocation(DATA1_PHYSICAL_TABLE_PATH, DATA1_TABLE_ID, 0, node1, serverNodes);

fluss-common/src/main/java/com/alibaba/fluss/cluster/MetadataCache.java

@@ -64,17 +64,17 @@ public interface MetadataCache {
      */
     Map<Integer, ServerNode> getAllAliveTabletServers(String listenerName);
 
-    Set<Integer> getAliveTabletServerIds();
+    Set<TabletServerInfo> getAliveTabletServerInfos();
 
     @Nullable
     PhysicalTablePath getTablePath(long tableId);
 
     /** Get ids of all alive tablet server nodes. */
-    default int[] getLiveServerIds() {
-        Set<Integer> aliveTabletServerIds = getAliveTabletServerIds();
-        int[] server = new int[aliveTabletServerIds.size()];
-        Iterator<Integer> iterator = aliveTabletServerIds.iterator();
-        for (int i = 0; i < aliveTabletServerIds.size(); i++) {
+    default TabletServerInfo[] getLiveServers() {
+        Set<TabletServerInfo> aliveTabletServerInfos = getAliveTabletServerInfos();
+        TabletServerInfo[] server = new TabletServerInfo[aliveTabletServerInfos.size()];
+        Iterator<TabletServerInfo> iterator = aliveTabletServerInfos.iterator();
+        for (int i = 0; i < aliveTabletServerInfos.size(); i++) {
             server[i] = iterator.next();
         }
         return server;

fluss-common/src/main/java/com/alibaba/fluss/cluster/ServerNode.java

@@ -18,6 +18,8 @@
 
 import com.alibaba.fluss.annotation.PublicEvolving;
 
+import javax.annotation.Nullable;
+
 import java.util.Objects;
 
 /**
@@ -33,15 +35,23 @@ public class ServerNode {
     private final int port;
     private final ServerType serverType;
 
+    /** rack info for ServerNode. Currently, only tabletServer has rack info. */
+    private final @Nullable String rack;
+
     // Cache hashCode as it is called in performance sensitive parts of the code (e.g.
     // RecordAccumulator.ready)
     private Integer hash;
 
     public ServerNode(int id, String host, int port, ServerType serverType) {
+        this(id, host, port, serverType, null);
+    }
+
+    public ServerNode(int id, String host, int port, ServerType serverType, @Nullable String rack) {
         this.id = id;
         this.host = host;
         this.port = port;
         this.serverType = serverType;
+        this.rack = rack;
         if (serverType == ServerType.COORDINATOR) {
             this.uid = "cs-" + id;
         } else {
@@ -80,6 +90,11 @@ public ServerType serverType() {
         return serverType;
     }
 
+    /** The rack for this node. */
+    public @Nullable String rack() {
+        return rack;
+    }
+
     /**
      * Check whether this node is empty, which may be the case if noNode() is used as a placeholder
      * in a response payload with an error.
@@ -98,6 +113,7 @@ public int hashCode() {
             result = 31 * result + id;
             result = 31 * result + port;
             result = 31 * result + serverType.hashCode();
+            result = 31 * result + ((rack == null) ? 0 : rack.hashCode());
             this.hash = result;
             return result;
         } else {
@@ -117,11 +133,12 @@ public boolean equals(Object obj) {
         return id == other.id
                 && port == other.port
                 && Objects.equals(host, other.host)
-                && serverType == other.serverType;
+                && serverType == other.serverType
+                && Objects.equals(rack, other.rack);
     }
 
     @Override
     public String toString() {
-        return host + ":" + port + " (id: " + uid + ")";
+        return host + ":" + port + " (id: " + uid + ", rack: " + rack + ")";
     }
 }

fluss-common/src/main/java/com/alibaba/fluss/cluster/TabletServerInfo.java

@@ -0,0 +1,58 @@
+/*
+ * Copyright (c) 2025 Alibaba Group Holding Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.alibaba.fluss.cluster;
+
+import javax.annotation.Nullable;
+
+import java.util.Objects;
+
+/** Tablet server info. */
+public class TabletServerInfo {
+    private final int id;
+
+    private @Nullable final String rack;
+
+    public TabletServerInfo(int id, @Nullable String rack) {
+        this.id = id;
+        this.rack = rack;
+    }
+
+    public int getId() {
+        return id;
+    }
+
+    public @Nullable String getRack() {
+        return rack;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (o == null || getClass() != o.getClass()) {
+            return false;
+        }
+        TabletServerInfo that = (TabletServerInfo) o;
+        return id == that.id && Objects.equals(rack, that.rack);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(id, rack);
+    }
+}

fluss-common/src/main/java/com/alibaba/fluss/config/ConfigOptions.java

@@ -343,6 +343,14 @@ public class ConfigOptions {
                     .noDefaultValue()
                     .withDescription("The id for the tablet server.");
 
+    public static final ConfigOption<String> TABLET_SERVER_RACK =
+            key("tablet-server.rack")
+                    .stringType()
+                    .noDefaultValue()
+                    .withDescription(
+                            "The rack for the tabletServer. This will be used in rack aware bucket assignment "
+                                    + "for fault tolerance. Examples: `RACK1`, `cn-hangzhou-server10`");
+
     public static final ConfigOption<String> DATA_DIR =
             key("data.dir")
                     .stringType()

fluss-common/src/main/java/com/alibaba/fluss/exception/InvalidServerRackInfoException.java

@@ -0,0 +1,27 @@
+/*
+ * Copyright (c) 2025 Alibaba Group Holding Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.alibaba.fluss.exception;
+
+/**
+ * Exception for invalid server rack info. For example, not all tabletServer have assigned rack
+ * info.
+ */
+public class InvalidServerRackInfoException extends ApiException {
+    public InvalidServerRackInfoException(String message) {
+        super(message);
+    }
+}

fluss-common/src/test/java/com/alibaba/fluss/cluster/BucketLocationTest.java

@@ -31,9 +31,11 @@ void testToString() {
         TablePath tablePath = new TablePath("test_db", "test_table");
         int bucketId = 0;
         long tableId = 150001L;
-        ServerNode leader = new ServerNode(0, "localhost", 9092, ServerType.TABLET_SERVER);
-        ServerNode replica1 = new ServerNode(1, "localhost", 9093, ServerType.TABLET_SERVER);
-        ServerNode replica2 = new ServerNode(2, "localhost", 9094, ServerType.TABLET_SERVER);
+        ServerNode leader = new ServerNode(0, "localhost", 9092, ServerType.TABLET_SERVER, "rack0");
+        ServerNode replica1 =
+                new ServerNode(1, "localhost", 9093, ServerType.TABLET_SERVER, "rack1");
+        ServerNode replica2 =
+                new ServerNode(2, "localhost", 9094, ServerType.TABLET_SERVER, "rack2");
         ServerNode[] replicas = {leader, replica1, replica2};
         // TODO add isr and offline.
         BucketLocation bucketLocation =