[JENKINS-70059] Improve Safe Restart interface and user information

core/src/main/java/hudson/util/HudsonIsRestarting.java

@@ -41,8 +41,29 @@
  * @author Kohsuke Kawaguchi
  */
 public class HudsonIsRestarting {
+    private boolean safeRestart;
+
+    /**
+     * @since TODO
+     */
+    public HudsonIsRestarting(boolean safeRestart) {
+        this.safeRestart = safeRestart;
+    }
+
+    @Deprecated
+    public HudsonIsRestarting() {
+        this.safeRestart = false;
+    }
+
     public void doDynamic(StaplerRequest req, StaplerResponse rsp) throws IOException, ServletException, InterruptedException {
         rsp.setStatus(SC_SERVICE_UNAVAILABLE);
         req.getView(this, "index.jelly").forward(req, rsp);
     }
+
+    /**
+     * @since TODO
+     */
+    public boolean isSafeRestart() {
+        return safeRestart;
+    }
 }

core/src/main/java/jenkins/cli/SafeRestartCommand.java

@@ -0,0 +1,59 @@
+/*
+ * The MIT License
+ *
+ * Copyright (c) 2023, Jan Meiswinkel
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+package jenkins.cli;
+
+import hudson.Extension;
+import hudson.cli.CLICommand;
+import hudson.cli.Messages;
+import java.util.logging.Logger;
+import jenkins.model.Jenkins;
+import org.kohsuke.accmod.Restricted;
+import org.kohsuke.accmod.restrictions.NoExternalUse;
+import org.kohsuke.args4j.Option;
+
+/**
+ * Safe Restart Jenkins - do not accept any new jobs and try to pause existing.
+ *
+ * @since TODO
+ */
+@Extension
+@Restricted(NoExternalUse.class)
+public class SafeRestartCommand extends CLICommand {
+    private static final Logger LOGGER = Logger.getLogger(SafeRestartCommand.class.getName());
+
+    @Option(name = "-message", usage = "Message for safe restart that will be visible to users")
+    public String message = null;
+
+    @Override
+    public String getShortDescription() {
+        return Messages.SafeRestartCommand_ShortDescription();
+    }
+
+    @Override
+    protected int run() throws Exception {
+        Jenkins.get().doSafeRestart(null, message);
+        return 0;
+    }
+}

core/src/main/java/jenkins/model/Jenkins.java

@@ -482,6 +482,7 @@ public class Jenkins extends AbstractCIBase implements DirectlyModifiableTopLeve
 
     @CheckForNull
     private transient volatile QuietDownInfo quietDownInfo;
+
     private transient volatile boolean terminating;
     @GuardedBy("Jenkins.class")
     private transient boolean cleanUpStarted;
@@ -2943,6 +2944,20 @@ public boolean isQuietingDown() {
         return quietDownInfo != null;
     }
 
