feat: add the ability to pass in a response to upload handlers (#6926)

Adds the ability to set response headers by using a new
`uploads.modifyResponseHeaders` property. You could previously do this
in Express in Payload v2.

You can do this like so:

```ts
upload: {
  modifyResponseHeaders: ({ headers }) => {
    headers.set('Cache-Control', 'public, max-age=86400')
    return headers
  }
},
```

Author: JarrodMFlesch

packages/next/src/routes/rest/files/getFile.ts

@@ -35,10 +35,10 @@ export const getFile = async ({ collection, filename, req }: Args): Promise<Resp
 
     if (accessResult instanceof Response) return accessResult
 
-    let response: Response = null
     if (collection.config.upload.handlers?.length) {
+      let customResponse = null
       for (const handler of collection.config.upload.handlers) {
-        response = await handler(req, {
+        customResponse = await handler(req, {
           doc: accessResult,
           params: {
             collection: collection.config.slug,
@@ -47,21 +47,21 @@ export const getFile = async ({ collection, filename, req }: Args): Promise<Resp
         })
       }
 
-      if (response instanceof Response) return response
+      if (customResponse instanceof Response) return customResponse
     }
 
     const fileDir = collection.config.upload?.staticDir || collection.config.slug
     const filePath = path.resolve(`${fileDir}/${filename}`)
-
     const stats = await fsPromises.stat(filePath)
-
     const data = streamFile(filePath)
-
-    const headers = new Headers(req.headers)
-    headers.set('Content-Length', stats.size + '')
-
     const fileTypeResult = (await fileTypeFromFile(filePath)) || getFileTypeFallback(filePath)
+
+    let headers = new Headers()
     headers.set('Content-Type', fileTypeResult.mime)
+    headers.set('Content-Length', stats.size + '')
+    headers = collection.config.upload?.modifyResponseHeaders
+      ? collection.config.upload.modifyResponseHeaders({ headers })
+      : headers
 
     return new Response(data, {
       headers: headersWithCors({

packages/payload/src/collections/config/schema.ts

@@ -180,6 +180,7 @@ const collectionSchema = joi.object().keys({
           .unknown(),
       ),
       mimeTypes: joi.array().items(joi.string()),
+      modifyResponseHeaders: joi.func(),
       resizeOptions: joi
         .object()
         .keys({

packages/payload/src/uploads/types.ts

@@ -124,15 +124,23 @@ export type UploadConfig = {
    */
   handlers?: ((
     req: PayloadRequestWithData,
-    args: { doc: TypeWithID; params: { collection: string; filename: string } },
-  ) => Promise<Response> | Response | null)[]
+    args: {
+      doc: TypeWithID
+      params: { collection: string; filename: string }
+    },
+  ) => Promise<Response> | Promise<void> | Response | void)[]
   imageSizes?: ImageSize[]
   /**
    * Restrict mimeTypes in the file picker. Array of valid mime types or mimetype wildcards
    * @example ['image/*', 'application/pdf']
    * @default undefined
    */
   mimeTypes?: string[]
+  /**
+   * Ability to modify the response headers fetching a file.
+   * @default undefined
+   */
+  modifyResponseHeaders?: ({ headers }: { headers: Headers }) => Headers
   /**
    * Sharp resize options for the original image.
    * @link https://sharp.pixelplumbing.com/api-resize#resize

packages/plugin-cloud/src/types.ts

@@ -41,7 +41,7 @@ export type GenerateURL = (args: {
 export type StaticHandler = (
   req: PayloadRequestWithData,
   args: { params: { collection: string; filename: string } },
-) => Promise<Response> | Response
+) => Promise<Response> | Promise<void> | Response | void
 
 export interface PayloadCloudEmailOptions {
   apiKey: string