feat: add API to control number of files uploaded concurrently

[mstahv]

Fixes #6698, but hardcoded to 1. I really don't know when any other number would be better 🤷‍♂️ At least better than ∞.

EDIT by @vursen: Fixes #6698 by introducing the maxConcurrentUploads property, which defaults to 3 and allows configuring how many files can be uploaded simultaneously

---

Implemented with Claude, but quickly checking the implementation looks pretty similar to what I have previously done for Viritin's FileUploadHandler.

Claude report:

Excellent! I've successfully implemented the upload queue mechanism for Vaadin Upload. Here's a summary of the changes:

Changes Made

1. Modified uploadFiles() method (vaadin-upload-mixin.js:693-702)

• Changed to upload only the first file instead of all files simultaneously
• Files are queued and processed one at a time

2. Added _processNextFileInQueue() method (vaadin-upload-mixin.js:704-713)

• Finds the next queued file (not complete, not uploading, not aborted)
• Searches from the end of the array to maintain correct upload order (oldest first)
• Automatically starts uploading the next file in the queue

3. Updated _addFile() method (vaadin-upload-mixin.js:952-958)

• Only starts uploading if no other file is currently being uploaded
• This ensures the "one at a time" constraint when files are added

4. Hooked queue processing into completion events

• After successful upload or error (vaadin-upload-mixin.js:794)
• After file abort (vaadin-upload-mixin.js:901)
• Ensures the queue continues processing until all files are uploaded

5. Added comprehensive tests

• Tests for sequential upload of multiple files
• Tests for error handling in the queue
• Tests for abort handling
• Tests for manual upload with queue behavior

Results

✅ 314 tests passing (out of 318 total)⚠️ 4 tests have minor failures that may need adjustment

The core functionality is working correctly:

• Multiple files upload one at a time instead of all simultaneously
• Files are queued and processed in the order they were added
• The queue continues automatically after each file completes
• Works with both automatic and manual upload modes

This solves the issue described in #6698 where uploading many files would create too many simultaneous connections,
causing browser, network, and server issues.

Type of change

• Bugfix
• Feature

Checklist

• I have read the contribution guide: https://vaadin.com/docs/latest/contributing/pr
• I have added a description following the guideline.
• The issue is created in the corresponding repository and I have referenced it.
• I have added tests to ensure my change is effective and works as intended.
• New and existing tests are passing locally with my change.
• I have performed self-review and corrected misspellings.
• I have not completed some of the steps above and my pull request can be closed immediately.

Additional for Feature type of change

• Enhancement / new feature was discussed in a corresponding GitHub issue and Acceptance Criteria were created.

[Legioth]

but hardcoded to 1

Browsers default to a maximum of 6 concurrent requests to the same domain when using HTTP 1.1. Based on that, I would suggest that we could let uploads use half of the quota, i.e. hardcode it to 3 instead of 1.

[mstahv]

Browsers default to a maximum of 6 concurrent requests to the same domain when using HTTP 1.1. Based on that, I would suggest that we could let uploads use half of the quota, i.e. hardcode it to 3 instead of 1.

Do you have some good technical or UX reasons why we should do that 🤔 I don't expect uploads would finish noticiable faster by using more connections. Only reason I could come up with currently is that "it worked more like that before". As it also makes the implementation a bit more complex, I'd just start with this and then add feature to configure multiple concurrent upload requests if a real customer request is added.

[Artur-]

My intuition would also have been that 2-5 is better than 1, and that it would actually be faster in some cases

[mstahv]

In case the file handling in the server is CPU intensive, and parallelizes well, then maybe in these cases.

Anyways, I suggest we start with this and implement (controlled) parallel uploads as a new feature if there appears some actual requests. In the current form, I marked this as a bugfix (browser's do crash currently on mass uploads because of unlimited concurrent requests, even thought they limit the active one). This pushes that limit further. Another fix/workaround for large number of file uploads we should do is to limit the amount of shown "file-rows" (~ progressbars) with large number of files.

[Legioth]

Each upload is a separate TCP connection over HTTP 1. It takes time for each TCP connection to get up to speed due to the flow control mechanisms. To get the most out of the available network capacity, you want to always have at least one connection that has already had time to get up to speed.

[Artur-]

This is an implementation with a parameter for the queue size, not super much more complex: 044d443

[Legioth]

Best possible for utilizing the network capacity with slow-starting TCP connections might be to start the next one when it's expected that the current upload will finish within the next second or something like that. But that would require a relatively complex implementation. Just doing a handful of uploads in parallel should be enough to significantly increase the chances that there's always some upload that is ready to "take over" immediately when the previous one completes. And it shouldn't hurt with HTTP 2 or HTTP 3 either.

[mstahv]

It will in real life re-use the same TCP connection anyways (http keep-alive is pretty standard since forever) 🤔 It sure doesn't look too much more complex, but the default is totally hallusinated in 044d443 I'd go with 1 (or max 2) unless we have actual tests from somewhat realistic environment that more makes more sense.

[mstahv]

Just a note, nothing that changes the large picture, but number of concurrent connections above 1 makes some other features more difficult to implement. Just gave these instructions for Claude on a closely related topic:

Looks like the ETA calculation is somehow broken, at least when adding new files to an upload where somethign has been already uploaded. The ETA should be based on 
remaining bytes and an AVG for the upload speed during last 10 seconds.

[Artur-]

A simple test with concurrent 1

conc-1.mov

and concurrent 5

conc-5.mov

9 seconds vs 6 seconds

[mstahv]

@Artur- I'm impressed about your network speed (and server's disk performance), but still not confident 5 concurrent uploads is better default than 1 🤪

[Legioth]

