refactor: simplify storage adapter handler pattern (#16231)

## 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`

Author: JarrodMFlesch

packages/storage-azure/src/adapter.ts

@@ -0,0 +1,69 @@
+import type { ContainerClient } from '@azure/storage-blob'
+import type {
+  Adapter,
+  ClientUploadsConfig,
+  GeneratedAdapter,
+} from '@payloadcms/plugin-cloud-storage/types'
+
+import { deleteFile } from './deleteFile.js'
+import { generateURL } from './generateURL.js'
+import { getFile } from './getFile.js'
+import { uploadFile } from './uploadFile.js'
+
+interface CreateAzureAdapterArgs {
+  allowContainerCreate: boolean
+  baseURL: string
+  clientUploads?: ClientUploadsConfig
+  containerName: string
+  createContainerIfNotExists: () => void
+  getStorageClient: () => ContainerClient
+}
+
+export function createAzureAdapter({
+  allowContainerCreate,
+  baseURL,
+  clientUploads,
+  containerName,
+  createContainerIfNotExists,
+  getStorageClient,
+}: CreateAzureAdapterArgs): Adapter {
+  return ({ collection, prefix = '' }): GeneratedAdapter => ({
+    name: 'azure',
+    clientUploads,
+
+    generateURL: ({ filename, prefix: urlPrefix = '' }) =>
+      generateURL({ baseURL, containerName, filename, prefix: urlPrefix }),
+
+    handleDelete: ({ doc: { prefix: docPrefix = '' }, filename }) =>
+      deleteFile({ client: getStorageClient(), filename, prefix: docPrefix }),
+
+    handleUpload: async ({ data, file }) => {
+      await uploadFile({
+        buffer: file.buffer,
+        client: getStorageClient(),
+        filename: file.filename,
+        mimeType: file.mimeType,
+        prefix: data.prefix || prefix,
+        tempFilePath: file.tempFilePath,
+      })
+
+      return data
+    },
+
+    staticHandler: (
+      req,
+      { headers, params: { clientUploadContext, filename, prefix: prefixQueryParam } },
+    ) =>
+      getFile({
+        client: getStorageClient(),
+        clientUploadContext,
+        collection,
+        filename,
+        incomingHeaders: headers,
+        prefixQueryParam,
+        req,
+      }),
+
+    ...(allowContainerCreate && { onInit: createContainerIfNotExists }),
+  })
+}

packages/storage-azure/src/deleteFile.ts

@@ -0,0 +1,14 @@
+import type { ContainerClient } from '@azure/storage-blob'
+
+import path from 'path'
+
+interface DeleteArgs {
+  client: ContainerClient
+  filename: string
+  prefix: string
+}
+
+export async function deleteFile({ client, filename, prefix }: DeleteArgs): Promise<void> {
+  const blockBlobClient = client.getBlockBlobClient(path.posix.join(prefix, filename))
+  await blockBlobClient.deleteIfExists()
+}

packages/storage-azure/src/generateURL.ts

@@ -1,14 +1,12 @@
-import type { GenerateURL } from '@payloadcms/plugin-cloud-storage/types'
-
 import path from 'path'
 
-interface Args {
+interface GenerateURLArgs {
   baseURL: string
   containerName: string
+  filename: string
+  prefix: string
 }
 
-export const getGenerateURL =
-  ({ baseURL, containerName }: Args): GenerateURL =>
-  ({ filename, prefix = '' }) => {
-    return `${baseURL}/${containerName}/${path.posix.join(prefix, filename)}`
-  }
+export function generateURL({ baseURL, containerName, filename, prefix }: GenerateURLArgs): string {
+  return `${baseURL}/${containerName}/${path.posix.join(prefix, filename)}`
+}

packages/storage-azure/src/getFile.ts

@@ -0,0 +1,172 @@
+import type { BlobDownloadResponseParsed, ContainerClient } from '@azure/storage-blob'
+import type { CollectionConfig, PayloadRequest } from 'payload'
+import type { Readable } from 'stream'
+
+import { RestError } from '@azure/storage-blob'
+import { getFilePrefix } from '@payloadcms/plugin-cloud-storage/utilities'
+import path from 'path'
+import { getRangeRequestInfo } from 'payload/internal'
+import { sanitizeFilename } from 'payload/shared'
+
+interface GetFileArgs {
+  client: ContainerClient
+  clientUploadContext?: unknown
+  collection: CollectionConfig
+  filename: string
+  incomingHeaders?: Headers
+  prefixQueryParam?: string
+  req: PayloadRequest
+}
+
+const isNodeReadableStream = (
+  body: BlobDownloadResponseParsed['readableStreamBody'],
+): body is Readable => {
+  return (
+    typeof body === 'object' &&
+    body !== null &&
+    'pipe' in body &&
+    typeof body.pipe === 'function' &&
+    'destroy' in body &&
+    typeof body.destroy === 'function'
+  )
+}
+
+const abortRequestAndDestroyStream = ({
+  abortController,
+  blob,
+}: {
+  abortController: AbortController
+  blob?: BlobDownloadResponseParsed
+}) => {
+  try {
+    abortController.abort()
+  } catch {
+    /* noop */
+  }
+  if (blob?.readableStreamBody && isNodeReadableStream(blob.readableStreamBody)) {
+    blob.readableStreamBody.destroy()
+  }
+}
+
+export async function getFile({
+  client,
+  clientUploadContext,
+  collection,
+  filename,
+  incomingHeaders,
+  prefixQueryParam,
+  req,
+}: GetFileArgs): Promise<Response> {
+  let blob: BlobDownloadResponseParsed | undefined = undefined
+  let streamed = false
+
+  const abortController = new AbortController()
+  if (req.signal) {
+    req.signal.addEventListener('abort', () => {
+      abortRequestAndDestroyStream({ abortController, blob })
+    })
+  }
+
+  try {
+    const prefix = await getFilePrefix({
+      clientUploadContext,
+      collection,
+      filename,
+      prefixQueryParam,
+      req,
+    })
+    const blockBlobClient = client.getBlockBlobClient(
+      path.posix.join(prefix, sanitizeFilename(filename)),
+    )
+
+    // Get file size for range validation
+    const properties = await blockBlobClient.getProperties()
+    const fileSize = properties.contentLength
+
+    if (!fileSize) {
+      return new Response('Internal Server Error', { status: 500 })
+    }
+
+    // Handle range request
+    const rangeHeader = req.headers.get('range')
+    const rangeResult = getRangeRequestInfo({ fileSize, rangeHeader })
+
+    if (rangeResult.type === 'invalid') {
+      return new Response(null, {
+        headers: new Headers(rangeResult.headers),
+        status: rangeResult.status,
+      })
+    }
+
+    // Download with range if partial
+    blob =
+      rangeResult.type === 'partial'
+        ? await blockBlobClient.download(
+            rangeResult.rangeStart,
+            rangeResult.rangeEnd - rangeResult.rangeStart + 1,
+            { abortSignal: abortController.signal },
+          )
+        : await blockBlobClient.download(0, undefined, { abortSignal: abortController.signal })
+
+    let headers = new Headers(incomingHeaders)
+
+    // Add range-related headers from the result
+    for (const [key, value] of Object.entries(rangeResult.headers)) {
+      headers.append(key, value)
+    }
+
+    // Add Azure-specific headers
+    headers.append('Content-Type', String(properties.contentType))
+    if (properties.etag) {
+      headers.append('ETag', String(properties.etag))
+    }
+
+    // Add Content-Security-Policy header for SVG files to prevent executable code
+    if (properties.contentType === 'image/svg+xml') {
+      headers.append('Content-Security-Policy', "script-src 'none'")
+    }
+
+    const etagFromHeaders = req.headers.get('etag') || req.headers.get('if-none-match')
+
+    if (
+      collection.upload &&
+      typeof collection.upload === 'object' &&
+      typeof collection.upload.modifyResponseHeaders === 'function'
+    ) {
+      headers = collection.upload.modifyResponseHeaders({ headers }) || headers
+    }
+
+    if (etagFromHeaders && etagFromHeaders === properties.etag) {
+      return new Response(null, {
+        headers,
+        status: 304,
+      })
+    }
+
+    if (!blob.readableStreamBody || !isNodeReadableStream(blob.readableStreamBody)) {
+      return new Response('Internal Server Error', { status: 500 })
+    }
+
+    const stream = blob.readableStreamBody
+    stream.on('error', (err: Error) => {
+      req.payload.logger.error({
+        err,
+        msg: 'Error while streaming Azure blob (aborting)',
+      })
+      abortRequestAndDestroyStream({ abortController, blob })
+    })
+
+    streamed = true
+    return new Response(stream, { headers, status: rangeResult.status })
+  } catch (err: unknown) {
+    if (err instanceof RestError && err.statusCode === 404) {
+      return new Response(null, { status: 404, statusText: 'Not Found' })
+    }
+    req.payload.logger.error(err)
+    return new Response('Internal Server Error', { status: 500 })
+  } finally {
+    if (!streamed) {
+      abortRequestAndDestroyStream({ abortController, blob })
+    }
+  }
+}