fix(storage-*): upload filename respects prefix (#14566)

## Overview

Fixes filename collision detection to respect storage adapter
prefix/suffix patterns. When using cloud storage with prefixes (e.g.,
multi-tenant scenarios), files with identical names under different
prefixes were incorrectly
  triggering deduplication.

Resolves #14561 

  ## Changes

  ### Core Upload Logic
- **`docWithFilenameExists`**: Now accepts and checks `prefix` parameter
in WHERE clause, scoping collision detection to prefix namespace
- **`getSafeFileName`**: Accepts `prefix` parameter and passes to
collision check
- **`generateFileData`**: Extracts `prefix` from data (set by storage
plugins) and threads through to collision detection

  ### Test Coverage
- **New collection `MediaWithDynamicPrefix`**: Tests multi-tenant
scenario with hook-based prefix assignment
- **Updated `MediaWithPrefix`**: Added `prefix` field and
`filenameCompoundIndex: true`
- **Comprehensive test suite**: Validates collision within prefix, no
collision across prefixes, backward compatibility for collections
without prefix, and dynamic prefix from hooks

Author: denolfe

packages/payload/src/uploads/docWithFilenameExists.ts

@@ -1,29 +1,34 @@
-import type { PayloadRequest } from '../types/index.js'
+import type { PayloadRequest, Where } from '../types/index.js'
 
 type Args = {
   collectionSlug: string
   filename: string
   path: string
+  prefix?: string
   req: PayloadRequest
 }
 
 export const docWithFilenameExists = async ({
   collectionSlug,
   filename,
+  prefix,
   req,
 }: Args): Promise<boolean> => {
+  const where: Where = {
+    filename: {
+      equals: filename,
+    },
+  }
+
+  if (prefix) {
+    where.prefix = { equals: prefix }
+  }
+
   const doc = await req.payload.db.findOne({
     collection: collectionSlug,
     req,
-    where: {
-      filename: {
-        equals: filename,
-      },
-    },
+    where,
   })
-  if (doc) {
-    return true
-  }
 
-  return false
+  return !!doc
 }

packages/payload/src/uploads/generateFileData.ts

@@ -255,9 +255,12 @@ export const generateFileData = async <T>({
     fsSafeName = `${baseFilename}${ext ? `.${ext}` : ''}`
 
     if (!overwriteExistingFiles) {
+      // Extract prefix if present (added by plugin-cloud-storage)
+      const prefix = (data as Record<string, unknown>)?.prefix as string | undefined
       fsSafeName = await getSafeFileName({
         collectionSlug: collectionConfig.slug,
         desiredFilename: fsSafeName,
+        prefix,
         req,
         staticPath: staticPath!,
       })

packages/payload/src/uploads/getSafeFilename.ts

@@ -25,13 +25,15 @@ const incrementName = (name: string) => {
 type Args = {
   collectionSlug: string
   desiredFilename: string
+  prefix?: string
   req: PayloadRequest
   staticPath: string
 }
 
 export async function getSafeFileName({
   collectionSlug,
   desiredFilename,
+  prefix,
   req,
   staticPath,
 }: Args): Promise<string> {
@@ -42,6 +44,7 @@ export async function getSafeFileName({
       collectionSlug,
       filename: modifiedFilename,
       path: staticPath,
+      prefix,
       req,
     })) ||
     (await fileExists(`${staticPath}/${modifiedFilename}`))

test/storage-s3/collections/MediaWithDynamicPrefix.ts

@@ -0,0 +1,36 @@
+import type { CollectionConfig } from 'payload'
+
+export const MediaWithDynamicPrefix: CollectionConfig<'media-with-dynamic-prefix'> = {
+  slug: 'media-with-dynamic-prefix',
+  fields: [
+    {
+      name: 'tenant',
+      type: 'text',
+      required: true,
+    },
+    {
+      name: 'prefix',
+      type: 'text',
+    },
+  ],
+  hooks: {
+    beforeOperation: [
+      ({ args, operation }) => {
+        if (operation === 'create') {
+          return {
+            ...args,
+            data: {
+              ...args.data,
+              prefix: `tenant-${args.data.tenant}`,
+            },
+          }
+        }
+        return args
+      },
+    ],
+  },
+  upload: {
+    disableLocalStorage: false,
+    filenameCompoundIndex: ['filename', 'prefix'],
+  },
+}

test/storage-s3/collections/MediaWithPrefix.ts

@@ -4,6 +4,12 @@ export const MediaWithPrefix: CollectionConfig = {
   slug: 'media-with-prefix',
   upload: {
     disableLocalStorage: false,
+    filenameCompoundIndex: ['filename', 'prefix'],
   },
-  fields: [],
+  fields: [
+    {
+      name: 'prefix',
+      type: 'text',
+    },
+  ],
 }

test/storage-s3/config.ts

@@ -6,10 +6,17 @@ import path from 'path'
 import { buildConfigWithDefaults } from '../buildConfigWithDefaults.js'
 import { devUser } from '../credentials.js'
 import { Media } from './collections/Media.js'
+import { MediaWithDynamicPrefix } from './collections/MediaWithDynamicPrefix.js'
 import { MediaWithPrefix } from './collections/MediaWithPrefix.js'
 import { MediaWithSignedDownloads } from './collections/MediaWithSignedDownloads.js'
 import { Users } from './collections/Users.js'
-import { mediaSlug, mediaWithPrefixSlug, mediaWithSignedDownloadsSlug, prefix } from './shared.js'
+import {
+  mediaSlug,
+  mediaWithDynamicPrefixSlug,
+  mediaWithPrefixSlug,
+  mediaWithSignedDownloadsSlug,
+  prefix,
+} from './shared.js'
 const filename = fileURLToPath(import.meta.url)
 const dirname = path.dirname(filename)
 
@@ -26,7 +33,7 @@ export default buildConfigWithDefaults({
       baseDir: path.resolve(dirname),
     },
   },
-  collections: [Media, MediaWithPrefix, MediaWithSignedDownloads, Users],
+  collections: [Media, MediaWithDynamicPrefix, MediaWithPrefix, MediaWithSignedDownloads, Users],
   onInit: async (payload) => {
     await payload.create({
       collection: 'users',
@@ -40,6 +47,7 @@ export default buildConfigWithDefaults({
     s3Storage({
       collections: {
         [mediaSlug]: true,
+        [mediaWithDynamicPrefixSlug]: true,
         [mediaWithPrefixSlug]: {
           prefix,
         },

test/storage-s3/int.spec.ts

@@ -1,4 +1,4 @@
-import type { Payload } from 'payload'
+import type { CollectionSlug, Payload } from 'payload'
 
 import * as AWS from '@aws-sdk/client-s3'
 import path from 'path'
@@ -7,7 +7,13 @@ import { fileURLToPath } from 'url'
 import type { NextRESTClient } from '../helpers/NextRESTClient.js'
 
 import { initPayloadInt } from '../helpers/initPayloadInt.js'
-import { mediaSlug, mediaWithPrefixSlug, mediaWithSignedDownloadsSlug, prefix } from './shared.js'
+import {
+  mediaSlug,
+  mediaWithDynamicPrefixSlug,
+  mediaWithPrefixSlug,
+  mediaWithSignedDownloadsSlug,
+  prefix,
+} from './shared.js'
 
 const filename = fileURLToPath(import.meta.url)
 const dirname = path.dirname(filename)
@@ -22,15 +28,15 @@ describe('@payloadcms/storage-s3', () => {
 
   beforeAll(async () => {
     ;({ payload, restClient } = await initPayloadInt(dirname))
-    TEST_BUCKET = process.env.S3_BUCKET
+    TEST_BUCKET = process.env.S3_BUCKET!
 
     client = new AWS.S3({
-      endpoint: process.env.S3_ENDPOINT,
+      endpoint: process.env.S3_ENDPOINT!,
       forcePathStyle: process.env.S3_FORCE_PATH_STYLE === 'true',
-      region: process.env.S3_REGION,
+      region: process.env.S3_REGION!,
       credentials: {
-        accessKeyId: process.env.S3_ACCESS_KEY_ID,
-        secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
+        accessKeyId: process.env.S3_ACCESS_KEY_ID!,
+        secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
       },
     })
 
@@ -119,6 +125,117 @@ describe('@payloadcms/storage-s3', () => {
     it.todo('can upload')
   })
 
+  describe('prefix collision detection', () => {
+    beforeEach(async () => {
+      // Clear S3 bucket before each test
+      await clearTestBucket()
+      // Clear database records before each test
+      await payload.delete({
+        collection: mediaWithPrefixSlug,
+        where: {},
+      })
+      await payload.delete({
+        collection: mediaSlug,
+        where: {},
+      })
+    })
+
+    it('detects collision within same prefix', async () => {
+      const imageFile = path.resolve(dirname, '../uploads/image.png')
+
+      // Upload twice with same prefix
+      const upload1 = await payload.create({
+        collection: mediaWithPrefixSlug,
+        data: {},
+        filePath: imageFile,
+      })
+
+      const upload2 = await payload.create({
+        collection: mediaWithPrefixSlug,
+        data: {},
+        filePath: imageFile,
+      })
+
+      expect(upload1.filename).toBe('image.png')
+      expect(upload2.filename).toBe('image-1.png')
+      expect(upload1.prefix).toBe(prefix)
+      expect(upload2.prefix).toBe(prefix)
+    })
+
+    it('works normally for collections without prefix', async () => {
+      const imageFile = path.resolve(dirname, '../uploads/image.png')
+
+      // Upload twice to collection without prefix
+      const upload1 = await payload.create({
+        collection: mediaSlug,
+        data: {},
+        filePath: imageFile,
+      })
+
+      const upload2 = await payload.create({
+        collection: mediaSlug,
+        data: {},
+        filePath: imageFile,
+      })
+
+      expect(upload1.filename).toBe('image.png')
+      expect(upload2.filename).toBe('image-1.png')
+      // @ts-expect-error prefix should never be set
+      expect(upload1.prefix).toBeUndefined()
+      // @ts-expect-error prefix should never be set
+      expect(upload2.prefix).toBeUndefined()
+    })
+
+    it('allows same filename under different prefixes', async () => {
+      const imageFile = path.resolve(dirname, '../uploads/image.png')
+
+      // Upload with default prefix from config ('test-prefix')
+      const upload1 = await payload.create({
+        collection: mediaWithPrefixSlug,
+        data: {},
+        filePath: imageFile,
+      })
+
+      // Upload with different prefix
+      const upload2 = await payload.create({
+        collection: mediaWithPrefixSlug,
+        data: {
+          prefix: 'different-prefix',
+        },
+        filePath: imageFile,
+      })
+
+      expect(upload1.filename).toBe('image.png')
+      expect(upload2.filename).toBe('image.png') // Should NOT increment
+      expect(upload1.prefix).toBe(prefix) // 'test-prefix'
+      expect(upload2.prefix).toBe('different-prefix')
+    })
+
+    it('supports multi-tenant scenario with dynamic prefix from hook', async () => {
+      const imageFile = path.resolve(dirname, '../uploads/image.png')
+
+      // Tenant A uploads logo.png
+      const tenantAUpload = await payload.create({
+        collection: mediaWithDynamicPrefixSlug,
+        data: { tenant: 'a' },
+        filePath: imageFile,
+      })
+
+      // Tenant B uploads logo.png
+      const tenantBUpload = await payload.create({
+        collection: mediaWithDynamicPrefixSlug,
+        data: { tenant: 'b' },
+        filePath: imageFile,
+      })
+
+      // Both should keep original filename
+      expect(tenantAUpload.filename).toBe('image.png')
+      expect(tenantBUpload.filename).toBe('image.png')
+      expect(tenantAUpload.prefix).toBe('tenant-a')
+      expect(tenantBUpload.prefix).toBe('tenant-b')
+    })
+  })
+
   async function createTestBucket() {
     try {
       const makeBucketRes = await client.send(new AWS.CreateBucketCommand({ Bucket: TEST_BUCKET }))
@@ -144,15 +261,11 @@ describe('@payloadcms/storage-s3', () => {
       return
     }
 
-    const deleteParams = {
+    const deleteParams: AWS.DeleteObjectsCommandInput = {
       Bucket: TEST_BUCKET,
-      Delete: { Objects: [] },
+      Delete: { Objects: listedObjects.Contents.map(({ Key }) => ({ Key })) },
     }
 
-    listedObjects.Contents.forEach(({ Key }) => {
-      deleteParams.Delete.Objects.push({ Key })
-    })
-
     const deleteResult = await client.send(new AWS.DeleteObjectsCommand(deleteParams))
     if (deleteResult.Errors?.length) {
       throw new Error(JSON.stringify(deleteResult.Errors))
@@ -169,12 +282,12 @@ describe('@payloadcms/storage-s3', () => {
     uploadId: number | string
   }) {
     const uploadData = (await payload.findByID({
-      collection: collectionSlug,
+      collection: collectionSlug as CollectionSlug,
       id: uploadId,
     })) as unknown as { filename: string; sizes: Record<string, { filename: string }> }
 
     const fileKeys = Object.keys(uploadData.sizes || {}).map((key) => {
-      const rawFilename = uploadData.sizes[key].filename
+      const rawFilename = uploadData?.sizes?.[key]?.filename
       return prefix ? `${prefix}/${rawFilename}` : rawFilename
     })