feat: disambiguate media files by prefix via query parameter by tschwartz · Pull Request #15844 · payloadcms/payload

tschwartz · 2026-03-04T17:28:55Z

Add optional ?prefix= query string support to the existing /api/:collection/file/:filename endpoint to disambiguate files that share the same filename but have different storage prefixes.

When a storage prefix (e.g., UUID or folder path) is used to make S3 keys unique, multiple documents can share the same filename. The current endpoint resolves by filename alone, which can match the wrong document in both access control and file retrieval.

checkFileAccess accepts optional prefix and adds it to the where clause alongside existing access filters
getFile handler reads prefix from req.searchParams and threads it to checkFileAccess and handler params
getFilePrefix accepts explicitPrefix to skip the DB query when the prefix is already known from the URL
S3 staticHandler forwards prefix from params to getFilePrefix
afterRead hook appends ?prefix= to Payload-proxied URLs
Added unit tests for checkFileAccess and getFilePrefix, and integration tests for the endpoint'

Add optional `?prefix=` query string support to the existing `/api/:collection/file/:filename` endpoint to disambiguate files that share the same filename but have different storage prefixes. When a storage prefix (e.g., UUID or folder path) is used to make S3 keys unique, multiple documents can share the same `filename`. The current endpoint resolves by filename alone, which can match the wrong document in both access control and file retrieval. - `checkFileAccess` accepts optional `prefix` and adds it to the `where` clause alongside existing access filters - `getFile` handler reads `prefix` from `req.searchParams` and threads it to `checkFileAccess` and handler `params` - `getFilePrefix` accepts `explicitPrefix` to skip the DB query when the prefix is already known from the URL - S3 `staticHandler` forwards `prefix` from params to `getFilePrefix` - `afterRead` hook appends `?prefix=` to Payload-proxied URLs - Added unit tests for `checkFileAccess` and `getFilePrefix`, and integration tests for the endpoint'

When a media URL already contains query parameters, appending the imageCacheTag with '?' produces a malformed URL with double '?'. Check for existing query parameters and use '&' as the separator when needed, matching the pattern already used in the Thumbnail component.

GermanJablo

One minor note (non-blocking)

Only the S3 storage adapter is updated. Other storage adapters (Azure, GCS, Vercel Blob, etc.) aren't changed. This is fine since the core changes (checkFileAccess, getFile) work independently. Other adapters can be updated separately.

Update storage-vercel-blob, storage-azure, storage-gcs, and storage-r2 static handlers to destructure `prefix` from params and pass it to `getFilePrefix` as `explicitPrefix`, matching the pattern established in the S3 adapter. This avoids an unnecessary DB query when the prefix is already known from the `?prefix=` URL query parameter. - storage-vercel-blob: add `prefix: explicitPrefix` to params and `getFilePrefix` call - storage-azure: same - storage-gcs: same - storage-r2: import `getFilePrefix`, replace static prefix arg with dynamic lookup, fall back to constructor default - Update URL assertions in storage-azure, storage-s3, and plugin-cloud-storage integration tests to expect `?prefix=` query parameter on prefix-enabled collection URLs

Add optional `?prefix=` query string support to the existing `/api/:collection/file/:filename` endpoint to disambiguate files that share the same filename but have different storage prefixes. When a storage prefix (e.g., UUID or folder path) is used to make S3 keys unique, multiple documents can share the same `filename`. The current endpoint resolves by filename alone, which can match the wrong document in both access control and file retrieval. - `checkFileAccess` accepts optional `prefix` and adds it to the `where` clause alongside existing access filters - `getFile` handler reads `prefix` from `req.searchParams` and threads it to `checkFileAccess` and handler `params` - `getFilePrefix` accepts `explicitPrefix` to skip the DB query when the prefix is already known from the URL - S3 `staticHandler` forwards `prefix` from params to `getFilePrefix` - `afterRead` hook appends `?prefix=` to Payload-proxied URLs - Added unit tests for `checkFileAccess` and `getFilePrefix`, and integration tests for the endpoint'

When a media URL already contains query parameters, appending the imageCacheTag with '?' produces a malformed URL with double '?'. Check for existing query parameters and use '&' as the separator when needed, matching the pattern already used in the Thumbnail component.

Update storage-vercel-blob, storage-azure, storage-gcs, and storage-r2 static handlers to destructure `prefix` from params and pass it to `getFilePrefix` as `explicitPrefix`, matching the pattern established in the S3 adapter. This avoids an unnecessary DB query when the prefix is already known from the `?prefix=` URL query parameter. - storage-vercel-blob: add `prefix: explicitPrefix` to params and `getFilePrefix` call - storage-azure: same - storage-gcs: same - storage-r2: import `getFilePrefix`, replace static prefix arg with dynamic lookup, fall back to constructor default - Update URL assertions in storage-azure, storage-s3, and plugin-cloud-storage integration tests to expect `?prefix=` query parameter on prefix-enabled collection URLs

