jenkinsci · jeffret-b · Jan 14, 2020 · Nov 13, 2019 · Nov 21, 2019 · Nov 21, 2019
diff --git a/README.md b/README.md
@@ -24,7 +24,7 @@ Feel free to contribute.
 User documentation:
 
 * [Changelog](CHANGELOG.md) - Remoting release notes
-* [Launching inbound TCP agents](docs/tcpAgent.md) - Mechanisms and parameters for launching inbound TCP agents
+* [Launching inbound agents](docs/inbound-agent.md) - Mechanisms and parameters for launching inbound agents
 * [Remoting Protocols](docs/protocols.md) - Overview of protocols integrated with Jenkins
 * [Remoting Configuration](docs/configuration.md) - Configuring remoting agents
 * [Logging](docs/logging.md) - Logging

diff --git a/assembly-uberjar-14.xml b/assembly-uberjar-14.xml
diff --git a/docs/tcpAgent.md → docs/inbound-agent.md b/docs/tcpAgent.md → docs/inbound-agent.md
@@ -1,17 +1,17 @@
-# Launching inbound TCP agents
+# Launching inbound agents
 Jenkins provides a number of ways of connecting remote agents.
-Two of the most popular are outbound SSH agents and inbound TCP agents.
+Two of the most popular are outbound SSH agents and inbound agents.
 SSH agents, most commonly used on Unix platforms, are master initiated.
 The master creates the connection when it needs.
-Inbound TCP agents, most commonly used on Windows platforms, are agent initiated.
+Inbound agents, most commonly used on Windows platforms, are agent initiated.
 The agent must first connect to the master and then the master sends commands as needed.
 These were formerly known as JNLP agents, but that name was erroneous and confusing.
-This document describes some of the primary mechanisms for launching inbound TCP agents.
+This document describes some of the primary mechanisms for launching inbound agents.
 
 For additional information about Jenkins agents see [Distributed builds](https://wiki.jenkins.io/display/JENKINS/Distributed+builds#Distributedbuilds-HavemasterlaunchagentonWindows).
 
 ## Launch mechanisms
-Part of the agent status page for TCP agents looks something like this:
+Part of the agent status page for inbound agents looks something like this:
 
 ![Tcp agent status UI](tcpAgentStatus.jpg)
 
@@ -33,7 +33,12 @@ This mechanism is not recommended, is deprecated, and may not be supported or av
 ### Download JNLP file
 Another mechanism, shown in the above status page fragment, runs the agent from a script or command-line to retrieve the JNLP file. 
 This mechanism does not use JNLP or WebStart but uses the downloaded file to obtain connection information. 
-Internally, this is a two-step process: 1) connect to an HTTP(S) port to retrieve the connection information, and 2) extract that information and connect to the TCP port.
+
+For an inbound agent using the TCP port, this is a two-step process:
+* Connect to an HTTP(S) port to retrieve the connection information.
+* Extract that information and connect to the TCP port.
+
+(When using the `-webSocket` option, only a single connection needs to be made.)
 
 Before invoking this command you must download the "agent.jar" file.
 The correct version can be obtained from your Jenkins server at something like "https://myjenkins.example.com/jnlpJars/agent.jar".
@@ -114,7 +119,7 @@ Similar to the usage in a number of other applications, this controls which host
 ### The '@' argument annotation
 
 If any command-line argument is prepended with the '@' symbol, special behavior is invoked. 
