Add TUS protocol selection proof

Author: kvz

example/build.gradle

@@ -72,6 +72,12 @@ tasks.register('api2DevdockTusParallelUploadConcat', JavaExec) {
     workingDir = rootProject.projectDir
 }
 
+tasks.register('api2DevdockTusProtocolVersionSelection', JavaExec) {
+    classpath = sourceSets.main.runtimeClasspath
+    mainClass = 'io.tus.java.example.Api2DevdockTusProtocolVersionSelection'
+    workingDir = rootProject.projectDir
+}
+
 tasks.register('api2DevdockTusRequestLifecycleHooks', JavaExec) {
     classpath = sourceSets.main.runtimeClasspath
     mainClass = 'io.tus.java.example.Api2DevdockTusRequestLifecycleHooks'

example/src/main/java/io/tus/java/example/Api2DevdockTusProtocolVersionSelection.java

@@ -0,0 +1,103 @@
+package io.tus.java.example;
+
+import io.tus.java.client.TusClient;
+import io.tus.java.client.TusUpload;
+import io.tus.java.client.TusUploader;
+import org.json.JSONObject;
+
+import java.io.ByteArrayInputStream;
+import java.net.URL;
+import java.util.Map;
+
+public final class Api2DevdockTusProtocolVersionSelection {
+    /**
+     * Run the API2 devdock TUS protocol-version selection example.
+     *
+     * @param args ignored
+     */
+    public static void main(String[] args) {
+        try {
+            System.setProperty("http.strictPostRedirect", "true");
+
+            final JSONObject scenario = Api2DevdockScenario.loadScenario();
+            final JSONObject result = uploadWithSelectedProtocol(scenario);
+            Api2DevdockScenario.writeResult(result);
+
+            System.out.println(
+                    "Java TUS SDK devdock scenario "
+                            + scenario.getString("scenarioId")
+                            + " created upload "
+                            + result.getString("uploadUrl")
+            );
+        } catch (Exception e) {
+            e.printStackTrace();
+            System.exit(1);
+        }
+    }
+
+    private static JSONObject uploadWithSelectedProtocol(JSONObject scenario) throws Exception {
+        final JSONObject conformanceScenario = Api2DevdockScenario.conformanceScenario(scenario);
+        final byte[] content = Api2DevdockScenario.conformanceInputSourceBytes(
+                conformanceScenario
+        );
+        final URL endpointOrigin = new URL(Api2DevdockScenario.conformanceInputStringOption(
+                conformanceScenario,
+                "endpointUrl"
+        ));
+        final Map<String, String> metadata = Api2DevdockScenario.conformanceInputStringMapOption(
+                conformanceScenario,
+                "metadata"
+        );
+        final String protocol = Api2DevdockScenario.conformanceInputStringOption(
+                conformanceScenario,
+                "protocol"
+        );
+        final boolean uploadDataDuringCreation =
+                Api2DevdockScenario.conformanceInputBooleanOption(
+                        conformanceScenario,
+                        "uploadDataDuringCreation",
+                        false
+                );
+        if (!uploadDataDuringCreation) {
+            throw new IllegalArgumentException(
+                    "Java protocol-version selection proof expects creation with upload"
+            );
+        }
+
+        final JSONObject completion = conformanceScenario.getJSONObject("completion");
+        try (Api2DevdockTusConformanceServer conformanceServer =
+                     new Api2DevdockTusConformanceServer(conformanceScenario, endpointOrigin)) {
+            final TusClient client = new TusClient();
+            client.setProtocol(protocol);
+            client.setUploadCreationURL(conformanceServer.endpointUrl());
+
+            final TusUpload upload = new TusUpload();
+            upload.setInputStream(new ByteArrayInputStream(content));
+            upload.setSize(content.length);
+            upload.setFingerprint(
+                    scenario.getString("scenarioId") + "-java-protocol-version-selection"
+            );
+            upload.setMetadata(metadata);
+
+            final TusUploader uploader = client.createUploadWithData(upload, content.length);
+            uploader.finish();
+
+            conformanceServer.assertExhausted();
+            final JSONObject result = conformanceServer.result();
+            result.put("completionKind", completion.getString("kind"));
+            result.put("errorCalled", false);
+            result.put("requestCount", result.getJSONArray("requestMethods").length());
+            result.put("successCalled", true);
+            result.put(
+                    "uploadUrl",
+                    conformanceServer.canonicalUrl(uploader.getUploadURL().toString())
+            );
+
+            return result;
+        }
+    }
+
+    private Api2DevdockTusProtocolVersionSelection() {
+        throw new IllegalStateException("Utility class");
+    }
+}

src/main/java/io/tus/java/client/TusClient.java

@@ -28,6 +28,7 @@ public class TusClient {
     private boolean addRequestId;
     private TusURLStore urlStore;
     private Map<String, String> headers;
+    private String protocol = TusProtocol.DEFAULT_CLIENT_PROTOCOL;
     private int connectTimeout = 5000;
     private TusRequestLifecycleHooks requestLifecycleHooks;
     private volatile HttpURLConnection currentConnection;
@@ -169,6 +170,31 @@ public Map<String, String> getHeaders() {
         return headers;
     }
 
+    /**
+     * Select the TUS client protocol mode used for generated protocol headers.
+     *
+     * @param protocol The protocol mode, e.g. {@code tus-v1} or {@code ietf-draft-05}.
+     */
+    public void setProtocol(@Nullable String protocol) {
+        final String normalizedProtocol = TusProtocol.normalizeProtocol(protocol);
+        if (normalizedProtocol == null) {
+            throw new IllegalArgumentException(
+                    TusProtocol.START_OPTION_VALIDATION_UNSUPPORTED_PROTOCOL_PREFIX + protocol
+            );
+        }
+
+        this.protocol = normalizedProtocol;
+    }
+
+    /**
+     * Return the selected TUS client protocol mode.
+     *
+     * @return The selected protocol mode.
+     */
+    public String getProtocol() {
+        return protocol;
+    }
+
     /**
      * Enable generated request IDs for every HTTP request made by this TusClient instance.
      */
@@ -363,10 +389,7 @@ private TusUploader createUpload(
         prepareUploadCreationHeaders(connection, upload);
 
         if (bytesToUpload > 0) {
-            connection.setRequestProperty(
-                    TusProtocol.UPLOAD_BODY_CONTENT_TYPE_HEADER_NAME,
-                    TusProtocol.UPLOAD_BODY_CONTENT_TYPE
-            );
+            prepareUploadBodyHeaders(connection, bytesToUpload >= upload.getSize());
             connection.setDoOutput(true);
             connection.setFixedLengthStreamingMode(bytesToUpload);
         }
@@ -535,6 +558,30 @@ private static void prepareUploadMetadataHeaders(
         }
     }
 
+    private void prepareUploadBodyHeaders(
+            @NotNull HttpURLConnection connection,
+            boolean requestCompletesUpload
+    ) {
+        final String contentType = TusProtocol.protocolUploadBodyContentType(protocol);
+        if (contentType != null) {
+            connection.setRequestProperty(
+                    TusProtocol.UPLOAD_BODY_CONTENT_TYPE_HEADER_NAME,
+                    contentType
+            );
+        }
+
+        final String uploadCompleteHeaderName =
+                TusProtocol.protocolUploadCompleteHeaderName(protocol);
+        if (uploadCompleteHeaderName == null) {
+            return;
+        }
+
+        connection.setRequestProperty(
+                uploadCompleteHeaderName,
+                TusProtocol.protocolUploadCompleteHeaderValue(protocol, requestCompletesUpload)
+        );
+    }
+
     private static String finalUploadConcatValue(@NotNull List<URL> uploadURLs) {
         StringBuilder value = new StringBuilder(TusProtocol.CONCATENATION_FINAL_PREFIX);
         for (int index = 0; index < uploadURLs.size(); index++) {
@@ -814,7 +861,7 @@ public void prepareConnection(@NotNull HttpURLConnection connection) {
         connection.setInstanceFollowRedirects(Boolean.getBoolean("http.strictPostRedirect"));
 
         connection.setConnectTimeout(connectTimeout);
-        TusProtocol.prepareRequestHeaders(connection, headers, addRequestId);
+        TusProtocol.prepareRequestHeaders(connection, headers, addRequestId, protocol);
     }
 
     final void runBeforeRequest(