openstack-uicore-foundation 5.0.64 → 5.0.65

package/docs/plans/clickup-dropzone-cancel-chunk-slot-leak.md

@@ -0,0 +1,58 @@
+TITLE
+
+UploadInputV3: cancelling a chunked upload leaks concurrency slots and can stall the next upload
+
+
+GOAL
+
+When a user removes a file in the middle of a chunked upload, DropzoneJS aborts that file's in-flight chunk requests but never gives back their concurrency slots. The dialog stays mounted, so the leaked slots carry over to the next file the user picks in it. With parallelChunkUploads enabled, as sponsor-services has it, one cancel can use up every slot, and the next upload sits on "Uploading" with no error and no progress. A common way to hit this: the user picks the wrong file, deletes it while it is still uploading, then picks the right one.
+
+Current state: xhr.abort() fires the XHR "abort" event, not "load", "error" or "timeout". DropzoneJS only releases a slot from its onload, onerror and ontimeout wrappers, so chunksInFlight is never decremented for aborted chunks. processChunkQueue also skips queued chunks only for files with status "error", not for cancelled ones, so leftover chunks of a removed file are still sent to the server. The counter only resets on unmount, for example when the dialog closes.
+
+Target state: every chunk request that took a slot gives it back, however it ends (load, error, timeout or abort). Queued chunks of a cancelled file are dropped without being sent. A new file uploaded in the same dialog after a cancel starts and finishes normally.
+
+
+TASKS
+
+- Release the chunk slot when a throttled chunk request is aborted
+  - In the "sending" handler of src/components/inputs/dropzone/index.js, wrap xhr.onabort the same way xhr.ontimeout is wrapped: call onChunkComplete() when file._isThrottledChunk is set, then chain any existing handler
+- Stop sending queued chunks that belong to a cancelled file
+  - In processChunkQueue, skip entries whose file has _canceled set or status "canceled", as well as "error"; a skipped entry does not take a slot
+  - In the removedfile handler, drop the removed file's entries from chunkQueue
+- Add regression tests in src/components/inputs/dropzone/__tests__/dropzone.test.js
+  - Cancel with every slot in use, then queue a chunk for a new file: the new chunk is sent right away
+  - Chunks queued for a removed file are never passed to the original _uploadData
+  - Unmount while chunks are in flight: aborts do not push chunksInFlight below 0 and do not send anything
+- Update the Upload Gotchas section of .claude/rules/openstack-uicore-foundation-components.md so it describes the abort-based slot release that is actually implemented
+
+
+ACCEPTANCE CRITERIA
+
+- With maxConcurrentChunks=2, two chunks of file A in flight, and file A removed, a chunk queued afterwards for file B goes out at once: chunkQueue.length is 0 and chunksInFlight is 1
+- After file A is removed, none of its chunks still in chunkQueue reach the original _uploadData
+- After componentWillUnmount runs with chunks in flight, chunksInFlight is 0 and no chunk is sent
+- npx jest src/components/inputs/dropzone src/components/inputs/upload-input-v3 passes: the 81 existing tests (as of PR 330 head d4f53a5) plus the new ones, with 0 failures
+- Manual check in sponsor-services, using a build that includes this change and a file large enough to fill every parallel chunk slot: start the upload, delete it mid-upload, pick another file in the same dialog without closing it. The second upload reaches Complete
+
+
+DEVELOPMENT NOTES
+
+Key files:
+- src/components/inputs/dropzone/index.js: the sending handler wrappers, processChunkQueue, the removedfile handler
+- src/components/inputs/dropzone/__tests__/dropzone.test.js: the regression tests. The Dropzone mock needs an _uploadData jest.fn so setupChunkThrottle installs the wrapper
+- .claude/rules/openstack-uicore-foundation-components.md: the Upload Gotchas section
+
+Gotchas:
+- Release the slot in onabort inside "sending", not in removedfile. Dropzone's removeFile calls cancelUpload first, which already runs file.xhr.abort() (dropzone 5.7.2 dist/dropzone.js:2199-2201). By the time removedfile runs, that xhr's readyState is DONE, so the handler's readyState !== DONE check skips it, and a release placed there would miss that chunk
+- Aborting an xhr that has already finished fires no event, so a chunk that already released its slot through onload cannot be released twice
+- componentWillUnmount sets chunksInFlight to 0 before aborting. The later onabort calls are harmless because onChunkComplete floors the counter at 0 and the queue is already empty
+- Only UploadInputV3 consumers that use parallelChunkUploads can reach a full stall. With sequential chunks, only one slot leaks per cancel, which cuts concurrency but does not block
+- MUI Dialog unmounts its children when closed (keepMounted defaults to false), so the leak lasts only for one open dialog. This is why closing and reopening "fixes" it
+
+Risk: skipping entries in processChunkQueue could leave a live file's chunk behind if the cancel check is too broad
+Mitigation: skip only on _canceled, status "canceled" or status "error", and cover the live-file path with the existing chunk-throttle tests
+
+Out of scope:
+- The status-poll request timeout, which is a separate follow-up
+- Moving UploadInputV3 row identity from name + size to a per-upload id
+- Upload V1/V2 components, beyond sharing the DropzoneJS fix