Add rest api to create agent from xml (#11229)

* Create agent from xml via rest api

One can create jobs from xml via the rest api or from cli. One can also
create agents from xml via the cli, but creating an agent via rest from
xml is not possible so far.

* add tests

* fix whitespace

---------

Co-authored-by: Mark Waite <mark.earl.waite@gmail.com>

Author: mawinter69

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

@@ -44,6 +44,7 @@
 import hudson.util.FormApply;
 import hudson.util.FormValidation;
 import jakarta.servlet.ServletException;
+import jakarta.servlet.http.HttpServletResponse;
 import java.io.File;
 import java.io.IOException;
 import java.lang.reflect.InvocationTargetException;
@@ -281,6 +282,12 @@ public synchronized void doCreateItem(StaplerRequest2 req, StaplerResponse2 rsp,
         final Jenkins app = Jenkins.get();
         app.checkPermission(Computer.CREATE);
 
+        String requestContentType = req.getContentType();
+
+        boolean isXmlSubmission = requestContentType != null
+                && (requestContentType.startsWith("application/xml")
+                || requestContentType.startsWith("text/xml"));
+
         if (mode != null && mode.equals("copy")) {
             name = checkName(name);
 
@@ -319,6 +326,22 @@ public synchronized void doCreateItem(StaplerRequest2 req, StaplerResponse2 rsp,
             // send the browser to the config page
             rsp.sendRedirect2(result.getNodeName() + "/configure");
         } else {
+            if (isXmlSubmission) {
+                final Node newNode = (Node) Jenkins.XSTREAM2.fromXML(req.getInputStream());
+                name = Util.fixEmptyAndTrim(name);
+
+                if (name != null) {
+                    newNode.setNodeName(name);
+                }
+
+                if (app.getNode(newNode.getNodeName()) != null) {
+                    throw new Failure("Node '" + newNode.getNodeName() + "' already exists");
+                }
+
+                app.addNode(newNode);
+                rsp.setStatus(HttpServletResponse.SC_OK);
+                return;
+            }
             // proceed to step 2
             if (mode == null) {
                 throw new Failure("No mode given");

core/src/main/resources/hudson/model/ComputerSet/_api.jelly

@@ -0,0 +1,12 @@
+<?jelly escape-by-default='true'?>
+<j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler">
+  <h2>Create Node</h2>
+  <p>
+    To create a new node, post <code>config.xml</code> to <a href="../createItem">this URL</a>. Optionally include the query
+    parameter <code>name=<i>NODENAME</i></code> if you want to overwrite the node name set in the xml. You need to send
+    a <code>Content-Type: application/xml header</code>. You will get a 200 status code if the creation
+    is successful, or 4xx/5xx code if it fails. <code>config.xml</code> is the format Jenkins uses to store the node in the file
+    system, so you can see examples of them in the Jenkins home directory, or by retrieving the XML configuration of
+    existing nodes from <code>/computer/<i>NODENAME</i>/config.xml</code>.
+  </p>
+</j:jelly>

test/src/test/java/hudson/model/ComputerSetTest.java

@@ -28,18 +28,24 @@
 import static org.hamcrest.Matchers.contains;
 import static org.hamcrest.Matchers.containsString;
 import static org.hamcrest.Matchers.empty;
+import static org.hamcrest.Matchers.instanceOf;
 import static org.hamcrest.Matchers.is;
 import static org.hamcrest.Matchers.not;
+import static org.hamcrest.Matchers.notNullValue;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 
 import hudson.cli.CLICommandInvoker;
 import hudson.slaves.DumbSlave;
 import hudson.slaves.OfflineCause;
+import hudson.slaves.RetentionStrategy;
 import java.net.HttpURLConnection;
 import jenkins.model.Jenkins;
 import jenkins.widgets.ExecutorsWidget;
 import jenkins.widgets.HasWidgetHelper;
+import org.htmlunit.HttpMethod;
 import org.htmlunit.Page;
+import org.htmlunit.WebRequest;
+import org.htmlunit.WebResponse;
 import org.htmlunit.html.HtmlForm;
 import org.htmlunit.html.HtmlPage;
 import org.junit.jupiter.api.BeforeEach;
@@ -186,4 +192,60 @@ void testTerminatedNodeAjaxExecutorsDoesNotShowTrace() throws Exception {
 
         j.assertBuildStatus(Result.FAILURE, j.waitForCompletion(b));
     }
+
+    @Test
+    void createItemFromXmlNoName() throws Exception {
+        createItemTest(null);
+    }
+
+    @Test
+    void createItemFromXmlWithName() throws Exception {
+        createItemTest("new-name");
+    }
+
+    void createItemTest(String name) throws Exception {
+        String USER = "user";
+        j.jenkins.setSecurityRealm(j.createDummySecurityRealm());
+        j.jenkins.setAuthorizationStrategy(new MockAuthorizationStrategy()
+                // Grant computer create
+                .grant(Jenkins.READ).everywhere().to(USER)
+                .grant(Computer.CREATE).everywhere().to(USER)
+        );
+
+        String xml = """
+                <slave>
+                  <name>agent-from-xml</name>
+                  <description></description>
+                  <remoteFS>/home/jenkins</remoteFS>
+                  <numExecutors>2</numExecutors>
+                  <mode>NORMAL</mode>
+                  <retentionStrategy class="hudson.slaves.RetentionStrategy$Always"/>
+                  <launcher class="hudson.slaves.JNLPLauncher"/>
+                  <label>linux</label>
+                  <nodeProperties/>
+                </slave>
+                """;
+        try (JenkinsRule.WebClient wc = j.createWebClient().withThrowExceptionOnFailingStatusCode(false)) {
+            wc.login(USER);
+            String agentCreateUrl = "computer/createItem";
+            if (name != null) {
+                agentCreateUrl += "?name=" + name;
+            }
+            WebRequest req = new WebRequest(wc.createCrumbedUrl(agentCreateUrl), HttpMethod.POST);
+            req.setAdditionalHeader("Content-Type", "application/xml");
+            req.setRequestBody(xml);
+            WebResponse rsp = wc.getPage(req).getWebResponse();
+            assertThat(rsp.getStatusCode(), is(200));
+            if (name == null) {
+                name = "agent-from-xml";
+            }
+            Node node = j.jenkins.getNode(name);
+            assertThat(node, is(notNullValue()));
+            DumbSlave agent = (DumbSlave) node;
+            assertThat(agent.remoteFS, is("/home/jenkins"));
+            assertThat(agent.getNumExecutors(), is(2));
+            assertThat(agent.getLabelString(), is("linux"));
+            assertThat(agent.getRetentionStrategy(), is(instanceOf(RetentionStrategy.Always.class)));
+        }
+    }
 }