improve stoppable check APIs to include failure details

.gitignore

@@ -2,6 +2,7 @@ cscope.*
 .classpath
 .project
 .svn
+.java-version
 target/
 /recipes/rabbitmq-consumer-group/target/
 .idea

helix-core/src/main/java/org/apache/helix/util/InstanceValidationUtil.java

@@ -396,7 +396,7 @@ public static boolean isInstanceStable(HelixDataAccessor dataAccessor, String in
    */
   public static boolean siblingNodesActiveReplicaCheck(HelixDataAccessor dataAccessor,
       String instanceName) {
-    return siblingNodesActiveReplicaCheck(dataAccessor, instanceName, Collections.emptySet());
+    return siblingNodesActiveReplicaCheckWithDetails(dataAccessor, instanceName, Collections.emptySet()).isPassed();
   }
 
   /**
@@ -416,6 +416,29 @@ public static boolean siblingNodesActiveReplicaCheck(HelixDataAccessor dataAcces
    */
   public static boolean siblingNodesActiveReplicaCheck(HelixDataAccessor dataAccessor,
       String instanceName, Set<String> toBeStoppedInstances) {
+    return siblingNodesActiveReplicaCheckWithDetails(dataAccessor, instanceName, toBeStoppedInstances).isPassed();
+  }
+
+  /**
+   * Check if sibling nodes of the instance meet min active replicas constraint with details
+   * Two instances are sibling of each other if they host the same partition. And sibling nodes
+   * that are in toBeStoppableInstances will be presumed to be stopped.
+   * WARNING: The check uses ExternalView to reduce network traffic but suffer from accuracy
+   * due to external view propagation latency
+   *
+   * This method returns detailed information about the first partition that fails the check,
+   * including resource name, partition name, current active replicas, and required minimum.
+   *
+   * TODO: Use in memory cache and query instance's currentStates
+   *
+   * @param dataAccessor A helper class to access the Helix data.
+   * @param instanceName An instance to be evaluated against this check.
+   * @param toBeStoppedInstances A set of instances presumed to be are already stopped. And it
+   *                             shouldn't contain the `instanceName`
+   * @return MinActiveReplicaCheckResult with pass/fail status and details of first failure
+   */
+  public static MinActiveReplicaCheckResult siblingNodesActiveReplicaCheckWithDetails(
+      HelixDataAccessor dataAccessor, String instanceName, Set<String> toBeStoppedInstances) {
     PropertyKey.Builder propertyKeyBuilder = dataAccessor.keyBuilder();
     List<String> resources = dataAccessor.getChildNames(propertyKeyBuilder.idealStates());
 
@@ -464,15 +487,15 @@ public static boolean siblingNodesActiveReplicaCheck(HelixDataAccessor dataAcces
             }
           }
           if (numHealthySiblings < minActiveReplicas) {
-            _logger.info(
-                "Partition {} doesn't have enough active replicas in sibling nodes. NumHealthySiblings: {}, minActiveReplicas: {}",
-                partition, numHealthySiblings, minActiveReplicas);
-            return false;
+            _logger.warn(
+                "Instance {} min active replica check failed: Resource {} partition {} has {}/{} active replicas",
+                instanceName, resourceName, partition, numHealthySiblings, minActiveReplicas);
+            return MinActiveReplicaCheckResult.failed(resourceName, partition, numHealthySiblings, minActiveReplicas);
           }
         }
       }
     }
 
-    return true;
+    return MinActiveReplicaCheckResult.passed();
   }
 }

helix-core/src/main/java/org/apache/helix/util/MinActiveReplicaCheckResult.java

