fix: head requests to /api/media/file/:filename return 404 instead of 200 (RFC 9110 §9.3.2)

packages/next/src/exports/routes.ts

@@ -3,6 +3,7 @@ export { GRAPHQL_PLAYGROUND_GET, GRAPHQL_POST } from '../routes/graphql/index.js
 export {
   DELETE as REST_DELETE,
   GET as REST_GET,
+  HEAD as REST_HEAD,
   OPTIONS as REST_OPTIONS,
   PATCH as REST_PATCH,
   POST as REST_POST,

packages/next/src/routes/index.ts

@@ -3,7 +3,9 @@ export { GRAPHQL_PLAYGROUND_GET, GRAPHQL_POST } from './graphql/index.js'
 export {
   DELETE as REST_DELETE,
   GET as REST_GET,
+  HEAD as REST_HEAD,
   OPTIONS as REST_OPTIONS,
   PATCH as REST_PATCH,
   POST as REST_POST,
+  PUT as REST_PUT,
 } from './rest/index.js'

packages/next/src/routes/rest/index.ts

@@ -51,6 +51,8 @@ export const OPTIONS = handlerBuilder
 
 export const GET = handlerBuilder
 
+export const HEAD = handlerBuilder
+
 export const POST = handlerBuilder
 
 export const DELETE = handlerBuilder

packages/payload/src/utilities/handleEndpoints.ts

@@ -216,31 +216,45 @@ export const handleEndpoints = async ({
       )
     }
 
-    // Find the relevant endpoint configuration
-    const endpoint = endpoints?.find((endpoint) => {
-      if (endpoint.method !== req.method?.toLowerCase()) {
-        return false
-      }
+    const reqMethod = req.method?.toLowerCase()
 
-      const pathMatchFn = match(endpoint.path, { decode: decodeURIComponent })
+    const findEndpoint = (targetMethod: string) =>
+      endpoints?.find((endpoint) => {
+        if (endpoint.method !== targetMethod) {
+          return false
+        }
 
-      const matchResult = pathMatchFn(adjustedPathname)
+        const pathMatchFn = match(endpoint.path, { decode: decodeURIComponent })
 
-      if (!matchResult) {
-        return false
-      }
+        const matchResult = pathMatchFn(adjustedPathname)
 
-      req.routeParams = matchResult.params as Record<string, unknown>
+        if (!matchResult) {
+          return false
+        }
 
-      // Inject to routeParams the slug as well so it can be used later
-      if (collection) {
-        req.routeParams.collection = collection.config.slug
-      } else if (globalConfig) {
-        req.routeParams.global = globalConfig.slug
-      }
+        req.routeParams = matchResult.params as Record<string, unknown>
 
-      return true
-    })
+        // Inject to routeParams the slug as well so it can be used later
+        if (collection) {
+          req.routeParams.collection = collection.config.slug
+        } else if (globalConfig) {
+          req.routeParams.global = globalConfig.slug
+        }
+
+        return true
+      })
+
+    // Find the relevant endpoint configuration
+    let endpoint = findEndpoint(reqMethod!)
+
+    // Per RFC 9110 §9.3.2, HEAD must behave identically to GET except that the
+    // server must not send a response body. Fall back to the GET endpoint so that
+    // HEAD /file/:filename returns the same status and headers as GET.
+    let isHeadViaGetFallback = false
+    if (!endpoint && reqMethod === 'head') {
+      endpoint = findEndpoint('get')
+      isHeadViaGetFallback = Boolean(endpoint)
+    }
 
     if (endpoint) {
       handler = endpoint.handler
@@ -267,7 +281,15 @@ export const handleEndpoints = async ({
 
     const response = await handler(req)
 
-    return new Response(response.body, {
+    // For HEAD requests resolved via the GET fallback, cancel the body stream
+    // (e.g. an open fs.ReadStream) so the file handle is released immediately,
+    // then return an empty body — headers and status are preserved as required
+    // by RFC 9110 §9.3.2.
+    if (isHeadViaGetFallback && response.body) {
+      await response.body.cancel()
+    }
+
+    return new Response(isHeadViaGetFallback ? null : response.body, {
       headers: headersWithCors({
         headers: mergeHeaders(req.responseHeaders ?? new Headers(), response.headers),
         req,

test/__helpers/shared/NextRESTClient.ts

@@ -5,6 +5,7 @@ import {
   REST_DELETE as createDELETE,
   REST_GET as createGET,
   GRAPHQL_POST as createGraphqlPOST,
+  REST_HEAD as createHEAD,
   REST_PATCH as createPATCH,
   REST_POST as createPOST,
   REST_PUT as createPUT,
@@ -59,6 +60,11 @@ export class NextRESTClient {
 
   private _GRAPHQL_POST: (request: Request) => Promise<Response>
 
+  private _HEAD: (
+    request: Request,
+    args: { params: Promise<{ slug: string[] }> },
+  ) => Promise<Response>
+
   private _PATCH: (
     request: Request,
     args: { params: Promise<{ slug: string[] }> },
@@ -86,6 +92,7 @@ export class NextRESTClient {
       this.serverURL = config.serverURL
     }
     this._GET = createGET(config)
+    this._HEAD = createHEAD(config)
     this._POST = createPOST(config)
     this._DELETE = createDELETE(config)
     this._PATCH = createPATCH(config)
@@ -165,6 +172,22 @@ export class NextRESTClient {
     return this._GET(request, { params: Promise.resolve({ slug }) })
   }
 
+  async HEAD(
+    path: ValidPath,
+    options: Omit<RequestInit, 'body'> & RequestOptions = {},
+  ): Promise<Response> {
+    const { slug, params, url } = this.generateRequestParts(path)
+    const { query, ...rest } = options || {}
+    const queryParams = generateQueryString(query, params)
+
+    const request = new Request(`${url}${queryParams}`, {
+      ...rest,
+      headers: this.buildHeaders(options),
+      method: 'HEAD',
+    })
+    return this._HEAD(request, { params: Promise.resolve({ slug }) })
+  }
+
   async GRAPHQL_POST(options: RequestInit & RequestOptions): Promise<Response> {
     const { query, ...rest } = options
     const queryParams = generateQueryString(query, {})

test/uploads/int.spec.ts

@@ -715,6 +715,25 @@ describe('Collections - Uploads', () => {
 
         await payload.delete({ collection: mediaSlug, id: mediaDoc.id })
       })
+
+      it('should handle HEAD request for media file returning identical status and content-type', async () => {
+        const filePath = path.resolve(dirname, './image.png')
+        const file = await getFileByPath(filePath)
+        file.name = 'head-test.png'
+
+        const mediaDoc = (await payload.create({
+          collection: mediaSlug,
+          data: {},
+          file,
+        })) as unknown as Media
+
+        const response = await restClient.HEAD(`/${mediaSlug}/file/${mediaDoc.filename}`)
+
+        expect(response.status).toBe(200)
+        expect(response.headers.get('content-type')).toContain('image/png')
+
+        await payload.delete({ collection: mediaSlug, id: mediaDoc.id })
+      })
     })
   })