Serve Standalone Pre-Compressed Files and Provide Helpful Error Page to Clients Lacking Support

[TheDocTrier]

This discussion is spawning from #617 (comment):

SWS could allow you to serve precompressed files only without having any uncompressed ones. [...] Also, I wonder how other mainstream servers manage this. If they.

The two web servers I am currently using are nginx and http-server. They both support being able to serve pre-compressed files without needing to keep the uncompressed copies adjacent. In the case of nginx, the support is explicitly intended as functionality for the gzip_static directive:

With the always value (1.3.6), gzipped file is used in all cases, without checking if the client supports it. It is useful if there are no uncompressed files on the disk anyway or the ngx_http_gunzip_module is used.

In the case of http-server, the support is implied by the documentation for the --gzip flag:

When enabled it will serve ./public/some-file.js.gz in place of ./public/some-file.js when a gzipped version of the file exists and the request accepts gzip encoding.

I recreated minimal examples using both nginx and http-server to observe their behavior when an appropriate Accept-Encoding header is not present versus present. Neither use the 415 (Unsupported Media Type) status code, opting instead for 404 (Not Found). Perhaps consequently, neither provide a corresponding Accept-Encoding header advertising that the resource does in fact exist, but only via a different content encoding. I think the choice to use 404 is ok, but I would prefer 415 and it would be especially helpful if the default 415 error page would indicate to the user the way to resolve the issue, "A web browser or HTTP client which supports Gzip content encoding is required to fetch this resource."

---

Here is using nginx:

$ ls
example.html.gz

$ curl -I localhost/example.html
HTTP/1.1 404 Not Found
Server: nginx
Date: Thu, 18 Jun 2026 11:35:43 GMT
Content-Type: text/html
Content-Length: 146
Connection: keep-alive

$ curl --header "Accept-Encoding: gzip" -I localhost/example.html
HTTP/1.1 200 OK
Server: nginx
Date: Thu, 18 Jun 2026 11:35:46 GMT
Content-Type: text/html
Content-Length: 0
Last-Modified: Thu, 18 Jun 2026 08:22:02 GMT
Connection: keep-alive
ETag: "6a33aaaa-0"
Content-Encoding: gzip
Accept-Ranges: bytes

Note, gzip_static can conflict with the try_files directive which will take precedence and prevent pre-compressed files from being checked for and served. I accidentally learned this since the default configuration of nginx in Debian uses a global try_files directive.

---

Here is using http-server:

$ ls
example.html.gz

$ curl -I localhost:8080/example.html
HTTP/1.1 404 Not Found
accept-ranges: bytes
Date: Thu, 18 Jun 2026 11:36:07 GMT
Connection: keep-alive
Keep-Alive: timeout=5

$ curl --header 'Accept-Encoding: gzip' -I localhost:8080/example.html
HTTP/1.1 200 OK
accept-ranges: bytes
Content-Encoding: gzip
cache-control: no-cache, no-store, must-revalidate
last-modified: Wed, 17 Jun 2026 08:15:19 GMT
etag: W/"4158-93-2026-06-17T08:15:19.583Z"
content-length: 93
content-type: text/html
Date: Thu, 18 Jun 2026 11:36:10 GMT
Connection: keep-alive
Keep-Alive: timeout=5

Edit: fixed GFM-induced line breaks.

[joseluisq]

@TheDocTrier thanks for the insights.

First, I will describe the current SWS behaviour so we can adjust it where necessary or find a solution for the discussion in the thread.

1. The --compression-static is disabled by default so that SWS will serve the uncompressed files, and if Accept-Encoding is provided, then the dynamic compression takes place. (correct behaviour)
2. However, if --compression-static is enabled, then SWS is doing the following at the moment:
   • Files exist:
   • If Accept-Encoding is sent, then SWS looks first for the uncompressed metadata, and then it goes for its precompressed variant.
   • If Accept-Encoding is not sent, then SWS responds with the uncompressed file. Here, I saw an incorrect log trace with preparing pre-compressed file.... This is misleading and has to be fixed, but still, SWS does not try to look for the precompressed, which is fine.
   • Precompressed file does not exist:
   • If Accept-Encoding is sent, then SWS looks first for the uncompressed metadata, then tries to look for the uncompressed. Because this does not exist, SWS will perform dynamic compression.
   • Uncompressed file does not exist:
   • Regardless of whether Accept-Encoding is sent or not, or if the precompressed file exists. SWS will return 404 because the uncompressed file has priority.

As you said, if we want to serve standalone precompressed files directly regardless of their uncompressed simblings being present. We can introduce a new SWS option that could swap the priority to complement what --compression-static already does.

I suggest a new option like --compression-static-priority=false. If true then SWS will check precompressed files directly if the Accept-Encoding is sent.

Let me know your thoughts on this.

---

P.D. In the upcoming v3, I plan to make this much clearer and more flexible by improving the --compression-static using modes instead of using boolean flags:

• --compression-static=off
• --compression-static=fallback
• --compression-static=prefer
• --compression-static=only