fix: missing range headers (#14887)

## Summary

Adds HTTP Range request support (RFC 7233) to Payload's core file
serving, enabling video streaming with scrubbing/seeking capabilities in
browsers.

## Changes

- **Added `Accept-Ranges: bytes` header** to all file responses
- **Created `parseRangeHeader` utility** for parsing Range headers using
`range-parser` package
- **Enhanced `streamFile` function** to support byte range streaming via
`fs.createReadStream` options
- **Added integration tests** covering various range request scenarios

## Technical Details

- Uses `range-parser` library for RFC 7233 compliant parsing
  - Supports single byte ranges (e.g., `bytes=0-1023`)
  - Handles open-ended ranges (e.g., `bytes=1024-`)
  - Handles suffix ranges (e.g., `bytes=-512`)
- Multi-range requests return first range only (standard simplification)

## Testing

Added comprehensive integration test suite covering:
- Full file requests with Accept-Ranges header
- Partial content requests (206 responses)
- Invalid range handling (416 responses)
- Response body size verification
- Edge cases (out-of-bounds, malformed headers)


### Before


https://github.com/user-attachments/assets/065060ae-35db-4c3d-bc72-cfb976b57349

### After


https://github.com/user-attachments/assets/b70caa49-e055-47b2-87f8-31f02a42c86a

Author: JarrodMFlesch

packages/payload/package.json

@@ -114,6 +114,7 @@
     "pino-pretty": "13.1.2",
     "pluralize": "8.0.0",
     "qs-esm": "7.0.2",
+    "range-parser": "1.2.1",
     "sanitize-filename": "1.6.3",
     "scmp": "2.1.0",
     "ts-essentials": "10.0.3",
@@ -130,6 +131,7 @@
     "@types/minimist": "1.2.2",
     "@types/nodemailer": "7.0.2",
     "@types/pluralize": "0.0.33",
+    "@types/range-parser": "1.2.7",
     "@types/uuid": "10.0.0",
     "@types/ws": "^8.5.10",
     "copyfiles": "2.4.1",

packages/payload/src/uploads/endpoints/getFile.ts

@@ -11,6 +11,7 @@ import { APIError } from '../../errors/APIError.js'
 import { checkFileAccess } from '../../uploads/checkFileAccess.js'
 import { streamFile } from '../../uploads/fetchAPI-stream-file/index.js'
 import { getFileTypeFallback } from '../../uploads/getFileTypeFallback.js'
+import { parseRangeHeader } from '../../uploads/parseRangeHeader.js'
 import { getRequestCollection } from '../../utilities/getRequestEntity.js'
 import { headersWithCors } from '../../utilities/headersWithCors.js'
 
@@ -94,17 +95,57 @@ export const getFileHandler: PayloadHandler = async (req) => {
     throw err
   }
 
-  const data = streamFile(filePath)
   const fileTypeResult = (await fileTypeFromFile(filePath)) || getFileTypeFallback(filePath)
   let mimeType = fileTypeResult.mime
 
   if (filePath.endsWith('.svg') && fileTypeResult.mime === 'application/xml') {
     mimeType = 'image/svg+xml'
   }
 
+  // Parse Range header for byte range requests
+  const rangeHeader = req.headers.get('range')
+  const rangeResult = parseRangeHeader({
+    fileSize: stats.size,
+    rangeHeader,
+  })
+
+  if (rangeResult.type === 'invalid') {
+    let headers = new Headers()
+    headers.set('Content-Range', `bytes */${stats.size}`)
+    headers = collection.config.upload?.modifyResponseHeaders
+      ? collection.config.upload.modifyResponseHeaders({ headers }) || headers
+      : headers
+
+    return new Response(null, {
+      headers: headersWithCors({
+        headers,
+        req,
+      }),
+      status: httpStatus.REQUESTED_RANGE_NOT_SATISFIABLE,
+    })
+  }
+
   let headers = new Headers()
   headers.set('Content-Type', mimeType)
-  headers.set('Content-Length', stats.size + '')
+  headers.set('Accept-Ranges', 'bytes')
+
+  let data: ReadableStream
+  let status: number
+  const isPartial = rangeResult.type === 'partial'
+  const range = rangeResult.range
+
+  if (isPartial && range) {
+    const contentLength = range.end - range.start + 1
+    headers.set('Content-Length', String(contentLength))
+    headers.set('Content-Range', `bytes ${range.start}-${range.end}/${stats.size}`)
+    data = streamFile({ filePath, options: { end: range.end, start: range.start } })
+    status = httpStatus.PARTIAL_CONTENT
+  } else {
+    headers.set('Content-Length', String(stats.size))
+    data = streamFile({ filePath })
+    status = httpStatus.OK
+  }
+
   headers = collection.config.upload?.modifyResponseHeaders
     ? collection.config.upload.modifyResponseHeaders({ headers }) || headers
     : headers
@@ -114,6 +155,6 @@ export const getFileHandler: PayloadHandler = async (req) => {
       headers,
       req,
     }),
