Return 503 on maintenance
sparkofyourlife opened this issue · comments
Return HTTP response code 503 instead of 200, if the server is down for maintenance. The returned page does not seem to be in source, but issue is still applicable to this repository.
- Spark
A temporary solution is to check the response headers, assuming you're using the api if you get a 200 and the Content-Type header doesn't start with application/json, the maintenance page is showing
This is what I do for https://status.e621.ws 🤷♂️
In fact, I'd love if something in the headers were able to point out specifically maintenance mode is happening (or if it returned an actual json body), because if it does become a 503 I'll have to scrape the actual html to differentiate between DDoS protection and maintenance mode
Hmm ... good point. From reading up on this I get the impression that DoS (not DDoS) protection should return 429 Too Many Requests and maintenance mode should return 503 Service Unavailable. A server might also want to return 503 if a DDoS attack was successful, but I guess that is not relevant since the service is behind Cloudflare.
DoS (not DDoS)
I don't feel like arguing over semantics is particularly relevant here
I also personally don't think that it should (or really can, I'm not sure cloudflare lets you configure the status code) return a 429 when protections are heightened. A 4XX is a client error, the website having heightened protections and serving up captchas isn't a client error.
A 503 can make sense for both, I think getting a 503 with an html page when protections are heightened is fine as to do the minimum required when it comes to processing requests. If maintenence mode could return a json body, that would be easy enough to distinguish for most traditional api routes.
Per MDN's definition of a 503:
The server is not ready to handle the request. Common causes are a server that is down for maintenance or that is overloaded.
This covers both scenarios.
I don't feel like arguing over semantics is particularly relevant here
I am sorry if it came across as pedantic. That wasn't the intention. I wanted to highlight that my proposal was not relevant in a DDoS scenario — for those I believe that error code 503 would be more relevant.
or if it returned an actual json body
This is a good point. Best-practice is that an API should always return a single format (in this case JSON), or in case of an error a text/plain body with just the error message I can also see as being acceptable. I don't think that returning HTML is optimal in these cases and should be avoided if possible.
A 4XX is a client error
Reading up some more on this, you are correct. 429 was specified in RFC 6585 as "Too Many Requests" which I believe is applicable here. I am not sure that I agree a 100% that that can be classified as a client error, but the logic behind that seems to be that the client made the requests, and that going above the limit can therefore be considered a client error.
A 503 can make sense for both
I am of the opinion that the most specific response code available should be used if possible. As such, I believe that the following would be most correct:
- OK: 200
- DoS / rate-limiting: 429
- DDoS: 503 (if anything at all)
- Maintenance: 503
Whether that is realistic with the current setup or there is a willingness to implement it I don't know.
What do you think about that?
I'm very against the protection returning a 429, the wording of the rfc may allow the definition to include any use of "too many requests", but I think 429 is generally understood to be the result of something the end user did. This also implies that some internal metric is tracking requests and that the requests can't be processed due to that, which is incorrect. If you can manage to solve the captcha, requests will be handled just fine.
Depending on in which part of the stack the maintenance page is implemented I may/may not be able to do something about this.
The person responsible is not available right, but I will ask once they're back.
From the resources that I have been able to find so far, I have come to the conclusion from my last comment. Cloudflare mentions the same thing, but without returning 429 when CAPTCHAs are required. That is what you mentioned and I think that you are right about that. Which HTTP response code do you think would be most appropriate when challenging the user to prove they are human?
With that, I am unsure if we are in agreement? If not, would it them be possible for you to point to a resource or two that indicates otherwise?
The previous maintenance started returning 503 about an hour in. I'll look into returning json when applicable for when it happens next.
Gonna close this since the original issue has been resolved, but feel free to make an extra issue for the json thing.