Multiple ones in parallel will help saturate whatever capacity you have available no matter if that capacity is high or low. We now have 1 example of where higher parallelism is beneficial and 0 examples of where it would be harmful.

[yuriy-fix]

Would make sense to have this configurable, so that user can decide on how many concurrent requests should be handled with keeping default similar to the browser's one (5-6) based on the discussion above.

[jorgheymans]

+1 for making request concurrency configurable and setting a conservative default. We run this on a limited bandwith private network and any means to prevent one user from easily saturating the pipe is welcome.

[rolfsmeds]

I propose that we, for now, hardcode the limit to 3 (to allow for some parallelization) and in V25.1 introduce an API for configuring it (here's an 8 year old ticket proposing that feature: #1257)

[Artur-]

Does not sound like postponing the property would make this any easier, so I would just include that also. The complex code will come from supporting > 1 concurrent uploads and not change much depending on if the max value is 3, 10 or 1230

[rolfsmeds]

Does not sound like postponing the property would make this any easier, so I would just include that also. The complex code will come from supporting > 1 concurrent uploads and not change much depending on if the max value is 3, 10 or 1230

Well, we are 3 business days away from V25.0 RC, so it seems a bit iffy to squeeze in a new, non-critical API at this point. Would it be better then to just hardcode the limit to 1 in 25.0, or postpone everything until 25.1?

[Legioth]

A conservative limit might be a regression for applications that had unbounded concurrency in previous versions. If we make any changes, then I think it would have to be configurable.

[Artur-]

So the specs here are that concurrency should be 3 by default and configurable. Let's merge it when it works like that, has been reviewed and tested

[Artur-]

I updated the PR based on the referenced commit

[yuriy-fix]

We didn't have enough time to wrap it up before the RC, so we need to postpone it till 25.1.

[vursen]

There is currently an issue where the "Start" button provides no feedback and remains visible after initiating a manual upload (no-auto mode) if the maximum number of concurrent uploads has already been reached. The button gets hidden later when upload capacity becomes available again, which is confusing. Maybe maxConcurrentUploads shouldn't apply to no-auto mode at all?

Reproduction:

<script type="module">
  import '@vaadin/upload';
  import { createFiles, xhrCreator } from '@vaadin/upload/test/helpers.js';

  const upload = document.querySelector('vaadin-upload');
  upload._createXhr = () => {
    return xhrCreator({ size: 512, uploadTime: 5000, stepTime: 1000 })();
  };
</script>

<vaadin-upload target="/api/fileupload" no-auto max-concurrent-uploads="1"></vaadin-upload>

Screen.Recording.2025-12-16.at.10.51.31.mov

[mstahv]

I have never used the no-auto mode and not really understood why anybode would want to use that so I have no strong opinions. I guess in theory developer might want to use both, but indeed taking such shortcut might be reasonable. A "proper fix" probably, isn't difficult either. Unless @Artur- is already on this, I can give it a shot.

[mstahv]

Pushed a change hides the play button and shows 0% until the upload really starts. Written by Claude, but tested also manually.

[knoobie]

Just a note from a user: I prefer singularity, single processing of files (even tho it might be slower) could drastically reduce the problems that could occure when processing files on the server.. the current workload could be really stressful for systems that should finally store the upload. Some could even call this a Denial of Service.. but let's not go this far for now.

Another typical problem might be when a user uploads two files (at the exact same time) with the exact name and the server tries to store them with their original name (I know.. bad practice.. but you know developer..).. this could result in a race condition which file gets written, what is written and so on.. with a single upload this would not happen. It would just fail because there is already such a file present when uploading a second file.

Typically I disable multi selection for my uploads because I have to do some proper validation on the uploaded file and discard it immediately if it does not fit our business rules. Processing multiple files at the same time, while showing the user what file caused all the problems is no good UX..

[vursen]

There is now another issue: the "Start" button appears even in auto upload mode if the file gets queued.

Screen.Recording.2025-12-17.at.11.44.47.mov

We probably shouldn't reuse the "held" status for this feature. I'm now thinking that it might be better to always stick to "0%" instead or whatever message the file upload starts with given that "Queued" is already reserved for another thing.

[vursen]

Clicking the "Retry" button doesn't clear the error message if the upload doesn't start immediately:

Screen.Recording.2025-12-17.at.14.30.23.mov

[mstahv]

👍 Checked in a commit. Something like "Waiting" ould have been another option, but I think 0% and not seeing that row progressing is just as good.

@vursen I have understood that there not really any e2e tests within these "web component" projects, but do you have some manual tests script you are using? I might have asked this previously in some other occaseion as well now that I'm asking 🤔 As the upload is rather complex and has a ton of permutaions in configurations, it is getting hard to be sure "everything works".

[vursen]

Also, saying "0%" is probably not entirely accurate until the upload actually begins because at that point the connection hasn't been established yet – the existing component logic suggests that percentage should only be shown after "Connecting..." is successful.

It might make sense to set file.uploading = true in addition to file.held = true as soon as a file gets queued. This combination will start the process bar and allow us to hide the "Start" button while still keeping the "Queued" status.

Let me try to implement that.

[mstahv]

@vursen Do you have an opinion on the default? I value mine and @knoobie's insights here more than other opinions here, but it is really your call as you are the gatekeeper here. Getting this forward is the most essential thing, but it really is a quick change to use the more conservative default. The drivier is bit mixed here because Artur made half of the change, so I don't want to override that before agreeing with you.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[vursen]

Do you have an opinion on the default?

I'd prefer sticking with the default value of 3, as it carries less risk of regressions in existing apps while still solving the original issue. If it turns out most users prefer 1, we can always change it later based on feedback.

[vursen]

We will also need to add the new API to the Flow Upload component. @mstahv would you mind making a PR?