-For example, more recent versions of Jenkins show in the UI that one form of launching inbound TCP agents is
+For example, more recent versions of Jenkins show in the UI that one form of launching inbound agents is
 ```
 echo <secret key> > secret-file
 java -jar agent.jar -jnlpUrl <jnlp url> -secret @secret-file -workDir <work directory> 

diff --git a/docs/protocols.md b/docs/protocols.md
@@ -1,8 +1,7 @@
 Remoting protocols
 ====
 
-Remoting library provides extension points, which allow implementing custom communication protocols.
-For example, Jenkins project defines its own protocols for the CLI client.
+The Remoting library provides APIs which allow custom communication protocols to be implemented.
 
 This section describes only the protocols available within the remoting library.
 
@@ -27,10 +26,16 @@ If stronger algorithms are needed (for example, AES with 256-bit keys), the [JCE
 
 Protocol uses non-blocking I/O wherever possible which removes the performance bottleneck of the <code>JNLP3-connect</code> protocol.
 
+### WebSocket
+
+* Introduced in: Remoting version TODO, [JEP-222](https://jenkins.io/jep/222)
+
+Uses WebSocket over an HTTP(S) port to handle handshakes, encryption, framing, etc.
+
 ## Plugin protocols
 
 ### Remoting Kafka Plugin
 
 * [Remoting Kafka Plugin](https://github.com/jenkinsci/remoting-kafka-plugin) uses Kafka as fault-tolerant communication layer to support command invocation between Jenkins master and agent.
 * The plugin gets rid of current direct TCP connection between master and agent.
-* More info can be found in the technical [documentation](https://github.com/jenkinsci/remoting-kafka-plugin/blob/master/docs/DOCUMENTATION.md) of the plugin.
+* More info can be found in the technical [documentation](https://github.com/jenkinsci/remoting-kafka-plugin/blob/master/docs/DOCUMENTATION.md) of the plugin.
diff --git a/pom.xml b/pom.xml
@@ -94,7 +94,12 @@ THE SOFTWARE.
       <artifactId>animal-sniffer-annotations</artifactId>
       <scope>provided</scope>
     </dependency>
-    <!-- test dependencies -->
+    <dependency>
+      <groupId>org.glassfish.tyrus.bundles</groupId>
+      <artifactId>tyrus-standalone-client-jdk</artifactId>
+      <version>1.12</version>
+      <optional>true</optional>
+    </dependency>
     <dependency>
       <groupId>junit</groupId>
       <artifactId>junit</artifactId>
@@ -129,7 +134,7 @@ THE SOFTWARE.
       <groupId>args4j</groupId>
       <artifactId>args4j</artifactId>
       <version>2.33</version>
-      <scope>provided</scope>
+      <optional>true</optional>
     </dependency>
     <dependency>
       <groupId>commons-io</groupId>
@@ -148,22 +153,16 @@ THE SOFTWARE.
       <version>1.10.19</version>
       <scope>test</scope>
     </dependency>
-    <dependency>
-      <!-- for JRE requirement check annotation -->
-      <groupId>org.jvnet</groupId>
-      <artifactId>animal-sniffer-annotation</artifactId>
-      <version>1.0</version>
-      <optional>true</optional><!-- no need to have this at runtime -->
-    </dependency>
     <dependency>
       <groupId>org.jenkins-ci</groupId>
       <artifactId>constant-pool-scanner</artifactId>
       <version>1.2</version>
+      <optional>true</optional>
     </dependency>
     <dependency>
       <groupId>com.github.spotbugs</groupId>
       <artifactId>spotbugs-annotations</artifactId>
-      <optional>true</optional>
+      <scope>provided</scope>
     </dependency>
     <dependency>
       <groupId>org.bouncycastle</groupId>
@@ -181,13 +180,7 @@ THE SOFTWARE.
       <groupId>org.kohsuke</groupId>
       <artifactId>access-modifier-annotation</artifactId>
       <version>1.12</version>
-      <type>jar</type>
-      <optional>true</optional><!-- no need to have this at runtime -->
-    </dependency>
-    <dependency>
-      <groupId>org.jenkins-ci</groupId>
-      <artifactId>test-annotations</artifactId>
-      <scope>test</scope>
+      <scope>provided</scope>
     </dependency>
   </dependencies>
 
@@ -219,25 +212,57 @@ THE SOFTWARE.
           <targetJdk>1.${java.level}</targetJdk>
         </configuration>
       </plugin>
+      <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-shade-plugin</artifactId>
+          <version>3.2.1</version>
+          <executions>
+              <execution>
+                  <phase>package</phase>
+                  <goals>
+                      <goal>shade</goal>
+                  </goals>
+                  <configuration>
+                      <createDependencyReducedPom>false</createDependencyReducedPom>
+                      <relocations>
+                          <relocation>
+                              <pattern>javax.websocket</pattern>
+                              <shadedPattern>io.jenkins.remoting.shaded.javax.websocket</shadedPattern>
+                          </relocation>
+                          <relocation>
+                              <pattern>org.glassfish.tyrus</pattern>
+                              <shadedPattern>io.jenkins.remoting.shaded.org.glassfish.tyrus</shadedPattern>
+                          </relocation>
+                          <relocation>
+                              <pattern>org.kohsuke.args4j</pattern>
+                              <shadedPattern>io.jenkins.remoting.shaded.org.kohsuke.args4j</shadedPattern>
+                          </relocation>
+                          <relocation>
+                              <pattern>org.jenkinsci.constant_pool_scanner</pattern>
+                              <shadedPattern>io.jenkins.remoting.shaded.org.jenkinsci.constant_pool_scanner</shadedPattern>
+                          </relocation>
+                      </relocations>
+                      <transformers>
+                          <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
+                              <mainClass>hudson.remoting.Launcher</mainClass>
+                              <manifestEntries>
+                                  <Version>${project.version}</Version>
+                                  <!-- attributes related to Java Web Start -->
+                                  <!-- see http://docs.oracle.com/javase/8/docs/technotes/guides/jweb/security/manifest.html -->
+                                  <Permissions>all-permissions</Permissions>
+                                  <Codebase>*</Codebase>
+                                  <Application-Name>Jenkins Remoting Agent</Application-Name>
+                                  <Trusted-Library>true</Trusted-Library>
+                              </manifestEntries>
+                          </transformer>
+                          <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
+                      </transformers>
+                  </configuration>
+              </execution>
+          </executions>
+      </plugin>
       <plugin>
         <artifactId>maven-jar-plugin</artifactId>
-        <!-- version specified in grandparent pom -->
-        <configuration>
-          <archive>
-            <manifest>
-              <mainClass>hudson.remoting.Launcher</mainClass>
-            </manifest>
-            <manifestEntries>
-              <Version>${project.version}</Version>
-              <!-- attributes related to Java Web Start -->
-              <!-- see http://docs.oracle.com/javase/8/docs/technotes/guides/jweb/security/manifest.html -->
-              <Permissions>all-permissions</Permissions>
-              <Codebase>*</Codebase>
-              <Application-Name>Jenkins Remoting Agent</Application-Name>
-              <Trusted-Library>true</Trusted-Library>
-            </manifestEntries>
-          </archive>
-        </configuration>
         <executions>
           <execution>
             <id>executable-tests</id>
@@ -317,31 +342,6 @@ THE SOFTWARE.
               </artifactItems>
             </configuration>
           </execution>
-          <execution>
-            <id>bundle-arg4j</id>
-            <phase>process-classes</phase>
-            <goals>
-              <goal>unpack-dependencies</goal>
-            </goals>
-            <configuration>
-              <outputDirectory>${project.build.outputDirectory}</outputDirectory>
-              <includeScope>provided</includeScope>
-              <includeArtifactIds>args4j</includeArtifactIds>
-              <includeGroupIds>args4j</includeGroupIds>
-            </configuration>
-          </execution>
-          <execution>
-            <id>bundle-cps</id>
-            <phase>process-classes</phase>
-            <goals>
-              <goal>unpack-dependencies</goal>
-            </goals>
-            <configuration>
-              <outputDirectory>${project.build.outputDirectory}</outputDirectory>
-              <includeArtifactIds>constant-pool-scanner</includeArtifactIds>
-              <includeGroupIds>org.jenkins-ci</includeGroupIds>
-            </configuration>
-          </execution>
         </executions>
       </plugin>
       <plugin>

diff --git a/src/main/java/hudson/remoting/AbstractByteArrayCommandTransport.java b/src/main/java/hudson/remoting/AbstractByteArrayCommandTransport.java
@@ -45,11 +45,12 @@ public interface ByteArrayReceiver {
          *
          * As discussed in {@link AbstractByteArrayCommandTransport#writeBlock(Channel, byte[])},
          * the block boundary is significant.
+         * @see CommandReceiver#handle
          */
         void handle(byte[] payload);
 
         /**
-         * See {@link CommandReceiver#handle(Command)} for details.
+         * @see CommandReceiver#terminate
          */
         void terminate(IOException e);
     }

diff --git a/src/main/java/hudson/remoting/Capability.java b/src/main/java/hudson/remoting/Capability.java
@@ -2,6 +2,8 @@
 
 import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
 import hudson.remoting.Channel.Mode;
+import java.io.ByteArrayInputStream;
+import java.io.ByteArrayOutputStream;
 import java.io.IOException;
 import java.io.InputStream;
 import java.io.ObjectInputStream;
@@ -25,6 +27,12 @@
  * @see Channel#remoteCapability
  */
 public final class Capability implements Serializable {
+
+    /**
+     * Key usable as a WebSocket HTTP header to negotiate capabilities.
+     */
+    public static final String KEY = "X-Remoting-Capability";
+
     /**
      * Bit mask of optional capabilities.
      */
@@ -121,10 +129,17 @@ public boolean supportsProxyExceptionFallback() {
 
     //TODO: ideally preamble handling needs to be reworked in order to avoid FB suppression
     /**
-     * Writes out the capacity preamble.
+     * Writes {@link #PREAMBLE} then uses {@link #write}.
      */
     void writePreamble(OutputStream os) throws IOException {
         os.write(PREAMBLE);
+        write(os);
+    }
+
+    /**
+     * Writes this capability to a stream.
+     */
+    private void write(OutputStream os) throws IOException {
         try (ObjectOutputStream oos = new ObjectOutputStream(Mode.TEXT.wrap(os)) {
             @Override
             public void close() throws IOException {
@@ -144,7 +159,7 @@ protected void annotateClass(Class<?> c) throws IOException {
     }
 
     /**
-     * The opposite operation of {@link #writePreamble(OutputStream)}.
+     * The opposite operation of {@link #write}.
      */
     @SuppressFBWarnings(value = "OBJECT_DESERIALIZATION", justification = "Capability is used for negotiating channel between authorized agent and server. Whitelisting and proper deserialization hygiene are used.")
     public static Capability read(InputStream is) throws IOException {
@@ -173,6 +188,25 @@ public void close() throws IOException {
         }
     }
 
+    /**
+     * Uses {@link #write} to serialize this object to a Base64-encoded ASCII stream.
+     */
+    public String toASCII() throws IOException {
+        try (ByteArrayOutputStream baos = new ByteArrayOutputStream()) {
+            write(baos);
+            return baos.toString(StandardCharsets.US_ASCII.name());
+        }
+    }
+
+    /**
+     * The inverse of {@link #toASCII}.
+     */
+    public static Capability fromASCII(String ascii) throws IOException {
+        try (ByteArrayInputStream bais = new ByteArrayInputStream(ascii.getBytes(StandardCharsets.US_ASCII))) {
+            return Capability.read(bais);
+        }
+    }
+
     private static final long serialVersionUID = 1L;
 
     /**