@@ -0,0 +1,81 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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 org.apache.helix.util;
+
+/**
+ * Result container for minimum active replica validation checks.
+ * Provides details about validation outcome and specific failure information.
+ */
+public class MinActiveReplicaCheckResult {
+  private final boolean passed;
+  private final String resourceName;
+  private final String partitionName;
+  private final int currentActiveReplicas;
+  private final int requiredMinActiveReplicas;
+
+  private MinActiveReplicaCheckResult(boolean passed, String resourceName, String partitionName,
+      int currentActiveReplicas, int requiredMinActiveReplicas) {
+    this.passed = passed;
+    this.resourceName = resourceName;
+    this.partitionName = partitionName;
+    this.currentActiveReplicas = currentActiveReplicas;
+    this.requiredMinActiveReplicas = requiredMinActiveReplicas;
+  }
+
+  public static MinActiveReplicaCheckResult passed() {
+    return new MinActiveReplicaCheckResult(true, null, null, -1, -1);
+  }
+
+  public static MinActiveReplicaCheckResult failed(String resourceName, String partitionName,
+      int currentActiveReplicas, int requiredMinActiveReplicas) {
+    return new MinActiveReplicaCheckResult(false, resourceName, partitionName,
+        currentActiveReplicas, requiredMinActiveReplicas);
+  }
+
+  public boolean isPassed() {
+    return passed;
+  }
+
+  public String getResourceName() {
+    return resourceName;
+  }
+
+  public String getPartitionName() {
+    return partitionName;
+  }
+
+  public int getCurrentActiveReplicas() {
+    return currentActiveReplicas;
+  }
+
+  public int getRequiredMinActiveReplicas() {
+    return requiredMinActiveReplicas;
+  }
+
+  @Override
+  public String toString() {
+    if (passed) {
+      return "MIN_ACTIVE_REPLICA_CHECK_FAILED: passed";
+    } else {
+      return String.format("MIN_ACTIVE_REPLICA_CHECK_FAILED: Resource %s partition %s has %d/%d active replicas",
+          resourceName, partitionName, currentActiveReplicas, requiredMinActiveReplicas);
+    }
+  }
+}

helix-core/src/test/java/org/apache/helix/util/TestInstanceValidationUtil.java

@@ -28,7 +28,6 @@
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ImmutableMap;
 import com.google.common.collect.ImmutableSet;
-import org.apache.helix.ConfigAccessor;
 import org.apache.helix.HelixDataAccessor;
 import org.apache.helix.HelixException;
 import org.apache.helix.PropertyKey;
@@ -589,13 +588,116 @@ public void TestSiblingNodesActiveReplicaCheckSuccessWithReplicaInErrorState() {
     Assert.assertFalse(result);
   }
 
