perf(storage-s3): avoid getObject call if ETag matches (#15295)

### What?

Avoid unnecessary getObject call to S3 when the ETag matches.

### Why?

Range support introduced an early headObject call, which already returns
ETag and metadata; we can use that to short‑circuit with 304 and save a
fetch.

### How?

By using response headers from headObject and check ETag matching before
invoking getObject.

Added a test case for verifying 200 status when If-None-Match does not
match, and 304 status with empty body when If-None-Match is included and
matching.

---------

Co-authored-by: Paul Popus <paul@payloadcms.com>

Author: andershermansen

packages/storage-s3/src/staticHandler.ts

@@ -111,7 +111,7 @@ export const getHandler = ({
         }
       }
 
-      // Get file size first for range validation
+      // Get file size first for range validation and to set Content-Length header before streaming
       const headObject = await getStorageClient().headObject({
         Bucket: bucket,
         Key: key,
@@ -138,36 +138,25 @@ export const getHandler = ({
           ? `bytes=${rangeResult.rangeStart}-${rangeResult.rangeEnd}`
           : undefined
 
-      object = await getStorageClient().getObject(
-        {
-          Bucket: bucket,
-          Key: key,
-          Range: rangeForS3,
-        },
-        { abortSignal: abortController.signal },
-      )
-
-      if (!object.Body) {
-        return new Response(null, { status: 404, statusText: 'Not Found' })
-      }
-
       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)
       }
 
-      headers.append('Content-Type', String(object.ContentType))
-      headers.append('ETag', String(object.ETag))
+      headers.append('Content-Type', String(headObject.ContentType))
+      if (headObject.ETag) {
+        headers.append('ETag', headObject.ETag)
+      }
 
       // Add Content-Security-Policy header for SVG files to prevent executable code
-      if (object.ContentType === 'image/svg+xml') {
+      if (headObject.ContentType === 'image/svg+xml') {
         headers.append('Content-Security-Policy', "script-src 'none'")
       }
 
       const etagFromHeaders = req.headers.get('etag') || req.headers.get('if-none-match')
-      const objectEtag = object.ETag
+      const objectEtag = headObject.ETag
 
       if (
         collection.upload &&
@@ -184,6 +173,19 @@ export const getHandler = ({
         })
       }
 
+      object = await getStorageClient().getObject(
+        {
+          Bucket: bucket,
+          Key: key,
+          Range: rangeForS3,
+        },
+        { abortSignal: abortController.signal },
+      )
+
+      if (!object.Body) {
+        return new Response(null, { status: 404, statusText: 'Not Found' })
+      }
+
       if (!isNodeReadableStream(object.Body)) {
         req.payload.logger.error({
           key,

test/storage-s3/int.spec.ts

@@ -135,6 +135,36 @@ describe('@payloadcms/storage-s3', () => {
     expect(response.status).toBe(404)
   })
 
+  it('should return 304 with empty body when the ETag matches', async () => {
+    await payload.create({
+      collection: mediaWithSignedDownloadsSlug,
+      data: {},
+      filePath: path.resolve(dirname, '../uploads/temp.png'),
+    })
+
+    const response = await restClient.GET(`/${mediaWithSignedDownloadsSlug}/file/temp.png`, {
+      headers: { 'X-Disable-Signed-URL': 'true', 'If-None-Match': 'invalid-etag-1234' },
+    })
+    expect(response.status).toBe(200)
+    expect(response.headers.get('Content-Type')).toBe('image/png')
+
+    const etag = response.headers.get('ETag')
+    expect(etag).toBeDefined()
+
+    const responseNotModified = await restClient.GET(
+      `/${mediaWithSignedDownloadsSlug}/file/temp.png`,
+      {
+        headers: {
+          'X-Disable-Signed-URL': 'true',
+          'If-None-Match': etag!,
+        },
+      },
+    )
+    expect(responseNotModified.status).toBe(304)
+    const body = await responseNotModified.text()
+    expect(body).toBe('')
+  })
+
   describe('disablePayloadAccessControl', () => {
     it('should return direct S3 URL with encoded filename when uploading file with spaces', async () => {
       const upload = await payload.create({