Display appropriate GUI that accurately displays offline by design

core/src/main/java/hudson/model/Computer.java

@@ -355,6 +355,7 @@ public AnnotatedLargeText<Computer> getLogText() {
      *      null if the system was put offline without given a cause.
      */
     @Exported
+    @Override
     public OfflineCause getOfflineCause() {
         var node = getNode();
         if (node != null) {
@@ -374,19 +375,7 @@ public boolean hasOfflineCause() {
     @Exported
     @Override
     public String getOfflineCauseReason() {
-        var offlineCause = getOfflineCause();
-        if (offlineCause == null) {
-            return "";
-        }
-        // fetch the localized string for "Disconnected By"
-        String gsub_base = hudson.slaves.Messages.SlaveComputer_DisconnectedBy("", "");
-        // regex to remove commented reason base string
-        String gsub1 = "^" + gsub_base + "[\\w\\W]* \\: ";
-        // regex to remove non-commented reason base string
-        String gsub2 = "^" + gsub_base + "[\\w\\W]*";
-
-        String newString = offlineCause.toString().replaceAll(gsub1, "");
-        return newString.replaceAll(gsub2, "");
+        return IComputer.super.getOfflineCauseReason();
     }
 
     /**
@@ -677,6 +666,14 @@ public boolean isTemporarilyOffline() {
         return node != null && node.isTemporarilyOffline();
     }
 
+    /**
+     * Allows a caller to define an {@link OfflineCause} for a computer that has never been online.
+     * @since TODO
+     */
+    public void setOfflineCause(OfflineCause cause) {
+        this.offlineCause = cause;
+    }
+
     /**
      * @deprecated as of 1.320.
      *      Use {@link #setTemporaryOfflineCause(OfflineCause)}
@@ -736,37 +733,20 @@ public String getTemporaryOfflineCauseReason() {
     @Exported
     @Override
     public String getIcon() {
-        // The machine was taken offline by someone
-        if (isTemporarilyOffline() && getOfflineCause() instanceof OfflineCause.UserCause) return "symbol-computer-disconnected";
-        // The computer is not accepting tasks, e.g. because the availability demands it being offline.
-        if (!isAcceptingTasks()) {
-            return "symbol-computer-not-accepting";
-        }
-        // The computer is not connected or it is temporarily offline due to a node monitor
-        if (isOffline()) return "symbol-computer-offline";
-        return "symbol-computer";
+        return IComputer.super.getIcon();
     }
 
     /**
      * {@inheritDoc}
      *
-     * <p>
-     * It is both the recommended and default implementation to serve different icons based on {@link #isOffline}.
+     * @see #getIcon()
      */
     @Exported
     @Override
     public String getIconClassName() {
         return IComputer.super.getIconClassName();
     }
 
-    public String getIconAltText() {
-        // The machine was taken offline by someone
-        if (isTemporarilyOffline() && getOfflineCause() instanceof OfflineCause.UserCause) return "[temporarily offline by user]";
-        // There is a "technical" reason the computer will not accept new builds
-        if (isOffline() || !isAcceptingTasks()) return "[offline]";
-        return "[online]";
-    }
-
     @Exported
     @Override public @NonNull String getDisplayName() {
         return nodeName;

core/src/main/java/hudson/slaves/OfflineCause.java

@@ -30,7 +30,7 @@
 import hudson.model.User;
 import java.io.ObjectStreamException;
 import java.util.Collections;
-import java.util.Date;
+import jenkins.agents.IOfflineCause;
 import jenkins.model.Jenkins;
 import org.jvnet.localizer.Localizable;
 import org.kohsuke.accmod.Restricted;
@@ -51,28 +51,20 @@
  * @since 1.320
  */
 @ExportedBean
-public abstract class OfflineCause {
+public abstract class OfflineCause implements IOfflineCause {
     protected final long timestamp = System.currentTimeMillis();
 
     /**
-     * Timestamp in which the event happened.
+     * {@inheritDoc}
      *
      * @since 1.612
      */
     @Exported
+    @Override
     public long getTimestamp() {
         return timestamp;
     }
 
-    /**
-     * Same as {@link #getTimestamp()} but in a different type.
-     *
-     * @since 1.612
-     */
-    public final @NonNull Date getTime() {
-        return new Date(timestamp);
-    }
-
     /**
      * @deprecated Only exists for backward compatibility.
      * @see Computer#setTemporarilyOffline(boolean)
@@ -192,6 +184,24 @@
             }
             return this;
         }
+
+        @Override
+        @NonNull
+        public String getComputerIcon() {
+            return "symbol-computer-disconnected";
+        }
+
+        @Override
+        @NonNull
+        public String getComputerIconAltText() {
+            return "[temporarily offline by user]";
+        }
+
+        @NonNull
+        @Override
+        public String getIcon() {
+            return "symbol-person";
+        }
     }
 
     public static class ByCLI extends UserCause {
@@ -212,5 +222,28 @@
         public IdleOfflineCause() {
             super(hudson.slaves.Messages._RetentionStrategy_Demand_OfflineIdle());
         }
+
+        @Override
+        @NonNull
+        public String getComputerIcon() {
+            return "symbol-computer-paused";
+        }
+
+        @Override
+        @NonNull
+        public String getComputerIconAltText() {
+            return "[will connect automatically whenever needed]";
+        }
+
+        @Override
+        @NonNull
+        public String getIcon() {
+            return "symbol-pause";
+        }
+
+        @Override
+        public String getStatusClass() {
+            return "info";
+        }
     }
 }

core/src/main/java/hudson/slaves/RetentionStrategy.java

@@ -272,6 +272,8 @@
                     logger.log(Level.INFO, "Launching computer {0} as it has been in demand for {1}",
                             new Object[]{c.getName(), Util.getTimeSpanString(demandMilliseconds)});
                     c.connect(false);
+                } else if (c.getOfflineCause() == null) {
+                    c.setOfflineCause(new OfflineCause.IdleOfflineCause());
                 }
             } else if (c.isIdle()) {
                 final long idleMilliseconds = System.currentTimeMillis() - c.getIdleStartMilliseconds();

core/src/main/java/jenkins/agents/IOfflineCause.java

@@ -0,0 +1,108 @@
+/*
+ * The MIT License
+ *
+ * Copyright 2024 CloudBees, Inc.
+ *
+ * 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.agents;
+
+import edu.umd.cs.findbugs.annotations.NonNull;
+import hudson.Util;
+import java.util.Date;
+import java.util.Objects;
+import jenkins.model.IComputer;
+
+/**
+ * Represents a cause that puts a {@linkplain IComputer#isOffline() computer offline}.
+ * @since TODO
+ */
+public interface IOfflineCause {
+    /**
+     * @return The icon to use for the computer that has this offline cause. It will be displayed in the build executor status widget, as well as in nodes list screen.
+     */
+    @NonNull
+    default String getComputerIcon() {
+        return "symbol-computer-offline";
+    }
+
+    /**
+     * @return The alt text for the icon returned by {@link #getComputerIcon()}.
+     */
+    @NonNull
+    default String getComputerIconAltText() {
+        return "[offline]";
+    }
+
+    /**
+     * @return The icon to render this offline cause. It will be displayed in the build executor status widget.
+     */
+    @NonNull
+    default String getIcon() {
+        return "symbol-error";
+    }
+
+    /**
+     * @return The reason why this offline cause exists.
+     * <p>
+     * For implementers: this can use HTML formatting, so make sure to only include trusted content.
+     */
+    @NonNull
+    default String getReason() {
+        // fetch the localized string for "Disconnected By"
+        String gsub_base = hudson.slaves.Messages.SlaveComputer_DisconnectedBy("", "");
+        // regex to remove commented reason base string
+        String gsub1 = "^" + gsub_base + "[\\w\\W]* \\: ";
+        // regex to remove non-commented reason base string
+        String gsub2 = "^" + gsub_base + "[\\w\\W]*";
+        return Objects.requireNonNull(Util.escape(toString().replaceAll(gsub1, "").replaceAll(gsub2, "")));
+    }
+
+    /**
+     * @return A short message (one word) that summarizes the offline cause.
+     *
+     * <p>
+     * For implementers: this can use HTML formatting, so make sure to only include trusted content.
+     */
+    @NonNull
+    default String getMessage() {
+        return Messages.IOfflineCause_offline();
+    }
+
+    /**
+     * @return the CSS class name that should be used to render the status.
+     */
+    @SuppressWarnings("unused") // jelly
+    default String getStatusClass() {
+        return "warning";
+    }
+
+    /**
+     * Timestamp in which the event happened.
+     */
+    long getTimestamp();
+
+    /**
+     * Same as {@link #getTimestamp()} but in a different type.
+     */
+    @NonNull
+    default Date getTime() {
+        return new Date(getTimestamp());
+    }
+}

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

@@ -32,6 +32,7 @@
 import hudson.security.AccessControlled;
 import java.util.List;
 import java.util.concurrent.Future;
+import jenkins.agents.IOfflineCause;
 import org.jenkins.ui.icon.Icon;
 import org.jenkins.ui.icon.IconSet;
 import org.kohsuke.accmod.Restricted;
@@ -91,6 +92,12 @@
         return Util.fixEmpty(getOfflineCauseReason()) != null;
     }
 
+    /**
+     * @return the offline cause if the computer is offline.
+     * @since TODO
+     */
+    IOfflineCause getOfflineCause();
+
     /**
      * If the computer was offline (either temporarily or not),
      * this method will return the cause as a string (without user info).
@@ -101,7 +108,12 @@
      *      empty string if the system was put offline without given a cause.
      */
     @NonNull
-    String getOfflineCauseReason();
+    default String getOfflineCauseReason() {
+        if (getOfflineCause() == null) {
+            return "";
+        }
+        return getOfflineCause().getReason();
+    }
 
     /**
      * @return true if the node is currently connecting to the Jenkins controller.
@@ -115,12 +127,45 @@
      *
      * @see #getIconClassName()
      */
-    String getIcon();
+    default String getIcon() {
+        // The computer is not accepting tasks, e.g. because the availability demands it being offline.
+        if (!isAcceptingTasks()) {
+            return "symbol-computer-not-accepting";
+        }
+        var offlineCause = getOfflineCause();
+        if (offlineCause != null) {
+            return offlineCause.getComputerIcon();
+        }
+        // The computer is not connected or it is temporarily offline due to a node monitor
+        if (isOffline()) return "symbol-computer-offline";
+        return "symbol-computer";
+    }
 
     /**
      * Returns the alternative text for the computer icon.
      */
-    String getIconAltText();
+    @SuppressWarnings("unused") // jelly
+    default String getIconAltText() {
+        if (!isAcceptingTasks()) {
+            return "[suspended]";
+        }
+        var offlineCause = getOfflineCause();
+        if (offlineCause != null) {
+            return offlineCause.getComputerIconAltText();
+        }
+        // There is a "technical" reason the computer will not accept new builds
+        if (isOffline()) return "[offline]";
+        return "[online]";
+    }
+
+    default String getTooltip() {
+        var offlineCause = getOfflineCause();
+        if (offlineCause != null) {
+            return offlineCause.toString();
+        } else {
+            return "";
+        }
+    }
 
     /**
      * Returns the class name that will be used to look up the icon.