fileserver: Add status code override

[francislavoie]

After reading a question about the handle_response feature of reverse_proxy, I realized that we didn't have a way of serving an arbitrary file with a status code other than 200. This is an issue in situations where you want to serve a custom error page in routes that are not errors, like the aforementioned handle_response, where you may want to retain the status code returned by the proxy but write a response with content from a file.

This feature is super simple, basically if a status code is configured (can be a status code number, or a placeholder string) then that status will be written out before serving the file - if we write the status code first, then the stdlib won't write its own (only the first HTTP status header wins).

[mholt]

Wouldn't it be better to use the error routes instead? ala https://github.com/caddyserver/caddy/pull/4076/files#diff-08835e4955ebc248e067238c368ac226eb8b44742ee4b04400ddb5f1e550cb47R268-R284

[francislavoie]

Unfortunately I don't think so, because I don't think error routes will let you keep the same error code if you're serving a file with file_server.

But either way, that would be pretty roundabout... reverse_proxy -> handle_response -> error -> handle_errors -> file_server? It would be better to cut out error and handle_errors and leave that to actually be for errors produced by Caddy.

This is still useful in other situations though, e.g. if you want to serve a "maintenance mode" page with a specific status, without emitting error, etc. Forcing users to use error -> handle_errors seems unwise, when they would just want a quick "respond with a file with X status code" based on some matcher decision.

[mholt]

Why did we add the errors directive then if we don't want people to use it? The whole point is to consolidate error handling.

[francislavoie]

I'm saying those are separate but valid usecases. The times where you use error are not necessarily the same as those you'd want to just serve a file with a specific status.

Here's an example of how it would look when paired with handle_response:

example.com {
	reverse_proxy localhost:8080 {
		@fourhundred status 4xx
		handle_response @fourhundred {
			root * /path/to/errors
			rewrite * /{http.reverse_proxy.status_code}.html
			file_server {
				status {http.reverse_proxy.status_code}
			}
		}
	}
}

But if it had to be done with error, it would look like this (way more complicated to reason about):

example.com {
	reverse_proxy localhost:8080 {
		@fourhundred status 4xx
		handle_response @fourhundred {
			error {http.reverse_proxy.status_text} {http.reverse_proxy.status_code}
		}
	}

	handle_errors {
		@fourhundred expression {http.error.status_code} >= 400 && {http.error.status_code} <= 499
		handle @fourhundred {
			root * /path/to/errors
			rewrite * /{http.error.status_code}.html
			file_server
		}
	}
}

And that assumes that file_server will still write the 4xx status in the 2nd example due to being in the error handler chain. I'm not certain that it does, I think it'll write a 200 status anyways.

[francislavoie]

Another example usecase for this https://caddy.community/t/serving-a-single-static-file-that-matches-multiple-paths-with-a-http-status-code-of-410/12072

[mholt]

Alright, I'm convinced this could be useful. Thanks!