-    status: httpStatus.OK,
+    status,
   })
 }

packages/payload/src/uploads/fetchAPI-stream-file/index.ts

@@ -19,8 +19,14 @@ export async function* nodeStreamToIterator(stream: fs.ReadStream) {
   }
 }
 
-export function streamFile(path: string): ReadableStream {
-  const nodeStream = fs.createReadStream(path)
+export function streamFile({
+  filePath,
+  options,
+}: {
+  filePath: string
+  options?: { end?: number; start?: number }
+}): ReadableStream {
+  const nodeStream = fs.createReadStream(filePath, options)
   const data: ReadableStream = iteratorToStream(nodeStreamToIterator(nodeStream))
   return data
 }

packages/payload/src/uploads/parseRangeHeader.ts

@@ -0,0 +1,60 @@
+import parseRange from 'range-parser'
+
+export type ByteRange = {
+  end: number
+  start: number
+}
+
+export type ParseRangeResult =
+  | { range: ByteRange; type: 'partial' }
+  | { range: null; type: 'full' }
+  | { range: null; type: 'invalid' }
+
+/**
+ * Parses HTTP Range header according to RFC 7233
+ *
+ * @returns Result object indicating whether to serve full file, partial content, or invalid range
+ */
+export function parseRangeHeader({
+  fileSize,
+  rangeHeader,
+}: {
+  fileSize: number
+  rangeHeader: null | string
+}): ParseRangeResult {
+  // No Range header - serve full file
+  if (!rangeHeader) {
+    return { type: 'full', range: null }
+  }
+
+  const result = parseRange(fileSize, rangeHeader)
+
+  // Invalid range syntax or unsatisfiable range
+  if (result === -1 || result === -2) {
+    return { type: 'invalid', range: null }
+  }
+
+  // Must be bytes range type
+  if (result.type !== 'bytes') {
+    return { type: 'invalid', range: null }
+  }
+
+  // Multi-range requests: use first range only (standard simplification)
+  if (result.length === 0) {
+    return { type: 'invalid', range: null }
+  }
+
+  const range = result[0]
+
+  if (range) {
+    return {
+      type: 'partial',
+      range: {
+        end: range.end,
+        start: range.start,
+      },
+    }
+  }
+
+  return { type: 'invalid', range: null }
+}

pnpm-lock.yaml

@@ -1285,6 +1285,116 @@ describe('Collections - Uploads', () => {
       expect(await fileExists(path.join(expectedPath, duplicatedDoc.filename))).toBe(true)
     })
   })
