collection.upload handlers - mismatch between docs and implementation

[OrenSayag]

Link to reproduction

No response

Describe the Bug

When setting an upload collection handlers array, all handlers are run and the last result is effective. This contradicts docs and results in redundant handler runs.

Docs:

"If a handler returns a Response, the response will be sent to the client and no further handlers will be run. "

payload/packages/payload/src/uploads/types.ts

Lines 168 to 183 in 03d4c5b

	/**
	* Custom handlers to run when a file is fetched.
	*
	* - If a handler returns a Response, the response will be sent to the client and no further handlers will be run.
	* - If a handler returns null, the next handler will be run.
	* - If no handlers return a response the file will be returned by default.
	*
	* @default undefined
	*/
	handlers?: ((
	req: PayloadRequest,
	args: {
	doc: TypeWithID
	params: { clientUploadContext?: unknown; collection: string; filename: string }
	},
	) => Promise<Response> | Promise<void> | Response | void)[]

Implementation:

payload/packages/payload/src/uploads/endpoints/getFile.ts

Lines 40 to 56 in 03d4c5b

	if (collection.config.upload.handlers?.length) {
	let customResponse = null
	for (const handler of collection.config.upload.handlers) {
	customResponse = await handler(req, {
	doc: accessResult,
	params: {
	collection: collection.config.slug,
	filename,
	},
	})
	}
	if (customResponse instanceof Response) {
	return customResponse
	}
	}

To Reproduce

0. You can clone this repo and skip steps 1+2: https://github.com/OrenSayag/poc-payload-upload-handlers

1. pnpm dlx create-payload-app poc-upload-handlers-bug

2. Edit Media collection:

import type { CollectionConfig } from 'payload'

export const Media: CollectionConfig = {
    slug: 'media',
    access: {
        read: () => true,
    },
    fields: [
        {
            name: 'alt',
            type: 'text',
            required: true,
        },
    ],
    upload: {
        handlers: [
            async () => {
                await new Promise((resolve) => setTimeout(resolve, 3_000))
                console.log(`File processed after 3 seconds`)
                return Response.json({ message: 'File processed after 3 seconds' })
            },

            async () => {
                await new Promise((resolve) => setTimeout(resolve, 5_000))
                console.log(`File processed after 5 seconds`)
                return Response.json({ message: 'File processed after 8 seconds' })
            },
        ],
    },
}

3. Upload a file using UI
4. Click on its name to open in a new tab, the static route

5. Notice the response is served after 8 seconds,
   and in console logs:

File processed after 3 seconds
File processed after 5 seconds
GET /api/media/file/android-chrome-192x192.png 200 in 8037ms

Payload Version

3.55.0

Adapters and Plugins

No response

[github-actions]

🚀 This is included in version v3.57.0

[github-actions]

This issue has been automatically locked.
Please open a new issue if this issue persists with any additional detail.