CORS: Add `Access-Control-Max-Age` Header to All API and Space Endpoints to Reduce Preflight Requests

[viocha]

Description:

Problem Description

Responses from Hugging Face endpoints, including both the main REST APIs and APIs hosted within Spaces, are missing the Access-Control-Max-Age CORS header.

As a result, browsers are forced to send a preflight OPTIONS request before every single API call that requires it (e.g., requests with custom headers like Authorization or non-simple methods/content-types). Since the preflight response cannot be cached by the browser, this leads to unnecessary network round-trips and adds significant latency to every request made from a web application.

Examples

This issue can be observed across the platform. Here are two examples:

1. Hugging Face REST API (e.g., fetching a raw file):
   Any request to this endpoint from a browser with custom headers will trigger a preflight check.

   fetch('https://huggingface.co/datasets/viocha/api-test/raw/main/12.md',{
     headers:{Authorization:'Bearer hf_xxxxxxxxxxxxxxx'}
   })

2. Space Application API:
   A POST request with a Content-Type: application/json header is a classic case that requires a preflight request. This check is repeated for every subsequent call.

   fetch('https://viocha-test-cors.hf.space/api', {
     method: 'POST',
     headers: {
       'Content-Type': 'application/json'
     },
     body: JSON.stringify({ user: 'test-user', action: 'check-cors' })
   })
     .then(response => response.json())
     .then(data => console.log('Data:', data))
     .catch(error => console.error('Error:', error));

Current Headers Example

The API correctly returns other essential CORS headers, but the caching directive is missing:

access-control-allow-headers: authorization
access-control-allow-methods: GET
access-control-allow-origin: http://localhost:8080

Suggestion

To improve performance and reduce redundant network traffic, I strongly recommend adding the Access-Control-Max-Age header to all relevant API responses. This will allow browsers to cache the preflight results for a specified duration.

A reasonable value would be between 1 and 24 hours (e.g., 86400 seconds).

Example of suggested header:

Access-Control-Max-Age: 86400

This simple change would significantly enhance the performance and efficiency of web applications interacting with any Hugging Face API endpoint.

[julien-c]

do you have example URLs you are hitting? and/or a reproducer.

[viocha]

do you have example URLs you are hitting? and/or a reproducer.

I have updated the description.

[viocha]

As illustrated, a preflight check is required for every request.

[coyotte508]

Thanks

Opened a PR internally, though I assume the cache will only work if the same exact endpoint is called (with the same headers?)

[coyotte508]

hi @viocha

the header should be present now:

Making three requests, the first is done + an options, and the two others are just 304s.

Thank you for pushing for these improvements :)

[viocha]

Hi @coyotte508, thanks for the quick fix!

It looks like the Access-Control-Max-Age header was added to the main API but is still missing on hf.space endpoints.

For example, the OPTIONS response from https://viocha-test-cors.hf.space/api doesn't include it:

access-control-allow-credentials: true
access-control-allow-headers: content-type
access-control-allow-methods: POST
access-control-allow-origin: https://example.com

Would it be possible to add it to Spaces as well?

Here is the test Space: https://huggingface.co/spaces/viocha/test-cors

[coyotte508]

@co42 @christophe-rannou It seems that CORS calls do not hit the space at all, they're handled by the Spaces proxy. (or cloudfront?)

If we want that to continue, should we add a Access-Control-Max-Age to the response in the spaces proxy? (or cloudfront?)

cc @Michellehbn @XciD for viz