…into media-endpoint

github-actions · 2026-04-08T16:08:17Z

🚀 This is included in version v3.82.0

## Summary - Replace factory function pattern (`getHandleUpload`, `getHandleDelete`, etc.) with simple helper functions - Create `adapter.ts` in each storage package that maps the plugin interface to the helpers - Fix R2 prefix bug: use OR logic (`filePrefix || prefix`) to match `handleUpload` behavior - Remove redundant `async/await` on pass-through handlers I think this approach makes it easier to trace backwards to the cloud-storage plugin the arguments that are actually passed into the adapter methods. ## Changes **Pattern change (all 6 storage adapters):** Before (factory functions): ```typescript export const getHandleDelete = ({ bucket }: Args): HandleDelete => { return async ({ doc: { prefix = '' }, filename }) => { await bucket.delete(path.posix.join(prefix, filename)) } } ``` After (simple functions + adapter mapping): ```typescript // handleDelete.ts export async function deleteFile({ bucket, prefix, filename }: DeleteArgs): Promise<void> { await bucket.delete(path.posix.join(prefix, filename)) } // adapter.ts export function createR2Adapter({ bucket, clientUploads }: CreateR2AdapterArgs): Adapter { return ({ collection, prefix = '' }): GeneratedAdapter => ({ name: 'r2', clientUploads, handleDelete: ({ doc: { prefix: docPrefix = '' }, filename }) => deleteFile({ bucket, filename, prefix: docPrefix }), handleUpload: ({ data, file }) => uploadFile({ bucket, buffer: file.buffer, filename: file.filename, mimeType: file.mimeType, prefix: data.prefix || prefix, }), staticHandler: ( req, { headers, params: { clientUploadContext, filename, prefix: prefixQueryParam } }, ) => getFile({ bucket, clientUploadContext, collection, filename, incomingHeaders: headers, prefix, prefixQueryParam, req, }), }) } ``` **Bug fix (storage-r2):** The prefix query param feature (#15844) introduced inconsistent logic in R2: - `handleUpload`: uses `data.prefix || prefix` (OR logic) - `staticHandler`: was using `prefix + filePrefix` (AND logic) Fixed to use consistent OR logic: `filePrefix || prefix` ## Packages affected - `@payloadcms/storage-r2` - `@payloadcms/storage-s3` - `@payloadcms/storage-gcs` - `@payloadcms/storage-azure` - `@payloadcms/storage-vercel-blob` - `@payloadcms/storage-uploadthing`

jasperkennis · 2026-04-14T12:26:12Z

This diff caused me some trouble. Our app transforms the returned media path without checking for query params, to point to dirs where our m3u8 files live. Due to there suddenly being a query param in the url it breaks.

I've had to revert a deploy and am now checking how to unset the query param without disabling the rest of the prefix logic.

…cms#15844) Add optional `?prefix=` query string support to the existing `/api/:collection/file/:filename` endpoint to disambiguate files that share the same filename but have different storage prefixes. When a storage prefix (e.g., UUID or folder path) is used to make S3 keys unique, multiple documents can share the same `filename`. The current endpoint resolves by filename alone, which can match the wrong document in both access control and file retrieval. - `checkFileAccess` accepts optional `prefix` and adds it to the `where` clause alongside existing access filters - `getFile` handler reads `prefix` from `req.searchParams` and threads it to `checkFileAccess` and handler `params` - `getFilePrefix` accepts `explicitPrefix` to skip the DB query when the prefix is already known from the URL - S3 `staticHandler` forwards `prefix` from params to `getFilePrefix` - `afterRead` hook appends `?prefix=` to Payload-proxied URLs - Added unit tests for `checkFileAccess` and `getFilePrefix`, and integration tests for the endpoint' --------- Co-authored-by: Jarrod Flesch <jarrodmflesch@gmail.com>

