Cannot register HEAD request handlers in custom Express middleware

[datakurre]

Describe the bug

Cannot register HEAD request handlers in Volto server with custom Express middleware, because Volto registers dummy HEAD handler for all requests.

const server = express()
  .disable('x-powered-by')
  .head('/*', function (req, res) {
    // Support for HEAD requests. Required by start-test utility in CI.
    res.send('');
  })

https://github.com/plone/volto/blob/98738972975ee6f74c29b05899fd261874a071de/src/server.jsx#L63

To Reproduce

1. Create HEAD handler in custom express middleware with e.g. res.status(404)
2. Try curl path for that middleware handler path
3. Get just 200 because of the Volto dummy handler being registered first
4. Remove the default head-handler
5. Try curl for your path again and get your handler fired and its status code returned

Expected behavior

Be able to register HEAD -handlers in custom express middleware.

[datakurre]

I agree, that this is "minor", "low" and "nice to have". And there's simple workaround with just registering required HEAD handler at GET handler with different path. I just happened to have a use case, where separate HEAD and GET handlers for at the same middleware path made sense.

[tiberiuichim]

I'm +1 for the needed refactor.

[Shreeyansh14]

I would like to work on this issue, could you tell some more information for this?

[djay]

btw, this is further a problem for HEAD requests to pdfs or images as it always returns the content type as html. This screws up some indexers.

[Shreeyansh14]

Hi 👋,

I'm still pretty new to contributing, so please feel free to correct me if I’m missing something — but I wanted to share what I’ve found while looking into this issue.

It looks like the wildcard .head('/*') handler in the server setup is causing all HEAD requests to return a 200 OK response with Content-Type: text/html, even when requesting files like PDFs or images.

This seems to break some indexers or tools that rely on HEAD responses to get accurate metadata (like Content-Type, Content-Length, etc.). For example, a HEAD request to a .pdf currently returns text/html instead of application/pdf.

I understand the handler is there to support CI testing, but it seems to interfere with:

• Custom HEAD routes
• Static asset requests
• Tools expecting correct headers

Would it make sense to:

• Remove or conditionally apply the wildcard .head('/*') only in test environments?
• Or move it after user-defined routes so they take precedence?

Also, just to clarify (since I'm learning): the /* in .head('/*') is acting as a wildcard — meaning it matches all possible paths, like /about, /api/data, or even /images/file.pdf. So it catches everything before any more specific handlers can respond.

I'd really appreciate any guidance on whether this is the right direction or how I can help fix it properly. Thanks in advance, and apologies if I'm overstepping — just trying to learn and contribute!

[davisagli]

@Shreeyansh14 I think you're looking in the right direction. The comment says the HEAD request support is needed by the start-test utility. I suggest some further analysis:

• Check whether start-test is still used in the Volto repository (after all, this issue is a couple years old)
• Check which routes are being checked by the start-check utility. Maybe we can register a more specific route, for example if it only checks the root route.

[Shreeyansh14]

can you refer me some documentation for setting up volto locally?

[stevepiercy]

@Shreeyansh14 please read and follow First-time contributors, especially Things not to do, Contributing to Plone, and Contributing to Volto.