Tests and documentation on uploadURI regex support

Author: tomdesair

README.md

@@ -38,7 +38,7 @@ Besides the [core protocol](https://tus.io/protocols/resumable-upload.html#core-
 ### 1. Setup
 The first step is to create a `TusFileUploadService` object using its constructor. You can make this object available as a (Spring bean) singleton or create a new instance for each request. After creating the object, you can configure it using the following methods:
 
-* `withUploadURI(String)`: Set the relative URL under which the tus upload endpoint will be made available, for example `/files/upload`.
+* `withUploadURI(String)`: Set the relative URL under which the main tus upload endpoint will be made available, for example `/files/upload`. Optionally, this URI may contain regex parameters in order to support endpoints that contain URL parameters, for example `/users/[0-9]+/files/upload`.
 * `withMaxUploadSize(Long)`: Specify the maximum number of bytes that can be uploaded per upload. If you don't call this method, the maximum number of bytes is `Long.MAX_VALUE`.
 * `withStoragePath(String)`: If you're using the default filesystem-based storage service, you can use this method to specify the path where to store the uploaded bytes and upload information.
 * `withChunkedTransferDecoding`: You can enable or disable the decoding of chunked HTTP requests by this library. Enable this feature in case the web container in which this service is running does not decode chunked transfers itself. By default, chunked decoding via this library is disabled (as modern frameworks tend to already do this for you).

src/main/java/me/desair/tus/server/TusFileUploadService.java

@@ -67,18 +67,39 @@ protected void initFeatures() {
         addTusExtension(new ConcatenationExtension());
     }
 
+    /**
+     * Set the URI under which the main tus upload endpoint is hosted.
+     * Optionally, this URI may contain regex parameters in order to support endpoints that contain
+     * URL parameters, for example /users/[0-9]+/files/upload
+     *
+     * @param uploadURI The URI of the main tus upload endpoint
+     * @return The current service
+     */
     public TusFileUploadService withUploadURI(String uploadURI) {
-        Validate.notBlank(uploadURI, "The upload URI pattern cannot be blank");
         this.idFactory.setUploadURI(uploadURI);
         return this;
     }
 
+    /**
+     * Specify the maximum number of bytes that can be uploaded per upload.
+     * If you don't call this method, the maximum number of bytes is Long.MAX_VALUE.
+     *
+     * @param maxUploadSize The maximum upload length that is allowed
+     * @return The current service
+     */
     public TusFileUploadService withMaxUploadSize(Long maxUploadSize) {
         Validate.exclusiveBetween(0, Long.MAX_VALUE, maxUploadSize, "The max upload size must be bigger than 0");
         this.uploadStorageService.setMaxUploadSize(maxUploadSize);
         return this;
     }
 
+    /**
+     * Provide a custom {@link UploadStorageService} implementation that should be used to store uploaded bytes and
+     * metadata ({@link UploadInfo}).
+     *
+     * @param uploadStorageService The custom {@link UploadStorageService} implementation
+     * @return The current service
+     */
     public TusFileUploadService withUploadStorageService(UploadStorageService uploadStorageService) {
         Validate.notNull(uploadStorageService, "The UploadStorageService cannot be null");
         //Copy over any previous configuration
@@ -91,6 +112,14 @@ public TusFileUploadService withUploadStorageService(UploadStorageService upload
         return this;
     }
 
+    /**
+     * Provide a custom {@link UploadLockingService} implementation that should be used when processing uploads.
+     * The upload locking service is responsible for locking an upload that is being processed so that it cannot
+     * be corrupted by simultaneous or delayed requests.
+     *
+     * @param uploadLockingService The {@link UploadLockingService} implementation to use
+     * @return The current service
+     */
     public TusFileUploadService withUploadLockingService(UploadLockingService uploadLockingService) {
         Validate.notNull(uploadLockingService, "The UploadStorageService cannot be null");
         uploadLockingService.setIdFactory(this.idFactory);
@@ -100,6 +129,13 @@ public TusFileUploadService withUploadLockingService(UploadLockingService upload
         return this;
     }
 
+    /**
+     * If you're using the default filesystem-based storage service, you can use this method to
+     * specify the path where to store the uploaded bytes and upload information.
+     *
+     * @param storagePath The file system path where uploads can be stored (temporarily)
+     * @return The current service
+     */
     public TusFileUploadService withStoragePath(String storagePath) {
         Validate.notBlank(storagePath, "The storage path cannot be blank");
         withUploadStorageService(new DiskStorageService(idFactory, storagePath));
@@ -133,48 +169,102 @@ public TusFileUploadService withChunkedTransferDecoding(boolean isEnabled) {
         return this;
     }
 
+    /**
+     * You can set the number of milliseconds after which an upload is considered as expired and available for cleanup.
+     *
+     * @param expirationPeriod The number of milliseconds after which an upload expires and can be removed
+     * @return The current service
+     */
     public TusFileUploadService withUploadExpirationPeriod(Long expirationPeriod) {
         uploadStorageService.setUploadExpirationPeriod(expirationPeriod);
         return this;
     }
 
+    /**
+     * Enable the unofficial `download` extension that also allows you to download uploaded bytes.
+     * By default this feature is disabled.
+     *
+     * @return The current service
+     */
     public TusFileUploadService withDownloadFeature() {
         addTusExtension(new DownloadExtension());
         return this;
     }
 
+    /**
+     * Add a custom (application-specific) extension that implements the `me.desair.tus.server.TusExtension` interface.
+     * For example you can add your own extension that checks authentication and authorization policies within your
+     * application for the user doing the upload.
+     *
+     * @param feature The custom extension implementation
+     * @return The current service
+     */
     public TusFileUploadService addTusExtension(TusExtension feature) {
         Validate.notNull(feature, "A custom feature cannot be null");
         enabledFeatures.put(feature.getName(), feature);
         updateSupportedHttpMethods();
         return this;
     }
 
-    public TusFileUploadService disableTusExtension(String featureName) {
-        Validate.notNull(featureName, "The feature name cannot be null");
-
-        if (StringUtils.equals("core", featureName)) {
-            throw new IllegalArgumentException("The core protocol cannot be disabled");
-        }
+    /**
+     * Disable the TusExtension for which the getName() method matches the provided string. The default extensions
+     * have names "creation", "checksum", "expiration", "concatenation", "termination" and "download".
+     * You cannot disable the "core" feature.
+     *
+     * @param extensionName The name of the extension to disable
+     * @return The current service
+     */
+    public TusFileUploadService disableTusExtension(String extensionName) {
+        Validate.notNull(extensionName, "The extension name cannot be null");
+        Validate.isTrue(!StringUtils.equals("core", extensionName), "The core protocol cannot be disabled");
 
-        enabledFeatures.remove(featureName);
+        enabledFeatures.remove(extensionName);
         updateSupportedHttpMethods();
         return this;
     }
 
+    /**
+     * Get all HTTP methods that are supported by this TusUploadService based on the enabled and/or disabled
+     * tus extensions
+     *
+     * @return The set of enabled HTTP methods
+     */
     public Set<HttpMethod> getSupportedHttpMethods() {
         return EnumSet.copyOf(supportedHttpMethods);
     }
 
+    /**
+     * Get the set of enabled Tus extensions
+     * @return The set of active extensions
+     */
     public Set<String> getEnabledFeatures() {
         return new LinkedHashSet<>(enabledFeatures.keySet());
     }
 
+    /**
+     * Process a tus upload request.
+     * Use this method to process any request made to the main and sub tus upload endpoints. This corresponds to
+     * the path specified in the withUploadURI() method and any sub-path of that URI.
+     *
+     * @param servletRequest The {@link HttpServletRequest} of the request
+     * @param servletResponse The {@link HttpServletResponse} of the request
+     * @throws IOException When saving bytes or information of this requests fails
+     */
     public void process(HttpServletRequest servletRequest, HttpServletResponse servletResponse)
             throws IOException {
         process(servletRequest, servletResponse, null);
     }
 
+    /**
+     * Process a tus upload request that belongs to a specific owner.
+     * Use this method to process any request made to the main and sub tus upload endpoints. This corresponds to
+     * the path specified in the withUploadURI() method and any sub-path of that URI.
+     *
+     * @param servletRequest The {@link HttpServletRequest} of the request
+     * @param servletResponse The {@link HttpServletResponse} of the request
+     * @param ownerKey A unique identifier of the owner (group) of this upload
+     * @throws IOException When saving bytes or information of this requests fails
+     */
     public void process(HttpServletRequest servletRequest, HttpServletResponse servletResponse,
                         String ownerKey) throws IOException {
         Validate.notNull(servletRequest, "The HTTP Servlet request cannot be null");

src/main/java/me/desair/tus/server/upload/UploadIdFactory.java

@@ -7,17 +7,39 @@
 import org.apache.commons.lang3.StringUtils;
 import org.apache.commons.lang3.Validate;
 
+/**
+ * Factory to create unique upload IDs. This factory can also parse the upload identifier
+ * from a given upload URL.
+ */
 public class UploadIdFactory {
 
     private String uploadURI = "/";
     private Pattern uploadUriPattern = null;
 
+    /**
+     * Set the URI under which the main tus upload endpoint is hosted.
+     * Optionally, this URI may contain regex parameters in order to support endpoints that contain
+     * URL parameters, for example /users/[0-9]+/files/upload
+     *
+     * @param uploadURI The URI of the main tus upload endpoint
+     */
     public void setUploadURI(String uploadURI) {
-        Validate.notNull(uploadURI, "The upload URI pattern cannot be null");
+        Validate.notBlank(uploadURI, "The upload URI pattern cannot be blank");
+        Validate.isTrue(StringUtils.startsWith(uploadURI, "/"), "The upload URI should start with /");
+        Validate.isTrue(!StringUtils.endsWith(uploadURI, "$"), "The upload URI should not end with $");
         this.uploadURI = uploadURI;
         this.uploadUriPattern = null;
     }
 
+    /**
+     * Read the upload identifier from the given URL.
+     * <p/>
+     * Clients will send requests to upload URLs or provided URLs of completed uploads. This method is able to
+     * parse those URLs and provide the user with the corresponding upload ID.
+     *
+     * @param url The URL provided by the client
+     * @return The corresponding Upload identifier
+     */
     public UUID readUploadId(String url) {
         Matcher uploadUriMatcher = getUploadUriPattern().matcher(StringUtils.trimToEmpty(url));
         String pathId = uploadUriMatcher.replaceFirst("");
@@ -34,10 +56,18 @@ public UUID readUploadId(String url) {
         return id;
     }
 
+    /**
+     * Return the URI of the main tus upload endpoint. Note that this value possibly contains regex parameters.
+     * @return The URI of the main tus upload endpoint.
+     */
     public String getUploadURI() {
         return uploadURI;
     }
 
+    /**
+     * Create a new unique upload ID
+     * @return A new unique upload ID
+     */
     public synchronized UUID createId() {
         return UUID.randomUUID();
     }

src/test/java/me/desair/tus/server/ITTusFileUploadService.java

@@ -1157,20 +1157,20 @@ public void testConcatenationUnfinished() throws Exception {
     }
 
     @Test
-    public void testChunkedDecodingDisabled() throws Exception {
+    public void testChunkedDecodingDisabledAndRegexUploadURI() throws Exception {
         String chunkedContent = "1B;test=value\r\nThis upload looks chunked, \r\n"
                 + "D\r\nbut it's not!\r\n"
                 + "\r\n0\r\n";
 
         //Create service without chunked decoding
         tusFileUploadService = new TusFileUploadService()
-                .withUploadURI(UPLOAD_URI)
+                .withUploadURI("/users/[0-9]+/files/upload")
                 .withStoragePath(storagePath.toAbsolutePath().toString())
                 .withDownloadFeature();
 
         //Create upload
         servletRequest.setMethod("POST");
-        servletRequest.setRequestURI(UPLOAD_URI);
+        servletRequest.setRequestURI("/users/98765/files/upload");
         servletRequest.addHeader(HttpHeader.CONTENT_LENGTH, 0);
         servletRequest.addHeader(HttpHeader.UPLOAD_LENGTH, "67");
         servletRequest.addHeader(HttpHeader.TUS_RESUMABLE, "1.0.0");
@@ -1183,8 +1183,7 @@ public void testChunkedDecodingDisabled() throws Exception {
         assertResponseHeaderNull(HttpHeader.UPLOAD_EXPIRES);
         assertResponseStatus(HttpServletResponse.SC_CREATED);
 
-        String location = UPLOAD_URI +
-                StringUtils.substringAfter(servletResponse.getHeader(HttpHeader.LOCATION), UPLOAD_URI);
+        String location = servletResponse.getHeader(HttpHeader.LOCATION);
 
         //Upload content
         reset();

src/test/java/me/desair/tus/server/creation/ITCreationExtension.java

@@ -5,6 +5,7 @@
 import static org.hamcrest.MatcherAssert.assertThat;
 import static org.mockito.Matchers.notNull;
 import static org.mockito.Mockito.anyString;
+import static org.mockito.Mockito.reset;
 import static org.mockito.Mockito.times;
 import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
@@ -47,6 +48,7 @@ public void setUp() throws Exception {
 
         id =  UUID.randomUUID();
         servletRequest.setRequestURI(UPLOAD_URI);
+        reset(uploadStorageService);
         when(uploadStorageService.getUploadURI()).thenReturn(UPLOAD_URI);
         when(uploadStorageService.create(Matchers.any(UploadInfo.class), anyString())).then(new Answer<UploadInfo>() {
             @Override
@@ -200,4 +202,65 @@ public void testPostOnInvalidUrl() throws Exception {
 
         executeCall(HttpMethod.POST, false);
     }
+
+    @Test
+    public void testPostWithValidRegexURI() throws Exception {
+        reset(uploadStorageService);
+        when(uploadStorageService.getUploadURI()).thenReturn("/submission/([a-z0-9]+)/files/upload");
+        when(uploadStorageService.create(Matchers.any(UploadInfo.class), anyString())).then(new Answer<UploadInfo>() {
+            @Override
+            public UploadInfo answer(InvocationOnMock invocation) throws Throwable {
+                UploadInfo upload = invocation.getArgumentAt(0, UploadInfo.class);
+                upload.setId(id);
+
+                when(uploadStorageService.getUploadInfo("/submission/0ae5f8vv4s8c/files/upload/" + id.toString(),
+                        invocation.getArgumentAt(1, String.class))).thenReturn(upload);
+                return upload;
+            }
+        });
+
+
+        //Create upload
+        servletRequest.setRequestURI("/submission/0ae5f8vv4s8c/files/upload");
+        servletRequest.addHeader(HttpHeader.UPLOAD_LENGTH, 9);
+        servletRequest.addHeader(HttpHeader.UPLOAD_METADATA, "submission metadata");
+
+        executeCall(HttpMethod.POST, false);
+
+        verify(uploadStorageService, times(1)).create(notNull(UploadInfo.class), anyString());
+        assertResponseHeader(HttpHeader.LOCATION, "/submission/0ae5f8vv4s8c/files/upload/" + id.toString());
+        assertResponseStatus(HttpServletResponse.SC_CREATED);
+
+        //Check data with head request
+        servletRequest.setRequestURI("/submission/0ae5f8vv4s8c/files/upload/" + id.toString());
+        servletResponse = new MockHttpServletResponse();
+        executeCall(HttpMethod.HEAD, false);
+
+        assertThat(servletResponse.getHeader(HttpHeader.UPLOAD_METADATA), is("submission metadata"));
+        assertThat(servletResponse.getHeader(HttpHeader.UPLOAD_DEFER_LENGTH), is(nullValue()));
+    }
+
+    @Test(expected = PostOnInvalidRequestURIException.class)
+    public void testPostWithInvalidRegexURI() throws Exception {
+        reset(uploadStorageService);
+        when(uploadStorageService.getUploadURI()).thenReturn("/submission/([a-z0-9]+)/files/upload");
+        when(uploadStorageService.create(Matchers.any(UploadInfo.class), anyString())).then(new Answer<UploadInfo>() {
+            @Override
+            public UploadInfo answer(InvocationOnMock invocation) throws Throwable {
+                UploadInfo upload = invocation.getArgumentAt(0, UploadInfo.class);
+                upload.setId(id);
+
+                when(uploadStorageService.getUploadInfo("/submission/0ae5f8vv4s8c/files/upload/" + id.toString(),
+                        invocation.getArgumentAt(1, String.class))).thenReturn(upload);
+                return upload;
+            }
+        });
+
+        //Create upload
+        servletRequest.setRequestURI("/submission/a+b/files/upload");
+        servletRequest.addHeader(HttpHeader.UPLOAD_LENGTH, 9);
+        servletRequest.addHeader(HttpHeader.UPLOAD_METADATA, "submission metadata");
+
+        executeCall(HttpMethod.POST, false);
+    }
 }

src/test/java/me/desair/tus/server/upload/UploadIdFactoryTest.java

@@ -35,6 +35,21 @@ public void setUploadURIWithTrailingSlash() throws Exception {
         assertThat(idFactory.getUploadURI(), is("/test/upload/"));
     }
 
+    @Test(expected = IllegalArgumentException.class)
+    public void setUploadURIBlank() throws Exception {
+        idFactory.setUploadURI(" ");
+    }
+
+    @Test(expected = IllegalArgumentException.class)
+    public void setUploadURINoStartingSlash() throws Exception {
+        idFactory.setUploadURI("test/upload/");
+    }
+
+    @Test(expected = IllegalArgumentException.class)
+    public void setUploadURIEndsWithDollar() throws Exception {
+        idFactory.setUploadURI("/test/upload$");
+    }
+
     @Test
     public void readUploadId() throws Exception {
         idFactory.setUploadURI("/test/upload");