Introducing ControllerToAgentCallable and ControllerToAgentFileCallable

core/src/main/java/hudson/Launcher.java

@@ -56,6 +56,7 @@
 import java.util.logging.Level;
 import java.util.logging.Logger;
 import jenkins.model.Jenkins;
+import jenkins.security.ControllerToAgentCallable;
 import jenkins.security.MasterToSlaveCallable;
 import jenkins.tasks.filters.EnvVarsFilterLocalRule;
 import jenkins.tasks.filters.EnvVarsFilterRuleWrapper;
@@ -1114,8 +1115,7 @@ public Proc launch(ProcStarter ps) throws IOException {
             final String workDir = psPwd == null ? null : psPwd.getRemote();
 
             try {
-                RemoteLaunchCallable remote = new RemoteLaunchCallable(ps.commands, ps.masks, ps.envs, in, ps.reverseStdin, out, ps.reverseStdout, err, ps.reverseStderr, ps.quiet, workDir, listener, ps.stdoutListener);
-                remote.setEnvVarsFilterRuleWrapper(envVarsFilterRuleWrapper);
+                RemoteLaunchCallable remote = new RemoteLaunchCallable(ps.commands, ps.masks, ps.envs, in, ps.reverseStdin, out, ps.reverseStdout, err, ps.reverseStderr, ps.quiet, workDir, listener, ps.stdoutListener, envVarsFilterRuleWrapper);
                 // reset the rules to prevent build step without rules configuration to re-use those
                 envVarsFilterRuleWrapper = null;
                 return new ProcImpl(getChannel().call(remote));
@@ -1334,46 +1334,13 @@ public interface RemoteProcess {
         IOTriplet getIOtriplet();
     }
 
-    private static class RemoteLaunchCallable extends MasterToSlaveCallable<RemoteProcess, IOException> {
-        private final @NonNull List<String> cmd;
-        private final @CheckForNull boolean[] masks;
-        private final @CheckForNull String[] env;
-        private final @CheckForNull InputStream in;
-        private final @CheckForNull OutputStream out;
-        private final @CheckForNull OutputStream err;
-        private final @CheckForNull String workDir;
-        private final @NonNull TaskListener listener;
-        private final @CheckForNull TaskListener stdoutListener;
-        private final boolean reverseStdin, reverseStdout, reverseStderr;
-        private final boolean quiet;
-
-        private EnvVarsFilterRuleWrapper envVarsFilterRuleWrapper;
-
-        RemoteLaunchCallable(@NonNull List<String> cmd, @CheckForNull boolean[] masks, @CheckForNull String[] env,
+    private record RemoteLaunchCallable(@NonNull List<String> cmd, @CheckForNull boolean[] masks, @CheckForNull String[] env,
                 @CheckForNull InputStream in, boolean reverseStdin,
                 @CheckForNull OutputStream out, boolean reverseStdout,
                 @CheckForNull OutputStream err, boolean reverseStderr,
-                boolean quiet, @CheckForNull String workDir, @NonNull TaskListener listener, @CheckForNull TaskListener stdoutListener) {
-            this.cmd = new ArrayList<>(cmd);
-            this.masks = masks;
-            this.env = env;
-            this.in = in;
-            this.out = out;
-            this.err = err;
-            this.workDir = workDir;
-            this.listener = listener;
-            this.stdoutListener = stdoutListener;
-            this.reverseStdin = reverseStdin;
-            this.reverseStdout = reverseStdout;
-            this.reverseStderr = reverseStderr;
-            this.quiet = quiet;
-        }
-
-        @Restricted(NoExternalUse.class)
-        public void setEnvVarsFilterRuleWrapper(EnvVarsFilterRuleWrapper envVarsFilterRuleWrapper) {
-            this.envVarsFilterRuleWrapper = envVarsFilterRuleWrapper;
-        }
-
+                boolean quiet, @CheckForNull String workDir,
+                @NonNull TaskListener listener, @CheckForNull TaskListener stdoutListener,
+                @CheckForNull EnvVarsFilterRuleWrapper envVarsFilterRuleWrapper) implements ControllerToAgentCallable<RemoteProcess, IOException> {
         @Override
         public RemoteProcess call() throws IOException {
             final Channel channel = getOpenChannelOrFail();
@@ -1433,8 +1400,6 @@ public IOTriplet getIOtriplet() {
                 }
             });
         }
-
-        private static final long serialVersionUID = 1L;
     }
 
     private static class RemoteChannelLaunchCallable extends MasterToSlaveCallable<OutputStream, IOException> {

core/src/main/java/jenkins/security/ControllerToAgentCallable.java

@@ -0,0 +1,47 @@
+/*
+ * 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.security;
+
+import hudson.remoting.Callable;
+import jenkins.slaves.RemotingVersionInfo;
+import org.jenkinsci.remoting.RoleChecker;
+
+/**
+ * {@link Callable} meant to be serialized then run on an agent.
+ * A typical implementation will be a {@link Record}
+ * since instance state merely transfers a set of parameters to an agent JVM.
+ * <p>Note that the logic within {@link #call} may not use Remoting APIs
+ * newer than {@link RemotingVersionInfo#getMinimumSupportedVersion}.
+ * (Core and plugin APIs will be identical to those run inside the controller.)
+ * @param <V> the return type; note that this must either be defined in your plugin or included in the stock JEP-200 whitelist
+ * @since TODO
+ */
+public interface ControllerToAgentCallable<V, T extends Throwable> extends Callable<V, T>  {
+
+    @Override
+    default void checkRoles(RoleChecker checker) throws SecurityException {
+        checker.check(this, Roles.SLAVE);
+    }
+}

core/src/main/java/jenkins/security/MasterToSlaveCallable.java

@@ -1,15 +1,12 @@
 package jenkins.security;
 
 import hudson.remoting.Callable;
-import jenkins.slaves.RemotingVersionInfo;
 import org.jenkinsci.remoting.RoleChecker;
 
 /**
- * Convenient {@link Callable} meant to be run on agent.
- *
- * Note that the logic within {@link #call()} should use API of a minimum supported Remoting version.
- * See {@link RemotingVersionInfo#getMinimumSupportedVersion()}.
- *
+ * {@link Callable} meant to be run on agent.
+ * For new code, implement {@link ControllerToAgentCallable}
+ * which has the advantage that it can be used on {@code record}s.
  * @author Kohsuke Kawaguchi
  * @since 1.587 / 1.580.1
  * @param <V> the return type; note that this must either be defined in your plugin or included in the stock JEP-200 whitelist

core/src/main/java/jenkins/slaves/RemotingVersionInfo.java

@@ -31,6 +31,7 @@
 import java.util.Properties;
 import java.util.logging.Level;
 import java.util.logging.Logger;
+import jenkins.security.ControllerToAgentCallable;
 
 /**
  * Provides information about Remoting versions used within the core.
@@ -100,7 +101,7 @@ public static VersionNumber getEmbeddedVersion() {
 
     /**
      * Gets Remoting version which is supported by the core.
-     * Jenkins core and plugins make invoke operations on agents (e.g. {@link jenkins.security.MasterToSlaveCallable})
+     * Jenkins core and plugins make invoke operations on agents (e.g. {@link ControllerToAgentCallable})
      * and use Remoting-internal API within them.
      * In such case this API should be present on the remote side.
      * This method defines a minimum expected version, so that all calls should use a compatible API.