+  @Test
+  public void testSiblingNodesActiveReplicaCheckWithDetails() throws Exception {
+    Mock mock = new Mock();
+
+    ClusterConfig clusterConfig = mock(ClusterConfig.class);
+
+    InstanceConfig instanceConfig = new InstanceConfig(TEST_INSTANCE);
+    instanceConfig.setDomain("zone=1");
+
+    // set ideal state
+    IdealState idealState = mock(IdealState.class);
+    when(idealState.isEnabled()).thenReturn(true);
+    when(idealState.isValid()).thenReturn(true);
+    when(idealState.getStateModelDefRef()).thenReturn("MasterSlave");
+
+    // set external view
+    ExternalView externalView = mock(ExternalView.class);
+    when(externalView.getMinActiveReplicas()).thenReturn(2);
+    when(externalView.getStateModelDefRef()).thenReturn("MasterSlave");
+    when(externalView.getPartitionSet()).thenReturn(ImmutableSet.of("testResource_0"));
+
+    StateModelDefinition stateModelDefinition = mock(StateModelDefinition.class);
+    when(stateModelDefinition.getInitialState()).thenReturn("OFFLINE");
+
+    doReturn(ImmutableList.of("testResource")).when(mock.dataAccessor)
+        .getChildNames(argThat(new PropertyKeyArgument(PropertyType.IDEALSTATES)));
+    doReturn(idealState).when(mock.dataAccessor).getProperty(argThat(new PropertyKeyArgument(PropertyType.IDEALSTATES)));
+    doReturn(externalView).when(mock.dataAccessor).getProperty(argThat(new PropertyKeyArgument(PropertyType.EXTERNALVIEW)));
+    doReturn(stateModelDefinition).when(mock.dataAccessor)
+        .getProperty(argThat(new PropertyKeyArgument(PropertyType.STATEMODELDEFS)));
+    when(mock.dataAccessor.getProperty(BUILDER.instanceConfig(TEST_INSTANCE))).thenReturn(instanceConfig);
+    when(mock.dataAccessor.getProperty(BUILDER.clusterConfig())).thenReturn(clusterConfig);
+
+    // Test with sufficient active replicas - should pass
+    when(externalView.getStateMap("testResource_0")).thenReturn(
+        ImmutableMap.of(TEST_INSTANCE, "Master", "instance1", "Slave", "instance2", "Slave"));
+
+    MinActiveReplicaCheckResult result = 
+        InstanceValidationUtil.siblingNodesActiveReplicaCheckWithDetails(mock.dataAccessor, TEST_INSTANCE, Collections.emptySet());
+
+    Assert.assertTrue(result.isPassed());
+    Assert.assertNull(result.getPartitionName());
+
+    // Test with insufficient active replicas after instance removal - should fail
+    System.out.println("Setting up second scenario...");
+    when(externalView.getStateMap("testResource_0")).thenReturn(
+        ImmutableMap.of(TEST_INSTANCE, "Master", "instance1", "ERROR", "instance2", "ERROR"));
+
+    result = InstanceValidationUtil.siblingNodesActiveReplicaCheckWithDetails(mock.dataAccessor, TEST_INSTANCE, Collections.emptySet());
+
+    Assert.assertFalse(result.isPassed());
+    Assert.assertNotNull(result.getPartitionName());
+    Assert.assertEquals("testResource_0", result.getPartitionName());
+    Assert.assertEquals("testResource", result.getResourceName());
+    Assert.assertEquals(0, result.getCurrentActiveReplicas());
+    Assert.assertEquals(2, result.getRequiredMinActiveReplicas());
+  }
+
+  @Test
+  public void testSiblingNodesActiveReplicaCheckWithDetailsFailFast() throws Exception {
+    Mock mock = new Mock();
+
+    ClusterConfig clusterConfig = mock(ClusterConfig.class);
+
+    InstanceConfig instanceConfig = new InstanceConfig(TEST_INSTANCE);
+    instanceConfig.setDomain("zone=1");
+
+    // set ideal state
+    IdealState idealState = mock(IdealState.class);
+    when(idealState.isEnabled()).thenReturn(true);
+    when(idealState.isValid()).thenReturn(true);
+    when(idealState.getStateModelDefRef()).thenReturn("MasterSlave");
+
+    // set external view - this one will fail the check
+    ExternalView externalView = mock(ExternalView.class);
+    when(externalView.getMinActiveReplicas()).thenReturn(2);
+    when(externalView.getStateModelDefRef()).thenReturn("MasterSlave");
+    when(externalView.getPartitionSet()).thenReturn(ImmutableSet.of("resource1_0"));
+    when(externalView.getStateMap("resource1_0")).thenReturn(
+        ImmutableMap.of(TEST_INSTANCE, "Master", "instance1", "ERROR")); // Failure scenario - only 0 healthy siblings after removal
+
+    StateModelDefinition stateModelDefinition = mock(StateModelDefinition.class);
+    when(stateModelDefinition.getInitialState()).thenReturn("OFFLINE");
+
+    doReturn(ImmutableList.of("resource1")).when(mock.dataAccessor)
+        .getChildNames(argThat(new PropertyKeyArgument(PropertyType.IDEALSTATES)));
+    doReturn(idealState).when(mock.dataAccessor).getProperty(argThat(new PropertyKeyArgument(PropertyType.IDEALSTATES)));
+    doReturn(externalView).when(mock.dataAccessor).getProperty(argThat(new PropertyKeyArgument(PropertyType.EXTERNALVIEW)));
+    doReturn(stateModelDefinition).when(mock.dataAccessor)
+        .getProperty(argThat(new PropertyKeyArgument(PropertyType.STATEMODELDEFS)));
+
+    when(mock.dataAccessor.getProperty(BUILDER.instanceConfig(TEST_INSTANCE))).thenReturn(instanceConfig);
+    when(mock.dataAccessor.getProperty(BUILDER.clusterConfig())).thenReturn(clusterConfig);
+
+    MinActiveReplicaCheckResult result = 
+        InstanceValidationUtil.siblingNodesActiveReplicaCheckWithDetails(mock.dataAccessor, TEST_INSTANCE, Collections.emptySet());
+
+    // Should fail on the resource
+    Assert.assertFalse(result.isPassed());
+    Assert.assertEquals("resource1_0", result.getPartitionName());
+    Assert.assertEquals("resource1", result.getResourceName());
+    Assert.assertEquals(0, result.getCurrentActiveReplicas());
+    Assert.assertEquals(2, result.getRequiredMinActiveReplicas());
+  }
+
   private class Mock {
     HelixDataAccessor dataAccessor;
-    ConfigAccessor configAccessor;
 
     Mock() {
       this.dataAccessor = mock(HelixDataAccessor.class);
-      this.configAccessor = mock(ConfigAccessor.class);
       when(dataAccessor.keyBuilder()).thenReturn(BUILDER);
     }
   }