+    /**
+     * Returns if the quietingDown is a safe restart.
+     * @since TODO
+     */
+    @Restricted(NoExternalUse.class)
+    @NonNull
+    public boolean isPreparingSafeRestart() {
+        QuietDownInfo quietDownInfo = this.quietDownInfo;
+        if (quietDownInfo != null) {
+            return quietDownInfo.isSafeRestart();
+        }
+        return false;
+    }
+
     /**
      * Returns quiet down reason if it was indicated.
      * @return
@@ -2953,7 +2968,7 @@ public boolean isQuietingDown() {
     @CheckForNull
     public String getQuietDownReason() {
         final QuietDownInfo info = quietDownInfo;
-        return info != null ? info.reason : null;
+        return info != null ? info.message : null;
     }
 
     /**
@@ -4093,7 +4108,7 @@ public synchronized HttpRedirect doQuietDown() {
      *
      * @param block Block until the system really quiets down and no builds are running
      * @param timeout If non-zero, only block up to the specified number of milliseconds
-     * @deprecated since 2.267; use {@link #doQuietDown(boolean, int, String)} instead.
+     * @deprecated since 2.267; use {@link #doQuietDown(boolean, int, String, boolean)} instead.
      */
     @Deprecated
     public synchronized HttpRedirect doQuietDown(boolean block, int timeout) {
@@ -4109,16 +4124,34 @@ public synchronized HttpRedirect doQuietDown(boolean block, int timeout) {
      *
      * @param block Block until the system really quiets down and no builds are running
      * @param timeout If non-zero, only block up to the specified number of milliseconds
-     * @param reason Quiet reason that will be visible to user
-     * @since 2.267
+     * @param message Quiet reason that will be visible to user
+     * @deprecated use {@link #doQuietDown(boolean, int, String, boolean)} instead.
+     */
+    @Deprecated(since = "TODO")
+    public HttpRedirect doQuietDown(boolean block,
+                                    int timeout,
+                                    @CheckForNull String message) throws InterruptedException, IOException {
+
+        return doQuietDown(block, timeout, message, false);
+    }
+
+    /**
+     * Quiet down Jenkins - preparation for a restart
+     *
+     * @param block Block until the system really quiets down and no builds are running
+     * @param timeout If non-zero, only block up to the specified number of milliseconds
+     * @param message Quiet reason that will be visible to user
+     * @param safeRestart If the quietDown is for a safeRestart
+     * @since TODO
      */
     @RequirePOST
     public HttpRedirect doQuietDown(@QueryParameter boolean block,
                                     @QueryParameter int timeout,
-                                    @QueryParameter @CheckForNull String reason) throws InterruptedException, IOException {
+                                    @QueryParameter @CheckForNull String message,
+                                    @QueryParameter boolean safeRestart) throws InterruptedException, IOException {
         synchronized (this) {
             checkPermission(MANAGE);
-            quietDownInfo = new QuietDownInfo(reason);
+            quietDownInfo = new QuietDownInfo(message, safeRestart);
         }
         if (block) {
             long waitUntil = timeout;
@@ -4513,20 +4546,35 @@ public void doRestart(StaplerRequest req, StaplerResponse rsp) throws IOExceptio
     }
 
     /**
-     * Queues up a restart of Jenkins for when there are no builds running, if we can.
+     * Queues up a safe restart of Jenkins.
+     * Builds that cannot continue while the controller is not running have to finish or pause before it can proceed.
+     * No new builds will be started. No new jobs are accepted.
      *
-     * This first replaces "app" to {@link HudsonIsRestarting}
+     * @deprecated use {@link #doSafeRestart(StaplerRequest, String)} instead.
      *
-     * @since 1.332
      */
-    @CLIMethod(name = "safe-restart")
+    @Deprecated(since = "TODO")
     public HttpResponse doSafeRestart(StaplerRequest req) throws IOException, ServletException, RestartNotSupportedException {
+        return doSafeRestart(req, null);
+    }
+
+    /**
+     * Queues up a safe restart of Jenkins. Jobs have to finish or pause before it can proceed. No new jobs are accepted.
+     *
+     * @since TODO
+     */
+    public HttpResponse doSafeRestart(StaplerRequest req, @QueryParameter("message") String message) throws IOException, ServletException, RestartNotSupportedException {
         checkPermission(MANAGE);
-        if (req != null && req.getMethod().equals("GET"))
+        if (req != null && req.getMethod().equals("GET")) {
             return HttpResponses.forwardToView(this, "_safeRestart.jelly");
+        }
+
+        if (req != null && req.getParameter("cancel") != null) {
+            return doCancelQuietDown();
+        }
 
         if (req == null || req.getMethod().equals("POST")) {
-            safeRestart();
+            safeRestart(message);
         }
 
         return HttpResponses.redirectToDot();
@@ -4572,11 +4620,22 @@ public void run() {
     /**
      * Queues up a restart to be performed once there are no builds currently running.
      * @since 1.332
+     * @deprecated use {@link #safeRestart(String)} instead.
      */
+    @Deprecated(since = "TODO")
     public void safeRestart() throws RestartNotSupportedException {
+        safeRestart(null);
+    }
+
+    /**
+     * Queues up a restart to be performed once there are no builds currently running.
+     * @param message the message to show to users in the shutdown banner.
+     * @since TODO
+     */
+    public void safeRestart(String message) throws RestartNotSupportedException {
         final Lifecycle lifecycle = restartableLifecycle();
         // Quiet down so that we won't launch new builds.
-        quietDownInfo = new QuietDownInfo();
+        quietDownInfo = new QuietDownInfo(message, true);
 
         new Thread("safe-restart thread") {
             final String exitUser = getAuthentication2().getName();
@@ -4585,11 +4644,10 @@ public void run() {
                 try (ACLContext ctx = ACL.as2(ACL.SYSTEM2)) {
 
                     // Wait 'til we have no active executors.
-                    doQuietDown(true, 0, null);
-
+                    doQuietDown(true, 0, message, true);
                     // Make sure isQuietingDown is still true.
                     if (isQuietingDown()) {
-                        servletContext.setAttribute("app", new HudsonIsRestarting());
+                        servletContext.setAttribute("app", new HudsonIsRestarting(true));
                         // give some time for the browser to load the "reloading" page
                         lifecycle.onStatusUpdate("Restart in 10 seconds");
                         Thread.sleep(TimeUnit.SECONDS.toMillis(10));
@@ -5761,16 +5819,31 @@ private static void _setJenkinsJVM(boolean jenkinsJVM) {
     }
 
     private static final class QuietDownInfo {
-
         @CheckForNull
-        final String reason;
+        final String message;
+
+        private boolean safeRestart;
 
         QuietDownInfo() {
-            this(null);
+            this(null, false);
+        }
+
+        QuietDownInfo(final String message) {
+            this(message, false);
+        }
+
+        QuietDownInfo(final String message, final boolean safeRestart) {
+                this.message = message;
+                this.safeRestart = safeRestart;
+        }
+
+
+        boolean isSafeRestart() {
+            return safeRestart;
         }
 
-        QuietDownInfo(final String reason) {
-            this.reason = reason;
+        void setSafeRestart(boolean safeRestart) {
+            this.safeRestart = safeRestart;
         }
     }
 }

core/src/main/resources/hudson/cli/Messages.properties

@@ -84,6 +84,7 @@ ReloadConfigurationCommand.ShortDescription=Discard all the loaded data in memor
 ConnectNodeCommand.ShortDescription=Reconnect to a node(s)
 DisconnectNodeCommand.ShortDescription=Disconnects from a node.
 QuietDownCommand.ShortDescription=Quiet down Jenkins, in preparation for a restart. Don’t start any builds.
+SafeRestartCommand.ShortDescription=Safe Restart Jenkins. Don't start any builds and try to  existing.
 CancelQuietDownCommand.ShortDescription=Cancel the effect of the "quiet-down" command.
 OfflineNodeCommand.ShortDescription=Stop using a node for performing builds temporarily, until the next "online-node" command.
 WaitNodeOnlineCommand.ShortDescription=Wait for a node to become online.

core/src/main/resources/hudson/cli/Messages_de.properties

@@ -39,6 +39,7 @@ ListPluginsCommand.ShortDescription=Gibt eine Liste installierter Plugins aus.
 OfflineNodeCommand.ShortDescription=Knoten wird bis zum nächsten "online-node"-Kommando für keine neuen Builds verwendet.
 OnlineNodeCommand.ShortDescription=Knoten wird wieder für neue Builds verwendet. Hebt ein vorausgegangenes "offline-node"-Kommando auf.
 QuietDownCommand.ShortDescription=Keine neuen Builds mehr starten, z.B. zur Vorbereitung eines Neustarts.
+SafeRestartCommand.ShortDescription=Sicheren Neustart einleiten. Keine neuen Builds mehr starten und versuchen, laufende zu pausieren.
 ReloadConfigurationCommand.ShortDescription=Alle Daten im Speicher verwerfen und Konfiguration neu von Festplatte laden. Dies ist nützlich, wenn Sie Änderungen direkt im Dateisystem vorgenommen haben.
 ReloadJobCommand.ShortDescription=Lädt ein Element neu.
 RemoveJobFromViewCommand.ShortDescription=Entfernt Elemente aus einer Ansicht

core/src/main/resources/hudson/util/HudsonIsRestarting/index.jelly

@@ -56,6 +56,17 @@ THE SOFTWARE.
                         <p class="restarting">
                             ${%Your browser will reload automatically when Jenkins is ready.}
                         </p>
+                        <j:if test="${it.safeRestart}">
+                            <div class="safe-restarting">
+                                <p>
+                                    <strong>${%Safe Restart}</strong>
+                                </p>
+                                <p>
+                                    ${%Builds on agents can usually continue.}
+                                </p>
+                            </div>
+                        </j:if>
+
                     </div>
                 </div>
             </div>

core/src/main/resources/hudson/util/HudsonIsRestarting/index_de.properties

@@ -1,2 +1,6 @@
-Please\ wait\ while\ Jenkins\ is\ restarting=Jenkins wird neu gestartet. Bitte warten
+Please\ wait\ while\ Jenkins\ is\ restarting=Jenkins wird neu gestartet. Bitte warten.
 Your\ browser\ will\ reload\ automatically\ when\ Jenkins\ is\ ready.=Der Webbrowser wird diese Seite automatisch neu laden, sobald Jenkins hochgefahren ist.
+Safe\ Restart=Sicherer Neustart
+Builds\ on\ agents\ can\ usually\ continue.=Builds auf Agenten laufen in der Regel weiter.
+Restart=Neustarten
+Cancel=Abbrechen

core/src/main/resources/jenkins/model/Jenkins/_safeRestart.jelly

@@ -25,19 +25,30 @@ THE SOFTWARE.
 <!-- Delete view -->
 <?jelly escape-by-default='true'?>
 <j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:d="jelly:define" xmlns:l="/lib/layout" xmlns:t="/lib/hudson" xmlns:f="/lib/form" xmlns:i="jelly:fmt">
-	<l:layout title="Safely Restart Jenkins">
+	<l:layout title="${%Safe restart}">
 		<st:include page="sidepanel.jelly" />
-		<l:breadcrumb title="${%Safe Restart}" />
+		<l:breadcrumb title="${%Safe restart}" />
 		<l:main-panel>
+			<l:app-bar title="${%Safe restart}" />
 			<j:choose>
 				<j:when test="${app.lifecycle.canRestart()}">
-					<form method="post" action="safeRestart">
-						${%confirmRestart}
-						<f:submit value="${%Yes}" />
-					</form>
+          <p>${%restartWarning}</p>
+
+          <form method="post" action="safeRestart">
+            <f:entry title="${%Jenkins is restarting banner}"
+                     description="${%description}">
+              <f:textbox name="message" value="${app.quietDownReason ?: null}"/>
+            </f:entry>
+            <f:bottomButtonBar>
+              <f:submit clazz="jenkins-!-destructive-color" value="${%Restart}"/>
+              <j:if test="${app.isQuietingDown()}">
+                <f:submit name="cancel" primary="false" value="${%Cancel}"/>
+              </j:if>
+            </f:bottomButtonBar>
+          </form>
 				</j:when>
 				<j:otherwise>
-					${%Jenkins cannot restart itself as currently configured.}
+					${%cannotRestart}
 				</j:otherwise>
 			</j:choose>
 		</l:main-panel>

core/src/main/resources/jenkins/model/Jenkins/_safeRestart.properties

@@ -20,7 +20,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
-confirmRestart=\
-  Are you sure you want to restart Jenkins? \
-  Jenkins will restart once all running jobs are finished. \
+cannotRestart=Jenkins cannot restart itself as currently configured.
+description=This will be displayed on most Jenkins pages, you can use it to let users know what is happening. A default message will be added if you don't supply one.
+restartWarning=Jenkins will try to pause jobs and restart once all running jobs are either finished or paused. \
   (Pipeline builds may prevent Jenkins from restarting for a short period of time in some cases, but if so, they will be paused at the next available opportunity and then resumed after Jenkins restarts.)

core/src/main/resources/jenkins/model/Jenkins/_safeRestart_bg.properties

@@ -20,7 +20,5 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
-Jenkins\ cannot\ restart\ itself\ as\ currently\ configured.=\
+cannotRestart=\
  С текущите си настройки Jenkins не може да се рестартира.
-Yes=\
- Да