+
+  describe('HTTP Range Requests', () => {
+    let uploadedDoc: Media
+    let uploadedFilename: string
+    let fileSize: number
+
+    beforeAll(async () => {
+      // Upload a test file for range request testing
+      const filePath = path.join(dirname, './audio.mp3')
+      const file = await getFileByPath(filePath)
+
+      uploadedDoc = (await payload.create({
+        collection: mediaSlug,
+        data: {},
+        file,
+      })) as unknown as Media
+
+      uploadedFilename = uploadedDoc.filename
+      const stats = await stat(filePath)
+      fileSize = stats.size
+    })
+
+    it('should return Accept-Ranges header on full file request', async () => {
+      const response = await restClient.GET(`/${mediaSlug}/file/${uploadedFilename}`)
+
+      expect(response.status).toBe(200)
+      expect(response.headers.get('Accept-Ranges')).toBe('bytes')
+      expect(response.headers.get('Content-Length')).toBe(String(fileSize))
+    })
+
+    it('should handle range request with single byte range', async () => {
+      const response = await restClient.GET(`/${mediaSlug}/file/${uploadedFilename}`, {
+        headers: { Range: 'bytes=0-1023' },
+      })
+
+      expect(response.status).toBe(206)
+      expect(response.headers.get('Content-Range')).toBe(`bytes 0-1023/${fileSize}`)
+      expect(response.headers.get('Content-Length')).toBe('1024')
+      expect(response.headers.get('Accept-Ranges')).toBe('bytes')
+
+      const arrayBuffer = await response.arrayBuffer()
+      expect(arrayBuffer.byteLength).toBe(1024)
+    })
+
+    it('should handle range request with open-ended range', async () => {
+      const response = await restClient.GET(`/${mediaSlug}/file/${uploadedFilename}`, {
+        headers: { Range: 'bytes=1024-' },
+      })
+
+      expect(response.status).toBe(206)
+      expect(response.headers.get('Content-Range')).toBe(`bytes 1024-${fileSize - 1}/${fileSize}`)
+      expect(response.headers.get('Content-Length')).toBe(String(fileSize - 1024))
+
+      const arrayBuffer = await response.arrayBuffer()
+      expect(arrayBuffer.byteLength).toBe(fileSize - 1024)
+    })
+
+    it('should handle range request for suffix bytes', async () => {
+      const response = await restClient.GET(`/${mediaSlug}/file/${uploadedFilename}`, {
+        headers: { Range: 'bytes=-512' },
+      })
+
+      expect(response.status).toBe(206)
+      expect(response.headers.get('Content-Range')).toBe(
+        `bytes ${fileSize - 512}-${fileSize - 1}/${fileSize}`,
+      )
+      expect(response.headers.get('Content-Length')).toBe('512')
+
+      const arrayBuffer = await response.arrayBuffer()
+      expect(arrayBuffer.byteLength).toBe(512)
+    })
+
+    it('should return 416 for invalid range (start > file size)', async () => {
+      const response = await restClient.GET(`/${mediaSlug}/file/${uploadedFilename}`, {
+        headers: { Range: `bytes=${fileSize + 1000}-` },
+      })
+
+      expect(response.status).toBe(416)
+      expect(response.headers.get('Content-Range')).toBe(`bytes */${fileSize}`)
+    })
+
+    it('should handle multi-range requests by returning first range', async () => {
+      const response = await restClient.GET(`/${mediaSlug}/file/${uploadedFilename}`, {
+        headers: { Range: 'bytes=0-1023,2048-3071' },
+      })
+
+      expect(response.status).toBe(206)
+      expect(response.headers.get('Content-Range')).toBe(`bytes 0-1023/${fileSize}`)
+      expect(response.headers.get('Content-Length')).toBe('1024')
+
+      const arrayBuffer = await response.arrayBuffer()
+      expect(arrayBuffer.byteLength).toBe(1024)
+    })
+
+    it('should handle range at end of file', async () => {
+      const lastByte = fileSize - 1
+      const response = await restClient.GET(`/${mediaSlug}/file/${uploadedFilename}`, {
+        headers: { Range: `bytes=${lastByte}-${lastByte}` },
+      })
+
+      expect(response.status).toBe(206)
+      expect(response.headers.get('Content-Range')).toBe(
+        `bytes ${lastByte}-${lastByte}/${fileSize}`,
+      )
+      expect(response.headers.get('Content-Length')).toBe('1')
+
+      const arrayBuffer = await response.arrayBuffer()
+      expect(arrayBuffer.byteLength).toBe(1)
+    })
+  })
 })
 
 async function fileExists(fileName: string): Promise<boolean> {