Merge pull request #12 from tomdesair/feature/upload-URI-regex-support

Support regex expression in upload URI

Author: tomdesair

README.md

@@ -38,9 +38,9 @@ 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.
+* `withStoragePath(String)`: If you're using the default file system-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).
 * `withThreadLocalCache(Boolean)`: Optionally you can enable (or disable) an in-memory (thread local) cache of upload request data to reduce load on the storage backend and potentially increase performance when processing upload requests.
 * `withUploadExpirationPeriod(Long)`: You can set the number of milliseconds after which an upload is considered as expired and available for cleanup.
@@ -49,7 +49,7 @@ The first step is to create a `TusFileUploadService` object using its constructo
 * `disableTusExtension(String)`: 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.
 
 
-For now this library only provides filesystem-based storage and locking options. You can however provide your own implementation of a `UploadStorageService` and `UploadLockingService` using the methods `withUploadStorageService(UploadStorageService)` and `withUploadLockingService(UploadLockingService)` in order to support different types of upload storage.
+For now this library only provides file system-based storage and locking options. You can however provide your own implementation of a `UploadStorageService` and `UploadLockingService` using the methods `withUploadStorageService(UploadStorageService)` and `withUploadLockingService(UploadLockingService)` in order to support different types of upload storage.
 
 ### 2. Processing an upload
 To process an upload request you have to pass the current `javax.servlet.http.HttpServletRequest` and `javax.servlet.http.HttpServletResponse` objects to the `me.desair.tus.server.TusFileUploadService.process()` method. Typical places were you can do this are inside Servlets, Filters or REST API Controllers (see [examples](#quick-start-and-examples)).

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 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 file system-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 {@link 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/creation/validation/PostURIValidator.java

@@ -1,25 +1,31 @@
 package me.desair.tus.server.creation.validation;
 
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
 import javax.servlet.http.HttpServletRequest;
 
 import me.desair.tus.server.HttpMethod;
 import me.desair.tus.server.RequestValidator;
 import me.desair.tus.server.exception.PostOnInvalidRequestURIException;
 import me.desair.tus.server.exception.TusException;
 import me.desair.tus.server.upload.UploadStorageService;
-import org.apache.commons.lang3.StringUtils;
 
 /**
  * The Client MUST send a POST request against a known upload creation URL to request a new upload resource.
  */
 public class PostURIValidator implements RequestValidator {
 
+    private Pattern uploadUriPattern = null;
+
     @Override
     public void validate(HttpMethod method, HttpServletRequest request,
                          UploadStorageService uploadStorageService, String ownerKey)
             throws TusException {
 
-        if (!StringUtils.equals(request.getRequestURI(), uploadStorageService.getUploadURI())) {
+        Matcher uploadUriMatcher = getUploadUriPattern(uploadStorageService).matcher(request.getRequestURI());
+
+        if (!uploadUriMatcher.matches()) {
             throw new PostOnInvalidRequestURIException("POST requests have to be send to "
                     + uploadStorageService.getUploadURI());
         }
@@ -30,4 +36,12 @@ public boolean supports(HttpMethod method) {
         return HttpMethod.POST.equals(method);
     }
 
+    private Pattern getUploadUriPattern(UploadStorageService uploadStorageService) {
+        if (uploadUriPattern == null) {
+            //A POST request should match the full URI
+            uploadUriPattern = Pattern.compile("^" + uploadStorageService.getUploadURI() + "$");
+        }
+        return uploadUriPattern;
+    }
+
 }

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

@@ -1,21 +1,48 @@
 package me.desair.tus.server.upload;
 
 import java.util.UUID;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
 
 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 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) {
-        String pathId = StringUtils.substringAfter(url, uploadURI + (StringUtils.endsWith(uploadURI, "/") ? "" : "/"));
+        Matcher uploadUriMatcher = getUploadUriPattern().matcher(StringUtils.trimToEmpty(url));
+        String pathId = uploadUriMatcher.replaceFirst("");
         UUID id = null;
 
         if (StringUtils.isNotBlank(pathId)) {
@@ -29,11 +56,29 @@ 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();
     }
+
+    private Pattern getUploadUriPattern() {
+        if (uploadUriPattern == null) {
+            //We will extract the upload ID's by removing the upload URI from the start of the request URI
+            uploadUriPattern = Pattern.compile("^.*"
+                    + uploadURI
+                    + (StringUtils.endsWith(uploadURI, "/") ? "" : "/?"));
+        }
+        return uploadUriPattern;
+    }
 }

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();