## Summary - Replace factory function pattern (`getHandleUpload`, `getHandleDelete`, etc.) with simple helper functions - Create `adapter.ts` in each storage package that maps the plugin interface to the helpers - Fix R2 prefix bug: use OR logic (`filePrefix || prefix`) to match `handleUpload` behavior - Remove redundant `async/await` on pass-through handlers I think this approach makes it easier to trace backwards to the cloud-storage plugin the arguments that are actually passed into the adapter methods. ## Changes **Pattern change (all 6 storage adapters):** Before (factory functions): ```typescript export const getHandleDelete = ({ bucket }: Args): HandleDelete => { return async ({ doc: { prefix = '' }, filename }) => { await bucket.delete(path.posix.join(prefix, filename)) } } ``` After (simple functions + adapter mapping): ```typescript // handleDelete.ts export async function deleteFile({ bucket, prefix, filename }: DeleteArgs): Promise<void> { await bucket.delete(path.posix.join(prefix, filename)) } // adapter.ts export function createR2Adapter({ bucket, clientUploads }: CreateR2AdapterArgs): Adapter { return ({ collection, prefix = '' }): GeneratedAdapter => ({ name: 'r2', clientUploads, handleDelete: ({ doc: { prefix: docPrefix = '' }, filename }) => deleteFile({ bucket, filename, prefix: docPrefix }), handleUpload: ({ data, file }) => uploadFile({ bucket, buffer: file.buffer, filename: file.filename, mimeType: file.mimeType, prefix: data.prefix || prefix, }), staticHandler: ( req, { headers, params: { clientUploadContext, filename, prefix: prefixQueryParam } }, ) => getFile({ bucket, clientUploadContext, collection, filename, incomingHeaders: headers, prefix, prefixQueryParam, req, }), }) } ``` **Bug fix (storage-r2):** The prefix query param feature (payloadcms#15844) introduced inconsistent logic in R2: - `handleUpload`: uses `data.prefix || prefix` (OR logic) - `staticHandler`: was using `prefix + filePrefix` (AND logic) Fixed to use consistent OR logic: `filePrefix || prefix` ## Packages affected - `@payloadcms/storage-r2` - `@payloadcms/storage-s3` - `@payloadcms/storage-gcs` - `@payloadcms/storage-azure` - `@payloadcms/storage-vercel-blob` - `@payloadcms/storage-uploadthing`

tschwartz requested a review from denolfe as a code owner March 4, 2026 17:28

tschwartz commented Mar 4, 2026

View reviewed changes

Comment thread packages/storage-s3/src/staticHandler.ts

Comment thread test/uploads/config.ts

tschwartz force-pushed the media-endpoint branch from 56ba0eb to 170b95e Compare March 7, 2026 01:07

tschwartz requested review from AlessioGr, JarrodMFlesch and jacobsfletch as code owners March 9, 2026 17:17

tschwartz force-pushed the media-endpoint branch from a0c9916 to de5df42 Compare March 10, 2026 16:43

GermanJablo previously approved these changes Mar 10, 2026

View reviewed changes

chore: regenerate uploads test types for prefix-media collection

8ad2148

tschwartz dismissed GermanJablo’s stale review via 8ad2148 March 31, 2026 12:39

fix: check prefix even when access returns boolean true

3a43806

JarrodMFlesch self-assigned this Mar 31, 2026

tschwartz added 6 commits April 7, 2026 08:57

chore: regenerate uploads test types for prefix-media collection

457b6bc

fix: check prefix even when access returns boolean true

cd8ec69

tschwartz force-pushed the media-endpoint branch from ec48dd0 to 1a04aef Compare April 7, 2026 16:50

JarrodMFlesch reviewed Apr 7, 2026

View reviewed changes

Comment thread packages/storage-r2/src/staticHandler.ts Outdated

JarrodMFlesch added 6 commits April 7, 2026 13:47

Merge remote-tracking branch 'origin' into media-endpoint

27f6283

Merge remote-tracking branch 'refs/remotes/tschwartz/media-endpoint' …

fa49d39

…into media-endpoint

adjust s3 handler

89cf2d4

adjust tests

1751196

updates getFilePrefix logic

8fa2e1b

chore: fix vercel-blob test to expect prefix query param

ebe24c2

DanRibbens approved these changes Apr 7, 2026

View reviewed changes

DanRibbens merged commit 05ddec1 into payloadcms:main Apr 7, 2026
312 of 314 checks passed

JarrodMFlesch mentioned this pull request Apr 9, 2026

refactor: simplify storage adapter handler pattern #16231

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: disambiguate media files by prefix via query parameter#15844

feat: disambiguate media files by prefix via query parameter#15844
DanRibbens merged 16 commits intopayloadcms:mainfrom
tschwartz:media-endpoint

tschwartz commented Mar 4, 2026

Uh oh!

Uh oh!

Uh oh!

GermanJablo left a comment

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Apr 8, 2026

Uh oh!

jasperkennis commented Apr 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

tschwartz commented Mar 4, 2026

Uh oh!

Uh oh!

Uh oh!

GermanJablo left a comment

Choose a reason for hiding this comment

One minor note (non-blocking)

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Apr 8, 2026

Uh oh!

jasperkennis commented Apr 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants