Replace pre publication FailedToCommitClusterStateExceptions (#135706)

Replaces three `FailedToCommitClusterStateExceptions` thrown prior to 
publishing the cluster state with `NotMasterExceptions` 

Relates to: ES-13061

Author: joshua-adams-1

server/src/main/java/org/elasticsearch/cluster/coordination/Coordinator.java

@@ -1568,7 +1568,8 @@ public void publish(
                             clusterStatePublicationEvent.getSummary()
                         )
                     );
-                    throw new FailedToCommitClusterStateException("publication " + currentPublication.get() + " already in progress");
+                    // If there is another publication in progress then we are not the master node
+                    throw new NotMasterException("publication " + currentPublication.get() + " already in progress");
                 }
 
                 assert assertPreviousStateConsistency(clusterStatePublicationEvent);
@@ -1586,8 +1587,9 @@ assert getLocalNode().equals(clusterState.getNodes().get(getLocalNode().getId())
                     publicationContext = publicationHandler.newPublicationContext(clusterStatePublicationEvent);
                 } catch (Exception e) {
                     logger.debug(() -> "[" + clusterStatePublicationEvent.getSummary() + "] publishing failed during context creation", e);
+                    // Calling becomeCandidate here means this node steps down from being master
                     becomeCandidate("publication context creation");
-                    throw new FailedToCommitClusterStateException("publishing failed during context creation", e);
+                    throw new NotMasterException("publishing failed during context creation", e);
                 }
 
                 try (Releasable ignored = publicationContext::decRef) {
@@ -1607,8 +1609,9 @@ assert getLocalNode().equals(clusterState.getNodes().get(getLocalNode().getId())
                                 + "]",
                             e
                         );
+                        // Calling becomeCandidate here means this node steps down from being master
                         becomeCandidate("publication creation");
-                        throw new FailedToCommitClusterStateException("publishing failed while starting", e);
+                        throw new NotMasterException("publishing failed while starting", e);
                     }
 
                     try {

server/src/main/java/org/elasticsearch/cluster/coordination/FailedToCommitClusterStateException.java

@@ -16,14 +16,19 @@
 import java.io.IOException;
 
 /**
- * Thrown when a cluster state publication fails to commit the new cluster state. If publication fails then a new master is elected but the
- * update might or might not take effect, depending on whether the newly-elected master accepted the published state that failed to
- * be committed. This exception should only be used when there is <i>ambiguity</i> whether a state update took effect or not.
- *
- * This is different from {@link NotMasterException} where we know for certain that a state update never took effect.
- *
- * This exception is retryable within {@link TransportMasterNodeAction}.
- *
+ * Exception indicating a cluster state update was published and may or may not have been committed.
+ * <p>
+ * If this exception is thrown, then the cluster state update was published, but is not guaranteed
+ * to be committed, including the next master node. This exception should only be thrown when there is
+ * <i>ambiguity</i> whether a cluster state update has been committed.
+ * <p>
+ * For exceptions thrown prior to publication,
+ * when the cluster update has <i>definitely</i> failed, use a different exception.
+ * <p>
+ * If during a cluster state update the node is no longer master, use a {@link NotMasterException}
+ * <p>
+ * This is a retryable exception inside {@link TransportMasterNodeAction}
+ * <p>
  * See {@link ClusterStatePublisher} for more details.
  */
 public class FailedToCommitClusterStateException extends ElasticsearchException {